@sema-agent/client-core 0.3.0 → 0.5.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/engineWireSdk.d.ts

@@ -0,0 +1,49 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/engineWireSdk.ts 逐字搬入(纯半场 client 工厂;agentsWireCaps 的静态依赖,故同批过来)。
+ */
+/**
+ * engineWireSdk — SDK 宪法迁移批(0.0.52)的纯半场 client 工厂:壳内各 wire 子模块(compact/steer/
+ * plan-review/auto-title/recap/caps 探测)从手抄 raw fetch 改接 @sema-agent/sdk AgentClient 的共用
+ * 构造点。ZERO 产品依赖(只 import 外部零依赖 SDK)——agentsWireCaps/liveInitToolFace 等「纯半场/
+ * 零产品图」模块可安全 import,不拖 engineTarget 的 fs 图,亦无循环依赖。
+ *
+ * 凭证解析 = engineTarget.resolveLiveAuthToken 的逐字镜像(#118 三态;那边是产品半场真源,这里为
+ * 纯半场复刻,两处语义必须一致):
+ *   · token 有            → 原样 Bearer;
+ *   · 无 token ∧ loopback → { mode: 'loopback-unauthed' }(出站零 Authorization 头,绝不伪造);
+ *   · 无 token ∧ 非 loopback → 'anon'(fail-closed worker 换来诚实 401;与主车道 replEntry 同姿势)。
+ * ⚠️ 迁移差分记账:旧 raw fetch 在「无 token ∧ 非 loopback」时不带任何 Authorization 头;SDK 恒需
+ * 合法 authToken 形,这里按主车道姿势出 'anon'——该态本就是残破配置(connect 未登录),两种姿势对
+ * fail-closed worker 都是 401,对 owner-gated 路由都是 owner 不匹配,行为面等价。
+ *
+ * 缺省 maxRetries=0:raw fetch 原语义是单发不重试(探针有自己的预算窗;fire-and-forget 不该静默
+ * 翻倍打点)。要 SDK 缺省重试的调用方显式传。principal 缺省 'anon:shell-live'(replEntry live 车道
+ * 同款)——SDK Transport 恒 stamp x-agent-principal(principal-first 宪法);旧 raw fetch 在缺
+ * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
+ */
+import { AgentClient } from '@sema-agent/sdk';
+export type WireAuthToken = string | {
+    mode: 'loopback-unauthed';
+};
+/** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
+export declare function isLoopbackWireUrl(url: string): boolean;
+/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
+export declare function wireAuthTokenFor(baseUrl: string, token?: string): WireAuthToken;
+export type EngineWireClientConfig = {
+    baseUrl: string;
+    /** 真 token 串;缺省经 wireAuthTokenFor 三态解析(loopback-unauthed / 'anon')。 */
+    token?: string;
+    /** 缺省 'anon:shell-live'(replEntry live 车道同款)。 */
+    principal?: string;
+    /** 每次请求的超时预算(SDK 缺省 60s)。 */
+    timeoutMs?: number;
+    /** 缺省 0(raw fetch 单发语义);要 SDK 重试的调用方显式传。 */
+    maxRetries?: number;
+    /** 测试注入面(探针单测的 fetch stub)。 */
+    fetchImpl?: typeof fetch;
+};
+/**
+ * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
+ * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
+ */
+export declare function makeEngineWireClient(cfg: EngineWireClientConfig): AgentClient | null;

package/dist/engineWireSdk.js

