@twinsearth/dsh-master 3.2.9 → 3.3.0

package/dist-worker/budget-guard.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+const nonNegativeInt = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+};
+export function createBudgetGuard(options = {}) {
+    const enabled = options.enabled === true;
+    const limitTokens = options.limitTokens === undefined ? null : nonNegativeInt(options.limitTokens) || null;
+    const reserveTokens = options.reserveTokens === undefined ? null : nonNegativeInt(options.reserveTokens);
+    const onExhaust = options.onExhaust === 'degrade' ? 'degrade' : 'hard-stop';
+    const degradeModels = (Array.isArray(options.degradeModels) ? options.degradeModels : [])
+        .map((item) => String(item ?? '').trim())
+        .filter(Boolean);
+    const degradeTo = options.degradeTo === undefined ? null : String(options.degradeTo);
+    const degradeAllowed = onExhaust === 'degrade' && degradeTo !== null && degradeModels.includes(degradeTo);
+    let consumedTokens = 0;
+    /** 尚未释放的预留（settle/refund 用它避免重复记账）。 */
+    let reservedTokens = 0;
+    function decide(requested, at = Date.now()) {
+        const effective = degradeAllowed ? 'degrade' : 'hard-stop';
+        const base = {
+            consumedTokens,
+            limitTokens,
+            remainingTokens: limitTokens === null ? null : Math.max(0, limitTokens - consumedTokens),
+            requested,
+            onExhaust: effective,
+            at,
+        };
+        if (!enabled || limitTokens === null) {
+            return { ok: true, ...base };
+        }
+        const remaining = limitTokens - consumedTokens;
+        if (requested <= remaining) {
+            consumedTokens += requested;
+            return { ok: true, ...base, consumedTokens, remainingTokens: limitTokens - consumedTokens };
+        }
+        if (degradeAllowed && degradeTo !== null) {
+            // 降级也要付得起：预留额度放进额度内才放行，否则仍然 fail-closed。
+            if (requested <= remaining) {
+                consumedTokens += requested;
+                return { ok: true, degraded: true, model: degradeTo, ...base, consumedTokens, remainingTokens: limitTokens - consumedTokens };
+            }
+            return {
+                ok: false,
+                code: 'budget-exhausted',
+                message: `预算不足：剩余 ${Math.max(0, remaining)} token，需 ${requested}，且降级模型 ${degradeTo} 也无法容纳`,
+                ...base,
+            };
+        }
+        return {
+            ok: false,
+            code: 'budget-exhausted',
+            message: `预算不足：剩余 ${Math.max(0, remaining)} token，需 ${requested} token（fail-closed，不启动模型调用）`,
+            ...base,
+        };
+    }
+    function beforeModelCall(input) {
+        // 预留值：显式配置优先；否则按「历史字符/4 + 固定输出余量」估算，宁高不低。
+        const estimate = reserveTokens !== null
+            ? reserveTokens
+            : Math.max(1, Math.ceil(Math.max(0, Number(input?.historyChars) || 0) / 4) + 256);
+        const decision = decide(estimate);
+        // 降级决策不消耗额外额度（预留已在 decide 内计入）。
+        if (decision.ok)
+            reservedTokens += estimate;
+        return decision;
+    }
+    function refund(tokens) {
+        const amount = nonNegativeInt(tokens);
+        consumedTokens = Math.max(0, consumedTokens - amount);
+        // 预留随之释放，否则后续 settle 会把同一份额度重复记账。
+        reservedTokens = Math.max(0, reservedTokens - amount);
+    }
+    function settle(tokens) {
+        const actual = nonNegativeInt(tokens);
+        // 结算：先退掉**尚未释放**的预留，再按真实用量记账（实际可能为 0）。
+        // 之前这里写的是 `- 0`（死代码），会把预留与真实用量重复计入，导致额度被提前耗尽。
+        consumedTokens = Math.max(0, consumedTokens - reservedTokens) + actual;
+        reservedTokens = 0;
+    }
+    function describe() {
+        return {
+            enabled,
+            limitTokens,
+            consumedTokens,
+            onExhaust: degradeAllowed ? onExhaust : 'hard-stop',
+            degradeTo: degradeAllowed ? degradeTo : null,
+            degradeModels: [...degradeModels],
+        };
+    }
+    return Object.freeze({ enabled, get consumedTokens() { return consumedTokens; }, beforeModelCall, refund, settle, describe });
+}

