@sema-agent/client-core 0.5.0 → 0.7.0

package/dist/request/taskRequest.d.ts

@@ -0,0 +1,135 @@
+/**
+ * request/taskRequest.ts — **请求面合一**(B4,多端改造设计稿 §3 B4 第二件 + §8-5 裁决)。
+ *
+ * ## 它解决的是什么
+ *
+ * 搬迁前壳里有 **三个**独立的请求构造器,谁也不知道对方长什么样:
+ *   · `S/seamQuery.toTaskRequest`(:535-869)—— 交互 REPL 车道;
+ *   · `S/seamQueryEngine`(:546-578)—— headless `-p` 车道,**自己另拼一份**;
+ *   · `S/liveClient.toLiveRequest`(:322-448)—— 两条车道共用的 live 兜底层。
+ *
+ * census §3.4 实测的漂移(B4 复核确认,逐字段见 `REQUEST_FIELD_MATRIX`):
+ *   · **print 独有** `finalVerification` / `limits` / `interactiveTools`;
+ *   · **TUI 独有** `ultracode` / `systemPrompt` / `reasoningEffort` / `images` / `model` /
+ *     rewind 三件 / `clientContext` / `scratchpadDir` / 已解析 settings。
+ * 这不是「两条车道本来就该不同」——里面**一部分是有理由的,一部分纯粹是漏了**。合一的目的不是
+ * 把它们抹平(那是行为改动),而是把「谁有谁没有、为什么」变成**一张表**:再漏就会在 diff 里显形。
+ *
+ * ## 分工铁律
+ *
+ * 🔴 本模块**零 env、零全局状态、零 IO**——所有值由端解析好之后放进 `TaskRequestInput`。
+ * 壳读 `process.env` / `getAppState()` / `getSessionId()` / `process.argv`,web 读 BFF 下发的配置,
+ * 桌面读主进程。包只负责三件**端无关**的事:
+ *   ① **字段集**:哪条车道 stamp 哪些字段(`REQUEST_FIELD_MATRIX`,带逐条理由);
+ *   ② **合并语义**:`settings` 四源合并、objective 的一次性装饰序、sessionId 三态;
+ *   ③ **live 门**:一个 `input.live` 布尔,替掉壳里散落的 20 处 `process.env.SEMA_LIVE_BASEURL` 判读。
+ */
+import type { TaskRequest } from '@sema-agent/sdk';
+/** 请求车道(§8-5:print lane 收编进来,但 stderr 分诊文案与 PrintStreamProjector 留壳)。 */
+export type RequestLane = 'interactive' | 'print';
+/** `TaskRequest` 的可写投影(包内按结构操作;SDK 型只做出口约束)。 */
+export type TaskRequestLike = Record<string, unknown>;
+/**
+ * 字段矩阵的一条 —— **这就是「不许静默统一」的载体**。
+ *
+ * `lanes` 是**事实**(今天哪条车道 stamp 它),`why` 是**理由**(为什么另一条没有)。
+ * 两者分开写:`lanes` 变了会被下面的自洽断言逮住,`why` 让下一棒知道该不该补齐。
+ * `gap:true` = 这条差异**没有正当理由,是漏的**(候补齐;补齐是行为改动,要单独一条测试)。
+ */
+export interface RequestFieldSpec {
+    field: string;
+    lanes: readonly RequestLane[];
+    /** 仅在 live 车道 stamp(mock/pty fixture 车道请求形状恒不变)。 */
+    live: boolean;
+    why: string;
+    gap?: true;
+}
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+export declare const REQUEST_FIELD_MATRIX: readonly RequestFieldSpec[];
+/** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
+export declare const LIVE_DEFAULT_FIELDS: readonly ["cwd", "additionalDirectories", "forwardSubagentEvents", "retainSubagentSessions", "agents", "appendSystemPrompt|settings.outputStyle", "suggestNextPrompts", "compactionModel", "sessionId(三态解析)"];
+/** 端解析好的输入 —— 每一项都是**值**,不是取值方式(取值方式属端)。 */
+export interface TaskRequestInput {
+    /** 本 turn 的模型面输入(已含 slash-skill 正文 / 注入式 meta / 历史种子等端侧组装)。 */
+    objective: string;
+    /** 壳会话 id(单命名空间);print 非 live 车道传 mock 常量。 */
+    sessionId: string;
+    /** live 车道(= 壳的 `process.env.SEMA_LIVE_BASEURL` 判真)。false ⇒ 全部 live-gated 字段不 stamp。 */
+    live: boolean;
+    scenario?: string;
+    systemPrompt?: string;
+    reasoningEffort?: string;
+    model?: string;
+    images?: readonly unknown[];
+    skills?: unknown;
+    mcpServers?: unknown;
+    agents?: unknown;
+    clientContext?: Record<string, unknown>;
+    scratchpadDir?: string;
+    sandboxImageProfile?: string;
+    permissionMode?: string;
+    selfOrchestration?: boolean;
+    deferTools?: readonly string[];
+    retainBackgroundProcesses?: boolean;
+    promptProfile?: string;
+    enableFork?: boolean;
+    attachments?: Record<string, unknown>;
+    finalVerification?: boolean;
+    limits?: Record<string, unknown>;
+    interactiveTools?: false;
+    /** rewind 三件(E18);端自己判空。 */
+    rewind?: Record<string, unknown>;
+    /** `settings` 的四个来源(端各自解析;本模块只负责合并序与「全空则不 stamp」)。 */
+    settings?: {
+        resolved?: Record<string, unknown>;
+        webSearch?: Record<string, unknown>;
+        ultracode?: boolean;
+        hooks?: Record<string, unknown>;
+        outputStyle?: string;
+    };
+}
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export declare function buildTaskRequest(input: TaskRequestInput, lane: RequestLane): TaskRequestLike;
+/** `applyLiveRequestDefaults` 的宿主输入(端解析好的值,同样零取值方式)。 */
+export interface LiveDefaultsInput {
+    cwd?: string;
+    additionalDirectories?: readonly string[];
+    agents?: unknown;
+    /** 引擎 caps 判真 ⇒ 走 `appendSystemPrompt` 一等位;否则借道 `settings.outputStyle`。 */
+    appendSystemPromptCapable: boolean;
+    /** 自我认知块的合并结果(端把既有值传进来,包只决定落哪个位)。 */
+    selfKnowledge?: {
+        forAppend: string;
+        forOutputStyle: string;
+    };
+    /** E12 opt-in(缺省关 —— 开着 = 每个 completed run 后端多跑一次 LLM pass)。 */
+    suggestNextPrompts?: boolean;
+    /** 三重门都过之后的 cheap 槽模型名;端负责 caps + 配置 + 目录同步校验。 */
+    compactionModel?: string;
+    /** 前一 turn 捕获的引擎 session id(连续性最高优先)。 */
+    capturedSessionId?: string;
+    /** 端的 mock session 常量(命中 ⇒ 删 sessionId 让引擎新铸)。 */
+    mockSessionIdConstant?: string;
+    /** 需要从 scenario 位剔除的 mock 关键字。 */
+    mockScenarioKeys?: ReadonlySet<string>;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export declare function applyLiveRequestDefaults(req: TaskRequestLike, host: LiveDefaultsInput): TaskRequestLike;
+/** 出口约束:构造结果确实是一个 `TaskRequest`(型只在这里碰 SDK,运行时零依赖)。 */
+export type BuiltTaskRequest = TaskRequest;

package/dist/request/taskRequest.js

@@ -0,0 +1,176 @@
+/**
+ * 逐字段对照表(B4 从三个构造器**逐行**读出来的,不是设计出来的)。
+ *
+ * 读法:`lanes` 只有一条 = 今天的漂移面;`gap:true` = 我判它是**漏**而不是**设计**。
+ * 🔴 `gap` 是【判断】不是【事实】——补齐任何一条都要按宪法三问单独立项,别当 B4 的收尾顺手做。
+ */
+export const REQUEST_FIELD_MATRIX = [
+    // ── 两条车道都有 ────────────────────────────────────────────────────────────────────────────
+    { field: 'objective', lanes: ['interactive', 'print'], live: false, why: '本 turn 的真实输入,两条车道都必需' },
+    { field: 'sessionId', lanes: ['interactive', 'print'], live: false, why: '单命名空间(TP-A Step 2):壳 id 即引擎 session id;print 在非 live 下保留 mock 常量' },
+    { field: 'scenario', lanes: ['interactive', 'print'], live: false, why: 'TUI 走 selectScenario(objective) 嗅探,print 走 --scenario/SEMA_HEADLESS_SCENARIO 显式值' },
+    { field: 'sandboxImageProfile', lanes: ['interactive', 'print'], live: true, why: '[686]② 显式 profile;auto 档只在 TUI 有(一次性 advisory 进 objective)' },
+    { field: 'permissionMode', lanes: ['interactive', 'print'], live: true, why: 'TUI 读 AppState.toolPermissionContext(带 stampDefault 门),print 读 flag>env(headlessPermissionModeWire)' },
+    { field: 'selfOrchestration', lanes: ['interactive', 'print'], live: true, why: 'SEMA_SELF_ORCHESTRATION opt-in → core 挂 run_workflow' },
+    { field: 'deferTools', lanes: ['interactive', 'print'], live: true, why: '[1052]① Workflow 延迟披露;selfOrchestration 前置门' },
+    { field: 'retainBackgroundProcesses', lanes: ['interactive', 'print'], live: true, why: '缺省 ON(clay 2026-07-26 翻转);SEMA_RETAIN_BACKGROUND=0 逃生' },
+    { field: 'promptProfile', lanes: ['interactive', 'print'], live: true, why: 'core 1.328 呈现轴 A/B 口,缺省不 stamp = 引擎缺省 simple' },
+    { field: 'enableFork', lanes: ['interactive', 'print'], live: true, why: '显式布尔才 stamp([503]② fail-OPEN 教训:off 必须显式)' },
+    { field: 'attachments', lanes: ['interactive', 'print'], live: true, why: 'design/133 + G1 缺省开的 turn 边界 attachment' },
+    { field: 'skills', lanes: ['interactive', 'print'], live: true, why: '本地 .claude/skills 投影;两条车道都由 launchRepl 载入面注入' },
+    { field: 'mcpServers', lanes: ['interactive', 'print'], live: true, why: '本地 .mcp.json 投影;service 单用户门决定是否兑现' },
+    { field: 'settings.webSearch', lanes: ['interactive', 'print'], live: true, why: 'SEMA_WEBSEARCH_* / settings.json;per-request 配置赢过部署 env' },
+    { field: 'settings.hooks', lanes: ['interactive', 'print'], live: true, why: '[495]① 用户 settings 文件 hooks 逐字上 wire' },
+    // ── print 独有(§8-5 认定的**有理由**的差异)──────────────────────────────────────────────
+    { field: 'finalVerification', lanes: ['print'], live: true, why: 'P1-1 终验:无人值守车道才需要引擎自证;交互 REPL 由人当场看结果。#106 裁 B(让位+告知)后交互面默认关' },
+    { field: 'limits', lanes: ['print'], live: true, why: 'P2-3-b:`-p` 的预算护栏(--max-* flag 族),交互 REPL 由人随时 Esc' },
+    { field: 'interactiveTools', lanes: ['print'], live: true, why: '[909]B 件3:无人值守 stamp false,从 roster 源头灭掉 AskUserQuestion/plan 门。交互车道 stamp false 等于自废武功' },
+    // ── TUI 独有 ────────────────────────────────────────────────────────────────────────────────
+    { field: 'settings.ultracode', lanes: ['interactive'], live: true, why: 'design/111:sticky `/effort ultracode` 拨盘 + 当轮关键词嗅探,两个来源都只在交互面存在', gap: true },
+    { field: 'systemPrompt', lanes: ['interactive'], live: false, why: 'CC QueryParams.systemPrompt;print 腿的 params 没有这一位' },
+    { field: 'reasoningEffort', lanes: ['interactive'], live: false, why: '`/effort` 拨盘存在 AppState,print 无 AppState', gap: true },
+    { field: 'model', lanes: ['interactive'], live: false, why: '`/model` 中途换模型读 toolUseContext.options.mainLoopModel;print 的模型走 MODEL_ID/--model 另一条路', gap: true },
+    { field: 'images', lanes: ['interactive'], live: false, why: '贴图提交是交互动作,`-p` 的 stdin 没有图片块' },
+    { field: 'resumeAt/rewindFiles/rewindFilesTo', lanes: ['interactive'], live: false, why: 'E18 `/rewind` 是交互命令' },
+    { field: 'clientContext', lanes: ['interactive'], live: false, why: 'IANA 时区 + 可选邮箱 → core 本地化 `# Environment` 的 today;print 同样跑在用户机器上,缺席让引擎误标 (UTC)', gap: true },
+    { field: 'scratchpadDir', lanes: ['interactive'], live: true, why: '[816]③ per-session 暂存目录;print 也有 session,缺席让 `-p` 的工具写不进 exemptDir', gap: true },
+    { field: 'settings.<resolved>', lanes: ['interactive'], live: true, why: 'settings resolver 的 effective 快照(hooks/env/model + 已解析权限);print 只带 webSearch+hooks 两键', gap: true },
+];
+/** live 兜底层(`toLiveRequest`)追加的字段 —— 两条车道**都**经过,故不进上表。 */
+export const LIVE_DEFAULT_FIELDS = [
+    'cwd',
+    'additionalDirectories',
+    'forwardSubagentEvents',
+    'retainSubagentSessions',
+    'agents',
+    'appendSystemPrompt|settings.outputStyle',
+    'suggestNextPrompts',
+    'compactionModel',
+    'sessionId(三态解析)',
+];
+const laneHas = (field, lane) => REQUEST_FIELD_MATRIX.find(f => f.field === field)?.lanes.includes(lane) ?? false;
+/**
+ * 合一后的请求构造器 —— **按车道出两形**,字段集差异全部由 `REQUEST_FIELD_MATRIX` 决定。
+ *
+ * 🔴 行为纪律:本函数**不做任何统一**。print 没有 `ultracode` 就是没有(表里 `gap:true` 记着账),
+ * 补齐要另立项 —— 在这里顺手加一行,就是把「合一」偷换成「行为改动」。
+ */
+export function buildTaskRequest(input, lane) {
+    const live = input.live;
+    /** stamp 门:字段在本车道的表里 ∧(非 live-gated ∨ 本次是 live 车道)∧ 值非空。 */
+    const on = (field, value) => {
+        if (value === undefined || value === null)
+            return false;
+        const spec = REQUEST_FIELD_MATRIX.find(f => f.field === field);
+        if (spec === undefined)
+            return false;
+        if (!spec.lanes.includes(lane))
+            return false;
+        if (spec.live && !live)
+            return false;
+        return true;
+    };
+    // settings 四源合并(cli 原式:任一存在则 stamp,全缺则整个 `settings` 键都不出现)。
+    // ultracode 只在交互车道进表 ⇒ print 传了也不 stamp(表说了算,不是调用方说了算)。
+    const s = input.settings ?? {};
+    const settingsOut = {
+        ...(laneHas('settings.<resolved>', lane) && live ? (s.resolved ?? {}) : {}),
+        ...(on('settings.webSearch', s.webSearch) ? { webSearch: s.webSearch } : {}),
+        ...(on('settings.ultracode', s.ultracode) ? { ultracode: s.ultracode } : {}),
+        ...(on('settings.hooks', s.hooks) ? { hooks: s.hooks } : {}),
+        ...(s.outputStyle !== undefined ? { outputStyle: s.outputStyle } : {}),
+    };
+    const out = {
+        objective: input.objective,
+        sessionId: input.sessionId,
+        ...(on('scenario', input.scenario) ? { scenario: input.scenario } : {}),
+        ...(on('systemPrompt', input.systemPrompt) ? { systemPrompt: input.systemPrompt } : {}),
+        ...(on('reasoningEffort', input.reasoningEffort) ? { reasoningEffort: input.reasoningEffort } : {}),
+        ...(on('model', input.model) ? { model: input.model } : {}),
+        ...(on('images', input.images) && (input.images?.length ?? 0) > 0 ? { images: input.images } : {}),
+        ...(on('skills', input.skills) ? { skills: input.skills } : {}),
+        ...(on('mcpServers', input.mcpServers) ? { mcpServers: input.mcpServers } : {}),
+        ...(on('resumeAt/rewindFiles/rewindFilesTo', input.rewind) ? input.rewind : {}),
+        ...(on('permissionMode', input.permissionMode) ? { permissionMode: input.permissionMode } : {}),
+        ...(on('sandboxImageProfile', input.sandboxImageProfile)
+            ? { sandboxImageProfile: input.sandboxImageProfile }
+            : {}),
+        ...(on('selfOrchestration', input.selfOrchestration) ? { selfOrchestration: input.selfOrchestration } : {}),
+        ...(on('deferTools', input.deferTools) ? { deferTools: input.deferTools } : {}),
+        ...(on('retainBackgroundProcesses', input.retainBackgroundProcesses)
+            ? { retainBackgroundProcesses: input.retainBackgroundProcesses }
+            : {}),
+        ...(on('promptProfile', input.promptProfile) ? { promptProfile: input.promptProfile } : {}),
+        ...(on('enableFork', input.enableFork) ? { enableFork: input.enableFork } : {}),
+        ...(on('attachments', input.attachments) ? { attachments: input.attachments } : {}),
+        ...(on('clientContext', input.clientContext) ? { clientContext: input.clientContext } : {}),
+        ...(on('scratchpadDir', input.scratchpadDir) ? { scratchpadDir: input.scratchpadDir } : {}),
+        ...(on('finalVerification', input.finalVerification)
+            ? { finalVerification: input.finalVerification }
+            : {}),
+        ...(on('limits', input.limits) ? { limits: input.limits } : {}),
+        ...(on('interactiveTools', input.interactiveTools) && input.interactiveTools === false
+            ? { interactiveTools: false }
+            : {}),
+        ...(Object.keys(settingsOut).length > 0 ? { settings: settingsOut } : {}),
+    };
+    return out;
+}
+/**
+ * live 兜底层(cli `liveClient.toLiveRequest` 的**包内半场**)—— 两条车道共用。
+ *
+ * 🔴 与 cli 的差分记账:cli 版在函数体里直接读 `process.cwd()` / `getAppStateStoreRef()` /
+ * `getLiveModelCatalog()` / `engineCapTrue()`。这些是**取值方式**,全部上移到 `LiveDefaultsInput`。
+ * 「调用方已带值就不覆盖」的语义(cli 每条都是 `if (out.X === undefined)`)在这里逐条保留。
+ */
+export function applyLiveRequestDefaults(req, host) {
+    const out = { ...req };
+    if (out.cwd == null && host.cwd !== undefined)
+        out.cwd = host.cwd;
+    if (out.additionalDirectories === undefined && (host.additionalDirectories?.length ?? 0) > 0) {
+        out.additionalDirectories = [...(host.additionalDirectories ?? [])];
+    }
+    // C1 / design/144:交互与 headless 都常开 —— 不开则引擎不建 SubagentRetainLedger,
+    // 后台子代 SendMessage 唤醒直接 "session was not retained" 拒绝。老引擎按 body→spec 白名单
+    // 忽略未知字段,version-safe。
+    if (out.forwardSubagentEvents === undefined)
+        out.forwardSubagentEvents = true;
+    if (out.retainSubagentSessions === undefined)
+        out.retainSubagentSessions = true;
+    if (out.agents === undefined && host.agents !== undefined)
+        out.agents = host.agents;
+    if (typeof out.scenario === 'string' && host.mockScenarioKeys?.has(out.scenario)) {
+        delete out.scenario;
+    }
+    // 自我认知块双臂([1487]/[1478] R1 终形):caps 判真走一等位,否则借道 outputStyle。
+    // 两臂同一合并序(知识块恒前、调用方块恒后)——序由端在 selfKnowledge 里拼好,包只选位。
+    if (host.selfKnowledge !== undefined) {
+        if (host.appendSystemPromptCapable) {
+            out.appendSystemPrompt = host.selfKnowledge.forAppend;
+        }
+        else {
+            const settings = (out.settings ?? {});
+            out.settings = { ...settings, outputStyle: host.selfKnowledge.forOutputStyle };
+        }
+    }
+    // E12:与 verify/cascade 互斥(那两个返 result 非 streamed run ⇒ 400)。
+    if (out.suggestNextPrompts === undefined &&
+        out.verify === undefined &&
+        out.cascade === undefined &&
+        host.suggestNextPrompts === true) {
+        out.suggestNextPrompts = true;
+    }
+    if (out.compactionModel === undefined && host.compactionModel !== undefined) {
+        out.compactionModel = host.compactionModel;
+    }
+    // 单命名空间三态(cli 逐字):① 已捕获的引擎 session 赢(连续性 —— 引擎 session 绝不在
+    // 会话中途被换掉);③ 还带着 mock 常量 ⇒ 删掉让引擎新铸;② 其余保留(首 turn 壳 id 直传)。
+    if (host.capturedSessionId) {
+        out.sessionId = host.capturedSessionId;
+    }
+    else if (host.mockSessionIdConstant !== undefined &&
+        out.sessionId === host.mockSessionIdConstant) {
+        delete out.sessionId;
+    }
+    return out;
+}

package/dist/sandboxWire.d.ts

@@ -0,0 +1,75 @@
+/**
+ * src/sema/sandboxWire.ts — [686]② `--sandbox` TRI-STATE flag (clay 拍, 2026-07-13): the CLI face of the
+ * per-task SANDBOX IMAGE PROFILE the server already ships end-to-end (`TaskRequest.sandboxImageProfile`
+ * per-task binding + the model-facing `SelectEnvironment` tool + the `GET /v1/images` catalog).
+ *
+ * TRI-STATE (clay 口径):
+ *  a) DEFAULT (no flag)      → NO `sandboxImageProfile` on the POST body — the worker's default image runs.
+ *  b) `--sandbox <profile>`  → EXPLICIT: stamp `sandboxImageProfile` (SDK types.ts:115 → service
+ *     main.ts:2316 resolves profile→digest FAIL-CLOSED with the caller's principal — we only ever send the
+ *     PROFILE, never a digest). Vocabulary = the live catalog (`sema cloud images list` / GET /v1/images) —
+ *     the shell does NOT pre-validate against it (fail-closed admission is the server's job; a typo comes
+ *     back as an honest 404, mapped to a hint by sandboxDegradeHint below).
+ *  c) `--sandbox auto`       → ADVISORY: the submit carries NO profile; instead the FIRST live turn's
+ *     objective is prefixed with an advisory block asking the model to drive the `SelectEnvironment` tool
+ *     itself (list → pick → report `Sandbox: <profile> — <reason>` in its reply, so the choice + reason are
+ *     visible on the run card and correctable by the user). NOT a hard route — server keeps zero new
+ *     endpoints; the tool's session binding takes effect from the NEXT task boundary ([440] F3 contract).
+ *
+ * LANE HONESTY (诚实不撒谎 UI, [686] constraint): the profile only works on the k8s sandbox lane — an
+ * e2b/host-lane worker (including the local TOC self-spawned engine) 400s the submit honestly
+ * (service main.ts:2323 "sandboxImageProfile is only supported on the k8s sandbox backend"). The shell does
+ * NOT pre-judge the lane (no caps sniffing before submit — per [686]: "不预判 lane,收到 400 再提示");
+ * it maps the server's honest reject into a degradation hint (sandboxDegradeHint) rendered on the error row.
+ * So on the local self-spawned engine `--sandbox <profile>` = a LOUD per-turn failure with an actionable
+ * hint — never a silent ignore (silently dropping the user's explicit environment choice would be lying).
+ */
+export type SandboxSelection = {
+    mode: 'default';
+} | {
+    mode: 'auto';
+} | {
+    mode: 'explicit';
+    profile: string;
+};
+export type SandboxParseResult = {
+    ok: true;
+    sel: SandboxSelection;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse `--sandbox` out of an argv slice (everything before a bare `--`; both `--sandbox <v>` and
+ * `--sandbox=<v>` forms). No flag ⇒ `{mode:'default'}`. Repeated flag ⇒ LAST wins (commander convention).
+ * Missing value / flag-shaped value / empty / over-long ⇒ fail-LOUD parse error (never a silent default —
+ * a mis-typed environment choice must not quietly run on the wrong image).
+ */
+export declare function parseSandboxArgv(argv: string[]): SandboxParseResult;
+/** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
+ *  (auto is advisory-by-prompt — the submit itself never carries a profile, per clay's c) 口径). */
+export declare function sandboxRequestFields(sel: SandboxSelection | undefined): {
+    sandboxImageProfile?: string;
+};
+/**
+ * The `--sandbox auto` advisory block. Design choices (each deliberate):
+ *  - Conditional on the tool being mounted: `SelectEnvironment` reaches the model via the deployment's
+ *    `spec.tools` injection (service select-environment-tool.ts RFC A2) — a worker without it must degrade
+ *    HONESTLY (model says so and continues on the default), not hallucinate a selection.
+ *  - The `Sandbox: <profile> — <reason>` reply line IS the run-card echo (可观测可纠正): the tool call
+ *    renders as a normal tool card and the choice+reason line lands in the assistant reply — zero new
+ *    renderer machinery, zero new server endpoints.
+ *  - Boundary honesty: the server applies a session's selection from the NEXT task boundary ([440] F3),
+ *    so the advisory says so — the model must not promise the current turn already runs on the new image.
+ */
+export declare const AUTO_SANDBOX_ADVISORY: string;
+/** Prefix an objective with the auto-select advisory (one-shot — the caller owns the latch). */
+export declare function wrapObjectiveWithAutoSandboxAdvisory(objective: string): string;
+/**
+ * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
+ * Keys on the server's honest reject texts (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
+ * server.ts:4651/4670) — status+substring, the same recognize-by-wire-shape idiom the quota/scenario
+ * copy modules use. The caller renders it under the raw "API Error: …" row (original message preserved —
+ * the hint supplements, never masks, the server's own words).
+ */
+export declare function sandboxDegradeHint(err: unknown): string | undefined;

package/dist/sandboxWire.js

@@ -0,0 +1,138 @@
+/**
+ * src/sema/sandboxWire.ts — [686]② `--sandbox` TRI-STATE flag (clay 拍, 2026-07-13): the CLI face of the
+ * per-task SANDBOX IMAGE PROFILE the server already ships end-to-end (`TaskRequest.sandboxImageProfile`
+ * per-task binding + the model-facing `SelectEnvironment` tool + the `GET /v1/images` catalog).
+ *
+ * TRI-STATE (clay 口径):
+ *  a) DEFAULT (no flag)      → NO `sandboxImageProfile` on the POST body — the worker's default image runs.
+ *  b) `--sandbox <profile>`  → EXPLICIT: stamp `sandboxImageProfile` (SDK types.ts:115 → service
+ *     main.ts:2316 resolves profile→digest FAIL-CLOSED with the caller's principal — we only ever send the
+ *     PROFILE, never a digest). Vocabulary = the live catalog (`sema cloud images list` / GET /v1/images) —
+ *     the shell does NOT pre-validate against it (fail-closed admission is the server's job; a typo comes
+ *     back as an honest 404, mapped to a hint by sandboxDegradeHint below).
+ *  c) `--sandbox auto`       → ADVISORY: the submit carries NO profile; instead the FIRST live turn's
+ *     objective is prefixed with an advisory block asking the model to drive the `SelectEnvironment` tool
+ *     itself (list → pick → report `Sandbox: <profile> — <reason>` in its reply, so the choice + reason are
+ *     visible on the run card and correctable by the user). NOT a hard route — server keeps zero new
+ *     endpoints; the tool's session binding takes effect from the NEXT task boundary ([440] F3 contract).
+ *
+ * LANE HONESTY (诚实不撒谎 UI, [686] constraint): the profile only works on the k8s sandbox lane — an
+ * e2b/host-lane worker (including the local TOC self-spawned engine) 400s the submit honestly
+ * (service main.ts:2323 "sandboxImageProfile is only supported on the k8s sandbox backend"). The shell does
+ * NOT pre-judge the lane (no caps sniffing before submit — per [686]: "不预判 lane,收到 400 再提示");
+ * it maps the server's honest reject into a degradation hint (sandboxDegradeHint) rendered on the error row.
+ * So on the local self-spawned engine `--sandbox <profile>` = a LOUD per-turn failure with an actionable
+ * hint — never a silent ignore (silently dropping the user's explicit environment choice would be lying).
+ */
+/** Mirror of the server's own body validation (server.ts:4651): non-empty, ≤128 chars. Validating locally
+ *  just converts a guaranteed 400 into an immediate CLI error — same rule, earlier and cheaper. */
+const MAX_PROFILE_LEN = 128;
+const USAGE_HINT = "sema: --sandbox expects a profile name or 'auto'.\n" +
+    '  --sandbox <profile>  run on that sandbox image profile (k8s-lane workers; list: sema cloud images list)\n' +
+    '  --sandbox auto       let the model pick via its SelectEnvironment tool (advisory — choice + reason shown in the reply)\n' +
+    '  (no flag)            the worker default image';
+/**
+ * Parse `--sandbox` out of an argv slice (everything before a bare `--`; both `--sandbox <v>` and
+ * `--sandbox=<v>` forms). No flag ⇒ `{mode:'default'}`. Repeated flag ⇒ LAST wins (commander convention).
+ * Missing value / flag-shaped value / empty / over-long ⇒ fail-LOUD parse error (never a silent default —
+ * a mis-typed environment choice must not quietly run on the wrong image).
+ */
+export function parseSandboxArgv(argv) {
+    let sel = { mode: 'default' };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        let raw;
+        if (a === '--sandbox') {
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                return { ok: false, error: USAGE_HINT };
+            }
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith('--sandbox=')) {
+            raw = a.slice('--sandbox='.length);
+        }
+        else {
+            continue;
+        }
+        const v = raw.trim();
+        if (v.length === 0)
+            return { ok: false, error: USAGE_HINT };
+        // audit #17: a bare `--sandbox` EATS the following positional — `-p --sandbox 'say hi'`
+        // consumed the prompt as the profile, then died on an unrelated "Input must be provided…"
+        // error. Profile names never contain whitespace; a value that does is almost certainly the
+        // user's prompt — say exactly that instead of silently mis-parsing.
+        if (/\s/.test(v)) {
+            return {
+                ok: false,
+                error: `Invalid sandbox profile "${v}". Profile names cannot contain spaces — if you meant it as the prompt, ` +
+                    `pass --sandbox a profile name (or 'auto') first, or omit --sandbox to use the worker default image.\n` +
+                    USAGE_HINT,
+            };
+        }
+        if (v.length > MAX_PROFILE_LEN) {
+            return {
+                ok: false,
+                error: `sema: --sandbox profile must be at most ${MAX_PROFILE_LEN} characters (same rule the server enforces).`,
+            };
+        }
+        sel = v === 'auto' ? { mode: 'auto' } : { mode: 'explicit', profile: v };
+    }
+    return { ok: true, sel };
+}
+/** The request-body stamp for a selection: EXPLICIT ⇒ `{sandboxImageProfile}`, default/auto ⇒ nothing
+ *  (auto is advisory-by-prompt — the submit itself never carries a profile, per clay's c) 口径). */
+export function sandboxRequestFields(sel) {
+    return sel?.mode === 'explicit' ? { sandboxImageProfile: sel.profile } : {};
+}
+/**
+ * The `--sandbox auto` advisory block. Design choices (each deliberate):
+ *  - Conditional on the tool being mounted: `SelectEnvironment` reaches the model via the deployment's
+ *    `spec.tools` injection (service select-environment-tool.ts RFC A2) — a worker without it must degrade
+ *    HONESTLY (model says so and continues on the default), not hallucinate a selection.
+ *  - The `Sandbox: <profile> — <reason>` reply line IS the run-card echo (可观测可纠正): the tool call
+ *    renders as a normal tool card and the choice+reason line lands in the assistant reply — zero new
+ *    renderer machinery, zero new server endpoints.
+ *  - Boundary honesty: the server applies a session's selection from the NEXT task boundary ([440] F3),
+ *    so the advisory says so — the model must not promise the current turn already runs on the new image.
+ */
+export const AUTO_SANDBOX_ADVISORY = '<sandbox-auto-select>\n' +
+    'The user launched this session with `--sandbox auto`: choose the best sandbox environment (image profile) for the work in this session yourself.\n' +
+    'If a SelectEnvironment tool is available: call it with no arguments to list the available profiles and their capabilities, then select the one that best fits the task (keep the default if nothing fits better). After deciding, report your choice on its own line, exactly in this form: `Sandbox: <profile> — <one-line reason>` (use `Sandbox: default — <reason>` if you kept the default). Note the selection takes effect from the next task boundary — the current turn keeps the environment it started with.\n' +
+    'If no SelectEnvironment tool is available, briefly say so and continue in the default environment.\n' +
+    '</sandbox-auto-select>';
+/** Prefix an objective with the auto-select advisory (one-shot — the caller owns the latch). */
+export function wrapObjectiveWithAutoSandboxAdvisory(objective) {
+    return `${AUTO_SANDBOX_ADVISORY}\n\n${objective}`;
+}
+/**
+ * Map a submit failure → the sandbox DEGRADATION HINT, or undefined when the error is not sandbox-shaped.
+ * Keys on the server's honest reject texts (ai-agent-service main.ts:2323-2330, per-task-image.ts:52,
+ * server.ts:4651/4670) — status+substring, the same recognize-by-wire-shape idiom the quota/scenario
+ * copy modules use. The caller renders it under the raw "API Error: …" row (original message preserved —
+ * the hint supplements, never masks, the server's own words).
+ */
+export function sandboxDegradeHint(err) {
+    const e = err;
+    if (typeof e?.status !== 'number' || typeof e?.message !== 'string')
+        return undefined;
+    const msg = e.message;
+    if (e.status === 400 && msg.includes('only supported on the k8s sandbox backend')) {
+        return ('--sandbox <profile> only applies on k8s-lane workers; this engine runs a host/e2b sandbox lane, so the request was honestly rejected.\n' +
+            'Re-run without --sandbox (worker default image), or point the shell at a k8s-lane worker (sema cloud engine connect <url>).');
+    }
+    if (e.status === 400 && msg.includes('requires the image index')) {
+        return ('This worker has no sandbox image index configured (sema-registry backend absent), so per-task profiles cannot resolve.\n' +
+            'Re-run without --sandbox, or use a worker with the image index enabled.');
+    }
+    if (e.status === 404 && msg.includes('no published sandbox image for profile')) {
+        return 'No published image matches that profile for your principal. List what you can use: sema cloud images list';
+    }
+    if (e.status === 400 && msg.includes('not supported together with cascade/verify')) {
+        return '--sandbox cannot combine with cascade/verify submits in v1 (the per-task image would not bind to the sub-runs). Drop one of the two.';
+    }
+    return undefined;
+}

