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.