@sema-agent/sdk 0.0.75 → 0.0.76

package/dist/resources/tool-approvals.d.ts

@@ -1,27 +1,80 @@
+/** tool-approvals — [830]① live-stream TOOL-APPROVAL HITL (server 1.191+ `ToolApprovalCoordinator`, gated on
+ *  `TOOL_APPROVAL_ENABLED`; server 1.214 tool-approval.js:113 `respond`). The THIRD sibling of
+ *  {@link import("./questions.js").QuestionsResource} / {@link import("./elicitations.js").ElicitationsResource}:
+ *  elicitation = an inbound-MCP-server ask, question = the agent's own AskUserQuestion, THIS = the ENGINE's
+ *  permission gate ("may I run this tool?") surfaced to a live human — the suspended↔overlay bridge's decide面.
+ *
+ *  🔴 LIVE-ONLY + SAME-REPLICA (the `steer()`-class of HITL, NOT the durable approvals/checkpoint class —
+ *  that is {@link import("./approvals.js").ApprovalsResource}): the parked ask is an in-memory promise with a
+ *  5-min TTL (server DEFAULT_APPROVAL_TTL_MS), so a respond that lands after settle / after the TTL / on
+ *  another replica finds nothing → 404. An unanswered ask fail-closes to DENY engine-side (the run proceeds;
+ *  it never hangs).
+ *
+ *  🔴 The `tool_approval` / `tool_approval_complete` FRAMES are NOT `AgentEvent` arms — they interleave on the
+ *  live token stream exactly like `question`/`elicitation` frames. Tail them off `tasks.streamRaw`, dispatch on
+ *  the SSE `event:` name (the payload echoes `type`), parse with {@link ToolApprovalFrame}, then decide via
+ *  {@link ToolApprovalsResource.respond}.
+ *
+ *  🔴 UNTRUSTED for display: `message`/`args` are service secret-redacted (+ args size-bounded, >16 KiB →
+ *  `argsOmitted:true`) but remain model/tool-authored — render only, never re-feed to a model. */
 import type { Transport } from "../transport.js";
+/** The human's decision (server `parseToolApprovalDecision`, tool-approval.js:15 — closed 3-word set; anything
+ *  else is a 400). `allow_session` = allow AND remember for this session's category (fs-write tools share ONE
+ *  category: approving Write covers Edit/NotebookEdit; other tools are per-tool) — the CC "don't ask again this
+ *  session" semantic. */
 export type ToolApprovalDecision = "allow" | "allow_session" | "deny";
+/** A live tool-approval frame interleaved on the run's `tasks.streamRaw` connection (server `ToolApprovalFrame`,
+ *  tool-approval.d.ts). `type` IS the SSE `event:` name AND is echoed in the payload. The shell renders the
+ *  `tool_approval` frame as an allow/deny dialog and dismisses it on `tool_approval_complete`. */
 export interface ToolApprovalFrame {
     type: "tool_approval" | "tool_approval_complete";
+    /** The id to echo back to {@link ToolApprovalsResource.respond}. */
     approvalId: string;
+    /** "tool_approval" only: the tool awaiting permission. */
     toolName?: string;
+    /** "tool_approval" only: the engine's ask text, secret-redacted. UNTRUSTED — display only. */
     message?: string;
+    /** "tool_approval" only: the pending call's args, redacted + size-bounded. Absent when `argsOmitted`. */
     args?: unknown;
+    /** "tool_approval" only: args exceeded the 16 KiB bound (or failed to serialize) → omitted, render a stub. */
     argsOmitted?: boolean;
+    /** "tool_approval_complete" only: how it settled (dialog dismiss reason). `expired` = TTL / abort / emit
+     *  failure — the engine got the fail-closed deny. Cosmetic. */
     outcome?: "allowed" | "denied" | "expired";
     [k: string]: unknown;
 }
