@sema-agent/client-core 0.2.0 → 0.4.0

package/dist/subagentContentStore.js

@@ -0,0 +1,322 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/subagentContentStore.ts 逐字搬入(零依赖;壳侧改 re-export)。
+ * 🔴 module 级台账(tasks/parentToTask/ownEngineRuns/bgFacts)= 单实例语义:写方(seam adapter
+ * runStream 的子代内容分流 + liveClient 的 run_started own 台账)与读方(查看态/帧级 own 判别)
+ * 必须走**同一个模块实例**,否则 own 判别恒 false(帧级校验静默失效)。
+ */
+/**
+ * subagentContentStore — dep-free side-channel store for ENGINE subagent CONTENT events (C1 consumption,
+ * service 1.89 `forwardSubagentEvents` + core 1.219; blackboard [381]⑤/[383]③).
+ *
+ * WIRE FACTS: with `forwardSubagentEvents: true` on the task request, the live stream carries the
+ * subagent's text_delta / reasoning_delta / tool_start / tool_end stamped with EventIdentity
+ * {taskId, parentToolCallId} (§E1 redact upstream; §E2 identity). The seam adapter (runStream.ts)
+ * DIVERTS those events here — they must never reach the main-transcript pipeline (a subagent's tokens
+ * rendering as the leader's text is the pollution failure mode).
+ *
+ * WHAT IT KEEPS (bounded, per task):
+ *   - a NEUTRAL item log: {kind:'text'|'thinking',text} | {kind:'tool',name,input,output,isError,id}
+ *     (ring-capped) — the 查看态 transcript backlog, so entering a running agent mid-flight still shows
+ *     history. Message SHAPES are built by the consumers (engineAgentView/chrome-agentprogress own the
+ *     CC message creators; this store stays dep-free like engineAgentPanelStore).
+ *   - live accumulation buffers (streaming text/thinking not yet segment-closed).
+ *   - taskId → parentToolCallId (the C2 steer target — service routes subagent steer by parentToolCallId).
+ *
+ * NOTIFY: coalesced (~250ms) per-task notify so a per-token delta storm never turns into per-token
+ * AppState writes; consumers pull a snapshot on notify.
+ */
+const MAX_ITEMS_PER_TASK = 200;
+const MAX_TASKS = 32;
+const NOTIFY_COALESCE_MS = 250;
+const tasks = new Map();
+// parentToolCallId ↔ engine taskId aliasing: CONTENT events carry ONLY {eventId, parentToolCallId}
+// (EventIdentity — no taskId on the wire), while the panel rows / 查看态 lookups key by the ENGINE task id
+// (task_progress carries BOTH). Content arriving before the first tick parks under the parent key and is
+// RE-KEYED when the alias registers.
+const parentToTask = new Map();
+const taskToParent = new Map();
+let notifyListener = null;
+const pendingNotify = new Set();
+let notifyTimer = null;
+/** LRU touch:Map 迭代序=插入序,容量淘汰取「最老」——不刷新的话是纯 FIFO,长会话里第 33 个
+ *  子代会把【仍在流式/正被查看】的最早行挤掉(扩散面复审 F11)。访问即 re-insert,活跃项恒新。 */
+function touchLru(map, key) {
+    const v = map.get(key);
+    if (v !== undefined) {
+        map.delete(key);
+        map.set(key, v);
+    }
+}
+function stateFor(taskId, parentToolCallId) {
+    let s = tasks.get(taskId);
+    if (!s) {
+        // Bound total task footprint: evict the LEAST-RECENTLY-USED task's log (reads/writes touch below).
+        if (tasks.size >= MAX_TASKS) {
+            const oldest = tasks.keys().next().value;
+            if (oldest !== undefined)
+                tasks.delete(oldest);
+        }
+        s = { items: [], textBuf: '', thinkBuf: '', openTools: new Map(), parentToolCallId };
+        tasks.set(taskId, s);
+    }
+    else {
+        touchLru(tasks, taskId);
+    }
+    return s;
+}
+function pushItem(s, item) {
+    s.items.push(item);
+    if (s.items.length > MAX_ITEMS_PER_TASK) {
+        s.items.splice(0, s.items.length - MAX_ITEMS_PER_TASK);
+        // open-tool indexes shifted — rebuild from the surviving items
+        s.openTools.clear();
+        s.items.forEach((it, i) => {
+            if (it.kind === 'tool' && it.output === undefined)
+                s.openTools.set(it.id, i);
+        });
+    }
+}
+/** Close out streaming buffers into items (segment boundary: a tool starts, or the run settles). */
+function flushBuffers(s) {
+    if (s.thinkBuf.trim())
+        pushItem(s, { kind: 'thinking', text: s.thinkBuf });
+    s.thinkBuf = '';
+    if (s.textBuf.trim())
+        pushItem(s, { kind: 'text', text: s.textBuf });
+    s.textBuf = '';
+}
+function scheduleNotify(taskId) {
+    pendingNotify.add(taskId);
+    if (notifyTimer)
+        return;
+    notifyTimer = setTimeout(() => {
+        notifyTimer = null;
+        const ids = [...pendingNotify];
+        pendingNotify.clear();
+        if (!notifyListener)
+            return;
+        for (const id of ids) {
+            try {
+                notifyListener(id);
+            }
+            catch {
+                // a consumer render error must never tear down the stream drain
+            }
+        }
+    }, NOTIFY_COALESCE_MS);
+}
+/** Register the parentToolCallId ↔ engine-taskId pair (from task_progress, which carries both).
+ *  Content parked under the parent key migrates to the canonical task key. */
+export function registerSubagentAlias(parentToolCallId, taskId) {
+    if (!parentToolCallId || !taskId || parentToolCallId === taskId)
+        return;
+    parentToTask.set(parentToolCallId, taskId);
+    taskToParent.set(taskId, parentToolCallId);
+    // a notify queued under the parent key before the alias landed must fire under the canonical key
+    if (pendingNotify.delete(parentToolCallId))
+        pendingNotify.add(taskId);
+    const parked = tasks.get(parentToolCallId);
+    if (parked && !tasks.has(taskId)) {
+        tasks.delete(parentToolCallId);
+        tasks.set(taskId, parked);
+        scheduleNotify(taskId);
+    }
+}
+function canonicalKey(ev) {
+    // the wire's content events carry no taskId — runStream passes parentToolCallId in both slots
+    if (ev.taskId !== ev.parentToolCallId)
+        return ev.taskId;
+    return parentToTask.get(ev.parentToolCallId) ?? ev.parentToolCallId;
+}
+export function publishSubagentContentEvent(ev) {
+    const key = canonicalKey(ev);
+    const s = stateFor(key, ev.parentToolCallId);
+    switch (ev.type) {
+        case 'text_delta':
+            if (typeof ev.delta === 'string')
+                s.textBuf += ev.delta;
+            break;
+        case 'reasoning_delta':
+            if (typeof ev.delta === 'string')
+                s.thinkBuf += ev.delta;
+            break;
+        case 'tool_start': {
+            flushBuffers(s);
+            const id = ev.toolCallId ?? `${ev.taskId}-tool-${s.items.length}`;
+            pushItem(s, { kind: 'tool', id, name: ev.toolName ?? 'Tool', input: ev.args ?? {} });
+            s.openTools.set(id, s.items.length - 1);
+            break;
+        }
+        case 'tool_end': {
+            const id = ev.toolCallId;
+            const idx = id !== undefined ? s.openTools.get(id) : undefined;
+            if (idx !== undefined && s.items[idx]?.kind === 'tool') {
+                const it = s.items[idx];
+                it.output = ev.output ?? '';
+                it.isError = ev.isError === true;
+                if (id !== undefined)
+                    s.openTools.delete(id);
+            }
+            else {
+                // orphan close (start lost to the ring / arrived first) — synthesize a resolved card
+                pushItem(s, {
+                    kind: 'tool',
+                    id: id ?? `${ev.taskId}-tool-${s.items.length}`,
+                    name: ev.toolName ?? 'Tool',
+                    input: ev.args ?? {},
+                    output: ev.output ?? '',
+                    isError: ev.isError === true,
+                });
+            }
+            break;
+        }
+    }
+    scheduleNotify(key);
+}
+/** 查看态 composer echo (C2 steer optimistic display) — segment-closes the buffers first so the echo
+ *  lands AFTER the text streamed before it. taskId may be unseen (row entered before any content):
+ *  parentToolCallId may then be unknown — pass '' and the steer path resolves the target separately. */
+export function pushSubagentLocalEcho(taskId, text) {
+    const s = stateFor(taskId, tasks.get(taskId)?.parentToolCallId ?? '');
+    flushBuffers(s);
+    pushItem(s, { kind: 'echo', text });
+    scheduleNotify(taskId);
+}
+export function getSubagentContentSnapshot(taskId) {
+    const key = tasks.has(taskId) ? taskId : (taskToParent.get(taskId) ?? '');
+    const s = tasks.get(key);
+    if (!s)
+        return null;
+    touchLru(tasks, key); // 正被查看的转录不因容量淘汰当场清空(F11)
+    return { items: [...s.items], textBuf: s.textBuf, thinkBuf: s.thinkBuf };
+}
+/**
+ * 把一个子代的内容账本投影成查看态渲染计划。
+ *
+ * [1568] 之前的形(壳侧 engineAgentView 里)有两处「等段闭合」:①遇到第一个未闭合工具就 break;
+ * ②textBuf/thinkBuf 完全不投影。实测(engine 1.275.0 真跑):数据面 ~23 帧/s 的 delta 连续到壳,
+ * 查看态却只在 tool 边界更新(进查看态后 6.0s 全空,之后每 5–15s 才动一次)。现形:在飞工具照投,
+ * 流式尾巴作为 live 槽投 —— 屏面粒度 = wire 粒度(store notify 已按 250ms 合并)。
+ */
+export function planSubagentViewSlots(taskId) {
+    const snap = getSubagentContentSnapshot(taskId);
+    if (!snap)
+        return [];
+    const out = [];
+    snap.items.forEach((it, i) => {
+        if (it.kind === 'tool') {
+            out.push({
+                kind: 'tool',
+                slot: `u${i}`,
+                id: it.id,
+                name: it.name,
+                input: it.input,
+                ...(it.output !== undefined ? { output: it.output } : {}),
+                ...(it.isError === true ? { isError: true } : {}),
+            });
+        }
+        else if (it.kind === 'text') {
+            out.push({ kind: 'text', slot: `t${i}`, text: it.text });
+        }
+        else if (it.kind === 'thinking') {
+            out.push({ kind: 'thinking', slot: `k${i}`, text: it.text });
+        }
+        else {
+            out.push({ kind: 'echo', slot: `e${i}`, text: it.text });
+        }
+    });
+    // 尾巴顺序与 flushBuffers 落项顺序一致(thinking 先、text 后)——段闭合时屏面内容连续不跳。
+    if (snap.thinkBuf.trim()) {
+        out.push({ kind: 'thinking', slot: 'live-think', text: snap.thinkBuf, live: true });
+    }
+    if (snap.textBuf.trim()) {
+        out.push({ kind: 'text', slot: 'live-text', text: snap.textBuf, live: true });
+    }
+    return out;
+}
+/** C2 steer target: the service routes subagent steer by the delegating tool call's id. */
+export function parentToolCallIdOf(taskId) {
+    return taskToParent.get(taskId) ?? tasks.get(taskId)?.parentToolCallId;
+}
+/** Settle a task's streaming buffers (turn ended / run settled) so the snapshot is complete. */
+export function settleSubagentContent(taskId) {
+    const s = tasks.get(taskId);
+    if (!s)
+        return;
+    flushBuffers(s);
+    scheduleNotify(taskId);
+}
+export function clearSubagentContent(taskId) {
+    tasks.delete(taskId);
+}
+const bgFacts = new Map();
+export function recordBgTerminalFacts(taskId, facts) {
+    if (!taskId)
+        return;
+    if (bgFacts.size >= MAX_TASKS && !bgFacts.has(taskId)) {
+        const oldest = bgFacts.keys().next().value;
+        if (oldest !== undefined)
+            bgFacts.delete(oldest);
+    }
+    bgFacts.delete(taskId); // LRU touch(F11):重录/更新即刷新插入序
+    bgFacts.set(taskId, facts);
+    scheduleNotify(taskId); // 打开中的查看态借既有 notify 链重建消息
+}
+export function getBgTerminalFacts(taskId) {
+    const key = bgFacts.has(taskId) ? taskId : (taskToParent.get(taskId) ?? '');
+    touchLru(bgFacts, key);
+    return bgFacts.get(key);
+}
+// ── bg 子代 → spawn 它的 leader run(server 1.244 subagentOutput 读面的寻址元组)──────────────
+// GET /v1/runs/:runId/subagents/:handle/output 的 runId = spawn 该子代的 run(registry access 从
+// run 行推导,[1491]①)。来源两路:fleet 行 parentId(出生帧即带)+ bg_notification.parentTaskId。
+const bgParentRun = new Map();
+export function recordBgParentRun(taskId, runId) {
+    if (!taskId || !runId || taskId === runId)
+        return;
+    if (bgParentRun.size >= MAX_TASKS * 2 && !bgParentRun.has(taskId)) {
+        const oldest = bgParentRun.keys().next().value;
+        if (oldest !== undefined)
+            bgParentRun.delete(oldest);
+    }
+    bgParentRun.delete(taskId); // LRU touch(F11):活跃映射不被容量淘汰挤掉 → 读面退错 runId
+    bgParentRun.set(taskId, runId);
+}
+export function getBgParentRun(taskId) {
+    touchLru(bgParentRun, taskId);
+    return bgParentRun.get(taskId);
+}
+// ── 本壳自己发起过的引擎 run 台账([1498]④ 帧级校验换锚)────────────────────────────────────
+// 喂给:engineToolDetach.setActiveEngineTaskId(liveClient 从 run_started 帧绑定,本壳每个交互
+// turn 的 run 必经)。与 bgParentRun 的关键区别:bgParentRun 由 fleet 行/通知帧喂(≤1.244 事实
+// 广播下可能混入别的壳的行),这份台账**只**记本进程亲手驱动的 run,是帧级 own/foreign 判别的
+// 唯一可信锚。进程内存态,壳重启即空(跨壳 resume 的历史 run 判不了 own——诚实边界,见
+// fleetClient 帧级校验注释)。
+const ownEngineRuns = new Set();
+export function recordOwnEngineRun(runId) {
+    if (!runId)
+        return;
+    // 防御性上限:一个壳进程生命周期内 turn 数远小于此;溢出丢最老(Set 迭代序=插入序)。
+    if (ownEngineRuns.size >= 8192 && !ownEngineRuns.has(runId)) {
+        const oldest = ownEngineRuns.values().next().value;
+        if (oldest !== undefined)
+            ownEngineRuns.delete(oldest);
+    }
+    ownEngineRuns.add(runId);
+}
+export function isOwnEngineRun(runId) {
+    return ownEngineRuns.has(runId);
+}
+/** Single consumer (the panel hook). Returns an unsubscribe. */
+export function subscribeSubagentContent(fn) {
+    notifyListener = fn;
+    // replay: anything already accumulated gets one notify so a late-mounting consumer catches up
+    for (const id of tasks.keys())
+        pendingNotify.add(id);
+    if (pendingNotify.size > 0)
+        scheduleNotify([...pendingNotify][0]);
+    return () => {
+        if (notifyListener === fn)
+            notifyListener = null;
+    };
+}