@@ -0,0 +1,61 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/engineWireSdk.ts 逐字搬入(纯半场 client 工厂;agentsWireCaps 的静态依赖,故同批过来)。
+ */
+/**
+ * engineWireSdk — SDK 宪法迁移批(0.0.52)的纯半场 client 工厂:壳内各 wire 子模块(compact/steer/
+ * plan-review/auto-title/recap/caps 探测)从手抄 raw fetch 改接 @sema-agent/sdk AgentClient 的共用
+ * 构造点。ZERO 产品依赖(只 import 外部零依赖 SDK)——agentsWireCaps/liveInitToolFace 等「纯半场/
+ * 零产品图」模块可安全 import,不拖 engineTarget 的 fs 图,亦无循环依赖。
+ *
+ * 凭证解析 = engineTarget.resolveLiveAuthToken 的逐字镜像(#118 三态;那边是产品半场真源,这里为
+ * 纯半场复刻,两处语义必须一致):
+ *   · token 有            → 原样 Bearer;
+ *   · 无 token ∧ loopback → { mode: 'loopback-unauthed' }(出站零 Authorization 头,绝不伪造);
+ *   · 无 token ∧ 非 loopback → 'anon'(fail-closed worker 换来诚实 401;与主车道 replEntry 同姿势)。
+ * ⚠️ 迁移差分记账:旧 raw fetch 在「无 token ∧ 非 loopback」时不带任何 Authorization 头;SDK 恒需
+ * 合法 authToken 形,这里按主车道姿势出 'anon'——该态本就是残破配置(connect 未登录),两种姿势对
+ * fail-closed worker 都是 401,对 owner-gated 路由都是 owner 不匹配,行为面等价。
+ *
+ * 缺省 maxRetries=0:raw fetch 原语义是单发不重试(探针有自己的预算窗;fire-and-forget 不该静默
+ * 翻倍打点)。要 SDK 缺省重试的调用方显式传。principal 缺省 'anon:shell-live'(replEntry live 车道
+ * 同款)——SDK Transport 恒 stamp x-agent-principal(principal-first 宪法);旧 raw fetch 在缺
+ * principal 时省略该头,迁移后恒出示,对 requirePrincipal 部署是 fail-open 改善,已记账。
+ */
+import { AgentClient } from '@sema-agent/sdk';
+/** loopback 判定(engineTarget.isLoopbackEngineUrl 逐字镜像;解析失败=非 loopback)。 */
+export function isLoopbackWireUrl(url) {
+    try {
+        const h = new URL(url).hostname;
+        return h === '127.0.0.1' || h === 'localhost' || h === '::1' || h === '[::1]';
+    }
+    catch {
+        return false;
+    }
+}
+/** #118 三态凭证解析(resolveLiveAuthToken 纯半场镜像)。 */
+export function wireAuthTokenFor(baseUrl, token) {
+    if (token)
+        return token;
+    if (isLoopbackWireUrl(baseUrl))
+        return { mode: 'loopback-unauthed' };
+    return 'anon';
+}
+/**
+ * 构造一个引擎 wire 用 AgentClient。null = 构造失败(SDK fail-closed 拒绝——不该发生:
+ * wireAuthTokenFor 恒给合法形;防御性 fail-soft,调用方按各自离线/探测失败路径处理)。
+ */
+export function makeEngineWireClient(cfg) {
+    try {
+        return new AgentClient({
+            baseUrl: cfg.baseUrl,
+            authToken: wireAuthTokenFor(cfg.baseUrl, cfg.token),
+            principal: cfg.principal ?? 'anon:shell-live',
+            ...(cfg.timeoutMs !== undefined ? { timeoutMs: cfg.timeoutMs } : {}),
+            maxRetries: cfg.maxRetries ?? 0,
+            ...(cfg.fetchImpl ? { fetch: cfg.fetchImpl } : {}),
+        });
+    }
+    catch {
+        return null;
+    }
+}

package/dist/forkWireCaps.d.ts

@@ -0,0 +1,25 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/forkWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/forkWireCaps.ts — Fork wire projection: the top-level `TaskRequest.enableFork` boolean →
+ * core fork governance → the model's Agent(subagent_type:"fork") availability (core 1.257 撤除独立
+ * Fork 工具,能力收编进 Agent;CC `subagent_type:fork`: the model forks ITSELF into a subagent that
+ * INHERITS the parent context + shares the prompt cache, vs Task's clean-context subagent).
+ *
+ * DEFAULT = CC parity(clay 2026-07-08 拍板,订正:此前壳里引用的「默认对 LLM 不开」是过时拍板):
+ * core ≥1.257 的 fork 治理是 opt-OUT——enableFork 缺省 = GRANTED(与 CC 一致)。壳默认 **不 stamp**,
+ * 让引擎默认生效(模型默认可用 Agent-fork)。`SEMA_ENABLE_FORK` 保留为显式开关:truthy ⇒ stamp true
+ * (对老引擎 <1.257 也点亮),显式 falsy('0'/'false'/'no'/'off')⇒ stamp false(用户关闭的口子,
+ * service [503]② 的 fail-OPEN 教训:关必须显式 false,缺省不再是"关")。
+ *
+ * PURE — no env/file IO of its OWN (callers pass `env`), so it bundles + unit-tests without the
+ * settings graph. The CALLER (seamQuery / the -p ask) gates the env read to LIVE mode so the mock
+ * request shape never changes.
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The env key the shell reads. SEMA_-namespaced so it never collides with a worker's own deploy env. */
+export declare const ENABLE_FORK_ENV: "SEMA_ENABLE_FORK";
+/** ENV source → explicit `true`/`false` when the user set SEMA_ENABLE_FORK either way, else
+ *  `undefined` (⇒ no stamp ⇒ the engine default applies — GRANTED on core ≥1.257, CC parity). */
+export declare function enableForkFromEnv(env?: EnvLike): boolean | undefined;