@sema-agent/client-core 0.6.0 → 0.8.0

package/dist/limitsWire.js

@@ -0,0 +1,225 @@
+/**
+ * src/sema/limitsWire.ts — headless `-p` run-limits wire (TB2.0 反馈批 E · P2-3-b, 2026-07-15):
+ * expose the engine's REQUEST-LEVEL pacing limits on the headless `-p` path via `TaskRequest.limits`.
+ * The server accepts `limits:{timeoutSec?,maxOutputTokens?,maxTurns?}` since 1.196.0 (positive-integer
+ * 400 gate, board [857]) and feeds the EXISTING pacing machinery (deadlineNudge / callCapByDeadline /
+ * gracefulFinalize) — the shell simply never stamped the field. This module is the CLI face.
+ *
+ * TWO FLAGS, TWO ALIGNMENT BUCKETS:
+ *  · `--deadline <sec>`   → limits.timeoutSec. Upstream CC 2.1.207 has NO deadline flag (nearest kin:
+ *    --max-turns / --task-budget / --max-budget-usd) → SUPERSET, help copy says so.
+ *  · `--max-turns <n>`    → limits.maxTurns. Upstream CC 2.1.207 HAS `--max-turns` (source 199676 /
+ *    793380) → ALIGNMENT-GAP fill: the flag was already registered (main.tsx CC-inherited surface) and
+ *    drove the local query loop, but the seam path executes turns ENGINE-side — this wire finally
+ *    carries the cap to where the turns actually run.
+ *
+ * PRECEDENCE per knob (flag > settings > none), scenarioWire 三件套同款:
+ *  a) explicit flag                                   → strict validation, FAIL-LOUD on an invalid
+ *     value (integer domain below; a mis-typed pacing bound must not quietly run unbounded).
+ *  b) settings env lane (settings.json `env` block → 1a-envseed → process.env):
+ *     `SEMA_HEADLESS_DEADLINE_SEC` / `SEMA_HEADLESS_MAX_TURNS` → SILENT degrade on an invalid value
+ *     (spec'd 静默降级 — a settings typo must never brick every headless run; unlike scenarioWire we
+ *     don't even warn, per the batch-E triage shape. SEMA_DEBUG surfaces the drop for diagnosis).
+ *  c) neither                                          → NO stamp = today's behaviour, verbatim.
+ *
+ * DOMAINS (integer, inclusive): timeoutSec 30..86400 · maxTurns 1..1000.
+ *
+ * VERSION GATE (triage risk ③ — an OLD server SILENTLY SWALLOWS unknown body fields, worse than not
+ * shipping): the self-spawned engine is release-pinned ≥1.197.0 so the dev/release lanes are safe by
+ * construction; but a user-supplied SEMA_ENGINE_URL may point at an older engine. When the user
+ * EXPLICITLY passed a flag (env-lane defaults stay quiet) and SEMA_ENGINE_URL is in play, the caller
+ * probes `${baseUrl}/health` (the engine self-describes `version` since 1.96) and prints ONE honest
+ * stderr line when version <1.196.0 — the request still goes out unchanged (warn, don't block).
+ * Unreachable /health or an unparsable version stays silent (can't confirm staleness — fail-soft).
+ */
+import { hostEnv } from './hostEnv.js';
+/** Settings-lane env knobs (settings.json `env` block → 1a-envseed → process.env). */
+export const HEADLESS_DEADLINE_ENV = 'SEMA_HEADLESS_DEADLINE_SEC';
+export const HEADLESS_MAX_TURNS_ENV = 'SEMA_HEADLESS_MAX_TURNS';
+/** Integer domains (inclusive). timeoutSec: 30s..24h; maxTurns: 1..1000. */
+export const DEADLINE_SEC_MIN = 30;
+export const DEADLINE_SEC_MAX = 86_400;
+export const MAX_TURNS_MIN = 1;
+export const MAX_TURNS_MAX = 1_000;
+/** First server version whose /v1/tasks|/v1/tasks/stream accept body.limits (board [857]). */
+export const LIMITS_WIRE_MIN_ENGINE = [1, 196, 0];
+const DEADLINE_USAGE = `sema: --deadline expects a whole number of seconds between ${DEADLINE_SEC_MIN} and ${DEADLINE_SEC_MAX}.\n` +
+    '  --deadline <sec>     soft wall-clock budget for this run (sema superset — no upstream equivalent):\n' +
+    '                       the engine paces itself (nudges + call caps) and finalizes gracefully near the deadline\n' +
+    '  (no flag)            no deadline — today\'s behaviour';
+const MAX_TURNS_USAGE = `sema: --max-turns expects a whole number of turns between ${MAX_TURNS_MIN} and ${MAX_TURNS_MAX}.\n` +
+    '  --max-turns <n>      maximum number of agentic turns for this run (upstream-aligned flag,\n' +
+    '                       enforced engine-side on the sema seam)\n' +
+    '  (no flag)            no turn cap — today\'s behaviour';
+/** STRICT integer shape for explicit flag values: ASCII digits only (no sign/decimal/exponent/space). */
+const INT_RE = /^\d+$/;
+/**
+ * Pull the LAST value of a `--name <v>` / `--name=<v>` flag out of an argv slice (everything before a
+ * bare `--` — positionals are never flags; scenarioWire 纪律). Returns:
+ *   {present:false}                 — flag absent
+ *   {present:true, raw}             — flag present with a value token
+ *   {present:true, raw:undefined}   — flag present but the value is missing/flag-shaped (fail-loud at caller)
+ */
+function lastFlagValue(argv, name) {
+    const eq = `${name}=`;
+    let present = false;
+    let raw;
+    let valueMissing = false;
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--')
+            break; // positionals — never flags
+        if (a === name) {
+            present = true;
+            const nxt = argv[i + 1];
+            if (nxt === undefined || nxt.startsWith('-')) {
+                // note: a NEGATIVE number would look flag-shaped too — the domains are all-positive, so the
+                // fail-loud usage hint is the right answer for `--deadline -5` as well.
+                valueMissing = true;
+                raw = undefined;
+                continue;
+            }
+            valueMissing = false;
+            raw = nxt;
+            i++; // consume the value token
+        }
+        else if (a.startsWith(eq)) {
+            present = true;
+            valueMissing = false;
+            raw = a.slice(eq.length);
+        }
+    }
+    if (present && (valueMissing || raw === undefined))
+        return { present: true };
+    return present ? { present: true, raw } : { present: false };
+}
+/** Validate a RAW flag value against an inclusive integer domain. Returns the number or null. */
+function parseIntInDomain(raw, min, max) {
+    const v = raw.trim();
+    if (!INT_RE.test(v))
+        return null;
+    const n = Number(v);
+    if (!Number.isSafeInteger(n) || n < min || n > max)
+        return null;
+    return n;
+}
+/**
+ * Parse `--deadline` + `--max-turns` out of an argv slice. No flags ⇒ `{ok:true}` with no limits.
+ * Repeated flag ⇒ LAST wins (commander convention). Missing value / non-integer / out-of-domain ⇒
+ * fail-LOUD parse error (never a silent default — same stance as `--scenario`/`--sandbox`).
+ * `flaggedFlags` names the flags that EXPLICITLY contributed (the version-gate probe trigger).
+ */
+export function parseLimitsArgv(argv) {
+    const limits = {};
+    const flaggedFlags = [];
+    const dl = lastFlagValue(argv, '--deadline');
+    if (dl.present) {
+        const n = dl.raw !== undefined ? parseIntInDomain(dl.raw, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX) : null;
+        if (n === null)
+            return { ok: false, error: DEADLINE_USAGE };
+        limits.timeoutSec = n;
+        flaggedFlags.push('--deadline');
+    }
+    const mt = lastFlagValue(argv, '--max-turns');
+    if (mt.present) {
+        const n = mt.raw !== undefined ? parseIntInDomain(mt.raw, MAX_TURNS_MIN, MAX_TURNS_MAX) : null;
+        if (n === null)
+            return { ok: false, error: MAX_TURNS_USAGE };
+        limits.maxTurns = n;
+        flaggedFlags.push('--max-turns');
+    }
+    return {
+        ok: true,
+        ...(flaggedFlags.length > 0 ? { limits } : {}),
+        flaggedFlags,
+    };
+}
+/**
+ * The settings-lane defaults. SILENT degrade on a bad value (batch-E triage shape — stricter than
+ * scenarioWire's warn-and-ignore: these are pacing hints, and a settings typo must neither brick nor
+ * spam every headless run). SEMA_DEBUG surfaces the drop.
+ */
+export function headlessLimitsFromEnv(env = hostEnv()) {
+    const out = {};
+    const dl = env[HEADLESS_DEADLINE_ENV]?.trim();
+    if (dl) {
+        const n = parseIntInDomain(dl, DEADLINE_SEC_MIN, DEADLINE_SEC_MAX);
+        if (n !== null)
+            out.timeoutSec = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_DEADLINE_ENV}="${dl}" is not an integer in ${DEADLINE_SEC_MIN}..${DEADLINE_SEC_MAX} — ignoring the settings default`);
+        }
+    }
+    const mt = env[HEADLESS_MAX_TURNS_ENV]?.trim();
+    if (mt) {
+        const n = parseIntInDomain(mt, MAX_TURNS_MIN, MAX_TURNS_MAX);
+        if (n !== null)
+            out.maxTurns = n;
+        else if (env.SEMA_DEBUG) {
+            // eslint-disable-next-line no-console
+            console.error(`[sema] ${HEADLESS_MAX_TURNS_ENV}="${mt}" is not an integer in ${MAX_TURNS_MIN}..${MAX_TURNS_MAX} — ignoring the settings default`);
+        }
+    }
+    return out.timeoutSec !== undefined || out.maxTurns !== undefined ? out : undefined;
+}
+/**
+ * Resolve the limits for a headless `-p` submit: explicit flags > settings env defaults > none
+ * (= no stamp, today's behaviour). Merge is PER-KNOB: `--deadline 300` + SEMA_HEADLESS_MAX_TURNS=50
+ * yields {timeoutSec:300, maxTurns:50}. Flag parse errors propagate fail-loud; the caller exits.
+ */
+export function limitsForPrint(argv, env = hostEnv()) {
+    const parsed = parseLimitsArgv(argv);
+    if (!parsed.ok)
+        return parsed;
+    const fromEnv = headlessLimitsFromEnv(env);
+    const merged = { ...(fromEnv ?? {}), ...(parsed.limits ?? {}) };
+    const any = merged.timeoutSec !== undefined || merged.maxTurns !== undefined;
+    return { ok: true, ...(any ? { limits: merged } : {}), flaggedFlags: parsed.flaggedFlags };
+}
+/** True when the engine version string satisfies the limits-wire minimum (≥1.196.0). Unparsable ⇒ false. */
+export function versionSupportsLimits(v) {
+    const m = v ? /^(\d+)\.(\d+)\.(\d+)/.exec(v) : null;
+    if (!m)
+        return false;
+    const [a, b, c] = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const [ma, mb, mc] = LIMITS_WIRE_MIN_ENGINE;
+    if (a !== ma)
+        return a > ma;
+    if (b !== mb)
+        return b > mb;
+    return c >= mc;
+}
+/**
+ * Version-gate probe (triage risk ③): GET `${baseUrl}/health`, read `version`, and return ONE honest
+ * stderr line when the engine is confirmed <1.196.0 — the caller prints it and SENDS ANYWAY (the old
+ * server drops the field server-side; warn, don't block). Returns undefined when the engine is new
+ * enough, unreachable, or self-describes no parsable version (can't confirm staleness — fail-soft
+ * silent; the release-pinned self-spawn lane never even reaches this probe).
+ */
+export async function engineLimitsSupportWarning(baseUrl, flaggedFlags, opts) {
+    const fetchImpl = opts?.fetchImpl ?? fetch;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 1500);
+    try {
+        const res = await fetchImpl(`${baseUrl.replace(/\/+$/, '')}/health`, {
+            method: 'GET',
+            signal: controller.signal,
+        });
+        if (!res.ok)
+            return undefined;
+        const body = (await res.json());
+        const version = typeof body?.version === 'string' ? body.version : undefined;
+        // No version field = pre-1.96 engine — definitely older than 1.196.0, warn honestly.
+        if (versionSupportsLimits(version))
+            return undefined;
+        const flags = flaggedFlags.length > 0 ? flaggedFlags.join('/') : '--deadline/--max-turns';
+        return `[sema] engine ${version ?? '(unversioned, pre-1.96)'} does not support ${flags} (needs ≥1.196.0); the flag will be ignored by the engine`;
+    }
+    catch {
+        return undefined; // unreachable/timeout — cannot confirm staleness, stay silent
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/liveInitToolFace.d.ts

@@ -0,0 +1,53 @@
+import type { EnvLike } from './hostEnv.js';
+/** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
+export declare const ENGINE_HANDS_BAND: readonly string[];
+/** 缺省(code/default)场景附加段 —— 与 GET /v1/capabilities/scenarios/{code,default} 详情面
+ *  实测逐字一致(场景工厂 nowTool + assembleFullBodyTools)。
+ *  ⚠️ TodoWrite 故意不在(core 1.296+ 默认 taskList:true ⇒ TodoWrite 不挂,[931] 本案根因);
+ *  TaskCreate 族在 —— 这两条就是本修要对齐的实况。 */
+export declare const ENGINE_SCENARIO_EXTRAS_DEFAULT: readonly string[];
+/** runner 恒挂段(prepare-task 按请求旋钮挂载、场景无关):壳 `-p` 恒 stamp
+ *  selfOrchestration→Workflow、attachments.backgroundTasks→TaskOutput/TaskStop/Monitor/
+ *  SendMessage/AgentTranscript;ReadToolResult/ReportBlocked/ReportFindings/Skill/Cron 族/
+ *  ScheduleWakeup 为 runner 缺省注入。 */
+export declare const ENGINE_RUNNER_FACE: readonly string[];
+/** [1036]/clay 裁:runner 恒挂段按壳已知 env 门过滤——print 宿主前置 SCHEDULER_ENABLED=false
+ *  (scheduler 族 headless 不挂)/SELF_ORCHESTRATION_ENABLED=false(Workflow 卸)时,自报面
+ *  必须跟实挂(此前静态词表在 env 门形态失真=自报 32 实挂 28,消融实测逮到)。 */
+export declare function runnerFaceForEnv(env: EnvLike): string[];
+export type LiveInitToolFace = {
+    tools: Array<{
+        name: string;
+    }>;
+    /** 'wire-vocabulary' = 缺省词表;'scenario-probe' = 非缺省场景 + 详情面探测成功。 */
+    source: 'wire-vocabulary' | 'scenario-probe';
+};
+/** 测试钩子:清缓存。 */
+export declare function _resetLiveInitToolFaceForTest(): void;
+/** 非缺省场景的详情面探测:SDK 0.0.52 scenarioCapabilities(name)(GET /v1/capabilities/scenarios/:name,
+ *  同 wire 同 encodeURIComponent)→ { tools(场景附加段), toolset }。fail-soft:任何失败(网络/404/
+ *  形状不符/超时)返回 null,调用层回退缺省词表。等价性记账:超时经 client timeoutMs(缺省 2s 同预算,
+ *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
+ *  差分:SDK Transport 恒 stamp x-agent-principal(缺省 'anon:shell-live')——原手抄在无 principal
+ *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
+export declare function probeScenarioTools(baseUrl: string, scenario: string, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+    authToken?: string;
+    principal?: string;
+}): Promise<{
+    tools: string[];
+    toolset?: string;
+} | null>;
+/**
+ * resolveLiveInitToolFace — live 车道 init 首帧 `tools` 的实挂投影。
+ *   · 无 SEMA_LIVE_BASEURL ⇒ null(mock/离线车道,调用方维持静态表现状);
+ *   · 缺省场景 ⇒ hands band + runner 恒挂段 + 旋钮修正(词表车道,零 IO);
+ *   · 非缺省场景 ⇒ 详情面探测成功用【场景附加 + runner 恒挂】(如实标注:hands band 是否在位
+ *     由部署定,不妄报),失败回退缺省词表;
+ *   · 任何内部错误 fail-soft 返回 null(调用方回退静态表,首帧永不因此缺席)。
+ */
+export declare function resolveLiveInitToolFace(argv: readonly string[], env: EnvLike, opts?: {
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<LiveInitToolFace | null>;

package/dist/liveInitToolFace.js

@@ -0,0 +1,251 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B2 判给后批的**宿主耦合六件**之一):cli
+ *    `src/sema/liveInitToolFace.ts` 整搬。B2 当时不搬的理由 = 它 `await import('./engineTarget.js')`
+ *    取凭证,而 engineTarget 是 fs 重图;B4 的 §8-2 收编把凭证解析定到了 `resolveWireAuth`
+ *    (engineWireSdk,零依赖),那条理由随之消失。
+ *
+ * 🔴 搬迁三处差分(行为一字节不变):
+ *   ① 凭证:`engineTarget.resolveLiveAuthToken(baseUrl)`(其 token 缺省 = `process.env.SEMA_LIVE_TOKEN`)
+ *      → `resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN)`。两者是同一套 #118 三态,`resolveWireAuth`
+ *      的头注自述就是它的收编口。取值面完全一致:三态里只有**真 token 串**与 `'anon'` 是 string,
+ *      `{mode:'loopback-unauthed'}` 是对象 ⇒ 原文那句 `typeof t === 'string' ? t : undefined` 语义照搬。
+ *   ② 三个 `await import('./xxxWire.js')` fail-soft 动态 import → **静态 import**(scenarioWire /
+ *      interactiveToolsWire / webSearchWireCaps 三件 B5 都已在本包内)。原文那三层 try/catch 的
+ *      目的是「模块缺席也别挡首帧」,包内它们不可能缺席;**try/catch 仍逐条保留**——它护的另一半是
+ *      「函数自己抛」,那半在包内照样成立。
+ *   ③ `process.env` → 入参 `EnvLike`(签名本来就显式收 env;缺省值不存在,调用方必传)。
+ *
+ * 🔴 模块级状态:`cached`(baseUrl+scenario+旋钮 键控的一次性探测缓存)。写读口都在本文件;
+ *    两份实例只是多探一次(不是静默失效),但仍登记进单实例清单。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * liveInitToolFace — 件1(core [931] 壳半场):headless `-p` live 车道 `system/init` 首帧的
+ * `tools` 自报面,从「壳静态工具表」改为「引擎实挂 wire 词表」生成。
+ *
+ * 根因(core [931]/CC209 裁决):壳自报静态表(TodoWrite 在、TaskCreate 族不在)而引擎 wire 实挂
+ * TaskCreate 族(core 1.296+ 默认)且不挂 TodoWrite ⇒ SDK/自动化消费者照自报面配
+ * `--disallowedTools TodoWrite` 之类静默无效(fail-open)。core 1.300 已在引擎侧加名单池审计
+ * advisory(config.toolpolicy.unmatched_names)兜观测面;这里是壳半场 = 自报按实挂生成。
+ *
+ * 真源层级(gap-check 2026-07-16 实测读数,server 1.214.0 / core 1.300.0):
+ *   1. server 无全量挂载探测面:GET /v1/capabilities 只有能力布尔;
+ *      GET /v1/capabilities/scenarios/:name 只含【场景附加】工具(default/code →
+ *      Now/WebFetch/Agent/TaskCreate 族七具),首方 band(Bash/Read/…)由 core prepare-task
+ *      另挂、不进该面 ⇒ 整表无法远端取。
+ *   2. 故缺省场景用壳已知 wire 词表(下表):观测 tap 记录壳 `-p` live 车道 LLM 请求体
+ *      tools[].name(REMOTE_EXEC=host 生产姿势)实测定稿,再按壳自己 stamp 的请求旋钮修正
+ *      (interactiveTools≠false → AskUserQuestion;settings.webSearch 在 → WebSearch)。
+ *   3. per-scenario 差异如实标注:非缺省 scenario(--scenario/SEMA_HEADLESS_SCENARIO)的工具面
+ *      由部署定义(scan/oa = repo-readonly 面,首方 band 是否在位壳无法确证)⇒ 尽力探场景详情面
+ *      GET /v1/capabilities/scenarios/:name 报【场景附加】工具 + runner 恒挂段,并经
+ *      SEMA_DEBUG 如实标注是探测面而非整表;探测失败回退缺省词表(fail-soft,绝不阻塞首帧)。
+ *   4. mock/离线车道(无 SEMA_LIVE_BASEURL)返回 null,调用方保持现状静态表 —— 宪法三问的
+ *      补偿轴:离线态回退静态表,行为字节不变。
+ *
+ * 已知局限(如实):词表按 pin 的 server/core 版本定稿,外接旧引擎或无执行底座的 worker
+ * (REMOTE_EXEC 缺省的裸 worker 不挂 hands band)会有偏差 —— 但相比旧静态表(TodoWrite 幻影 +
+ * TaskCreate 族缺席)已是严格更准的自报;整表探测面等引擎侧补(见 [931] 报告)。
+ */
+import { makeEngineWireClient, resolveWireAuth } from './engineWireSdk.js';
+import { hostLog } from './host.js';
+import { scenarioForPrint } from './scenarioWire.js';
+import { resolveHeadlessInteractiveTools } from './interactiveToolsWire.js';
+import { webSearchFromEnv } from './webSearchWireCaps.js';
+// ── 壳已知 wire 词表(tap 实测 2026-07-16,server 1.214.0/core 1.300.0,壳 -p 缺省旋钮)──────────
+/** hands band(本地/远程执行底座在位时 prepare-task 挂载;壳自 spawn 恒 REMOTE_EXEC=host ⇒ 在位)。 */
+export const ENGINE_HANDS_BAND = [
+    'Bash',
+    'Read',
+    'Edit',
+    'Write',
+    'Glob',
+    'Grep',
+    'NotebookEdit',
+    'LSP',
+    'RepoMap',
+    'EnterWorktree',
+    'ExitWorktree',
+    'Monitor',
+];
+/** 缺省(code/default)场景附加段 —— 与 GET /v1/capabilities/scenarios/{code,default} 详情面
+ *  实测逐字一致(场景工厂 nowTool + assembleFullBodyTools)。
+ *  ⚠️ TodoWrite 故意不在(core 1.296+ 默认 taskList:true ⇒ TodoWrite 不挂,[931] 本案根因);
+ *  TaskCreate 族在 —— 这两条就是本修要对齐的实况。 */
+export const ENGINE_SCENARIO_EXTRAS_DEFAULT = [
+    'Now',
+    'WebFetch',
+    'Agent',
+    'TaskCreate',
+    'TaskGet',
+    'TaskUpdate',
+    'TaskList',
+];
+/** runner 恒挂段(prepare-task 按请求旋钮挂载、场景无关):壳 `-p` 恒 stamp
+ *  selfOrchestration→Workflow、attachments.backgroundTasks→TaskOutput/TaskStop/Monitor/
+ *  SendMessage/AgentTranscript;ReadToolResult/ReportBlocked/ReportFindings/Skill/Cron 族/
+ *  ScheduleWakeup 为 runner 缺省注入。 */
+export const ENGINE_RUNNER_FACE = [
+    'AgentTranscript',
+    'CronCreate',
+    'CronDelete',
+    'CronList',
+    'ReadToolResult',
+    'ReportBlocked',
+    'ReportFindings',
+    'ScheduleWakeup',
+    'SendMessage',
+    'Skill',
+    'TaskOutput',
+    'TaskStop',
+    'Workflow',
+];
+/** [1036]/clay 裁:runner 恒挂段按壳已知 env 门过滤——print 宿主前置 SCHEDULER_ENABLED=false
+ *  (scheduler 族 headless 不挂)/SELF_ORCHESTRATION_ENABLED=false(Workflow 卸)时,自报面
+ *  必须跟实挂(此前静态词表在 env 门形态失真=自报 32 实挂 28,消融实测逮到)。 */
+export function runnerFaceForEnv(env) {
+    let face = [...ENGINE_RUNNER_FACE];
+    if (env.SCHEDULER_ENABLED === 'false') {
+        face = face.filter(n => !['CronCreate', 'CronDelete', 'CronList', 'ScheduleWakeup'].includes(n));
+    }
+    if (env.SELF_ORCHESTRATION_ENABLED === 'false') {
+        face = face.filter(n => n !== 'Workflow');
+    }
+    return face;
+}
+// 按 baseUrl+scenario 缓存(多 turn headless 会话只付一次探测;词表车道零 IO 本就便宜,统一缓存简单)。
+let cached = null;
+/** 测试钩子:清缓存。 */
+export function _resetLiveInitToolFaceForTest() {
+    cached = null;
+}
+/** 非缺省场景的详情面探测:SDK 0.0.52 scenarioCapabilities(name)(GET /v1/capabilities/scenarios/:name,
+ *  同 wire 同 encodeURIComponent)→ { tools(场景附加段), toolset }。fail-soft:任何失败(网络/404/
+ *  形状不符/超时)返回 null,调用层回退缺省词表。等价性记账:超时经 client timeoutMs(缺省 2s 同预算,
+ *  maxRetries=0 单发同原语义);ScenarioDetail 类型面之外仍保留逐字段运行时校验(引擎回什么不轻信)。
+ *  差分:SDK Transport 恒 stamp x-agent-principal(缺省 'anon:shell-live')——原手抄在无 principal
+ *  时省略该头;principal-first 宪法姿势,对 requirePrincipal 部署是 fail-open 改善。 */
+export async function probeScenarioTools(baseUrl, scenario, opts) {
+    const client = makeEngineWireClient({
+        baseUrl,
+        ...(opts?.authToken ? { token: opts.authToken } : {}),
+        ...(opts?.principal ? { principal: opts.principal } : {}),
+        timeoutMs: opts?.timeoutMs ?? 2000,
+        ...(opts?.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+    });
+    if (!client)
+        return null;
+    try {
+        const body = await client.scenarioCapabilities(scenario);
+        if (!Array.isArray(body?.tools))
+            return null;
+        const names = body.tools.filter((t) => typeof t === 'string' && t.length > 0);
+        if (names.length === 0)
+            return null;
+        return {
+            tools: names,
+            ...(typeof body.toolset === 'string' ? { toolset: body.toolset } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * resolveLiveInitToolFace — live 车道 init 首帧 `tools` 的实挂投影。
+ *   · 无 SEMA_LIVE_BASEURL ⇒ null(mock/离线车道,调用方维持静态表现状);
+ *   · 缺省场景 ⇒ hands band + runner 恒挂段 + 旋钮修正(词表车道,零 IO);
+ *   · 非缺省场景 ⇒ 详情面探测成功用【场景附加 + runner 恒挂】(如实标注:hands band 是否在位
+ *     由部署定,不妄报),失败回退缺省词表;
+ *   · 任何内部错误 fail-soft 返回 null(调用方回退静态表,首帧永不因此缺席)。
+ */
+export async function resolveLiveInitToolFace(argv, env, opts) {
+    const baseUrl = env.SEMA_LIVE_BASEURL;
+    if (!baseUrl)
+        return null;
+    try {
+        // 场景解析(scenarioWire 同源:flag > SEMA_HEADLESS_SCENARIO;非法 flag 在 seamQueryEngine
+        // 已 fail-loud 退出,这里只可能看到合法值或解析失败 → 按缺省处理)。
+        let scenario;
+        try {
+            const sc = scenarioForPrint([...argv], env);
+            if (sc.ok && sc.scenario)
+                scenario = sc.scenario;
+        }
+        catch {
+            /* fail-soft → 缺省场景 */
+        }
+        // 旋钮修正① interactiveTools:壳 `-p` 缺省 stamp false ⇒ AskUserQuestion 不挂;
+        // 显式交互意图(--permission-mode plan)/部署旋钮开 ⇒ 引擎缺省挂。
+        let askUserQuestion = false;
+        try {
+            const r = resolveHeadlessInteractiveTools([...argv], env);
+            askUserQuestion = r.fields.interactiveTools !== false;
+        }
+        catch {
+            /* fail-soft → 按缺省 stamp false,不报 AskUserQuestion */
+        }
+        // 旋钮修正② webSearch:壳发 settings.webSearch 时 server 才组 WebSearch 后端
+        // (seamQueryEngine `-p` 车道同源 = env 面 webSearchFromEnv)。
+        let webSearch = false;
+        try {
+            webSearch = webSearchFromEnv(env) !== undefined;
+        }
+        catch {
+            /* fail-soft → 不报 WebSearch */
+        }
+        const knobTools = [
+            ...(askUserQuestion ? ['AskUserQuestion'] : []),
+            ...(webSearch ? ['WebSearch'] : []),
+        ];
+        // 缓存键含旋钮(argv/env 同进程内稳定,但键面完备防同进程内旋钮变化的陈旧命中)。
+        const key = `${baseUrl}::${scenario ?? ''}::${askUserQuestion ? 'q' : ''}${webSearch ? 'w' : ''}::${env.SCHEDULER_ENABLED === 'false' ? 'ns' : ''}${env.SELF_ORCHESTRATION_ENABLED === 'false' ? 'nw' : ''}`;
+        if (cached && cached.key === key)
+            return cached.face;
+        let names;
+        let source = 'wire-vocabulary';
+        if (scenario) {
+            // 非缺省场景:详情面探测(场景附加段真源)。auth 同 live 车道纪律(#118 三态;
+            // loopback-unauthed ⇒ 不出示 bearer —— 对象形不是 string,下面那句照原文过滤掉)。
+            let authToken;
+            try {
+                const t = resolveWireAuth(baseUrl, env.SEMA_LIVE_TOKEN);
+                authToken = typeof t === 'string' ? t : undefined;
+            }
+            catch {
+                /* fail-soft → 无 token 探测 */
+            }
+            const probed = await probeScenarioTools(baseUrl, scenario, {
+                ...(opts?.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+                ...(opts?.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {}),
+                ...(authToken ? { authToken } : {}),
+                ...(env.SEMA_LIVE_PRINCIPAL ? { principal: env.SEMA_LIVE_PRINCIPAL } : {}),
+            });
+            if (probed) {
+                // 如实标注:场景附加(探测面)+ runner 恒挂段;hands band 只在详情面自证 full-body 时
+                // 才报(repo-readonly 等场景不挂首方 band,不妄报)。
+                const handsBand = probed.toolset === 'full-body' ? ENGINE_HANDS_BAND : [];
+                names = [...new Set([...probed.tools, ...handsBand, ...runnerFaceForEnv(env), ...knobTools])];
+                source = 'scenario-probe';
+                if (env.SEMA_DEBUG) {
+                    hostLog('debug', `[sema] init tool face: scenario "${scenario}" detail probe ok (toolset=${probed.toolset ?? 'unknown'}) — reporting scenario tools + runner face${handsBand.length > 0 ? ' + hands band' : ' (hands band not claimed for a non-full-body toolset)'}`);
+                }
+            }
+            else {
+                names = [...ENGINE_HANDS_BAND, ...ENGINE_SCENARIO_EXTRAS_DEFAULT, ...runnerFaceForEnv(env), ...knobTools];
+                if (env.SEMA_DEBUG) {
+                    hostLog('debug', `[sema] init tool face: scenario "${scenario}" detail probe unavailable — falling back to the default wire vocabulary (may not match this scenario's roster)`);
+                }
+            }
+        }
+        else {
+            names = [...ENGINE_HANDS_BAND, ...ENGINE_SCENARIO_EXTRAS_DEFAULT, ...runnerFaceForEnv(env), ...knobTools];
+        }
+        const face = { tools: names.map(name => ({ name })), source };
+        cached = { key, face };
+        return face;
+    }
+    catch {
+        return null; // 调用方回退静态表(首帧契约:永不因自报面缺席)
+    }
+}