package/dist/scenarioWire.d.ts

@@ -0,0 +1,62 @@
+/**
+ * src/sema/scenarioWire.ts — `--scenario <name>` wire (clay 拍, 2026-07-15): expose the engine's
+ * REQUEST-LEVEL scenario routing axis on the headless `-p` path. The server has shipped scenario
+ * routing since day one (ai-agent-service capabilities/scenarios.ts — `TaskRequest.scenario` picks the
+ * tool roster + prompt provider per request: default / code-review / scan / oa / team + center-declared
+ * overlays); the shell simply never exposed the field to users. This module is the CLI face.
+ *
+ * PRECEDENCE (flag > settings > default):
+ *  a) `--scenario <name>` (explicit flag)                 → stamp `TaskRequest.scenario`.
+ *  b) `SEMA_HEADLESS_SCENARIO` env — the settings lane:   → stamp when no flag. Set it in the user
+ *     settings.json `env` block (seeded into process.env by the SAME 1a-envseed both the REPL boot and
+ *     printModeEngine run), the lane every other wire config rides (SEMA_SELF_ORCHESTRATION,
+ *     SEMA_WEBSEARCH_*, SEMA_ENABLE_FORK). One mechanism serves both "env var" and "settings file".
+ *  c) neither                                             → NO stamp = today's behaviour, verbatim.
+ *
+ * VOCABULARY = the server's scenario registry (builtin + center-declared). The shell does NOT
+ * pre-validate against it (the registry is deployment-side truth): an UNKNOWN name falls back to the
+ * `default` scenario server-side (scenarios.ts selectScenario — safe), and a center allowlist violation
+ * comes back as an honest 400 `scenario_not_allowed` (already rendered by scenarioNotAllowedCopy.ts).
+ * We only mirror the server's NAME-SHAPE rule (scenarios.ts:318 SCENARIO_NAME_RE) locally — same rule,
+ * earlier and cheaper, and it keeps prompt-looking values (whitespace etc.) from being eaten as a name.
+ *
+ * NOTE (mock-key shadow): the seam also uses `scenario` as the MOCK transcript selector
+ * (seamQuery.selectScenario / SEMA_SCENARIO). liveClient strips those mock keys before a live forward;
+ * a `--scenario` value that collides with a mock key (e.g. `bash`) is therefore equivalent to `default`
+ * on the live engine — which is exactly what the server would resolve for it anyway (no such scenario).
+ *
+ * SEMA_SCENARIO (the mock harness opt-in — "never spawn a real engine", printModeEngine.ts) is
+ * deliberately NOT reused here: it selects offline mock transcripts, not live engine routing.
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
+export declare const SCENARIO_NAME_RE: RegExp;
+/** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
+export declare const HEADLESS_SCENARIO_ENV = "SEMA_HEADLESS_SCENARIO";
+export type ScenarioParseResult = {
+    ok: true;
+    scenario?: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Parse `--scenario` out of an argv slice (everything before a bare `--`; both `--scenario <v>` and
+ * `--scenario=<v>` forms — the sandboxWire idiom). No flag ⇒ `{ok:true}` with no scenario. Repeated
+ * flag ⇒ LAST wins (commander convention). Missing value / flag-shaped value / name-shape violation ⇒
+ * fail-LOUD parse error (never a silent default — a mis-typed routing choice must not quietly run on
+ * the wrong tool surface; same stance as `--sandbox`).
+ */
+export declare function parseScenarioArgv(argv: string[]): ScenarioParseResult;
+/**
+ * The settings-lane default (`SEMA_HEADLESS_SCENARIO`). FAIL-SOFT on a bad value (stderr warning +
+ * no stamp): a settings-file typo must not hard-brick every headless run the way an explicit flag
+ * typo fails the one run it was typed on.
+ */
+export declare function headlessScenarioFromEnv(env?: EnvLike): string | undefined;
+/**
+ * Resolve the scenario for a headless `-p` submit: explicit `--scenario` flag > `SEMA_HEADLESS_SCENARIO`
+ * settings default > none (= the engine's default scenario, today's behaviour). Flag parse errors
+ * propagate fail-loud; the caller exits.
+ */
+export declare function scenarioForPrint(argv: string[], env?: EnvLike): ScenarioParseResult;