package/dist/types/engineState.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
+ * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
+ * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
+ * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
+ */
+/**
+ * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
+ *
+ * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
+ * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
+ *
+ * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
+ * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
+ * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
+ */
+/** 引擎 GET /health 返回体(与 ai-agent-service server.ts:645-660 对齐;字段大多 additive 可缺)。 */
+export interface HealthResponse {
+    /** 恒为 'ok';非 200 / 非此值 = 不健康。 */
+    status: string;
+    /** 当前模型 id(configHash 的一部分,信息性)。 */
+    model?: string;
+    /** 会话存储后端('file' for TOC local)。 */
+    sessionBackend?: string;
+    /** 活跃 session 数(信息性)。 */
+    sessions?: number;
+    /** 引擎实例身份(uuidv7,每次 boot 唯一)。陈旧 port 连错引擎时此值会变 → 拒连。 */
+    instanceId?: string;
+    /** 引擎 localDataRoot 解析结果。壳校验 === assembleChildEnv 注入的 LOCAL_DATA_ROOT。 */
+    dataRoot?: string;
+    /** restart-relevant config 的稳定指纹(无 secret)。drift 检测:configHash 变 → 拒连旧引擎。 */
+    configHash?: string;
+    /** 引擎进程 pid。orphan reap 的 kill-0 目标 + heartbeat 死活判定。 */
+    pid?: number;
+    /** 引擎监听端口。 */
+    port?: number;
+    /** 引擎请求重启(center restart 信号);壳侧信息性。 */
+    restartRequired?: boolean;
+    /** 引擎 build 版本自述(service 1.96+,[392]ask②)。复用时与本地 dist 版本比对,不一致=陈旧代码拒复用。 */
+    version?: string;
+}
+/**
+ * engine.port 文件落盘的 JSON 形状(write-temp+fsync+mv 原子写)。
+ * 壳启动时读此文件做引擎发现:存在且 kill-0 活 + /health 身份匹配 → 复用;否则 reap + spawn。
+ * 🔴 secrets 边界:绝不写入任何明文 token/secret(只透传到 child env)。grep engine.port 不得见 secret。
+ */
+export interface EnginePortFile {
+    /** 引擎监听端口。 */
+    port: number;
+    /** spawn 出的引擎子进程 pid(kill-0 存活检测 / orphan reap 目标)。 */
+    pid: number;
+    /** 引擎实例身份(uuidv7);连接前用 /health 复验,不匹配 = 陈旧 port。 */
+    instanceId?: string;
+    /** 引擎 localDataRoot;身份校验用。 */
+    dataRoot?: string;
+    /** boot 时记录的 configHash;drift 检测基线。 */
+    configHash?: string;
+    /** 引擎日志文件路径(<configHome>/engine-<pid>.log),壳可 tail 诊断。 */
+    logPath: string;
+    /** 落盘时间戳(epoch ms);信息性 / 调试用。 */
+    startedAt: number;
+    /** 写文件的格式版本(向后兼容);当前 1。 */
+    version: number;
+    /**
+     * P2 云配置整体开关:spawn 该引擎时生效的配置源标签('local' | 'cloud:<profile>')。
+     * ADDITIVE 可缺(老文件缺 = 'local')。boot 复用检查:与当前 desiredEngineConfigSource() 不一致
+     * → 视同配置漂移 reap+respawn(models 域走 CONFIG_LOCAL_DIR shadow,restart-to-apply)。
+     */
+    configSource?: string;
+}
+/**
+ * 内存中持有的「已托管引擎实例」句柄。lifecycle 全程持有,shutdown 时据此 SIGTERM/SIGKILL。
+ */
+export interface EngineInstance {
+    /** 监听端口。 */
+    port: number;
+    /** 子进程 pid。 */
+    pid: number;
+    /** baseUrl = http://127.0.0.1:<port>,壳设到 SEMA_LIVE_BASEURL。 */
+    baseUrl: string;
+    /** /health 校验拿到的身份(复用既有引擎时可能来自 probe,而非自己 spawn)。 */
+    instanceId?: string;
+    /** 引擎 dataRoot。 */
+    dataRoot?: string;
+    /** boot configHash 基线(heartbeat drift 检测)。 */
+    configHash?: string;
+    /** 日志文件路径(自己 spawn 的才有;复用既有引擎为 undefined)。 */
+    logPath?: string;
+    /** true = 本壳 spawn 出来的(shutdown 时负责回收);false = 复用既有引擎(不杀)。 */
+    ownedByThisShell: boolean;
+    /** node ChildProcess 句柄(仅自己 spawn 时有;复用既有为 undefined)。as unknown 避免类型耦合 child_process。 */
+    child?: unknown;
+}
+/**
+ * 壳注入给引擎子进程的 TOC env pack(§3.1)。引擎默认偏云(PORT=8090/DB_BACKEND=tidb/
+ * CONFIG_PROVIDER=undefined),壳必须显式覆盖为 local 单用户模式,绝不依赖引擎默认。
+ * secrets(ANTHROPIC_API_KEY/E2B_API_KEY 等)仅在父 env 存在时透传到 child,不落任何文件。
+ */
+export interface TOCConfig {
+    /** 选定端口(显式 pin SEMA_ENGINE_PORT 优先;无 pin 按 config dir 派生 + 空闲探测,P0-2)。 */
+    port: number;
+    /** 引擎数据根 = <configHome>/engine-data;引擎 LOCAL_DATA_ROOT 优先级链最高项。 */
+    localDataRoot: string;
+    /** 本地 config.d 目录 = <configHome>/config.d(引擎 CONFIG_LOCAL_DIR)。 */
+    configLocalDir: string;
+    /** 壳配置主目录(getClaudeConfigHomeDir());也作 SEMA_CONFIG_DIR 注入对齐路径。 */
+    configHome: string;
+    /** per-spawn 随机服务令牌(uuid),SERVICE_AUTH_TOKENS="<uuid>=system:shell-local";不落 .env。 */
+    serviceAuthToken: string;
+    /** 引擎入口文件绝对路径(ai-agent-service/dist/main.js,缺则回退 tsx src/main.ts)。 */
+    engineEntry: string;
+    /** 引擎入口的工作目录(ai-agent-service 根)。 */
+    engineCwd: string;
+    /** 引擎日志输出文件(<configHome>/engine-<pid>.log;pid spawn 后回填,先用占位)。 */
+    logPath: string;
+}

