From 5c82310f47a57f5031e3301042a53a0768a53b30 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 03:58:34 +0800
Subject: [PATCH 01/11] refactor: prune unused llm contract fields

---
 docs/cordis-catalog/services.md               |  2 +-
 .../testing/2026-06-19-acp-snapshot-tests.md  |  2 +-
 ...0-remove-redundant-snapshot-log-goldens.md |  2 +-
 .../error-finish/replay.override.json         |  2 +-
 packages/llm/llm-deepseek/src/adapter.ts      |  8 ++--
 .../llm/llm-deepseek/tests/adapter.spec.ts    |  7 +--
 packages/llm/llm/README.md                    |  2 +-
 packages/llm/llm/src/assembler.ts             |  8 ++--
 packages/llm/llm/src/index.ts                 |  6 +--
 packages/llm/llm/tests/assembler.spec.ts      | 43 ++++++-------------
 packages/llm/llm/tests/service.spec.ts        |  5 ++-
 packages/support/llm-replay/src/index.ts      |  4 +-
 .../llm-replay/tests/llm-replay.spec.ts       | 10 ++---
 13 files changed, 37 insertions(+), 64 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 0aea3f1589..95df09d45e 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -159,7 +159,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:88`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:86`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.sandbox` — `SandboxProvider` (abstract seam)
 
diff --git a/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md b/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md
index b424a253bd..4bfa3660bf 100644
--- a/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md
+++ b/docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md
@@ -30,7 +30,7 @@ The replay seam is the provider-agnostic `llm/stream` waterfall ([packages/llm/l
 
 ```
 { kind: 'chunks', chunks: StreamChunk[] }