package/dist-worker/ccs.js

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+const tokensOf = (text) => (text.length > 0 ? Math.ceil(text.length / 4) : 0);
+/** 派发结果是否算「失败」：抛错、系统拒绝、执行报错都算。 */
+function resultFailed(text) {
+    const value = String(text ?? '');
+    if (value.startsWith('【系统拒绝】'))
+        return 'tool-denied';
+    if (value.startsWith('执行报错'))
+        return 'tool-error';
+    return null;
+}
+export function createCcs(options) {
+    if (!options?.dispatcher || typeof options.dispatcher.execute !== 'function') {
+        throw new Error('ccs requires the native dispatcher (worker/tools.ts execute)');
+    }
+    const clock = typeof options.clock === 'function' ? options.clock : () => Date.now();
+    const budget = options.budget ?? null;
+    let attempted = 0;
+    let dispatched = 0;
+    let failed = 0;
+    let fallbacks = 0;
+    function cert(input, fields) {
+        return {
+            edgeId: String(input.edge?.id ?? ''),
+            toolName: String(input.edge?.toolName ?? ''),
+            schemaHash: String(input.edge?.schemaHash ?? ''),
+            guardExpr: String(input.edge?.guard?.expr ?? ''),
+            receiptDigest: String(input.receipt?.digest ?? ''),
+            replacedCallbackId: String(input.replacedCallbackId ?? ''),
+            viaNativeDispatcher: true,
+            taskId: String(input.taskId ?? ''),
+            step: Number(input.step ?? 0),
+            dispatched: false,
+            moduleId: input.moduleId ?? 'b3-ccs',
+            savedTokens: Math.max(0, Number(input.savedTokens ?? 0) || 0),
+            at: clock(),
+            ...fields,
+        };
+    }
+    async function substitute(input) {
+        attempted += 1;
+        // ⓪ 取消信号：替换路径不得绕过取消（I8）。
+        if (input.signal?.aborted === true) {
+            failed += 1;
+            fallbacks += 1;
+            return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: 'aborted' }) };
+        }
+        // ① 预算闸：替模型做的这次调用同样要付得起（禁止绕过 budget 检查）。
+        if (budget) {
+            const decision = budget.beforeModelCall({ historyChars: 0 });
+            if (!decision.ok) {
+                failed += 1;
+                fallbacks += 1;
+                return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: decision.code ?? 'budget-exhausted' }) };
+            }
+            // 替模型省下的这次调用不产生模型 token：把刚扣的预留退回去。
+            budget.refund(decision.requested);
+        }
+        // ② 经**未改动的原生派发器**执行：权限/Mandate/取消/超时/审计全部照旧。
+        let text;
+        try {
+            text = await options.dispatcher.execute({ name: input.edge.toolName, arguments: JSON.stringify(input.args ?? {}) }, {
+                workspace: input.workspace,
+                signal: input.signal,
+                timeoutMs: Math.max(1, Number(input.timeoutMs) || 1),
+                mandate: input.mandate,
+            });
+        }
+        catch (error) {
+            failed += 1;
+            fallbacks += 1;
+            const message = error instanceof Error ? error.message : String(error);
+            return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: `dispatch-threw:${message}` }) };
+        }
+        // ③ 派发器返回的「拒绝/报错」也算失败：不吞错、不假装成功。
+        const failure = resultFailed(text);
+        if (failure) {
+            failed += 1;
+            fallbacks += 1;
+            return { ok: false, text: null, fallback: true, certificate: cert(input, { dispatched: false, error: failure }) };
+        }
+        dispatched += 1;
+        return {
+            ok: true,
+            text,
+            fallback: false,
+            certificate: cert(input, {
+                dispatched: true,
+                resultDigest: `sha256:${tokensOf(text).toString(36)}`,
+                resultChars: text.length,
+            }),
+        };
+    }
+    function stats() {
+        return { attempted, dispatched, failed, fallbacks };
+    }
+    return Object.freeze({ substitute, stats });
+}

