dsh-decision-layer 0.4.0

package/service/dsh.mjs

@@ -0,0 +1,175 @@
+import { readFile } from 'node:fs/promises';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { resolveConfig, featureEnabled } from './config-store.mjs';
+import { createBackend } from './backend.mjs';
+import { createManagerRoutes } from './manager-api.mjs';
+import { createSessionState } from './session-state.mjs';
+import { createDangerGate, normalizeDangerRules } from './danger-gate.mjs';
+import { createSelfCheck } from './self-check.mjs';
+import { createNarrowing } from './narrowing.mjs';
+import { createLoopGuard } from './loop-guard.mjs';
+import { createLogStore } from './log-store.mjs';
+
+export const name = 'dsh-decision-layer';
+export const inject = ['tools', 'skills'];
+
+// Best-effort extraction of the turn's final assistant text. The self-check
+// treats empty output as "skip", so an unreachable shape degrades safely.
+function lastAssistantText(agent) {
+  try {
+    const messages = agent?.session?.deriveMessages?.();
+    if (!Array.isArray(messages)) return '';
+    for (let i = messages.length - 1; i >= 0; i--) {
+      const message = messages[i];
+      if (message?.role !== 'assistant' || !Array.isArray(message.content)) continue;
+      return message.content.filter(block => block?.type === 'text' && typeof block.text === 'string').map(block => block.text).join('');
+    }
+    return '';
+  } catch { return ''; }
+}
+
+// The task text a narrowing pass judges tools against: the user messages
+// entering this step. An unreachable shape yields '', which skips narrowing.
+function stepTaskText(messages) {
+  try {
+    if (!Array.isArray(messages)) return '';
+    return messages
+      .filter(message => message?.role === 'user' && Array.isArray(message.content))
+      .flatMap(message => message.content.filter(block => block?.type === 'text' && typeof block.text === 'string').map(block => block.text))
+      .join('\n').slice(0, 8 * 1024);
+  } catch { return ''; }
+}
+
+// Enumerate the tool names/descriptions visible to this agent scope, best-effort.
+function agentTools(ctx, agent) {
+  try {
+    const schemas = typeof ctx.tools?.schemas === 'function' ? ctx.tools.schemas(agent) : undefined;
+    if (!Array.isArray(schemas)) return [];
+    return schemas
+      .filter(schema => schema && typeof schema.name === 'string')
+      .map(schema => ({ name: schema.name, description: typeof schema.description === 'string' ? schema.description : '' }));
+  } catch { return []; }
+}
+
+export async function apply(ctx, options = {}) {
+  const path = options.configPath;
+  const backend = createBackend({ config: () => resolveConfig({ path }) });
+  // The research log sink is attached once the web server reveals the instance
+  // port (used in the file name); until then decision logs stay in memory only.
+  let logStore;
+  const sessions = createSessionState({ onLog: entry => logStore?.append(entry) });
+  const gate = createDangerGate({
+    evaluate: (input, request) => backend.evaluate(input, request),
+    sessions,
+    rules: async () => normalizeDangerRules((await resolveConfig({ path })).dangerRules),
+  });
+  const loopGuard = createLoopGuard({ sessions });
+  // Live per-feature enablement; every decision point defaults to enabled.
+  const featureOn = async key => featureEnabled((await resolveConfig({ path })).features, key);
+  if (typeof ctx.on === 'function') {
+    if (typeof ctx.tools.guard === 'function') {
+      // Deterministic loop guard runs with no backend; then the dangerous-gate
+      // monotonic denial. Guards can only deny, never re-allow.
+      ctx.tools.guard(exec => loopGuard.check(exec));
+      ctx.tools.guard(exec => gate.guardReason(exec));
+    }
+    const install = () => {
+      const disposePre = ctx.on('tools/pre-execute', async (exec, next) => {
+        if (!(await featureOn('gate'))) return next();
+        return gate.preExecute(exec, next);
+      });
+      const disposePost = ctx.on('tools/post-execute', async (exec, result, next) => {
+        gate.observeResult(exec, result);
+        return next();
+      });
+      return () => { disposePre?.(); disposePost?.(); };
+    };
+    if (typeof ctx.effect === 'function') ctx.effect(install);
+    else install();
+
+    const selfCheck = createSelfCheck({
+      evaluate: (input, request) => backend.evaluate(input, request),
+      sessions,
+      settings: async () => (await resolveConfig({ path })).checkSettings,
+      steer: (agent, text) => agent.steer(createUserMessage({
+        content: [{ type: 'text', text }],
+        source: { kind: 'user' },
+      })),
+    });
+    const installCheck = () => ctx.on('agent/turn-stopping', async payload => {
+      if (!(await featureOn('check'))) return;
+      return selfCheck.review({
+        agent: payload.agent, turn: payload.turn, signal: payload.signal,
+        output: lastAssistantText(payload.agent),
+      });
+    });
+    if (typeof ctx.effect === 'function') ctx.effect(installCheck);
+    else installCheck();
+
+    const narrowing = createNarrowing({
+      evaluate: (input, request) => backend.evaluate(input, request),
+      sessions,
+      settings: async () => (await resolveConfig({ path })).narrowSettings,
+    });
+    // Narrow once per turn, on its first step, and only enforce a restriction in
+    // enforce mode. The restriction is agent-scoped and lifted before the next
+    // turn's pass so a later turn is judged against the full host-allowed set.
+    const narrowedTurns = new Map();
+    const installNarrowingHook = () => ctx.on('agent/pre-step', async (payload, next) => {
+      const agent = payload?.agent;
+      const id = agent?.session?.id;
+      const turn = payload?.turn;
+      if (typeof id === 'string' && Number.isInteger(turn) && await featureOn('narrow')) {
+        const state = narrowedTurns.get(id);
+        if (!state || state.turn !== turn) {
+          state?.dispose?.();
+          const entry = { turn, dispose: undefined };
+          narrowedTurns.set(id, entry);
+          if (narrowedTurns.size > 1024) { const oldest = narrowedTurns.keys().next().value; if (oldest !== id) { narrowedTurns.get(oldest)?.dispose?.(); narrowedTurns.delete(oldest); } }
+          try {
+            const result = await narrowing.review({
+              agent, turn, signal: payload.signal,
+              state: stepTaskText(payload.messages), tools: agentTools(ctx, agent),
+            });
+            if (result.mode === 'enforce' && result.applied && typeof agent?.ctx?.tools?.restrict === 'function') {
+              entry.dispose = agent.ctx.tools.restrict({ allow: result.keep });
+            }
+          } catch { /* narrowing is best effort; never block the step */ }
+        }
+      }
+      return next();
+    });
+    if (typeof ctx.effect === 'function') ctx.effect(installNarrowingHook);
+    else installNarrowingHook();
+  }
+  const rawSkill = await readFile(new URL('../skills/decision-layer/SKILL.md', import.meta.url), 'utf8');
+  const content = rawSkill.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/, '').trim();
+  ctx.skills.register({ name: 'decision-layer', description: '显式发起结构化裁决，辅助明确边界的选择与评分。', content, source: 'bundled' });
+
+  const output = { schema: { type: 'object', additionalProperties: true }, render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }] };
+  ctx.tools.register({
+    name: 'decision_evaluate', description: '对 state 和 questions 执行一次显式结构化裁决，不修改 agent 行为。',
+    parameters: { type: 'object', required: ['state', 'questions'], properties: {
+      state: { oneOf: [{ type: 'string' }, { type: 'object', additionalProperties: true }, { type: 'array', items: {} }] },
+      questions: { type: 'object', additionalProperties: { type: 'object', additionalProperties: true } },
+    }, additionalProperties: false },
+    output, timeoutMs: 25_000,
+    execute: (args, exec) => backend.evaluate(args, { signal: exec.signal }),
+  });
+  ctx.tools.register({
+    name: 'decision_check_connection', description: '向裁决端点发送一次轻量连通测试，不增加自动裁决指标。',
+    parameters: { type: 'object', properties: {}, additionalProperties: false }, output, timeoutMs: 25_000,
+    execute: async (_args, exec) => {
+      const result = await backend.evaluate({ state: 'Connection test', questions: {
+        connected: { type: 'noul', instructions: 'Is this a connection test?' },
+      } }, { signal: exec.signal });
+      return { connected: true, model: result.model, usage: result.usage };
+    },
+  });
+
+  ctx.inject(['webServer'], web => {
+    logStore = createLogStore({ port: web.webServer.port });
+    const unregister = createManagerRoutes({ path, sessions, backend, bindHost: web.webServer.host }).map(route => web.webServer.register(route));
+    return () => { unregister.forEach(dispose => dispose()); const store = logStore; logStore = undefined; void store?.dispose(); };
+  });
+}