-| { kind: 'throw', chunks: StreamChunk[], message: string, code: string, status?: number }
+| { kind: 'throw', chunks: StreamChunk[], message: string, code: string }
 | { kind: 'hang' }
 ```
 
diff --git a/docs/rfc/implemented/testing/2026-06-20-remove-redundant-snapshot-log-goldens.md b/docs/rfc/implemented/testing/2026-06-20-remove-redundant-snapshot-log-goldens.md
index 2a6f8b7ae3..a7c56af2bd 100644
--- a/docs/rfc/implemented/testing/2026-06-20-remove-redundant-snapshot-log-goldens.md
+++ b/docs/rfc/implemented/testing/2026-06-20-remove-redundant-snapshot-log-goldens.md
@@ -6,7 +6,7 @@ Status: implemented
 
 Model-driving ACP snapshot scenarios ship both `session.jsonl` and `session.golden.jsonl`. For normal recorded scenarios, `session.jsonl` is the replay fixture harvested from a real run, and the replay test normalizes the newly persisted log and compares it to `session.golden.jsonl`. In the current fixtures, the normalized recorded log and normalized golden are identical for the ordinary recorded scenarios.
 
-Authored override scenarios (`error-finish`, `cancel`) currently use `replay.override.json` to drive model behavior and keep `session.jsonl` as a minimal dummy fixture, while `session.golden.jsonl` holds the expected persisted log. The override file is a JSON array of `ReplayEntry` objects: `{ "kind": "chunks", "chunks": StreamChunk[] }`, `{ "kind": "throw", "chunks": StreamChunk[], "message": string, "code": string, "status"?: number }`, or `{ "kind": "hang" }`. That split is also unnecessary: when an override sidecar exists, `llm-replay` replaces the derived script and does not need `session.jsonl` for model chunks, so `session.jsonl` can still be the expected session-log artifact for the scenario.
+Authored override scenarios (`error-finish`, `cancel`) currently use `replay.override.json` to drive model behavior and keep `session.jsonl` as a minimal dummy fixture, while `session.golden.jsonl` holds the expected persisted log. The override file is a JSON array of `ReplayEntry` objects: `{ "kind": "chunks", "chunks": StreamChunk[] }`, `{ "kind": "throw", "chunks": StreamChunk[], "message": string, "code": string }`, or `{ "kind": "hang" }`. That split is also unnecessary: when an override sidecar exists, `llm-replay` replaces the derived script and does not need `session.jsonl` for model chunks, so `session.jsonl` can still be the expected session-log artifact for the scenario.
 
 ## Decision
 
diff --git a/examples/acp-agent/tests/snapshots/error-finish/replay.override.json b/examples/acp-agent/tests/snapshots/error-finish/replay.override.json
index eea32f25ca..cfa0d84227 100644
--- a/examples/acp-agent/tests/snapshots/error-finish/replay.override.json
+++ b/examples/acp-agent/tests/snapshots/error-finish/replay.override.json
@@ -1,3 +1,3 @@
 [
-  { "kind": "throw", "chunks": [], "message": "simulated provider error (HTTP 401)", "code": "AUTH", "status": 401 }
+  { "kind": "throw", "chunks": [], "message": "simulated provider error (HTTP 401)", "code": "AUTH" }
 ]
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index e0627c5695..c90404720b 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -79,9 +79,9 @@ export class DeepSeekAdapter extends LlmAdapter {
         const parsed = await response.json() as WireError
         if (parsed.error?.message) message = parsed.error.message
       } catch {
-        // Paranoid by design: `code` and the HTTP status are ALREADY captured
-        // above (and passed to LlmError below), so the only thing this `try`
-        // can add is a richer provider-supplied message. A malformed, empty,
+        // Paranoid by design: the stable `code` and status-line message are
+        // already captured above, so the only thing this `try` can add is a
+        // richer provider-supplied message. A malformed, empty,
         // or non-JSON error body is a normal thing for gateways/proxies to
         // return on a 5xx/429 — swallowing the parse failure keeps the usable
         // status-line message instead of letting a JSON.parse throw mask the
@@ -89,7 +89,7 @@ export class DeepSeekAdapter extends LlmAdapter {
         // is the sole statement, and any non-parse failure (e.g. body already
         // consumed) is equally non-actionable here.
       }
-      throw new LlmError(message, code, response.status)
+      throw new LlmError(message, code)
     }
     if (!response.body) {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 46f123a1c7..1f1aef3f05 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -158,7 +158,7 @@ describe('DeepSeekAdapter against a mock server', () => {
       status,
       body: JSON.stringify({ error: { message: `failed with ${status}`, type: 't', code: 'c' } }),
     }
-    const server = await mockServer([behavior, behavior, behavior])
+    const server = await mockServer([behavior, behavior])
     const ctx = await harness(server.url)
     await expect(assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] }))
       .rejects.toThrow(`failed with ${status}`)
@@ -166,11 +166,6 @@ describe('DeepSeekAdapter against a mock server', () => {
       assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
         .catch((error: unknown) => (error as LlmError).code),
     ).resolves.toBe(code)
-    // The numeric HTTP status is carried on the error for explicit handling.
-    await expect(
-      assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-        .catch((error: unknown) => (error as LlmError).status),
-    ).resolves.toBe(status)
   })
 
   it('keeps the status-line message for JSON error bodies without a message', async () => {
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 42694ba5ea..7c847447b8 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -42,7 +42,7 @@ Every product adapter must identify the application on every provider HTTP reque
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
-- `LlmError` — extends `HarnessError`; `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) plus an optional numeric `status` when the failure came from a non-2xx provider response.
+- `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract.
 
 ### Real adapters
 
diff --git a/packages/llm/llm/src/assembler.ts b/packages/llm/llm/src/assembler.ts
index 1b8ba6e60c..fb34afe0b9 100644
--- a/packages/llm/llm/src/assembler.ts
+++ b/packages/llm/llm/src/assembler.ts
@@ -38,12 +38,10 @@ export class BlockAssembler {
   private _finish: FinishReason | undefined
 
   /**
-   * Feed one chunk. Returns the completed block when the chunk closes one
-   * (an explicit `block-end`), otherwise undefined.
+   * Feed one chunk into the assembly state.
    * @param chunk - the next raw chunk, in stream order.
-   * @returns the authoritative block from the first `block-end` at its index; undefined for every other chunk.
    */
-  push(chunk: StreamChunk): ContentBlock | undefined {
+  push(chunk: StreamChunk): void {
     switch (chunk.type) {
       case 'block-start': {
         if (!this.partials.has(chunk.index)) {
@@ -79,7 +77,7 @@ export class BlockAssembler {
         // re-close could rewrite a block already flushed downstream.
         if (partial.block) return
         partial.block = chunk.block
-        return chunk.block
+        return
       }
       case 'usage': {
         this._usage = chunk.usage
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 667e9bca78..e32894efdd 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -42,12 +42,10 @@ declare module 'cordis' {
 
 /**
  * Typed error for LLM-related failures. Extends {@link HarnessError}, so the
- * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy;
- * `status` carries the HTTP status when the error originated from a non-2xx
- * provider response (absent for protocol/usage errors that have no HTTP status).
+ * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy.
  */
 export class LlmError extends HarnessError {
-  constructor(message: string, code: string, public status?: number, options?: ErrorOptions) {
+  constructor(message: string, code: string, options?: ErrorOptions) {
     super(message, code, options)
     this.name = 'LlmError'
   }
diff --git a/packages/llm/llm/tests/assembler.spec.ts b/packages/llm/llm/tests/assembler.spec.ts
index d9a4fe33f3..0674c55fb8 100644
--- a/packages/llm/llm/tests/assembler.spec.ts
+++ b/packages/llm/llm/tests/assembler.spec.ts
@@ -29,12 +29,12 @@ describe('BlockAssembler', () => {
     expect(assembler.message().role).toBe('assistant')
   })
 
-  it('returns the completed block from push() on block-end', () => {
+  it('records the completed block from block-end', () => {
     const assembler = new BlockAssembler()
-    expect(assembler.push({ type: 'block-start', index: 0, blockType: 'text' })).toBeUndefined()
-    expect(assembler.push({ type: 'text-delta', index: 0, text: 'hi' })).toBeUndefined()
-    const block = assembler.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } })
-    expect(block).toEqual({ type: 'text', text: 'hi' })
+    assembler.push({ type: 'block-start', index: 0, blockType: 'text' })
+    assembler.push({ type: 'text-delta', index: 0, text: 'hi' })
+    assembler.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } })
+    expect(assembler.blocks()).toEqual([{ type: 'text', text: 'hi' }])
   })
 
   it('tolerates deltas without explicit block-start/end', () => {
@@ -57,8 +57,8 @@ describe('BlockAssembler', () => {
     // push a delta first to guarantee the partial exists
     assembler.push({ type: 'text-delta', index: 0, text: 'hi' })
     // block-end's ensure() must find the existing partial (the second branch path)
-    const block = assembler.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } })
-    expect(block).toEqual({ type: 'text', text: 'hi' })
+    assembler.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } })
+    expect(assembler.blocks()).toEqual([{ type: 'text', text: 'hi' }])
   })
 
   it('throws from assemble() when a partial has an unhandled blockType', () => {
@@ -130,7 +130,7 @@ describe('assertNever', () => {
 
   it('BlockAssembler.push rejects chunks outside the closed StreamChunk union', () => {
     const assembler = new BlockAssembler()
-    expect(() => assembler.push({ type: 'rogue-chunk' } as unknown as StreamChunk))
+    expect(() => { assembler.push({ type: 'rogue-chunk' } as unknown as StreamChunk) })
       .toThrow('unreachable variant in BlockAssembler.push')
   })
 })
@@ -140,32 +140,13 @@ describe('BlockAssembler regressions (property-test findings)', () => {
     // Found by fast-check (the property-testing RFC): two block-ends at the same index made the
     // streamed prefix (first block) disagree with final blocks() (second
     // block). The first close must win — same straggler rule as post-close
-    // deltas — so the prefix returned incrementally by push() and the final
-    // blocks() stay identical.
+    // deltas — so later chunks cannot rewrite the completed block.
     const chunks: StreamChunk[] = [
       { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'first' } },
       { type: 'block-end', index: 0, block: { type: 'text', text: 'second' } },
     ]
-    const streaming = new BlockAssembler()
-    const closed = []
-    for (const chunk of chunks) {
-      const block = streaming.push(chunk)
-      if (block) closed.push(block)
-    }
-
-    const oneShot = new BlockAssembler()
-    for (const chunk of chunks) oneShot.push(chunk)
-
-    expect(closed).toEqual([{ type: 'reasoning', text: 'first' }])
-    expect(oneShot.blocks()).toEqual([{ type: 'reasoning', text: 'first' }])
-    expect(closed).toEqual(oneShot.blocks())
-  })
-
-  it('push returns undefined for a duplicate block-end (it closed nothing)', () => {
-    const a = new BlockAssembler()
-    expect(a.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'x' } }))
-      .toEqual({ type: 'text', text: 'x' })
-    expect(a.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'y' } }))
-      .toBeUndefined()
+    const assembler = new BlockAssembler()
+    for (const chunk of chunks) assembler.push(chunk)
+    expect(assembler.blocks()).toEqual([{ type: 'reasoning', text: 'first' }])
   })
 })
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index f669069c44..125a810261 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -79,11 +79,12 @@ describe('LlmService', () => {
 
   it('LlmError extends the shared HarnessError base', async () => {
     const { HarnessError, isHarnessError } = await import('@deepseek-ai/dsh-llm')
-    const err = new LlmError('boom', 'AUTH', 401)
+    const cause = new Error('root cause')
+    const err = new LlmError('boom', 'AUTH', { cause })
     expect(err).toBeInstanceOf(HarnessError)
     expect(isHarnessError(err)).toBe(true)
     expect(err.code).toBe('AUTH')
-    expect(err.status).toBe(401)
+    expect(err.cause).toBe(cause)
   })
 
   it('HarnessError carries a code, names itself by subclass, and chains cause', async () => {
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index 94bd0cdd7e..b919c21176 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -74,7 +74,7 @@ import { LlmError, assertNever } from '@deepseek-ai/dsh-llm'
  */
 export type ReplayEntry =
   | { kind: 'chunks'; chunks: StreamChunk[] }
-  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string; status?: number }
+  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string }
   | { kind: 'hang' }
 
 /** Resolved plugin configuration. */
@@ -324,7 +324,7 @@ async function* replayEntry(entry: ReplayEntry, signal: AbortSignal | undefined)
         if (signal?.aborted) throw new Error('aborted')
         yield chunk
       }
-      throw new LlmError(entry.message, entry.code, entry.status)
+      throw new LlmError(entry.message, entry.code)
     case 'hang':
       // Replay a stream that stalls until cancelled (mirrors MockAdapter): one
       // chunk, then wait for abort and surface it as the consumer expects.
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index 3b4e8c5fee..f7e85a74bf 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -175,7 +175,7 @@ describe('loadReplayScript', () => {
   it('uses the sidecar override when present, ignoring the JSONL', () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
-    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH', status: 401 }]
+    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH' }]
     writeFileSync(overrideFile, JSON.stringify(override), 'utf8')
     expect(loadReplayScript({ file, overrideFile })).toEqual(override)
   })
@@ -231,12 +231,12 @@ describe('installLlmReplay (through the real waterfall)', () => {
     expect(await drain(ctx.llm.stream({ model: 'm', messages: [] }))).toEqual(second)
   })
 
-  it('replays a sidecar throw-entry as an LlmError with code/status, after its prefix chunks', async () => {
+  it('replays a sidecar throw-entry as an LlmError with its stable code, after its prefix chunks', async () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -245,7 +245,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const seen: StreamChunk[] = []
     await expect((async () => {
       for await (const c of ctx.llm.stream({ model: 'm', messages: [] })) seen.push(c)
-    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH', status: 401 })
+    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH' })
     expect(seen).toEqual(partial)
   })
 
@@ -350,7 +350,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)

From 91075e010ab641a3cc236881d0713f68b27e8191 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 04:03:44 +0800
Subject: [PATCH 02/11] refactor: hide llm adapter helpers

---
 docs/config-catalog.md                           |  4 ++--
 packages/llm/llm-deepseek/README.md              |  2 ++
 packages/llm/llm-deepseek/src/index.ts           |  5 +----
 packages/llm/llm-deepseek/tests/adapter.spec.ts  | 16 +++++++++++++++-
 .../llm/llm-deepseek/tests/serialize.spec.ts     |  2 +-
 packages/llm/llm-deepseek/tests/sse.spec.ts      |  2 +-
 .../llm/llm-deepseek/tests/translate.spec.ts     |  3 ++-
 packages/llm/llm-pi-ai/README.md                 |  2 ++
 packages/llm/llm-pi-ai/src/index.ts              |  3 +--
 packages/llm/llm-pi-ai/tests/adapter.spec.ts     |  9 ++++++++-
 packages/llm/llm-pi-ai/tests/convert.spec.ts     |  2 +-
 11 files changed, 36 insertions(+), 14 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 9d4b8038b5..9db148cbae 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -389,7 +389,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/llm/llm-deepseek/src/index.ts:43`](../packages/llm/llm-deepseek/src/index.ts)