package/dist/model/modelFamilies.json

@@ -0,0 +1,63 @@
+{
+    "families": [
+        {
+            "id": "qwen35",
+            "name": "Qwen 3.5 family",
+            "match": "^qwen3\\.5|^qwen3-",
+            "contextWindow": 1000000,
+            "maxTokens": 65536
+        },
+        {
+            "id": "deepseek4",
+            "name": "DeepSeek V4 family",
+            "match": "^deepseek",
+            "contextWindow": 1000000,
+            "maxTokens": 384000,
+            "vision": false
+        },
+        {
+            "id": "claude",
+            "name": "Claude 4/5 family",
+            "match": "^claude-",
+            "contextWindow": 200000,
+            "maxTokens": 64000,
+            "vision": true
+        },
+        {
+            "id": "gpt5",
+            "name": "GPT-5 family",
+            "match": "^gpt-5",
+            "contextWindow": 400000,
+            "maxTokens": 128000,
+            "vision": true
+        },
+        {
+            "id": "kimi",
+            "name": "Kimi K3 family",
+            "match": "^kimi-",
+            "contextWindow": 262144,
+            "maxTokens": 65536
+        },
+        {
+            "id": "glm-5.2",
+            "name": "GLM 5.2 (1M ctx, Z.ai 2026-06-13)",
+            "match": "^glm-5\\.2",
+            "contextWindow": 1000000,
+            "maxTokens": 131072
+        },
+        {
+            "id": "glm",
+            "name": "GLM 4.7/5 family",
+            "match": "^glm-",
+            "contextWindow": 202800,
+            "maxTokens": 131100
+        },
+        {
+            "id": "oss",
+            "name": "Llama / other open models",
+            "match": "",
+            "contextWindow": 128000,
+            "maxTokens": 32768
+        }
+    ]
+}