package/service/log-store.mjs

@@ -0,0 +1,70 @@
+import { mkdir, appendFile, readdir, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export function logsDir() {
+  return join(homedir(), '.config', 'dsh-decision-layer', 'logs');
+}
+
+const dayStamp = date => date.toISOString().slice(0, 10);
+
+// Batched, rolling JSONL log writer keyed by the running instance's port. One
+// file per UTC day: `decisions-<port>-YYYY-MM-DD.jsonl`. Entries are buffered and
+// flushed on an interval or when the buffer fills; every flush prunes this port's
+// files older than the retention window. Writing is best-effort: a failed flush
+// drops that batch rather than throwing into the decision path.
+export function createLogStore({ port, dir = logsDir(), flushIntervalMs = 5000,
+  maxBuffer = 200, retentionDays = 30, now = () => new Date() } = {}) {
+  const safePort = Number.isInteger(port) && port > 0 && port < 65536 ? port : 0;
+  const prefix = `decisions-${safePort}-`;
+  let buffer = [];
+  let timer;
+  let flushing = false;
+
+  const fileFor = date => join(dir, `${prefix}${dayStamp(date)}.jsonl`);
+
+  const prune = async () => {
+    let names;
+    try { names = await readdir(dir); } catch { return; }
+    const cutoff = now().getTime() - retentionDays * 24 * 60 * 60 * 1000;
+    await Promise.all(names.map(async name => {
+      if (!name.startsWith(prefix) || !name.endsWith('.jsonl')) return;
+      const stamp = name.slice(prefix.length, -'.jsonl'.length);
+      const day = Date.parse(`${stamp}T00:00:00Z`);
+      if (Number.isFinite(day) && day < cutoff) await rm(join(dir, name), { force: true }).catch(() => {});
+    }));
+  };
+
+  const flush = async () => {
+    if (flushing || buffer.length === 0) return;
+    flushing = true;
+    const pending = buffer;
+    buffer = [];
+    try {
+      await mkdir(dir, { recursive: true, mode: 0o700 });
+      const byFile = new Map();
+      for (const entry of pending) {
+        const at = Number.isFinite(entry?.at) ? entry.at : now().getTime();
+        const file = fileFor(new Date(at));
+        (byFile.get(file) ?? byFile.set(file, []).get(file)).push(`${JSON.stringify(entry)}\n`);
+      }
+      for (const [file, lines] of byFile) await appendFile(file, lines.join(''), { mode: 0o600 });
+      await prune();
+    } catch { /* best effort; a dropped batch must never break the decision path */ }
+    finally { flushing = false; }
+  };
+
+  return {
+    append(entry) {
+      if (entry === null || typeof entry !== 'object') return;
+      buffer.push(entry);
+      if (buffer.length >= maxBuffer) { void flush(); return; }
+      if (!timer) timer = setTimeout(() => { timer = undefined; void flush(); }, flushIntervalMs);
+    },
+    flush,
+    dispose() {
+      if (timer) { clearTimeout(timer); timer = undefined; }
+      return flush();
+    },
+  };
+}

package/service/loop-guard.mjs

@@ -0,0 +1,52 @@
+import { createHash } from 'node:crypto';
+
+const MAX_FINGERPRINT_INPUT = 16 * 1024;
+
+export function fingerprintCall(exec) {
+  const name = typeof exec?.name === 'string' ? exec.name : '';
+  let args = '';
+  try { args = JSON.stringify(exec?.arguments ?? null); } catch { args = ''; }
+  return createHash('sha256').update(name).update('\0').update(args.slice(0, MAX_FINGERPRINT_INPUT)).digest('hex');
+}
+
+// Deterministic, backend-free loop guard: it denies only a run of the SAME tool
+// call repeated consecutively past a threshold. Any different intervening call
+// resets the run, so a legitimate identical call reached again later is allowed.
+export function createLoopGuard({ threshold = 3, maxSessions = 1024, sessions } = {}) {
+  if (!Number.isSafeInteger(threshold) || threshold < 2) throw new Error('Invalid loop threshold');
+  const runs = new Map();
+  const runFor = id => {
+    let run = runs.get(id);
+    if (!run) {
+      if (runs.size >= maxSessions) runs.delete(runs.keys().next().value);
+      run = { key: undefined, count: 0 };
+      runs.set(id, run);
+    }
+    return run;
+  };
+  return {
+    check(exec) {
+      const id = exec?.agent?.session?.id;
+      if (typeof id !== 'string') return undefined;
+      // The master switch pauses automatic intervention (mirrors the danger gate);
+      // capacity overflow still guards, since that is involuntary, not a user choice.
+      if (sessions) {
+        try {
+          const snapshot = sessions.snapshot(id);
+          if (snapshot.enabled === false && !snapshot.capacityExceeded) return undefined;
+        } catch { /* fall through and guard */ }
+      }
+      const run = runFor(id);
+      const key = fingerprintCall(exec);
+      run.count = key === run.key ? run.count + 1 : 1;
+      run.key = key;
+      if (run.count >= threshold) {
+        return `Identical tool call repeated ${run.count} times in a row; blocked to break a loop`;
+      }
+      return undefined;
+    },
+    runLength(id) {
+      return runs.get(id)?.count ?? 0;
+    },
+  };
+}

package/service/manager-api.mjs

@@ -0,0 +1,87 @@
+import { loadConfig, resolveConfig, saveConfig } from './config-store.mjs';
+
+export const API_PREFIX = '/plugins/dsh-decision-layer/api';
+const BODY_LIMIT = 32 * 1024;
+
+function respond(res, status, value) {
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store',
+    'x-content-type-options': 'nosniff', 'referrer-policy': 'no-referrer' });
+  res.end(JSON.stringify(value));
+}
+
+function authorizedBrowser(req) {
+  const address = req.socket?.remoteAddress;
+  if (!['127.0.0.1', '::1', '::ffff:127.0.0.1'].includes(address)) return false;
+  const host = req.headers.host;
+  if (typeof host !== 'string' || !/^(localhost|127\.0\.0\.1|\[::1\]):\d+$/.test(host)) return false;
+  if (req.headers['sec-fetch-site'] === 'cross-site') return false;
+  const origin = req.headers.origin;
+  if (origin === undefined) return req.method === 'GET';
+  try {
+    const parsed = new URL(origin);
+    return ['http:', 'https:'].includes(parsed.protocol) && parsed.host === host;
+  } catch { return false; }
+}
+
+async function readBody(req) {
+  if (!req.headers['content-type']?.startsWith('application/json')) throw new Error('Expected JSON');
+  let size = 0;
+  const chunks = [];
+  for await (const chunk of req) {
+    size += chunk.length;
+    if (size > BODY_LIMIT) throw new Error('Request too large');
+    chunks.push(chunk);
+  }
+  const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error('Expected object');
+  return value;
+}
+
+export function createManagerRoutes({ path, sessions, backend, env = process.env, bindHost = '127.0.0.1' }) {
+  const route = (suffix, methods) => ({ kind: 'exact', path: `${API_PREFIX}/${suffix}`, handler: async (req, res) => {
+    if (bindHost !== '127.0.0.1' || !authorizedBrowser(req)) return respond(res, 403, { ok: false, error: 'Local same-origin browser request required' });
+    if (!Object.hasOwn(methods, req.method)) return respond(res, 405, { ok: false, error: 'Method not allowed' });
+    try {
+      const value = await methods[req.method](req);
+      return respond(res, 200, { ok: true, value });
+    } catch (error) {
+      if (error?.code === 'BAD_REQUEST') return respond(res, 400, { ok: false, error: error.message });
+      return respond(res, 400, { ok: false, error: 'Invalid request or backend unavailable' });
+    }
+  } });
+  const sessionId = req => {
+    const id = new URL(req.url ?? '/', 'http://localhost').searchParams.get('sessionId');
+    if (!id) { const error = new Error('sessionId is required'); error.code = 'BAD_REQUEST'; throw error; }
+    return id;
+  };
+  return [
+    route('config', {
+      GET: async () => ({ ...(await loadConfig(path)), effectiveUrl: (await resolveConfig({ path, env })).url }),
+      PUT: async req => {
+        const saved = await saveConfig(await readBody(req), path);
+        return { ...saved, effectiveUrl: (await resolveConfig({ path, env })).url };
+      },
+    }),
+    route('probe', {
+      POST: async () => {
+        const effectiveUrl = (await resolveConfig({ path, env })).url;
+        try {
+          const result = await backend.evaluate({ state: 'Connection test', questions: {
+            connected: { type: 'noul', instructions: 'Is this a connection test?' },
+          } });
+          return { connected: true, model: result.model, usage: result.usage, effectiveUrl };
+        } catch { return { connected: false, reason: 'unavailable', effectiveUrl }; }
+      },
+    }),
+    route('metrics', { GET: req => sessions.snapshot(sessionId(req)) }),
+    route('log', { GET: req => ({ entries: sessions.snapshot(sessionId(req)).log ?? [] }) }),
+    route('session', {
+      GET: req => sessions.snapshot(sessionId(req)),
+      PUT: async req => {
+        const body = await readBody(req);
+        sessions.setEnabled(body.sessionId, body.enabled);
+        return sessions.snapshot(body.sessionId);
+      },
+    }),
+  ];
+}

