@twinsearth/dsh-master 0.0.0-stage → 3.2.8

package/dist-host/index.js

@@ -0,0 +1,260 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * Dsh-Master（房主）核心插件 / 主 Agent 控制面。
+ *
+ * 定位：与瓮城 dsh-Fang 并行的主插件。房主不接管瓮城的镜像/原身/分身生命周期，
+ * 只在自己的命名空间里托管三个 Agent 子插件，并通过 DSH 服务键与瓮城协作：
+ *
+ *   ┌──────────────────────────── DSH Host ────────────────────────────┐
+ *   │  瓮城 bundle (dsh-Fang)         房主 bundle (dsh-Master)          │
+ *   │  mirror / essence / derived      core ─┬─ superagent  (fork)      │
+ *   │  fangForker / fangDecisionCenter      ├─ cost        (fork)      │
+ *   │                                       └─ dual        (mother/essence)
+ *   └──────────────────────────────────────────────────────────────────┘
+ *
+ * 协作只走服务键（见 kernel.mjs FANG_SERVICE）：房主不 import 瓮城代码；瓮城服务
+ * 不可用时子插件必须 fail-closed，绝不本地降级执行。
+ */
+import { FANG_CONTRACT_MIN, FANG_SERVICE, MASTER_VERSION, ROLE_MATRIX, ROW, SERVICE, SUBPLUGIN_CATALOG, bearerOf, detectRole, enabledOf, jsonResponse, masterError, readJsonBody, roleAllowed, safeGet, } from "./kernel.js";
+import { BRIDGE_PATH, filterEnv } from "./superagent/dispatch.js";
+import { createBridgeTokenManager } from "./superagent/bridge-tokens.js";
+export const name = 'dsh-master';
+export const inject = [];
+/** 状态路由（Client UI 读取；只读、非敏感、loopback-only 由宿主 webServer 保证）。 */
+export const STATUS_ROUTE = '/dsh-master/api/status';
+/**
+ * 房主核心 apply。
+ * @param {object} ctx Cordis context
+ * @param {object} [config] loader 行配置
+ */
+export function apply(ctx, config = {}) {
+    if (!enabledOf(config))
+        return undefined;
+    const role = detectRole();
+    const startedAt = Date.now();
+    // 桥 token：自动轮换 + 宽限重叠 + 摘要持久化 + 审计（v3.2.5）。
+    const bridgeTokens = createBridgeTokenManager({
+        staticToken: String(config.bridgeToken ?? '').trim(),
+        rotateMs: config.bridgeTokenRotateMs,
+        graceMs: config.bridgeTokenGraceMs,
+        dataDir: String(config.dataDir ?? '').trim(),
+        auditLimit: config.tokenAuditLimit,
+    });
+    const logInfo = (...args) => { try {
+        ctx?.logger?.info?.(...args);
+    }
+    catch { /* ignore */ } };
+    const logWarn = (...args) => { try {
+        ctx?.logger?.warn?.(...args);
+    }
+    catch { /* ignore */ } };
+    const subplugins = new Map();
+    const cooperation = () => {
+        const services = {};
+        for (const [alias, serviceName] of Object.entries(FANG_SERVICE)) {
+            const found = safeGet(ctx, serviceName);
+            services[alias] = {
+                service: serviceName,
+                available: Boolean(found),
+                spawn: typeof found?.spawn === 'function',
+                decide: typeof found?.decide === 'function' || typeof found?.create === 'function',
+            };
+        }
+        return {
+            contract: `dsh-fang >= ${FANG_CONTRACT_MIN}`,
+            mode: 'service-key-only',
+            services,
+            available: Object.values(services).some((item) => item.available),
+            canSpawn: services.forker.spawn === true,
+        };
+    };
+    const catalog = () => SUBPLUGIN_CATALOG.map((entry) => {
+        const active = subplugins.get(entry.id) ?? null;
+        const allowed = roleAllowed(entry.row, role);
+        return {
+            id: entry.id,
+            row: entry.row,
+            name: entry.name,
+            nameEn: entry.nameEn,
+            roadmap: entry.roadmap,
+            description: entry.description,
+            allowedRoles: entry.roles,
+            roleAllowed: allowed,
+            active: Boolean(active) && allowed,
+            registered: Boolean(active),
+            capabilities: active?.capabilities ?? [],
+            blockedReason: active || allowed ? null : `role-not-allowed:${role}`,
+        };
+    });
+    const service = {
+        id: SERVICE.master,
+        name: 'dsh-master',
+        version: MASTER_VERSION,
+        role,
+        startedAt,
+        /** 子插件启动时注册；重复 id 直接抛（fail loud）。 */
+        registerSubplugin(descriptor) {
+            const id = String(descriptor?.id ?? '').trim();
+            if (!id)
+                throw new Error('dsh-master: subplugin id is required');
+            if (subplugins.has(id))
+                throw new Error(`dsh-master: subplugin already registered: ${id}`);
+            const record = Object.freeze({
+                id,
+                name: String(descriptor.name ?? id),
+                capabilities: Object.freeze([...(descriptor.capabilities ?? [])].map(String)),
+                description: String(descriptor.description ?? ''),
+                registeredAt: Date.now(),
+            });
+            subplugins.set(id, record);
+            logInfo(`[dsh-master] subplugin registered: ${id} (${record.capabilities.join(',')})`);
+            return () => { subplugins.delete(id); };
+        },
+        subplugins() {
+            return catalog();
+        },
+        cooperation,
+        /** 桥 token 运维：只读描述 / 审计 / 手动轮换（无明文 token）。 */
+        bridgeTokens: () => bridgeTokens.describe(),
+        bridgeTokenAudit: (limit) => bridgeTokens.audit(limit),
+        rotateBridgeToken: () => {
+            const rotated = bridgeTokens.rotate({ reason: 'manual' });
+            return { ok: true, token: rotated.token, tokenId: rotated.tokenId, graceMs: rotated.graceMs };
+        },
+        /** 统一状态：Client 状态页与工具/测试共用。 */
+        status() {
+            const dispatchCfg = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {};
+            return {
+                ok: true,
+                id: 'dsh-master',
+                version: MASTER_VERSION,
+                role,
+                startedAt,
+                uptimeMs: Date.now() - startedAt,
+                cooperation: cooperation(),
+                subplugins: catalog(),
+                roleMatrix: ROLE_MATRIX,
+                bridge: {
+                    enabled: Boolean(String(config.bridgeToken ?? '').trim()) || bridgeTokens.describe().tokens.length > 0,
+                    dispatchConfigured: Boolean(String(dispatchCfg.homeDir ?? '').trim() && String(dispatchCfg.cliPath ?? '').trim()),
+                    tokens: bridgeTokens.describe(),
+                    tokenAudit: bridgeTokens.audit(10),
+                },
+            };
+        },
+        /** 房主自检：缺瓮城服务时给出可读原因，不抛。 */
+        health() {
+            const coop = cooperation();
+            const warnings = [];
+            if (!coop.available)
+                warnings.push('fang-unavailable: 瓮城 bundle 未加载或版本低于契约');
+            else if (!coop.canSpawn)
+                warnings.push('fang-forker-spawn-unavailable');
+            return {
+                ok: warnings.length === 0,
+                version: MASTER_VERSION,
+                role,
+                warnings,
+                cooperation: coop,
+            };
+        },
+    };
+    try {
+        ctx.effect(() => ctx.provide(SERVICE.master, service));
+    }
+    catch { /* fake ctx */ }
+    try {
+        ctx.effect(() => () => bridgeTokens.stop());
+    }
+    catch { /* fake ctx */ }
+    try {
+        if (typeof ctx.provide === 'function' && typeof ctx.effect !== 'function')
+            ctx.provide(SERVICE.master, service);
+    }
+    catch { /* ignore */ }
+    // Client 状态页数据源：只读、limit 到 non-sensitive 字段。
+    try {
+        if (typeof ctx.inject === 'function') {
+            ctx.inject(['webServer'], (child) => {
+                const webServer = child?.get?.('webServer') ?? child?.webServer;
+                if (!webServer || typeof webServer.register !== 'function')
+                    return;
+                try {
+                    webServer.register({
+                        kind: 'exact',
+                        path: STATUS_ROUTE,
+                        method: 'GET',
+                        handler: async (req, res) => jsonResponse(res, 200, service.status()),
+                    });
+                }
+                catch (error) {
+                    logWarn(`[dsh-master] status route registration failed: ${String(error?.message ?? error)}`);
+                }
+                // v3.2.3：原身 Router → 母体 forker 的跨进程派发桥。
+                try {
+                    webServer.register({
+                        kind: 'exact',
+                        path: BRIDGE_PATH,
+                        method: 'POST',
+                        handler: async (req, res) => {
+                            const bridge = bridgeTokens.describe();
+                            if (!bridge.enabled)
+                                return jsonResponse(res, 503, masterError('bridge-disabled', 'bridgeToken is not configured in this host'));
+                            const verified = bridgeTokens.verify(bearerOf(req?.headers));
+                            if (!verified.ok) {
+                                return jsonResponse(res, 401, masterError('bridge-unauthorized', 'invalid bridge token'), { reason: verified.reason });
+                            }
+                            const parsed = await readJsonBody(req);
+                            if (!parsed.ok) {
+                                return jsonResponse(res, parsed.code === 'body-too-large' ? 413 : 400, masterError(parsed.code, 'invalid bridge request body'));
+                            }
+                            const ticket = parsed.body?.ticket;
+                            if (!ticket || typeof ticket !== 'object' || typeof ticket.id !== 'string' || !ticket.id) {
+                                return jsonResponse(res, 400, masterError('ticket-invalid', 'bridge request must include a ticket with id'));
+                            }
+                            const forker = safeGet(ctx, FANG_SERVICE.forker);
+                            if (!forker || typeof forker.spawn !== 'function') {
+                                return jsonResponse(res, 503, masterError('fang-forker-unavailable', 'fangForker.spawn is not available in this host'));
+                            }
+                            const dispatchCfg = config.dispatch && typeof config.dispatch === 'object' ? config.dispatch : {};
+                            const homeDir = String(dispatchCfg.homeDir ?? '').trim();
+                            const cliPath = String(dispatchCfg.cliPath ?? '').trim();
+                            const profile = String(dispatchCfg.profile ?? '').trim() || 'default';
+                            if (!homeDir || !cliPath) {
+                                return jsonResponse(res, 503, masterError('dispatch-config-incomplete', 'bridge host requires dispatch.homeDir and dispatch.cliPath'));
+                            }
+                            const env = { ...filterEnv(parsed.body?.env), DSH_MASTER_TICKET: JSON.stringify(ticket) };
+                            try {
+                                const fork = await forker.spawn({ homeDir, cliPath, profile, taskTitle: `SuperAgent ${ticket.id}`, env });
+                                if (fork && fork.ok === false) {
+                                    return jsonResponse(res, 502, { ...masterError('fang-spawn-failed', 'forker.spawn returned an error', fork), fork });
+                                }
+                                return jsonResponse(res, 200, { ok: true, fork });
+                            }
+                            catch (error) {
+                                return jsonResponse(res, 500, masterError('fang-spawn-threw', String(error?.message ?? error)));
+                            }
+                        },
+                    });
+                }
+                catch (error) {
+                    logWarn(`[dsh-master] bridge route registration failed: ${String(error?.message ?? error)}`);
+                }
+            });
+        }
+    }
+    catch { /* 宿主没有 webServer 时状态仍可通过服务读取 */ }
+    logInfo(`[dsh-master] core ready version=${MASTER_VERSION} role=${role}`);
+    return service;
+}
+/** 给子插件复用：取核心服务；不可用时返回 error（启动阶段应 fail loud）。 */
+export function requireMaster(ctx) {
+    const master = safeGet(ctx, SERVICE.master);
+    if (!master || typeof master.registerSubplugin !== 'function') {
+        return { ok: false, error: masterError('master-core-unavailable', 'dsh-master core service is not available') };
+    }
+    return { ok: true, master };
+}
+export { ROLE_MATRIX, ROW, SERVICE, SUBPLUGIN_CATALOG };