+/** The 200 ack from a successful respond (server tool-approval.js:133 — exact shape, `decision` echoed). */
 export interface ToolApprovalRespondAck {
     approvalId: string;
     delivery: "applied";
     decision: ToolApprovalDecision;
+    /** server 1.239([1392]②):allow_session 时诚实回显 remember 是否**真记了**(true=grant 落桥内店;
+     *  false=无 sessionId 记不了,壳不得渲染「本 session 全放行」)。非 allow_session 决策=字段省略;
+     *  旧 server=恒缺席(tolerate-absent)。 */
     rememberApplied?: boolean;
+    /** server 1.241([1458] ctrl+g 编辑放行):allow 族带 `updatedInput` 时=server 已把编辑后的 args 透传给
+     *  引擎(是否被消费取决于 core OnAsk 对象臂是否到位——诚实措辞:forwarded≠applied)。deny/未带编辑/
+     *  旧 server=字段省略(tolerate-absent)。 */
     updatedInputForwarded?: boolean;
 }
 export declare class ToolApprovalsResource {
     private readonly t;
     constructor(t: Transport);
+    /** POST /v1/tool-approvals/:id/respond — settle a parked LIVE tool-approval gate with the human's decision.
+     *  The engine's suspended tool call resumes (allow) or is refused (deny) on the still-open task connection.
+     *
+     *  🔴 OWNER-GATED with a 404 (NO existence oracle, server tool-approval.js:118): a non-owner AND an
+     *  unknown/settled/expired/wrong-replica id both get the same 404 — never branch existence off the status.
+     *  A malformed body (`decision` outside the 3-word set) is a 400 (existence-independent). A worker without
+     *  `TOOL_APPROVAL_ENABLED` → 501 (probe `capabilities.toolApproval` instead of trial-by-501); missing
+     *  principal on a require-principal worker → 401.
+     *
+     *  Not a submit / not idempotent (it settles an in-flight promise exactly once) → NO SDK retry. */
     respond(id: string, body: {
         decision: ToolApprovalDecision;
+        /** server 1.241([1458] ctrl+g「edit script in $EDITOR」):allow 族可带编辑后的 tool args(**整体替换**形,
+         *  非 patch)。deny 上 server 静默忽略;旧 server 同样忽略未知键(前向兼容)。透传与否看 ack 的
+         *  `updatedInputForwarded`。 */
         updatedInput?: unknown;
     }, opts?: {
         signal?: AbortSignal;

package/dist/resources/tool-approvals.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-approvals.d.ts","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAMjD,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,eAAe,GAAG,MAAM,CAAC;AAKtE,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,GAAG,wBAAwB,CAAC;IAEjD,UAAU,EAAE,MAAM,CAAC;IAEnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,IAAI,CAAC,EAAE,OAAO,CAAC;IAEf,WAAW,CAAC,EAAE,OAAO,CAAC;IAGtB,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAGD,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,oBAAoB,CAAC;IAI/B,eAAe,CAAC,EAAE,OAAO,CAAC;IAI1B,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAYnC,OAAO,CACX,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QACJ,QAAQ,EAAE,oBAAoB,CAAC;QAI/B,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,EACD,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9B,OAAO,CAAC,sBAAsB,CAAC;CAQnC"}
+{"version":3,"file":"tool-approvals.d.ts","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;kGAkBkG;AAClG,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;yBAGyB;AACzB,MAAM,MAAM,oBAAoB,GAAG,OAAO,GAAG,eAAe,GAAG,MAAM,CAAC;AAEtE;;kGAEkG;AAClG,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,GAAG,wBAAwB,CAAC;IACjD,oEAAoE;IACpE,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,8FAA8F;IAC9F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8GAA8G;IAC9G,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;mEAC+D;IAC/D,OAAO,CAAC,EAAE,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC3C,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACtB;AAED,4GAA4G;AAC5G,MAAM,WAAW,sBAAsB;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,SAAS,CAAC;IACpB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B;;yCAEqC;IACrC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;0CAEsC;IACtC,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,qBAAa,qBAAqB;IACpB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;;;;;uGASmG;IAC7F,OAAO,CACX,EAAE,EAAE,MAAM,EACV,IAAI,EAAE;QACJ,QAAQ,EAAE,oBAAoB,CAAC;QAC/B;;uCAE+B;QAC/B,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,EACD,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAC9B,OAAO,CAAC,sBAAsB,CAAC;CAQnC"}

package/dist/resources/tool-approvals.js

@@ -3,6 +3,16 @@ export class ToolApprovalsResource {
     constructor(t) {
         this.t = t;
     }
+    /** POST /v1/tool-approvals/:id/respond — settle a parked LIVE tool-approval gate with the human's decision.
+     *  The engine's suspended tool call resumes (allow) or is refused (deny) on the still-open task connection.
+     *
+     *  🔴 OWNER-GATED with a 404 (NO existence oracle, server tool-approval.js:118): a non-owner AND an
+     *  unknown/settled/expired/wrong-replica id both get the same 404 — never branch existence off the status.
+     *  A malformed body (`decision` outside the 3-word set) is a 400 (existence-independent). A worker without
+     *  `TOOL_APPROVAL_ENABLED` → 501 (probe `capabilities.toolApproval` instead of trial-by-501); missing
+     *  principal on a require-principal worker → 401.
+     *
+     *  Not a submit / not idempotent (it settles an in-flight promise exactly once) → NO SDK retry. */
     async respond(id, body, opts) {
         return this.t.request({
             method: "POST",

package/dist/resources/tool-approvals.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-approvals.js","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"AA+DA,MAAM,OAAO,qBAAqB;IACH;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAY7C,KAAK,CAAC,OAAO,CACX,EAAU,EACV,IAMC,EACD,IAA+B;QAE/B,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAyB;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,sBAAsB,kBAAkB,CAAC,EAAE,CAAC,UAAU;YAC5D,IAAI;YACJ,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;IACL,CAAC;CACF"}
+{"version":3,"file":"tool-approvals.js","sourceRoot":"","sources":["../../src/resources/tool-approvals.ts"],"names":[],"mappings":"AA+DA,MAAM,OAAO,qBAAqB;IACH;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C;;;;;;;;;uGASmG;IACnG,KAAK,CAAC,OAAO,CACX,EAAU,EACV,IAMC,EACD,IAA+B;QAE/B,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAyB;YAC5C,MAAM,EAAE,MAAM;YACd,IAAI,EAAE,sBAAsB,kBAAkB,CAAC,EAAE,CAAC,UAAU;YAC5D,IAAI;YACJ,MAAM,EAAE,IAAI,EAAE,MAAM;SACrB,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/resources/trace.d.ts

@@ -1,8 +1,14 @@
+/** trace — the "工作区" data source (SERVICE-CORE-CONTEXT §3.5): full per-task turn trace = the action
+ *  timeline; artifacts (diff/files/git-push) = the deliverable. Needs a SESSION_BACKEND=tidb worker.
+ *  A web workspace view is built ENTIRELY from this — keep it the SHARED model for all doors. */
 import type { Transport } from "../transport.js";
 import type { Artifact, TaskSummary, TraceStreamEvent, TraceTurn } from "../types.js";
 export declare class TraceResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /v1/tasks — list runs. Envelope `{ tasks, nextCursor? }` (key `tasks`, pinned). `?jobId=`
+     *  groups one logical job's runs (LIVE, [6]); `?source=` filters by credential-derived system ([40]);
+     *  also `?status=`, `?limit=` (default 50, max 100). */
     list(opts?: {
         jobId?: string;
         status?: string;
@@ -15,6 +21,8 @@ export declare class TraceResource {
         tasks: TaskSummary[];
         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. */
     sourceSummary(opts?: {
         sinceSec?: number;
         signal?: AbortSignal;
@@ -25,6 +33,8 @@ 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. */
     turns(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<{
@@ -32,9 +42,22 @@ export declare class TraceResource {
         nextCursor?: string;
         retainedFrom?: number;
     }>;
+    /** 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). */
     artifacts(taskId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Artifact[]>;
+    /** GET /v1/tasks/:id/stream — the workspace LIVE timeline (`streamTaskTrace` + `mapTraceEvent`, server.ts).
+     *  RESUMABLE SSE with a DISTINCT vocabulary from `runs.events`/AgentEvent: the durable log is BLOCK-grained,
+     *  so each frame is a `block-content-delta` / `block-thinking-delta` / `tool-call` / `tool-result` / `turn` /
+     *  `done` / `error` delta the client appends (see `TraceStreamEvent`). The FIRST frame is `meta`
+     *  `{version, mode, resumeFrom}`. Each frame's `id:` = the durable `task_event.seq`; on a window eviction the
+     *  server returns 416 (`{retainedFrom}`) and this reader transparently resumes from `retainedFrom` (the
+     *  consumer should full-sync the gap via `trace.turns`). `heartbeat` keep-alives are swallowed (never yielded).
+     *
+     *  ⚠️ This is NOT `runs.events` (which yields the typed `AgentEvent` union from `/v1/runs/:id/events`). Use this
+     *  for the workspace/trace VIEW; use `runs.events` for the durable run lifecycle stream. A `done` with
+     *  `data.suspended === true` means the run PAUSED on HITL (not completed). */
     stream(taskId: string, opts?: {
         signal?: AbortSignal;
         lastEventId?: string;

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

@@ -1 +1 @@
-{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/resources/trace.ts"],"names":[],"mappings":"AAGA,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;IAKnC,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;IAchM,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAOzI,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;IAMnI,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAoB9E,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;gGAC4F;IACtF,aAAa,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,EAAE,CAAA;KAAE,CAAC;IAK/I;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,QAAQ,EAAE,CAAC;IASrF;;;;;;;;;;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

@@ -4,6 +4,9 @@ export class TraceResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /v1/tasks — list runs. Envelope `{ tasks, nextCursor? }` (key `tasks`, pinned). `?jobId=`
+     *  groups one logical job's runs (LIVE, [6]); `?source=` filters by credential-derived system ([40]);
+     *  also `?status=`, `?limit=` (default 50, max 100). */
     async list(opts) {
         const q = new URLSearchParams();
         if (opts?.jobId)
@@ -21,13 +24,19 @@ export class TraceResource {
         const qs = q.toString();
         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. */
     async sourceSummary(opts) {
         const qs = opts?.sinceSec ? `?sinceSec=${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. */
     async turns(taskId, opts) {
         return this.t.request({ method: "GET", path: `/v1/tasks/${encodeURIComponent(taskId)}/turns`, 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). */
     async artifacts(taskId, opts) {
         const r = await this.t.request({
             method: "GET",
@@ -36,6 +45,17 @@ export class TraceResource {
         });
         return r.artifacts;
     }
+    /** GET /v1/tasks/:id/stream — the workspace LIVE timeline (`streamTaskTrace` + `mapTraceEvent`, server.ts).
+     *  RESUMABLE SSE with a DISTINCT vocabulary from `runs.events`/AgentEvent: the durable log is BLOCK-grained,
+     *  so each frame is a `block-content-delta` / `block-thinking-delta` / `tool-call` / `tool-result` / `turn` /
+     *  `done` / `error` delta the client appends (see `TraceStreamEvent`). The FIRST frame is `meta`
+     *  `{version, mode, resumeFrom}`. Each frame's `id:` = the durable `task_event.seq`; on a window eviction the
+     *  server returns 416 (`{retainedFrom}`) and this reader transparently resumes from `retainedFrom` (the
+     *  consumer should full-sync the gap via `trace.turns`). `heartbeat` keep-alives are swallowed (never yielded).
+     *
+     *  ⚠️ This is NOT `runs.events` (which yields the typed `AgentEvent` union from `/v1/runs/:id/events`). Use this
+     *  for the workspace/trace VIEW; use `runs.events` for the durable run lifecycle stream. A `done` with
+     *  `data.suspended === true` means the run PAUSED on HITL (not completed). */
     async *stream(taskId, opts) {
         let first = opts?.lastEventId;
         const frames = parseFrameStream((lastEventId) => {
@@ -50,11 +70,16 @@ export class TraceResource {
             if (opts?.signal)
                 o.signal = opts.signal;
             return this.t.openStream(o);
-        }, (f) => f.event === "done" || f.event === "error", opts?.signal ? { signal: opts.signal } : undefined);
+        }, 
+        // terminal frames: the run ended (`done`) or hard-failed (`error`). A `done{suspended:true}` (HITL pause)
+        // is ALSO terminal for THIS stream — the run is no longer producing trace deltas until resumed.
+        (f) => f.event === "done" || f.event === "error", opts?.signal ? { signal: opts.signal } : undefined);
         for await (const f of frames) {
+            // server keep-alives are `event: heartbeat\ndata: {}` (a real data line, NOT a bare `:` comment) — swallow
+            // by NAME; also drop any genuinely data-less frame (a bare `:` comment beat).
             if (f.event === "heartbeat" || !f.data)
                 continue;
-            const data = JSON.parse(f.data);
+            const data = JSON.parse(f.data); // SyntaxError = contract breach → rethrown by reader
             const ev = { event: (f.event ?? "message"), data };
             if (f.id)
                 ev.id = f.id;

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/usage.d.ts

@@ -1,31 +1,52 @@
+/** usage — §cost/usage 面板的**只读**数据源（service `GET /v1/usage`,实测形态 the pinned wire contract）。
+ *
+ *  `get` = `GET /v1/usage` → `UsageInfo`（per-principal 成本配额 + 单任务上限,worker 据 request principal 自算）。
+ *  CLI `/cost` `/usage` 面板 + 门B 用量条渲它显真实「已用/剩余/上限」（取代静态占位）。
+ *
+ *  🔴 owner-scoped:用量按 request principal（BFF 注）算,client 不传 scope。失败由 caller fail-safe
+ *     （`{enabled:false,...}` → 面板降级显「无配额数据」,同 models 范式;绝不阻断）。
+ *  🔴 只读 inspect:client 不据此放行/拦截（配额 enforcement 100% 在 worker;面板只展示）。 */
 import type { Transport } from "../transport.js";
 import type { UsageInfo } from "../types.js";
 export declare class UsageResource {
     private readonly t;
     constructor(t: Transport);
+    /** GET /v1/usage — per-principal 成本配额 + 单任务上限。无配额时 `{enabled:false, windowSec?, maxTask*}`。 */
     get(opts?: {
         signal?: AbortSignal;
     }): Promise<UsageInfo>;
+    /** GET /v1/usage/summary — 窗内用量总账(server ≥1.20x usage-analytics 面,server.ts /v1/usage/ 分发实拆)。
+     *  `from`/`to` = ISO-8601 或 epoch-ms(缺省近 7 天);JWT 主体强制 owner=本人,fleet 凭证可传 `principal`。
+     *  501 = 无 run store;`truncated:true` = 扫描窗被截。 */
     summary(opts?: UsageAnalyticsParams & {
         signal?: AbortSignal;
     }): Promise<UsageSummary>;
+    /** GET /v1/usage/series — 时序(UTC 桶,空桶不发行——消费方按需补零)。metric=tasks|tokensIn|tokensOut|costUsd
+     *  (缺省 costUsd),granularity=hour|day(缺省 day)。 */
     series(opts?: UsageAnalyticsParams & {
         metric?: UsageMetric;
         granularity?: UsageGranularity;
         signal?: AbortSignal;
     }): Promise<UsageSeries>;
+    /** GET /v1/usage/breakdown — 维度分桶。dimension=principal|model(缺省 principal;JWT 主体的 principal 桶
+     *  只会是本人一桶——owner 已强制,语义自然成立)。 */
     breakdown(opts?: UsageAnalyticsParams & {
         dimension?: UsageDimension;
         signal?: AbortSignal;
     }): Promise<UsageBreakdown>;
 }
+/** usage-analytics 公共窗口参数(server 校验 from<to,坏形 400)。 */
 export interface UsageAnalyticsParams {
+    /** ISO-8601 或 epoch-ms;缺省 = now-7d。 */
     from?: string | number;
+    /** ISO-8601 或 epoch-ms;缺省 = now。 */
     to?: string | number;
+    /** fleet 凭证专用(JWT 主体被强制 owner=本人,该参数被忽略)。 */
     principal?: string;
 }
 export type UsageMetric = "tasks" | "tokensIn" | "tokensOut" | "costUsd";
 export type UsageGranularity = "hour" | "day";
+/** 窗内总账(server usage-analytics.ts UsageTotals 实拆;estimated=有旧行走了 tokens fallback,token 口径部分估算)。 */
 export interface UsageTotals {
     tasks: number;
     tokensIn: number;

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

@@ -1 +1 @@
-{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/resources/usage.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAGnC,GAAG,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAOxD,OAAO,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAMtF,MAAM,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAS1I,SAAS,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,SAAS,CAAC,EAAE,cAAc,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;CAK7H;AAGD,MAAM,WAAW,oBAAoB;IAEnC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAEvB,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAErB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AACzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,CAAC;AAE9C,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE;AAC9I,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE;AACxG,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,WAAW,CAAC;AACzD,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAC5I,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,CAAC,CAAA;CAAE,CAAC;AAC9H,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,CAAC"}
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/resources/usage.ts"],"names":[],"mappings":"AAAA;;;;;;;yEAOyE;AACzE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC,+FAA+F;IACzF,GAAG,CAAC,IAAI,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAI9D;;sDAEkD;IAC5C,OAAO,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,YAAY,CAAC;IAI5F;qDACiD;IAC3C,MAAM,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,WAAW,CAAC,EAAE,gBAAgB,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAOhJ;sCACkC;IAC5B,SAAS,CAAC,IAAI,CAAC,EAAE,oBAAoB,GAAG;QAAE,SAAS,CAAC,EAAE,cAAc,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,cAAc,CAAC;CAK7H;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB,oCAAoC;IACpC,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACrB,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AACD,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,UAAU,GAAG,WAAW,GAAG,SAAS,CAAC;AACzE,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,KAAK,CAAC;AAC9C,mGAAmG;AACnG,MAAM,WAAW,WAAW;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE;AAC9I,MAAM,WAAW,eAAe;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;CAAE;AACxG,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,WAAW,CAAC;AACzD,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,WAAW,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,KAAK,CAAC;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CAAE,CAAC;AAC5I,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG;IAAE,SAAS,EAAE,cAAc,CAAC;IAAC,SAAS,EAAE,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,WAAW,CAAC,CAAA;CAAE,CAAC;AAC9H,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,OAAO,CAAC"}

package/dist/resources/usage.js

@@ -3,12 +3,18 @@ export class UsageResource {
     constructor(t) {
         this.t = t;
     }
+    /** GET /v1/usage — per-principal 成本配额 + 单任务上限。无配额时 `{enabled:false, windowSec?, maxTask*}`。 */
     async get(opts) {
         return this.t.request({ method: "GET", path: "/v1/usage", signal: opts?.signal });
     }
+    /** GET /v1/usage/summary — 窗内用量总账(server ≥1.20x usage-analytics 面,server.ts /v1/usage/ 分发实拆)。
+     *  `from`/`to` = ISO-8601 或 epoch-ms(缺省近 7 天);JWT 主体强制 owner=本人,fleet 凭证可传 `principal`。
+     *  501 = 无 run store;`truncated:true` = 扫描窗被截。 */
     async summary(opts) {
         return this.t.request({ method: "GET", path: `/v1/usage/summary${analyticsQuery(opts)}`, signal: opts?.signal });
     }
+    /** GET /v1/usage/series — 时序(UTC 桶,空桶不发行——消费方按需补零)。metric=tasks|tokensIn|tokensOut|costUsd
+     *  (缺省 costUsd),granularity=hour|day(缺省 day)。 */
     async series(opts) {
         const extra = new URLSearchParams();
         if (opts?.metric)
@@ -17,6 +23,8 @@ export class UsageResource {
             extra.set("granularity", opts.granularity);
         return this.t.request({ method: "GET", path: `/v1/usage/series${analyticsQuery(opts, extra)}`, signal: opts?.signal });
     }
+    /** GET /v1/usage/breakdown — 维度分桶。dimension=principal|model(缺省 principal;JWT 主体的 principal 桶
+     *  只会是本人一桶——owner 已强制,语义自然成立)。 */
     async breakdown(opts) {
         const extra = new URLSearchParams();
         if (opts?.dimension)

package/dist/resources/usage.js.map

@@ -1 +1 @@
-{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/resources/usage.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAG7C,KAAK,CAAC,GAAG,CAAC,IAA+B;QACvC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IAKD,KAAK,CAAC,OAAO,CAAC,IAAsD;QAClE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnH,CAAC;IAID,KAAK,CAAC,MAAM,CAAC,IAA4G;QACvH,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,IAAI,EAAE,MAAM;YAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,IAAI,EAAE,WAAW;YAAE,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACzH,CAAC;IAID,KAAK,CAAC,SAAS,CAAC,IAAkF;QAChG,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,IAAI,EAAE,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5H,CAAC;CACF;AAqBD,SAAS,cAAc,CAAC,IAA2B,EAAE,KAAuB;IAC1E,MAAM,CAAC,GAAG,KAAK,IAAI,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,IAAI,EAAE,IAAI,KAAK,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,IAAI,IAAI,EAAE,EAAE,KAAK,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,IAAI,IAAI,EAAE,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC"}
+{"version":3,"file":"usage.js","sourceRoot":"","sources":["../../src/resources/usage.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,CAAY;QAAZ,MAAC,GAAD,CAAC,CAAW;IAAG,CAAC;IAE7C,+FAA+F;IAC/F,KAAK,CAAC,GAAG,CAAC,IAA+B;QACvC,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACpF,CAAC;IAED;;sDAEkD;IAClD,KAAK,CAAC,OAAO,CAAC,IAAsD;QAClE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,oBAAoB,cAAc,CAAC,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACnH,CAAC;IAED;qDACiD;IACjD,KAAK,CAAC,MAAM,CAAC,IAA4G;QACvH,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,IAAI,EAAE,MAAM;YAAE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QACnD,IAAI,IAAI,EAAE,WAAW;YAAE,KAAK,CAAC,GAAG,CAAC,aAAa,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAClE,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,mBAAmB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IACzH,CAAC;IAED;sCACkC;IAClC,KAAK,CAAC,SAAS,CAAC,IAAkF;QAChG,MAAM,KAAK,GAAG,IAAI,eAAe,EAAE,CAAC;QACpC,IAAI,IAAI,EAAE,SAAS;YAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QAC5D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,sBAAsB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5H,CAAC;CACF;AAqBD,SAAS,cAAc,CAAC,IAA2B,EAAE,KAAuB;IAC1E,MAAM,CAAC,GAAG,KAAK,IAAI,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,IAAI,EAAE,IAAI,KAAK,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC/D,IAAI,IAAI,EAAE,EAAE,KAAK,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IACzD,IAAI,IAAI,EAAE,SAAS;QAAE,CAAC,CAAC,GAAG,CAAC,WAAW,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;IACxD,MAAM,EAAE,GAAG,CAAC,CAAC,QAAQ,EAAE,CAAC;IACxB,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AAC5B,CAAC"}

package/dist/resources/workflows.d.ts

@@ -1,5 +1,16 @@
+/** workflows — §workflow 可观测（core 1.116 design/97 observe API;service `GET /v1/workflows*`）。
+ *
+ *  `list` = `GET /v1/workflows?status=&limit=` → `{workflows: WorkflowRunSummary[]}`（**owner-scoped**:只返调用方 principal 自己的 run）。
+ *  `get`  = `GET /v1/workflows/:id` → 完整 `WorkflowRun`（phases/agents/stats）。**非 owner → 404**（无 existence oracle）。
+ *
+ *  🔴 S8（LLM 自助编排）现 flag-gated off → 端点回 **501**；enable 后即活。按契约消费,caller fail-safe 501/空。
+ *  🔴 in-process replica-local:list 只见**本副本**的 run（同 worker 亲和;durable 跨副本历史是 service follow-on）。
+ *  🔴 实时进度 `GET /v1/workflows/:id/stream`（SSE,首帧 `event:meta`,后续 `event:<type> data:<JSON>`,replica-local 无 resume）
+ *     不复用 `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). */
 export interface WorkflowAgentSteerReceipt {
     runId: string;
     label: string;
@@ -10,7 +21,18 @@ export interface WorkflowAgentSteerReceipt {
 export declare class WorkflowsResource {
     private readonly t;
     constructor(t: Transport);
+    /** server 1.247 ([1508]) — `?session=` on the workflow per-id faces (accept-phase, run-face sibling):
+     *  pass your conversation's sessionId on get/journal/stream/steerAgent. Today a MISMATCH against the run's
+     *  `originatingSessionId` → 404 (absence passes; a run without the field is principal-only); the
+     *  enforcement train will 404 absence too — new code should always send it. Send a real sessionId or
+     *  nothing (an EMPTY string counts as present-and-mismatched). On `list` the param is accepted but not yet
+     *  filtering (summary rows lack the field — pending a core addition); harmless forward-compat. */
     private sessionQs;
+    /** GET /v1/workflows — owner-scoped run 列表（summary 投影）。filter:status/limit。信封 `{workflows}`。 */
+    /** GET /v1/workflows/:runId/journal — the per-agent journal read face(server 1.239,[1402]/[1400]④:
+     *  workflow 失败诊断的模型/面板可见读面,云本地同构)。Entries ride ordinal-ordered:
+     *  `{callKey, ordinal, status, error?(首行), result?(bounded+redacted), tokens?, turns?}`。
+     *  404 = run 不存在/非 owner(无存在性 oracle);501 = journal store 未接(self-orchestration off)。 */
     journal(runId: string, opts?: {
         session?: string;
         signal?: AbortSignal;
@@ -26,6 +48,10 @@ export declare class WorkflowsResource {
             turns?: number;
         }>;
     }>;
+    /** `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.
+     *  server 1.249 filtered the returned newest-`limit` page; server 1.250+ pushes the filter into the store
+     *  (applied BEFORE limit — a busy scope no longer hides this session's older runs). */
     list(opts?: {
         status?: string;
         limit?: number;
@@ -34,16 +60,38 @@ export declare class WorkflowsResource {
     }): Promise<{
         workflows: WorkflowRunSummary[];
     }>;
+    /** GET /v1/workflows/:id — 完整 run。非 owner / 不存在 / session 不匹配 → 404（不暴露 existence）。 */
     get(id: string, opts?: {
         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
+     *  (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). */
     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`).
+     *
+     *  🔴 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.
+     *  Deliberately does NOT reuse `parseSse`/`parseFrameStream` (those auto-reconnect with Last-Event-ID, which
+     *  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`. */
     stream(id: 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":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,kBAAkB,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAMxF,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,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAQzC,OAAO,CAAC,SAAS;IASX,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;QACvF,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACxI,CAAC;IAQI,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;IAUtI,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAaxF,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;IAqB9B,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CAkBlH"}
+{"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;AAIxF;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,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,CAAC;gBAAD,CAAC,EAAE,SAAS;IAEzC;;;;;sGAKkG;IAClG,OAAO,CAAC,SAAS;IAIjB,gGAAgG;IAChG;;;6FAGyF;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;QACvF,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAC;KACxI,CAAC;IAIF;;;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,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9F;;;;;;;;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,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,cAAc,CAAC,mBAAmB,CAAC;CAkBlH"}

package/dist/resources/workflows.js

@@ -5,12 +5,27 @@ export class WorkflowsResource {
     constructor(t) {
         this.t = t;
     }
+    /** server 1.247 ([1508]) — `?session=` on the workflow per-id faces (accept-phase, run-face sibling):
+     *  pass your conversation's sessionId on get/journal/stream/steerAgent. Today a MISMATCH against the run's
+     *  `originatingSessionId` → 404 (absence passes; a run without the field is principal-only); the
+     *  enforcement train will 404 absence too — new code should always send it. Send a real sessionId or
+     *  nothing (an EMPTY string counts as present-and-mismatched). On `list` the param is accepted but not yet
+     *  filtering (summary rows lack the field — pending a core addition); harmless forward-compat. */
     sessionQs(session) {
         return session !== undefined ? `?session=${encodeURIComponent(session)}` : "";
     }
+    /** GET /v1/workflows — owner-scoped run 列表（summary 投影）。filter:status/limit。信封 `{workflows}`。 */
+    /** GET /v1/workflows/:runId/journal — the per-agent journal read face(server 1.239,[1402]/[1400]④:
+     *  workflow 失败诊断的模型/面板可见读面,云本地同构)。Entries ride ordinal-ordered:
+     *  `{callKey, ordinal, status, error?(首行), result?(bounded+redacted), tokens?, turns?}`。
+     *  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 });
     }
+    /** `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.
+     *  server 1.249 filtered the returned newest-`limit` page; server 1.250+ pushes the filter into the store
+     *  (applied BEFORE limit — a busy scope no longer hides this session's older runs). */
     async list(opts) {
         const q = new URLSearchParams();
         if (opts?.status)
@@ -22,9 +37,19 @@ export class WorkflowsResource {
         const qs = q.toString();
         return this.t.request({ method: "GET", path: `/v1/workflows${qs ? `?${qs}` : ""}`, signal: opts?.signal });
     }
+    /** GET /v1/workflows/:id — 完整 run。非 owner / 不存在 / session 不匹配 → 404（不暴露 existence）。 */
     async get(id, opts) {
         return this.t.request({ method: "GET", path: `/v1/workflows/${encodeURIComponent(id)}${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
+     *  (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). */
     async steerAgent(runId, label, message, opts) {
         return this.t.request({
             method: "POST",
@@ -33,6 +58,18 @@ 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`).
+     *
+     *  🔴 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.
+     *  Deliberately does NOT reuse `parseSse`/`parseFrameStream` (those auto-reconnect with Last-Event-ID, which
+     *  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`. */
     async *stream(id, opts) {
         const o = {
             method: "GET",
@@ -42,17 +79,17 @@ export class WorkflowsResource {
             o.signal = opts.signal;
         const res = await this.t.openStream(o);
         if (!res.ok)
-            throw toApiError(res.status, await res.json().catch(() => ({})));
+            throw toApiError(res.status, await res.json().catch(() => ({}))); // 501 (S8 off) / 404 (non-owner) — before any frame
         try {
             for await (const frame of readSseFrames(res, undefined, opts?.signal)) {
                 if (!frame.data)
-                    continue;
+                    continue; // heartbeat / comment
                 const data = JSON.parse(frame.data);
                 yield { event: (frame.event ?? "message"), data };
             }
         }
         finally {
-            res.body?.cancel().catch(() => { });
+            res.body?.cancel().catch(() => { }); // disconnect = stop the in-process subscription
         }
     }
 }

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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"}