Merge remote-tracking branch 'origin/master' into xtr/identified-immutable-messages

# Conflicts:
#	docs/cordis-catalog/events.md
#	docs/core-data-structures/core.i18n.yaml
#	docs/event-producer-consumer.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	packages/core/agent-loop/README.i18n.yaml
#	packages/core/agent/README.i18n.yaml

packages/sdk/sdk-client/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sdk/sdk-client/README.md
-README.md: 33a933e10abfa865cf9ce34b87c377d07081cc68
-README.zh.md: 9f4453a00efef2685acec0194f83fcec2edf1409
+README.md: 3ac4de540401f6f40dab3e84f7005f91d024aee8
+README.zh.md: 1d9f8fbded8b477d519a5244735179fba581cdd0

packages/sdk/sdk-client/README.md

@@ -15,12 +15,13 @@ await using harness = new DeepSeekHarness({
   launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
   provider: 'deepseek',
   model: 'deepseek-v4-flash',
+  maxTokens: 49_152,
 })
 const result = await harness.run('say hi')
 console.log(result.status, result.finalResponse)
 ```
 
-The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). `session(id?)` opens a named or fresh session handle; `run(input, { sessionId?, onNotification? })` sends one prompt turn and settles when the paired `session.finished` arrives, returning a `TurnResult`: `status` (`ok`/`error` as the deployment maps it), the structured `reason` (`TurnEndReason`), `finalResponse` (last assistant message text), root-session `events`, and raw `notifications` for that session plus descendants discovered from `subagent.started`, all in wire order. Model-level failure is a `status: 'error'` result, never a rejection; rejections mean transport loss, timeout, or protocol violation.
+The subprocess starts lazily on first use and stays owned by the instance across `run()` calls; `close()` (or `await using`) is required so the child is always reaped. `start()` memoizes the `initialize` handshake (the workspace cwd — resolved absolute before it crosses the wire — plus the provider/model route and optional positive `maxTokens` output cap); a failed handshake reaps the runtime and swaps in a fresh client, so a later call retries with a new subprocess (until `close()`, which is terminal). The cap applies to each root-agent request and is inherited by in-process descendants; compaction plugins own their separate summary limits. `session(id?)` opens a named or fresh session handle; `run(input, { sessionId?, onNotification? })` sends one prompt turn and settles when the paired `session.finished` arrives, returning a `TurnResult`: `status` (`ok`/`error` as the deployment maps it), the structured `reason` (`TurnEndReason`), `finalResponse` (last assistant message text), root-session `events`, and raw `notifications` for that session plus descendants discovered from `subagent.started`, all in wire order. Model-level failure is a `status: 'error'` result, never a rejection; rejections mean transport loss, timeout, or protocol violation.
 
 ## HarnessClient
 

packages/sdk/sdk-client/README.zh.md

@@ -15,12 +15,13 @@ await using harness = new DeepSeekHarness({
   launch: { command: 'node', args: ['lib/bin.js', 'cordis.yml'] },
   provider: 'deepseek',
   model: 'deepseek-v4-flash',
+  maxTokens: 49_152,
 })
 const result = await harness.run('say hi')
 console.log(result.status, result.finalResponse)
 ```
 
-子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被收割。`start()` 记忆化 `initialize` 握手（工作区 cwd——在跨越线之前解析为绝对路径——加 provider/model 路由）；握手失败会收割运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。`session(id?)` 打开具名或全新的会话句柄；`run(input, { sessionId?, onNotification? })` 发送一个 prompt 回合，在配对的 `session.finished` 到达时尘埃落定，返回 `TurnResult`：`status`（按部署映射的 `ok`/`error`）、结构化 `reason`（`TurnEndReason`）、`finalResponse`（最后一条助手消息文本）、根会话的 `events`，以及该会话和通过 `subagent.started` 发现的后代的原始 `notifications`，均按线序排列。模型层失败是 `status: 'error'` 的结果，绝不是拒绝；拒绝意味着传输丢失、超时或协议违例。
+子进程在首次使用时惰性启动，并在多次 `run()` 之间持续归实例所有；必须 `close()`（或 `await using`），子进程才总能被收割。`start()` 记忆化 `initialize` 握手（工作区 cwd——在跨越线之前解析为绝对路径——加 provider/model 路由和可选的正整数 `maxTokens` 输出上限）；握手失败会收割运行时并换入全新客户端，后续调用用新子进程重试（直到终结性的 `close()`）。该上限作用于根 agent 的每次请求，并由进程内后代继承；压缩插件单独持有摘要上限。`session(id?)` 打开具名或全新的会话句柄；`run(input, { sessionId?, onNotification? })` 发送一个 prompt 回合，在配对的 `session.finished` 到达时尘埃落定，返回 `TurnResult`：`status`（按部署映射的 `ok`/`error`）、结构化 `reason`（`TurnEndReason`）、`finalResponse`（最后一条助手消息文本）、根会话的 `events`，以及该会话和通过 `subagent.started` 发现的后代的原始 `notifications`，均按线序排列。模型层失败是 `status: 'error'` 的结果，绝不是拒绝；拒绝意味着传输丢失、超时或协议违例。
 
 ## HarnessClient
 

packages/sdk/sdk-client/src/api.ts

