@chatcode/cco-llm-chatcode-config 0.1.0

package/vendor/dsh-llm-pi-ai/src/provider.ts

@@ -0,0 +1,192 @@
+/**
+ * Construction of the pi-ai `Provider` that one configured route registers into
+ * the adapter's `Models` collection.
+ *
+ * Two constructions, one decision: a route the installed catalog ships, whose
+ * profile does not override the wire protocol, **reuses that catalog provider**
+ * with its models replaced — the catalog provider owns API implementations this
+ * package cannot reconstruct (Bedrock loads its Smithy module through a
+ * separate entry point), so rebuilding it from parts would silently narrow
+ * which providers work. Every other route — one pi-ai has never heard of, or a
+ * catalog route pointed at a different protocol — is built by `createProvider`
+ * over the protocol table below.
+ *
+ * Credentials never reach this module's storage: the harness resolves a route's
+ * key through `ctx.credentials` before the request enters pi-ai and hands it
+ * over as a stream option, which `Models` presents to `resolve()` as the
+ * credential key.
+ *
+ * @module dsh-llm-pi-ai/provider
+ */
+
+import { createProvider } from '@earendil-works/pi-ai'
+import type { Api, ApiKeyAuth, Model, Provider, ProviderStreams } from '@earendil-works/pi-ai'
+import { anthropicMessagesApi } from '@earendil-works/pi-ai/api/anthropic-messages.lazy'
+import { openAICompletionsApi } from '@earendil-works/pi-ai/api/openai-completions.lazy'
+import { openAIResponsesApi } from '@earendil-works/pi-ai/api/openai-responses.lazy'
+import { catalogProvider } from './catalog.ts'
+
+/**
+ * Wire protocols a configured route may name, mapped to pi-ai's lazily loaded
+ * implementations. Each entry is the factory that pi-ai's matching provider
+ * factory uses, so a hand-declared route reaches exactly the implementation a
+ * catalog route would.
+ *
+ * The table is deliberately narrow: the protocols a hand-declared route
+ * actually reads, each completely describable with a key, an
+ * endpoint, and headers. Bedrock signs with SigV4 over AWS credentials and a
+ * region, Vertex needs a project, a location, and application-default
+ * credentials, Azure needs provider environment plus an api-version, and Codex
+ * authenticates through OAuth — none of which this configuration shape can
+ * express, so offering them would hand back a provider that cannot
+ * authenticate. The remainder are absent for want of a consumer rather than a
+ * blocker: each is one line here once a deployment needs it. Catalog routes
+ * still reach every protocol through their own provider; only an explicit
+ * override is refused.
+ */
+const PROTOCOLS: Readonly<Record<string, () => ProviderStreams>> = {
+  'openai-completions': openAICompletionsApi,
+  'openai-responses': openAIResponsesApi,
+  'anthropic-messages': anthropicMessagesApi,
+}
+
+/**
+ * Every wire protocol a configured route may name, most-reached first. The
+ * order is the table's and therefore stable; a configuration surface offering
+ * a choice presents the first as its default, which is why the protocol a
+ * hand-declared gateway most often speaks — and the one endpoint interrogation
+ * can read — leads.
+ * @returns the supported protocol identifiers.
+ */
+export function supportedProtocols(): readonly string[] {
+  return Object.keys(PROTOCOLS)
+}
+
+/**
+ * Api-key auth for a route the harness authenticates itself. `Models` calls
+ * this after the adapter has already resolved the route's credential, so a
+ * missing key here is not this layer's failure: a named-but-unresolvable
+ * reference has already failed the request with `MISSING_CREDENTIAL`, and a
+ * route naming no credential at all is deliberately unauthenticated. Reporting
+ * it as configured hands the decision to the protocol, which is where the
+ * requirement actually lives — pi-ai's OpenAI-compatible implementation, for
+ * one, still insists on a key or an `Authorization` header of its own.
+ * @param name - display name used as the resolution's status label.
+ * @returns the api-key auth for a harness-authenticated route.
+ */
+function harnessApiKeyAuth(name: string): ApiKeyAuth {
+  return {
+    name,
+    resolve: ({ credential }) => Promise.resolve({
+      auth: credential?.key === undefined ? {} : { apiKey: credential.key },
+      source: name,
+    }),
+  }
+}
+
+/** The resolved route facts provider construction reads. */
+export interface ProviderSpec {
+  /** Provider route key; also the `Models` collection key and each model's `provider`. */
+  provider: string
+  /** Display name for selectors and status labels. */
+  displayName: string
+  /** Wire protocol override; absent means each model keeps its catalog protocol. */
+  api?: string
+  /** Endpoint override already applied to {@link models}; kept for provider-level display. */
+  baseURL?: string
+  /** The route's materialized models, in configuration order. */
+  models: readonly Model<Api>[]
+  /**
+   * Whether the profile names a credential, which it does through `apiKeyEnv`
+   * alone: configuration carries the reference, never the secret. Only that
+   * decides whether {@link routeAuth} adds the harness's own api-key method to
+   * a catalog provider that offers none; the key itself still arrives per
+   * request, never at construction.
+   */
+  namesCredential: boolean
+}
+
+/**
+ * The auth one route resolves its credential through.
+ *
+ * A catalog route keeps the installed provider's own auth, which is what
+ * preserves provider-native ambient discovery for a profile naming no
+ * credential. That holds even when the profile repoints the protocol: which
+ * environment a provider reads is a property of the provider, not of the wire
+ * format its models speak.
+ *
+ * The single addition covers a catalog provider that offers no api-key method
+ * at all. pi-ai resolves a request's `apiKey` override only when the provider
+ * declares one (`resolveProviderAuth` checks `provider.auth.apiKey` before
+ * honouring the override), so an OAuth-only provider — `openai-codex` is the
+ * one the installed catalog ships — would refuse a profile's explicit key with
+ * `Provider is not configured` before any request went out. Adding the harness
+ * method beside the provider's own restores that route. A keyless profile adds
+ * nothing and still reports the honest refusal, because this adapter resolves
+ * credentials through its own seam and holds no OAuth store to fall back on.
+ * @param spec - the resolved route facts.
+ * @param catalog - the installed catalog provider, when pi-ai ships one.
+ * @returns the auth to construct this route's provider with.
+ */
+function routeAuth(spec: ProviderSpec, catalog: Provider | undefined): Provider['auth'] {
+  if (catalog === undefined) return { apiKey: harnessApiKeyAuth(spec.displayName) }
+  if (catalog.auth.apiKey !== undefined || !spec.namesCredential) return catalog.auth
+  return { ...catalog.auth, apiKey: harnessApiKeyAuth(spec.displayName) }
+}
+
+/**
+ * Reuse an installed catalog provider with this route's models and identity.
+ * Model dispatch stays with the catalog provider, so its API implementations,
+ * compatibility quirks, and ambient credential discovery are preserved exactly.
+ * Catalog-owned dynamic refresh is dropped: this route's catalog is the
+ * settings document, and a background refresh would contradict it.
+ */
+function reuseCatalogProvider(base: Provider, spec: ProviderSpec): Provider {
+  // Provider-level `baseUrl` is display metadata: pi-ai routes every request
+  // through `Model.baseUrl`, which model resolution has already overridden.
+  const baseUrl = spec.baseURL ?? base.baseUrl
+  return {
+    id: spec.provider,
+    name: spec.displayName,
+    ...baseUrl === undefined ? {} : { baseUrl },
+    auth: routeAuth(spec, base),
+    getModels: () => spec.models,
+    // Delegated rather than copied: the catalog provider stays the receiver, so
+    // an implementation holding state on itself keeps working.
+    stream: (model, context, options) => base.stream(model, context, options),
+    streamSimple: (model, context, options) => base.streamSimple(model, context, options),
+  }
+}
+
+/**
+ * Build the pi-ai provider for one resolved route.
+ * @param spec - the resolved route facts.
+ * @returns the provider to register in the adapter's `Models` collection.
+ * @throws Error when the route names a wire protocol this build cannot serve.
+ */
+export function buildProvider(spec: ProviderSpec): Provider {
+  const catalog = catalogProvider(spec.provider)
+  // A catalog route keeping its catalog protocol reuses the catalog provider;
+  // an explicit protocol means the deployment is repointing the route at a
+  // different wire format, which only the protocol table can serve.
+  if (catalog !== undefined && spec.api === undefined) return reuseCatalogProvider(catalog, spec)
+
+  // Every model on this path carries the route's protocol: model resolution
+  // requires one for a route the catalog cannot default, and an explicit one
+  // replaces each catalog model's own. So the route has a single API.
+  const factory = spec.api === undefined ? undefined : PROTOCOLS[spec.api]
+  if (factory === undefined) {
+    throw new Error(
+      `llm-pi-ai: provider "${spec.provider}" names api "${spec.api}", which this build cannot serve;`
+      + ` supported protocols are ${supportedProtocols().join(', ')}`,
+    )
+  }
+  return createProvider({
+    id: spec.provider,
+    name: spec.displayName,
+    ...spec.baseURL === undefined ? {} : { baseUrl: spec.baseURL },
+    auth: routeAuth(spec, catalog),
+    models: spec.models,
+    api: factory(),
+  })
+}

