dsh-yolo-mode 0.4.0

package/lib/remote.js

@@ -0,0 +1,489 @@
+/**
+ * dsh-yolo-mode —— 自发布设置桥（lib/remote.js）
+ *
+ * 镜像参考项目 dsh-subagents-options/src/envelope.ts + src/remote.ts：
+ * 宿主在 webServer 上注册 `/yolo-mode` 前缀路由（kind:'prefix', path），绕过
+ * apiproxy 的 exposedNamespaces() 白名单（树外插件无法往该名单加命名空间），
+ * 直接用 cordis `inject` 拿到的 `settings` 读写自身 `yolo-mode` 命名空间。
+ *
+ * 线协议镜像 Connection RPC 通道（dsh-client-connection lib/index.js 275-328）：
+ *   - 非 POST            → 404
+ *   - content-type 非 json → 415
+ *   - Host 非 loopback    → 403（轻量信任围栏）
+ *   - body 非法 JSON      → 400
+ *   - 信封非法            → 200 bad-request（固定 rpcId 'invalid-request'）
+ *   - method 与端点不符   → 200 bad-request
+ *   - dispatch 抛错       → 500（headersSent 则 destroy）
+ * 响应一律 `RpcResult` 信封（{ rpcId, result: { ok, value|error } }）。
+ *
+ * 三个端点：
+ *   settingsView   → { writable, view }
+ *   settingsMutate → 应用带 expectedRevision 乐观锁的路径 op，返回新 redacted view；
+ *                    冲突 → settings-conflict（含 expected/actual），其余拒绝 → settings-rejected。
+ *   statusView     → getStatusPayload()（本插件扩展；不触碰 settings）。
+ *
+ * 纯映射 / 线信封辅助在顶部（无 cordis），可在普通 node 环境单测。
+ *
+ * @module lib/remote.js
+ */
+import {
+  SettingsConflictError,
+  settingsNamespace,
+} from '@deepseek-ai/dsh-settings';
+import { YOLO_SETTINGS_NAMESPACE } from './settings.js';
+
+/** 桥接通道绝对前缀路由（design.md §12.4）。 */
+export const YOLO_RPC_CHANNEL = '/yolo-mode';
+/** settingsView 端点。 */
+export const YOLO_RPC_VIEW = 'settingsView';
+/** settingsMutate 端点。 */
+export const YOLO_RPC_MUTATE = 'settingsMutate';
+/** statusView 端点（本插件扩展）。 */
+export const YOLO_RPC_STATUS = 'statusView';
+
+/** 顶层校验失败时宿主用的固定 rpcId（镜像 invalidEnvelopeResponse）。 */
+export const INVALID_REQUEST_RPC_ID = 'invalid-request';
+
+/* ------------------------------------------------------------------ *
+ * 线信封辅助（纯函数，无 cordis；镜像 src/envelope.ts）
+ * ------------------------------------------------------------------ */
+
+/**
+ * 解析并校验一个解码后的 JSON body 是否为 "client-request" 信封。
+ * 仅接受 type 恰为 "client-request"、rpcId/method 为字符串的对象。
+ * @param {unknown} body
+ * @returns {{ok:true, envelope:{type:'client-request',rpcId:string,method:string,payload:unknown}}
+ *          |{ok:false, issues:string[]}}
+ */
+export function parseClientRequestEnvelope(body) {
+  if (body === null || typeof body !== 'object' || Array.isArray(body)) {
+    return { ok: false, issues: ['body must be a JSON object'] };
+  }
+  const record = body;
+  const issues = [];
+  if (record.type !== 'client-request') issues.push('type must equal "client-request"');
+  if (typeof record.rpcId !== 'string') issues.push('rpcId must be a string');
+  if (typeof record.method !== 'string') issues.push('method must be a string');
+  if (issues.length > 0) return { ok: false, issues };
+  return {
+    ok: true,
+    envelope: {
+      type: 'client-request',
+      rpcId: record.rpcId,
+      method: record.method,
+      payload: record.payload,
+    },
+  };
+}
+
+/**
+ * 构造请求 rpcId 的 "server-response" 信封，携带一个 RpcResult。
+ * @template T
+ * @param {string} rpcId
+ * @param {{ok:boolean, value?:T, error?:object}} result
+ * @returns {{type:'server-response', rpcId:string, result:object}}
+ */
+export function buildServerResponse(rpcId, result) {
+  return { type: 'server-response', rpcId, result };
+}
+
+/**
+ * 构造坏请求 "server-response"：对非法 client-request 信封，宿主无法信任调用方
+ * rpcId，故用固定 INVALID_REQUEST_RPC_ID（镜像 invalidEnvelopeResponse）。
+ * @param {readonly string[]} issues
+ * @returns {{type:'server-response', rpcId:string, result:object}}
+ */
+export function buildBadRequestResponse(issues) {
+  const error = {
+    code: 'bad-request',
+    message: 'invalid client-request message',
+    details: { issues: [] },
+  };
+  return buildServerResponse(INVALID_REQUEST_RPC_ID, { ok: false, error });
+}
+
+/**
+ * 构造 method 与端点不符的 "server-response"（镜像 289-293）。
+ * @param {string} rpcId
+ * @param {unknown} method
+ * @param {string} endpoint
+ * @returns {{type:'server-response', rpcId:string, result:object}}
+ */
+export function buildMethodMismatchResponse(rpcId, method, endpoint) {
+  const error = {
+    code: 'bad-request',
+    message: 'method ' + JSON.stringify(method) + ' does not match endpoint ' + JSON.stringify(endpoint),
+    details: { issues: [] },
+  };
+  return buildServerResponse(rpcId, { ok: false, error });
+}
+
+const IPV4_OCTET = /^\d{1,3}$/;
+
+/** 最小 127/8 IPv4 段常量。 */
+const IPV4_LOOPBACK = '127';
+
+/**
+ * WHATWG URL hostname 是否命名本机回环权威。
+ * 接受 "localhost"、"[::1]"（保留括号）或 127/8 任意 IPv4。
+ * @param {string} hostname
+ * @returns {boolean}
+ */
+export function isLoopbackHostname(hostname) {
+  if (hostname === 'localhost' || hostname === '[::1]') return true;
+  const parts = hostname.split('.');
+  return (
+    parts.length === 4 &&
+    parts[0] === IPV4_LOOPBACK &&
+    parts.every((part) => IPV4_OCTET.test(part) && Number(part) <= 255)
+  );
+}
+
+/**
+ * 将原始 Host 头分类为 loopback。剥离端口后缀并括号归一化权威后再判定。
+ * 无端口时视为裸主机名。
+ * @param {string} rawHost
+ * @returns {boolean}
+ */
+export function isLoopbackHost(rawHost) {
+  let host = typeof rawHost === 'string' ? rawHost.trim() : '';
+  if (host.length === 0) return false;
+  if (host.startsWith('[')) {
+    const close = host.indexOf(']');
+    if (close === -1) return false;
+    host = host.slice(0, close + 1);
+  } else {
+    const colon = host.indexOf(':');
+    if (colon !== -1) host = host.slice(0, colon);
+  }
+  return isLoopbackHostname(host);
+}
+
+/**
+ * 从通道前缀下派生端点段。路径必须为 "<channel>/<单一合法段>"。
+ * 合法端点=非空、不含 "/"、"."、".." 遍历段。
+ * @param {string} channel 如 '/yolo-mode'
+ * @param {string} pathname 如 '/yolo-mode/settingsView'
+ * @returns {string|undefined}
+ */
+export function endpointFromPath(channel, pathname) {
+  if (!pathname.startsWith(channel + '/')) return undefined;
+  const endpoint = pathname.slice(channel.length + 1);
+  if (endpoint.length === 0) return undefined;
+  if (endpoint.split('/').some((segment) => segment.length === 0 || segment === '.' || segment === '..')) {
+    return undefined;
+  }
+  return endpoint;
+}
+
+/* ------------------------------------------------------------------ *
+ * 命名空间视图映射（镜像 src/remote.ts toDirectorNamespaceView / pick）
+ * ------------------------------------------------------------------ */
+
+/** 把 describe 的一个设置描述符映射为线视图。 */
+function toNamespaceView(descriptor) {
+  return {
+    ns: String(descriptor.ns),
+    schema: descriptor.schema,
+    value: descriptor.value,
+    ...(descriptor.base === undefined ? {} : { base: descriptor.base }),
+    ...(descriptor.user === undefined ? {} : { user: descriptor.user }),
+    applies: descriptor.applies,
+    secrets: (descriptor.secrets ?? []).map((secret) => ({
+      path: [...secret.path],
+      set: secret.set,
+    })),
+    revision: descriptor.revision,
+  };
+}
+
+/** 在 redacted describe 结果中挑出 yolo-mode 命名空间视图；未注册则 undefined。 */
+export function pickYoloNamespaceView(descriptors) {
+  for (const descriptor of descriptors) {
+    if (descriptor.ns === YOLO_SETTINGS_NAMESPACE) {
+      return toNamespaceView(descriptor);
+    }
+  }
+  return undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * settings 维度映射（镜像 src/remote.ts directorRejected / directorConflict / directorMutate）
+ * ------------------------------------------------------------------ */
+
+/** 构造 settings-rejected RPC 错误。 */
+function yoloRejected(ns, error) {
+  return {
+    code: 'settings-rejected',
+    message: error instanceof Error ? error.message : String(error),
+    details: { ns },
+  };
+}
+
+/** 构造 settings-conflict RPC 错误（镜像 apiproxy 映射）。 */
+function yoloConflict(conflict) {
+  const structural = conflict;
+  const ns = structural.ns;
+  return {
+    code: 'settings-conflict',
+    message: conflict.message,
+    details: {
+      ns: ns === undefined ? 'yolo-mode' : String(ns),
+      expected: conflict.expected,
+      actual: conflict.actual,
+    },
+  };
+}
+
+/**
+ * 对 settings seam 执行一次路径 op 变更并映射为 RpcResult（携带新 redacted view，
+ * 或 settings-conflict / settings-rejected 错误）。纯函数可注入 mutate/describe 测试。
+ * @param {Function} mutate settings.mutate 绑定
+ * @param {Function} describe settings.describe 绑定
+ * @param {string} ns 命名空间字符串
+ * @param {Array<{op:'set'|'unset', path:string[], value?:unknown}>} ops
+ * @param {number|undefined} expectedRevision
+ * @returns {Promise<{ok:boolean, value?:object, error?:object}>}
+ */
+export async function yoloMutate(mutate, describe, ns, ops, expectedRevision) {
+  const branded = settingsNamespace(ns);
+  try {
+    await mutate(branded, ops, expectedRevision);
+  } catch (error) {
+    if (error instanceof SettingsConflictError) {
+      return { ok: false, error: yoloConflict(error) };
+    }
+    return { ok: false, error: yoloRejected(ns, error) };
+  }
+  const descriptor = describe({ redactSecrets: true }).find(
+    (candidate) => candidate.ns === branded,
+  );
+  if (descriptor === undefined) {
+    return {
+      ok: false,
+      error: {
+        code: 'internal',
+        message: 'settings namespace "' + ns + '" was disposed after the mutate',
+        details: {},
+      },
+    };
+  }
+  return { ok: true, value: toNamespaceView(descriptor) };
+}
+
+/* ------------------------------------------------------------------ *
+ * 请求处理器（镜像 src/remote.ts handleDirectorBridgeRequest + dispatch）
+ * ------------------------------------------------------------------ */
+
+/** HTTP body 读取上限（design.md §11.1，64KB）。 */
+const BODY_LIMIT = 64 * 1024;
+
+/** 读 IncomingMessage body 至多 limit 字节；超出抛 {code:'LIMIT'}。 */
+function readRequestBody(req, limit) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    let size = 0;
+    let done = false;
+    const fail = (err) => {
+      if (done) return;
+      done = true;
+      reject(err);
+    };
+    req.on('data', (chunk) => {
+      if (done) return;
+      const buf = Buffer.isBuffer(chunk)
+        ? chunk
+        : Buffer.from(typeof chunk === 'string' ? chunk : String(chunk), 'utf8');
+      size += buf.length;
+      if (size > limit) {
+        fail(Object.assign(new Error('request body too large'), { code: 'LIMIT' }));
+        return;
+      }
+      chunks.push(buf);
+    });
+    req.on('end', () => {
+      if (done) return;
+      done = true;
+      resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    req.on('error', (err) => fail(err));
+  });
+}
+
+/** pathname 部分（安全传给 endpointFromPath）。 */
+function pathnameOf(rawUrl) {
+  try {
+    return new URL(rawUrl, 'http://dsh.internal').pathname;
+  } catch {
+    return rawUrl;
+  }
+}
+
+/** 纯文本响应。 */
+function sendPlain(res, status, text) {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.end(text);
+}
+
+/** JSON 响应。 */
+function sendJson(res, status, payload) {
+  res.statusCode = status;
+  res.setHeader('Content-Type', 'application/json; charset=utf-8');
+  res.end(JSON.stringify(payload));
+}
+
+/**
+ * 分派一个已校验端点。未知端点抛错（由调用方兜底为 500）。
+ * @param {object} settings settings 服务对象
+ * @param {() => object} getStatusPayload statusView 载荷装配（由桥接条目注入）
+ * @param {string} endpoint
+ * @param {unknown} payload
+ * @returns {Promise<{ok:boolean, value?:unknown, error?:object}>}
+ */
+async function dispatchYoloEndpoint(settings, getStatusPayload, endpoint, payload) {
+  if (endpoint === YOLO_RPC_VIEW) {
+    return {
+      ok: true,
+      value: {
+        writable: settings.writable,
+        view: pickYoloNamespaceView(settings.describe({ redactSecrets: true })),
+      },
+    };
+  }
+  if (endpoint === YOLO_RPC_STATUS) {
+    return { ok: true, value: getStatusPayload() };
+  }
+  if (endpoint === YOLO_RPC_MUTATE) {
+    const request = payload ?? null;
+    if (request === null || typeof request !== 'object' || request.ns !== String(YOLO_SETTINGS_NAMESPACE)) {
+      return {
+        ok: false,
+        error: {
+          code: 'bad-request',
+          message: 'settingsMutate: expected ns "' + String(YOLO_SETTINGS_NAMESPACE) + '"',
+          details: { issues: [] },
+        },
+      };
+    }
+    const ops = Array.isArray(request.ops) ? request.ops : [];
+    return yoloMutate(
+      (n, o, r) => settings.mutate(n, o, r),
+      (opts) => settings.describe(opts),
+      String(YOLO_SETTINGS_NAMESPACE),
+      ops,
+      typeof request.expectedRevision === 'number' ? request.expectedRevision : undefined,
+    );
+  }
+  throw new Error('unknown bridge endpoint ' + JSON.stringify(endpoint));
+}
+
+/**
+ * `/yolo-mode` 前缀路由处理器（node:http 原语）。拥有完整响应生命周期。
+ * @param {object} settings settings 服务对象（注入）
+ * @param {() => object} getStatusPayload statusView 载荷装配（由桥接条目注入）
+ * @param {import('node:http').IncomingMessage} req
+ * @param {import('node:http').ServerResponse} res
+ * @returns {Promise<void>}
+ */
+export async function handleYoloBridgeRequest(settings, getStatusPayload, req, res) {
+  const rawUrl = typeof req.url === 'string' ? req.url : '/';
+  const hostHeader = req.headers.host;
+
+  if (typeof req.method !== 'string') {
+    sendPlain(res, 404, 'not found');
+    return;
+  }
+  // 非 POST → 404。
+  if (req.method !== 'POST') {
+    sendPlain(res, 404, 'not found');
+    return;
+  }
+  // content-type 必须 application/json → 415。
+  const contentType = (req.headers['content-type'] ?? '').split(';', 1)[0].trim().toLowerCase();
+  if (contentType !== 'application/json') {
+    sendPlain(res, 415, 'content type must be application/json');
+    return;
+  }
+  // Host 非 loopback → 403（轻量信任围栏）。
+  if (hostHeader === undefined || !isLoopbackHost(hostHeader)) {
+    sendPlain(res, 403, 'forbidden');
+    return;
+  }
+  // 读 body → 400 非法 JSON / 413 超长。
+  let raw;
+  try {
+    raw = await readRequestBody(req, BODY_LIMIT);
+  } catch (err) {
+    if (err && err.code === 'LIMIT') {
+      sendPlain(res, 413, 'request body too large');
+    } else {
+      // body 读取错误 → 400。
+      sendPlain(res, 400, 'body is not JSON');
+    }
+    return;
+  }
+  let body;
+  try {
+    body = raw.length === 0 ? {} : JSON.parse(raw);
+  } catch {
+    sendPlain(res, 400, 'body is not JSON');
+    return;
+  }
+  // 信封校验 → 200 bad-request。
+  const parsed = parseClientRequestEnvelope(body);
+  if (!parsed.ok) {
+    sendJson(res, 200, buildBadRequestResponse(parsed.issues));
+    return;
+  }
+  const envelope = parsed.envelope;
+  // method 必须匹配路径派生端点。
+  const endpoint = endpointFromPath(YOLO_RPC_CHANNEL, pathnameOf(rawUrl));
+  if (endpoint === undefined || envelope.method !== endpoint) {
+    sendJson(
+      res,
+      200,
+      buildMethodMismatchResponse(envelope.rpcId, envelope.method, endpoint ?? '(invalid path)'),
+    );
+    return;
+  }
+  // 分派。
+  const result = await dispatchYoloEndpoint(settings, getStatusPayload, endpoint, envelope.payload);
+  sendJson(res, 200, buildServerResponse(envelope.rpcId, result));
+}
+
+/**
+ * 在宿主 webServer 上安装 `/yolo-mode` 前缀路由。惰性读取 webServer/settings；
+ * 服务缺失时打 debug 日志并安装空操作（不抛错）。返回 disposer。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object} settings settings 服务对象（注入）
+ * @param {() => object} getStatusPayload statusView 载荷装配（注入）
+ * @returns {() => void} 卸载时反注册路由
+ */
+export function installYoloRemoteBridge(ctx, settings, getStatusPayload) {
+  const webServer = ctx.get('webServer');
+  if (settings === undefined || webServer === undefined) {
+    ctx.logger.debug(
+      '[yolo-mode] settings bridge not installed ' +
+        '(settings:' + String(settings !== undefined) +
+        ', webServer:' + String(webServer !== undefined) + ')',
+    );
+    return () => {};
+  }
+
+  const handler = (req, res) => {
+    handleYoloBridgeRequest(settings, getStatusPayload, req, res).catch((error) => {
+      // 分派抛错（未知端点或 settings seam 爆掉）→ 500；headersSent 则 destroy。
+      if (res.headersSent) {
+        res.destroy();
+        return;
+      }
+      sendPlain(res, 500, 'handler failure: ' + String(error));
+    });
+  };
+
+  return ctx.effect(
+    () => webServer.register({ kind: 'prefix', path: YOLO_RPC_CHANNEL, handler }),
+    'yolo-mode: settings bridge route',
+  );
+}