+Source: [`packages/llm/llm-deepseek/src/index.ts:40`](../packages/llm/llm-deepseek/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-pi-ai`
 
@@ -420,7 +420,7 @@ export interface Config {
 export type PiAiReasoning = 'off' | 'high' | 'xhigh'
 ```
 
-Source: [`packages/llm/llm-pi-ai/src/index.ts:37`](../packages/llm/llm-pi-ai/src/index.ts)
+Source: [`packages/llm/llm-pi-ai/src/index.ts:36`](../packages/llm/llm-pi-ai/src/index.ts)
 
 ## `@deepseek-ai/dsh-llm-replay`
 
diff --git a/packages/llm/llm-deepseek/README.md b/packages/llm/llm-deepseek/README.md
index 15fad9f881..4d9ff8fcae 100644
--- a/packages/llm/llm-deepseek/README.md
+++ b/packages/llm/llm-deepseek/README.md
@@ -4,6 +4,8 @@ DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch`
 
 A second, independent implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai` (library-backed). Same Config shape — pick one per context (registering both for the same model names throws by design).
 
+The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire serialization, SSE parsing, and chunk translation helpers are not part of that root contract.
+
 ## Config
 
 ```yaml
diff --git a/packages/llm/llm-deepseek/src/index.ts b/packages/llm/llm-deepseek/src/index.ts
index 3a3d7bb4a1..3b8013de5c 100644
--- a/packages/llm/llm-deepseek/src/index.ts
+++ b/packages/llm/llm-deepseek/src/index.ts
@@ -23,12 +23,9 @@ import z from 'schemastery'
 import type {} from '@deepseek-ai/dsh-llm'
 import { DeepSeekAdapter } from './adapter.ts'
 
-export { DeepSeekAdapter, httpErrorCode } from './adapter.ts'
+export { DeepSeekAdapter } from './adapter.ts'
 export type { DeepSeekAdapterOptions } from './adapter.ts'
-export { serializeMessages, serializeRequest } from './serialize.ts'
 export type { RequestDefaults } from './serialize.ts'
-export { DONE, parseSse } from './sse.ts'
-export { mapFinishReason, mapUsage, translate } from './translate.ts'
 export type * from './types.ts'
 
 export const name = 'llm-deepseek'
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 1f1aef3f05..ca9c6b7097 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -4,7 +4,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { LlmError, userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
-import { DeepSeekAdapter, httpErrorCode } from '@deepseek-ai/dsh-llm-deepseek'
+import { DeepSeekAdapter } from '@deepseek-ai/dsh-llm-deepseek'
+import { httpErrorCode } from '../src/adapter.ts'
 import { assemble } from './assemble.ts'
 
 /** One scripted behavior for the next request the mock server receives. */
@@ -234,6 +235,19 @@ describe('DeepSeekAdapter against a mock server', () => {
 })
 
 describe('plugin registration and config', () => {
+  it('keeps wire helpers off the package root', () => {
+    for (const helper of [
+      'httpErrorCode',
+      'serializeMessages',
+      'serializeRequest',
+      'DONE',
+      'parseSse',
+      'mapFinishReason',
+      'mapUsage',
+      'translate',
+    ]) expect(LlmDeepSeek).not.toHaveProperty(helper)
+  })
+
   it('registers the configured models and unregisters on dispose (HMR safety)', async () => {
     const server = await mockServer([])
     const ctx = new Context()
diff --git a/packages/llm/llm-deepseek/tests/serialize.spec.ts b/packages/llm/llm-deepseek/tests/serialize.spec.ts
index 3e533f8e7c..a1d7d8b4a7 100644
--- a/packages/llm/llm-deepseek/tests/serialize.spec.ts
+++ b/packages/llm/llm-deepseek/tests/serialize.spec.ts
@@ -1,7 +1,7 @@
 import { describe, expect, it } from 'vitest'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, GenerateOptions, Message } from '@deepseek-ai/dsh-llm'
-import { serializeMessages, serializeRequest } from '@deepseek-ai/dsh-llm-deepseek'
+import { serializeMessages, serializeRequest } from '../src/serialize.ts'
 
 function request(overrides: Partial<GenerateOptions> = {}): GenerateOptions {
   return { model: 'deepseek-v4-flash', messages: [], ...overrides }
diff --git a/packages/llm/llm-deepseek/tests/sse.spec.ts b/packages/llm/llm-deepseek/tests/sse.spec.ts
index 2fc297bbec..b18862e4f3 100644
--- a/packages/llm/llm-deepseek/tests/sse.spec.ts
+++ b/packages/llm/llm-deepseek/tests/sse.spec.ts
@@ -1,6 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { LlmError } from '@deepseek-ai/dsh-llm'
-import { DONE, parseSse } from '@deepseek-ai/dsh-llm-deepseek'
+import { DONE, parseSse } from '../src/sse.ts'
 
 /** Build a byte stream from string fragments (fragments = network reads). */
 async function* bytes(...fragments: (string | Uint8Array)[]): AsyncGenerator<Uint8Array> {
diff --git a/packages/llm/llm-deepseek/tests/translate.spec.ts b/packages/llm/llm-deepseek/tests/translate.spec.ts
index d6968faed5..e62cebc4af 100644
--- a/packages/llm/llm-deepseek/tests/translate.spec.ts
+++ b/packages/llm/llm-deepseek/tests/translate.spec.ts
@@ -1,7 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { BlockAssembler, LlmError } from '@deepseek-ai/dsh-llm'
 import type { StreamChunk } from '@deepseek-ai/dsh-llm'
-import { DONE, mapFinishReason, mapUsage, translate } from '@deepseek-ai/dsh-llm-deepseek'
+import { DONE } from '../src/sse.ts'
+import { mapFinishReason, mapUsage, translate } from '../src/translate.ts'
 
 async function* feed(...payloads: (string | object)[]): AsyncGenerator<string> {
   for (const payload of payloads) {
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index f74ccd2246..adb22c585c 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -2,6 +2,8 @@
 
 DeepSeek adapter for the harness LLM seam backed by [`@earendil-works/pi-ai`](https://www.npmjs.com/package/@earendil-works/pi-ai) (the LLM library behind the pi agent).
 
+The package root exposes the Cordis plugin contract and `PiAiAdapter`; model construction and event-conversion helpers are not part of that root contract.
+
 ## Why a second adapter exists
 
 `@deepseek-ai/dsh-llm-deepseek` already talks to the same endpoint. This package is its **design-verification twin**: same models, same wire protocol, completely different internals — a unified LLM library with its own event vocabulary versus hand-rolled fetch/SSE. Anything the harness `StreamChunk` protocol cannot express for BOTH implementations is a core-vocabulary bug. The differences it exercised on purpose:
diff --git a/packages/llm/llm-pi-ai/src/index.ts b/packages/llm/llm-pi-ai/src/index.ts
index 43468ba507..fd81b77b56 100644
--- a/packages/llm/llm-pi-ai/src/index.ts
+++ b/packages/llm/llm-pi-ai/src/index.ts
@@ -22,9 +22,8 @@ import type {} from '@deepseek-ai/dsh-llm'
 import { PiAiAdapter } from './adapter.ts'
 import type { PiAiReasoning } from './adapter.ts'
 
-export { buildModel, PiAiAdapter } from './adapter.ts'
+export { PiAiAdapter } from './adapter.ts'
 export type { PiAiAdapterOptions, PiAiReasoning } from './adapter.ts'
-export { mapStopReason, mapUsage, toPiContext, toStreamChunks } from './convert.ts'
 
 export const name = 'llm-pi-ai'
 export const inject = ['llm']
diff --git a/packages/llm/llm-pi-ai/tests/adapter.spec.ts b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
index cefaa9f745..cc4f129b72 100644
--- a/packages/llm/llm-pi-ai/tests/adapter.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/adapter.spec.ts
@@ -4,7 +4,8 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import LlmService, { CallId, userAgent } from '@deepseek-ai/dsh-llm'
 import * as LlmPiAi from '@deepseek-ai/dsh-llm-pi-ai'
-import { buildModel, PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { PiAiAdapter } from '@deepseek-ai/dsh-llm-pi-ai'
+import { buildModel } from '../src/adapter.ts'
 import { assemble } from './assemble.ts'
 
 /** Scripted SSE responses, one per request (OpenAI chat-completions shape). */
@@ -245,6 +246,12 @@ describe('PiAiAdapter against a mock server', () => {
 })
 
 describe('option spreads and env fallbacks', () => {
+  it('keeps adapter conversion helpers off the package root', () => {
+    for (const helper of ['buildModel', 'mapStopReason', 'mapUsage', 'toPiContext', 'toStreamChunks']) {
+      expect(LlmPiAi).not.toHaveProperty(helper)
+    }
+  })
+
   it('forwards temperature, maxTokens, and signal', async () => {
     const server = await mockServer([{ events: textEvents }])
     const ctx = await harness(server.url)
diff --git a/packages/llm/llm-pi-ai/tests/convert.spec.ts b/packages/llm/llm-pi-ai/tests/convert.spec.ts
index 078d2a4d3b..3dc4709603 100644
--- a/packages/llm/llm-pi-ai/tests/convert.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/convert.spec.ts
@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
 import type { AssistantMessage, AssistantMessageEvent, Usage } from '@earendil-works/pi-ai'
-import { mapStopReason, mapUsage, toPiContext, toStreamChunks } from '@deepseek-ai/dsh-llm-pi-ai'
+import { mapStopReason, mapUsage, toPiContext, toStreamChunks } from '../src/convert.ts'
 
 function usage(input = 0, output = 0, cacheRead = 0, cacheWrite = 0): Usage {
   return {

From f1373cd7abc479ae89a219e6a3fad6023f66aa64 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:15:17 +0800
Subject: [PATCH 03/11] refactor: drop unused tool schema defaults

---
 docs/core-data-structures/tools.md      |  2 --
 packages/core/tools/README.md           |  2 +-
 packages/core/tools/src/schema.ts       | 10 -------
 packages/core/tools/tests/tools.spec.ts | 37 ++-----------------------
 4 files changed, 3 insertions(+), 48 deletions(-)

diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index 36c59aea17..1d59542404 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -57,8 +57,6 @@ interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
-  /** Default value. */
-  default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec
   /** Items schema for type: 'array'. */
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index d57aeba10b..5f06154ec4 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -77,7 +77,7 @@ ctx.tools.register(defineTool({
 
 The helper converts the author-facing `SchemaSpec` (with `required: true` as a per-property boolean) to standard JSON Schema for the wire format and uses the same typed spec for execute/presentation validation. Raw JSON-Schema tool definitions (from MCP servers) are still accepted by the registry directly.
 
-A `defineTool` tool also **validates the model-generated arguments against its `SchemaSpec` before `execute` runs** (`validateArgs`). The model's JSON is untrusted — `InferArgs<S>` is a compile-time claim, not a runtime guarantee — so on a mismatch (missing required key, wrong primitive, bad enum member, nested violation) the tool throws a `ToolArgsError` (`code: 'INVALID_ARGS'`); the registry turns it into an `isError` result whose text lists the violations, which the model sees and self-corrects from. Validation mirrors the JSON Schema conversion exactly: extra keys are allowed, `default` is not applied, and an `object`/`array` prop without `properties`/`items` only type-checks. Raw-registered tools (MCP) are **not** validated by the harness — they validate their own input.
+A `defineTool` tool also **validates the model-generated arguments against its `SchemaSpec` before `execute` runs** (`validateArgs`). The model's JSON is untrusted — `InferArgs<S>` is a compile-time claim, not a runtime guarantee — so on a mismatch (missing required key, wrong primitive, bad enum member, nested violation) the tool throws a `ToolArgsError` (`code: 'INVALID_ARGS'`); the registry turns it into an `isError` result whose text lists the violations, which the model sees and self-corrects from. Validation mirrors the JSON Schema conversion exactly: extra keys are allowed, and an `object`/`array` prop without `properties`/`items` only type-checks. Raw-registered tools (MCP) are **not** validated by the harness — they validate their own input.
 
 See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details.
 
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index d3a2d32e18..ad7c28760e 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -39,15 +39,6 @@ export interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
-  /**
-   * Default value, emitted into the JSON Schema only (validation never applies
-   * it — see the validator note below).
-   *
-   * XXX(unused-default): no tool definition in the repo sets `default`; it rides
-   * into the wire schema for a model that no tool surfaces it to. Drop the field
-   * and its converter line unless a real tool needs a model-visible default.
-   */
-  default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec
   /** Items schema for type: 'array'. */
@@ -123,7 +114,6 @@ function propToJsonSchema(prop: SchemaProp): { schema: Record<string, unknown>;
   const result: Record<string, unknown> = { type: prop.type }
   if (prop.description) result.description = prop.description
   if (prop.enum) result.enum = prop.enum
-  if (prop.default !== undefined) result.default = prop.default
 
   const required = prop.required === true
 
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index a2dff84287..2bca8e05fc 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -904,17 +904,6 @@ describe('schema DSL edge cases', () => {
     })
   })
 
-  it('emits default value in JSON Schema property', () => {
-    const spec = {
-      limit: { type: 'number', default: 25 },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
-    expect(jsonSchema.properties['limit']).toMatchObject({
-      type: 'number',
-      default: 25,
-    })
-  })
-
   it('handles array items without nested properties (plain type array)', () => {
     const spec = {
       tags: { type: 'array', items: { type: 'string' } },
@@ -926,28 +915,12 @@ describe('schema DSL edge cases', () => {
     })
   })
 
-  it('handles enum and default together in one property', () => {
-    const spec = {
-      level: { type: 'string', enum: ['low', 'high'], default: 'low' },
-    } satisfies SchemaSpec
-    const jsonSchema = schemaSpecToJsonSchema(spec)
-    expect(jsonSchema.properties['level']).toMatchObject({
-      type: 'string',
-      enum: ['low', 'high'],
-      default: 'low',
-    })
-  })
-
-  it('omits description, enum, default keys when not specified', () => {
+  it('emits only the type when optional fields are omitted', () => {
     const spec = {
       bare: { type: 'string' },
     } satisfies SchemaSpec
     const jsonSchema = schemaSpecToJsonSchema(spec)
-    const prop = jsonSchema.properties['bare'] as Record<string, unknown>
-    expect(prop).toEqual({ type: 'string' })
-    expect('description' in prop).toBe(false)
-    expect('enum' in prop).toBe(false)
-    expect('default' in prop).toBe(false)
+    expect(jsonSchema.properties['bare']).toEqual({ type: 'string' })
   })
 
   it('handles array with no items (items omitted)', () => {
@@ -1137,12 +1110,6 @@ describe('validateArgs (the runtime-validation RFC, part 1)', () => {
     expect(validateArgs(spec, { path: '/tmp', extra: 1 })).toEqual([])
   })
 
-  it('does not apply defaults (validation only)', () => {
-    const spec = { limit: { type: 'number', default: 25 } } satisfies SchemaSpec
-    // absent optional is valid, and validation does not synthesize the default
-    expect(validateArgs(spec, {})).toEqual([])
-  })
-
   it('type-checks primitives', () => {
     const spec = {
       s: { type: 'string' },

From 863116daaf406d3fc6485be819bcba0fc3d275f1 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:23:17 +0800
Subject: [PATCH 04/11] fix: retain dynamic tool schema defaults

---
 docs/core-data-structures/tools.md            |  2 +
 .../cordis/tool-cordis/tests/mount.spec.ts    |  6 ++-
 packages/core/tools/README.md                 |  2 +-
 packages/core/tools/src/schema.ts             |  6 +++
 packages/core/tools/tests/tools.spec.ts       | 37 ++++++++++++++++++-
 5 files changed, 49 insertions(+), 4 deletions(-)

diff --git a/docs/core-data-structures/tools.md b/docs/core-data-structures/tools.md
index 1d59542404..36c59aea17 100644
--- a/docs/core-data-structures/tools.md
+++ b/docs/core-data-structures/tools.md
@@ -57,6 +57,8 @@ interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
+  /** Default value. */
+  default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec
   /** Items schema for type: 'array'. */
diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts
index fc29eeb2a0..bf2e57c13e 100644
--- a/packages/cordis/tool-cordis/tests/mount.spec.ts
+++ b/packages/cordis/tool-cordis/tests/mount.spec.ts
@@ -185,9 +185,13 @@ describe('cordis_mount', () => {
     // The registered schema is canonical JSON Schema derived from the DSL:
     // the required array survived, integer became number, extra is optional.
     const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')!
-    const parameters = schema.parameters as { properties: Record<string, { type: string; enum?: string[] }>; required?: string[] }
+    const parameters = schema.parameters as {
+      properties: Record<string, { type: string; enum?: string[]; default?: unknown }>
+      required?: string[]
+    }
     expect(parameters.required).toEqual(['text'])
     expect(parameters.properties.count!.type).toBe('number')
+    expect(parameters.properties.count!.default).toBe(1)
     expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow'])
     // Arg validation enforces the normalized spec: text required, extra not.
     expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true)
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 5f06154ec4..d57aeba10b 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -77,7 +77,7 @@ ctx.tools.register(defineTool({
 
 The helper converts the author-facing `SchemaSpec` (with `required: true` as a per-property boolean) to standard JSON Schema for the wire format and uses the same typed spec for execute/presentation validation. Raw JSON-Schema tool definitions (from MCP servers) are still accepted by the registry directly.
 
-A `defineTool` tool also **validates the model-generated arguments against its `SchemaSpec` before `execute` runs** (`validateArgs`). The model's JSON is untrusted — `InferArgs<S>` is a compile-time claim, not a runtime guarantee — so on a mismatch (missing required key, wrong primitive, bad enum member, nested violation) the tool throws a `ToolArgsError` (`code: 'INVALID_ARGS'`); the registry turns it into an `isError` result whose text lists the violations, which the model sees and self-corrects from. Validation mirrors the JSON Schema conversion exactly: extra keys are allowed, and an `object`/`array` prop without `properties`/`items` only type-checks. Raw-registered tools (MCP) are **not** validated by the harness — they validate their own input.
+A `defineTool` tool also **validates the model-generated arguments against its `SchemaSpec` before `execute` runs** (`validateArgs`). The model's JSON is untrusted — `InferArgs<S>` is a compile-time claim, not a runtime guarantee — so on a mismatch (missing required key, wrong primitive, bad enum member, nested violation) the tool throws a `ToolArgsError` (`code: 'INVALID_ARGS'`); the registry turns it into an `isError` result whose text lists the violations, which the model sees and self-corrects from. Validation mirrors the JSON Schema conversion exactly: extra keys are allowed, `default` is not applied, and an `object`/`array` prop without `properties`/`items` only type-checks. Raw-registered tools (MCP) are **not** validated by the harness — they validate their own input.
 
 See `defineTool`, `validateArgs`, `ToolArgsError`, `SchemaSpec`, `InferArgs`, and `schemaSpecToJsonSchema` in the public API for details.
 
diff --git a/packages/core/tools/src/schema.ts b/packages/core/tools/src/schema.ts
index ad7c28760e..e912252b18 100644
--- a/packages/core/tools/src/schema.ts
+++ b/packages/core/tools/src/schema.ts
@@ -39,6 +39,11 @@ export interface SchemaProp {
   description?: string
   /** Enum of allowed values (strings only). */
   enum?: string[]
+  /**
+   * Model-visible JSON Schema default annotation. Validation does not apply it;
+   * dynamic tool mounts may supply it even though first-party definitions do not.
+   */
+  default?: unknown
   /** Nested properties for type: 'object'. */
   properties?: SchemaSpec
   /** Items schema for type: 'array'. */
@@ -114,6 +119,7 @@ function propToJsonSchema(prop: SchemaProp): { schema: Record<string, unknown>;
   const result: Record<string, unknown> = { type: prop.type }
   if (prop.description) result.description = prop.description
   if (prop.enum) result.enum = prop.enum
+  if (prop.default !== undefined) result.default = prop.default
 
   const required = prop.required === true
 
diff --git a/packages/core/tools/tests/tools.spec.ts b/packages/core/tools/tests/tools.spec.ts
index 2bca8e05fc..a2dff84287 100644
--- a/packages/core/tools/tests/tools.spec.ts
+++ b/packages/core/tools/tests/tools.spec.ts
@@ -904,6 +904,17 @@ describe('schema DSL edge cases', () => {
     })
   })
 
+  it('emits default value in JSON Schema property', () => {
+    const spec = {
+      limit: { type: 'number', default: 25 },
+    } satisfies SchemaSpec
+    const jsonSchema = schemaSpecToJsonSchema(spec)
+    expect(jsonSchema.properties['limit']).toMatchObject({
+      type: 'number',
+      default: 25,
+    })
+  })
+
   it('handles array items without nested properties (plain type array)', () => {
     const spec = {
       tags: { type: 'array', items: { type: 'string' } },
@@ -915,12 +926,28 @@ describe('schema DSL edge cases', () => {
     })
   })
 
-  it('emits only the type when optional fields are omitted', () => {
+  it('handles enum and default together in one property', () => {
+    const spec = {
+      level: { type: 'string', enum: ['low', 'high'], default: 'low' },
+    } satisfies SchemaSpec
+    const jsonSchema = schemaSpecToJsonSchema(spec)
+    expect(jsonSchema.properties['level']).toMatchObject({
+      type: 'string',
+      enum: ['low', 'high'],
+      default: 'low',
+    })
+  })
+
+  it('omits description, enum, default keys when not specified', () => {
     const spec = {
       bare: { type: 'string' },
     } satisfies SchemaSpec
     const jsonSchema = schemaSpecToJsonSchema(spec)
-    expect(jsonSchema.properties['bare']).toEqual({ type: 'string' })
+    const prop = jsonSchema.properties['bare'] as Record<string, unknown>
+    expect(prop).toEqual({ type: 'string' })
+    expect('description' in prop).toBe(false)
+    expect('enum' in prop).toBe(false)
+    expect('default' in prop).toBe(false)
   })
 
   it('handles array with no items (items omitted)', () => {
@@ -1110,6 +1137,12 @@ describe('validateArgs (the runtime-validation RFC, part 1)', () => {
     expect(validateArgs(spec, { path: '/tmp', extra: 1 })).toEqual([])
   })
 
+  it('does not apply defaults (validation only)', () => {
+    const spec = { limit: { type: 'number', default: 25 } } satisfies SchemaSpec
+    // absent optional is valid, and validation does not synthesize the default
+    expect(validateArgs(spec, {})).toEqual([])
+  })
+
   it('type-checks primitives', () => {
     const spec = {
       s: { type: 'string' },

From a415d8fdb1b3de4425495b6c87707b58f5c3f65f Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 05:43:10 +0800
Subject: [PATCH 05/11] docs: remove stale streamed-prefix rationale

---
 .../implemented/testing/2026-06-11-property-based-testing.md | 2 +-
 packages/llm/llm/src/assembler.ts                            | 5 ++---
 2 files changed, 3 insertions(+), 4 deletions(-)

diff --git a/docs/rfc/implemented/testing/2026-06-11-property-based-testing.md b/docs/rfc/implemented/testing/2026-06-11-property-based-testing.md
index 67404ab49a..db7a9c8a79 100644
--- a/docs/rfc/implemented/testing/2026-06-11-property-based-testing.md
+++ b/docs/rfc/implemented/testing/2026-06-11-property-based-testing.md
@@ -20,7 +20,7 @@ Adopt `fast-check` (a root devDependency) with one `tests/properties.spec.ts` pe
 ## Consequences
 
 - Generator quality is the value lever — the generators bias toward small index pools and short strings so collisions and interleavings are common.
-- **It already paid off:** the BlockAssembler stream found a real bug — a duplicate `block-end` at the same index overwrote an already-flushed block, so the streamed prefix disagreed with final `blocks()`. Fixed (first close wins, matching the existing straggler rule) with a dedicated regression test.
+- **It already paid off:** the BlockAssembler stream found a real bug — a duplicate `block-end` at the same index rewrote a completed block. Fixed (first close wins, matching the existing straggler rule) with a dedicated regression test.
 - A property flake from a timeout is a finding, not something to retry away. The loop properties are deterministic by construction (settle on `agent/status`), so a hang is a real defect.
 - Property tests supplement, not replace, the example tests that pin specific branches for the 100%-coverage gate.
 
diff --git a/packages/llm/llm/src/assembler.ts b/packages/llm/llm/src/assembler.ts
index fb34afe0b9..1dd023d177 100644
--- a/packages/llm/llm/src/assembler.ts
+++ b/packages/llm/llm/src/assembler.ts
@@ -72,9 +72,8 @@ export class BlockAssembler {
       case 'block-end': {
         const partial = this.ensure(chunk.index, chunk.block.type)
         // First close wins: a second block-end for an already-closed index is
-        // a straggler (same rule as post-close deltas). Ignoring it keeps the
-        // streamed prefix and the final blocks() in agreement — otherwise a
-        // re-close could rewrite a block already flushed downstream.
+        // a straggler (same rule as post-close deltas). Ignoring it prevents a
+        // later chunk from rewriting a completed block.
         if (partial.block) return
         partial.block = chunk.block
         return

From d0df50aa8eee0c98b7eacadcdbc797f7780de565 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Tue, 14 Jul 2026 23:43:53 +0800
Subject: [PATCH 06/11] fix: retain LLM HTTP status metadata

---
 packages/llm/llm-deepseek/src/adapter.ts             |  2 +-
 packages/llm/llm-deepseek/tests/adapter.spec.ts      |  7 ++++++-
 packages/llm/llm/README.md                           |  2 +-
 packages/llm/llm/src/index.ts                        |  6 ++++--
 packages/llm/llm/tests/service.spec.ts               |  5 ++---
 packages/support/llm-replay/src/index.ts             |  4 ++--
 packages/support/llm-replay/tests/llm-replay.spec.ts | 10 +++++-----
 7 files changed, 21 insertions(+), 15 deletions(-)

diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index f6051d1ccd..30760a8fbc 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -76,7 +76,7 @@ export class DeepSeekAdapter extends LlmAdapter {
         // Only swallow error-body parsing: status and code are already captured,
         // so malformed gateway JSON must not mask the actionable HTTP failure.
       }
-      throw new LlmError(message, code)
+      throw new LlmError(message, code, response.status)
     }
     if (!response.body) {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 1f1aef3f05..46f123a1c7 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -158,7 +158,7 @@ describe('DeepSeekAdapter against a mock server', () => {
       status,
       body: JSON.stringify({ error: { message: `failed with ${status}`, type: 't', code: 'c' } }),
     }
-    const server = await mockServer([behavior, behavior])
+    const server = await mockServer([behavior, behavior, behavior])
     const ctx = await harness(server.url)
     await expect(assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] }))
       .rejects.toThrow(`failed with ${status}`)
@@ -166,6 +166,11 @@ describe('DeepSeekAdapter against a mock server', () => {
       assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
         .catch((error: unknown) => (error as LlmError).code),
     ).resolves.toBe(code)
+    // The numeric HTTP status is carried on the error for explicit handling.
+    await expect(
+      assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
+        .catch((error: unknown) => (error as LlmError).status),
+    ).resolves.toBe(status)
   })
 
   it('keeps the status-line message for JSON error bodies without a message', async () => {
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index c8f2002f9f..296fd0c3d3 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -42,7 +42,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
-- `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract.
+- `LlmError` — extends `HarnessError`; `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) plus an optional numeric `status` when the failure came from a non-2xx provider response.
 
 ### Real adapters
 
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 8f2c9b4f39..08f3f54c51 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -42,10 +42,12 @@ declare module 'cordis' {
 
 /**
  * Typed error for LLM-related failures. Extends {@link HarnessError}, so the
- * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy.
+ * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy;
+ * `status` carries the HTTP status when the error originated from a non-2xx
+ * provider response (absent for protocol/usage errors that have no HTTP status).
  */
 export class LlmError extends HarnessError {
-  constructor(message: string, code: string, options?: ErrorOptions) {
+  constructor(message: string, code: string, public status?: number, options?: ErrorOptions) {
     super(message, code, options)
     this.name = 'LlmError'
   }
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index 125a810261..f669069c44 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -79,12 +79,11 @@ describe('LlmService', () => {
 
   it('LlmError extends the shared HarnessError base', async () => {
     const { HarnessError, isHarnessError } = await import('@deepseek-ai/dsh-llm')
-    const cause = new Error('root cause')
-    const err = new LlmError('boom', 'AUTH', { cause })
+    const err = new LlmError('boom', 'AUTH', 401)
     expect(err).toBeInstanceOf(HarnessError)
     expect(isHarnessError(err)).toBe(true)
     expect(err.code).toBe('AUTH')
-    expect(err.cause).toBe(cause)
+    expect(err.status).toBe(401)
   })
 
   it('HarnessError carries a code, names itself by subclass, and chains cause', async () => {
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index b7e4e30a46..2e509973e5 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -20,7 +20,7 @@ import { LlmError, assertNever } from '@deepseek-ai/dsh-llm'
  */
 export type ReplayEntry =
   | { kind: 'chunks'; chunks: StreamChunk[] }
-  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string }
+  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string; status?: number }
   | { kind: 'hang' }
 
 /** Resolved plugin configuration. */
@@ -221,7 +221,7 @@ async function* replayEntry(entry: ReplayEntry, signal: AbortSignal | undefined)
         if (signal?.aborted) throw new Error('aborted')
         yield chunk
       }
-      throw new LlmError(entry.message, entry.code)
+      throw new LlmError(entry.message, entry.code, entry.status)
     case 'hang':
       // Replay a stream that stalls until cancelled (mirrors MockAdapter): one
       // chunk, then wait for abort and surface it as the consumer expects.
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index aa3fea20d5..ac52ec11c9 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -175,7 +175,7 @@ describe('loadReplayScript', () => {
   it('uses the sidecar override when present, ignoring the JSONL', () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
-    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH' }]
+    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH', status: 401 }]
     writeFileSync(overrideFile, JSON.stringify(override), 'utf8')
     expect(loadReplayScript({ file, overrideFile })).toEqual(override)
   })
@@ -231,12 +231,12 @@ describe('installLlmReplay (through the real waterfall)', () => {
     expect(await drain(ctx.llm.stream({ model: 'm', messages: [] }))).toEqual(second)
   })
 
-  it('replays a sidecar throw-entry as an LlmError with its stable code, after its prefix chunks', async () => {
+  it('replays a sidecar throw-entry as an LlmError with code/status, after its prefix chunks', async () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -245,7 +245,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const seen: StreamChunk[] = []
     await expect((async () => {
       for await (const c of ctx.llm.stream({ model: 'm', messages: [] })) seen.push(c)
-    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH' })
+    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH', status: 401 })
     expect(seen).toEqual(partial)
   })
 
@@ -350,7 +350,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)

From 0892831177c895b4139cb61b9c20a32b465fc923 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 00:01:00 +0800
Subject: [PATCH 07/11] docs: refresh LLM service catalog

---
 docs/cordis-catalog/services.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index de6bf20fd1..ca83b3c489 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -127,7 +127,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:75`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 

From ff064917a25fe72af8ba109847fa822220cc4330 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 00:18:04 +0800
Subject: [PATCH 08/11] docs: refresh LLM service catalog

---
 docs/cordis-catalog/services.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index de6bf20fd1..ca83b3c489 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -127,7 +127,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:75`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 

From bb1c8fa27da12f2432afaf3d5c04fd8299df73e9 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Wed, 15 Jul 2026 23:09:14 +0800
Subject: [PATCH 09/11] fix(llm): restore pruned status contract

---
 docs/cordis-catalog/services.md                      |  2 +-
 packages/llm/llm-deepseek/src/adapter.ts             |  6 +++---
 packages/llm/llm-deepseek/tests/adapter.spec.ts      |  7 +------
 packages/llm/llm-pi-ai/README.md                     |  2 +-
 packages/llm/llm/README.md                           |  2 +-
 packages/llm/llm/src/index.ts                        |  6 ++----
 packages/llm/llm/tests/service.spec.ts               |  5 +++--
 packages/support/llm-replay/src/index.ts             |  4 ++--
 packages/support/llm-replay/tests/llm-replay.spec.ts | 10 +++++-----
 9 files changed, 19 insertions(+), 25 deletions(-)

diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 18e00b7904..48fb887d27 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -128,7 +128,7 @@ stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 
 Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
-Source: [`packages/llm/llm/src/index.ts:75`](../../packages/llm/llm/src/index.ts)
+Source: [`packages/llm/llm/src/index.ts:73`](../../packages/llm/llm/src/index.ts)
 
 ## `ctx.permission` — `PermissionService`
 
diff --git a/packages/llm/llm-deepseek/src/adapter.ts b/packages/llm/llm-deepseek/src/adapter.ts
index 30760a8fbc..978dec65c8 100644
--- a/packages/llm/llm-deepseek/src/adapter.ts
+++ b/packages/llm/llm-deepseek/src/adapter.ts
@@ -73,10 +73,10 @@ export class DeepSeekAdapter extends LlmAdapter {
         const parsed = await response.json() as WireError
         if (parsed.error?.message) message = parsed.error.message
       } catch {
-        // Only swallow error-body parsing: status and code are already captured,
-        // so malformed gateway JSON must not mask the actionable HTTP failure.
+        // Only swallow error-body parsing: the stable code and status-line message
+        // are already captured, so malformed gateway JSON must not mask the failure.
       }
-      throw new LlmError(message, code, response.status)
+      throw new LlmError(message, code)
     }
     if (!response.body) {
       throw new LlmError('DeepSeek API returned no response body', 'EMPTY_RESPONSE')
diff --git a/packages/llm/llm-deepseek/tests/adapter.spec.ts b/packages/llm/llm-deepseek/tests/adapter.spec.ts
index 46f123a1c7..1f1aef3f05 100644
--- a/packages/llm/llm-deepseek/tests/adapter.spec.ts
+++ b/packages/llm/llm-deepseek/tests/adapter.spec.ts
@@ -158,7 +158,7 @@ describe('DeepSeekAdapter against a mock server', () => {
       status,
       body: JSON.stringify({ error: { message: `failed with ${status}`, type: 't', code: 'c' } }),
     }
-    const server = await mockServer([behavior, behavior, behavior])
+    const server = await mockServer([behavior, behavior])
     const ctx = await harness(server.url)
     await expect(assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] }))
       .rejects.toThrow(`failed with ${status}`)
@@ -166,11 +166,6 @@ describe('DeepSeekAdapter against a mock server', () => {
       assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
         .catch((error: unknown) => (error as LlmError).code),
     ).resolves.toBe(code)
-    // The numeric HTTP status is carried on the error for explicit handling.
-    await expect(
-      assemble(ctx,{ model: 'deepseek-v4-flash', messages: [] })
-        .catch((error: unknown) => (error as LlmError).status),
-    ).resolves.toBe(status)
   })
 
   it('keeps the status-line message for JSON error bodies without a message', async () => {
diff --git a/packages/llm/llm-pi-ai/README.md b/packages/llm/llm-pi-ai/README.md
index dd1cb5b48c..281a4f13be 100644
--- a/packages/llm/llm-pi-ai/README.md
+++ b/packages/llm/llm-pi-ai/README.md
@@ -55,6 +55,6 @@ Unit suites run against a local `node:http` mock SSE server (pi-ai's openai SDK
 
 - **`tool_choice` is not mapped** — same MVP contract as llm-deepseek.
 - **In-history `system`-role messages fold into `user`-role wire messages** — pi-ai exposes a single `systemPrompt` slot, diverging from the hand-rolled twin's `role: 'system'` passthrough.
-- **`LlmError.status` is never set** — pi-ai reports failures as in-stream events with no HTTP status, so error codes are regex-classified from the error text.
+- **Provider HTTP status is unavailable** — pi-ai reports failures as in-stream events, so stable error codes are regex-classified from the error text.
 - **`buildModel` hardcodes descriptor metadata** — `contextWindow: 128000`, `maxTokens: 64000`, zero cost, identically for every registered model name; not configurable.
 - **pi-ai's built-in retries are disabled (`maxRetries: 0`)** — failures surface immediately; retry policy belongs to `llm/stream` listeners.
diff --git a/packages/llm/llm/README.md b/packages/llm/llm/README.md
index 296fd0c3d3..c8f2002f9f 100644
--- a/packages/llm/llm/README.md
+++ b/packages/llm/llm/README.md
@@ -42,7 +42,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 - `LlmAdapter` — abstract base class for provider adapters. The only required method is `stream()`.
 - `BlockAssembler` — incrementally assembles raw chunks into complete content blocks and an assistant message. The agent loop feeds it raw chunks (logging them for replay) while reading the assembled blocks/message for history.
 - `HarnessError` — base class for the harness error taxonomy: a stable `code` string (distinct from the human `message`) plus `cause` chaining. Lives here, in the leaf package every other imports, so a single base is shared without a new dependency edge. Per-package errors (`LlmError`, `ToolArgsError`, `InvariantError`, …) extend it. `isHarnessError(value)` narrows at seams.
-- `LlmError` — extends `HarnessError`; `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) plus an optional numeric `status` when the failure came from a non-2xx provider response.
+- `LlmError` — extends `HarnessError`; its stable `code` string (`NO_ADAPTER`, `DUPLICATE_ADAPTER`, and adapter codes like `AUTH`/`RATE_LIMIT`) is the programmatic failure contract.
 
 ### Real adapters
 
