fix(subagent): complete output selection contract

packages/scaffold/client/tests/fake-runtime.ts

@@ -26,9 +26,8 @@
  *   array; `FAKE_MESSAGE_WITHOUT_DATA`: assistant/message with no data
  *   member; `FAKE_MALFORMED_REASON`: `session.finished` reason is a bare
  *   string (wire-validation probes).
- * - `FAKE_EMPTY_MESSAGE`: the turn's assistant/message has EMPTY content (a
- *   usage-only max-tokens step) after streaming the text chunk — a consumer
- *   must keep the streamed text instead of the empty message.
+ * - `FAKE_EMPTY_MESSAGE`: the turn streams a text chunk, then records an empty
+ *   assistant/message for a usage-only max-tokens step.
  * - `FAKE_HANG_INIT`: never answer `initialize` (mid-handshake cancel probe).
  * - `FAKE_INIT_READY` + `FAKE_INIT_GO`: touch the READY file when `initialize`
  *   arrives, then poll for the GO file before answering (deterministic
@@ -120,9 +119,8 @@ function runTurn(sessionId: string): void {
     message: {
       id: `fake-assistant-${seq}`,
       role: 'assistant',
-      // FAKE_EMPTY_MESSAGE: a usage-only terminal message (the harness loop
-      // appends one when a max-tokens step assembled no text blocks) whose
-      // empty content must not erase the text streamed above.
+      // Model the usage-only message recorded after a max-tokens step that
+      // assembled no output blocks.
       content: env.FAKE_EMPTY_MESSAGE !== undefined ? [] : [{ type: 'text', text }],
       source: { kind: 'model', provider: 'fake', model: 'fake' },
     },

packages/scaffold/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/scaffold/protocol/README.md
-README.md: 88a48957d0d44cec9f776d31eab7d25bd353de5f
-README.zh.md: 6618d8838a00f945c79d7ec24b1e7491df08a3f1
+README.md: 082a890454f900aec51df123669f28814d39d601
+README.zh.md: d9b8460e51b5313f4c3a8ac66471e8cd39142430

packages/scaffold/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. `SessionPromptResult.messageId` identifies the queued `UserMessage`; it does not identify a later assistant message, turn ending, or prompt result. Clients combine the open-ended `session.event` stream with agent-wide `session.status` according to their own activity ownership. `InitializeParams.maxTokens` is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission allows the selected adapter's exact-model default to apply, or otherwise preserves provider behavior. 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. `SessionPromptResult.messageId` identifies the queued `UserMessage`; it does not identify a later assistant message, turn ending, or prompt result. Clients combine the open-ended `session.event` stream with agent-wide `session.status` according to their own activity ownership. `SubagentFinishedNotification.lastAssistantMessage` contains the child's last non-empty assistant message or, when no such message exists, its accumulated assistant text; the field is absent when the child produced neither. `InitializeParams.maxTokens` is an optional positive safe integer that caps each conversation-model output for SDK-created agents and their in-process descendants; omission allows the selected adapter's exact-model default to apply, or otherwise preserves provider behavior. 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/scaffold/protocol/README.zh.md

@@ -22,7 +22,7 @@ DeepSeek Harness SDK 运行时的共享协议格式（wire format）：一个按
 | server→client | `subagent.started` | `SubagentStartedNotification` |
 | server→client | `subagent.finished` | `SubagentFinishedNotification`（仅进程内运行） |
 
-`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式约定的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
+`HarnessSdkRequestMap` 与 `HarnessSdkNotificationMap` 按方法名索引这些类型。`SessionPromptResult.messageId` 标识已排队的 `UserMessage`；它不标识后续的助手消息、轮次结束或提示词结果。客户端根据自己对活动区间的所有权，组合持续开放的 `session.event` 流与 agent 级的 `session.status`。`SubagentFinishedNotification.lastAssistantMessage` 包含子 agent 最后一条非空 assistant 消息；若不存在这类消息，则包含其累积的 assistant 文本；子 agent 两种输出均未产生时，该字段缺省。`InitializeParams.maxTokens` 是可选的正的安全整数，用于限制 SDK 创建的 agent 及其进程内后代的每次对话模型输出；省略时会应用所选适配器的确切模型默认值，否则提供方行为保持不变。通知载荷类型依赖 `SessionEvent`（`dsh-session`）、`ContentBlock`（`dsh-llm`）与 `SubagentStopReason`（`dsh-subagent`）——协议以完整会话日志封套进行流式传输，因此会话词汇是协议格式约定的一部分。`serverInfo.name` 的协议值固定为 `deepseek-harness-sdk-runtime`。
 
 ## 模型体验
 

packages/scaffold/protocol/src/types.ts

@@ -85,7 +85,7 @@ export interface SubagentFinishedNotification {
   status: SdkRunStatus
   /** The provider-reported stop reason. */
   stopReason: SubagentStopReason
-  /** The child's final assistant message, when it produced one. */
+  /** The child's selected assistant output; absent when the child produced none. */
   lastAssistantMessage?: ContentBlock[]
 }
 

packages/scaffold/server/tests/built-scope-carrier.e2e.ts

@@ -106,8 +106,8 @@ describe.skipIf(!existsSync(jsonrpcBundle))('dsh-jsonrpc BUILT scope carrier', (
     })
 
     expect(stderr).not.toContain('listener threw')
-    // A childless result carries NO lastAssistantMessage on the wire: the end
-    // edge encodes "no output" as an absent field, never `[]`.
+    // A result without output omits lastAssistantMessage from the wire; it
+    // never sends `[]`.
     expect(JSON.parse(stdout) as unknown).toEqual([{
       method: 'subagent.finished',
       params: {

packages/scaffold/server/tests/server.spec.ts

@@ -736,8 +736,8 @@ describe('HarnessSdkServer', () => {
         stopReason: 'error',
       })
 
-      // A childless result carries NO lastAssistantMessage on the wire: the
-      // end edge encodes "no output" as an absent field, never `[]`.
+      // A result without output omits lastAssistantMessage from the wire; it
+      // never sends `[]`.
       expect(transport.notifications).toContainEqual({
         method: 'subagent.finished',
         params: {