@sema-agent/client-core 0.3.0 → 0.5.0

package/dist/sseIdleTriage.js

@@ -0,0 +1,142 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/sseIdleTriage.ts 逐字搬入(只 import SDK)。
+ */
+/**
+ * src/sema/sseIdleTriage.ts — turn-stream SSE idle-silence triage(TB2.0 反馈批 D · P0-2 壳半场,2026-07-15)。
+ *
+ * WHY: TB2.0 bench 真实案例 —— agent 长跑前台编译 ~9.5min,工具完成前壳侧 45s 空闲监测器
+ * (`@sema-agent/sdk` readSseFrames HEARTBEAT_GRACE_MS)命中 `SSE: no data for 45000ms (heartbeat
+ * silence)` → 整轮 rc=1 丢弃,引擎不知情继续跑完(access log 499)。分诊报告判决①修正段拍定:
+ * 壳侧独立可发 = S1(SDK grace 透传+typed SseIdleError,0.0.47 已发)+ S4(grace 旋钮)+
+ * S3 缩水版(engine-alive-idle 分诊,只改报错文案,不重连)。本模块 = S4 + S3 的共享件。
+ *
+ * S4 · SEMA_SSE_HEARTBEAT_GRACE_MS(settings.json `env` 块 → 1a-envseed → process.env,其它 wire
+ * 旋钮同一车道):整数毫秒,合法域 [5000, 600000];非法/缺省 = 不透传(SDK 默认 45s)——静默
+ * fail-soft,一个 settings typo 绝不 brick 任何 run(scenarioWire settings-lane 纪律)。
+ * ⚠️ 作用面 = 会话 turn 流(tasks.stream / liveClient)一条车道。SDK 控制通道(SSETransport.ts:21
+ * LIVENESS_TIMEOUT_MS=45s)自带重连+give-up 自愈,本旋钮【不】达那条车道——这不是全局 grace。
+ *
+ * S3 缩水版 · engine-alive-idle 分诊:liveClient 的 tasks.stream 包装 catch 到 SseIdleError 时,
+ * 先判 signal.aborted(用户中止契约先行,seamQuery.ts:1073——Esc 撕流绝不被分诊吞),再 GET
+ * `/health`(非 /healthz;server dist server.js:290)短超时探引擎活性:引擎死 → 原样抛(现行
+ * engine-down/not-restart 路径不变);引擎活 → 给同一错误对象打 engine-alive-idle 标记,
+ * seamQuery 的 tearVerdict 恢复腿据此渲染诚实分诊文案(engineAliveIdleContent)。
+ *
+ * 【本模块绝不重连】(判决①修正段圣旨,范围随 M2 精化):非 detach 车道上 tasks/stream 客户端
+ * 断连 = server onDisconnect ac.abort() 终止 run(anti token-burn by design),且该车道帧无 id
+ * 不可位置续传——空闲监测器抛出的那一刻 finally 已 cancel res.body,run 已被这次断连自身中止,
+ * 同 key in-flight 重放拿到的只是 aborted 结局。前台另有既有裁决:mid-turn 工具副作用非幂等,
+ * 绝不自动重发。引擎 E2(server ≥1.196 x-detach-on-disconnect,[854]①)已到货:headless `-p`
+ * detach 车道的 R1 换道重连 = 重连腿 M2,住在 headlessReconnectWire.ts(liveClient 管线最内层,
+ * 只在 detach 头已发出的流上武装);本模块保持「探活+打标,不重连」——交互 REPL 与一切非
+ * detach 车道的取消契约一根毛不动,M2 耗尽预算后判死文案也仍由这里的打标驱动。
+ */
+import { hostEnv } from './hostEnv.js';
+import { SseIdleError, probeHealth as sdkProbeHealth } from '@sema-agent/sdk';
+/** Settings-lane env knob(settings.json `env` 块 → 1a-envseed → process.env)。整数毫秒。 */
+export const SSE_HEARTBEAT_GRACE_ENV = 'SEMA_SSE_HEARTBEAT_GRACE_MS';
+/** 合法域下界:低于 5s 会把正常 token 间隙误判成静默。 */
+export const SSE_GRACE_MIN_MS = 5_000;
+/** 合法域上界:10min——超过引擎自身各级 idle 顶,再长没有意义。 */
+export const SSE_GRACE_MAX_MS = 600_000;
+/** SDK 默认(readSseFrames HEARTBEAT_GRACE_MS)——文案引用用,不在本模块生效。 */
+export const SDK_DEFAULT_GRACE_MS = 45_000;
+/**
+ * S4 — resolve the turn-stream heartbeat grace override. Unset/empty → undefined(SDK 默认 45s,
+ * 不透传);非纯十进制整数 / 超出 [5000,600000] → undefined(静默落默认,fail-soft)。
+ */
+export function resolveSseHeartbeatGraceMs(env = hostEnv()) {
+    const raw = env[SSE_HEARTBEAT_GRACE_ENV]?.trim();
+    if (!raw)
+        return undefined;
+    if (!/^\d+$/.test(raw))
+        return undefined; // 纯十进制整数——'45e3'/'45000.5'/'-1' 全部落默认
+    const n = Number(raw);
+    if (!Number.isSafeInteger(n) || n < SSE_GRACE_MIN_MS || n > SSE_GRACE_MAX_MS)
+        return undefined;
+    return n;
+}
+/** 给 SseIdleError 打 engine-alive-idle 标(引擎 /health 已确认活着)。返回同一对象。 */
+export function markEngineAliveIdle(err) {
+    ;
+    err.semaTearVerdict = 'engine-alive-idle';
+    return err;
+}
+/**
+ * engine-alive-idle 判型:命中返回静默时长 elapsedMs(SseIdleError 0.0.47 自带;缺失兜 0),
+ * 未命中返回 undefined。seamQuery tearVerdict 腿与 headless `-p` 的 stderr 面共用。
+ */
+export function engineAliveIdleElapsedMs(err) {
+    const e = err;
+    if (!e || e.semaTearVerdict !== 'engine-alive-idle')
+        return undefined;
+    return typeof e.elapsedMs === 'number' && Number.isFinite(e.elapsedMs) ? e.elapsedMs : 0;
+}
+/**
+ * SseIdleError 判型:instanceof 为主;双包风险(bundle 内外两份 SDK class identity 分叉)下
+ * name 兜底——name 由 SDK 构造器冻结为 'SseIdleError',非我方铸造。
+ */
+export function isSseIdleError(err) {
+    if (err instanceof SseIdleError)
+        return true;
+    return err?.name === 'SseIdleError';
+}
+/**
+ * 引擎活性探针 — SDK probeHealth(GET `${baseUrl}/health`;端点是 /health 非 /healthz),默认 2s
+ * 预算,永不抛:alive = 200 且 status==='ok';非 2xx / 不可达 / 超时 = not alive(引擎死 → 现行
+ * 失败路径,分诊绝不让真死引擎空等)。与 engineUpgradeCoordinator 的 classifyStreamTear 同款姿势。
+ * SDK 宪法迁移批差分记账:原实现只看 res.ok(200 非 JSON / status!=='ok' 也判活);SDK 额外要
+ * status==='ok'——service /health 200 恒报 status:'ok',契约面等价,对「200 但引擎自述非 ok」的
+ * 病态更严格诚实。
+ */
+export async function probeEngineAlive(baseUrl, timeoutMs = 2_000) {
+    return (await sdkProbeHealth(baseUrl, timeoutMs)).alive;
+}
+/**
+ * S3 缩水版 — the tasks.stream diagnose wrapper(liveClient 出口整流罩)。
+ * 透传 inner 的每个事件;仅当 inner 以 SseIdleError 收场时介入:
+ *   1. signal.aborted 先行 — 用户中止(Esc)撕流原样抛,绝不探活/绝不改判(seamQuery.ts:1073 契约);
+ *   2. GET /health 探引擎活性(2s 预算);
+ *   3. 引擎活 → 同一错误对象打 engine-alive-idle 标后重抛(下游 tearVerdict 腿改文案;detach `-p`
+ *      车道的 R1 重连发生在更内层的 headlessReconnectWire——错误能到这里 = 重连已耗尽/不可换道);
+ *      引擎死/探测失败 → 原样重抛(现行 classifyStreamTear 会诚实判 engine-down)。
+ * 非 SseIdleError 一律原样穿透。
+ */
+export async function* diagnoseSseIdleTear(inner, baseUrl, signal) {
+    try {
+        yield* inner;
+    }
+    catch (err) {
+        if (!signal?.aborted && isSseIdleError(err) && (await probeEngineAlive(baseUrl))) {
+            throw markEngineAliveIdle(err);
+        }
+        throw err;
+    }
+}
+/**
+ * engine-alive-idle 的用户可见分诊文案(升级自裸 "API Error: SSE: no data for …" 行)。
+ * 措辞如实(判决②契约),按 detach 态分叉:
+ *  · 非 detach(默认/旋钮关/版本门拒/交互车道):tasks/stream 断连 = server 端 abort 这次 run——
+ *    不许说"任务仍在继续"的安慰话;能给的出路只有 grace 旋钮 + 手动重发。字节与批 D 发运稿一致
+ *    (存量脚本可能 grep)。
+ *  · detach 态(重连腿 M1,`x-detach-on-disconnect: true` 已随首次 POST 发出,server ≥1.196):
+ *    断连【不再】abort run——run 已 detach,引擎会把它后台跑完并落 durable 账本;文案如实改述并
+ *    指 `GET /v1/runs/<id>`(taskId 已知时带上)/ `sema resume` 查终局。M1 不重连(M2/M3),
+ *    本轮前台 rc 仍非零——这是净改善:结果不再整轮丢弃。
+ */
+export function engineAliveIdleContent(elapsedMs, detach) {
+    const secs = Math.max(1, Math.round((elapsedMs > 0 ? elapsedMs : SDK_DEFAULT_GRACE_MS) / 1000));
+    const graceTail = `If your tasks legitimately go quiet this long (e.g. a long build), raise the idle grace: set ${SSE_HEARTBEAT_GRACE_ENV} ` +
+        `(settings env, integer ms, ${SSE_GRACE_MIN_MS}-${SSE_GRACE_MAX_MS}; default ${SDK_DEFAULT_GRACE_MS}).`;
+    if (detach?.detached) {
+        const runRef = detach.taskId ? `GET /v1/runs/${detach.taskId}` : 'GET /v1/runs/<task-id>';
+        return (`The engine is still running, but this turn's event stream went silent for ${secs}s, so the connection was closed as idle. ` +
+            `This run was DETACHED (x-detach-on-disconnect): the disconnect did NOT abort it — the engine keeps running it to completion in the background ` +
+            `and records the outcome durably. Check the final result with \`${runRef}\` on the engine, or \`sema resume\` to pick the session back up. ` +
+            graceTail);
+    }
+    return (`The engine is still running, but this turn's event stream went silent for ${secs}s, so the connection was closed as idle — ` +
+        `and closing the stream aborts the run on the engine side (this turn did NOT finish; a long-running tool may have been killed mid-flight). ` +
+        graceTail +
+        ` The session is intact — resend the prompt to retry.`);
+}