diff --git a/packages/llm/llm/src/index.ts b/packages/llm/llm/src/index.ts
index 08f3f54c51..8f2c9b4f39 100644
--- a/packages/llm/llm/src/index.ts
+++ b/packages/llm/llm/src/index.ts
@@ -42,12 +42,10 @@ declare module 'cordis' {
 
 /**
  * Typed error for LLM-related failures. Extends {@link HarnessError}, so the
- * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy;
- * `status` carries the HTTP status when the error originated from a non-2xx
- * provider response (absent for protocol/usage errors that have no HTTP status).
+ * `code` string (e.g. `AUTH`, `RATE_LIMIT`, `NO_ADAPTER`) is shared taxonomy.
  */
 export class LlmError extends HarnessError {
-  constructor(message: string, code: string, public status?: number, options?: ErrorOptions) {
+  constructor(message: string, code: string, options?: ErrorOptions) {
     super(message, code, options)
     this.name = 'LlmError'
   }
diff --git a/packages/llm/llm/tests/service.spec.ts b/packages/llm/llm/tests/service.spec.ts
index f669069c44..125a810261 100644
--- a/packages/llm/llm/tests/service.spec.ts
+++ b/packages/llm/llm/tests/service.spec.ts
@@ -79,11 +79,12 @@ describe('LlmService', () => {
 
   it('LlmError extends the shared HarnessError base', async () => {
     const { HarnessError, isHarnessError } = await import('@deepseek-ai/dsh-llm')
-    const err = new LlmError('boom', 'AUTH', 401)
+    const cause = new Error('root cause')
+    const err = new LlmError('boom', 'AUTH', { cause })
     expect(err).toBeInstanceOf(HarnessError)
     expect(isHarnessError(err)).toBe(true)
     expect(err.code).toBe('AUTH')
-    expect(err.status).toBe(401)
+    expect(err.cause).toBe(cause)
   })
 
   it('HarnessError carries a code, names itself by subclass, and chains cause', async () => {
diff --git a/packages/support/llm-replay/src/index.ts b/packages/support/llm-replay/src/index.ts
index 2e509973e5..b7e4e30a46 100644
--- a/packages/support/llm-replay/src/index.ts
+++ b/packages/support/llm-replay/src/index.ts
@@ -20,7 +20,7 @@ import { LlmError, assertNever } from '@deepseek-ai/dsh-llm'
  */
 export type ReplayEntry =
   | { kind: 'chunks'; chunks: StreamChunk[] }
-  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string; status?: number }
+  | { kind: 'throw'; chunks: StreamChunk[]; message: string; code: string }
   | { kind: 'hang' }
 
 /** Resolved plugin configuration. */
@@ -221,7 +221,7 @@ async function* replayEntry(entry: ReplayEntry, signal: AbortSignal | undefined)
         if (signal?.aborted) throw new Error('aborted')
         yield chunk
       }
-      throw new LlmError(entry.message, entry.code, entry.status)
+      throw new LlmError(entry.message, entry.code)
     case 'hang':
       // Replay a stream that stalls until cancelled (mirrors MockAdapter): one
       // chunk, then wait for abort and surface it as the consumer expects.
diff --git a/packages/support/llm-replay/tests/llm-replay.spec.ts b/packages/support/llm-replay/tests/llm-replay.spec.ts
index ac52ec11c9..aa3fea20d5 100644
--- a/packages/support/llm-replay/tests/llm-replay.spec.ts
+++ b/packages/support/llm-replay/tests/llm-replay.spec.ts
@@ -175,7 +175,7 @@ describe('loadReplayScript', () => {
   it('uses the sidecar override when present, ignoring the JSONL', () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
-    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH', status: 401 }]
+    const override: ReplayEntry[] = [{ kind: 'throw', chunks: [], message: '401', code: 'AUTH' }]
     writeFileSync(overrideFile, JSON.stringify(override), 'utf8')
     expect(loadReplayScript({ file, overrideFile })).toEqual(override)
   })
@@ -231,12 +231,12 @@ describe('installLlmReplay (through the real waterfall)', () => {
     expect(await drain(ctx.llm.stream({ model: 'm', messages: [] }))).toEqual(second)
   })
 
-  it('replays a sidecar throw-entry as an LlmError with code/status, after its prefix chunks', async () => {
+  it('replays a sidecar throw-entry as an LlmError with its stable code, after its prefix chunks', async () => {
     writeFileSync(file, sessionJsonl([]), 'utf8')
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)
@@ -245,7 +245,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const seen: StreamChunk[] = []
     await expect((async () => {
       for await (const c of ctx.llm.stream({ model: 'm', messages: [] })) seen.push(c)
-    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH', status: 401 })
+    })()).rejects.toMatchObject({ message: 'unauthorized', code: 'AUTH' })
     expect(seen).toEqual(partial)
   })
 
@@ -350,7 +350,7 @@ describe('installLlmReplay (through the real waterfall)', () => {
     const overrideFile = join(dir, 'replay.override.json')
     const partial: StreamChunk[] = [{ type: 'block-start', index: 0, blockType: 'text' }]
     writeFileSync(overrideFile, JSON.stringify([
-      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH', status: 401 },
+      { kind: 'throw', chunks: partial, message: 'unauthorized', code: 'AUTH' },
     ]), 'utf8')
     const ctx = new Context()
     await ctx.plugin(LlmService)

From 60c4d523d1a868d6766b828a2e5a0771f7c42205 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Thu, 16 Jul 2026 00:59:24 +0800
Subject: [PATCH 10/11] docs(tools): align schema default contract

---
 packages/core/tools/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index 0f7974e0f9..00bbb67ff5 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -142,7 +142,7 @@ The available tools:
 
 - **Native tool calls execute sequentially** — `ToolDefinition` carries no concurrency-safety metadata; adding it (and parallel execution in the loop) waits on the deferred tool-shapes review (`TODO(review)`).
 - **`tools/pre-execute` deliberately cannot rewrite `exec.arguments`** — logged and rendered args would desync from what ran; the rewrite design is [a proposed RFC](../../../docs/rfc/proposed/feature/2026-06-30-pre-tool-input-rewrite.md).
-- **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and never applies `default` (`XXX(unused-default)` flags removing that field); raw-registered JSON-Schema tools validate their own input.
+- **`defineTool`'s schema DSL is a deliberate subset** — string/number/boolean/object/array with string-only `enum`; `validateArgs` tolerates extra keys and preserves `default` as a model-visible JSON Schema annotation without applying it during validation; dynamic Cordis mounts may supply defaults even though first-party definitions do not, while raw-registered JSON-Schema tools validate their own input.
 - **`timeoutMs` on a definition is declarative only** — the registry never enforces deadlines; enforcement requires the `@deepseek-ai/dsh-timeout-policy` wrapper.
 - **Code Mode is TypeScript-only and the presentation mode is service-wide** — `mode: code`/`both` rejects prompt assembly unless `ctx.codeRuntime.language === 'typescript'`; scoped restrictions/shadows still choose each agent's visible bindings, but one tool cannot be native-only while another is code-only.
 - **Code Mode bindings return text only** — non-text content blocks in a sub-call result collapse to `[<type> content]` placeholders.

From 546143048c011b30380fc135efbbde12afc8b465 Mon Sep 17 00:00:00 2001
From: Tianyi Cui <53024+tianyicui@users.noreply.github.com>
Date: Sat, 18 Jul 2026 14:29:29 +0800
Subject: [PATCH 11/11] docs(api): refresh llm reference

---
 website/zh-CN/api/harness/llm.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/website/zh-CN/api/harness/llm.md b/website/zh-CN/api/harness/llm.md
index 200e926d15..a70d5bd478 100644
--- a/website/zh-CN/api/harness/llm.md
+++ b/website/zh-CN/api/harness/llm.md
@@ -6,7 +6,7 @@
 
 The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L96)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L94)
 
 ### ctx.llm.registerAdapter(providers, adapter)
 
@@ -21,7 +21,7 @@ Register an adapter for the given provider routes. Throws `LlmError` with code `
 
 **Returns** the disposer that unregisters all of them.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L111)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L109)
 
 ### ctx.llm.listProviders()
 
@@ -33,7 +33,7 @@ Describe provider routes with a registered adapter.
 
 **Returns** detached provider metadata in registration order.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L142)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L140)
 
 ### ctx.llm.listModels(provider)
 
@@ -47,7 +47,7 @@ Discover models advertised by one registered provider. Catalog membership is adv
 
 **Returns** detached model metadata in adapter-preferred order.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L152)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L150)
 
 ### ctx.llm.stream(options)
 
@@ -61,4 +61,4 @@ Stream one model call as raw chunks (token-level deltas). Throws `LlmError` with
 
 **Returns** the chunk stream, possibly wrapped by `llm/stream` listeners.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L210)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/llm/llm/src/index.ts#L208)