@sema-agent/client-core 0.7.0 → 0.8.1

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;

package/dist/model/providerPresets.js

@@ -0,0 +1,160 @@
+/**
+ * ⇄ B6 批搬迁(2026-07-27,设计稿 §3 B6 · B4「四残件」之 model 数据表):cli
+ *    `src/sema/onboard/providerPresets.{ts,json}` + `modelFamilies.json` 整搬(零依赖、纯查表)。
+ *
+ * 🔴 **为什么数据表必须进包**:`modelBudgetRule.defaultMaxTokensFor()`(B2 已搬)的封顶① 参数
+ *    `perModelCap` 只有一个来源 —— `inferFamily()` 第①层精确命中。表留在壳里 ⇒ 库里那条中央规则
+ *    在 web/桌面上**永远拿不到 cap**,`defaultMaxTokensFor(ctx)` 恒走 min(base, ctx/4),
+ *    对 deepseek-chat(cap 8192)这类模型直接超发 ⇒ 网关 400。这不是「少个装饰」。
+ *
+ * 🔴 **两份副本的漂移锁**:搬迁期壳树那两个 JSON 还在(壳侧 shim 批之前 onboard 全族在读它),
+ *    所以 pure 门加了一条 **byte-identity 断言**:本包 `src/model/*.json` 与壳树
+ *    `src/sema/onboard/*.json` 必须**逐字节相等**,任一侧加一行 provider 而另一侧没加即当场红。
+ *    壳侧 shim 落地(那两个 JSON 删除、providerPresets.ts 改 re-export 本包)之后,该断言
+ *    自动降为 SKIP(壳树缺席 = 搬完了),不会变成陈旧的假红。
+ *
+ * ── 以下为原文件的领域说明(逐字保留)────────────────────────────────────────────────────────
+ *
+ * providerPresets.ts — typed accessors over the static preset data tables for
+ * `sema onboard` (GUIDE-ONBOARD-DESIGN §3a/§3b, clay 拍板 2026-07-03).
+ *
+ * DATA lives in the sibling JSON files (providerPresets.json /
+ * modelFamilies.json) — adding a provider or family is a table row, no code
+ * change (维护性原则: new source = one module + one table row). Shapes align
+ * with openclaw's plugin-manifest `modelCatalog.providers` / CenterModel so
+ * translators stay ~free, but centralized (sema has no plugin system).
+ *
+ * All numbers are best-effort defaults (待核 official docs); qwen/glm values
+ * were read from clay's real ~/.openclaw catalog.
+ */
+import presetData from './providerPresets.json' with { type: 'json' };
+import familyData from './modelFamilies.json' with { type: 'json' };
+export const PROVIDER_PRESETS = presetData.presets;
+export const MODEL_FAMILIES = familyData.families;
+// ── 模型自动匹配 v2(clay 07-06:预填要"较为准确的推荐",真实测例驱动,verify/_infer-family-test)──
+// 四层:①preset 大表精确命中(46 provider 的真实 models,最强证据)②容量后缀/名内提示([1m]、-128k)
+// ③家族主干匹配(部署前缀/参数量/量化后缀容忍)④family 表前缀兜底。
+/** 尾部变体词(主干提取时剥):不承载 ctx 信息的营销/角色/量化/参数量后缀。 */
+const VARIANT_TAIL = /(-(plus|pro|max|flash|turbo|mini|lite|chat|coder?|code|instruct|thinking|reasoner|next|preview|latest|fp8|fp16|awq|int[48]|gptq|\d+b))+$/;
+let presetIndexCache = null;
+function presetIndex() {
+    if (presetIndexCache)
+        return presetIndexCache;
+    const exact = new Map();
+    const stems = [];
+    for (const p of PROVIDER_PRESETS) {
+        for (const m of p.models ?? []) {
+            if (!m?.id || !m.contextWindow)
+                continue;
+            const hit = {
+                id: m.id.toLowerCase(),
+                contextWindow: m.contextWindow,
+                maxTokens: m.maxTokens ?? 32768,
+                famId: p.id,
+            };
+            if (!exact.has(hit.id))
+                exact.set(hit.id, hit);
+            stems.push(hit);
+        }
+    }
+    presetIndexCache = { exact, stems };
+    return presetIndexCache;
+}
+function normalizeId(raw) {
+    let id = raw.trim().toLowerCase();
+    const slash = id.lastIndexOf('/');
+    if (slash >= 0)
+        id = id.slice(slash + 1); // org/model → model
+    id = id.replace(/\[[0-9]+[km]\]$/, ''); // [1m] 容量后缀在第②层单独消费
+    return id;
+}
+/** Infer context/max from a model id — four evidence tiers, strongest first. */
+export function inferFamily(modelId) {
+    const raw = modelId.trim().toLowerCase();
+    if (!raw)
+        return undefined;
+    const idx = presetIndex();
+    // ② 前置:显式容量标注恒赢([1m]/[200k] CC 惯例后缀)——用户/工具已声明,别猜。
+    const capSuffix = raw.match(/\[(\d+)([km])\]$/);
+    if (capSuffix) {
+        const n = Number(capSuffix[1]);
+        const ctx = capSuffix[2] === 'm' ? n * 1000000 : n * 1024;
+        const base = inferFamily(raw.replace(/\[[0-9]+[km]\]$/, ''));
+        // perModelCap 透传:后缀只声明 ctx,不改该模型的确证输出 cap(deepseek-chat[1m] 仍 cap 8192)
+        return { id: base?.id ?? 'cap-suffix', name: base?.name ?? 'capacity suffix', match: '', contextWindow: ctx, maxTokens: base?.maxTokens ?? 64000, vision: base?.vision, perModelCap: base?.perModelCap };
+    }
+    const id = normalizeId(raw);
+    // ① preset 大表精确(含剥变体尾巴后再试)——精确命中才带 perModelCap(F2 裁决封顶① 证据位;
+    //   ③ 层主干匹配拿的是家族参考行,不是该模型的确证 cap)
+    const hitOf = (m, exact = false) => ({ id: m.famId, name: m.famId, match: '', contextWindow: m.contextWindow, maxTokens: m.maxTokens, ...(exact ? { perModelCap: m.maxTokens } : {}) });
+    const exact = idx.exact.get(id);
+    if (exact)
+        return hitOf(exact, true);
+    const stripped = id.replace(VARIANT_TAIL, '');
+    if (stripped !== id) {
+        const e2 = idx.exact.get(stripped);
+        if (e2)
+            return hitOf(e2, true);
+    }
+    // ② 名内容量提示(moonshot-v1-128k / *-32k):k=×1024
+    const inline = id.match(/-(\d+)([km])\b/);
+    if (inline) {
+        const n = Number(inline[1]);
+        if ((inline[2] === 'k' && n >= 8) || inline[2] === 'm') {
+            const ctx = inline[2] === 'm' ? n * 1000000 : n * 1024;
+            return { id: 'inline-cap', name: 'capacity in id', match: '', contextWindow: ctx, maxTokens: Math.min(ctx, 65536) };
+        }
+    }
+    // ③ 家族主干:候选主干=preset model id 剥变体尾;主干出现在待匹配 id 中,取最长主干
+    let best = null;
+    let bestLen = 0;
+    for (const m of idx.stems) {
+        const stem = m.id.replace(VARIANT_TAIL, '');
+        if (stem.length >= 6 && id.includes(stem)) {
+            // 同长命中取 ctx 最小=家族原生保守值(服务档扩展如 DashScope 1M 让用户在档位里升,
+            // 预填错大比错小危险——超发请求直接被网关拒)
+            if (stem.length > bestLen || (stem.length === bestLen && best && m.contextWindow < best.contextWindow)) {
+                best = m;
+                bestLen = stem.length;
+            }
+        }
+    }
+    if (best)
+        return hitOf(best);
+    // ④ family 表前缀(anchored → unanchored)
+    for (const fam of MODEL_FAMILIES) {
+        if (fam.match && new RegExp(fam.match, 'i').test(id))
+            return fam;
+    }
+    for (const fam of MODEL_FAMILIES) {
+        if (fam.match && new RegExp(fam.match.replace(/\^/g, ''), 'i').test(id))
+            return fam;
+    }
+    return undefined;
+}
+/** Format token counts like "1m" / "384k". */
+export function fmtTokens(n) {
+    // token 界惯例=二进制 K(clay 07-06:32768 显示 33K 是错的,就是 32K;262144=256K)。
+    // 1024 整除走二进制;否则十进制圆整(200000→200k、202800→203k);M 档十进制(1000000→1m)。
+    // #29⑤(prelaunch audit):十进制整千先判 —— 128000 是十进制圆数,必须渲 128k,不是 125k
+    // (128000%1024==0 曾把它劫进二进制档;其它入口全都叫 128K)。32768/262144/393216 不整除 1000,不受影响。
+    if (n >= 1000000 && n % 100000 === 0)
+        return `${n / 1000000}m`;
+    if (n >= 1000 && n % 1000 === 0)
+        return `${n / 1000}k`;
+    if (n >= 1024 && n % 1024 === 0)
+        return `${n / 1024}k`;
+    if (n >= 1000)
+        return `${Math.round(n / 1000)}k`;
+    return String(n);
+}
+/** "1m ctx / 384k out" style short metric text. */
+export function fmtCtxOut(ctx, out) {
+    return `${fmtTokens(ctx)} ctx / ${fmtTokens(out)} out`;
+}
+/** Screen-4 execution-slot recommendation: cheapHint first, else a cheap-sounding sibling. */
+export function pickCheapCandidate(models, defaultId) {
+    const others = models.filter(m => m.id !== defaultId);
+    return (others.find(m => m.cheapHint) ??
+        others.find(m => /flash|mini|lite|turbo|air|haiku|small/i.test(m.id)));
+}