package/lib/settings.js

@@ -0,0 +1,102 @@
+/**
+ * dsh-yolo-mode —— 宿主设置分区（lib/settings.js）
+ *
+ * 镜像参考项目 dsh-subagents-options/src/settings.ts：注册 settings 命名空间
+ * `yolo-mode`，用 schemastery 宽松 schema 解析分区值，写时校验委托
+ * ./policy.js 的 `normalizeConfig`（fail-loud 抛错即拒绝写入）。
+ *
+ * 分层层（design.md §12.3）：插件行 config 作为 settings 的 `base` 层，
+ * 用户文档写在上层；`installYoloSettings` 走 `installSettingsSection` 的
+ * 可选-settings 消费者接线，部署无 settings 服务时打 debug 日志跳过（零侵入）。
+ *
+ * 纯 JavaScript（ESM），宿主代码仅 import node: 内置与同包 peer
+ * （@deepseek-ai/dsh-settings、@deepseek-ai/schemastery）。
+ *
+ * @module lib/settings.js
+ */
+import { installSettingsSection, settingsNamespace } from '@deepseek-ai/dsh-settings';
+import z from '@deepseek-ai/schemastery';
+import { normalizeConfig } from './policy.js';
+
+/** settings 命名空间：`yolo-mode`（与插件行 id 一致，纯小写 kebab-case）。 */
+export const YOLO_SETTINGS_NAMESPACE = settingsNamespace('yolo-mode');
+
+/** 预设枚举（与 ./policy.js PRSESTS 保持一致，供 union schema 使用）。 */
+const PRESETS = ['off', 'strict', 'balanced', 'permissive', 'yolo', 'custom'];
+
+/**
+ * schemastery 宽松 schema：全字段可选（object 字段默认可选），
+ * 使未写入的空白分区解析为空对象，绝不泄漏默认值覆盖插件行 config。
+ * 真正的形状/语义校验由写时 `validateYoloSettings = normalizeConfig` 完成（fail-loud）。
+ */
+export const YoloSettingsSchema = z.object({
+  preset: z.union([...PRESETS]).default('balanced'),
+  modes: z.array(z.string()),
+  levels: z.dict(z.any()),
+  judge: z.object({
+    provider: z.string(),
+    model: z.string(),
+    systemPrompt: z.string(),
+    timeoutMs: z.natural(),
+    maxTokens: z.natural(),
+    concurrency: z.natural(),
+  }),
+  includeSubagents: z.boolean(),
+  auditFile: z.string(),
+});
+
+/**
+ * 剔除 schema 解析出的"空集合默认值"（schemastery 对 array/dict 缺省解析为
+ * []/{}，标量缺省为 absent），避免把这些默认空值当成用户配置喂给
+ * normalizeConfig（其会 fail-loud 拒绝空 modes 数组）。供 validate 钩子与
+ * 主条目 effectiveConfig 复用。
+ * @param {object} value 解析值
+ * @returns {object} 仅含非空字段的浅拷贝
+ */
+export function pruneEmpty(value) {
+  const out = {};
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return out;
+  for (const key of Object.keys(value)) {
+    const v = value[key];
+    if (v === undefined || v === null) continue;
+    if (Array.isArray(v)) {
+      if (v.length > 0) out[key] = v;
+      continue;
+    }
+    if (typeof v === 'object') {
+      if (Object.keys(v).length > 0) out[key] = v;
+      continue;
+    }
+    out[key] = v;
+  }
+  return out;
+}
+
+/**
+ * 分区写时/注册时校验：剔除空默认值后 = `normalizeConfig`（design.md §12.2）。
+ * 任何非法值抛错 → 拒绝写入/注册；空 modes/levels 等 schema 默认回落为
+ * normalizeConfig 的默认值（空 modes 即"未设"，回落 ['workspace-write']）。
+ * @param {object} value 当前解析出的分区值（schema 合法）
+ * @returns {Readonly<Config>} 规范化后的冻结配置
+ */
+export function validateYoloSettings(value) {
+  return normalizeConfig(pruneEmpty(value));
+}
+
+/**
+ * 安装 yolo-mode settings 分区（可选-settings 消费者接线）。
+ * settings 服务缺失时打 debug 日志并跳过（插件继续按插件行 config 运行）。
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {object} entry 插件行 config（成为 settings `base` 层）
+ * @param {import('@deepseek-ai/dsh-settings').SettingsSectionHooks<object>} hooks
+ *   { setSource, onChange, validate? }
+ */
+export function installYoloSettings(ctx, entry, hooks) {
+  if (ctx.get('settings') === undefined) {
+    ctx.logger.debug(
+      '[yolo-mode] no settings service mounted; using composition config and skipping settings section registration',
+    );
+    return;
+  }
+  installSettingsSection(ctx, YOLO_SETTINGS_NAMESPACE, YoloSettingsSchema, entry, hooks);
+}