package/dist-worker/cost-hooks.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+const nonNegative = (value) => {
+    const n = Number(value);
+    return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+};
+/** 把 provider 的 usage 归一成 {input, output, total}；缺 total 时用 input+output。 */
+export function normalizeCostUsage(usage) {
+    const input = nonNegative(usage?.promptTokens);
+    const output = nonNegative(usage?.completionTokens);
+    const total = nonNegative(usage?.totalTokens) || input + output;
+    return { input, output, total };
+}
+export function createCostHooks(options = {}) {
+    const clock = typeof options.clock === 'function' ? options.clock : () => Date.now();
+    const emit = (event) => {
+        const sink = options.sink;
+        if (!sink || typeof sink.cost !== 'function')
+            return;
+        try {
+            sink.cost(event);
+        }
+        catch {
+            /* 成本观测失败不得影响控制流 */
+        }
+    };
+    const hooks = {
+        beforeModelCall(input) {
+            emit({
+                point: 'beforeModelCall',
+                at: clock(),
+                ticketId: String(input?.ticketId ?? ''),
+                stepIndex: Number(input?.stepIndex) || 0,
+                model: input?.model === undefined ? undefined : String(input.model),
+                historyChars: nonNegative(input?.historyChars),
+            });
+        },
+        afterModelResponse(input) {
+            emit({
+                point: 'afterModelResponse',
+                at: clock(),
+                ticketId: String(input?.ticketId ?? ''),
+                stepIndex: Number(input?.stepIndex) || 0,
+                usage: input?.usage ?? normalizeCostUsage(),
+                latencyMs: nonNegative(input?.latencyMs),
+                estimated: input?.estimated === true,
+            });
+        },
+        beforeToolDispatch(input) {
+            emit({
+                point: 'beforeToolDispatch',
+                at: clock(),
+                ticketId: String(input?.ticketId ?? ''),
+                stepIndex: Number(input?.stepIndex) || 0,
+                toolName: String(input?.toolName ?? ''),
+                argsChars: nonNegative(input?.argsChars),
+            });
+        },
+        afterToolReceipt(input) {
+            emit({
+                point: 'afterToolReceipt',
+                at: clock(),
+                ticketId: String(input?.ticketId ?? ''),
+                stepIndex: Number(input?.stepIndex) || 0,
+                toolName: String(input?.toolName ?? ''),
+                resultChars: nonNegative(input?.resultChars),
+                truncated: input?.truncated === true,
+                compaction: input?.compaction,
+            });
+        },
+        degraded(input) {
+            emit({
+                point: 'degraded',
+                at: clock(),
+                ticketId: String(input?.ticketId ?? ''),
+                stepIndex: Number(input?.stepIndex) || 0,
+                toolName: input?.module === undefined ? undefined : String(input.module),
+                degraded: {
+                    module: String(input?.module ?? ''),
+                    phase: input?.phase ?? 'transform',
+                    message: String(input?.message ?? ''),
+                    count: nonNegative(input?.count) || 1,
+                },
+            });
+        },
+    };
+    return Object.freeze(hooks);
+}
+/** 合并宿主注入的覆盖实现：先跑默认实现，再跑覆盖；任一失败都不影响另一个。 */
+export function mergeCostHooks(base, override) {
+    if (!override)
+        return base;
+    const chain = (key) => {
+        const extra = override[key];
+        if (typeof extra !== 'function')
+            return base[key];
+        return ((...args) => {
+            try {
+                base[key](...args);
+            }
+            catch { /* ignore */ }
+            try {
+                extra(...args);
+            }
+            catch { /* ignore */ }
+        });
+    };
+    return Object.freeze({
+        beforeModelCall: chain('beforeModelCall'),
+        afterModelResponse: chain('afterModelResponse'),
+        beforeToolDispatch: chain('beforeToolDispatch'),
+        afterToolReceipt: chain('afterToolReceipt'),
+        degraded: chain('degraded'),
+    });
+}

package/dist-worker/cost-modules.js

