@sema-agent/client-core 0.2.0 → 0.4.0

package/dist/controlRouter.d.ts

@@ -0,0 +1,191 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/seam/adapter/upstream/controlRouter.ts 逐字搬入(闭包 1 文件,只 import SDK)。
+ */
+/**
+ * src/seam/adapter/upstream/controlRouter.ts — the UPSTREAM control-VERB router (NEW file, no CC-logic edit).
+ *
+ * Where `hitlBridge.ts` owns the suspended → decide → resume HITL loop (the gate-resolution verbs:
+ * `approvals.decide` / `assistant.planReview` / `assistant.resume`), THIS module owns the OTHER half of the
+ * upstream control channel (contract/04 §5/§6, contract/08 IH-7/IH-8): the SUPERVISION verbs that act on a
+ * run *while it works* — submit a turn, steer it mid-flight, kill it, and the client-side QUEUED-COMMAND
+ * ordering that has no wire of its own. It is the single choke point that maps a shell control INTENT onto
+ * the right `client.runs.*` verb, branching the §9.1 error taxonomy fail-closed.
+ *
+ * The five routes (contract/04 §5/§6; 08 IH-7/IH-8; the catalog rows it binds):
+ *
+ *  1. **submit** (IH-1/IH-2, catalog L73/L74). A turn → its OWN durable run: `runs.create(TaskRequest)` →
+ *     202 `RunReceipt`. The SAME `sessionId` continues the conversation (the service serializes turns per
+ *     session); the SAME `jobId` groups the sub-runs into ONE Task in the work view (contract/04 §5.2,
+ *     types.ts:59-63). `runs.create` is a SUBMIT → it carries an idempotency key and the SDK may retry it.
+ *
+ *  2. **steer** (IH-7, §5.1, catalog L81). Inject mid-flight direction into a RUNNING durable run:
+ *     `runs.steer(taskId, { text, mode? })`. The text is untrusted DATA — the shell sends it RAW and the
+ *     SERVER fences it (the shell does NOT pre-sanitize control markers). AT-MOST-ONCE: steer is NOT
+ *     idempotent, so it is NEVER retried (runs.ts:43). `mode` drains queued steers at the TURN boundary
+ *     ("all" = inject all next turn; "one-at-a-time" = one per turn, FIFO). Errors are fail-closed:
+ *     `SteeringNotRunningError` (run suspended/terminal — resolve its gate, don't steer) and
+ *     `SteeringInvalidContentError` (the text carried a control-plane escape — SURFACE, never strip-and-retry).
+ *
+ *  3. **cancel** (IH-8, §5.3, catalog L84). HARD-STOP an async run: `runs.cancel(taskId)` → 202 `CancelAck`
+ *     (`status:"cancelling"` or a terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"`
+ *     (NOT a new status — the UI shows "cancelled", not an error). A 409 means the run is SUSPENDED → it must
+ *     be cancelled by DENYING its approval (`hitlBridge.decideTool({decision:"deny"})`), never by `cancel`;
+ *     the router surfaces a `ControlSafetyError('cancel_suspended')` telling the shell to route to deny. 404 =
+ *     non-owner/unknown (no existence leak). Server-idempotent; not a submit → no SDK retry.
+ *
+ *  4. **queued commands** (§5.2, catalog L82 `contract-extension`). CC enqueues next turns with a per-message
+ *     `priority: 'now'|'next'|'later'` and drops a queued message by uuid (`cancel_async_message`). The SDK
+ *     has NEITHER: no `priority` on `TaskRequest`, no drop-queued verb. The faithful behavior is CLIENT-SIDE:
+ *     hold a local priority-ordered queue, allow a DEQUEUE *before* submit (the only stop a queued message
+ *     has — once submitted the nearest lever is `cancel`, which kills the whole run, not one message), and
+ *     drain by submitting each queued turn as its own run under the same sessionId+jobId.
+ *
+ * Provider- and presentation-agnostic (contract/04 laws 2-3; 08 invariants): every verb stays at
+ * `TaskRequest` / `RunReceipt` / `CancelAck` altitude. No Anthropic `effort`/`fast_mode`, no claude.ai
+ * control-message shape, no widget/glyph crosses this seam. The router emits the SDK verb; the shell owns the
+ * keybinding, the queue chrome, and the "cancelled" badge.
+ */
+import type { TaskRequest, RunReceipt, CancelAck, Scenario } from '@sema-agent/sdk';
+export interface RunsResourceLike {
+    /** POST /v1/runs → 202 RunReceipt. SUBMIT-class: carries an idempotency key, SDK may retry (runs.ts:13). */
+    create(req: TaskRequest, opts?: {
+        idempotencyKey?: string | null;
+        signal?: AbortSignal;
+    }): Promise<RunReceipt>;
+    /** POST /v1/runs/:id/steer — inject mid-flight direction into a RUNNING run. AT-MOST-ONCE: NOT a submit,
+     *  NEVER retried (runs.ts:51). The text is untrusted DATA the server fences. */
+    steer(taskId: string, steer: {
+        text: string;
+        mode?: 'all' | 'one-at-a-time';
+    }, opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /** POST /v1/runs/:id/cancel → 202 CancelAck. Hard-stop; server-idempotent; not a submit → no retry
+     *  (runs.ts:34). 409 if suspended (deny instead); 404 non-owner. */
+    cancel(taskId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<CancelAck>;
+}
+export interface ControlClientLike {
+    runs: RunsResourceLike;
+}
+/** A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
+ *  shell can branch: `not_running` (steer a non-running run) | `invalid_content` (steer carried an escape) |
+ *  `cancel_suspended` (cancel a suspended run — route to DENY instead) | `not_found` (non-owner/unknown). */
+export declare class ControlSafetyError extends Error {
+    readonly code: 'not_running' | 'invalid_content' | 'cancel_suspended' | 'not_found';
+    /** The original SDK error, for logging (never re-thrown blind). */
+    readonly cause?: unknown | undefined;
+    constructor(message: string, code: 'not_running' | 'invalid_content' | 'cancel_suspended' | 'not_found', 
+    /** The original SDK error, for logging (never re-thrown blind). */
+    cause?: unknown | undefined);
+}
+export type QueuePriority = 'now' | 'next' | 'later';
+/** A turn the user queued but has not yet submitted. `id` is a local uuid the shell uses to DEQUEUE it. */
+export interface QueuedCommand {
+    id: string;
+    text: string;
+    priority: QueuePriority;
+}
+export interface ControlRouterOptions {
+    /** Continue a conversation: the SAME sessionId across turns (contract/04 §5.2; types.ts:59). Omit to start
+     *  fresh — the service mints one and the shell adopts it from the first `RunReceipt.sessionId`. */
+    sessionId?: string;
+    /** Group the sub-runs of one logical job into one Task (contract/04 §5.2; types.ts:62). */
+    jobId?: string;
+    /** Scenario passthrough (default/oa/code-review/team) applied to every submitted turn. */
+    scenario?: Scenario;
+    /** Per-submit system prompt the integrator owns (types.ts:64 — stable cacheable prefix). */
+    systemPrompt?: string;
+}
+export declare class ControlRouter {
+    private readonly client;
+    /** The run currently in flight — the target of steer/cancel. Null before the first submit. */
+    private taskId;
+    /** Adopted from the first RunReceipt when the caller did not pin one (service-minted continuity). */
+    private sessionId;
+    private readonly jobId;
+    private readonly scenario;
+    private readonly systemPrompt;
+    /** The client-side queued turns (contract/04 §5.2 — no wire equivalent). */
+    private readonly queue;
+    private seq;
+    constructor(client: ControlClientLike, opts?: ControlRouterOptions);
+    /** The run currently in flight, if any. The shell reads this to know what steer/cancel will target. */
+    activeTaskId(): string | null;
+    /** The session token threading the conversation (service-minted after the first submit). */
+    activeSessionId(): string | undefined;
+    /**
+     * Submit a turn as a durable async run (`runs.create` → 202 `RunReceipt`). The SAME `sessionId` continues
+     * the conversation (the service serializes turns per session — a session-CAS conflict while a prior run
+     * holds the claim → 409 `Conflict`, contract/04 §5.2 / openapi:173); the SAME `jobId` groups the sub-runs
+     * into one Task in the work view. `runs.create` is a SUBMIT, so the idempotency key rides along (the SDK
+     * auto-generates one and may safely retry on transport failure).
+     *
+     * Adopts the service-minted `sessionId` from the receipt when the caller did not pin one (continuity), and
+     * latches the new run as the active steer/cancel target.
+     */
+    submit(text: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<RunReceipt>;
+    /** Project the session context + the typed turn into the `@sema-ai` `TaskRequest` wire shape. Secret
+     *  discipline (types.ts:54-58): NEVER put tokens in `objective`/`systemPrompt`. */
+    private buildTaskRequest;
+    /**
+     * Steer the RUNNING run: `runs.steer(taskId, { text, mode? })`. Hard rules this method enforces:
+     *
+     *  - **The text is untrusted DATA — sent RAW.** The shell does NOT pre-sanitize control markers; the SERVER
+     *    fences the text (contract/04 §5.1). A text carrying a control-plane escape → 422
+     *    `SteeringInvalidContentError` → surfaced as `ControlSafetyError('invalid_content')` (SURFACE the error;
+     *    never strip-and-retry).
+     *  - **`trusted` is NOT a client field** — the server derives trust from the authenticated operator role;
+     *    this method has no way to assert it, by construction.
+     *  - **AT-MOST-ONCE — never retried.** `runs.steer` is not idempotent and not a submit, so a transport
+     *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
+     *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
+     *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
+     *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
+     *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
+     *    the next turn boundary, not instantly.
+     */
+    steer(text: string, mode?: 'all' | 'one-at-a-time', opts?: {
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+    /**
+     * Cancel (kill) the in-flight run: `runs.cancel(taskId)` → 202 `CancelAck` (`status:"cancelling"` or a
+     * terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"` — the UI shows "cancelled",
+     * NOT an error (the router does not synthesize that terminal; the downstream stream / `terminalToSdkResult`
+     * does). Branching (contract/04 §9.1):
+     *
+     *  - **409 = the run is SUSPENDED.** A suspended run is cancelled by DENYING its approval, NOT by `cancel`
+     *    (which 409s). Surfaced as `ControlSafetyError('cancel_suspended')` so the shell routes the kill to
+     *    `hitlBridge.decideTool({decision:"deny"})` instead.
+     *  - **404 = non-owner / unknown.** No existence oracle (404, not 403) → `ControlSafetyError('not_found')`.
+     *
+     * Server-idempotent and NOT a submit, so a successful cancel is safe to repeat (a terminal run no-ops);
+     * the router still does not auto-retry on transport failure (the shell re-invokes on the user's repeat).
+     */
+    cancel(opts?: {
+        signal?: AbortSignal;
+    }): Promise<CancelAck>;
+    /** Enqueue a turn for later submission. `now` jumps the line, `next` (default) is FIFO, `later` trails.
+     *  Returns the queued row (its `id` is the dequeue handle). Nothing leaves the machine until `drainNext`. */
+    enqueue(text: string, priority?: QueuePriority): QueuedCommand;
+    /** Drop a STILL-QUEUED turn by id BEFORE it is submitted (the only stop a queued message has —
+     *  contract/04 §5.2). Returns true if it was in the queue, false if absent / already drained (mirrors CC's
+     *  `cancel_async_message` → `{cancelled:false}` "not in the queue / already dequeued"). */
+    dequeue(id: string): boolean;
+    /** A stable, priority-banded view of the queue (the shell renders this; drain order matches it). */
+    pending(): readonly QueuedCommand[];
+    /**
+     * Drain the highest-priority queued turn: dequeue it and `submit` it as its own durable run (same session
+     * → continues the conversation; same jobId → one Task). Returns the `RunReceipt`, or null when the queue is
+     * empty. The session serializes turns, so the caller drains one at a time (submit, await the run, drain the
+     * next); submitting while a prior run holds the session claim surfaces the SDK's 409 `ConflictError` from
+     * `submit` — the shell waits and re-drains (contract/04 §5.2; openapi:173).
+     */
+    drainNext(opts?: {
+        signal?: AbortSignal;
+    }): Promise<RunReceipt | null>;
+    private nextId;
+}

package/dist/controlRouter.js

@@ -0,0 +1,244 @@
+// ── Errors the router surfaces (fail-closed; never auto-retried) ───────────────
+//
+// Mirrors hitlBridge.HitlSafetyError: every safety-relevant control error is a signal to re-present to the
+// human or surface the error, NEVER to silently retry or auto-decide (contract/04 §9.1 fail-closed law). The
+// router catches the SDK's typed errors and re-raises a stable, shell-branchable code.
+/** A supervision-verb stop the shell must HANDLE, not retry (contract/04 §9.1). The `code` is stable so the
+ *  shell can branch: `not_running` (steer a non-running run) | `invalid_content` (steer carried an escape) |
+ *  `cancel_suspended` (cancel a suspended run — route to DENY instead) | `not_found` (non-owner/unknown). */
+export class ControlSafetyError extends Error {
+    code;
+    cause;
+    constructor(message, code, 
+    /** The original SDK error, for logging (never re-thrown blind). */
+    cause) {
+        super(message);
+        this.code = code;
+        this.cause = cause;
+        this.name = 'ControlSafetyError';
+    }
+}
+/** Band rank for stable priority ordering: lower drains first. */
+const BAND_RANK = { now: 0, next: 1, later: 2 };
+export class ControlRouter {
+    client;
+    /** The run currently in flight — the target of steer/cancel. Null before the first submit. */
+    taskId = null;
+    /** Adopted from the first RunReceipt when the caller did not pin one (service-minted continuity). */
+    sessionId;
+    jobId;
+    scenario;
+    systemPrompt;
+    /** The client-side queued turns (contract/04 §5.2 — no wire equivalent). */
+    queue = [];
+    seq = 0;
+    constructor(client, opts = {}) {
+        this.client = client;
+        this.sessionId = opts.sessionId;
+        this.jobId = opts.jobId;
+        this.scenario = opts.scenario;
+        this.systemPrompt = opts.systemPrompt;
+    }
+    /** The run currently in flight, if any. The shell reads this to know what steer/cancel will target. */
+    activeTaskId() {
+        return this.taskId;
+    }
+    /** The session token threading the conversation (service-minted after the first submit). */
+    activeSessionId() {
+        return this.sessionId;
+    }
+    // ── §1. submit — a turn → its own durable run (contract/04 §5.2; 08 IH-2, catalog L74) ───────────────────
+    /**
+     * Submit a turn as a durable async run (`runs.create` → 202 `RunReceipt`). The SAME `sessionId` continues
+     * the conversation (the service serializes turns per session — a session-CAS conflict while a prior run
+     * holds the claim → 409 `Conflict`, contract/04 §5.2 / openapi:173); the SAME `jobId` groups the sub-runs
+     * into one Task in the work view. `runs.create` is a SUBMIT, so the idempotency key rides along (the SDK
+     * auto-generates one and may safely retry on transport failure).
+     *
+     * Adopts the service-minted `sessionId` from the receipt when the caller did not pin one (continuity), and
+     * latches the new run as the active steer/cancel target.
+     */
+    async submit(text, opts) {
+        const req = this.buildTaskRequest(text);
+        const receipt = await this.client.runs.create(req, opts ? { signal: opts.signal } : undefined);
+        // Adopt service-minted continuity + latch the in-flight run.
+        if (this.sessionId === undefined)
+            this.sessionId = receipt.sessionId;
+        this.taskId = receipt.taskId;
+        return receipt;
+    }
+    /** Project the session context + the typed turn into the `@sema-ai` `TaskRequest` wire shape. Secret
+     *  discipline (types.ts:54-58): NEVER put tokens in `objective`/`systemPrompt`. */
+    buildTaskRequest(text) {
+        // 空内容守卫(2026-07-16 唤醒 400 批,同病同修):SDK/控制面递来的空/全空白 user_message 绝不作为
+        // 空 objective 上 wire——引擎会把空 user 消息写进会话持久历史(provider 400 + session 毒化)。
+        // 与 CC createUserMessage 的 NO_CONTENT_MESSAGE 同语义占位。
+        const req = { objective: text.trim().length > 0 ? text : '(no content)' };
+        if (this.sessionId !== undefined)
+            req.sessionId = this.sessionId;
+        if (this.jobId !== undefined)
+            req.jobId = this.jobId;
+        if (this.scenario !== undefined)
+            req.scenario = this.scenario;
+        if (this.systemPrompt !== undefined)
+            req.systemPrompt = this.systemPrompt;
+        return req;
+    }
+    // ── §2. steer — inject mid-flight direction (contract/04 §5.1; 08 IH-7, catalog L81) ─────────────────────
+    /**
+     * Steer the RUNNING run: `runs.steer(taskId, { text, mode? })`. Hard rules this method enforces:
+     *
+     *  - **The text is untrusted DATA — sent RAW.** The shell does NOT pre-sanitize control markers; the SERVER
+     *    fences the text (contract/04 §5.1). A text carrying a control-plane escape → 422
+     *    `SteeringInvalidContentError` → surfaced as `ControlSafetyError('invalid_content')` (SURFACE the error;
+     *    never strip-and-retry).
+     *  - **`trusted` is NOT a client field** — the server derives trust from the authenticated operator role;
+     *    this method has no way to assert it, by construction.
+     *  - **AT-MOST-ONCE — never retried.** `runs.steer` is not idempotent and not a submit, so a transport
+     *    failure propagates; the router does NOT auto-resend (a double-steer must be impossible).
+     *  - **Steer needs a RUNNING run.** A suspended/terminal run → 409 `SteeringNotRunningError` → surfaced as
+     *    `ControlSafetyError('not_running')` (resolve its gate via the hitlBridge `decide`, don't steer).
+     *  - **`mode` drains at the TURN boundary** (FORWARD-DRAFT per-call mapping, runs.ts:49-50): `"all"` injects
+     *    all queued steers at the next turn; `"one-at-a-time"` (default) one per turn, FIFO. Steer applies at
+     *    the next turn boundary, not instantly.
+     */
+    async steer(text, mode, opts) {
+        if (this.taskId === null) {
+            throw new ControlSafetyError('no run in flight to steer — submit a turn first', 'not_running');
+        }
+        // Raw text, no pre-sanitize (the server fences). `mode` omitted → server default one-at-a-time.
+        const body = mode !== undefined ? { text, mode } : { text };
+        try {
+            return await this.client.runs.steer(this.taskId, body, opts ? { signal: opts.signal } : undefined);
+        }
+        catch (e) {
+            if (isSteeringNotRunning(e)) {
+                throw new ControlSafetyError('steering.not_running — the run is suspended/terminal; resolve its gate via decide, do not steer', 'not_running', e);
+            }
+            if (isSteeringInvalidContent(e)) {
+                throw new ControlSafetyError('steering.invalid_content — the steer text carried a control-plane escape; surface it, do not strip-and-retry', 'invalid_content', e);
+            }
+            // Any other error (auth/transport): NOT retried (steer is at-most-once) — propagate to the shell.
+            throw e;
+        }
+    }
+    // ── §3. cancel — hard-stop / kill the run (contract/04 §5.3; 08 IH-8, catalog L84) ───────────────────────
+    /**
+     * Cancel (kill) the in-flight run: `runs.cancel(taskId)` → 202 `CancelAck` (`status:"cancelling"` or a
+     * terminal no-op). The run then SETTLES to `failed` + `errorCode:"cancelled"` — the UI shows "cancelled",
+     * NOT an error (the router does not synthesize that terminal; the downstream stream / `terminalToSdkResult`
+     * does). Branching (contract/04 §9.1):
+     *
+     *  - **409 = the run is SUSPENDED.** A suspended run is cancelled by DENYING its approval, NOT by `cancel`
+     *    (which 409s). Surfaced as `ControlSafetyError('cancel_suspended')` so the shell routes the kill to
+     *    `hitlBridge.decideTool({decision:"deny"})` instead.
+     *  - **404 = non-owner / unknown.** No existence oracle (404, not 403) → `ControlSafetyError('not_found')`.
+     *
+     * Server-idempotent and NOT a submit, so a successful cancel is safe to repeat (a terminal run no-ops);
+     * the router still does not auto-retry on transport failure (the shell re-invokes on the user's repeat).
+     */
+    async cancel(opts) {
+        if (this.taskId === null) {
+            throw new ControlSafetyError('no run in flight to cancel', 'not_found');
+        }
+        try {
+            return await this.client.runs.cancel(this.taskId, opts ? { signal: opts.signal } : undefined);
+        }
+        catch (e) {
+            if (isCancelSuspendedConflict(e)) {
+                throw new ControlSafetyError('cancel on a SUSPENDED run (409) — cancel it by DENYING its approval (decide), not by runs.cancel', 'cancel_suspended', e);
+            }
+            if (isNotFound(e)) {
+                throw new ControlSafetyError('runs.cancel 404 — non-owner / unknown run (no existence leak)', 'not_found', e);
+            }
+            throw e;
+        }
+    }
+    // ── §4. queued commands — client-side priority + drop (contract/04 §5.2, catalog L82) ────────────────────
+    //
+    // The SDK has no per-message priority and no drop-queued verb. The router holds the queue locally: enqueue
+    // by priority band, dequeue a still-queued turn by its local id, and drain by submitting each as its own
+    // run under the same session. A submitted turn LEAVES the queue — its only after-submit stop is `cancel`.
+    /** Enqueue a turn for later submission. `now` jumps the line, `next` (default) is FIFO, `later` trails.
+     *  Returns the queued row (its `id` is the dequeue handle). Nothing leaves the machine until `drainNext`. */
+    enqueue(text, priority = 'next') {
+        const cmd = { id: this.nextId(), text, priority };
+        this.queue.push(cmd);
+        return cmd;
+    }
+    /** Drop a STILL-QUEUED turn by id BEFORE it is submitted (the only stop a queued message has —
+     *  contract/04 §5.2). Returns true if it was in the queue, false if absent / already drained (mirrors CC's
+     *  `cancel_async_message` → `{cancelled:false}` "not in the queue / already dequeued"). */
+    dequeue(id) {
+        const i = this.queue.findIndex((c) => c.id === id);
+        if (i < 0)
+            return false;
+        this.queue.splice(i, 1);
+        return true;
+    }
+    /** A stable, priority-banded view of the queue (the shell renders this; drain order matches it). */
+    pending() {
+        return [...this.queue].sort((a, b) => BAND_RANK[a.priority] - BAND_RANK[b.priority]);
+    }
+    /**
+     * Drain the highest-priority queued turn: dequeue it and `submit` it as its own durable run (same session
+     * → continues the conversation; same jobId → one Task). Returns the `RunReceipt`, or null when the queue is
+     * empty. The session serializes turns, so the caller drains one at a time (submit, await the run, drain the
+     * next); submitting while a prior run holds the session claim surfaces the SDK's 409 `ConflictError` from
+     * `submit` — the shell waits and re-drains (contract/04 §5.2; openapi:173).
+     */
+    async drainNext(opts) {
+        const ordered = this.pending();
+        const head = ordered[0];
+        if (!head)
+            return null;
+        this.dequeue(head.id);
+        return this.submit(head.text, opts);
+    }
+    nextId() {
+        this.seq += 1;
+        return `q-${this.seq}-${uuid()}`;
+    }
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+/** A v4-shaped uuid for the local queue handles (never on the wire). Mirrors types.ts/seamQuery's helper. */
+function uuid() {
+    const g = typeof globalThis !== 'undefined'
+        ? globalThis.crypto
+        : undefined;
+    if (g && typeof g.randomUUID === 'function')
+        return g.randomUUID();
+    return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, (c) => {
+        const r = (Math.random() * 16) | 0;
+        const v = c === 'x' ? r : (r & 0x3) | 0x8;
+        return v.toString(16);
+    });
+}
+/** Read a normalized error code/status off any SDK error shape variant (errorCode / code / name / status). */
+function errCodes(e) {
+    if (!e || typeof e !== 'object')
+        return {};
+    const o = e;
+    return { code: o.errorCode ?? o.code, name: o.name, status: o.status ?? o.statusCode };
+}
+/** 409 `steering.not_running` / `SteeringNotRunningError` — the run is suspended/terminal (runs.ts:45). */
+function isSteeringNotRunning(e) {
+    const { code, name } = errCodes(e);
+    return code === 'steering.not_running' || name === 'SteeringNotRunningError';
+}
+/** 422 `steering.invalid_content` / `SteeringInvalidContentError` — control-plane escape (runs.ts:46). */
+function isSteeringInvalidContent(e) {
+    const { code, name } = errCodes(e);
+    return code === 'steering.invalid_content' || name === 'SteeringInvalidContentError';
+}
+/** A 409 on `cancel` means the run is SUSPENDED → cancel-by-deny instead (runs.ts:36; openapi:371-372).
+ *  The SDK raises a generic `ConflictError` (status 409) for this case — there is no dedicated subclass. */
+function isCancelSuspendedConflict(e) {
+    const { name, status } = errCodes(e);
+    return name === 'ConflictError' || status === 409;
+}
+/** 404 — non-owner / unknown run; the SDK raises `NotFoundError` (no existence oracle, contract/04 §9.1). */
+function isNotFound(e) {
+    const { name, status } = errCodes(e);
+    return name === 'NotFoundError' || status === 404;
+}

package/dist/effortWire.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/effortWire.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/effortWire.ts — the EFFORT/REASONING-STRENGTH ENGINE WIRE (per-turn `/effort` → engine).
+ *
+ * WHY THIS FILE EXISTS (the parity gap it closes):
+ * CC's `/effort` slider sets a per-turn reasoning strength; sema's picker writes it to `AppState.effortValue`
+ * (overrides/effort.tsx:302) but the seam's `toTaskRequest` never put it on the wire, so the picked effort
+ * reached the UI yet NOT the engine. Grounding (2026-06-29) showed the seam is ALREADY complete downstream:
+ *   - core `TaskSpec.thinking: ThinkingLevel` = off|minimal|low|medium|high|xhigh|max (7 档,covers CC effort)
+ *     — `core/src/core/types.ts:466`; consumed at `prepare-task.ts:1663` (→brain) / :1471 (xhigh/max→awareness).
+ *   - service `reasoningEffort` → `thinking`, UNKNOWN value 400 fail-loud — `server.ts:234/3576`, `main.ts:1270`.
+ * So this is a SHELL-only wire: map the picked `EffortValue` → the wire `reasoningEffort` (a core ThinkingLevel)
+ * and stamp it on `TaskRequest`. Pure projection here (testable); the AppState read is inline in seamQuery.
+ *
+ * MAPPING: sema's picker can yield low|medium|high|max (base EffortLevel) + xhigh|ultracode|auto (187 override
+ * accept-set) + numeric. The wire `reasoningEffort` accepts a core ThinkingLevel only. So pass a value IFF it
+ * is a ThinkingLevel (off|minimal|low|medium|high|xhigh|max); `auto` (let engine default), `ultracode` (a
+ * separate mode, future slice), numeric and unset all OMIT — the engine then uses its own default.
+ */
+/**
+ * The core ThinkingLevel = the service `reasoningEffort` accept-set (`server.ts:3576`) = the SDK
+ * `TaskRequest.reasoningEffort` union. Declared as a literal union (not bare `string`) so the projection's
+ * result narrows to exactly what `TaskRequest.reasoningEffort` accepts — a bare `string` would not be
+ * assignable to that enum (the false-green tsc hid this; see memory shell-tsc-check-broken-false-green).
+ */
+export type ReasoningEffort = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+/**
+ * Project a picked `EffortValue` (string level | number | undefined) → the wire `reasoningEffort`, or
+ * undefined to OMIT. Returns the value verbatim iff it is a core ThinkingLevel; everything else (auto,
+ * ultracode, numeric efforts, undefined) → undefined so the engine applies its own default.
+ */
+export declare function effortToReasoningEffort(effort: unknown): ReasoningEffort | undefined;

package/dist/effortWire.js

@@ -0,0 +1,38 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/effortWire.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/effortWire.ts — the EFFORT/REASONING-STRENGTH ENGINE WIRE (per-turn `/effort` → engine).
+ *
+ * WHY THIS FILE EXISTS (the parity gap it closes):
+ * CC's `/effort` slider sets a per-turn reasoning strength; sema's picker writes it to `AppState.effortValue`
+ * (overrides/effort.tsx:302) but the seam's `toTaskRequest` never put it on the wire, so the picked effort
+ * reached the UI yet NOT the engine. Grounding (2026-06-29) showed the seam is ALREADY complete downstream:
+ *   - core `TaskSpec.thinking: ThinkingLevel` = off|minimal|low|medium|high|xhigh|max (7 档,covers CC effort)
+ *     — `core/src/core/types.ts:466`; consumed at `prepare-task.ts:1663` (→brain) / :1471 (xhigh/max→awareness).
+ *   - service `reasoningEffort` → `thinking`, UNKNOWN value 400 fail-loud — `server.ts:234/3576`, `main.ts:1270`.
+ * So this is a SHELL-only wire: map the picked `EffortValue` → the wire `reasoningEffort` (a core ThinkingLevel)
+ * and stamp it on `TaskRequest`. Pure projection here (testable); the AppState read is inline in seamQuery.
+ *
+ * MAPPING: sema's picker can yield low|medium|high|max (base EffortLevel) + xhigh|ultracode|auto (187 override
+ * accept-set) + numeric. The wire `reasoningEffort` accepts a core ThinkingLevel only. So pass a value IFF it
+ * is a ThinkingLevel (off|minimal|low|medium|high|xhigh|max); `auto` (let engine default), `ultracode` (a
+ * separate mode, future slice), numeric and unset all OMIT — the engine then uses its own default.
+ */
+const REASONING_EFFORTS = new Set([
+    'off',
+    'minimal',
+    'low',
+    'medium',
+    'high',
+    'xhigh',
+    'max',
+]);
+/**
+ * Project a picked `EffortValue` (string level | number | undefined) → the wire `reasoningEffort`, or
+ * undefined to OMIT. Returns the value verbatim iff it is a core ThinkingLevel; everything else (auto,
+ * ultracode, numeric efforts, undefined) → undefined so the engine applies its own default.
+ */
+export function effortToReasoningEffort(effort) {
+    return typeof effort === 'string' && REASONING_EFFORTS.has(effort) ? effort : undefined;
+}

package/dist/engineAgentPanelStore.d.ts

@@ -0,0 +1,111 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/engineAgentPanelStore.ts 逐字搬入(零 import;壳侧改 re-export)。
+ * 🔴 同 subagentContentStore:buffer/listener/residentTaskIds 是单实例语义,发布侧(bridge/fleet
+ * 投影)与订阅侧(chrome-agentprogress 的面板 hook)必须同实例,否则事件发进一个副本、面板订另一个。
+ */
+/**
+ * engineAgentPanelStore — dep-free side-channel store bridging ENGINE-side subagent progress
+ * (`task_progress` ticks, design/99 MF-10) to CC's CoordinatorTaskPanel (the footer live-agent panel).
+ *
+ * WHY A STORE (the retryStatusStore / liveQuestionStore pattern): the upstream bridge is a plain
+ * generator with no React/AppState access, while the panel reads `AppState.tasks` — so the bridge
+ * PUBLISHES neutral events here and a sema-owned hook inside chrome-agentprogress.tsx (already mounted
+ * under the footer) SUBSCRIBES and applies them to AppState via registerTask/updateTaskState. CC files
+ * stay verbatim; the AppState write side lives in the sema override that owns the panel.
+ *
+ * WHY THE PANEL (CC-187 parity): a local sync AgentTool renders an inline progress TRAIL from the
+ * subagent's real messages. An engine tick carries ONLY rollup numbers ({toolUses, totalTokens}) — the
+ * exact shape of CC's `AgentProgress` — and CC's own precedent for out-of-process agents (remote agent
+ * tasks) is the TASK PANEL + task-notification, not a synthetic inline trail. Faithful mapping, no
+ * fabricated subagent messages.
+ *
+ * Buffering: ticks published before the panel mounts are buffered (bounded) and replayed to the first
+ * subscriber, so early frames in a fast turn aren't lost to mount timing.
+ */
+export type EngineAgentPanelEvent = {
+    kind: 'tick';
+    taskId: string;
+    /** Subagent display name off the wire tick (redacted upstream); absent ⇒ keep taskId. */
+    name?: string;
+    /** The delegating Task tool_use's `description` (the card title), when the bridge could bind one. */
+    description?: string;
+    /** The delegated prompt off the bound tool_use input, when present. */
+    prompt?: string;
+    /** core 1.262.0 [558]B (service 1.154.0 wire) — the child's most recent tool intent as ONE
+     *  human line ("Bash npm test"), service-redacted. The panel consumer maps it onto the row's
+     *  `progress.summary` (CC's own live-activity display slot); absent ⇒ slot untouched. */
+    currentAction?: string;
+    toolUses: number;
+    totalTokens: number;
+} | {
+    /**
+     * 行帧 lane 投影(2026-07-26 「后台 Agent 子代不进 Background 面板」案)。
+     *
+     * 一手取证(verify/_bgagent-panel-lane-live-pty.mjs 首跑,engine 1.277.4 真机):两个
+     * `run_in_background:true` 的 fork 子代**活跃干活整跑**,`task_progress` tick 探针 **0 条**、
+     * fleet 行帧探针 **24 条** —— 父 turn 秒收口即关 SSE,子代的 tick 根本没有通道到壳;行帧
+     * lane(常开 fleet stream)才是后台子代唯一在场的 lane。面板的 local_agent 行此前**只**由
+     * tick 注册 ⇒ 产品自印的「N background agents launched (↓ to manage)」指向一个看不到它们的
+     * 面板(还顺带让 `ctrl+x ctrl+k … stop all agents` 的渲染门在真产品里永不成立)。
+     *
+     * 为什么是独立事件形而不是复用 'tick':两条 lane 的**可选性**不同 —— tick 的 `toolUses` 是
+     * 必填数,行帧的是**可选**位(server 1.278.0 才有,老引擎没有)。复用 tick 会强迫本 lane 在
+     * 缺席时编一个 0,把前台子代由真 tick 写进去的进度数字每秒清一次。消费端对本事件的规矩:
+     * 只建/只喂**本 lane 亲手建的行**,tick 一到就永久让位(fleetOwnedRowIds 摘除)。
+     */
+    kind: 'fleet-row';
+    taskId: string;
+    /** 行帧 agentType(fleet 行 label 列,如 'fork')→ 行的 agentType。 */
+    name?: string;
+    /** 行帧投影出的任务描述(如 'alpha-probe')→ 行的 description(面板行 label)。 */
+    description?: string;
+    /** core 1.429 → server 1.288([1831]②):子代当前工具的结构化形。`toolName` verbatim
+     *  (查壳工具注册表),`target` 已上游 redact + 300 bound。缺席=旧端或子代从未跑过工具。 */
+    currentTool?: {
+        toolName: string;
+        target?: string;
+    };
+    /** 行帧累计 token。 */
+    totalTokens?: number;
+    /**
+     * server 1.278.0 起行帧也带的**累计**工具调用数(修「后台子代详情页 tool 计数恒 0」)。
+     *
+     * 🔴 三态,别写 `?? 0`:
+     *   · 键在 ⇒ 真值(含真 0 = 引擎说「一个工具都没跑」);
+     *   · 键不在 ⇒ 老引擎没这个位 = **不知道**,消费端如实留空/保留行上已有值,绝不写 0。
+     * 🔴 **累计不是增量**:bg sink 的 usage 是累计口径(与 `turn_end` 的每轮增量相反,后者在
+     *    upstreamBridge 里要累加)——消费端直接赋值,绝不 `+=`。
+     *
+     * ⚠️ 时序差(server 主动提醒,不是接错):1.278.0 只在 **bg lane** 上线;workflow/subagent
+     * 子代走的 `task_progress`(tick lane)的 `usage.toolUses` 在 core 类型里本来就必填、数据一直
+     * 在,只是那条 lane 也没发 —— 已补齐但搭 1.278.0 之后的下一车。所以短期内「有的行有、有的
+     * 行没有」是**预期形**,两条 lane 的接线口径已按同一套三态写好。
+     */
+    toolUses?: number;
+    /**
+     * server 1.278.0 `transcriptId`(= core 铸的子代 childSessionId)—— 转录锚,**不是** prompt。
+     * 委派 prompt 走它:壳侧凭这个 id 去转录读面取首条 user 消息(engineDelegatedPrompt.ts),
+     * 修「详情页 Prompt 段恒空」。缺席 ⇒ 维持现状(诚实留白)。
+     */
+    transcriptId?: string;
+} | {
+    kind: 'end';
+    taskId: string;
+    isError: boolean;
+    /** The subagent's FINAL REPORT — the delegating Task/Agent card's `tool_end.output` text (only the
+     *  explicit close arm carries it; the defensive sweeps settle without one). The consumer persists it
+     *  on the row (task.result) + appends it to a live-viewed transcript (拍1 查看态 seed). */
+    report?: string;
+} | {
+    /** Exception-path safety net (published by seamQuery after every turn, throw or return):
+     *  the consumer settles ALL rows it owns that are still running. Idempotent. */
+    kind: 'sweep';
+};
+export declare function markEnginePanelTaskResident(taskId: string): void;
+export declare function clearEnginePanelTaskResident(taskId: string): void;
+export declare function isEnginePanelTaskResident(taskId: string): boolean;
+type Listener = (ev: EngineAgentPanelEvent) => void;
+export declare function publishEngineAgentPanelEvent(ev: EngineAgentPanelEvent): void;
+/** Single consumer (the panel hook). Replays any buffered events, returns an unsubscribe. */
+export declare function subscribeEngineAgentPanel(fn: Listener): () => void;
+export {};