package/lib/state.js

@@ -0,0 +1,92 @@
+/**
+ * dsh-yolo-mode —— 模块级共享状态（lib/state.js）
+ *
+ * 主插件条目（lib/index.js）在裁决时调用 `recordDecision(entry)` 写入审计统计
+ * 与最近决策环形缓冲；桥接条目（lib/bridge-entry.js）经 `getStatusPayload(cfg)`
+ * 读取。二者为同一包内的模块单例，天然共享（design.md §12.3「stats/recent 写入
+ * lib/state.js 模块级单例」）。
+ *
+ * 本模块不触碰 settings / webServer；只含纯数据与纯装配（design.md §12.4 statusView）。
+ * statusView 附带 presetDefaults：六预设 id → { systemPrompt, levels }，供设置页
+ * 选中预设时预填充（systemPrompt 来自 lib/judge.js 的 defaultJudgePromptFor，
+ * levels 来自 lib/policy.js 的 defaultLevelsFor；二者均为无副作用纯函数）。
+ *
+ * @module lib/state.js
+ */
+import { PRESETS, defaultLevelsFor } from './policy.js'
+import { defaultJudgePromptFor } from './judge.js'
+
+/** recent 环形缓冲上限（design.md §11.1/12.4，≤20）。 */
+export const RECENT_CAP = 20;
+
+/** 模块级统计计数（设计 §3.8/12.3；主条目内存写，桥接条目只读）。 */
+export const stats = { total: 0, allowed: 0, rejected: 0, delegated: 0 };
+
+/** recent 环形缓冲：新条目 unshift 到头部，超过上限截断尾部（倒序，≤RECENT_CAP）。 */
+const recent = [];
+
+/**
+ * 六预设的默认 { systemPrompt, levels } 映射（design.md §2/§13.1；statusView 携带，
+ * 设置页选中预设时预填充）。纯函数静态装配一次：值为不可变字符串与冻结对象，只读。
+ */
+const presetDefaults = (() => {
+  const map = {};
+  for (const id of PRESETS) {
+    map[id] = { systemPrompt: defaultJudgePromptFor(id), levels: defaultLevelsFor(id) };
+  }
+  return map;
+})();
+
+/**
+ * 判定某个会话的审计 origin：'subagent' 或 'main'（design.md §3.8）。
+ * 由 session 的 delegation 信息判定，无法判定时回退 'main'。
+ * @param {object|undefined} session 申请方的 agent session
+ * @returns {'subagent'|'main'}
+ */
+export function sessionOrigin(session) {
+  if (!session) return 'main';
+  const header = session.header;
+  if (header && header.origin === 'subagent') return 'subagent';
+  return 'main';
+}
+
+/**
+ * 记录一次裁决到模块级统计与 recent 环（主条目 audit() 调用）。
+ * @param {object} entry 审计条目：
+ *   { time, sessionId, origin, toolName?, callId?, targetMode, currentMode?,
+ *     justification, decision, outcome, reason? }
+ */
+export function recordDecision(entry) {
+  recent.unshift({
+    time: entry.time,
+    toolName: entry.toolName,
+    targetMode: entry.targetMode,
+    decision: entry.decision,
+    outcome: entry.outcome,
+    ...(entry.reason !== undefined ? { reason: entry.reason } : {}),
+  });
+  if (recent.length > RECENT_CAP) recent.length = RECENT_CAP;
+
+  stats.total += 1;
+  if (entry.outcome === 'delegate') stats.delegated += 1;
+  else if (entry.outcome === 'allowed-once') stats.allowed += 1;
+  else if (entry.outcome === 'rejected') stats.rejected += 1;
+}
+
+/**
+ * 以浅拷贝装配 statusView 载荷（design.md §12.4）。
+ * @param {object} cfg 含 { preset, judge?: { provider?, model? } } 的配置字形
+ *   （主条目传 effectiveConfig()；桥接条目传 settings.describe 推导的 view 字形）
+ * @returns {{preset:string, judgeConfigured:boolean, presetDefaults:object, stats:object, recent:Array<object>}}
+ */
+export function getStatusPayload(cfg) {
+  const c = cfg && typeof cfg === 'object' ? cfg : {};
+  const j = c.judge && typeof c.judge === 'object' ? c.judge : {};
+  return {
+    preset: c.preset,
+    judgeConfigured: Boolean(j.provider && j.model),
+    presetDefaults,
+    stats: { ...stats },
+    recent: recent.map((r) => ({ ...r })),
+  };
+}