@@ -0,0 +1,330 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+import { createToolCompactor } from "./tool-compact.js";
+import { normalizeCompactMode } from "./tool-compact.js";
+import { createSpillStore } from "./spill.js";
+const estimateTokens = (chars) => (chars > 0 ? Math.ceil(chars / 4) : 0);
+export function createModuleRegistry(options = {}) {
+    const toolModules = [];
+    const decisionModules = [];
+    const ids = new Set();
+    const errors = [];
+    const degradedList = [];
+    const degradedCounts = new Map();
+    let stats = { evaluated: 0, applied: 0, savedChars: 0 };
+    const byModule = {};
+    const noteError = (message) => {
+        if (errors.length < 20)
+            errors.push(message);
+    };
+    /** 模块异常：fail-open 留痕（不改写本次输出、不阻断 Agent Loop）。 */
+    const noteDegraded = (module, phase, error) => {
+        const message = error instanceof Error ? error.message : String(error);
+        noteError(`${module}: ${message}`);
+        const key = `${module}|${phase}`;
+        const previous = degradedCounts.get(key);
+        const count = (previous?.count ?? 0) + 1;
+        const event = { module, phase, message, count, at: Date.now() };
+        degradedCounts.set(key, event);
+        const existing = degradedList.findIndex((item) => item.module === module && item.phase === phase);
+        if (existing >= 0)
+            degradedList[existing] = event;
+        else
+            degradedList.push(event);
+        if (count === 1 || count % 20 === 0) {
+            try {
+                options.onDegraded?.(event);
+            }
+            catch { /* 留痕失败不得影响执行 */ }
+        }
+    };
+    function register(module) {
+        if (!module || typeof module !== 'object')
+            return false;
+        const id = String(module.id ?? '');
+        if (!id || ids.has(id))
+            return false;
+        ids.add(id);
+        if (module.kind === 'tool')
+            toolModules.push(module);
+        else if (module.kind === 'decision')
+            decisionModules.push(module);
+        else
+            return false;
+        return true;
+    }
+    for (const module of options.modules ?? [])
+        register(module);
+    /**
+     * ③ 派发前：顺序应用 `beforeDispatch`。
+     * **只有 enforce 档才真的改写/屏蔽**；shadow 只记录「本可…」，observe/off 跳过。
+     */
+    function beforeToolDispatch(input) {
+        const attributions = [];
+        let call = input.call;
+        for (const module of toolModules) {
+            if (module.mode === 'off' || typeof module.beforeDispatch !== 'function')
+                continue;
+            try {
+                if (!module.appliesTo(call.name))
+                    continue;
+                const ctx = { ticketId: input.ticketId, stepIndex: input.stepIndex, mode: module.mode, originalToolName: input.call.name };
+                const next = module.beforeDispatch(call, ctx);
+                const wouldChange = next === null || next.name !== call.name || JSON.stringify(next.args ?? {}) !== JSON.stringify(call.args ?? {});
+                if (!wouldChange)
+                    continue;
+                const attribution = {
+                    module: module.id,
+                    mode: module.mode,
+                    applied: module.mode === 'enforce',
+                    originalChars: 0,
+                    resultChars: 0,
+                    savedChars: 0,
+                    estimatedTokens: 0,
+                    meta: { point: 'beforeDispatch', hidden: next === null, from: call.name, to: next === null ? null : next.name },
+                };
+                attributions.push(attribution);
+                if (module.mode !== 'enforce')
+                    continue;
+                if (next === null) {
+                    return { call, hidden: true, hiddenBy: module.id, reason: 'hidden-by-module', attributions, errors: errors.slice() };
+                }
+                call = next;
+            }
+            catch (error) {
+                noteDegraded(module.id, 'beforeDispatch', error);
+            }
+        }
+        return { call, hidden: false, attributions, errors: errors.slice() };
+    }
+    /** ④ 回执：顺序应用 `afterReceipt`（shadow 只算不换）。 */
+    function afterToolReceipt(input) {
+        const attributions = [];
+        let text = String(input.text ?? '');
+        for (const module of toolModules) {
+            if (module.mode === 'off' || typeof module.afterReceipt !== 'function')
+                continue;
+            try {
+                if (!module.appliesTo(input.toolName))
+                    continue;
+                const ctx = { ticketId: input.ticketId, stepIndex: input.stepIndex, mode: module.mode, originalToolName: input.toolName };
+                const out = module.afterReceipt({ text }, ctx);
+                if (!out || typeof out.text !== 'string')
+                    continue;
+                const originalChars = text.length;
+                const resultChars = out.text.length;
+                const savedChars = Math.max(0, originalChars - resultChars);
+                // §5.4：模块可给出拟合式算出的 token 归因；否则退回字符/4 估算。
+                const moduleTokens = Math.max(0, Number(out.savedTokens ?? 0) || 0);
+                const estimatedTokens = moduleTokens > 0 ? moduleTokens : estimateTokens(savedChars);
+                // 是否「真的替换」由模式决定：模块在 shadow 下不得改变执行；
+                // A1 自己在「不更短」时返回原文，因此长度纪律不放在注册表里。
+                const applied = module.mode === 'enforce' && out.text !== text;
+                attributions.push({
+                    module: module.id,
+                    mode: module.mode,
+                    applied,
+                    originalChars,
+                    resultChars: applied ? resultChars : originalChars,
+                    savedChars: applied ? savedChars : 0,
+                    estimatedTokens: applied ? estimatedTokens : 0,
+                    meta: { point: 'afterReceipt', toolName: input.toolName, wouldSaveChars: savedChars },
+                });
+                stats.evaluated += 1;
+                if (applied) {
+                    stats.applied += 1;
+                    stats.savedChars += savedChars;
+                    byModule[module.id] = (byModule[module.id] ?? 0) + estimatedTokens;
+                    text = out.text;
+                }
+            }
+            catch (error) {
+                noteDegraded(module.id, 'afterReceipt', error);
+            }
+        }
+        return { text, attributions, errors: errors.slice() };
+    }
+    /* ---------------- B 类：决策复用（§7 SPI） ---------------- */
+    /** ② 作者步骤：每个 B 模块产出一张候选图（异常 fail-open 留痕）。 */
+    async function authorGraphs(turn) {
+        const drafts = [];
+        for (const module of decisionModules) {
+            if (module.mode === 'off' || typeof module.author !== 'function')
+                continue;
+            try {
+                const draft = await module.author(turn);
+                if (draft && Array.isArray(draft.edges) && draft.edges.length > 0)
+                    drafts.push({ module: module.id, draft });
+            }
+            catch (error) {
+                noteDegraded(module.id, 'author', error);
+            }
+        }
+        return { drafts, errors: errors.slice() };
+    }
+    /** ④ 守卫：收集所有命中（observe 只计数，shadow 落证书，enforce 可替换）。 */
+    function guardReceipt(input) {
+        const verdicts = [];
+        for (const module of decisionModules) {
+            if (module.mode === 'off' || typeof module.guard !== 'function')
+                continue;
+            try {
+                const verdict = module.guard(input.receipt, input.graph);
+                if (!verdict || typeof verdict !== 'object')
+                    continue;
+                verdicts.push({ module: module.id, mode: module.mode, verdict });
+            }
+            catch (error) {
+                noteDegraded(module.id, 'guard', error);
+            }
+        }
+        const hit = verdicts.find((item) => item.verdict.hit === true) ?? null;
+        return { verdicts, hit, errors: errors.slice() };
+    }
+    /**
+     * 命中后的替换：只有 `enforce` 真的执行（且需策略层白名单放行，由调用方判定）；
+     * `shadow` 只产出「本可替换」的证书草案，不执行任何工具。
+     */
+    async function substitute(input) {
+        for (const module of decisionModules) {
+            if (module.mode === 'off' || typeof module.substitute !== 'function')
+                continue;
+            if (module.id !== input.ctx.ticketId && false)
+                continue;
+            try {
+                const certificate = await module.substitute(input.edge, input.receipt, input.ctx);
+                if (!certificate)
+                    continue;
+                // 非原生派发的证书一律拒绝（§5.5 硬约束）。
+                if (certificate.viaNativeDispatcher !== true) {
+                    noteDegraded(module.id, 'substitute', new Error('substitute must go through the native dispatcher'));
+                    continue;
+                }
+                const executed = input.mode === 'enforce';
+                return { executed, certificate, module: module.id, errors: errors.slice() };
+            }
+            catch (error) {
+                noteDegraded(module.id, 'substitute', error);
+            }
+        }
+        return { executed: false, certificate: null, module: null, errors: errors.slice() };
+    }
+    function beforeModelCall(info) {
+        for (const module of decisionModules) {
+            try {
+                module.beforeModelCall?.(info);
+            }
+            catch (error) {
+                noteDegraded(module.id, 'beforeModelCall', error);
+            }
+        }
+    }
+    function afterModelResponse(info) {
+        for (const module of decisionModules) {
+            try {
+                module.afterModelResponse?.(info);
+            }
+            catch (error) {
+                noteDegraded(module.id, 'afterModelResponse', error);
+            }
+        }
+    }
+    function describe() {
+        return [
+            ...toolModules.map((module) => ({ id: module.id, kind: module.kind, mode: module.mode, surface: module.surface })),
+            ...decisionModules.map((module) => ({ id: module.id, kind: module.kind, mode: module.mode, surface: 'worker' })),
+        ];
+    }
+    /** 工具面常驻成本：各 A 模块自报之和（供 prompt 成本报表）。 */
+    function promptCost() {
+        const byModuleCost = {};
+        let toolTokens = 0;
+        let schemaCount = 0;
+        for (const module of toolModules) {
+            if (typeof module.promptCost !== 'function')
+                continue;
+            try {
+                const cost = module.promptCost();
+                const tokens = Math.max(0, Number(cost?.toolTokens ?? 0) || 0);
+                const count = Math.max(0, Number(cost?.schemaCount ?? 0) || 0);
+                byModuleCost[module.id] = { toolTokens: tokens, schemaCount: count };
+                toolTokens += tokens;
+                schemaCount += count;
+            }
+            catch (error) {
+                noteDegraded(module.id, 'afterReceipt', error);
+            }
+        }
+        return { toolTokens, schemaCount, byModule: byModuleCost };
+    }
+    function summary() {
+        return {
+            evaluated: stats.evaluated,
+            applied: stats.applied,
+            savedChars: stats.savedChars,
+            estimatedTokens: estimateTokens(stats.savedChars),
+            byModule: { ...byModule },
+        };
+    }
+    function degraded() {
+        return degradedList.map((item) => ({ ...item }));
+    }
+    function resetTask() {
+        stats = { evaluated: 0, applied: 0, savedChars: 0 };
+        for (const key of Object.keys(byModule))
+            delete byModule[key];
+        errors.length = 0;
+        degradedList.length = 0;
+        degradedCounts.clear();
+    }
+    return Object.freeze({
+        register,
+        beforeToolDispatch,
+        afterToolReceipt,
+        transformToolResult: afterToolReceipt,
+        authorGraphs,
+        guardReceipt,
+        substitute,
+        beforeModelCall,
+        afterModelResponse,
+        describe,
+        promptCost,
+        summary,
+        degraded,
+        resetTask,
+    });
+}
+/** A1：把 tool-compact 的纯格式化函数适配成 ToolModule（SPI §6）。 */
+export function createCompactModule(mode, options = {}) {
+    const resolved = normalizeCompactMode(mode);
+    // spill：大输出落盘 + 摘要（原文仍可回读）。只在 enforce 生效，且必须有 workspace。
+    const spill = options.spill !== false && options.workspace
+        ? createSpillStore({ workspace: options.workspace })
+        : null;
+    const compactor = createToolCompactor({
+        mode: 'enforce',
+        spill: spill ? { save: (input) => spill.save({ ticketId: 'worker', stepIndex: 0, toolName: 'tool', text: input.text }) } : null,
+        spillThresholdChars: options.spillThresholdChars,
+    });
+    const handled = new Set(['fs_read_file', 'fs_list_dir', 'fs_write_file', 'exec_shell_in_vm']);
+    return Object.freeze({
+        id: 'a1-compact',
+        kind: 'tool',
+        surface: 'worker',
+        mode: resolved,
+        appliesTo(toolName) {
+            return handled.has(String(toolName ?? ''));
+        },
+        afterReceipt(result, ctx) {
+            // 候选压缩结果一律算出；**由注册表按模式决定是否真的替换**（shadow 不改变执行）。
+            const candidate = compactor.compact({ toolName: ctx.originalToolName, text: result.text });
+            if (!candidate.evaluated || !candidate.applied)
+                return null;
+            return { text: candidate.text, truncated: result.truncated, savedTokens: candidate.estimatedTokens };
+        },
+        /** A1 不新增常驻工具：prompt 成本为 0（真实 schema 成本由 Agent Loop 另计）。 */
+        promptCost() {
+            return { toolTokens: 0, schemaCount: 0 };
+        },
+    });
+}

package/dist-worker/cost-spi.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+export {};