package/dist-host/kernel.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * Dsh-Master（房主）共享内核（v3.2.3）。
+ * 只放纯函数与常量；Node 侧工具用到的 crypto 是唯一内置模块依赖。
+ * 与瓮城 dsh-Fang 的协作只走 DSH 服务键，不 import fang 代码。
+ */
+import crypto from 'node:crypto';
+export const MASTER_VERSION = '3.2.8';
+export const FANG_CONTRACT_MIN = '3.1.14';
+export const SERVICE = Object.freeze({
+    master: 'dshMaster',
+    superagentRouter: 'dshMasterSuperagentRouter',
+    superagentWorker: 'dshMasterSuperagentWorker',
+    cost: 'dshMasterCost',
+    dual: 'dshMasterDual',
+});
+export const FANG_SERVICE = Object.freeze({
+    orchestrator: 'fang',
+    forker: 'fangForker',
+    decisionCenter: 'fangDecisionCenter',
+    sessionCatalog: 'fangSessionCatalog',
+    sessionBridge: 'fangSessionBridge',
+});
+export const ROW = Object.freeze({
+    core: 'master-core',
+    superagentRouter: 'master-superagent-router',
+    superagentWorker: 'master-superagent-worker',
+    superagentLoop: 'master-superagent-loop',
+    cost: 'master-cost-optimizer',
+    dual: 'master-dual-manager',
+});
+export const ROLE = Object.freeze({ mother: 'mother', essence: 'essence', fork: 'fork' });
+/**
+ * 角色矩阵（v3.2.3）：
+ *   * Router 常驻原身（essence）：只评估/建票/派发，不执行代码；母体不接纳。
+ *   * Worker 是研究原型，只在 fork：编译后的 Worker preset 行 master-superagent-loop 也只 fork。
+ *   * 成本优化 fork；双主管 mother/essence。
+ */
+export const ROLE_MATRIX = Object.freeze({
+    'master-core': Object.freeze(Object.values(ROLE)),
+    'master-superagent-router': Object.freeze([ROLE.essence]),
+    'master-superagent-worker': Object.freeze([ROLE.fork]),
+    'master-superagent-loop': Object.freeze([ROLE.fork]),
+    'master-cost-optimizer': Object.freeze([ROLE.fork]),
+    'master-dual-manager': Object.freeze([ROLE.mother, ROLE.essence]),
+});
+export const SUBPLUGIN_CATALOG = Object.freeze([
+    Object.freeze({
+        id: 'superagent-router', row: ROW.superagentRouter, name: '超级智能体 Router', nameEn: 'SuperAgent Router',
+        roles: ROLE_MATRIX[ROW.superagentRouter], roadmap: '3.2.1',
+        description: '常驻原身：Webhook → 评估 → Ticket/Mandate → 派发；不执行代码改动。',
+    }),
+    Object.freeze({
+        id: 'superagent-worker', row: ROW.superagentWorker, name: '超级智能体 Worker', nameEn: 'SuperAgent Worker',
+        roles: ROLE_MATRIX[ROW.superagentWorker], roadmap: '3.2.1',
+        description: '每个工单一个隔离分身：在 Mandate 作用域内执行；研究原型，仅 fork。',
+    }),
+    Object.freeze({
+        id: 'superagent-loop', row: ROW.superagentLoop, name: 'Worker Agent Loop', nameEn: 'SuperAgent Worker Loop',
+        roles: ROLE_MATRIX[ROW.superagentLoop], roadmap: '3.2.3',
+        description: '编译后的 Worker preset：有 Ticket 的 fork 自动跑多轮工具循环并流式回传。',
+    }),
+    Object.freeze({
+        id: 'cost-optimizer', row: ROW.cost, name: '成本优化', nameEn: 'HarnessMM',
+        roles: ROLE_MATRIX[ROW.cost], roadmap: '3.3.0',
+        description: 'HarnessMM observe 层；仅 fork，默认 observe。',
+    }),
+    Object.freeze({
+        id: 'dual-manager', row: ROW.dual, name: '双主管', nameEn: 'PM + PJM',
+        roles: ROLE_MATRIX[ROW.dual], roadmap: '3.4.0',
+        description: 'PM 产 PRD、PJM 调度分身；只允许 mother / essence。',
+    }),
+]);
+/**
+ * 从环境变量探测当前角色。
+ * 瓮城注入：母体 DSH_FANG_ROLE=mother；元宝运行态 fork+DSH_FANG_ESSENCE=1；
+ * 普通分身 DSH_FANG_ROLE=fork + DSH_FANG_TASK_ID=task_/rt-。
+ */
+export function detectRole(env = process.env) {
+    const raw = String(env?.DSH_FANG_ROLE ?? '').trim().toLowerCase();
+    const taskId = String(env?.DSH_FANG_TASK_ID ?? '');
+    const essence = String(env?.DSH_FANG_ESSENCE ?? '') === '1' || taskId.startsWith('rt-');
+    if (raw === 'mother')
+        return ROLE.mother;
+    if (raw === 'fork')
+        return essence ? ROLE.essence : ROLE.fork;
+    return essence ? ROLE.essence : ROLE.mother;
+}
+export function roleAllowed(rowId, role) {
+    const allowed = ROLE_MATRIX[rowId];
+    return Array.isArray(allowed) ? allowed.includes(role) : true;
+}
+export function enabledOf(config) {
+    return !(config && typeof config === 'object' && config.enabled === false);
+}
+export function safeGet(ctx, name) {
+    try {
+        if (!ctx || typeof ctx !== 'object')
+            return null;
+        if (typeof ctx.get === 'function')
+            return ctx.get(name) ?? null;
+        return ctx[name] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+export function jsonResponse(res, status, body) {
+    try {
+        if (res && typeof res.statusCode === 'number')
+            res.statusCode = status;
+        res?.setHeader?.('content-type', 'application/json; charset=utf-8');
+        res?.setHeader?.('cache-control', 'no-store');
+        res?.end?.(JSON.stringify(body));
+    }
+    catch {
+        /* ignore */
+    }
+}
+/** 读取请求 JSON body（大小上限；非法/超限返回 {ok:false,code}）。 */
+export async function readJsonBody(req, limit = 512 * 1024) {
+    try {
+        const chunks = [];
+        let total = 0;
+        if (req && typeof req[Symbol.asyncIterator] === 'function') {
+            for await (const chunk of req) {
+                const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+                total += buffer.length;
+                if (total > limit)
+                    return { ok: false, code: 'body-too-large' };
+                chunks.push(buffer);
+            }
+        }
+        else if (req && typeof req.on === 'function') {
+            await new Promise((resolve, reject) => {
+                req.on('data', (chunk) => {
+                    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(String(chunk));
+                    total += buffer.length;
+                    if (total > limit)
+                        reject(new Error('body-too-large'));
+                    else
+                        chunks.push(buffer);
+                });
+                req.on('end', resolve);
+                req.on('error', reject);
+            });
+        }
+        const raw = Buffer.concat(chunks).toString('utf8');
+        if (!raw)
+            return { ok: true, body: {} };
+        return { ok: true, body: JSON.parse(raw) };
+    }
+    catch (error) {
+        return { ok: false, code: String(error?.message ?? error) === 'body-too-large' ? 'body-too-large' : 'invalid-json' };
+    }
+}
+/** 常量时间比较两个 token（长度不同直接 false）。 */
+export function tokenEquals(received, expected) {
+    const a = Buffer.from(String(received ?? ''), 'utf8');
+    const b = Buffer.from(String(expected ?? ''), 'utf8');
+    if (a.length === 0 || a.length !== b.length)
+        return false;
+    return crypto.timingSafeEqual(a, b);
+}
+export function bearerOf(headers) {
+    const raw = headers && typeof headers === 'object'
+        ? (headers.authorization ?? headers.Authorization ?? '')
+        : '';
+    const match = /^Bearer\s+(\S+)$/i.exec(String(raw ?? '').trim());
+    return match ? match[1] : '';
+}
+export function masterError(code, message, detail) {
+    const out = { ok: false, code: String(code), error: String(message ?? code) };
+    if (detail !== undefined)
+        out.detail = detail;
+    return out;
+}
+export function createIdFactory(prefix) {
+    let seq = 0;
+    return () => {
+        seq += 1;
+        return `${prefix}_${Date.now().toString(36)}_${seq.toString(36)}`;
+    };
+}

package/dist-host/plugins/cost-optimizer.js

@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: AGPL-3.0-or-later
+// Copyright (c) 2026 dsh-Master contributors — see LICENSE-CORE.
+// @ts-nocheck — host JS→TS 迁移阶段：运行时行为优先，类型注解逐步补齐（worker/ 仍严格检查）。
+/**
+ * 子插件 2：成本优化（HarnessMM 观察层）—— 为分身装“燃油表”。
+ *
+ * 3.2.0 先交付可观测/可估算的骨架，不做推理拦截：
+ *   * `observe` 模式只统计/估算，不改写任何模型调用；
+ *   * HarnessMM 的 EGD/GDR/CCS 真实接入在 3.3.0 里程碑（见 docs/ROADMAP.md）；
+ *   * 角色：只允许 fork（分身生产盘），母体/元主不加载。
+ */
+import { ROW, ROLE, SERVICE, detectRole, enabledOf, masterError, roleAllowed, safeGet, } from "../kernel.js";
+export const name = 'dsh-master-cost-optimizer';
+export const inject = ['dshMaster'];
+export const ROW_ID = ROW.cost;
+/** HarnessMM 官方基准（3.2.0 文档引用；3.3.0 接入后应被实测值覆盖）。 */
+export const HARNESSMM_BENCHMARK = Object.freeze({
+    baselineTokens: 96280,
+    optimizedTokens: 11620,
+    savingsRatio: 0.8793,
+    successRate: { baseline: 0.7143, optimized: 0.8571 },
+});
+function finiteNonNegative(value) {
+    const n = Number(value);
+    return Number.isFinite(n) && n >= 0 ? n : null;
+}
+/**
+ * @param {object} ctx
+ * @param {{enabled?:boolean, mode?:string, targetSavingsRatio?:number}} [config]
+ */
+export function apply(ctx, config = {}) {
+    if (!enabledOf(config))
+        return { skipped: true, reason: 'disabled-by-config' };
+    const role = detectRole();
+    if (!roleAllowed(ROW_ID, role)) {
+        try {
+            ctx?.logger?.info?.(`[dsh-master] cost-optimizer skipped: role=${role} not in ${ROLE.fork}`);
+        }
+        catch { /* ignore */ }
+        return { skipped: true, reason: `role-not-allowed:${role}` };
+    }
+    const master = safeGet(ctx, SERVICE.master);
+    if (!master || typeof master.registerSubplugin !== 'function') {
+        return { skipped: true, reason: 'master-core-unavailable' };
+    }
+    const targetSavingsRatio = finiteNonNegative(config.targetSavingsRatio);
+    const policy = Object.freeze({
+        mode: 'observe', // 3.2.0 只允许 observe；replay 在 3.3.0 打开
+        requestedMode: String(config.mode ?? 'observe'),
+        targetSavingsRatio: targetSavingsRatio !== null && targetSavingsRatio <= 1 ? targetSavingsRatio : 0.8,
+    });
+    const metrics = {
+        tasks: 0,
+        baselineTokens: 0,
+        optimizedTokens: 0,
+        savedTokens: 0,
+        observedSuccess: 0,
+        observedTotal: 0,
+    };
+    const service = {
+        id: SERVICE.cost,
+        version: '3.2.5',
+        role,
+        mode: policy.mode,
+        /** 基于 HarnessMM 基准 + 目标比例做派生前预估。 */
+        estimate({ baselineTokens } = {}) {
+            const baseline = finiteNonNegative(baselineTokens);
+            if (baseline === null)
+                return masterError('baseline-tokens-invalid', 'baselineTokens must be a non-negative number');
+            const projectedOptimized = Math.round(baseline * (1 - policy.targetSavingsRatio));
+            return {
+                ok: true,
+                mode: policy.mode,
+                baselineTokens: baseline,
+                targetSavingsRatio: policy.targetSavingsRatio,
+                projectedOptimizedTokens: projectedOptimized,
+                projectedSavingsTokens: baseline - projectedOptimized,
+                basis: {
+                    source: 'HarnessMM benchmark',
+                    baselineTokens: HARNESSMM_BENCHMARK.baselineTokens,
+                    optimizedTokens: HARNESSMM_BENCHMARK.optimizedTokens,
+                    savingsRatio: HARNESSMM_BENCHMARK.savingsRatio,
+                },
+            };
+        },
+        /** 归档后记录实测；3.3.0 起由 HarnessMM 的 EGD/GDR/CCS 自动上报。 */
+        record({ taskId, baselineTokens, optimizedTokens, success } = {}) {
+            const baseline = finiteNonNegative(baselineTokens);
+            const optimized = finiteNonNegative(optimizedTokens);
+            if (baseline === null)
+                return masterError('baseline-tokens-invalid', 'baselineTokens must be a non-negative number');
+            if (optimized === null)
+                return masterError('optimized-tokens-invalid', 'optimizedTokens must be a non-negative number');
+            if (optimized > baseline)
+                return masterError('optimized-exceeds-baseline', 'optimizedTokens must not exceed baselineTokens');
+            metrics.tasks += 1;
+            metrics.baselineTokens += baseline;
+            metrics.optimizedTokens += optimized;
+            metrics.savedTokens += baseline - optimized;
+            if (typeof success === 'boolean') {
+                metrics.observedTotal += 1;
+                if (success)
+                    metrics.observedSuccess += 1;
+            }
+            return {
+                ok: true,
+                taskId: taskId === undefined ? null : String(taskId),
+                savedTokens: baseline - optimized,
+                summary: service.summary(),
+            };
+        },
+        summary() {
+            const ratio = metrics.baselineTokens > 0 ? metrics.savedTokens / metrics.baselineTokens : 0;
+            const successRate = metrics.observedTotal > 0 ? metrics.observedSuccess / metrics.observedTotal : null;
+            return { ...metrics, savingsRatio: ratio, successRate };
+        },
+        reset() {
+            Object.assign(metrics, { tasks: 0, baselineTokens: 0, optimizedTokens: 0, savedTokens: 0, observedSuccess: 0, observedTotal: 0 });
+            return { ok: true };
+        },
+        status() {
+            return {
+                ok: true,
+                id: 'cost-optimizer',
+                version: '3.2.5',
+                role,
+                mode: policy.mode,
+                requestedMode: policy.requestedMode,
+                targetSavingsRatio: policy.targetSavingsRatio,
+                benchmark: HARNESSMM_BENCHMARK,
+                summary: service.summary(),
+                note: '3.2.0 observe-only：不拦截/不改写模型调用；EGD/GDR/CCS 在 3.3.0 接入。',
+            };
+        },
+    };
+    try {
+        ctx.effect(() => ctx.provide(SERVICE.cost, service));
+    }
+    catch { /* fake ctx */ }
+    master.registerSubplugin({
+        id: 'cost-optimizer',
+        name: 'dsh-master-cost-optimizer',
+        capabilities: ['token-estimate', 'savings-record', 'cost-status'],
+        description: 'HarnessMM observe 层（仅 fork）',
+    });
+    return service;
+}