Add two DeepSeek LLM adapters: dsh-llm-deepseek and dsh-llm-pi-ai

The first real LlmAdapter implementations, shipped as a deliberate pair:
same models and wire protocol, completely different internals, so the
StreamChunk protocol is verified across independent implementations.

- dsh-llm-deepseek: hand-rolled fetch + SSE parser + chunk-translation
  state machine against the official chat-completions format (thinking
  mode via top-level thinking/reasoning_effort; the empty-string
  reasoning_content first chunk; usage attached to the finish chunk or
  trailing; reasoning_content passback on tool-call turns; disjoint
  cache-token accounting).
- dsh-llm-pi-ai: the same endpoint through @earendil-works/pi-ai,
  mapping its event vocabulary (parsed tool arguments, in-stream error
  events, folded reasoning tokens) onto the same chunks.

The agent loop now honors the in-band error path: an adapter that ends
its stream with finish {kind:error|aborted} (the only option for
adapters that can't throw mid-stream, like pi-ai) is translated into a
step error, so the turn ends error/aborted with a logged error event
instead of a normal completed assistant message. This makes the
StreamChunk error contract real for both adapters; docs/architecture.md
and the StreamChunk doc are updated accordingly.

New yarn test:e2e (vitest.e2e.config.ts, *.e2e.ts) runs key-gated
real-API matrices for both adapters across V4 Flash/Pro and all
thinking/effort levels; it self-skips without DEEPSEEK_API_KEY. Unit
suites run against local node:http mock SSE servers at 100% per-file
coverage.

packages/agent-loop/src/loop.ts

@@ -8,7 +8,7 @@
  */
 
 import type { Context } from 'cordis'
-import type { GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
+import type { FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
 import { BlockAssembler } from '@deepseek-ai/dsh-llm'
 import type { Session, TurnEndReason, TurnTrigger } from '@deepseek-ai/dsh-session'
 import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -23,6 +23,40 @@ function toError(error: unknown): CodedError {
   return error instanceof Error ? error : new Error(String(error))
 }
 
+/**
+ * Map a model-call {@link FinishReason} to the step error it should raise, or
+ * `undefined` when the step completed normally.
+ *
+ * Adapters report provider/transport failures one of two sanctioned ways (see
+ * the StreamChunk contract in dsh-llm): throw from `stream()` (handled by the
+ * caller's try/catch), OR end the stream with a finish-error/aborted chunk
+ * (the only option for adapters that can't throw mid-stream, e.g.
+ * library-backed ones). This translates the latter into a thrown step error
+ * so the turn ends error/aborted with a logged `error` event, never as a
+ * normal `completed` assistant message.
+ *
+ * `FinishReason` is merge-extensible (plugins/adapters can add `kind`s), so
+ * the switch handles the known terminal-failure kinds and treats every other
+ * kind — `stop`, `tool-calls`, `max-tokens`, future additions — as success.
+ */
+function finishError(finish: FinishReason): CodedError | undefined {
+  switch (finish.kind) {
+    case 'error': {
+      const error: CodedError = new Error(finish.message)
+      if (finish.code !== undefined) error.code = finish.code
+      return error
+    }
+    case 'aborted': {
+      const error: CodedError = new Error('model stream aborted')
+      error.code = 'ABORTED'
+      return error
+    }
+    // stop / tool-calls / max-tokens / plugin-added kinds → not a failure.
+    default:
+      return undefined
+  }
+}
+
 /**
  * Build the `{ message, code? }` part of an error payload, omitting the
  * `code` key entirely when absent (exactOptionalPropertyTypes-correct).
@@ -266,6 +300,14 @@ async function runStep(
     assembler.push(chunk)
   }
 
+  // Adapters report provider/transport failures one of two sanctioned ways
+  // (see the StreamChunk contract in dsh-llm): throw from stream() — already
+  // handled by the caller's try/catch — OR end the stream with a
+  // finish-error/aborted chunk. finishError() maps the latter to the step
+  // error to raise (turn ends error/aborted, not a normal completed message).
+  const stepError = finishError(assembler.finish)
+  if (stepError) throw stepError
+
   // The step-result waterfall runs BEFORE the session append so the log (the
   // source of truth for derived history and replay) records the message that
   // tool dispatch actually uses.

packages/agent-loop/tests/review-fixes.spec.ts

@@ -546,3 +546,67 @@ describe('LOW: discriminated SessionEvent narrows without casts', () => {
     }
   })
 })
+
+describe('HIGH: a finish-error stream chunk ends the turn as error, not completed', () => {
+  it('translates finish {kind:error} into a turn error with a logged error event', async () => {
+    // The second sanctioned adapter error path (besides throwing): an
+    // adapter that cannot throw mid-stream ends the stream with a
+    // finish-error chunk (e.g. the pi-ai adapter mapping a provider 401).
+    // The loop must NOT log a normal assistant/message + completed turn.
+    const errorStream: StreamChunk[] = [
+      { type: 'finish', reason: { kind: 'error', message: 'provider 401', code: 'AUTH' } },
+    ]
+    const adapter = new MockAdapter([errorStream])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a-finish-error', { model: 'mock' })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_agent, _turn, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(reasons).toEqual([{ kind: 'error', message: 'provider 401', code: 'AUTH' }])
+
+    const events = [...agent.session.events]
+    expect(events.some(event => event.type === 'error'
+      && event.data.message === 'provider 401' && event.data.code === 'AUTH')).toBe(true)
+    // Crucially: no assistant/message was logged for the failed step.
+    expect(events.some(event => event.type === 'assistant/message')).toBe(false)
+  })
+
+  it('translates finish {kind:aborted} into a turn error coded ABORTED', async () => {
+    const abortedStream: StreamChunk[] = [
+      { type: 'finish', reason: { kind: 'aborted' } },
+    ]
+    const adapter = new MockAdapter([abortedStream])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a-finish-aborted', { model: 'mock' })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_agent, _turn, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(reasons).toEqual([{ kind: 'error', message: 'model stream aborted', code: 'ABORTED' }])
+    expect([...agent.session.events].some(event => event.type === 'assistant/message')).toBe(false)
+  })
+
+  it('handles a finish error without a code (code key omitted)', async () => {
+    const errorStream: StreamChunk[] = [
+      { type: 'finish', reason: { kind: 'error', message: 'codeless failure' } },
+    ]
+    const adapter = new MockAdapter([errorStream])
+    const ctx = await harness(adapter)
+    const agent = ctx.agentLoop.create('a-finish-error-nocode', { model: 'mock' })
+
+    const reasons: TurnEndReason[] = []
+    ctx.on('agent/turn-end', (_agent, _turn, reason) => void reasons.push(reason))
+
+    send(agent, 'go')
+    await waitForIdle(ctx, agent)
+
+    expect(reasons).toEqual([{ kind: 'error', message: 'codeless failure' }])
+  })
+})