package/vendor/dsh-llm-pi-ai/src/replay.ts

@@ -0,0 +1,249 @@
+/**
+ * Durable pi-ai replay metadata and assistant-history reconstruction.
+ *
+ * ChatCode CLI content remains the durable source for text and tool calls. This
+ * module stores only the provider-native metadata needed to reconstruct a
+ * pi-ai assistant message on a later request.
+ *
+ * @module dsh-llm-pi-ai/replay
+ */
+
+import { LlmError } from '@deepseek-ai/dsh-llm'
+import type { Message, ModelMessageSource, ReplayEnvelope } from '@deepseek-ai/dsh-llm'
+import type { Api, AssistantMessage, Usage as PiUsage } from '@earendil-works/pi-ai'
+
+/** Per-block half of the pi-ai replay envelope, one entry per content block. */
+export type PiAiReplayBlock =
+  | { type: 'text'; textSignature?: string }
+  | { type: 'reasoning'; thinkingSignature?: string; redacted?: boolean }
+  | { type: 'tool-call'; thoughtSignature?: string }
+
+/** Versioned response-level half of the pi-ai replay envelope. */
+export interface PiAiReplayResponse {
+  kind: 'pi-ai'
+  version: 2
+  api: Api
+  provider: string
+  model: string
+  responseModel?: string
+  responseId?: string
+  stopReason: AssistantMessage['stopReason']
+}
+
+/** The validated halves of one pi-ai replay envelope. */
+interface PiAiReplayState {
+  response: PiAiReplayResponse
+  blocks: PiAiReplayBlock[]
+}
+
+/** Parse tool-call argument JSON; tolerate model malformations with {}. */
+function parseArguments(raw: string): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(raw)
+    if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+      return parsed as Record<string, unknown>
+    }
+  } catch {
+    // fall through
+  }
+  return {}
+}
+
+/** Construct the zero usage value required by historical pi-ai messages. */
+function emptyPiUsage(): PiUsage {
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  }
+}
+
+/**
+ * Project a successful pi-ai response into the minimal durable replay state.
+ * The per-block half is index-aligned with the streamed blocks (pi-ai content
+ * order), so `BlockAssembler` prunes an entry with its block whenever assembly
+ * removes one.
+ * @param message - completed native pi-ai assistant response.
+ * @returns the versioned lossless-JSON replay projection.
+ */
+export function toPiReplayState(message: AssistantMessage): ReplayEnvelope {
+  const response: PiAiReplayResponse = {
+    kind: 'pi-ai',
+    version: 2,
+    api: message.api,
+    provider: message.provider,
+    model: message.model,
+    ...message.responseModel === undefined ? {} : { responseModel: message.responseModel },
+    ...message.responseId === undefined ? {} : { responseId: message.responseId },
+    stopReason: message.stopReason,
+  }
+  return {
+    response,
+    blocks: message.content.map((block): PiAiReplayBlock => {
+      switch (block.type) {
+        case 'text': return {
+          type: 'text',
+          ...block.textSignature === undefined ? {} : { textSignature: block.textSignature },
+        }
+        case 'thinking': return {
+          type: 'reasoning',
+          ...block.thinkingSignature === undefined ? {} : { thinkingSignature: block.thinkingSignature },
+          ...block.redacted === undefined ? {} : { redacted: block.redacted },
+        }
+        case 'toolCall': return {
+          type: 'tool-call',
+          ...block.thoughtSignature === undefined ? {} : { thoughtSignature: block.thoughtSignature },
+        }
+      }
+    }),
+  }
+}
+
+function invalidReplay(message: string): never {
+  throw new LlmError(`invalid pi-ai replay state: ${message}`, 'INVALID_REPLAY_STATE')
+}
+
+/** Validate the durable adapter-private envelope before it reaches pi-ai. */
+function readReplayState(value: unknown): PiAiReplayState {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidReplay('expected a replay envelope')
+  const envelope = value as Record<string, unknown>
+  const rawResponse = envelope['response']
+  if (typeof rawResponse !== 'object' || rawResponse === null || Array.isArray(rawResponse)) return invalidReplay('expected a response object')
+  const response = rawResponse as Record<string, unknown>
+  if (response['kind'] !== 'pi-ai') return invalidReplay('unknown state kind')
+  if (response['version'] !== 2) return invalidReplay(`unsupported version ${String(response['version'])}`)
+  for (const key of ['api', 'provider', 'model'] as const) {
+    if (typeof response[key] !== 'string' || response[key].length === 0) return invalidReplay(`${key} must be a non-empty string`)
+  }
+  if (!['stop', 'length', 'toolUse', 'error', 'aborted'].includes(String(response['stopReason']))) {
+    return invalidReplay('unknown stopReason')
+  }
+  if (response['responseModel'] !== undefined && typeof response['responseModel'] !== 'string') return invalidReplay('responseModel must be a string')
+  if (response['responseId'] !== undefined && typeof response['responseId'] !== 'string') return invalidReplay('responseId must be a string')
+  const blocks = envelope['blocks']
+  if (!Array.isArray(blocks)) return invalidReplay('blocks must be an array')
+  for (const [index, value] of blocks.entries()) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) return invalidReplay(`block ${index} must be an object`)
+    const block = value as Record<string, unknown>
+    if (!['text', 'reasoning', 'tool-call'].includes(String(block['type']))) return invalidReplay(`block ${index} has an unknown type`)
+    for (const signature of ['textSignature', 'thinkingSignature', 'thoughtSignature'] as const) {
+      if (block[signature] !== undefined && typeof block[signature] !== 'string') return invalidReplay(`block ${index} ${signature} must be a string`)
+    }
+    if (block['redacted'] !== undefined && typeof block['redacted'] !== 'boolean') return invalidReplay(`block ${index} redacted must be boolean`)
+  }
+  return {
+    response: response as unknown as PiAiReplayResponse,
+    blocks: blocks as PiAiReplayBlock[],
+  }
+}
+
+/** Convert provider-neutral blocks without trusting them as same-model replay. */
+function foreignAssistant(message: Message): AssistantMessage {
+  const source = message.source.kind === 'model' ? message.source : undefined
+  const content: AssistantMessage['content'] = []
+  for (const block of message.content) {
+    switch (block.type) {
+      case 'text': content.push({ type: 'text', text: block.text }); break
+      case 'reasoning': content.push({ type: 'thinking', thinking: block.text }); break
+      case 'tool-call': content.push({
+        type: 'toolCall',
+        id: block.id,
+        name: block.name,
+        arguments: parseArguments(block.arguments),
+      }); break
+      case 'image':
+        throw new LlmError('pi-ai chat history cannot represent structured assistant image output', 'UNSUPPORTED_CONTENT')
+      default:
+        // plugin-added block types are not representable in pi-ai.
+        break
+    }
+  }
+  return {
+    role: 'assistant',
+    content,
+    // Deliberately never equals a catalog API: absent replay state is foreign
+    // even if source names the same provider/model as this request.
+    api: 'dsh-foreign',
+    provider: source?.provider ?? 'dsh-foreign',
+    model: source?.model ?? 'dsh-foreign',
+    usage: emptyPiUsage(),
+    stopReason: content.some(piece => piece.type === 'toolCall') ? 'toolUse' : 'stop',
+    timestamp: 0,
+  }
+}
+
+/** Recombine durable ChatCode CLI content with validated pi-ai replay metadata. */
+function replayedAssistant(message: Message, source: ModelMessageSource, rawState: unknown): AssistantMessage {
+  const state = readReplayState(rawState)
+  if (state.response.provider !== source.provider) return invalidReplay('provider does not match assistant source')
+  if (state.response.model !== source.model) return invalidReplay('model does not match assistant source')
+  if (state.blocks.length !== message.content.length) return invalidReplay('block count does not match assistant content')
+  const content: AssistantMessage['content'] = message.content.map((block, index) => {
+    const replay = state.blocks[index]
+    if (replay === undefined || replay.type !== block.type) return invalidReplay(`block ${index} does not match assistant content`)
+    switch (block.type) {
+      case 'text': return {
+        type: 'text',
+        text: block.text,
+        ...replay.type === 'text' && replay.textSignature !== undefined ? { textSignature: replay.textSignature } : {},
+      }
+      case 'reasoning': return {
+        type: 'thinking',
+        thinking: block.text,
+        ...replay.type === 'reasoning' && replay.thinkingSignature !== undefined ? { thinkingSignature: replay.thinkingSignature } : {},
+        ...replay.type === 'reasoning' && replay.redacted !== undefined ? { redacted: replay.redacted } : {},
+      }
+      case 'tool-call': return {
+        type: 'toolCall',
+        id: block.id,
+        name: block.name,
+        arguments: parseArguments(block.arguments),
+        ...replay.type === 'tool-call' && replay.thoughtSignature !== undefined ? { thoughtSignature: replay.thoughtSignature } : {},
+      }
+      /* v8 ignore next -- readReplayState rejects unknown replay tags, so an equal plugin-added ChatCode CLI tag cannot reach this switch */
+      default: return invalidReplay(`block ${index} has an unsupported ChatCode CLI type`)
+    }
+  })
+  return {
+    role: 'assistant',
+    content,
+    api: state.response.api,
+    provider: state.response.provider,
+    model: state.response.model,
+    ...state.response.responseModel === undefined ? {} : { responseModel: state.response.responseModel },
+    ...state.response.responseId === undefined ? {} : { responseId: state.response.responseId },
+    usage: emptyPiUsage(),
+    stopReason: state.response.stopReason,
+    timestamp: 0,
+  }
+}
+
+/**
+ * Convert one durable ChatCode CLI assistant message into pi-ai history.
+ *
+ * Durable content is the authoritative record; replay metadata only restores
+ * native fidelity (ids, signatures). A replay state this build cannot use —
+ * another adapter's kind, another version, a malformed value, or metadata that
+ * no longer matches the content — therefore degrades the one message to
+ * provider-neutral history instead of failing the request.
+ * @param message - assistant content with required source and optional adapter-owned replay metadata.
+ * @param onDegrade - called with the diagnostic reason when an unusable replay
+ *   state falls back to provider-neutral conversion.
+ * @returns a native pi-ai assistant message reconstructed from durable content.
+ */
+export function toPiAssistant(message: Message, onDegrade?: (reason: string) => void): AssistantMessage {
+  const source = message.source
+  if (source.kind !== 'model' || source.replayState === undefined) return foreignAssistant(message)
+  try {
+    return replayedAssistant(message, source, source.replayState)
+  } catch (error: unknown) {
+    /* v8 ignore next -- replayedAssistant throws only INVALID_REPLAY_STATE LlmErrors; the
+       guard keeps a future non-replay failure loud instead of silently degrading it */
+    if (!(error instanceof LlmError) || error.code !== 'INVALID_REPLAY_STATE') throw error
+    onDegrade?.(error.message)
+    return foreignAssistant(message)
+  }
+}

