@sema-agent/sdk 4.2.0 → 5.0.0

package/dist/resources/trace.d.ts

@@ -22,7 +22,13 @@ export declare class TraceResource {
         nextCursor?: string;
     }>;
     /** GET /v1/tasks/source-summary?sinceSec= — per-door usage rollup `{rows:[{source,status,count}]}`
-     *  (the pinned wire contract; trace-auth surface). The web usage overview's data source. */
+     *  (the pinned wire contract; trace-auth surface).
+     *
+     *  🔴 **ops-only** (server `routes/trace-usage.ts:51-54`): `if (!isFleetWide(req)) → 401 auth.unauthorized`.
+     *  This is a CROSS-TENANT aggregate with no owner-scoped variant, so a plain principal caller gets 401 —
+     *  ALWAYS, with a perfectly valid credential. Do NOT wire it behind an end-user JWT (the symptom reads as a
+     *  login/credential problem and sends the investigation the wrong way); it is a fleet-console data source.
+     *  `sinceSec` is clamped server-side to `[60 s, 30 d]`; absent ⇒ 24 h. */
     sourceSummary(opts?: {
         sinceSec?: number;
         signal?: AbortSignal;
@@ -34,9 +40,17 @@ export declare class TraceResource {
             count: number;
         }[];
     }>;
-    /** GET /v1/tasks/:id/turns — the full turn trace (the workspace action timeline). Envelope
-     *  `{ turns, nextCursor?, retainedFrom }` (pinned wire contract); turn item shape draft. */
+    /** GET /v1/tasks/:id/turns[?limit=&cursor=] — the turn trace (the workspace action timeline). Envelope
+     *  `{ turns, nextCursor?, retainedFrom }` (pinned wire contract); turn item shape draft.
+     *
+     *  🔴 **PAGED, newest-first** (server `routes/trace-usage.ts:223-232`): `limit` is clamped to 1..100 and
+     *  DEFAULTS TO 20 — a 500-turn run does not come back whole. `cursor` is an opaque turn-seq: pass back the
+     *  `nextCursor` of the previous page to walk BACKWARD (older). `nextCursor` is present only while more
+     *  eligible turns remain. Until 4.3.0 this method took no query args at all, so the `nextCursor` it returned
+     *  could not be sent anywhere — the older pages were unreachable through the SDK. */
     turns(taskId: string, opts?: {
+        limit?: number;
+        cursor?: string;
         signal?: AbortSignal;
     }): Promise<{
         turns: TraceTurn[];

package/dist/resources/trace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"AAAA;;iGAEiG;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;4DAEwD;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYtM;gGAC4F;IAGtF,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAKxK;gGAC4F;IACtF,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAIzI;2HACuH;IACjH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;IASpG;;;;;;;;;;kFAU8E;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,gBAAgB,CAAC;CA6BvH"}
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"AAAA;;iGAEiG;AACjG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,gBAAgB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGtF,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;4DAEwD;IAClD,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAYtM;;;;;;;8EAO0E;IAGpE,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAOxK;;;;;;;yFAOqF;IAC/E,KAAK,CACT,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC;QAAE,KAAK,EAAE,SAAS,EAAE,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ9E;2HACuH;IACjH,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,QAAQ,EAAE,CAAA;KAAE,CAAC;IASpG;;;;;;;;;;kFAU8E;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,cAAc,CAAC,gBAAgB,CAAC;CA6BvH"}

package/dist/resources/trace.js

@@ -25,17 +25,37 @@ export class TraceResource {
         return this.t.request({ method: "GET", path: `/v1/tasks${qs ? `?${qs}` : ""}`, signal: opts?.signal });
     }
     /** GET /v1/tasks/source-summary?sinceSec= — per-door usage rollup `{rows:[{source,status,count}]}`
-     *  (the pinned wire contract; trace-auth surface). The web usage overview's data source. */
+     *  (the pinned wire contract; trace-auth surface).
+     *
+     *  🔴 **ops-only** (server `routes/trace-usage.ts:51-54`): `if (!isFleetWide(req)) → 401 auth.unauthorized`.
+     *  This is a CROSS-TENANT aggregate with no owner-scoped variant, so a plain principal caller gets 401 —
+     *  ALWAYS, with a perfectly valid credential. Do NOT wire it behind an end-user JWT (the symptom reads as a
+     *  login/credential problem and sends the investigation the wrong way); it is a fleet-console data source.
+     *  `sinceSec` is clamped server-side to `[60 s, 30 d]`; absent ⇒ 24 h. */
     // 2.1.4:返回型对齐 server 实况(trace-usage.ts:61)——顶层恒发 sinceSec(生效窗口秒);store 三实现的
     // source 签名均为 string|null(census 批2 三段发现的 spec 谎同源修)。
     async sourceSummary(opts) {
-        const qs = opts?.sinceSec ? `?sinceSec=${opts.sinceSec}` : "";
+        // `!== undefined`,不是真值判断:`sinceSec: 0` 曾被 falsy-drop 成"没传"⇒ 落默认 24h,而调用方的本意是
+        // 让 server 把它夹到下限 60s。显式传了就发,值域由 server 判。
+        const qs = opts?.sinceSec !== undefined ? `?sinceSec=${encodeURIComponent(String(opts.sinceSec))}` : "";
         return this.t.request({ method: "GET", path: `/v1/tasks/source-summary${qs}`, signal: opts?.signal });
     }
-    /** GET /v1/tasks/:id/turns — the full turn trace (the workspace action timeline). Envelope
-     *  `{ turns, nextCursor?, retainedFrom }` (pinned wire contract); turn item shape draft. */
+    /** GET /v1/tasks/:id/turns[?limit=&cursor=] — the turn trace (the workspace action timeline). Envelope
+     *  `{ turns, nextCursor?, retainedFrom }` (pinned wire contract); turn item shape draft.
+     *
+     *  🔴 **PAGED, newest-first** (server `routes/trace-usage.ts:223-232`): `limit` is clamped to 1..100 and
+     *  DEFAULTS TO 20 — a 500-turn run does not come back whole. `cursor` is an opaque turn-seq: pass back the
+     *  `nextCursor` of the previous page to walk BACKWARD (older). `nextCursor` is present only while more
+     *  eligible turns remain. Until 4.3.0 this method took no query args at all, so the `nextCursor` it returned
+     *  could not be sent anywhere — the older pages were unreachable through the SDK. */
     async turns(taskId, opts) {
-        return this.t.request({ method: "GET", path: `/v1/tasks/${encodeURIComponent(taskId)}/turns`, signal: opts?.signal });
+        const q = new URLSearchParams();
+        if (opts?.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts?.cursor !== undefined)
+            q.set("cursor", opts.cursor);
+        const qs = q.toString();
+        return this.t.request({ method: "GET", path: `/v1/tasks/${encodeURIComponent(taskId)}/turns${qs ? `?${qs}` : ""}`, signal: opts?.signal });
     }
     /** GET /v1/tasks/:id/artifacts — workspace artifacts (projection of the persisted trace; co-signed
      *  the pinned wire contract). Job-level aggregation = list by jobId then fetch per run (each carries taskId+jobId). */