@@ -25,6 +25,7 @@ export class DeepSeekHarness implements AsyncDisposable {
   private readonly cwd: string
   private readonly provider: string
   private readonly model: string
+  private readonly maxTokens: number | undefined
   private initialized: Promise<void> | undefined
   private closed = false
 
@@ -38,6 +39,7 @@ export class DeepSeekHarness implements AsyncDisposable {
     this.cwd = resolve(options.cwd ?? options.launch.cwd ?? process.cwd())
     this.provider = options.provider ?? 'deepseek'
     this.model = options.model ?? 'deepseek-v4-flash'
+    this.maxTokens = options.maxTokens
   }
 
   /**
@@ -61,7 +63,12 @@ export class DeepSeekHarness implements AsyncDisposable {
     this.initialized ??= (async () => {
       try {
         this.clientInstance.start()
-        await this.clientInstance.initialize({ cwd: this.cwd, provider: this.provider, model: this.model })
+        await this.clientInstance.initialize({
+          cwd: this.cwd,
+          provider: this.provider,
+          model: this.model,
+          ...this.maxTokens === undefined ? {} : { maxTokens: this.maxTokens },
+        })
       } catch (error) {
         this.initialized = undefined
         await this.clientInstance.close()

packages/sdk/sdk-client/src/types.ts

@@ -55,6 +55,8 @@ export interface DeepSeekHarnessOptions {
   provider?: string
   /** Model for SDK-created agents (default `deepseek-v4-flash`). */
   model?: string
+  /** Maximum output tokens for each conversation-model request. */
+  maxTokens?: number
 }
 
 /** The settled outcome of one {@link HarnessSession.run} turn. */

packages/sdk/sdk-client/tests/sdk-client.spec.ts

@@ -106,7 +106,7 @@ describe('DeepSeekHarness', () => {
     await harness.close()
   })
 
-  it('sends the configured cwd/provider/model in the handshake exactly once', async () => {
+  it('sends the configured cwd/provider/model/maxTokens in the handshake exactly once', async () => {
     const dir = await tempDir('sdk-client-init-')
     const recordFile = join(dir, 'init.jsonl')
     const harness = new DeepSeekHarness({
@@ -114,13 +114,19 @@ describe('DeepSeekHarness', () => {
       cwd: dir,
       provider: 'custom-provider',
       model: 'custom-model',
+      maxTokens: 4096,
     })
     cleanups.push(() => harness.close())
     await harness.run('one')
     await harness.run('two')
     await harness.close()
     const records = (await readFile(recordFile, 'utf8')).trim().split('\n').map(line => JSON.parse(line) as object)
-    expect(records).toEqual([{ cwd: dir, provider: 'custom-provider', model: 'custom-model' }])
+    expect(records).toEqual([{
+      cwd: dir,
+      provider: 'custom-provider',
+      model: 'custom-model',
+      maxTokens: 4096,
+    }])
   })
 
   it('resolves a relative launch cwd to an absolute workspace before the handshake', async () => {

packages/sdk/sdk-protocol/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sdk/sdk-protocol/README.md
-README.md: 79e6bc36a656ce0d68c8e01ab2f75e26b4ac8ca5
-README.zh.md: 8322da0f2bf7251f2b958c6a15f1738b9d8c41a4
+README.md: 62b26d4a82d358fa4efcb7ab84036e5f4848057f
+README.zh.md: c08c32b2fbf0b63b28826bae8fd6c2a73bfe09d0

packages/sdk/sdk-protocol/README.md

@@ -22,7 +22,7 @@ The shared wire protocol for the DeepSeek Harness SDK runtime: one newline-delim
 | server→client | `subagent.started` | `SubagentStartedNotification` |
 | server→client | `subagent.finished` | `SubagentFinishedNotification` (in-process runs only) |
 
-`HarnessSdkRequestMap` and `HarnessSdkNotificationMap` index these by method name. The notification payload types depend on `SessionEvent` (`dsh-session`), `ContentBlock` (`dsh-llm`), and `SubagentStopReason` (`dsh-subagent`) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.
+`HarnessSdkRequestMap` and `HarnessSdkNotificationMap` index these by method name. `InitializeParams.maxTokens` is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission leaves the provider default in control. The notification payload types depend on `SessionEvent` (`dsh-session`), `ContentBlock` (`dsh-llm`), and `SubagentStopReason` (`dsh-subagent`) — the protocol streams full session-log envelopes, so the session vocabulary is part of the wire contract. `serverInfo.name` stays the wire-stable `deepseek-harness-sdk-runtime`.
 
 ## Model Experience
 

packages/sdk/sdk-protocol/README.zh.md

@@ -22,7 +22,7 @@ DeepSeek Harness SDK 运行时的共享线协议：一个按换行分帧的 JSON
 | server→client | `subagent.started` | `SubagentStartedNotification` |
 | server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内 run） |
 
-`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇表是线契约的一部分。`serverInfo.name` 保持线上稳定值 `deepseek-harness-sdk-runtime`。
+`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`InitializeParams.maxTokens` 是可选的正安全整数，用于限制 SDK 创建的 agent 及其进程内后代每次对话模型输出；省略时由提供方默认值控制。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇表是线契约的一部分。`serverInfo.name` 保持线上稳定值 `deepseek-harness-sdk-runtime`。
 
 ## Model Experience
 

packages/sdk/sdk-protocol/src/types.ts

@@ -20,6 +20,8 @@ export interface InitializeParams {
   provider: string
   /** Model name every SDK-created agent runs on (the server may mount a fallback adapter; see `HarnessSdkServer.initialize`). */
   model: string
+  /** Optional positive output-token cap inherited by SDK-created agents and their in-process descendants. */
+  maxTokens?: number
 }
 
 /** Wire-stable server identity returned by initialization. */