package/dist/types/engineState.js

@@ -0,0 +1,17 @@
+/**
+ * ⇄ B1 批搬迁(2026-07-27,多端改造设计稿 §2.4.1-B):cli src/sema/types/engineState.ts 逐字搬入(纯类型,零运行时;壳侧改 re-export)。
+ * ⚠️ 归属注记:`EngineInstance`/`TOCConfig` 描述的是**宿主**职责(spawn/端口/日志路径),逻辑本体
+ * (engineLifecycleManager)按设计稿 §2.4.2-A 留 TUI;搬进本包的只是**形状**,让 desktop 宿主与
+ * TUI 宿主共用同一套 /health 与 engine.port 契约类型,不代表生命周期逻辑下沉。
+ */
+/**
+ * TOC 一体化 (TP-A-P0-IMPL Step 5) — Engine Lifecycle 状态类型。
+ *
+ * 壳一体化起本地引擎(ai-agent-service file 模式),对用户透明,体验等同 CC 单进程。
+ * 本文件只定义跨 lifecycle 流转的纯数据形状,不含逻辑(逻辑在 engineLifecycleManager.ts)。
+ *
+ * 真相源契约:engine.port 文件是壳↔引擎的「当前活引擎」单一发现锚点(flock 串行化写,
+ * write-temp+fsync+mv 原子落盘)。HealthResponse 字段与引擎 server.ts:645-660 /health 逐字对齐
+ * (W2 同约定实现):instanceId/dataRoot/configHash/pid —— 壳据此判断「连对引擎」防陈旧 port 连错。
+ */
+export {};

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;