@sema-agent/client-core 0.6.0 → 0.7.0

package/dist/scenarioWire.js

@@ -0,0 +1,115 @@
+/**
+ * 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 { hostEnv } from './hostEnv.js';
+/** Mirror of the server's scenario NAME shape (ai-agent-service scenarios.ts:318). */
+export const SCENARIO_NAME_RE = /^[a-z][a-z0-9-]{1,31}$/;
+/** Settings-lane env knob (settings.json `env` block → 1a-envseed → process.env). */
+export const HEADLESS_SCENARIO_ENV = 'SEMA_HEADLESS_SCENARIO';
+const USAGE_HINT = "sema: --scenario expects a scenario name (lowercase letters/digits/hyphens, starting with a letter, ≤32 chars).\n" +
+    '  --scenario <name>    route this run through the named engine scenario (deployment-defined tool\n' +
+    '                       roster + system prompt; unknown names fall back to the default scenario)\n' +
+    '  (no flag)            the default scenario — today\'s behaviour';
+/**
+ * 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 function parseScenarioArgv(argv) {
+    let scenario;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        let raw;
+        if (a === '--scenario') {
+            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('--scenario=')) {
+            raw = a.slice('--scenario='.length);
+        }
+        else {
+            continue;
+        }
+        const v = raw.trim();
+        // sandboxWire audit #17 lesson: a bare `--scenario` EATS the following positional — a value with
+        // whitespace is almost certainly the user's prompt; say exactly that instead of mis-parsing.
+        if (/\s/.test(v)) {
+            return {
+                ok: false,
+                error: `sema: --scenario got "${v.length > 48 ? `${v.slice(0, 48)}…` : v}" — that looks like your prompt, not a scenario name.\n` +
+                    'Put the flag AFTER the value form (--scenario=<name>) or keep the name and prompt as separate tokens.\n' +
+                    USAGE_HINT,
+            };
+        }
+        if (!SCENARIO_NAME_RE.test(v)) {
+            return { ok: false, error: USAGE_HINT };
+        }
+        scenario = v;
+    }
+    return { ok: true, ...(scenario ? { scenario } : {}) };
+}
+/**
+ * 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 function headlessScenarioFromEnv(env = hostEnv()) {
+    const v = env[HEADLESS_SCENARIO_ENV]?.trim();
+    if (!v)
+        return undefined;
+    if (!SCENARIO_NAME_RE.test(v)) {
+        // eslint-disable-next-line no-console
+        console.error(`[sema] ${HEADLESS_SCENARIO_ENV}="${v}" is not a valid scenario name (want ${String(SCENARIO_NAME_RE)}) — ignoring the settings default`);
+        return undefined;
+    }
+    return v;
+}
+/**
+ * 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 function scenarioForPrint(argv, env = hostEnv()) {
+    const parsed = parseScenarioArgv(argv);
+    if (!parsed.ok)
+        return parsed;
+    if (parsed.scenario)
+        return parsed;
+    const fromEnv = headlessScenarioFromEnv(env);
+    return { ok: true, ...(fromEnv ? { scenario: fromEnv } : {}) };
+}

package/dist/seam.d.ts

@@ -98,6 +98,20 @@ export type ChromeEvent = {
     taskId: string;
     status: string;
     outputPath?: string;
+}
+/**
+ * B5 新臂(#117a,E 层 Bash 分臂的**执行半场**)—— 模型发起的后台 Bash 回执被认出来了。
+ * 判定在库(`detectEngineBgShellReceipt`,纯文案锚定 + `run_in_background` 门);执行留宿主:
+ * 宿主消费义务 = ① 把 registration 发给自己的后台 shell 面板 store(壳 =
+ * `publishEngineBgShellPanelEvent`)② 登记「句柄 → 宿主 run」映射(壳 = `recordBgParentRun(
+ * taskId, getActiveEngineTaskId())`,[1501] A/B 寻址的硬证据)。
+ * 缺席 = ctrl+B 面板看不到这条后台命令(不是报错,是这一面在该宿主上哑掉)。
+ */
+ | {
+    kind: 'bgshell_register';
+    laneProof: LaneProof;
+    taskId: string;
+    registration: unknown;
 } | {
     kind: 'tasks_expand';
     laneProof: LaneProof;
@@ -165,8 +179,11 @@ export type ChromeEvent = {
  *  🔴 配对纪律([paired-mechanisms-must-share-premise]):这两件从「宿主义务」改成「库自持」是
  *     **整臂让位**,不是两边都做——宿主若仍照旧实现,两次 drop/clear 幂等无害,但**记号必须删**,
  *     否则下一棒会以为库没做。
- * 跨通道去重(「补发通道不得再注入模型一遍」)由**适配器自持台账**负责,不摊给宿主——
- * 见 adapt.ts 的 notifiedRuns / workflow_notification_enqueue 臂的发射门。
+ * 跨通道去重(「补发通道不得再注入模型一遍」)由**库自持**,不摊给宿主 —— B5 起台账回到
+ * `notifications.ts` 的 **module 级** `notifiedRunIds` / `cardEnqueuedRunIds`(0.6.0 曾放在适配器
+ * 实例上,与清账/记账的另一半不共享前提 = [1857] 那个缺口)。
+ * 🔴 宿主**不要**再在本臂上调 `markEngineWorkflowNotified` —— 库已在同一位置调过(幂等,
+ *   宿主照调无害,但记号该删:整臂让位,不是两边都做)。
  * 注:面板行 end 事件本身走 panel_task 臂、SubagentStop 走 subagent_lifecycle 臂,不重复。
  */
  | {
@@ -261,6 +278,20 @@ export type ChromeEvent = {
     toolUseId: string;
     input: unknown;
 }
+/**
+ * B5 —— 同一台账的**第二个来源**:core 1.217([379])的 `task` / `task-list` structured 权威全量态。
+ * `source:'tool_use'` 那条是旧引擎兜底(从 input 重建),本条是引擎真实 id 的精确同步。
+ * 宿主消费义务:壳 = `handleEngineTaskStructured(structured)`(两路经 engineToShellTaskId 收敛)。
+ * 🔴 两条**不是**二选一 —— 旧引擎只有前者、新引擎两者都来且后者更准,宿主按幂等处理即可。
+ */
+ | {
+    kind: 'task_ledger_sync';
+    laneProof: LaneProof;
+    source: 'structured';
+    /** `'task' | 'task-list'`(白名单已在库内判过)。 */
+    structuredType: string;
+    structured: unknown;
+}
 /**
  * B3 新臂 ①(T38 三清的第三清 + T57 五处断闸的第五处)—— E12「下一步可问什么」建议**批**。
  * `suggestions: null` = 作废(turn 开场必发一次:上一轮的建议对新上下文是噪声,挂着不掉会让人

package/dist/seam.js

@@ -13,6 +13,7 @@ export const CHROME_ARMS = [
     { kind: 'retry_status', required: false, duty: '渲/清 spinner 的重试覆盖层' },
     { kind: 'panel_task', required: true, duty: 'publishEngineAgentPanelEvent(event) 原样转发' },
     { kind: 'bgshell_settle', required: true, duty: '后台 shell 面板行落终态(含 outputPath)' },
+    { kind: 'bgshell_register', required: true, duty: '后台 shell 面板行建行 + 登记「句柄→宿主 run」' },
     { kind: 'tasks_expand', required: false, duty: '展开 ctrl+t 任务面板' },
     { kind: 'thinking_activity', required: false, duty: '开/收活体 "∴ Thinking…" 行' },
     { kind: 'request_start', required: false, duty: 'spinner 置 requesting 态' },

package/dist/toolResult.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 引擎会在 `tool_end.structured` 顶层 `type` 上发的**全部**取值。
+ * 用途**不是**「只处理这些」——下面的 switch 只认得其中一部分,认不得的照旧走 text 回落;
+ * 用途是「**structured 在场**」这个判据本身:顶层 type 命中白名单 ⇒ 引擎这一版是发结构化的,
+ * 于是模型面正文的**正则反解**(T11 bash / T13+T24 task-output / T14 后台回执三代文案)退位。
+ * 反过来,一个 `{type:'something-else'}` 或裸对象**不算** structured 在场 —— 宁可回落到正则,
+ * 也不许把「有个对象」当成「引擎发了结构化」(判据锚在决定结果的量上:决定的是「该不该信正则」)。
+ * ⚠️ 与设计稿的口径差:任务书写「29 项」,[1840] 清单逐条数是 **30 项**(见交接报告「设计稿错漏」)。
+ */
+export declare const STRUCTURED_DETAIL_TYPES: ReadonlySet<string>;
+/** structured 在场判别:顶层 `type` ∈ 白名单 ⇒ 返回该 type,否则 undefined(= 不在场)。 */
+export declare function structuredDetailType(structured: unknown): string | undefined;
+export declare function modelFacingParseCalls(): number;
+export declare function _resetModelFacingParseCountForTest(): void;
+export declare function parseModelFacingBash(text: string): {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+} | null;
+/**
+ * T12 —— 剥引擎的 `delimitUntrusted` 围栏(core untrusted-text.ts:118)**仅供渲染**。
+ * 围栏是给模型看的注入防护,人类转录卡显示正文(clay 07-03 审计 #1/#9 视觉 bug 的修)。
+ */
+export declare function stripUntrustedFence(text: string): {
+    label: string;
+    body: string;
+} | null;
+/**
+ * T13 回落 —— 引擎 TaskOutput 的模型面正文(core task-registry.ts 的 bash/agent 两形,整体
+ * delimitUntrusted 包裹、label = `TaskOutput <id>`)反解回卡片槽位。`kind` 报哪一形命中,
+ * 'unknown' ⇒ 调用方回落原文。
+ */
+export declare function parseModelFacingTaskOutput(text: string): {
+    kind: 'bash' | 'agent' | 'unknown';
+    taskId?: string;
+    status?: string;
+    output?: string;
+};
+/**
+ * T14 回落 —— 后台回执**三代文案**正则(#117a:core ≥1.283 的 `Command running in background` 是
+ * 第三代)。structured bash 在场时由 `background`/`task_id` 位取代(见 `wireOutputToBody`)。
+ */
+export declare function parseBackgroundReceipt(text: string): {
+    taskId: string;
+} | null;
+/**
+ * T8 —— 压平非均匀 §E1 `output`(`string` | `(Text|Image)[]`)。
+ * ⚠️ 真源在 adapt.ts(A 层 settle 报告也用同一份),本文件只 import,别再写第二份。
+ */
+export type FlattenWireOutput = (output: unknown) => string;
+/** wire 没带 output 时的降级原因码(UI 显示决策留端;客户端绝不编造执行结果)。 */
+export declare const TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT: "wire_carried_no_output";
+export interface ToolResultBody {
+    content: unknown;
+    isError: boolean;
+    toolUseResult?: unknown;
+    /** 只在「wire 没带正文」时出现;在场 = 这张卡**没有真实执行结果**,不是空结果。 */
+    degraded?: typeof TOOL_RESULT_DEGRADED_WIRE_NO_OUTPUT;
+}
+/**
+ * T7 —— `tool_end.output === undefined`(events.d.ts:79 文档化的「工具没有正文」情形)时的卡体。
+ *
+ * cli 旧形:调 mock 注册表 `synthesizeToolIO(name, input)` **反造**一个结果体(stdout/hunks/匹配列表),
+ * 卡片于是显示「看起来像真的、但根本不是这次执行产物」的内容。§8-4 按宪法「诚实优先于产出」裁定
+ * 搬的时候就改掉:**输出诚实缺席 + degraded 标记**,由 UI 决定显示「结果不可用」。
+ * 🔴 `content` 保持**字符串**(件1:tool_result block content 恒字符串,裸对象经 /compact 直发
+ * provider = 400 invalid_request);空串 = 无正文,`degraded` 才是判别位。
+ */
+export declare function degradedToolResultBody(isError: boolean): ToolResultBody;
+/**
+ * 真实 §E1 `tool_end.output` → 卡片读的 typed 正文。
+ *
+ * B5 新增第 5 个入参 `structured`:**structured 在场 ⇒ 正则退位**(①)。
+ * 三臂:`bash`(T11/T14)· `taskoutput|task_output`(T13,无 structured 的老腿)· 泛化兜底。
+ * 🔴 `truncated` 只做中性提示,截断正文**绝不**回喂模型(events.d.ts:80-85)。
+ */
+export declare function wireOutputToBody(toolName: string, output: unknown, isError: boolean, truncated: boolean, flatten: FlattenWireOutput, structured?: unknown): ToolResultBody;
+/**
+ * design/64 CC-parity `toolUseResult`:引擎结构化细节 → 各卡 outputSchema **精确** typed 形
+ * (safeParse 过了才渲富卡,不过就回落 12 行文本兜底)。
+ * `structuredPatch` 在**这里**算(T20,core 裁定:引擎发 originalFile、客户端算 hunks)。
+ * 全部**防御读**:形状不认得 ⇒ null ⇒ 调用方回落 text 路径(降保真,绝不炸)。
+ */
+export declare function structuredToToolUseResult(structured: unknown, 
+/** 压平后的模型面正文 —— 有些形(task-output)只带 identity/status,正文仍在模型面。 */
+modelText?: string): {
+    toolUseResult: unknown;
+    isError?: boolean;
+} | null;
+export interface EngineBgShellRegistration {
+    kind: 'register';
+    /** 回执上的**引擎** task id(`task_id=…`,TaskOutput/TaskStop 的句柄)。 */
+    taskId: string;
+    /** Bash tool_use input 的 command(面板行的命令行)。 */
+    command: string;
+    /** 模型给了 description 才有。 */
+    description?: string;
+    /** 引擎模型面回执原文,逐字 —— 详情视图显示它(里面的 output-file 路径因此可见可复制)。 */
+    receipt: string;
+}
+export declare function detectEngineBgShellReceipt(rawInput: unknown, outputText: string | undefined): EngineBgShellRegistration | null;
+/**
+ * TodoWrite 清单卡:引擎不发 todo structured,全量新表骑在 tool_use INPUT 上 ⇒ 从它合成 typed 结果。
+ * `oldTodos` = 上一次的活体清单(调用方持:一个 session 一份,正是划删线 diff 要的粒度)。
+ */
+export declare function todoWriteToolUseResult(rawInput: unknown, oldTodos: unknown[], isError: boolean): {
+    toolUseResult: unknown;
+    isError: boolean;
+    newTodos: unknown[];
+} | null;
+/**
+ * ReportFindings(core 1.288 [811]b,引擎侧执行的合成回声工具):details 是 `{count, level?, findings}`
+ * **没有 type 判别位**(core synthetic-tools.js)⇒ B 层的 type-keyed switch 认领不了,按**工具名**认。
+ * 双腿:优先 wire structured;引擎没发就从 tool_use INPUT 合成(回声工具:input.findings ≡ output.findings)。
+ */
+export declare function reportFindingsToolUseResult(structured: unknown, rawInput: unknown): {
+    toolUseResult: unknown;
+} | null;