package/dist/resources/trace.js.map

@@ -1 +1 @@
-{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"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"}

package/dist/resources/workflows.d.ts

@@ -9,8 +9,9 @@
  *     不复用 `parseSse`（其硬编码 AgentEvent + 自动重连,与 workflow 帧/无-resume 语义冲突）→ 留**专用 reader follow-on**。 */
 import type { Transport } from "../transport.js";
 import type { WorkflowRunSummary, WorkflowRun, WorkflowStreamEvent } from "../types.js";
-/** workflow-agent steer 200 receipt (server 1.214 server.js:1755 — exact literal: `status:"running"`,
- *  `delivery:"applied"`, `marker` = the engine-minted delivery marker; NO `note`, unlike the run-subagent verb). */
+/** workflow-agent steer 200 receipt (server 5.3.0 `src/http/routes/workflows.ts:279` — exact literal:
+ *  `status:"running"`, `delivery:"applied"`, `marker` = the engine-minted delivery marker; NO `note`, unlike the
+ *  run-subagent verb). (4.3.0 坐标刷新:此前写的是 `server 1.214 server.js:1755`,那是 routes 拆分前的门牌。) */
 export interface WorkflowAgentSteerReceipt {
     runId: string;
     label: string;
@@ -73,9 +74,16 @@ export declare class WorkflowsResource {
      *  批次①-5:此前单一必填-status 形状不诚实,截断行现网真的没有 status)。`nextOffset` = the pagination
      *  cursor, present only when the page came back exactly `limit`-sized (more may exist) — 🔴 此前类型上
      *  完全没有这个字段,消费方读不到分页续读钩子。
+     *
+     *  🔴 **分页入参(4.3.0,FW-2)**:`limit` 缺省 20、**上限 50**;`offset` >= 0(server `routes/workflows.ts:123-124`)。
+     *  在此之前 SDK 补了 `nextOffset` 字段却没补能用它的入口 —— 一个 21 个 agent 的 workflow 拿回 20 条 +
+     *  `nextOffset: 20`,消费方握着游标却发现没有任何参数能把它送回去,第 21 条 agent 的失败诊断在 SDK 通路上
+     *  **不可达**,只能绕过 SDK 裸拼 URL(而绕过 SDK 正是这个包存在的理由被否定的那一刻)。
      *  404 = run 不存在/非 owner(无存在性 oracle);501 = journal store 未接(self-orchestration off)。 */
     journal(runId: string, opts?: {
         session?: string;
+        limit?: number;
+        offset?: number;
         signal?: AbortSignal;
     }): Promise<WorkflowJournalPage>;
     /** `session` filter semantics(distinct from the per-id accept-phase): present = strict-equality filter
@@ -95,24 +103,39 @@ export declare class WorkflowsResource {
         session?: string;
         signal?: AbortSignal;
     }): Promise<WorkflowRun>;
-    /** server 1.214 (server.js:1706 WORKFLOW_AGENT_STEER_RE region) — STEER a RUNNING AGENT of a WORKFLOW run
+    /** server 5.3.0 (`src/http/routes/workflows.ts:25` 的 `WORKFLOW_AGENT_STEER_RE` 常量 / `:194` 的处理段)
+     *  — STEER a RUNNING AGENT of a WORKFLOW run
      *  (the S8 self-orchestration sibling of `runs.steerSubagent`): inject `content` into the labelled live agent;
      *  it drains at the agent's next tool round. `label` = the workflow-graph agent label (NOT a toolCallId);
      *  a label shared by >1 live agents → 409 `steering.ambiguous_label`. Body `{ content }` (non-empty, else 400).
      *  200 {@link WorkflowAgentSteerReceipt} (`marker`, no `note`).
      *
      *  🔴 REPLICA-LOCAL live handle: 409 `steering.not_running` = agent settled / workflow not running / live on
-     *  another replica (cross-replica live-steer unsupported). 501 = worker without SELF_ORCHESTRATION_ENABLED
-     *  (gate on `capabilities.workflows`). Owner-scoped 404 (operator principals bypass). AT-MOST-ONCE (no retry). */
+     *  another replica (cross-replica live-steer unsupported).
+     *
+     *  🔴 **413 `steer.content_too_large`**(4.3.0 补,FW-12):`content` 超过 `STEER_IN_MAX_REQUEST_CHARS` 时
+     *  server **拒收**(`routes/workflows.ts:232-240`),而不是先截断再投递 —— `:229-231` 写明了为什么必须是拒:
+     *  先截会让引擎的 `[+N chars]` 披露低报,且脱敏门要同步、还烧事件循环。消费方应当分出这条臂并提示
+     *  「内容太长,请缩短」,而不是落进「未知错误 / 服务异常」兜底(用户根本不知道该怎么办)。
+     *
+     *  🔴 **501 的门是 `capabilities.workflowsList`,不是 `capabilities.workflows`**(4.3.0 更正,FW-5):
+     *  501 的真判据是 `!deps.workflowRunStore`(`routes/workflows.ts:197-200`),而
+     *  `workflows: deps.workflowsCapable ?? Boolean(deps.workflowRunStore)` 与
+     *  `workflowsList: Boolean(deps.workflowRunStore)` 是**两个不同的量**(`routes/capabilities.ts:276-289` 的注
+     *  逐字区分:`workflows` = ENGINE-CAN「引擎能不能自编排」,`workflowsList` = 能不能 durable 列 run)。
+     *  同一判据也管着 `list`/`get`/`journal`/`stream` 四条读面。查错了键的后果双向都有:
+     *  `workflows:true, workflowsList:false` ⇒ 入口被点亮、每次点都吃 501;反过来则把一个能用的面藏起来。
+     *  Owner-scoped 404 (operator principals bypass). AT-MOST-ONCE (no retry). */
     steerAgent(runId: string, label: string, message: {
         content: string;
     }, opts?: {
         session?: string;
         signal?: AbortSignal;
     }): Promise<WorkflowAgentSteerReceipt>;
-    /** GET /v1/workflows/:id/stream — LIVE S8 self-orchestration progress (`streamWorkflowRun` +
-     *  core `subscribeWorkflow`, server.ts). SSE; FIRST frame is `meta` `{version, runId}`, then each subsequent
-     *  frame carries a core `WorkflowEvent` (its `type` becomes the SSE `event` name; see `WorkflowStreamEvent`).
+    /** GET /v1/workflows/:id/stream — LIVE S8 self-orchestration progress (`streamWorkflowRun`,
+     *  server 5.3.0 `src/http/routes/workflows.ts:483` + core `subscribeWorkflow`). SSE; FIRST frame is `meta`
+     *  `{type:"meta", version, runId}`, then each subsequent frame carries a core `WorkflowEvent` (its `type`
+     *  becomes the SSE `event` name; see `WorkflowStreamEvent`).
      *
      *  🔴 NOT RESUMABLE (unlike `runs.events`/`trace.stream`): the source is REPLICA-LOCAL + in-process — there is
      *  NO durable seq / Last-Event-ID, so a drop is a FULL restart (re-`get()` for the snapshot), not a resume.
@@ -120,8 +143,17 @@ export declare class WorkflowsResource {
      *  would silently lose/duplicate frames here). TRANSIENT: a disconnect just ends the iterator. S8 flag-gated
      *  off → the route returns 501 (typed error) before any frame; owner-gated (non-owner → 404).
      *
-     *  No explicit terminal frame is guaranteed (the core subscription simply ends) — the generator returns when the
-     *  server closes the stream; `get()` for the authoritative terminal `status`. */
+     *  🔴 **There IS one terminal frame, and it means FAILURE** (4.3.0 更正,FW-3): if the core subscription
+     *  throws mid-stream the server emits `event: error` with
+     *  `data: {type:"error", errorCode:"workflow.stream_error", message:"workflow stream error"}`
+     *  (`routes/workflows.ts:517`; `:515-516` 写明了加 `errorCode` 的理由 —— 此前只发人话 message,消费端要么
+     *  锚文案、要么把「流断了」和「流正常结束」混为一谈)。这条注释此前写的是「没有终态帧保证」,照它写的消费方
+     *  会把一个**失败的** workflow 报成跑完了。正确姿势:分支
+     *  `if (f.event === "error" && f.data.errorCode === "workflow.stream_error")`,别锚 `message`。
+     *  除这条之外没有正常终态帧 —— 迭代器自然结束 ⇒ 用 `get()` 取权威终态 `status`。
+     *
+     *  保活是**真帧** `event: heartbeat\ndata: {}` @15s(`routes/workflows.ts:496`,旁注写明**故意不用 SSE 注释**:
+     *  逐帧解析的 BFF 会把注释丢掉,下游于是看到一个零帧窗口)。别按「跳过以 `:` 开头的行」实现读端。 */
     stream(runId: string, opts?: {
         session?: string;
         signal?: AbortSignal;

package/dist/resources/workflows.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/resources/workflows.ts"],"names":[],"mappings":"AAAA;;;;;;;;sGAQsG;AACtG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAGxF;oHACoH;AACpH,MAAM,WAAW,yBAAyB;IACxC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;0FAG0F;AAC1F,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;mFAEmF;AACnF,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,IAAI,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;2DAG2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,oBAAoB,GAAG,6BAA6B,CAAC;AAEtF;8BAC8B;AAC9B,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;+EAM2E;IAC3E,OAAO,CAAC,SAAS;IAIjB,gGAAgG;IAChG;;;;;;;;;6FASyF;IACnF,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI7G;;;2FAGuF;IACjF,IAAI,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,SAAS,EAAE,kBAAkB,EAAE,CAAA;KAAE,CAAC;IAS5I,uFAAuF;IACjF,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAIjG;;;;;;;;sHAQkH;IAC5G,UAAU,CACd,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,MAAM,EACb,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,EAC5B,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAChD,OAAO,CAAC,yBAAyB,CAAC;IASrC;;;;;;;;;;;qFAWiF;IAC1E,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CAoBrH"}
+{"version":3,"file":"workflows.d.ts","sourceRoot":"","sources":["../../src/resources/workflows.ts"],"names":[],"mappings":"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"}

package/dist/resources/workflows.js

@@ -24,9 +24,22 @@ export class WorkflowsResource {
      *  批次①-5:此前单一必填-status 形状不诚实,截断行现网真的没有 status)。`nextOffset` = the pagination
      *  cursor, present only when the page came back exactly `limit`-sized (more may exist) — 🔴 此前类型上
      *  完全没有这个字段,消费方读不到分页续读钩子。
+     *
+     *  🔴 **分页入参(4.3.0,FW-2)**:`limit` 缺省 20、**上限 50**;`offset` >= 0(server `routes/workflows.ts:123-124`)。
+     *  在此之前 SDK 补了 `nextOffset` 字段却没补能用它的入口 —— 一个 21 个 agent 的 workflow 拿回 20 条 +
+     *  `nextOffset: 20`,消费方握着游标却发现没有任何参数能把它送回去,第 21 条 agent 的失败诊断在 SDK 通路上
+     *  **不可达**,只能绕过 SDK 裸拼 URL(而绕过 SDK 正是这个包存在的理由被否定的那一刻)。
      *  404 = run 不存在/非 owner(无存在性 oracle);501 = journal store 未接(self-orchestration off)。 */
     async journal(runId, opts) {
-        return this.t.request({ method: "GET", path: `/v1/workflows/${encodeURIComponent(runId)}/journal${this.sessionQs(opts?.session)}`, signal: opts?.signal });
+        const q = new URLSearchParams();
+        if (opts?.session !== undefined)
+            q.set("session", opts.session);
+        if (opts?.limit !== undefined)
+            q.set("limit", String(opts.limit));
+        if (opts?.offset !== undefined)
+            q.set("offset", String(opts.offset));
+        const qs = q.toString();
+        return this.t.request({ method: "GET", path: `/v1/workflows/${encodeURIComponent(runId)}/journal${qs ? `?${qs}` : ""}`, signal: opts?.signal });
     }
     /** `session` filter semantics(distinct from the per-id accept-phase): present = strict-equality filter
      *  on the run's `originatingSessionId` (fieldless pre-core-1.210 rows are dropped); absent = full list.
@@ -47,15 +60,29 @@ export class WorkflowsResource {
     async get(runId, opts) {
         return this.t.request({ method: "GET", path: `/v1/workflows/${encodeURIComponent(runId)}${this.sessionQs(opts?.session)}`, signal: opts?.signal });
     }
-    /** server 1.214 (server.js:1706 WORKFLOW_AGENT_STEER_RE region) — STEER a RUNNING AGENT of a WORKFLOW run
+    /** server 5.3.0 (`src/http/routes/workflows.ts:25` 的 `WORKFLOW_AGENT_STEER_RE` 常量 / `:194` 的处理段)
+     *  — STEER a RUNNING AGENT of a WORKFLOW run
      *  (the S8 self-orchestration sibling of `runs.steerSubagent`): inject `content` into the labelled live agent;
      *  it drains at the agent's next tool round. `label` = the workflow-graph agent label (NOT a toolCallId);
      *  a label shared by >1 live agents → 409 `steering.ambiguous_label`. Body `{ content }` (non-empty, else 400).
      *  200 {@link WorkflowAgentSteerReceipt} (`marker`, no `note`).
      *
      *  🔴 REPLICA-LOCAL live handle: 409 `steering.not_running` = agent settled / workflow not running / live on
-     *  another replica (cross-replica live-steer unsupported). 501 = worker without SELF_ORCHESTRATION_ENABLED
-     *  (gate on `capabilities.workflows`). Owner-scoped 404 (operator principals bypass). AT-MOST-ONCE (no retry). */
+     *  another replica (cross-replica live-steer unsupported).
+     *
+     *  🔴 **413 `steer.content_too_large`**(4.3.0 补,FW-12):`content` 超过 `STEER_IN_MAX_REQUEST_CHARS` 时
+     *  server **拒收**(`routes/workflows.ts:232-240`),而不是先截断再投递 —— `:229-231` 写明了为什么必须是拒:
+     *  先截会让引擎的 `[+N chars]` 披露低报,且脱敏门要同步、还烧事件循环。消费方应当分出这条臂并提示
+     *  「内容太长,请缩短」,而不是落进「未知错误 / 服务异常」兜底(用户根本不知道该怎么办)。
+     *
+     *  🔴 **501 的门是 `capabilities.workflowsList`,不是 `capabilities.workflows`**(4.3.0 更正,FW-5):
+     *  501 的真判据是 `!deps.workflowRunStore`(`routes/workflows.ts:197-200`),而
+     *  `workflows: deps.workflowsCapable ?? Boolean(deps.workflowRunStore)` 与
+     *  `workflowsList: Boolean(deps.workflowRunStore)` 是**两个不同的量**(`routes/capabilities.ts:276-289` 的注
+     *  逐字区分:`workflows` = ENGINE-CAN「引擎能不能自编排」,`workflowsList` = 能不能 durable 列 run)。
+     *  同一判据也管着 `list`/`get`/`journal`/`stream` 四条读面。查错了键的后果双向都有:
+     *  `workflows:true, workflowsList:false` ⇒ 入口被点亮、每次点都吃 501;反过来则把一个能用的面藏起来。
+     *  Owner-scoped 404 (operator principals bypass). AT-MOST-ONCE (no retry). */
     async steerAgent(runId, label, message, opts) {
         return this.t.request({
             method: "POST",
@@ -64,9 +91,10 @@ export class WorkflowsResource {
             signal: opts?.signal,
         });
     }
-    /** GET /v1/workflows/:id/stream — LIVE S8 self-orchestration progress (`streamWorkflowRun` +
-     *  core `subscribeWorkflow`, server.ts). SSE; FIRST frame is `meta` `{version, runId}`, then each subsequent
-     *  frame carries a core `WorkflowEvent` (its `type` becomes the SSE `event` name; see `WorkflowStreamEvent`).
+    /** GET /v1/workflows/:id/stream — LIVE S8 self-orchestration progress (`streamWorkflowRun`,
+     *  server 5.3.0 `src/http/routes/workflows.ts:483` + core `subscribeWorkflow`). SSE; FIRST frame is `meta`
+     *  `{type:"meta", version, runId}`, then each subsequent frame carries a core `WorkflowEvent` (its `type`
+     *  becomes the SSE `event` name; see `WorkflowStreamEvent`).
      *
      *  🔴 NOT RESUMABLE (unlike `runs.events`/`trace.stream`): the source is REPLICA-LOCAL + in-process — there is
      *  NO durable seq / Last-Event-ID, so a drop is a FULL restart (re-`get()` for the snapshot), not a resume.
@@ -74,8 +102,17 @@ export class WorkflowsResource {
      *  would silently lose/duplicate frames here). TRANSIENT: a disconnect just ends the iterator. S8 flag-gated
      *  off → the route returns 501 (typed error) before any frame; owner-gated (non-owner → 404).
      *
-     *  No explicit terminal frame is guaranteed (the core subscription simply ends) — the generator returns when the
-     *  server closes the stream; `get()` for the authoritative terminal `status`. */
+     *  🔴 **There IS one terminal frame, and it means FAILURE** (4.3.0 更正,FW-3): if the core subscription
+     *  throws mid-stream the server emits `event: error` with
+     *  `data: {type:"error", errorCode:"workflow.stream_error", message:"workflow stream error"}`
+     *  (`routes/workflows.ts:517`; `:515-516` 写明了加 `errorCode` 的理由 —— 此前只发人话 message,消费端要么
+     *  锚文案、要么把「流断了」和「流正常结束」混为一谈)。这条注释此前写的是「没有终态帧保证」,照它写的消费方
+     *  会把一个**失败的** workflow 报成跑完了。正确姿势:分支
+     *  `if (f.event === "error" && f.data.errorCode === "workflow.stream_error")`,别锚 `message`。
+     *  除这条之外没有正常终态帧 —— 迭代器自然结束 ⇒ 用 `get()` 取权威终态 `status`。
+     *
+     *  保活是**真帧** `event: heartbeat\ndata: {}` @15s(`routes/workflows.ts:496`,旁注写明**故意不用 SSE 注释**:
+     *  逐帧解析的 BFF 会把注释丢掉,下游于是看到一个零帧窗口)。别按「跳过以 `:` 开头的行」实现读端。 */
     async *stream(runId, opts) {
         const o = {
             method: "GET",

package/dist/resources/workflows.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/resources/workflows.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workflows.js","sourceRoot":"","sources":["../../src/resources/workflows.ts"],"names":[],"mappings":"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"}

package/dist/resources/workspace.d.ts

@@ -24,6 +24,40 @@ export interface WorkspaceFile {
     /** [1894]③ 二进制判别(server 首 8KiB NUL 嗅探,git 同判据)——web 预览器分流用。 */
     binary: boolean;
 }
+/** `GET …/workspace` 的 200 信封(server `routes/sessions.ts:624-629`)。
+ *
+ *  🔴 4.3.0 提成 **exported type**(此前是 `list()` 返回位上的**内联闭合字面量**):两道 spec 门谁都扫不到
+ *  方法返回位置的内联形 —— `spec-field-drift-gate` 只扫 `src/types.ts` 的 exported interface,
+ *  `spec-resource-schema-gate` 只扫 `src/resources/*.ts` 的 exported type。于是这个信封漏了 `sessionId`
+ *  (server 与 spec 都把它列为 required)整整一个 major 版本而 CI 全绿。提出来 = 让第二道门罩住它。 */
+export interface WorkspaceSnapshotPage {
+    /** 恒发 —— 回声校验(拿它与请求的 id 对一遍防串会话)在 TS 下此前根本写不出来,只能强制断言绕过。 */
+    sessionId: string;
+    snapshots: WorkspaceSnapshotRow[];
+    /** 最新快照键;无快照时缺席。与展示行**同源**(server 防 ghost key:latest 绝不指向已被 reap 的快照)。 */
+    latest?: string;
+    /** ⚠️ **本页行数,不是快照总数** —— `total = snapshots.length`(server `:628`)。而且这条腿**没有任何
+     *  分页游标**:超过 `limit`(上限 100)的老快照取不到。渲「共 N 个快照」会在快照多于 limit 时永远显示
+     *  limit,用户以为老快照被清了。
+     *  🔴 同族的 {@link WorkspaceTreePage} 用**同一个键名**表示 `all.length` 的**全量** —— 同名键在同一族的
+     *  两条腿上语义相反,这是 server 侧的既成事实,别把两处的 `total` 当同一个量读。 */
+    total: number;
+    [k: string]: unknown;
+}
+/** `GET …/workspace/:key/tree` 的 200 信封(server `routes/sessions.ts:651-657`)。提成 exported type 的
+ *  理由同 {@link WorkspaceSnapshotPage}。 */
+export interface WorkspaceTreePage {
+    /** 恒发(server 与 spec 均列为 required)。 */
+    sessionId: string;
+    /** 解析后的**真实**快照键 —— 请求里传 `"latest"` 别名时,这里回的是它解析到的那个 uuidv7 键。 */
+    key: string;
+    entries: WorkspaceTreeEntry[];
+    /** ⚠️ 这条腿的 `total` 是**真·全量**(`all.length`),与 {@link WorkspaceSnapshotPage.total} 语义相反。 */
+    total: number;
+    /** 在场 = 还有下一页;把它当 `offset` 送回来。 */
+    nextOffset?: number;
+    [k: string]: unknown;
+}
 export declare class WorkspaceResource {
     private readonly t;
     constructor(t: Transport);
@@ -31,23 +65,14 @@ export declare class WorkspaceResource {
     list(sessionId: string, opts?: {
         limit?: number;
         signal?: AbortSignal;
-    }): Promise<{
-        snapshots: WorkspaceSnapshotRow[];
-        latest?: string;
-        total: number;
-    }>;
+    }): Promise<WorkspaceSnapshotPage>;
     /** `GET …/workspace/:key/tree` — 文件树(path 序稳定;limit 1..2000 默认 500 + offset 分页;
      *  `key="latest"` 别名可用)。`nextOffset` 在场=还有下一页。 */
     tree(sessionId: string, key: string, opts?: {
         limit?: number;
         offset?: number;
         signal?: AbortSignal;
-    }): Promise<{
-        key: string;
-        entries: WorkspaceTreeEntry[];
-        total: number;
-        nextOffset?: number;
-    }>;
+    }): Promise<WorkspaceTreePage>;
     /** `GET …/workspace/:key/file?path=` — 单文件字节(≤ capabilities.workspace.maxFileBytes,默认 8MiB)。
      *  超限=413 结构化信封([1894]①)⇒ typed {@link WorkspaceFileTooLargeError}(带 sizeBytes/limit)——
      *  web 渲「文件过大,下载查看」卡,archive 口是退路。 */

package/dist/resources/workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/resources/workspace.ts"],"names":[],"mappings":"AAAA;;;;;sEAKsE;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC,8EAA8E;IACxE,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9C,OAAO,CAAC;QAAE,SAAS,EAAE,oBAAoB,EAAE,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAKjF;sDACkD;IAC5C,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,kBAAkB,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAQ9F;;0CAEsC;IAChC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBjH;;mEAE+D;IACzD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;CAUlG"}
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../src/resources/workspace.ts"],"names":[],"mappings":"AAAA;;;;;sEAKsE;AACtE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AACD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AACD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,MAAM,EAAE,OAAO,CAAC;CACjB;AAED;;;;;yEAKyE;AACzE,MAAM,WAAW,qBAAqB;IACpC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,oBAAoB,EAAE,CAAC;IAClC,0EAA0E;IAC1E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;0DAIsD;IACtD,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED;yCACyC;AACzC,MAAM,WAAW,iBAAiB;IAChC,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,kBAAkB,EAAE,CAAC;IAC9B,0FAA0F;IAC1F,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC,8EAA8E;IACxE,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9C,OAAO,CAAC,qBAAqB,CAAC;IAKjC;sDACkD;IAC5C,IAAI,CACR,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC/D,OAAO,CAAC,iBAAiB,CAAC;IAQ7B;;0CAEsC;IAChC,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,aAAa,CAAC;IAoBjH;;mEAE+D;IACzD,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;CAUlG"}

package/dist/resources/workspace.js.map

@@ -1 +1 @@
-{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/resources/workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../../src/resources/workspace.ts"],"names":[],"mappings":"AAiEA,MAAM,OAAO,iBAAiB;IACC;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C,8EAA8E;IAC9E,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,IAA+C;QAE/C,MAAM,EAAE,GAAG,IAAI,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,aAAa,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACvI,CAAC;IAED;sDACkD;IAClD,KAAK,CAAC,IAAI,CACR,SAAiB,EACjB,GAAW,EACX,IAAgE;QAEhE,MAAM,CAAC,GAAG,IAAI,eAAe,EAAE,CAAC;QAChC,IAAI,IAAI,EAAE,KAAK,KAAK,SAAS;YAAE,CAAC,CAAC,GAAG,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;QAClE,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS;YAAE,CAAC,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC;QACrE,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,cAAc,kBAAkB,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACvK,CAAC;IAED;;0CAEsC;IACtC,KAAK,CAAC,IAAI,CAAC,SAAiB,EAAE,GAAW,EAAE,IAAY,EAAE,IAA+B;QACtF,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;YAC/B,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,cAAc,kBAAkB,CAAC,GAAG,CAAC,cAAc,kBAAkB,CAAC,IAAI,CAAC,EAAE;YAChI,MAAM,EAAE,0BAA0B;YAClC,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;QACH,kFAAkF;QAClF,iEAAiE;QACjE,wDAAwD;QACxD,2EAA2E;QAC3E,4BAA4B;QAC5B,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO;YACL,KAAK,EAAE,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,WAAW,EAAE,CAAC;YAC9C,WAAW,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,0BAA0B;YAC1E,MAAM,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,uBAAuB,CAAC,KAAK,MAAM;SAC5D,CAAC;IACJ,CAAC;IAED;;mEAE+D;IAC/D,KAAK,CAAC,OAAO,CAAC,SAAiB,EAAE,GAAW,EAAE,IAA+B;QAC3E,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC;YAC/B,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,gBAAgB,kBAAkB,CAAC,SAAS,CAAC,cAAc,kBAAkB,CAAC,GAAG,CAAC,UAAU;YAClG,MAAM,EAAE,mBAAmB;YAC3B,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;QACH,IAAI,CAAC,GAAG,CAAC,EAAE;YAAE,MAAM,MAAM,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAC/C,OAAO,GAAG,CAAC;IACb,CAAC;CACF"}

package/dist/sync.d.ts

@@ -11,8 +11,14 @@
  * entry id 是 uuidv7、**不是内容寻址**,而 wire 本身就收调用方给的 entries ⇒「同 id、异载荷」结构上完全可能。
  * 于是集合比较会把它判成 `identical`,entries **整段跳过**,调用方拿到"已同步"而目的端仍是自己那份内容。
  * 集合比较能精确回答的是「**id 集合**是否分叉」,**不能**回答「内容是否相同」—— 这两件事在这个契约里被
- * 长期混为一谈。真修需要内容摘要参与分类(方案 B:Phase A 加可选 `logDigest`,黑板 [1701]/[1702] 三端已对齐);
- * 在那之前,`basis`/`payloadVerified` 两个字段负责**不让调用方误读**(见 {@link PushSessionResult})。
+ * 长期混为一谈。
+ *
+ * ✅ **真修已接线(4.3.0)**:方案 B 的 `logDigest`(黑板 [1701]/[1702] 三端对齐)此前只在 server 落地,SDK 这一端
+ * 从未送过这个键 ⇒ `payloadVerified:true` 在本 SDK 上**结构性不可达**,而三处 JSDoc 把「SDK 的遗漏」写成了
+ * 「server 的现状」(「现值恒 `entry-ids`」/「现值恒 `false`」)。现在 {@link PushSessionOptions.logDigest} 会
+ * 透传到 Phase A,且**给了摘要就不再在本地短路 identical** —— 因为本地 dry-run 只比 id 集合,短路会把服务端
+ * 唯一能做内容判定的那一步跳掉。给了摘要 ⇒ 由 server 判:相等 ⇒ `basis:"entry-ids+digest"` + `payloadVerified:true`;
+ * 不等/不可比 ⇒ 开 staging 走完整同步(安全方向)。不给 ⇒ 与 4.2.0 逐字节同行为。
  *
  * No I/O, no dependencies — a byte-faithful copy so the local peer and the cloud agree on the relation without a
  * round-trip. `srcIds`/`dstIds` are OLDEST-FIRST so the fork `commonAncestor` (the deepest shared id) and the
@@ -33,6 +39,19 @@ export interface PushSessionOptions {
     /** Echoed into import Phase A. REQUIRED to apply a `fork`/`stale` push (dst history would be lost);
      *  never defaulted — the caller must have shown the divergence to a human first. */
     resolution?: "overwrite-dst";
+    /** 🔴 源端整条 entry 日志的**内容摘要**(core `sessionLogDigest`,scheme `sema-log-v3`;server 这条腿的
+     *  core 下限是 ^1.416.0)。SDK 零运行时依赖、**不自己算** —— 手里已有 core 的调用方透传它,没有的省略。
+     *
+     *  给了它会改变两件事(缺省不给 = 与 4.2.0 逐字节同行为):
+     *   ① **本地 dry-run 的 `identical` 短路被跳过** —— 本地 plan 只比 id 集合,短路会把服务端唯一能做内容
+     *      判定的那一步跳掉。给了摘要就一路走到 Phase A,让 server 拿它自己的日志算一次摘要来判。
+     *   ② Phase A 回的 {@link PushSessionResult.payloadVerified} 才可能为 `true`(相等 ⇒ 真短路);
+     *      不等或不可比 ⇒ server 开 staging 走完整同步 —— 「同 id 异载荷」的分叉会话不再被判成已同步。 */
+    logDigest?: string;
+    /** Phase B 用**真流式**请求体(`ReadableStream`,常量内存)而不是先在内存里拼完整条 NDJSON。
+     *  opt-in:流式请求体要求运行时 `fetch` 支持 `duplex:"half"`(Node ≥18 undici / Deno 有;polyfill 未必)。
+     *  详见 {@link import("./resources/session-sync.js").SessionSyncResource.importEntries}。 */
+    stream?: boolean;
     signal?: AbortSignal;
 }
 export interface PushSessionResult {
@@ -42,11 +61,14 @@ export interface PushSessionResult {
      *  ⚠️ 后一种情况下**不能**推断"dst 已逐字持有" —— 这个类型此前的注释就是这么写的,而它不成立
      *  (见文件顶注的纠正)。要判"内容真的同步了",看 {@link payloadVerified}。 */
     pushed: boolean;
-    /** 🔴 分类**判据**(server ≥1.277 / 本地 dry-run 同值)。现值恒 `"entry-ids"`:分类只比 entry id 集合。
+    /** 🔴 分类**判据**(server ≥1.277 / 本地 dry-run 同值)。两个真值:
+     *   - `"entry-ids"` —— 只比了 entry id 集合,**内容未校验**(没送 {@link PushSessionOptions.logDigest} 时的形);
+     *   - `"entry-ids+digest"` —— 调用方送了可比摘要且相等,**内容真的验过**。
      *  开集串,未知值按"未验证内容"降级。仅在 `identical` 这类**跳过写入**的路径上有值 —— 真走完 Phase B 时
      *  entries 是实际传输过去的,不存在"判据"问题,那时本字段缺席。 */
-    basis?: "entry-ids" | (string & {});
-    /** 🔴 是否**验证过载荷**。现值恒 `false`(见 {@link basis})。
+    basis?: "entry-ids" | "entry-ids+digest" | (string & {});
+    /** 🔴 是否**验证过载荷**。要它为 `true`,调用方必须送 {@link PushSessionOptions.logDigest}(4.3.0 起可送);
+     *  不送则恒 `false` —— 那是判据的如实回声,不是 bug。
      *  ⚠️ **缺席 ≠ 已验证**:老 server(<1.277)不带这个字段而判据同样只有 id 集合;真走完 Phase B 时也缺席
      *  (那时内容确实传过去了)。所以要表达"内容未被校验"请配合 `relation` 一起读:
      *  `relation === "identical" && payloadVerified !== true` 才是"跳过了写入且未校验内容"。 */
@@ -67,8 +89,13 @@ export interface PushSessionResult {
 /**
  * PUSH one session from peer `src` into peer `dst` (same-id, cross-backend):
  *   src manifest → dst dry-run plan (§7 classify) → [conflict? return, don't write] → blobs (content-addressed
- *   PUTs) → import Phase A (small metadata + lease/active-run guards) → Phase B (pipe the src entry stream
- *   straight into the staged import — never materializes the whole log in memory beyond the NDJSON body).
+ *   PUTs) → import Phase A (small metadata + lease/active-run guards) → Phase B (the src entry stream into the
+ *   staged import).
+ *
+ * 🔴 Phase B memory (corrected 4.3.0): by default the NDJSON body is BUILT IN MEMORY first — peak = the whole log.
+ * This module used to claim the opposite ("never materializes the whole log in memory beyond the NDJSON body") and
+ * `pullSessionBundle`'s "unlike the push pipe" contrast was written against that false premise. Pass
+ * {@link PushSessionOptions.stream `stream:true`} for the constant-memory streaming body.
  *
  * Conflict contract (③): a `fork`/`stale` seen at plan time is RETURNED (`{pushed:false, conflict}`) so the
  * caller can render the divergence; a TOCTOU flip after the plan (dst advanced mid-push) THROWS the typed
@@ -92,7 +119,9 @@ export interface PulledSession {
 /**
  * PULL one session OUT of peer `src` into memory (manifest + full entry log [+ blobs]) for callers that land
  * the state outside an engine — e.g. the sema shell converting entries into its CC-format `<id>.jsonl`.
- * 🔴 This MATERIALIZES the whole entry log (unlike the push pipe) — the caller owns the memory trade-off.
+ * 🔴 This MATERIALIZES the whole entry log — the caller owns the memory trade-off. (Until 4.3.0 this line read
+ * "unlike the push pipe"; that contrast was FALSE — the push path also built the whole NDJSON body in memory.
+ * It now holds only against `pushSessionBundle(..., {stream:true})`.)
  * A truncated entry stream throws SyncTruncatedError (the NDJSON trailer guard) — never a silently short log.
  */
 export declare function pullSessionBundle(src: SessionSyncPeer, sessionId: string, opts?: PullSessionOptions): Promise<PulledSession>;

package/dist/sync.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,oBAAoB,EAEpB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;2GAC2G;AAC3G,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,YAAY,CAkCrG;AAoBD,gHAAgH;AAChH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC;wFACoF;IACpF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,gHAAgH;IAChH,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IACnC;;4DAEwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB;;8CAE0C;IAC1C,KAAK,CAAC,EAAE,WAAW,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACpC;;;kFAG8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;8GAC0G;IAC1G,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,QAAQ,EAAE,eAAe,CAAC;IAC1B;sFACkF;IAClF,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAsE5B;AAED,MAAM,WAAW,kBAAkB;IACjC;6GACyG;IACzG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,wEAAwE;IACxE,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAChC;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC,EAC5D,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAyD5B"}
+{"version":3,"file":"sync.d.ts","sourceRoot":"","sources":["../src/sync.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EACb,oBAAoB,EAEpB,YAAY,EACb,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AAEvE;2GAC2G;AAC3G,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,YAAY,CAkCrG;AAoBD,gHAAgH;AAChH,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE;QAAE,IAAI,EAAE,mBAAmB,CAAA;KAAE,CAAC;CACzC;AAED,MAAM,WAAW,kBAAkB;IACjC;wFACoF;IACpF,UAAU,CAAC,EAAE,eAAe,CAAC;IAC7B;;;;;;;0EAOsE;IACtE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;8FAE0F;IAC1F,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,iBAAiB;IAChC,gHAAgH;IAChH,QAAQ,EAAE,YAAY,CAAC,UAAU,CAAC,CAAC;IACnC;;4DAEwD;IACxD,MAAM,EAAE,OAAO,CAAC;IAChB;;;;8CAI0C;IAC1C,KAAK,CAAC,EAAE,WAAW,GAAG,kBAAkB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;IACzD;;;;kFAI8E;IAC9E,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;8GAC0G;IAC1G,QAAQ,CAAC,EAAE,oBAAoB,CAAC;IAChC,iEAAiE;IACjE,UAAU,EAAE,MAAM,CAAC;IACnB,6FAA6F;IAC7F,WAAW,EAAE,MAAM,CAAC;IACpB,mGAAmG;IACnG,QAAQ,EAAE,eAAe,CAAC;IAC1B;sFACkF;IAClF,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CA0E5B;AAED,MAAM,WAAW,kBAAkB;IACjC;6GACyG;IACzG,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,eAAe,CAAC;IAC1B,wEAAwE;IACxE,MAAM,EAAE,aAAa,CAAC;IACtB,6EAA6E;IAC7E,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,eAAe,EACpB,SAAS,EAAE,MAAM,EACjB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,aAAa,CAAC,CAyBxB;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAC,EAC5D,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CA8D5B"}

package/dist/sync.js

@@ -36,8 +36,13 @@ export function classifySyncRelationshipByIds(srcIds, dstIds) {
 /**
  * PUSH one session from peer `src` into peer `dst` (same-id, cross-backend):
  *   src manifest → dst dry-run plan (§7 classify) → [conflict? return, don't write] → blobs (content-addressed
- *   PUTs) → import Phase A (small metadata + lease/active-run guards) → Phase B (pipe the src entry stream
- *   straight into the staged import — never materializes the whole log in memory beyond the NDJSON body).
+ *   PUTs) → import Phase A (small metadata + lease/active-run guards) → Phase B (the src entry stream into the
+ *   staged import).
+ *
+ * 🔴 Phase B memory (corrected 4.3.0): by default the NDJSON body is BUILT IN MEMORY first — peak = the whole log.
+ * This module used to claim the opposite ("never materializes the whole log in memory beyond the NDJSON body") and
+ * `pullSessionBundle`'s "unlike the push pipe" contrast was written against that false premise. Pass
+ * {@link PushSessionOptions.stream `stream:true`} for the constant-memory streaming body.
  *
  * Conflict contract (③): a `fork`/`stale` seen at plan time is RETURNED (`{pushed:false, conflict}`) so the
  * caller can render the divergence; a TOCTOU flip after the plan (dst advanced mid-push) THROWS the typed
@@ -50,7 +55,9 @@ export async function pushSessionBundle(src, dst, sessionId, opts) {
     // Dry-run classify BEFORE any write (and before any blob upload — don't spend bandwidth on a push the
     // conflict gate will refuse).
     const rel = await dst.sessions.sync.plan(sessionId, { entryIds: manifest.entryIds }, sopts);
-    if (rel.relation === "identical") {
+    // 🔴 只在**没有内容摘要**时本地短路 identical:本地 dry-run 只比 id 集合,短路会把服务端唯一能做内容判定的
+    // 那一步(Phase A 拿 logDigest 与目的端日志摘要对比)整个跳掉 —— 「同 id 异载荷」就永远被判成已同步。
+    if (rel.relation === "identical" && opts?.logDigest === undefined) {
         // 本地 dry-run 判 identical ⇒ 同样只比了 id 集合,如实标注(否则调用方在这条路上连字段都看不到)
         return { relation: "identical", pushed: true, entryCount: 0, blobsPushed: 0, manifest, plan: rel, basis: "entry-ids", payloadVerified: false };
     }
@@ -88,6 +95,7 @@ export async function pushSessionBundle(src, dst, sessionId, opts) {
         policy: manifest.policy,
         anchors: manifest.anchors,
         ...(opts?.resolution ? { resolution: opts.resolution } : {}),
+        ...(opts?.logDigest !== undefined ? { logDigest: opts.logDigest } : {}),
     }, sopts);
     if (!staged.stagingId) {
         // Phase A itself classified `identical` (raced to equality) — dst already holds the log.
@@ -99,14 +107,17 @@ export async function pushSessionBundle(src, dst, sessionId, opts) {
             ...(staged.payloadVerified !== undefined ? { payloadVerified: staged.payloadVerified } : {}),
         };
     }
-    // Phase B — pipe the src entry stream straight into the staged import (async-iterable in, NDJSON out).
-    const committed = await dst.sessions.sync.importEntries(sessionId, staged.stagingId, src.sessions.sync.entries(sessionId, undefined, sopts), sopts);
+    // Phase B — the src entry stream into the staged import (async-iterable in, NDJSON out; `stream:true` makes it
+    // a real constant-memory pipe, see PushSessionOptions.stream).
+    const committed = await dst.sessions.sync.importEntries(sessionId, staged.stagingId, src.sessions.sync.entries(sessionId, undefined, sopts), { ...sopts, ...(opts?.stream === true ? { stream: true } : {}) });
     return { relation: committed.relation, pushed: true, entryCount: manifest.entryCount, blobsPushed, manifest, plan: rel };
 }
 /**
  * PULL one session OUT of peer `src` into memory (manifest + full entry log [+ blobs]) for callers that land
  * the state outside an engine — e.g. the sema shell converting entries into its CC-format `<id>.jsonl`.
- * 🔴 This MATERIALIZES the whole entry log (unlike the push pipe) — the caller owns the memory trade-off.
+ * 🔴 This MATERIALIZES the whole entry log — the caller owns the memory trade-off. (Until 4.3.0 this line read
+ * "unlike the push pipe"; that contrast was FALSE — the push path also built the whole NDJSON body in memory.
+ * It now holds only against `pushSessionBundle(..., {stream:true})`.)
  * A truncated entry stream throws SyncTruncatedError (the NDJSON trailer guard) — never a silently short log.
  */
 export async function pullSessionBundle(src, sessionId, opts) {
@@ -150,7 +161,8 @@ export async function importSessionBundle(dst, pulled, opts) {
     const { manifest, bundle, blobs } = pulled;
     const sessionId = bundle.sessionId;
     const rel = await dst.sessions.sync.plan(sessionId, { entryIds: manifest.entryIds }, sopts);
-    if (rel.relation === "identical") {
+    // 与 pushSessionBundle 同判据:给了 logDigest 就不本地短路,交给 Phase A 做内容判定。
+    if (rel.relation === "identical" && opts?.logDigest === undefined) {
         // 本地 dry-run 判 identical ⇒ 同样只比了 id 集合,如实标注(否则调用方在这条路上连字段都看不到)
         return { relation: "identical", pushed: true, entryCount: 0, blobsPushed: 0, manifest, plan: rel, basis: "entry-ids", payloadVerified: false };
     }
@@ -185,6 +197,7 @@ export async function importSessionBundle(dst, pulled, opts) {
         policy: bundle.policy,
         anchors: bundle.anchors,
         ...(opts?.resolution ? { resolution: opts.resolution } : {}),
+        ...(opts?.logDigest !== undefined ? { logDigest: opts.logDigest } : {}),
     }, sopts);
     if (!staged.stagingId) {
         // 透传服务端的判据 —— cli 黑板 [1704] 抓到的管道缺口:字段只加在 `ImportStaged` 上、这一层没穿透,
@@ -195,7 +208,10 @@ export async function importSessionBundle(dst, pulled, opts) {
             ...(staged.payloadVerified !== undefined ? { payloadVerified: staged.payloadVerified } : {}),
         };
     }
-    const committed = await dst.sessions.sync.importEntries(sessionId, staged.stagingId, bundle.entries, sopts);
+    const committed = await dst.sessions.sync.importEntries(sessionId, staged.stagingId, bundle.entries, {
+        ...sopts,
+        ...(opts?.stream === true ? { stream: true } : {}),
+    });
     return { relation: committed.relation, pushed: true, entryCount: bundle.entries.length, blobsPushed, manifest, plan: rel };
 }
 //# sourceMappingURL=sync.js.map