Merge remote-tracking branch 'origin/master' into worktree/fix-ci-timing-flakes-20260727

packages/llm/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
-README.md: 0278a4a582e535125d001e09736b89f13be72a0c
-README.zh.md: e3e2b9559d69e4be10cd4d373bbda2dd47396b72
+README.md: 13a04aa9f73fec5824069644449009989d6fd924
+README.zh.md: 3e417c5f8be1f7831b99940c2a4aec815dc2c5b6

packages/llm/README.md

@@ -9,7 +9,7 @@ The LLM seam and its provider adapters. The interface package (`llm`) owns the a
 | `llm/` | Abstract LLM service + content-block vocabulary + chunk assembler | `ctx.llm` |
 | `token-meter/` | Replay-aware request and surface token measurement | `ctx.tokenMeter` |
 | `llm-retry/` | Bounded transient request retry policy | (listens to `agent/request-error`) |
-| `llm-deepseek/` | DeepSeek API adapter (hand-rolled fetch/SSE) | (registers on `ctx.llm`) |
+| `llm-deepseek/` | DeepSeek API adapter (direct fetch + eventsource-parser SSE) | (registers on `ctx.llm`) |
 | `llm-pi-ai/` | Multi-provider adapter via `@earendil-works/pi-ai` | (registers on `ctx.llm`) |
 
 The interface lives at `llm/llm/`; adapters, retry policy, and the reusable token meter are flat siblings under the group. Requests route by `provider`, while `model` is passed through to the selected adapter. The route-owning adapter optionally resolves exact provider/model context capacity; the token meter remains model-agnostic. A new provider adapter registers one or more provider routes on `ctx.llm` without touching the interface or consumers. See [twin LLM adapters](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the two shipping implementations, the [replay token meter Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md) for measurement ownership, and the [routed model context Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md) for capacity and compaction-policy ownership.

packages/llm/README.zh.md

@@ -9,7 +9,7 @@ LLM seam 及其提供方适配器。接口包（`llm`）拥有抽象服务、内
 | `llm/` | 抽象 LLM 服务 + 内容块词汇 + 分片组装器 | `ctx.llm` |
 | `token-meter/` | 感知回放的请求与表层 token 测量 | `ctx.tokenMeter` |
 | `llm-retry/` | 有界的暂时性请求重试策略 | （监听 `agent/request-error`） |
-| `llm-deepseek/` | DeepSeek API 适配器（手写 fetch/SSE） | （注册到 `ctx.llm`） |
+| `llm-deepseek/` | DeepSeek API 适配器（直接 fetch + eventsource-parser SSE） | （注册到 `ctx.llm`） |
 | `llm-pi-ai/` | 通过 `@earendil-works/pi-ai` 实现的多提供方适配器 | （注册到 `ctx.llm`） |
 
 接口位于 `llm/llm/`；适配器、重试策略和可复用的 token 计量器都是该分组下的扁平兄弟包。请求按 `provider` 路由，而 `model` 会原样传给选中的适配器。拥有路由的适配器可以解析精确的提供方／模型上下文容量；token 计量器仍与模型无关。新的提供方适配器只需在 `ctx.llm` 上注册一个或多个提供方路由，无需改动接口或消费方。两个已交付实现见[双生 LLM 适配器](../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)，测量归属见[回放 token 计量器 Agent Note](../../.agents/notes/implemented/architecture/2026-07-15-replay-token-meter-service.md)，容量与压缩策略归属见[路由模型上下文 Agent Note](../../.agents/notes/implemented/architecture/2026-07-20-routed-model-context-and-compaction-policy.md)。

packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: cfa11f34a69b1098d0ff894dd2193cfbf9809be3
-README.zh.md: b3ec9413427a4cb1a22152e0a1d9c9e432cdad8d
+README.md: 4358620295547248ca87c42e07022c5eab0c947b
+README.zh.md: 4ecc5dd2e5980751ca6e724b5041efefc8114077

packages/llm/llm-deepseek/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-DeepSeek chat-completions adapter for the harness LLM seam: hand-rolled `fetch` + SSE translation from the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.
+DeepSeek chat-completions adapter for the harness LLM seam: direct `fetch` + SSE (framed by `eventsource-parser`) translating the official wire format (source of truth: the API docs — guides/thinking_mode, guides/tool_calls, api/create-chat-completion) into the `StreamChunk` protocol.
 
 A second, library-backed implementation of the same seam exists in `@deepseek-ai/dsh-llm-pi-ai`. This package always owns the `deepseek` provider route; mounting a pi-ai profile with `provider: deepseek` in the same context throws `LlmError('DUPLICATE_ADAPTER')` by design.
 

packages/llm/llm-deepseek/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-harness LLM seam 的 DeepSeek chat-completions 适配器：手写 `fetch` + SSE，将官方协议格式（真源：API 文档 guides/thinking_mode、guides/tool_calls、api/create-chat-completion）转换为 `StreamChunk` 协议。
+harness LLM seam 的 DeepSeek chat-completions 适配器：直接 `fetch` + SSE（由 `eventsource-parser` 分帧），将官方协议格式（真源：API 文档 guides/thinking_mode、guides/tool_calls、api/create-chat-completion）转换为 `StreamChunk` 协议。
 
 同一 seam 的第二个库支持实现位于 `@deepseek-ai/dsh-llm-pi-ai`。本包始终拥有 `deepseek` 提供方路由；在同一上下文中装载 `provider: deepseek` 的 pi-ai profile 会按设计抛出 `LlmError('DUPLICATE_ADAPTER')`。
 

packages/llm/llm-deepseek/package.json

@@ -33,6 +33,7 @@
     "cordis": "^4.0.0-rc.7"
   },
   "dependencies": {
+    "eventsource-parser": "^3.1.0",
     "schemastery": "^3.18.0"
   },
   "devDependencies": {

packages/llm/llm-deepseek/src/adapter.ts

@@ -20,7 +20,7 @@ import { parseSse } from './sse.ts'
 import { translate } from './translate.ts'
 import type { WireError } from './types.ts'
 
-/** One optional model entry advertised by the hand-written adapter. */
+/** One optional model entry advertised by the direct-fetch adapter. */
 export interface DeepSeekCatalogModel {
   /** Wire model id accepted by the configured endpoint. */
   id: string

packages/llm/llm-deepseek/src/sse.ts

@@ -1,65 +1,33 @@
 /**
- * Decode an SSE byte stream into event `data` payloads. Network reads may split UTF-8 or lines;
- * CRLF, comments, non-data fields, and multi-data events are handled per SSE rules. The literal
- * `[DONE]` is yielded so the caller owns final flushing, and EOF before it raises {@link LlmError}.
+ * Decode an SSE byte stream into event `data` payloads. Framing — chunk
+ * reassembly, UTF-8/CRLF/BOM handling, comment and non-data field skipping,
+ * multi-`data:` joining — is `eventsource-parser`'s; this module keeps only
+ * the DeepSeek protocol: the literal `[DONE]` is yielded so the caller owns
+ * final flushing, and EOF before it raises {@link LlmError}. Framing is
+ * spec-strict: an event dispatches only on its blank-line terminator, so an
+ * unterminated tail at EOF is truncation, not a flushable payload.
  *
- * Minimal SSE (text/event-stream) parser for the chat-completions stream.
  * @module dsh-llm-deepseek/sse
  */
 
+import { EventSourceParserStream } from 'eventsource-parser/stream'
 import { LlmError } from '@deepseek-ai/dsh-llm'
 
 /** The terminal payload DeepSeek (and OpenAI) send after the last chunk. */
 export const DONE = '[DONE]'
 
-/** Extract the joined data payload from one raw SSE event block. */
-function eventData(block: string): string | undefined {
-  const data: string[] = []
-  for (const rawLine of block.split('\n')) {
-    const line = rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine
-    if (line.startsWith('data:')) {
-      // The spec strips ONE leading space after the colon.
-      data.push(line.startsWith('data: ') ? line.slice(6) : line.slice(5))
-    }
-    // Comments (':…') and other fields (event:, id:, retry:) are ignored.
-  }
-  if (data.length === 0) return undefined
-  return data.join('\n')
-}
-
 /**
- * Parse a byte stream into SSE data payloads. Yields `[DONE]` as the final
+ * Parse an SSE byte stream into data payloads. Yields `[DONE]` as the final
  * value and returns; throws `LlmError('STREAM_CLOSED')` when the stream ends
  * without it (truncated response — the model call cannot be trusted).
  * @param stream - raw SSE bytes; reads may split anywhere, including mid-UTF-8 sequence.
  * @returns each event's data payload in arrival order, the `[DONE]` sentinel last.
  */
-export async function* parseSse(stream: AsyncIterable<Uint8Array>): AsyncGenerator<string> {
-  const decoder = new TextDecoder()
-  let buffer = ''
-
-  for await (const bytes of stream) {
-    buffer += decoder.decode(bytes, { stream: true })
-    // Events are separated by a blank line (\n\n; tolerate \r\n\r\n via the
-    // per-line \r strip in eventData and a normalized split here).
-    let boundary: number
-    while ((boundary = buffer.search(/\r?\n\r?\n/)) !== -1) {
-      const matched = /\r?\n\r?\n/.exec(buffer.slice(boundary))
-      const block = buffer.slice(0, boundary)
-      // matched cannot be null: search() just found the same pattern at 0.
-      buffer = buffer.slice(boundary + (matched as RegExpExecArray)[0].length)
-      const data = eventData(block)
-      if (data === undefined) continue
-      yield data
-      if (data === DONE) return
-    }
-  }
-
-  // Flush any final un-terminated event (servers usually end with \n\n, but
-  // a trailing block without one is still parseable).
-  buffer += decoder.decode()
-  const data = eventData(buffer)
-  if (data !== undefined) {
+export async function* parseSse(stream: ReadableStream<BufferSource>): AsyncGenerator<string> {
+  const events = stream
+    .pipeThrough(new TextDecoderStream())
+    .pipeThrough(new EventSourceParserStream())
+  for await (const { data } of events) {
     yield data
     if (data === DONE) return
   }

packages/llm/llm-deepseek/tests/adapter.e2e.ts

@@ -7,7 +7,7 @@ import type { Config } from '@deepseek-ai/dsh-llm-deepseek'
 import { assemble, type AssembledResult } from './assemble.ts'
 
 /**
- * Real-API e2e for the hand-rolled adapter: V4 Flash + V4 Pro across
+ * Real-API e2e for the direct-fetch adapter: V4 Flash + V4 Pro across
  * thinking modes and both official effort levels. Key-gated — skips
  * entirely without $DEEPSEEK_API_KEY (see vitest.e2e.config.ts).
  */

packages/llm/llm-deepseek/tests/sse.spec.ts

@@ -2,12 +2,21 @@ import { describe, expect, it } from 'vitest'
 import { LlmError } from '@deepseek-ai/dsh-llm'
 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> {
+/**
+ * DeepSeek protocol contract only: the [DONE] sentinel and STREAM_CLOSED on
+ * EOF without it. SSE framing (chunk splits, CRLF, multi-data joins, comments)
+ * is eventsource-parser's contract, not re-proven here.
+ */
+
+/** Build an SSE byte stream from string fragments (fragments = network reads). */
+function bytes(...fragments: string[]): ReadableStream<Uint8Array<ArrayBuffer>> {
   const encoder = new TextEncoder()
-  for (const fragment of fragments) {
-    yield typeof fragment === 'string' ? encoder.encode(fragment) : fragment
-  }
+  return new ReadableStream({
+    start(controller) {
+      for (const fragment of fragments) controller.enqueue(encoder.encode(fragment))
+      controller.close()
+    },
+  })
 }
 
 async function collect(stream: AsyncIterable<string>): Promise<string[]> {
@@ -17,57 +26,14 @@ async function collect(stream: AsyncIterable<string>): Promise<string[]> {
 }
 
 describe('parseSse', () => {
-  it('parses simple events and the DONE sentinel', async () => {
+  it('yields event payloads and the DONE sentinel', async () => {
     const events = await collect(parseSse(bytes('data: {"a":1}\n\ndata: [DONE]\n\n')))
     expect(events).toEqual(['{"a":1}', DONE])
   })
 
-  it('handles events split across reads at arbitrary positions', async () => {
-    const events = await collect(parseSse(bytes('da', 'ta: {"a"', ':1}\n', '\ndata: [DO', 'NE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('handles multi-byte UTF-8 split across reads', async () => {
-    const encoded = new TextEncoder().encode('data: {"text":"日本語"}\n\ndata: [DONE]\n\n')
-    // Split inside the 3-byte sequence for 日.
-    const splitAt = 16
-    const events = await collect(parseSse(bytes(encoded.slice(0, splitAt), encoded.slice(splitAt))))
-    expect(events).toEqual(['{"text":"日本語"}', DONE])
-  })
-
-  it('tolerates CRLF line endings', async () => {
-    const events = await collect(parseSse(bytes('data: {"a":1}\r\n\r\ndata: [DONE]\r\n\r\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('joins multi-data events with newlines (SSE spec)', async () => {
-    const events = await collect(parseSse(bytes('data: line1\ndata: line2\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['line1\nline2', DONE])
-  })
-
-  it('ignores comments and non-data fields', async () => {
-    const events = await collect(parseSse(bytes(': keepalive\nevent: chunk\nid: 7\ndata: {"a":1}\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('skips blocks without data fields', async () => {
-    const events = await collect(parseSse(bytes(': ping\n\ndata: {"a":1}\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('preserves data lines without the optional space', async () => {
-    const events = await collect(parseSse(bytes('data:{"a":1}\n\ndata:[DONE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('parses several events from one read', async () => {
-    const events = await collect(parseSse(bytes('data: 1\n\ndata: 2\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['1', '2', DONE])
-  })
-
-  it('flushes a final un-terminated DONE at stream end', async () => {
-    const events = await collect(parseSse(bytes('data: {"a":1}\n\ndata: [DONE]')))
-    expect(events).toEqual(['{"a":1}', DONE])
+  it('stops yielding after DONE even when more data follows', async () => {
+    const events = await collect(parseSse(bytes('data: [DONE]\n\ndata: {"late":1}\n\n')))
+    expect(events).toEqual([DONE])
   })
 
   it('throws STREAM_CLOSED when the stream ends without DONE', async () => {
@@ -83,26 +49,10 @@ describe('parseSse', () => {
     await expect(collect(parseSse(bytes('data: {"a"')))).rejects.toThrow(/without \[DONE\]/)
   })
 
-  it('stops yielding after DONE even when more data follows', async () => {
-    const events = await collect(parseSse(bytes('data: [DONE]\n\ndata: {"late":1}\n\n')))
-    expect(events).toEqual([DONE])
-  })
-})
-
-describe('parseSse edge branches', () => {
-  it('handles a lone CR-terminated data line', async () => {
-    // Exercises the \r-strip branch on a line that is ONLY "data:…\r".
-    const events = await collect(parseSse(bytes('data: {"a":1}\r\n\r\ndata:[DONE]\r\n\r\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('strips CR from non-data field lines too', async () => {
-    const events = await collect(parseSse(bytes('event: chunk\r\ndata: {"a":1}\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['{"a":1}', DONE])
-  })
-
-  it('treats bare "data:" lines as empty payload entries', async () => {
-    const events = await collect(parseSse(bytes('data:\ndata: x\n\ndata: [DONE]\n\n')))
-    expect(events).toEqual(['\nx', DONE])
+  it('treats a final DONE missing its blank-line terminator as truncation', async () => {
+    // Spec-strict framing: an event dispatches only on its blank-line
+    // terminator, so an unterminated tail at EOF is STREAM_CLOSED — real
+    // providers always terminate events, so a missing terminator is truncation.
+    await expect(collect(parseSse(bytes('data: {"a":1}\n\ndata: [DONE]')))).rejects.toThrow(/without \[DONE\]/)
   })
 })

packages/llm/llm/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/llm/llm/README.md
-README.md: e11b997cddaacaea7fec00f73b7f5b47c60a943d
-README.zh.md: e074d7f764c130b4ea3df343f566b27ef3a5dd3d
+README.md: 3efb3ece3caadeaceaa3c504ba4b10ddb951127a
+README.zh.md: 4af8b8d08cc96ff0e36b10b15e1d86afd43004c9

packages/llm/llm/README.md

@@ -64,7 +64,7 @@ Every product adapter sends application identity on provider HTTP requests. `att
 
 ### Real adapters
 
-Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses hand-rolled fetch/SSE for the `deepseek` route, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) dynamically resolves configured provider/model pairs through `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish, tool arguments remain raw strings, and errors take one of two sanctioned paths. See [the twin LLM adapters](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the design rationale.
+Two adapters implement `LlmAdapter` on different internals: [`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) uses direct fetch with `eventsource-parser` SSE framing for the `deepseek` route, while [`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) dynamically resolves configured provider/model pairs through `@earendil-works/pi-ai`. Both follow the `StreamChunk` conventions in `types.ts`: usage precedes finish, tool arguments remain raw strings, and errors take one of two sanctioned paths. See [the twin LLM adapters](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md) for the design rationale.
 
 ## Model Experience
 

packages/llm/llm/README.zh.md

@@ -64,7 +64,7 @@
 
 ### 真实适配器
 
-两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用手写 fetch/SSE，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `StreamChunk` 约定，定义见 `types.ts`：usage 先于 finish，工具参数保持原始字符串，错误使用两种已批准路径之一。设计理由见 [双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)。
+两个适配器使用不同内部机制实现 `LlmAdapter`：[`@deepseek-ai/dsh-llm-deepseek`](../llm-deepseek) 针对 `deepseek` 路由使用直接 fetch 加 `eventsource-parser` SSE 分帧，[`@deepseek-ai/dsh-llm-pi-ai`](../llm-pi-ai) 则通过 `@earendil-works/pi-ai` 动态解析已配置提供方／模型对。两者都遵循 `StreamChunk` 约定，定义见 `types.ts`：usage 先于 finish，工具参数保持原始字符串，错误使用两种已批准路径之一。设计理由见 [双 LLM 适配器](../../../.agents/notes/implemented/architecture/2026-06-13-twin-llm-adapters.md)。
 
 ## 模型体验
 

packages/llm/llm/src/index.ts

@@ -121,8 +121,8 @@ export interface PreparedLlmCall {
 /**
  * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
  * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
- * `attributionHeaders()`; prove that at the wire or library header-hook boundary. The hand-rolled
- * DeepSeek and pi-ai adapters intentionally exercise this contract through different internals.
+ * `attributionHeaders()`; prove that at the wire or library header-hook boundary. The direct-fetch
+ * DeepSeek and library-backed pi-ai adapters intentionally exercise this contract through different internals.
  */
 export abstract class LlmAdapter {
   /**

packages/sdk/helper/src/features/builtin/provider.ts

@@ -1,5 +1,5 @@
 /**
- * Required hand-rolled DeepSeek and custom pi-ai provider behavior.
+ * Required direct-fetch DeepSeek and custom pi-ai provider behavior.
  *
  * @module @deepseek-ai/dsh-helper/features/builtin/provider
  */
@@ -74,7 +74,7 @@ export class ProviderFeature extends ExclusiveOptionFeature {
   override readonly required = true
   override readonly options = [new DeepSeekOption(), new CustomOption()]
 
-  /** Prefer the hand-rolled adapter and its public endpoint defaults. */
+  /** Prefer the direct-fetch adapter and its public endpoint defaults. */
   override defaultOptions(): readonly string[] {
     return ['deepseek']
   }