package/dist/ultracodeWireCaps.d.ts

@@ -0,0 +1,90 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/ultracodeWireCaps.ts 逐字搬入(零依赖;🔴 模块级 ultracodePreset 是 sticky 单实例态,写口 setUltracodePreset 与读口 ultracodeForWire 必须同实例)。
+ */
+/**
+ * src/sema/ultracodeWireCaps.ts — the shell's TWO opt-in sources for the CC-parity `settings.ultracode` PRESET,
+ * projected onto `TaskRequest.settings.ultracode` (a typed boolean the SERVICE — ai-agent-service 1.48.0 — reads
+ * and EXPANDS to `thinking:"max"` + `selfOrchestration:true`; both core's existing orthogonal axes, fail-closed
+ * gates unchanged). design/111 (core/search AI 2026-06-30): ultracode is a STANDALONE settings boolean folding
+ * "max thinking × workflow orchestration", surfaced in sema as the top notch of the `/effort` dial.
+ *
+ * Two sources, ONE structured-spec output (`settings.ultracode:true` — never prompt text):
+ *
+ *  ① L2 dial preset (STICKY): the `/effort ultracode` pick. The effort dial COERCES the reasoning axis to `xhigh`
+ *     (overrides/effort.tsx executeEffortSema — "ultracode runs at xhigh effort"), which would LOSE the
+ *     orchestration axis. So the dial separately latches this module-level preset: ON when `ultracode` is picked,
+ *     OFF when any OTHER effort level is picked (a sticky session setting, like CC's settings.ultracode boolean).
+ *
+ *  ② L3 keyword (PER-TURN): a client-side scan of the REAL human turn input for the literal word "ultracode".
+ *     🔴 RED LINE (design/111 L3, the ONLY injection risk): scan ONLY the human's current-turn submission, BEFORE
+ *     any untrusted content (tool results / file reads / web / subagent / MCP) is concatenated. NEVER scan the
+ *     assembled prompt server-side — a malicious file containing "ultracode" would be a privilege-escalation
+ *     injection. The keyword is a UX convenience switch, NOT a security decision point: privilege STILL passes the
+ *     service's fail-closed per-principal `allowWorkflows` gate (core deliberately refuses prompt scanning,
+ *     prepare-task.ts:1612 — that boundary is correct). The output is a STRUCTURED spec (the boolean), never
+ *     injected prompt text.
+ *
+ * Both sources are OR'd live-side by `toTaskRequest`; the SAME `SEMA_LIVE_BASEURL` gate the other capability wires
+ * use keeps the mock request shape unchanged (the stamp IS the opt-in; absent ⇒ the engine never expands ultracode).
+ *
+ * The PRESET state is module-level (mirrors seamQuery's seam* injectors): the dial (a React override) latches it,
+ * the seam reads it. The KEYWORD scan is a PURE function (caller passes the human input) so it bundles + unit-tests
+ * without React/AppState.
+ */
+import { type EnvLike } from './hostEnv.js';
+/** Latch the dial preset. `effort.tsx` calls this whenever an effort level is APPLIED: `true` for the `ultracode`
+ *  notch, `false` for every other level (so switching the dial OFF ultracode clears the workflow-orchestration axis
+ *  while the reasoning axis follows the picked level). */
+export declare function setUltracodePreset(on: boolean): void;
+/** Read the sticky dial preset (the L2 source). */
+export declare function getUltracodePreset(): boolean;
+/** Test/boot reset — clears the latched preset (e.g. a fresh session). */
+export declare function _resetUltracodePreset(): void;
+/**
+ * L3 keyword source: `true` iff the REAL human turn input contains the "ultracode" keyword, else `undefined`.
+ * 🔴 The caller MUST pass ONLY the human's current-turn submission (seamQuery's `objective`, derived from the
+ * projectable user message) — NOT any assembled/untrusted content. Returns `true | undefined` (never `false`) to
+ * mirror the strict additive-stamp discipline of the other wire caps (a stamped `false` would needlessly change
+ * the default request shape).
+ */
+export declare function ultracodeFromInput(humanInput: string | undefined): true | undefined;
+/**
+ * Combine the two sources into the structured spec the seam stamps. `true` when EITHER the sticky dial preset is on
+ * OR the human's current-turn input contains the keyword; otherwise `undefined` (⇒ no stamp ⇒ default behaviour).
+ * Returns `true | undefined` so the seam can spread `...(ultracode ? { ultracode } : {})` without changing the
+ * default request shape. The CALLER gates this to LIVE mode (mock parity).
+ */
+export declare function ultracodeForRequest(humanInput: string | undefined): true | undefined;
+export declare function workflowFromInput(humanInput: string | undefined): true | undefined;
+/** Env escape hatch for the deferred-Workflow factory default: `SEMA_WORKFLOW_DEFER=0/false/no/off` restores the
+ *  pre-[1052] always-exposed shape (schema bytes back in the prefix). Anything else (incl. unset) = defer ON. */
+export declare const WORKFLOW_DEFER_ENV: "SEMA_WORKFLOW_DEFER";
+/**
+ * [1052]① 收官形(clay 裁 B 的 core deferred 机制件,cli 接线半场):Workflow「全局默认开但不暴露」——
+ * 未命中激活源的 TaskRequest 带 `deferTools:["Workflow"]`(core 1.314 对已挂载工具做 design/36 延迟披露:
+ * 占位符上 wire、schema 字节撤出缓存前缀、ToolSearch 可激活=中途激活通路);命中任一激活源 ⇒ `undefined`
+ * (不 defer=名字+schema 全量上 wire):
+ *   a) 用户当轮说 "workflow"(workflowFromInput,只扫真人输入);
+ *   b) "ultracode" 关键词(L3,同一红线);
+ *   c) `/effort ultracode` sticky dial(L2 preset)。
+ * CALLER 前置两门:live 门(mock 形不变)+ selfOrchestration stamp 存在(opt-out 时 Workflow 根本不挂载,
+ * defer 无意义)。前缀缓存注记:defer↔不 defer 的翻转只发生在真人激活当轮,与 CC 209 ToolSearch materialize
+ * 同一形——非激活轮的前缀指纹稳定([1044]② clay 硬约束 ii 的解)。
+ */
+export declare function workflowDeferForRequest(humanInput: string | undefined, env?: EnvLike): ['Workflow'] | undefined;
+/** [1077]④ 低频工具惰性注入:`SEMA_DEFER_TOOLS=<csv>`(wire 名)追加进 deferTools(core 1.314
+ *  延迟披露腿)。**缺省翻转已裁(clay [1212]⑤,2026-07-19)**:九件低频工具缺省 defer——判决数=
+ *  -2,484 tok/首调用+多轮 gate 零行为退化;defer≠禁用(占位符在,模型 ToolSearch 随取)。
+ *  逃生门:`SEMA_DEFER_LOWFREQ=0/false/no/off` 关缺省名单(九件恢复全量上前缀)。 */
+export declare const DEFER_TOOLS_ENV: "SEMA_DEFER_TOOLS";
+export declare const DEFER_LOWFREQ_ENV: "SEMA_DEFER_LOWFREQ";
+/** clay 裁定的缺省惰性名单([1076]④ 评测九件原单,[1090]② 判决数)。 */
+export declare const DEFAULT_LOWFREQ_DEFER: readonly string[];
+/**
+ * The FULL deferTools list for a request: the Workflow default-defer lane (activation sources, see
+ * {@link workflowDeferForRequest}) + the DEFAULT low-frequency list (clay [1212]⑤, opt-out via
+ * SEMA_DEFER_LOWFREQ) + the SEMA_DEFER_TOOLS extra list, deduped. An activation hit removes ONLY
+ * Workflow (the user asked for it by name); the other lanes are source-independent. Empty ⇒
+ * `undefined` (no stamp, request shape unchanged).
+ */
+export declare function deferToolsForRequest(humanInput: string | undefined, env?: EnvLike): string[] | undefined;