package/vendor/dsh-llm-pi-ai/src/stream.ts

@@ -0,0 +1,232 @@
+/**
+ * pi-ai assistant event translation into the ChatCode CLI streaming protocol.
+ *
+ * pi-ai tool-call arguments are parsed objects while ChatCode CLI keeps their
+ * raw JSON representation. pi-ai also reports failures as terminal stream
+ * events, which this module maps into ChatCode CLI finish chunks.
+ *
+ * @module dsh-llm-pi-ai/stream
+ */
+
+import { brandString } from '@deepseek-ai/dsh-brand'
+import { CONTEXT_WINDOW_EXCEEDED_CODE, EMPTY_RESPONSE_CODE, isContextWindowExceededError, isQuotaExceededError, LlmError, QUOTA_EXCEEDED_CODE } from '@deepseek-ai/dsh-llm'
+import type { FinishReason, StreamChunk, TokenUsage, ToolCallId } from '@deepseek-ai/dsh-llm'
+import { isContextOverflow } from '@earendil-works/pi-ai'
+import type { AssistantMessage, AssistantMessageEvent, Usage as PiUsage } from '@earendil-works/pi-ai'
+import { toPiReplayState } from './replay.ts'
+
+/**
+ * Map pi-ai usage (reasoning folded into output by pi-ai).
+ * @param usage - cumulative usage from the terminal pi-ai event.
+ * @returns harness counts with pi-ai's exact total; cache fields appear only
+ *   when non-zero (pi-ai reports zeros, not absence).
+ */
+export function mapUsage(usage: PiUsage): TokenUsage {
+  return {
+    inputTokens: usage.input,
+    outputTokens: usage.output,
+    totalTokens: usage.totalTokens,
+    ...usage.cacheRead > 0 ? { cacheReadTokens: usage.cacheRead } : {},
+    ...usage.cacheWrite > 0 ? { cacheWriteTokens: usage.cacheWrite } : {},
+  }
+}
+
+// XXX(pi-ai upstream): pi-ai flattens the caught error to `error.message`
+// (api/anthropic-messages.js: `errorMessage = error instanceof Error ?
+// error.message : JSON.stringify(error)`), discarding the original Error and its
+// `cause` chain before it reaches us. undici carries the actionable transport
+// detail on `cause` (e.g. `SocketError: other side closed`) but hands the fetch
+// wrapper a bare `terminated`, so we are left pattern-matching terse words here.
+// If pi-ai ever forwards the original Error (or a fetch/dispatcher hook that lets
+// us capture the cause ourselves), classify on `code`/`cause` instead of text.
+function classifyPiAiError(message: string): string {
+  if (/\b(?:401|403)\b/.test(message)) return 'AUTH'
+  if (isQuotaExceededError(message)) return QUOTA_EXCEEDED_CODE
+  if (/\b429\b|rate.?limit/i.test(message)) return 'RATE_LIMIT'
+  // A rejected request body (gateway or provider size cap): resending the
+  // same request cannot succeed, so it is invalid, not transient.
+  if (/\b413\b|failed to buffer the request body:\s*length limit exceeded|payload too large|request body too large/i.test(message)) return 'INVALID_REQUEST'
+  if (/\b400\b|invalid.?request/i.test(message)) return 'INVALID_REQUEST'
+  if (/\b5\d\d\b/.test(message)) return 'SERVER'
+  if (/\btime(?:d)?\s*out\b|timeout/i.test(message)) return 'TIMEOUT'
+  // A stream truncated before the provider's terminal event: each pi-ai provider
+  // throws its own wording when the wire closes mid-response without a terminal
+  // event (`… stream ended before message_stop`, `… before a terminal response
+  // event`, `… ended without a terminal event`, `Stream ended without
+  // finish_reason`). The connection dropped mid-response, so this is a transport
+  // truncation, not a model-level error.
+  if (/stream ended (?:before|without)\b/i.test(message)) return 'TRANSPORT'
+  if (/\b(?:network|connection|socket|fetch)\b|\bECONN[A-Z]+\b/i.test(message)
+    || /\b(?:other side closed|HTTP2 request did not get a response|WebSocket closed unexpectedly)\b/i.test(message)
+    // undici renders a mid-stream socket drop as a bare `terminated` (its
+    // `cause` — the real SocketError — was flattened away upstream); Node's
+    // stream layer says `Premature close`.
+    || /\bterminated\b|premature close/i.test(message)) {
+    return 'TRANSPORT'
+  }
+  return 'PI_AI_ERROR'
+}
+
+/**
+ * Map a terminal pi-ai event to the harness finish reason.
+ * @param message - the assistant message carried by the `done` or `error` event.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @returns the mapped harness reason. Recognized error text, `stop` usage above
+ *   `contextWindow`, and zero-output `length` usage that fills the window map
+ *   to `CONTEXT_WINDOW_EXCEEDED`; a `stop` with no content blocks maps to an
+ *   `EMPTY_RESPONSE` error, while terminal `pending` and `deferred` states map
+ *   to non-retryable `PI_AI_ERROR` failures.
+ */
+export function mapStopReason(message: AssistantMessage, contextWindow?: number): FinishReason {
+  const piAiOverflow = isContextOverflow(message, contextWindow)
+  const harnessOverflow = message.stopReason === 'error'
+    && message.errorMessage !== undefined
+    && isContextWindowExceededError(message.errorMessage)
+  if (piAiOverflow || harnessOverflow) {
+    return {
+      kind: 'error',
+      failure: {
+        message: message.errorMessage ?? `pi-ai detected context overflow for model "${message.model}"`,
+        code: CONTEXT_WINDOW_EXCEEDED_CODE,
+      },
+    }
+  }
+
+  switch (message.stopReason) {
+    case 'stop':
+      // A terminal stop that produced no content blocks is a degenerate
+      // provider completion, not a successful (empty) assistant message.
+      if (message.content.length === 0) {
+        return {
+          kind: 'error',
+          failure: {
+            message: `model "${message.model}" returned a completed response with no content`,
+            code: EMPTY_RESPONSE_CODE,
+          },
+        }
+      }
+      return { kind: 'stop' }
+    case 'length': return { kind: 'max-tokens' }
+    case 'toolUse': return { kind: 'tool-calls' }
+    case 'pending': return {
+      kind: 'error',
+      failure: { message: `pi-ai stream for model "${message.model}" ended pending`, code: 'PI_AI_ERROR' },
+    }
+    case 'deferred': return {
+      kind: 'error',
+      failure: { message: `pi-ai deferred response for model "${message.model}" is not supported`, code: 'PI_AI_ERROR' },
+    }
+    case 'aborted': return {
+      kind: 'aborted',
+      failure: { message: message.errorMessage ?? 'pi-ai stream aborted', code: 'ABORTED' },
+    }
+    case 'error': {
+      const text = message.errorMessage ?? 'pi-ai stream error'
+      return { kind: 'error', failure: { message: text, code: classifyPiAiError(text) } }
+    }
+  }
+}
+
+/**
+ * Translate the pi-ai event stream into StreamChunks. pi-ai never throws
+ * mid-stream — failures arrive as `error` events, which become error/aborted
+ * `finish` chunks (the harness protocol's other error-delivery style).
+ * @param events - one assistant turn's pi-ai event stream.
+ * @param contextWindow - resolved catalog capacity for usage-based overflow detection.
+ * @param callerSignal - caller cancellation state; an aborted caller makes any
+ *   in-band terminal error an aborted finish.
+ * @returns the harness chunks, ending with `usage` then `finish`; throws
+ *   `LlmError` (`STREAM_CLOSED`) if the source ends without a terminal event.
+ */
+export async function* toStreamChunks(
+  events: AsyncIterable<AssistantMessageEvent>,
+  contextWindow?: number,
+  callerSignal?: AbortSignal,
+): AsyncGenerator<StreamChunk> {
+  // pi-ai contentIndex ↔ our block index map 1:1 (both count blocks from 0
+  // in stream order), but we track ids per index for tool calls.
+  const toolIds = new Map<number, { id: string; name: string }>()
+
+  for await (const event of events) {
+    switch (event.type) {
+      case 'start':
+        break
+      case 'text_start':
+        yield { type: 'block-start', index: event.contentIndex, blockType: 'text' }
+        break
+      case 'text_delta':
+        yield { type: 'text-delta', index: event.contentIndex, text: event.delta }
+        break
+      case 'text_end':
+        yield { type: 'block-end', index: event.contentIndex, block: { type: 'text', text: event.content } }
+        break
+      case 'thinking_start':
+        yield { type: 'block-start', index: event.contentIndex, blockType: 'reasoning' }
+        break
+      case 'thinking_delta':
+        yield { type: 'reasoning-delta', index: event.contentIndex, text: event.delta }
+        break
+      case 'thinking_end':
+        yield { type: 'block-end', index: event.contentIndex, block: { type: 'reasoning', text: event.content } }
+        break
+      case 'toolcall_start': {
+        // The id/name live on the partial's content at this index.
+        const partial = event.partial.content[event.contentIndex]
+        const id = partial?.type === 'toolCall' ? partial.id : ''
+        const name = partial?.type === 'toolCall' ? partial.name : ''
+        toolIds.set(event.contentIndex, { id, name })
+        yield { type: 'block-start', index: event.contentIndex, blockType: 'tool-call' }
+        break
+      }
+      case 'toolcall_delta': {
+        const known = toolIds.get(event.contentIndex)
+        yield {
+          type: 'tool-call-delta',
+          index: event.contentIndex,
+          id: brandString<ToolCallId>(known?.id ?? ''),
+          ...known?.name !== undefined && known.name.length > 0 ? { name: known.name } : {},
+          argumentsDelta: event.delta,
+        }
+        break
+      }
+      case 'toolcall_end':
+        yield {
+          type: 'block-end',
+          index: event.contentIndex,
+          block: {
+            type: 'tool-call',
+            id: brandString<ToolCallId>(event.toolCall.id),
+            name: event.toolCall.name,
+            // pi-ai hands back the PARSED arguments; the harness vocabulary
+            // keeps the raw string.
+            arguments: JSON.stringify(event.toolCall.arguments),
+          },
+        }
+        break
+      case 'done':
+        yield { type: 'usage', usage: mapUsage(event.message.usage) }
+        yield {
+          type: 'finish',
+          reason: mapStopReason(event.message, contextWindow),
+          replayState: toPiReplayState(event.message),
+        }
+        return
+      case 'error':
+        // In-stream error delivery (pi-ai's style) → error finish chunk
+        // (the harness's other sanctioned error path besides throwing).
+        yield { type: 'usage', usage: mapUsage(event.error.usage) }
+        yield {
+          type: 'finish',
+          reason: mapStopReason(
+            callerSignal?.aborted ? { ...event.error, stopReason: 'aborted' } : event.error,
+            contextWindow,
+          ),
+        }
+        return
+      // no default: AssistantMessageEvent is pi-ai's closed union; a new
+      // event type should fail compilation here via tsc's exhaustiveness
+      // when one is added (switch covers all current variants).
+    }
+  }
+  throw new LlmError('pi-ai event stream ended without done/error', 'STREAM_CLOSED')
+}