LLM Adapters and Conversation Protocol Translation

The request, raw chunks, and final message inside one Step all carry the same Turn and Step. Providers never receive the Session object and never decide when another Step begins.LOOP-STEP-STATELOOP-REQUEST-BUILD

Model I/O is an explicit semantic side-effect boundary. If request facts cannot be made durable, the checkpoint listener never invokes the adapter.LLM-CHECKPOINT-BARRIER

One provider string maps to at most one adapter registration. Empty routes, duplicates, or a metadata ID mismatch fail synchronously, and a multi-route registration is all-or-nothing. Effect teardown removes exactly the routes still owned by that registration, while replace() swaps old and new route sets in one synchronous section.LLM-ADAPTER-REGISTRY

prepareCall() captures the registration, resolved config, retry policy, model context, and adapter-default markers. Its frozen handle can dispatch once and rejects caller-side config mutation as INVALID_PREPARED_CALL.LLM-PREPARED-CALL

When a route is replaced after preparation, the old prepared call remains served by the old adapter and old retry policy. A fresh registry lookup sees the new registration.LLM-PREPARED-PIN-TEST

The assembler retains insertion order by block index, tolerates adapters with delta-only protocols, and allows reasoning, text, and multiple tool calls to interleave. The first block-end becomes authoritative; later deltas or another close for that index are ignored.LLM-BLOCK-ASSEMBLER

System becomes the first wire message, user text is joined, and internal user-role tool results expand into standalone role: tool messages. Assistant text and tool calls preserve order, but reasoning_content is replayed only on tool-call turns. Plain-turn reasoning remains in the durable internal message but does not enter later DeepSeek wire history. Images are rejected before any text-flattening path.LLM-DEEPSEEK-SERIALIZE

The translator waits for the literal [DONE] before closing blocks and emitting final usage and finish. Malformed JSON becomes MALFORMED_RESPONSE, missing DONE becomes STREAM_CLOSED, and a normal stop with no content becomes EMPTY_RESPONSE. Because DeepSeek prompt totals include cache hits, the adapter subtracts hits to form disjoint input buckets.LLM-DEEPSEEK-TRANSLATE

For an installed catalog route without a wire-API override, the Harness reuses the original pi-ai Provider and retains its native API implementation and ambient authentication. A manual route or protocol override permits only openai-completions, openai-responses, and anthropic-messages. Bedrock, Vertex, Azure, and OAuth-only paths are not advertised when the current configuration shape cannot express their requirements.LLM-PI-PROVIDER

The plugin starts with no routes. Each configured profile owns model catalogs and overrides, endpoint, credential reference, reasoning mappings, thinking budgets, cache retention, SSE/WebSocket transport, timeouts, headers, and retry policy.LLM-PI-CONFIG

Before the first await, the Pi adapter captures the profile, model collection, and descriptor, then resolves credentials. A configuration update during the active request cannot alter that snapshot; the next call sees the new one.LLM-PI-STREAM

Harness Message content remains authoritative for Pi AI text, reasoning, and tool calls. PiAiReplayState v1 persists only API, source provider/model, response identity, stop reason, and per-block signatures. Restoration validates kind and version, source identity, block count, block types, and metadata.LLM-PI-REPLAY

dsh-llm-replay is a test and snapshot adapter, not production session recovery. It derives one provider call at each assistant/chunk finish, so retries sharing a Turn and Step become multiple script entries. A thrown stream or a hang cannot be recovered from the successful event log alone and requires an explicit sidecar override.LLM-REPLAY-DERIVATION

The while (true) in step() encloses request construction, streaming, and the request-error waterfall. After a failure yields {kind:'retry'}, it directly continues without closing the Step or Turn. The next attempt derives messages and rebuilds the request again while reusing the Step’s prompt assembly.PROMPT-RETRY-BOUNDARYLLM-RETRY-SAME-STEP-TEST

Normal mode defaults to at most two retries for EMPTY_RESPONSE, RATE_LIMIT, SERVER, TIMEOUT, and TRANSPORT. Local delay grows exponentially from 500ms to 10s with 10 percent symmetric jitter. Always mode retries every request failure without a count limit until success, cancellation, or plugin disposal.LLM-RETRY-POLICY

The plugin appends llm/retry with policy key, failure, retry number, and delay before a cancellable wait. It appends llm/retry-started only after the wait and immediately before returning the retry action. A provider Retry-After value is accepted directly only when it does not exceed the cap.LLM-RETRY-EXECUTOR

The real mock-HTTP tests require byte-equivalent request bodies for failed and successful attempts. Failed partial chunks remain in the raw log but outside the surface, and only one assistant message is committed. A clean EOF is STREAM_CLOSED, which the default policy does not retry. Dependencies are not installed here, so this study reviewed but did not run the tests.LLM-RETRY-WIRE-TEST

Provider selection, adapter stream() invocation, iterator construction, and next() failures all become one terminal finish {error|aborted, failure}. The serializable failure snapshot can retain a Harness-owned code, HTTP status, provider delay, and request ID.LLM-FAILURE-BOUNDARY

A usage chunk arrives before the final message, and a successful message carries the same usage again. The projection therefore uses (turn, step) to identify early and final samples for “one call,” subtracting the former before adding the latter to avoid double counting.LLM-TOKEN-USAGE-PROJECTION

This chapter reviewed production source, types, and test source line by line, and labels test conclusions as contracts defined by tests. Dependencies are not installed in the upstream checkout, so this study did not run upstream tests and does not present source-derived inferences as runtime observations.