LLM Adapter 与会话协议转换

同一 Step 内的 request、raw chunks 和最终 message 都携带相同 turn/step；Provider 不接触 Session 对象，也不决定何时开始下一 Step。LOOP-STEP-STATELOOP-REQUEST-BUILD

模型 I/O 是明确的语义副作用边界：request facts 未成功持久化时，checkpoint listener 不会调用 Adapter。LLM-CHECKPOINT-BARRIER

一个 provider string 同时只能映射到一个 Adapter registration。空 route、重复 route 或 metadata ID 不一致均同步失败；一项多 route 注册是 all-or-nothing。Effect teardown 精确删除自己仍拥有的 route，replace() 在一个同步区段内完成旧集合到新集合的切换。LLM-ADAPTER-REGISTRY

prepareCall() 捕获 registration、resolved config、retry policy、model context 和 adapter-default marker，返回只能 dispatch 一次的 frozen handle；调用者若改动 config，派发以 INVALID_PREPARED_CALL 拒绝。LLM-PREPARED-CALL

Route 在 prepare 后被替换，旧 prepared call 仍由旧 Adapter 和旧 retry policy 服务；新的 registry lookup 才看到新 registration。LLM-PREPARED-PIN-TEST

Assembler 以 block index 维护插入顺序，支持没有 start/end 的 delta-only Adapter，也允许 reasoning、text 与多个 tool call 交错。第一次 block-end 成为权威完整 block；随后同 index 的 delta 或再次 close 被忽略。LLM-BLOCK-ASSEMBLER

System 成为首条 wire message；user text 连接；内部 user-role tool-result 被展开成独立 role: tool。Assistant 的 text 与 tool calls 原序投影，但 reasoning_content 只在 tool-call turn 回传；plain-turn reasoning 仍在 durable internal message 中，却不进入后续 DeepSeek wire history。Image 在任何 text flattening 前显式拒绝。LLM-DEEPSEEK-SERIALIZE

Translator 在收到字面量 [DONE] 时才关闭所有 block、发最后 usage 和 finish。坏 JSON 为 MALFORMED_RESPONSE，无 DONE 为 STREAM_CLOSED，没有任何 content 的正常 stop 为 EMPTY_RESPONSE。DeepSeek 的 prompt total 包含 cache hit，Adapter 会扣除 hit 形成互斥 input bucket。LLM-DEEPSEEK-TRANSLATE

已安装 catalog 的 route 且未覆盖 wire API 时，Harness 复用原 pi-ai Provider，保留其 native API implementation 与 ambient auth。手工 route 或显式 protocol override 只允许 openai-completions、openai-responses、anthropic-messages；Bedrock、Vertex、Azure 与 OAuth-only 路径因当前配置形状无法完整表达而不伪装支持。LLM-PI-PROVIDER

Plugin 默认没有任何 route。每个配置 profile 自己拥有 model catalog/override、endpoint、credential reference、reasoning mapping、thinking budget、cache retention、SSE/WebSocket transport、timeout、header 与 retry policy。LLM-PI-CONFIG

Pi Adapter 在第一次 await 前固定 profile、model collection 和 descriptor，再解析 credential；中途配置更新不会改变已开始请求，下次调用看到新 snapshot。LLM-PI-STREAM

Pi AI 的 text、reasoning 和 tool-call 内容仍以 Harness Message 为权威；PiAiReplayState v1 只持久化 API、source provider/model、response identity、stop reason 与各 block signature。恢复时先验证 kind/version，再验证 source 和每个 block 的数量、类型及 metadata。LLM-PI-REPLAY

dsh-llm-replay 是测试/快照 Adapter，不是生产会话恢复机制。它从 assistant/chunk 的每个 finish 派生一次 provider call；同一 Turn/Step 内的 retry 被切成多条 script entry。Thrown stream 与 hang 无法仅凭成功日志还原，必须提供 sidecar override。LLM-REPLAY-DERIVATION

step() 的 while (true) 包住 build request、stream 与 request-error waterfall。失败得到 {kind:'retry'} 后直接 continue，没有关闭 Step 或 Turn；下一 attempt 重新 derive messages 和 build request，但复用该 Step 的 prompt assembly。PROMPT-RETRY-BOUNDARYLLM-RETRY-SAME-STEP-TEST

Normal mode 默认最多两次 retry，只覆盖 EMPTY_RESPONSE、RATE_LIMIT、SERVER、TIMEOUT、TRANSPORT；本地延迟从 500ms 指数增长至 10s，带 10% 对称 jitter。Always mode 对所有 request failure 无限尝试，直到成功、取消或 plugin disposal。LLM-RETRY-POLICY

Plugin 先 append 包含 policy key、失败、retry number 和 delay 的 llm/retry，再进行可取消等待；等待结束后 append llm/retry-started，才把 retry action 交回 Loop。Provider Retry-After 只有不超过 cap 才直接采用。LLM-RETRY-EXECUTOR

真实 mock HTTP 测试要求失败与成功 attempt 的 body 完全相同；失败 partial chunks 仍在 raw log，但不进入 surface，最终只提交一个 assistant message。干净 EOF 分类为 STREAM_CLOSED，当前默认 policy 不重试它。依赖未安装，本研究只审阅了测试源码。LLM-RETRY-WIRE-TEST

Provider route 选择、Adapter stream() 调用、iterator 构造和 next() 抛错都会变成一个 terminal finish {error|aborted, failure}。Failure 是可序列化快照，可保留 Harness-owned code、HTTP status、provider delay 和 request ID。LLM-FAILURE-BOUNDARY

Usage chunk 会早于最终 message；成功时 message 又携带同一 usage。因此 projection 用 (turn, step) 识别“同一次调用”的早期与最终样本，扣掉旧值再加入新值，避免双计。LLM-TOKEN-USAGE-PROJECTION

本章逐段审阅了生产源码、类型与测试源码，并把测试结论明确标为“测试定义的合同”。仓库没有安装依赖，本研究没有执行上游测试，也没有把 source inference 冒充运行时观察。