package/service/narrowing.mjs

@@ -0,0 +1,149 @@
+const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const probability = value => typeof value === 'number' && Number.isFinite(value) && value >= 0 && value <= 1;
+const MAX_STATE = 8 * 1024;
+
+// Core tools an agent almost always needs. They are never judged for relevance
+// and never dropped, so narrowing cannot strip the agent's fundamental
+// capabilities. Beyond the filesystem/shell/search/todo basics, this includes
+// the DSH agent meta-abilities (ask the user, goals, skills, delivery, images,
+// background jobs, teammates, subagents): their relevance rarely shows in a
+// single turn's task text, so per-tool judging would keep pruning them.
+export const DEFAULT_CORE_TOOLS = Object.freeze([
+  'read', 'write', 'edit', 'bash', 'glob', 'grep', 'ls', 'todo_write',
+  'ask_user_question', 'create_goal', 'update_goal', 'get_goal', 'exit_plan_mode',
+  'skill', 'present', 'read_image', 'workflow',
+  'job_list', 'job_output', 'job_kill',
+  'spawn_teammate', 'interrupt_agent', 'list_agents', 'wait_agent', 'send_message',
+  'subagent', 'subagent_fork',
+]);
+
+// Tool-name prefixes that are always kept and never judged, on top of the core
+// tools. Memory/context tools like OpenViking are "keep resident, trigger on
+// demand": their relevance rarely shows in the literal task text, so per-tool
+// relevance judging would keep pruning them. `team_task_` covers the shared
+// task-board tools as a group. Users can override this list.
+export const DEFAULT_KEEP_PREFIXES = Object.freeze(['mcp__openviking', 'team_task_']);
+
+// Intersect the host-allowed tool set with the model's relevance verdict. Only
+// removes tools; never adds. Any missing or invalid noul keeps the tool, and a
+// verdict that would strip everything is skipped so the agent is never disabled.
+// Drop threshold: a tool is dropped only when the model is fairly confident it
+// is not needed (noul < threshold). Default 0.3 is deliberately conservative —
+// a noul near 0.5 means the model is unsure, and dropping there is the most
+// likely to strip a still-useful tool, so uncertain tools are kept.
+export function narrowTools(allowed, result, { threshold = 0.3 } = {}) {
+  const tools = Array.isArray(allowed) ? allowed.filter(name => typeof name === 'string') : [];
+  const answers = isObject(result?.answers) ? result.answers : undefined;
+  if (tools.length === 0 || !answers) return { applied: false, keep: [...tools], drop: [] };
+
+  const keep = [];
+  const drop = [];
+  for (const name of tools) {
+    const answer = answers[name];
+    if (isObject(answer) && answer.type === 'noul' && probability(answer.noul) && answer.noul < threshold) drop.push(name);
+    else keep.push(name);
+  }
+  if (drop.length === 0 || keep.length === 0) return { applied: false, keep: [...tools], drop: [] };
+  return { applied: true, keep, drop };
+}
+
+// Build one Noul relevance question per candidate tool. The state carries the
+// current task; each question references the tool being judged. Noul answers
+// have no confidence field, so relevance is read straight from the probability.
+export function relevanceQuestions(state, tools) {
+  const task = typeof state === 'string' ? state.slice(0, MAX_STATE)
+    : isObject(state) ? state : '';
+  return {
+    state: task,
+    questions: Object.fromEntries(tools.map(tool => [tool.name, {
+      type: 'noul',
+      instructions: {
+        tool: { name: tool.name, description: typeof tool.description === 'string' ? tool.description.slice(0, 512) : '' },
+        question: '完成当前任务是否会用到 `tool` 描述的这个工具？',
+      },
+    }])),
+  };
+}
+
+// Orchestrates one relevance pass over the host-allowed tools. Pure of DSH
+// runtime types: the caller supplies the candidate tools and the task state,
+// and owns applying the restriction (only enforce mode should act on `drop`).
+// `settings` resolves { mode: 'observe' | 'enforce', threshold } live.
+//
+// Guardrails against over-narrowing a large tool surface:
+//   A. core tools are always kept and never judged (DEFAULT_CORE_TOOLS);
+//   B. when the judged (optional) candidate count exceeds `maxCandidates`,
+//      enforce is downgraded to observe so a large surface cannot be mass-pruned;
+//   C. if narrowing would leave fewer than `minKeep` tools total, the verdict is
+//      treated as untrustworthy and no restriction is applied.
+export function createNarrowing({ evaluate, sessions, settings, coreTools = DEFAULT_CORE_TOOLS,
+  keepPrefixes = DEFAULT_KEEP_PREFIXES, minCandidates = 2, maxCandidates = 20, minKeep = 5 } = {}) {
+  if (typeof evaluate !== 'function') throw new Error('Narrowing requires an evaluator');
+  const core = new Set(Array.isArray(coreTools) ? coreTools.filter(name => typeof name === 'string') : []);
+  const defaultPrefixes = Array.isArray(keepPrefixes) ? keepPrefixes.filter(prefix => typeof prefix === 'string' && prefix) : [];
+  const resolveSettings = async () => {
+    let raw = {};
+    try { raw = (typeof settings === 'function' ? await settings() : settings) ?? {}; } catch { raw = {}; }
+    const mode = raw?.mode === 'observe' ? 'observe' : 'enforce';
+    const threshold = typeof raw?.threshold === 'number' && Number.isFinite(raw.threshold) && raw.threshold >= 0 && raw.threshold <= 1 ? raw.threshold : 0.3;
+    // An explicit array in settings (including empty) overrides the default set.
+    const prefixes = Array.isArray(raw?.keepPrefixes)
+      ? raw.keepPrefixes.filter(prefix => typeof prefix === 'string' && prefix)
+      : defaultPrefixes;
+    // A configured optional-candidate ceiling overrides the constructor default.
+    const cap = Number.isSafeInteger(raw?.maxCandidates) && raw.maxCandidates >= 1 ? raw.maxCandidates : maxCandidates;
+    return { mode, threshold, prefixes, cap };
+  };
+  const record = (turn, outcome, detail = {}) => {
+    const id = turn?.agent?.session?.id;
+    if (!sessions || typeof id !== 'string') return;
+    try { if (typeof sessions.recordNarrow === 'function') sessions.recordNarrow(id, outcome, detail.dropped ?? 0); }
+    catch { /* telemetry is best effort */ }
+    if (typeof sessions.log !== 'function') return;
+    try { sessions.log(id, { kind: 'narrow', outcome, ...detail }); }
+    catch { /* logging is best effort */ }
+  };
+  const skip = { evaluated: false, applied: false, keep: [], drop: [], mode: 'observe' };
+  return {
+    async review(turn) {
+      const tools = Array.isArray(turn?.tools) ? turn.tools.filter(tool => tool && typeof tool.name === 'string') : [];
+      const names = tools.map(tool => tool.name);
+      const { mode, threshold, prefixes, cap } = await resolveSettings();
+      // A: core tools and keep-prefix matches are always kept and never sent to
+      // the model for judging (e.g. mcp__openviking memory tools stay resident).
+      const alwaysKeep = name => core.has(name) || prefixes.some(prefix => name.startsWith(prefix));
+      const keptNames = names.filter(alwaysKeep);
+      const optional = tools.filter(tool => !alwaysKeep(tool.name));
+      const optionalNames = optional.map(tool => tool.name);
+      if (optional.length < minCandidates) return { ...skip, keep: names };
+      const hasState = typeof turn?.state === 'string' ? turn.state.trim().length > 0
+        : isObject(turn?.state) ? Object.keys(turn.state).length > 0 : false;
+      if (!hasState) return { ...skip, keep: names };
+      const id = turn?.agent?.session?.id;
+      if (sessions && typeof id === 'string') {
+        try { if (sessions.snapshot(id).enabled === false) return { ...skip, keep: names }; }
+        catch { return { ...skip, keep: names }; }
+      }
+      // B: a large optional surface must not be enforced — only observed.
+      const overCap = optional.length > cap;
+      const effectiveMode = overCap ? 'observe' : mode;
+      let result;
+      try { result = await evaluate(relevanceQuestions(turn.state, optional), { signal: turn.signal }); }
+      catch (error) { record(turn, 'error', { reason: typeof error?.reason === 'string' ? error.reason : 'unreachable', mode: effectiveMode }); return { ...skip, keep: names, mode: effectiveMode }; }
+      const narrowed = narrowTools(optionalNames, result, { threshold });
+      const keep = [...keptNames, ...narrowed.keep];
+      const drop = narrowed.drop;
+      // C: too few tools left over is a sign the verdict over-pruned; do not apply.
+      const trustworthy = keep.length >= minKeep;
+      const applied = narrowed.applied && trustworthy && !overCap && mode === 'enforce';
+      const dropped = drop.length;
+      const detail = { dropped, kept: keep.length, mode: effectiveMode, tools: drop };
+      // The optional-candidate count (excludes core tools and keep-prefix matches),
+      // recorded so the "too many candidates" reason shows the number that tripped it.
+      if (overCap) { detail.reason = 'too-many-candidates'; detail.candidates = optional.length; }
+      else if (dropped > 0 && !trustworthy) detail.reason = 'low-keep';
+      record(turn, dropped > 0 ? 'applied' : 'ok', detail);
+      return { evaluated: true, applied, keep, drop, mode: effectiveMode, overCap, trustworthy };
+    },
+  };
+}