package/dist/ultracodeWireCaps.js

@@ -0,0 +1,159 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/ultracodeWireCaps.ts 逐字搬入(零依赖;🔴 模块级 ultracodePreset 是 sticky 单实例态,写口 setUltracodePreset 与读口 ultracodeForWire 必须同实例)。
+ */
+/**
+ * src/sema/ultracodeWireCaps.ts — the shell's TWO opt-in sources for the CC-parity `settings.ultracode` PRESET,
+ * projected onto `TaskRequest.settings.ultracode` (a typed boolean the SERVICE — ai-agent-service 1.48.0 — reads
+ * and EXPANDS to `thinking:"max"` + `selfOrchestration:true`; both core's existing orthogonal axes, fail-closed
+ * gates unchanged). design/111 (core/search AI 2026-06-30): ultracode is a STANDALONE settings boolean folding
+ * "max thinking × workflow orchestration", surfaced in sema as the top notch of the `/effort` dial.
+ *
+ * Two sources, ONE structured-spec output (`settings.ultracode:true` — never prompt text):
+ *
+ *  ① L2 dial preset (STICKY): the `/effort ultracode` pick. The effort dial COERCES the reasoning axis to `xhigh`
+ *     (overrides/effort.tsx executeEffortSema — "ultracode runs at xhigh effort"), which would LOSE the
+ *     orchestration axis. So the dial separately latches this module-level preset: ON when `ultracode` is picked,
+ *     OFF when any OTHER effort level is picked (a sticky session setting, like CC's settings.ultracode boolean).
+ *
+ *  ② L3 keyword (PER-TURN): a client-side scan of the REAL human turn input for the literal word "ultracode".
+ *     🔴 RED LINE (design/111 L3, the ONLY injection risk): scan ONLY the human's current-turn submission, BEFORE
+ *     any untrusted content (tool results / file reads / web / subagent / MCP) is concatenated. NEVER scan the
+ *     assembled prompt server-side — a malicious file containing "ultracode" would be a privilege-escalation
+ *     injection. The keyword is a UX convenience switch, NOT a security decision point: privilege STILL passes the
+ *     service's fail-closed per-principal `allowWorkflows` gate (core deliberately refuses prompt scanning,
+ *     prepare-task.ts:1612 — that boundary is correct). The output is a STRUCTURED spec (the boolean), never
+ *     injected prompt text.
+ *
+ * Both sources are OR'd live-side by `toTaskRequest`; the SAME `SEMA_LIVE_BASEURL` gate the other capability wires
+ * use keeps the mock request shape unchanged (the stamp IS the opt-in; absent ⇒ the engine never expands ultracode).
+ *
+ * The PRESET state is module-level (mirrors seamQuery's seam* injectors): the dial (a React override) latches it,
+ * the seam reads it. The KEYWORD scan is a PURE function (caller passes the human input) so it bundles + unit-tests
+ * without React/AppState.
+ */
+import { hostEnv } from './hostEnv.js';
+/** STICKY L2 preset: latched ON by the `/effort ultracode` dial pick, OFF by any other effort pick. Module-level
+ *  (one shell process = one session) — the same single-namespace assumption seamQuery's session state uses. */
+let ultracodePreset = false;
+/** Latch the dial preset. `effort.tsx` calls this whenever an effort level is APPLIED: `true` for the `ultracode`
+ *  notch, `false` for every other level (so switching the dial OFF ultracode clears the workflow-orchestration axis
+ *  while the reasoning axis follows the picked level). */
+export function setUltracodePreset(on) {
+    ultracodePreset = on === true;
+}
+/** Read the sticky dial preset (the L2 source). */
+export function getUltracodePreset() {
+    return ultracodePreset;
+}
+/** Test/boot reset — clears the latched preset (e.g. a fresh session). */
+export function _resetUltracodePreset() {
+    ultracodePreset = false;
+}
+/** Word-boundary, case-insensitive scan for the literal keyword. A bare mention ("ultracode") anywhere in the
+ *  human's own turn text counts (CC-style UX toggle); the server's `allowWorkflows` gate is the real guard, so a
+ *  false-positive (the user discussing the word) only requests the preset — it cannot escalate past the gate. */
+const ULTRACODE_KEYWORD = /\bultracode\b/i;
+/**
+ * L3 keyword source: `true` iff the REAL human turn input contains the "ultracode" keyword, else `undefined`.
+ * 🔴 The caller MUST pass ONLY the human's current-turn submission (seamQuery's `objective`, derived from the
+ * projectable user message) — NOT any assembled/untrusted content. Returns `true | undefined` (never `false`) to
+ * mirror the strict additive-stamp discipline of the other wire caps (a stamped `false` would needlessly change
+ * the default request shape).
+ */
+export function ultracodeFromInput(humanInput) {
+    return typeof humanInput === 'string' && ULTRACODE_KEYWORD.test(humanInput) ? true : undefined;
+}
+/**
+ * Combine the two sources into the structured spec the seam stamps. `true` when EITHER the sticky dial preset is on
+ * OR the human's current-turn input contains the keyword; otherwise `undefined` (⇒ no stamp ⇒ default behaviour).
+ * Returns `true | undefined` so the seam can spread `...(ultracode ? { ultracode } : {})` without changing the
+ * default request shape. The CALLER gates this to LIVE mode (mock parity).
+ */
+export function ultracodeForRequest(humanInput) {
+    return getUltracodePreset() || ultracodeFromInput(humanInput) ? true : undefined;
+}
+/** [1044]②裁 B 激活源 a(clay 拍):用户当轮说 "workflow"(词边界、大小写不敏感)⇒ 该 turn 激活
+ *  Workflow 暴露。与 ultracode 线同一注入红线:只扫真人当轮输入(objective),绝不扫组装后内容。
+ *  消费接线=[1052]① 收官形(workflowDeferForRequest,core 1.314 deferTools 首班到货后点亮)。
+ *  [1486] 词表扩(2026-07-21,「启动 Agent Team 走成三 fork」白盒定谳):多 agent 语义族也激活——
+ *  run_workflow 描述里的路由映射句(multi-agent orchestration…fan out agents)defer 后模型读不到,
+ *  「agent team/multi-agent/swarm/多agent/编排」类输入落进可见工具面的理性变通(三 fork)。命中即
+ *  当轮全量上 wire(翻转只发生在激活当轮,前缀缓存语义不变)。终态=Agent Team 真入口(案A,
+ *  [1484]/[1485])落地后此词有真归宿,本词表是过渡补丁。 */
+const WORKFLOW_KEYWORD = /\bworkflows?\b|\bagent[ -]?teams?\b|\bmulti[ -]?agent\b|\bswarms?\b|多\s?agent|多智能体|编排/i;
+export function workflowFromInput(humanInput) {
+    return typeof humanInput === 'string' && WORKFLOW_KEYWORD.test(humanInput) ? true : undefined;
+}
+/** Env escape hatch for the deferred-Workflow factory default: `SEMA_WORKFLOW_DEFER=0/false/no/off` restores the
+ *  pre-[1052] always-exposed shape (schema bytes back in the prefix). Anything else (incl. unset) = defer ON. */
+export const WORKFLOW_DEFER_ENV = 'SEMA_WORKFLOW_DEFER';
+function deferOptedOut(env) {
+    const raw = env[WORKFLOW_DEFER_ENV];
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    return s === '0' || s === 'false' || s === 'no' || s === 'off';
+}
+/**
+ * [1052]① 收官形(clay 裁 B 的 core deferred 机制件,cli 接线半场):Workflow「全局默认开但不暴露」——
+ * 未命中激活源的 TaskRequest 带 `deferTools:["Workflow"]`(core 1.314 对已挂载工具做 design/36 延迟披露:
+ * 占位符上 wire、schema 字节撤出缓存前缀、ToolSearch 可激活=中途激活通路);命中任一激活源 ⇒ `undefined`
+ * (不 defer=名字+schema 全量上 wire):
+ *   a) 用户当轮说 "workflow"(workflowFromInput,只扫真人输入);
+ *   b) "ultracode" 关键词(L3,同一红线);
+ *   c) `/effort ultracode` sticky dial(L2 preset)。
+ * CALLER 前置两门:live 门(mock 形不变)+ selfOrchestration stamp 存在(opt-out 时 Workflow 根本不挂载,
+ * defer 无意义)。前缀缓存注记:defer↔不 defer 的翻转只发生在真人激活当轮,与 CC 209 ToolSearch materialize
+ * 同一形——非激活轮的前缀指纹稳定([1044]② clay 硬约束 ii 的解)。
+ */
+export function workflowDeferForRequest(humanInput, env = hostEnv()) {
+    if (deferOptedOut(env))
+        return undefined;
+    if (getUltracodePreset() || ultracodeFromInput(humanInput) || workflowFromInput(humanInput))
+        return undefined;
+    return ['Workflow'];
+}
+/** [1077]④ 低频工具惰性注入:`SEMA_DEFER_TOOLS=<csv>`(wire 名)追加进 deferTools(core 1.314
+ *  延迟披露腿)。**缺省翻转已裁(clay [1212]⑤,2026-07-19)**:九件低频工具缺省 defer——判决数=
+ *  -2,484 tok/首调用+多轮 gate 零行为退化;defer≠禁用(占位符在,模型 ToolSearch 随取)。
+ *  逃生门:`SEMA_DEFER_LOWFREQ=0/false/no/off` 关缺省名单(九件恢复全量上前缀)。 */
+export const DEFER_TOOLS_ENV = 'SEMA_DEFER_TOOLS';
+export const DEFER_LOWFREQ_ENV = 'SEMA_DEFER_LOWFREQ';
+/** clay 裁定的缺省惰性名单([1076]④ 评测九件原单,[1090]② 判决数)。 */
+export const DEFAULT_LOWFREQ_DEFER = [
+    'Glob',
+    'Grep',
+    'LSP',
+    'RepoMap',
+    'Monitor',
+    'Now',
+    'AgentTranscript',
+    'ReadToolResult',
+    'ReportBlocked',
+];
+function extraDeferFromEnv(env) {
+    const raw = env[DEFER_TOOLS_ENV];
+    if (typeof raw !== 'string' || raw.trim().length === 0)
+        return [];
+    return raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+function lowFreqOptedOut(env) {
+    const raw = env[DEFER_LOWFREQ_ENV];
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    return s === '0' || s === 'false' || s === 'no' || s === 'off';
+}
+/**
+ * The FULL deferTools list for a request: the Workflow default-defer lane (activation sources, see
+ * {@link workflowDeferForRequest}) + the DEFAULT low-frequency list (clay [1212]⑤, opt-out via
+ * SEMA_DEFER_LOWFREQ) + the SEMA_DEFER_TOOLS extra list, deduped. An activation hit removes ONLY
+ * Workflow (the user asked for it by name); the other lanes are source-independent. Empty ⇒
+ * `undefined` (no stamp, request shape unchanged).
+ */
+export function deferToolsForRequest(humanInput, env = hostEnv()) {
+    const workflowLane = workflowDeferForRequest(humanInput, env) ?? [];
+    const lowFreqLane = lowFreqOptedOut(env) ? [] : DEFAULT_LOWFREQ_DEFER;
+    const extra = extraDeferFromEnv(env).filter((name) => name !== 'Workflow' || workflowLane.length > 0);
+    const merged = [...new Set([...workflowLane, ...lowFreqLane, ...extra])];
+    return merged.length > 0 ? merged : undefined;
+}

package/dist/webSearchWireCaps.d.ts

@@ -0,0 +1,54 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/webSearchWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/webSearchWireCaps.ts — PURE projection: the shell's WebSearch backend config → the @sema-ai
+ * `SemaSettings.webSearch` wire shape carried on `TaskRequest.settings.webSearch`.
+ *
+ * The SERVICE consumes `body.settings.webSearch` — ai-agent-service `src/plugins/web-search.ts`
+ * `webSearchConfigFromSettings(raw)` reads a per-request `{ provider, apiKey?, endpoint?, maxResults? }` that
+ * WINS over the deployment-env backend, gated to the single-user host lane (a per-request endpoint/apiKey is a
+ * capability config; on multi-tenant it would be SSRF, so multi-tenant uses ONLY the deploy-env backend —
+ * design/107). The service validates `provider ∈ brave | tavily | searxng` and DROPS a missing/invalid provider
+ * (it never throws — a bad config falls back to the deploy-env backend). We mirror that exact validation here so
+ * the shell never stamps a config the service would reject.
+ *
+ * Two config sources, ENV wins (the primary / verify lane):
+ *   - ENV: `SEMA_WEBSEARCH_PROVIDER` / `_ENDPOINT` / `_API_KEY` / `_MAX_RESULTS` (SEMA_-namespaced, distinct from
+ *     the SERVICE's own deploy `WEB_SEARCH_*` env so the shell config never collides with the worker's).
+ *   - settings.json: a CC-parity `webSearch` section (the SettingsSchema outer `.passthrough()` preserves it).
+ *
+ * PURE — no env/file IO of its OWN (callers pass `env` / `raw`), so it bundles + unit-tests without the heavy
+ * settings graph, exactly like mcpWireCaps. The CALLER (seamQuery / seamQueryEngine) gates the env read to LIVE
+ * mode so the mock request shape never changes; webSearch presence IS the opt-in (no extra flag needed).
+ */
+import { type EnvLike } from './hostEnv.js';
+/** The search providers the service backend speaks (web-search.ts `WebSearchProvider`). */
+export type WebSearchProvider = 'brave' | 'tavily' | 'searxng';
+/** The `SemaSettings.webSearch` wire shape — mirrors the service's per-request parser input
+ *  (web-search.ts `webSearchConfigFromSettings`: `{ provider, apiKey?, endpoint?, maxResults? }`). */
+export interface WebSearchSettings {
+    provider: WebSearchProvider;
+    /** API key (brave/tavily). The service keeps it in a closure — it never reaches the model or the tool args. */
+    apiKey?: string;
+    /** SearXNG base URL (REQUIRED for searxng); for brave/tavily an optional base-URL override. */
+    endpoint?: string;
+    /** Max results returned to the model (the service clamps 1..20; default 10). */
+    maxResults?: number;
+}
+/** The four env keys the shell reads. SEMA_-namespaced so they never collide with the worker's deploy
+ *  `WEB_SEARCH_*` env (the service reads BOTH — a per-request body.settings.webSearch WINS over its env). */
+export declare const WEBSEARCH_ENV: {
+    readonly provider: "SEMA_WEBSEARCH_PROVIDER";
+    readonly endpoint: "SEMA_WEBSEARCH_ENDPOINT";
+    readonly apiKey: "SEMA_WEBSEARCH_API_KEY";
+    readonly maxResults: "SEMA_WEBSEARCH_MAX_RESULTS";
+};
+/** ENV source → WebSearchSettings, or undefined when no/invalid provider (⇒ no stamp; service uses its env/none). */
+export declare function webSearchFromEnv(env?: EnvLike): WebSearchSettings | undefined;
+/** settings.json `webSearch` section (UNTRUSTED passthrough value) → WebSearchSettings, mirroring the service's
+ *  `webSearchConfigFromSettings`. Missing/invalid provider ⇒ undefined (omit). NEVER throws. */
+export declare function webSearchFromSettings(raw: unknown): WebSearchSettings | undefined;
+/** Resolve the effective WebSearch config: ENV wins (the primary lane), else the settings.json section.
+ *  Undefined ⇒ no stamp (the service falls back to its deploy-env backend, or ships no WebSearch tool). */
+export declare function resolveWebSearch(env?: EnvLike, settingsRaw?: unknown): WebSearchSettings | undefined;

package/dist/webSearchWireCaps.js

@@ -0,0 +1,76 @@
+/**
+ * ⇄ B2 批搬迁(2026-07-27,多端改造设计稿 §3 B2):cli src/sema/webSearchWireCaps.ts 逐字搬入(零依赖)。
+ */
+/**
+ * src/sema/webSearchWireCaps.ts — PURE projection: the shell's WebSearch backend config → the @sema-ai
+ * `SemaSettings.webSearch` wire shape carried on `TaskRequest.settings.webSearch`.
+ *
+ * The SERVICE consumes `body.settings.webSearch` — ai-agent-service `src/plugins/web-search.ts`
+ * `webSearchConfigFromSettings(raw)` reads a per-request `{ provider, apiKey?, endpoint?, maxResults? }` that
+ * WINS over the deployment-env backend, gated to the single-user host lane (a per-request endpoint/apiKey is a
+ * capability config; on multi-tenant it would be SSRF, so multi-tenant uses ONLY the deploy-env backend —
+ * design/107). The service validates `provider ∈ brave | tavily | searxng` and DROPS a missing/invalid provider
+ * (it never throws — a bad config falls back to the deploy-env backend). We mirror that exact validation here so
+ * the shell never stamps a config the service would reject.
+ *
+ * Two config sources, ENV wins (the primary / verify lane):
+ *   - ENV: `SEMA_WEBSEARCH_PROVIDER` / `_ENDPOINT` / `_API_KEY` / `_MAX_RESULTS` (SEMA_-namespaced, distinct from
+ *     the SERVICE's own deploy `WEB_SEARCH_*` env so the shell config never collides with the worker's).
+ *   - settings.json: a CC-parity `webSearch` section (the SettingsSchema outer `.passthrough()` preserves it).
+ *
+ * PURE — no env/file IO of its OWN (callers pass `env` / `raw`), so it bundles + unit-tests without the heavy
+ * settings graph, exactly like mcpWireCaps. The CALLER (seamQuery / seamQueryEngine) gates the env read to LIVE
+ * mode so the mock request shape never changes; webSearch presence IS the opt-in (no extra flag needed).
+ */
+import { hostEnv } from './hostEnv.js';
+/** The four env keys the shell reads. SEMA_-namespaced so they never collide with the worker's deploy
+ *  `WEB_SEARCH_*` env (the service reads BOTH — a per-request body.settings.webSearch WINS over its env). */
+export const WEBSEARCH_ENV = {
+    provider: 'SEMA_WEBSEARCH_PROVIDER',
+    endpoint: 'SEMA_WEBSEARCH_ENDPOINT',
+    apiKey: 'SEMA_WEBSEARCH_API_KEY',
+    maxResults: 'SEMA_WEBSEARCH_MAX_RESULTS',
+};
+/** Validate a provider EXACTLY as the service does (trim + lowercase; only the three known providers). */
+function normProvider(v) {
+    const p = typeof v === 'string' ? v.trim().toLowerCase() : '';
+    return p === 'brave' || p === 'tavily' || p === 'searxng' ? p : undefined;
+}
+/** Parse a positive integer maxResults (string env or number); undefined when absent/invalid (service clamps). */
+function normMax(v) {
+    const n = typeof v === 'number' ? v : Number(v);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+}
+/** Assemble a `WebSearchSettings`, omitting empty optionals (never stamp `apiKey:''`/`endpoint:''`/`maxResults:0`). */
+function build(provider, apiKey, endpoint, maxResults) {
+    const max = normMax(maxResults);
+    return {
+        provider,
+        ...(typeof apiKey === 'string' && apiKey ? { apiKey } : {}),
+        ...(typeof endpoint === 'string' && endpoint ? { endpoint } : {}),
+        ...(max ? { maxResults: max } : {}),
+    };
+}
+/** ENV source → WebSearchSettings, or undefined when no/invalid provider (⇒ no stamp; service uses its env/none). */
+export function webSearchFromEnv(env = hostEnv()) {
+    const provider = normProvider(env[WEBSEARCH_ENV.provider]);
+    if (!provider)
+        return undefined;
+    return build(provider, env[WEBSEARCH_ENV.apiKey], env[WEBSEARCH_ENV.endpoint], env[WEBSEARCH_ENV.maxResults]);
+}
+/** settings.json `webSearch` section (UNTRUSTED passthrough value) → WebSearchSettings, mirroring the service's
+ *  `webSearchConfigFromSettings`. Missing/invalid provider ⇒ undefined (omit). NEVER throws. */
+export function webSearchFromSettings(raw) {
+    if (!raw || typeof raw !== 'object')
+        return undefined;
+    const s = raw;
+    const provider = normProvider(s.provider);
+    if (!provider)
+        return undefined;
+    return build(provider, s.apiKey, s.endpoint, s.maxResults);
+}
+/** Resolve the effective WebSearch config: ENV wins (the primary lane), else the settings.json section.
+ *  Undefined ⇒ no stamp (the service falls back to its deploy-env backend, or ships no WebSearch tool). */
+export function resolveWebSearch(env = hostEnv(), settingsRaw) {
+    return webSearchFromEnv(env) ?? webSearchFromSettings(settingsRaw);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/client-core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Client-side session runtime shared by every sema human client (TUI / web / desktop): sema wire frames (AgentEvent) -> CC session vocabulary (SDKMessage) with dual-plane output (transcript/chrome), deterministic transcript ids, lane discipline as a type, and the notification/dedup ledgers. Every CC-skin shape is collected here so the wire itself stays neutral. Blackboard [1832] design axioms; [1651]/[1652]/[1653] signed seam design. Renamed from @sema-agent/wire-cc-adapter (0.1.x).",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,7 @@
   "sideEffects": false,
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node scripts/run-client-core-pure-test.mjs && node scripts/run-client-core-diff-test.mjs"
+    "test": "node scripts/run-client-core-pure-test.mjs && node scripts/run-client-core-portability-test.mjs && node scripts/run-client-core-diff-test.mjs"
   },
   "dependencies": {},
   "peerDependencies": {