package/dist/model/providerPresets.d.ts

@@ -0,0 +1,46 @@
+export type PresetModel = {
+    id: string;
+    contextWindow: number;
+    maxTokens: number;
+    /** Marks the provider's cheap sibling — screen-4 execution-slot recommendation. */
+    cheapHint?: boolean;
+};
+export type ProviderPreset = {
+    id: string;
+    name: string;
+    baseUrl: string;
+    api: 'anthropic-messages' | 'openai-completions';
+    authEnv: string;
+    models: PresetModel[];
+    /** Aggregator gateways (OpenRouter): model id is hand-typed, ctx/maxtok via family table. */
+    modelViaFamily?: boolean;
+};
+export type ModelFamily = {
+    id: string;
+    name: string;
+    /** Regex source matched against a model id to PRE-SELECT the family. '' = fallback. */
+    match: string;
+    contextWindow: number;
+    maxTokens: number;
+    /** 图像输入能力(确信才标:false=确认无 vision,true=确认有;缺省=未知不 stamp)。 */
+    vision?: boolean;
+    /**
+     * per-model 已知输出上限 —— 仅 inferFamily 第①层(providerPresets.json 精确表)命中时携带
+     * (=该行 maxTokens)。F2 裁决(clay 2026-07-15)封顶① 的证据位:家族正则/主干层的 maxTokens
+     * 是家族参考值,不是该模型的确证 cap,不带此位。
+     */
+    perModelCap?: number;
+};
+export declare const PROVIDER_PRESETS: ProviderPreset[];
+export declare const MODEL_FAMILIES: ModelFamily[];
+/** Infer context/max from a model id — four evidence tiers, strongest first. */
+export declare function inferFamily(modelId: string): ModelFamily | undefined;
+/** Format token counts like "1m" / "384k". */
+export declare function fmtTokens(n: number): string;
+/** "1m ctx / 384k out" style short metric text. */
+export declare function fmtCtxOut(ctx: number, out: number): string;
+/** Screen-4 execution-slot recommendation: cheapHint first, else a cheap-sounding sibling. */
+export declare function pickCheapCandidate<T extends {
+    id: string;
+    cheapHint?: boolean;
+}>(models: T[], defaultId: string): T | undefined;