package/service/self-check.mjs

@@ -0,0 +1,94 @@
+const MAX_OUTPUT = 24 * 1024;
+
+export const DEFAULT_RUBRIC = Object.freeze([
+  '明显答非所问，或存在严重遗漏 / 自相矛盾',
+  '基本答到问题，但有可察觉的遗漏或不严谨',
+  '完整、准确、无自相矛盾地回应了请求',
+]);
+
+const STEER_TEXT = '本回合自检得分偏低：请复核是否答到了用户的问题、有无遗漏或自相矛盾，并在需要时补完。';
+
+function boundedRubric(rubric) {
+  if (!Array.isArray(rubric)) return DEFAULT_RUBRIC;
+  const levels = rubric.filter(item => typeof item === 'string' && item.trim() && item.length <= 256).slice(0, 10);
+  return levels.length >= 2 ? levels : DEFAULT_RUBRIC;
+}
+
+export function scoreQuestion(output, rubric = DEFAULT_RUBRIC) {
+  return {
+    state: { answer: String(output).slice(0, MAX_OUTPUT) },
+    questions: { quality: {
+      type: 'score',
+      instructions: '按下列从低到高的档位，评估这次最终产出对用户请求的完成质量。',
+      criteria: boundedRubric(rubric),
+    } },
+  };
+}
+
+// `settings` is an async resolver so rubric/mode/threshold follow live config.
+// `steer(agent, text)` performs the host-native steer; the caller owns building
+// the framework UserMessage so this module stays free of DSH message types.
+export function createSelfCheck({ evaluate, sessions, steer, settings, minConfidence = 0.4 } = {}) {
+  if (typeof evaluate !== 'function') throw new Error('Self-check requires an evaluator');
+  const steeredTurns = new Set();
+  const steerKey = turn => {
+    const id = turn?.agent?.session?.id;
+    return typeof id === 'string' && Number.isInteger(turn?.turn) ? `${id}:${turn.turn}` : undefined;
+  };
+  const resolveSettings = async () => {
+    let raw = {};
+    try { raw = (typeof settings === 'function' ? await settings() : settings) ?? {}; } catch { raw = {}; }
+    const mode = raw?.mode === 'steer' ? 'steer' : 'observe';
+    const lowScoreThreshold = Number.isSafeInteger(raw?.lowScoreThreshold) && raw.lowScoreThreshold >= 0 ? raw.lowScoreThreshold : 1;
+    return { mode, rubric: boundedRubric(raw?.rubric), lowScoreThreshold };
+  };
+  const record = (turn, outcome, detail = {}) => {
+    const id = turn?.agent?.session?.id;
+    if (!sessions || typeof id !== 'string' || typeof sessions.recordCheck !== 'function') return;
+    try { sessions.recordCheck(id, outcome); } catch { /* telemetry is best effort */ }
+    if (typeof sessions.log !== 'function') return;
+    try { sessions.log(id, { kind: 'check', outcome, ...detail }); }
+    catch { /* logging is best effort */ }
+  };
+  return {
+    async review(turn) {
+      const output = typeof turn?.output === 'string' ? turn.output.trim() : '';
+      if (!output) return { evaluated: false, lowScore: false, steered: false };
+      const id = turn?.agent?.session?.id;
+      if (sessions && typeof id === 'string') {
+        try { if (sessions.snapshot(id).enabled === false) return { evaluated: false, lowScore: false, steered: false }; }
+        catch { return { evaluated: false, lowScore: false, steered: false }; }
+      }
+      const { mode, rubric, lowScoreThreshold } = await resolveSettings();
+      let answer;
+      try {
+        const result = await evaluate(scoreQuestion(output, rubric), { signal: turn.signal });
+        answer = result?.answers?.quality;
+      } catch (error) { record(turn, 'error', { reason: typeof error?.reason === 'string' ? error.reason : 'unreachable' }); return { evaluated: false, lowScore: false, steered: false }; }
+      if (!answer || answer.type !== 'score' || typeof answer.score !== 'number' || !Number.isFinite(answer.score)) {
+        record(turn, 'error', { reason: 'invalid-response' });
+        return { evaluated: false, lowScore: false, steered: false };
+      }
+      // A low-confidence Score is a legitimate answer, not a failure: the score
+      // stays usable and is recorded as ok/low. Confidence only gates the steer,
+      // because only interrupting the user warrants the model being sure.
+      const confidence = typeof answer.confidence === 'number' && Number.isFinite(answer.confidence) ? answer.confidence : undefined;
+      const detail = confidence === undefined ? {} : { confidence };
+      const lowScore = answer.score <= lowScoreThreshold;
+      record(turn, lowScore ? 'low' : 'ok', { score: answer.score, ...detail });
+      if (!lowScore) return { evaluated: true, lowScore: false, steered: false, score: answer.score };
+      const confident = confidence !== undefined && confidence >= minConfidence;
+      if (mode === 'steer' && confident && typeof steer === 'function' && turn?.agent) {
+        const key = steerKey(turn);
+        if (key !== undefined && !steeredTurns.has(key)) {
+          steeredTurns.add(key);
+          if (steeredTurns.size > 4096) steeredTurns.delete(steeredTurns.values().next().value);
+          try { steer(turn.agent, STEER_TEXT); }
+          catch { return { evaluated: true, lowScore: true, steered: false, score: answer.score }; }
+          return { evaluated: true, lowScore: true, steered: true, score: answer.score };
+        }
+      }
+      return { evaluated: true, lowScore: true, steered: false, score: answer.score };
+    },
+  };
+}