dsh-decision-layer 0.7.1 → 0.7.3

package/lib/host/manager-api.js

@@ -0,0 +1,174 @@
+import { loadConfig, resolveConfig, saveConfig } from "./config-store.js";
+import { isObject } from "./types.js";
+const API_PREFIX = "/plugins/dsh-decision-layer/api";
+const BODY_LIMIT = 32 * 1024;
+const codedError = (message, code) => Object.assign(new Error(message), { code });
+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 === void 0) return req.method === "GET";
+  if (typeof origin !== "string") return false;
+  try {
+    const parsed = new URL(origin);
+    return ["http:", "https:"].includes(parsed.protocol) && parsed.host === host;
+  } catch {
+    return false;
+  }
+}
+async function readBody(req) {
+  const contentType = req.headers["content-type"];
+  if (typeof contentType !== "string" || !contentType.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 (!isObject(value)) throw new Error("Expected object");
+  return value;
+}
+function createManagerRoutes({ path, sessions, backend, logStore, analyze, listRows, 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" });
+    const method = req.method ?? "";
+    if (!Object.hasOwn(methods, method)) return respond(res, 405, { ok: false, error: "Method not allowed" });
+    const handler = methods[method];
+    if (typeof handler !== "function") return respond(res, 405, { ok: false, error: "Method not allowed" });
+    try {
+      const value = await handler(req);
+      return respond(res, 200, { ok: true, value });
+    } catch (error) {
+      const coded = error;
+      if (coded?.code === "INTERNAL") return respond(res, 500, { ok: false, error: "Internal error" });
+      if (coded?.code === "BAD_REQUEST") return respond(res, 400, { ok: false, error: coded.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) throw codedError("sessionId is required", "BAD_REQUEST");
+    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: async (req) => {
+      const id = sessionId(req);
+      await sessions.ensureLoaded?.(id);
+      return sessions.snapshot(id);
+    } }),
+    route("log", { GET: async (req) => {
+      const id = sessionId(req);
+      await sessions.ensureLoaded?.(id);
+      return { entries: sessions.snapshot(id).log ?? [] };
+    } }),
+    // Read-only analysis over the persisted decision logs for one session. Returns
+    // only aggregates and annotation counts — never raw log rows — so gate command
+    // / path fragments are not echoed back to the browser.
+    route("logs", {
+      GET: async (req) => {
+        if (typeof analyze !== "function") throw codedError("analysis unavailable", "BAD_REQUEST");
+        const id = sessionId(req);
+        try {
+          return await analyze(id);
+        } catch (error) {
+          if (error?.code === "BAD_REQUEST") throw error;
+          throw codedError("analysis failed", "INTERNAL");
+        }
+      }
+    }),
+    // One newest-first page of this session's full persisted decision rows, for
+    // the analysis tab's paginated log. Rows carry the same panel fields as /log,
+    // including the gate's already-redacted and length-bounded command/path, so
+    // this exposes nothing the recent-rows route does not already.
+    route("logrows", {
+      GET: async (req) => {
+        if (typeof listRows !== "function") throw codedError("log rows unavailable", "BAD_REQUEST");
+        const id = sessionId(req);
+        const params = new URL(req.url ?? "/", "http://localhost").searchParams;
+        const page = Number.parseInt(params.get("page") ?? "1", 10);
+        const pageSize = Number.parseInt(params.get("pageSize") ?? "100", 10);
+        try {
+          return await listRows(id, { page: Number.isNaN(page) ? 1 : page, pageSize: Number.isNaN(pageSize) ? 100 : pageSize });
+        } catch (error) {
+          if (error?.code === "BAD_REQUEST") throw error;
+          throw codedError("log rows failed", "INTERNAL");
+        }
+      }
+    }),
+    // Append one annotation event for a decision. Explicit user intent: validated
+    // and written immediately; a write failure surfaces as an error, not silence.
+    route("annotate", {
+      POST: async (req) => {
+        if (!logStore || typeof logStore.appendAnnotation !== "function") throw codedError("annotation unavailable", "BAD_REQUEST");
+        const body = await readBody(req);
+        const target = typeof body.target === "string" ? body.target.trim() : "";
+        const rating = body.rating;
+        const session = typeof body.sessionId === "string" ? body.sessionId.trim() : "";
+        if (!target || target.length > 128 || !["good", "bad", "unsure"].includes(rating) || !session || session.length > 512) {
+          throw codedError("Invalid annotation", "BAD_REQUEST");
+        }
+        try {
+          await logStore.appendAnnotation({ kind: "annotation", target, rating, sessionId: session });
+        } catch {
+          throw codedError("annotation write failed", "INTERNAL");
+        }
+        return { ok: true, target, rating };
+      }
+    }),
+    route("session", {
+      GET: async (req) => {
+        const id = sessionId(req);
+        await sessions.ensureLoaded?.(id);
+        return sessions.snapshot(id);
+      },
+      PUT: async (req) => {
+        const body = await readBody(req);
+        const id = body.sessionId;
+        const enabled = body.enabled;
+        if (typeof id !== "string" || typeof enabled !== "boolean") throw codedError("Invalid session switch", "BAD_REQUEST");
+        await sessions.ensureLoaded?.(id);
+        if (typeof sessions.setEnabled !== "function") throw codedError("session switch unavailable", "BAD_REQUEST");
+        sessions.setEnabled(id, enabled);
+        return sessions.snapshot(id);
+      }
+    })
+  ];
+}
+export {
+  API_PREFIX,
+  createManagerRoutes
+};

package/lib/host/narrowing.d.ts

@@ -0,0 +1,51 @@
+import type { AgentLike, EvaluateInput, Evaluator, NarrowMode, NarrowSettings, SessionsFace, ToolCandidate } from './types.js';
+export declare const narrowApplied: (record: {
+    applied?: unknown;
+    reason?: unknown;
+    outcome?: unknown;
+} | undefined) => boolean;
+export declare const DEFAULT_CORE_TOOLS: readonly string[];
+export declare const DEFAULT_KEEP_PREFIXES: readonly string[];
+export declare const DEFAULT_NARROW_THRESHOLD = 0.7;
+export declare function narrowTools(allowed: unknown, result: unknown, { threshold, keepBase }?: {
+    threshold?: number;
+    keepBase?: number;
+}): {
+    applied: boolean;
+    keep: string[];
+    drop: string[];
+};
+export declare function relevanceQuestions(state: unknown, tools: readonly ToolCandidate[]): EvaluateInput;
+export type NarrowTurn = {
+    agent?: AgentLike;
+    turn?: number;
+    step?: number;
+    signal?: AbortSignal;
+    state?: unknown;
+    /** Raw request text for the log row; `state` may now be a structured object. */
+    taskText?: unknown;
+    tools?: unknown;
+};
+export type NarrowResult = {
+    evaluated: boolean;
+    applied: boolean;
+    keep: string[];
+    drop: string[];
+    mode: NarrowMode;
+    overCap?: boolean;
+    trustworthy?: boolean;
+};
+export type NarrowingOptions = {
+    evaluate?: Evaluator;
+    sessions?: SessionsFace;
+    settings?: NarrowSettings | (() => Promise<NarrowSettings | undefined>);
+    coreTools?: readonly string[];
+    keepPrefixes?: readonly string[];
+    minCandidates?: number;
+    maxCandidates?: number;
+    minKeep?: number;
+    splitConcurrency?: number;
+};
+export declare function createNarrowing({ evaluate, sessions, settings, coreTools, keepPrefixes, minCandidates, maxCandidates, minKeep, splitConcurrency }?: NarrowingOptions): {
+    review(turn: NarrowTurn | undefined): Promise<NarrowResult>;
+};

package/lib/host/narrowing.js

@@ -0,0 +1,214 @@
+import { taskExcerpt } from "./excerpt.js";
+import { errorReason, isObject, isProbability } from "./types.js";
+const narrowApplied = (record) => {
+  if (record?.applied === false) return false;
+  if (record?.reason === "low-keep" || record?.reason === "too-many-candidates") return false;
+  return record?.applied === true || record?.outcome === "applied";
+};
+const MAX_STATE = 8 * 1024;
+const MAX_QUESTIONS = 64;
+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"
+]);
+const DEFAULT_KEEP_PREFIXES = Object.freeze(["mcp__openviking"]);
+const DEFAULT_NARROW_THRESHOLD = 0.7;
+function narrowTools(allowed, result, { threshold = DEFAULT_NARROW_THRESHOLD, keepBase = 0 } = {}) {
+  const tools = Array.isArray(allowed) ? allowed.filter((name) => typeof name === "string") : [];
+  const answers = isObject(result) && isObject(result.answers) ? result.answers : void 0;
+  if (tools.length === 0 || !answers) return { applied: false, keep: [...tools], drop: [] };
+  const base = Number.isSafeInteger(keepBase) && keepBase > 0 ? keepBase : 0;
+  const keep = [];
+  const drop = [];
+  for (const name of tools) {
+    const answer = answers[name];
+    if (isObject(answer) && answer.type === "noul" && isProbability(answer.noul) && answer.noul < threshold) drop.push(name);
+    else keep.push(name);
+  }
+  if (drop.length === 0 || keep.length + base === 0) return { applied: false, keep: [...tools], drop: [] };
+  return { applied: true, keep, drop };
+}
+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: "\u5B8C\u6210\u5F53\u524D\u4EFB\u52A1\u662F\u5426\u4F1A\u7528\u5230 `tool` \u63CF\u8FF0\u7684\u8FD9\u4E2A\u5DE5\u5177\uFF1F"
+      }
+    }]))
+  };
+}
+function createNarrowing({
+  evaluate,
+  sessions,
+  settings,
+  coreTools = DEFAULT_CORE_TOOLS,
+  keepPrefixes = DEFAULT_KEEP_PREFIXES,
+  minCandidates = 2,
+  maxCandidates = 20,
+  minKeep = 5,
+  splitConcurrency = 8
+} = {}) {
+  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 concurrency = Number.isSafeInteger(splitConcurrency) && splitConcurrency >= 1 ? splitConcurrency : 8;
+  let adaptiveSplit = false;
+  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 : DEFAULT_NARROW_THRESHOLD;
+    const batchMode = raw?.batchMode === "single" || raw?.batchMode === "split" ? raw.batchMode : "auto";
+    const prefixes = Array.isArray(raw?.keepPrefixes) ? raw.keepPrefixes.filter((prefix) => typeof prefix === "string" && Boolean(prefix)) : defaultPrefixes;
+    const configuredCap = Number.isSafeInteger(raw?.maxCandidates) && raw.maxCandidates >= 1 ? raw.maxCandidates : maxCandidates;
+    const cap = Math.min(configuredCap, MAX_QUESTIONS);
+    return { mode, threshold, prefixes, cap, batchMode };
+  };
+  const record = (turn, outcome, detail = {}) => {
+    const id = turn?.agent?.session?.id;
+    if (!sessions || typeof id !== "string") return;
+    try {
+      sessions.recordNarrow?.(id, outcome, detail.dropped ?? 0, narrowApplied({ ...detail, outcome }));
+    } catch {
+    }
+    if (typeof sessions.log !== "function") return;
+    try {
+      const task = taskExcerpt(turn?.taskText ?? turn?.state);
+      const context = task ? { task } : {};
+      if (Number.isSafeInteger(turn?.turn) && turn?.turn >= 0) context.turn = turn?.turn;
+      if (Number.isSafeInteger(turn?.step) && turn?.step >= 0) context.step = turn?.step;
+      sessions.log(id, { kind: "narrow", outcome, ...context, ...detail });
+    } catch {
+    }
+  };
+  const evaluateSplit = async (state, tools, signal) => {
+    const answers = /* @__PURE__ */ Object.create(null);
+    let anyOk = false;
+    for (let i = 0; i < tools.length; i += concurrency) {
+      const group = tools.slice(i, i + concurrency);
+      const settled = await Promise.all(group.map(async (tool) => {
+        try {
+          const reply = await evaluate(relevanceQuestions(state, [tool]), { signal });
+          const answer = reply?.answers?.[tool.name];
+          return isObject(answer) ? [tool.name, answer] : void 0;
+        } catch {
+          return void 0;
+        }
+      }));
+      for (const pair of settled) {
+        if (pair) {
+          answers[pair[0]] = pair[1];
+          anyOk = true;
+        }
+      }
+    }
+    return anyOk ? { model: "split", answers } : null;
+  };
+  const skip = { evaluated: false, applied: false, keep: [], drop: [], mode: "observe" };
+  return {
+    async review(turn) {
+      const tools = Array.isArray(turn?.tools) ? turn.tools.filter((tool) => isObject(tool) && typeof tool.name === "string") : [];
+      const names = tools.map((tool) => tool.name);
+      const { mode, threshold, prefixes, cap, batchMode } = await resolveSettings();
+      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));
+      if (optional.length < minCandidates) return { ...skip, keep: names };
+      const hasState = typeof turn?.taskText === "string" ? turn.taskText.trim().length > 0 : 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 };
+        }
+      }
+      const overCap = optional.length > cap;
+      const effectiveMode = overCap ? "observe" : mode;
+      const judged = overCap ? optional.slice(0, cap) : optional;
+      const judgedNames = judged.map((tool) => tool.name);
+      let result = null;
+      if (batchMode === "split" || adaptiveSplit) {
+        result = await evaluateSplit(turn?.state, judged, turn?.signal);
+        if (!result) {
+          record(turn, "error", { reason: "unreachable", mode: effectiveMode });
+          return { ...skip, keep: names, mode: effectiveMode };
+        }
+      } else {
+        try {
+          const reply = await evaluate(relevanceQuestions(turn?.state, judged), { signal: turn?.signal });
+          result = reply;
+        } catch (error) {
+          const reason = errorReason(error);
+          if (batchMode === "auto" && reason === "http-error") {
+            adaptiveSplit = true;
+            result = await evaluateSplit(turn?.state, judged, turn?.signal);
+            if (!result) {
+              record(turn, "error", { reason, mode: effectiveMode });
+              return { ...skip, keep: names, mode: effectiveMode };
+            }
+          } else {
+            record(turn, "error", { reason, mode: effectiveMode });
+            return { ...skip, keep: names, mode: effectiveMode };
+          }
+        }
+      }
+      const narrowed = narrowTools(judgedNames, result, { threshold, keepBase: keptNames.length });
+      const keep = [...keptNames, ...narrowed.keep];
+      const drop = narrowed.drop;
+      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, applied };
+      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 };
+    }
+  };
+}
+export {
+  DEFAULT_CORE_TOOLS,
+  DEFAULT_KEEP_PREFIXES,
+  DEFAULT_NARROW_THRESHOLD,
+  createNarrowing,
+  narrowApplied,
+  narrowTools,
+  relevanceQuestions
+};

package/lib/host/quality-trend.d.ts

@@ -0,0 +1,14 @@
+import type { Severity } from './types.js';
+export declare const DEFAULT_TREND_MIN_CONFIDENCE = 0.6;
+export declare const DEFAULT_TREND_RUN = 3;
+export declare const DEFAULT_TREND_SEVERE_RUN = 5;
+export type TrendSample = {
+    lowScore?: boolean;
+    confident?: boolean;
+};
+export type TrendThresholds = {
+    trendRun?: number;
+    trendSevereRun?: number;
+};
+export declare function advanceRun(run: number, sample: TrendSample | undefined): number;
+export declare function severityOf(run: number, { trendRun, trendSevereRun }?: TrendThresholds): Severity;

package/lib/host/quality-trend.js

@@ -0,0 +1,22 @@
+const DEFAULT_TREND_MIN_CONFIDENCE = 0.6;
+const DEFAULT_TREND_RUN = 3;
+const DEFAULT_TREND_SEVERE_RUN = 5;
+function advanceRun(run, sample) {
+  const current = Number.isSafeInteger(run) && run >= 0 ? run : 0;
+  if (!sample || sample.lowScore !== true) return 0;
+  if (sample.confident === true) return current + 1;
+  return current;
+}
+function severityOf(run, { trendRun = DEFAULT_TREND_RUN, trendSevereRun = DEFAULT_TREND_SEVERE_RUN } = {}) {
+  const value = Number.isSafeInteger(run) && run >= 0 ? run : 0;
+  if (value >= trendSevereRun) return "severe";
+  if (value >= trendRun) return "warn";
+  return "normal";
+}
+export {
+  DEFAULT_TREND_MIN_CONFIDENCE,
+  DEFAULT_TREND_RUN,
+  DEFAULT_TREND_SEVERE_RUN,
+  advanceRun,
+  severityOf
+};

package/lib/host/self-check.d.ts

@@ -0,0 +1,28 @@
+import type { AgentLike, CheckSettings, DecisionContext, EvaluateInput, Evaluator, SessionsFace } from './types.js';
+export declare const DEFAULT_RUBRIC: readonly string[];
+export declare function scoreQuestion(output: unknown, rubric?: readonly string[], context?: DecisionContext): EvaluateInput;
+export declare const DEFAULT_MIN_CONFIDENCE = 0.4;
+export type CheckTurn = {
+    agent?: AgentLike;
+    turn?: number;
+    signal?: AbortSignal;
+    output?: unknown;
+    userText?: unknown;
+    context?: DecisionContext;
+};
+export type CheckResult = {
+    evaluated: boolean;
+    lowScore: boolean;
+    steered: boolean;
+    score?: number;
+};
+export type SelfCheckOptions = {
+    evaluate?: Evaluator;
+    sessions?: SessionsFace;
+    steer?: (agent: AgentLike, text: string) => unknown;
+    settings?: CheckSettings | (() => Promise<CheckSettings | undefined>);
+    minConfidence?: number;
+};
+export declare function createSelfCheck({ evaluate, sessions, steer, settings, minConfidence }?: SelfCheckOptions): {
+    review(turn: CheckTurn | undefined): Promise<CheckResult>;
+};

package/lib/host/self-check.js

@@ -0,0 +1,111 @@
+import { taskExcerpt } from "./excerpt.js";
+import { createSteerOnce } from "./steer-once.js";
+import { errorReason, isProbability } from "./types.js";
+const MAX_OUTPUT = 24 * 1024;
+const DEFAULT_RUBRIC = Object.freeze([
+  "\u660E\u663E\u7B54\u975E\u6240\u95EE\uFF0C\u6216\u5B58\u5728\u4E25\u91CD\u9057\u6F0F / \u81EA\u76F8\u77DB\u76FE",
+  "\u57FA\u672C\u7B54\u5230\u95EE\u9898\uFF0C\u4F46\u6709\u53EF\u5BDF\u89C9\u7684\u9057\u6F0F\u6216\u4E0D\u4E25\u8C28",
+  "\u5B8C\u6574\u3001\u51C6\u786E\u3001\u65E0\u81EA\u76F8\u77DB\u76FE\u5730\u56DE\u5E94\u4E86\u8BF7\u6C42"
+]);
+const STEER_TEXT = "\u672C\u56DE\u5408\u81EA\u68C0\u5F97\u5206\u504F\u4F4E\uFF1A\u8BF7\u590D\u6838\u662F\u5426\u7B54\u5230\u4E86\u7528\u6237\u7684\u95EE\u9898\u3001\u6709\u65E0\u9057\u6F0F\u6216\u81EA\u76F8\u77DB\u76FE\uFF0C\u5E76\u5728\u9700\u8981\u65F6\u8865\u5B8C\u3002";
+function boundedRubric(rubric) {
+  if (!Array.isArray(rubric)) return DEFAULT_RUBRIC;
+  const levels = rubric.filter((item) => typeof item === "string" && Boolean(item.trim()) && item.length <= 256).slice(0, 10);
+  return levels.length >= 2 ? levels : DEFAULT_RUBRIC;
+}
+function scoreQuestion(output, rubric = DEFAULT_RUBRIC, context) {
+  return {
+    state: {
+      // What the turn was asked to do. Without it the model scores an answer
+      // against nothing and cannot detect an off-topic reply.
+      ...context?.request ? { request: context.request } : {},
+      ...context?.background?.length ? { background: context.background } : {},
+      answer: String(output).slice(0, MAX_OUTPUT)
+    },
+    questions: { quality: {
+      type: "score",
+      instructions: "\u6309\u4E0B\u5217\u4ECE\u4F4E\u5230\u9AD8\u7684\u6863\u4F4D\uFF0C\u8BC4\u4F30\u8FD9\u6B21\u6700\u7EC8\u4EA7\u51FA\u5BF9\u7528\u6237\u8BF7\u6C42\u7684\u5B8C\u6210\u8D28\u91CF\u3002",
+      criteria: boundedRubric(rubric)
+    } }
+  };
+}
+const DEFAULT_MIN_CONFIDENCE = 0.4;
+function createSelfCheck({ evaluate, sessions, steer, settings, minConfidence = DEFAULT_MIN_CONFIDENCE } = {}) {
+  if (typeof evaluate !== "function") throw new Error("Self-check requires an evaluator");
+  const steerOnce = createSteerOnce();
+  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;
+    const confidenceFloor = isProbability(raw?.minConfidence) ? raw.minConfidence : minConfidence;
+    const trendMinConfidence = typeof raw?.trendMinConfidence === "number" && Number.isFinite(raw.trendMinConfidence) && raw.trendMinConfidence >= 0 && raw.trendMinConfidence <= 1 ? raw.trendMinConfidence : 0.6;
+    const trendRun = Number.isSafeInteger(raw?.trendRun) && raw.trendRun >= 2 ? raw.trendRun : 3;
+    const trendSevereRun = Number.isSafeInteger(raw?.trendSevereRun) && raw.trendSevereRun > trendRun ? raw.trendSevereRun : Math.max(trendRun + 1, 5);
+    return { mode, rubric: boundedRubric(raw?.rubric), lowScoreThreshold, minConfidence: confidenceFloor, trendMinConfidence, trendRun, trendSevereRun };
+  };
+  const record = (turn, outcome, detail = {}, trend) => {
+    const id = turn?.agent?.session?.id;
+    if (!sessions || typeof id !== "string" || typeof sessions.recordCheck !== "function") return;
+    try {
+      sessions.recordCheck(id, outcome, trend);
+    } catch {
+    }
+    if (typeof sessions.log !== "function") return;
+    try {
+      sessions.log(id, { kind: "check", outcome, ...detail });
+    } catch {
+    }
+  };
+  return {
+    async review(turn) {
+      const output = typeof turn?.output === "string" ? turn.output.trim() : "";
+      if (!output) return { evaluated: false, lowScore: false, steered: false };
+      if (turn?.context !== void 0 && !turn.context.request) 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 task = taskExcerpt(turn?.context?.request ?? turn?.userText);
+      const taskDetail = task ? { task } : {};
+      if (Number.isSafeInteger(turn?.turn) && turn?.turn >= 0) taskDetail.turn = turn?.turn;
+      const { mode, rubric, lowScoreThreshold, minConfidence: confidenceFloor, trendMinConfidence, trendRun, trendSevereRun } = await resolveSettings();
+      let answer;
+      try {
+        const result = await evaluate(scoreQuestion(output, rubric, turn?.context), { signal: turn?.signal });
+        answer = result?.answers?.quality;
+      } catch (error) {
+        record(turn, "error", { ...taskDetail, reason: errorReason(error) });
+        return { evaluated: false, lowScore: false, steered: false };
+      }
+      if (!answer || answer.type !== "score" || typeof answer.score !== "number" || !Number.isFinite(answer.score)) {
+        record(turn, "error", { ...taskDetail, reason: "invalid-response" });
+        return { evaluated: false, lowScore: false, steered: false };
+      }
+      const confidence = typeof answer.confidence === "number" && Number.isFinite(answer.confidence) ? answer.confidence : void 0;
+      const detail = confidence === void 0 ? { ...taskDetail } : { ...taskDetail, confidence };
+      const lowScore = answer.score <= lowScoreThreshold;
+      const trend = { confident: lowScore && confidence !== void 0 && confidence >= trendMinConfidence, trendRun, trendSevereRun };
+      if (lowScore && confidence !== void 0 && !trend.confident) detail.lowConfidence = true;
+      record(turn, lowScore ? "low" : "ok", { score: answer.score, ...detail }, trend);
+      if (!lowScore) return { evaluated: true, lowScore: false, steered: false, score: answer.score };
+      const confident = confidence !== void 0 && confidence >= confidenceFloor;
+      const steered = mode === "steer" && confident && typeof steer === "function" && turn?.agent ? steerOnce.attempt(turn, () => steer(turn.agent, STEER_TEXT)) : false;
+      return { evaluated: true, lowScore: true, steered, score: answer.score };
+    }
+  };
+}
+export {
+  DEFAULT_MIN_CONFIDENCE,
+  DEFAULT_RUBRIC,
+  createSelfCheck,
+  scoreQuestion
+};

package/lib/host/session-state.d.ts

@@ -0,0 +1,19 @@
+import type { SessionSinkRow, SessionSnapshot, SessionState } from './types.js';
+export type SessionStateOptions = {
+    maxSessions?: number;
+    maxLogEntries?: number;
+    onLog?: (entry: SessionSinkRow) => void;
+    loadState?: (id: string) => Promise<unknown> | unknown;
+    persistState?: (id: string, state: SessionState) => unknown;
+};
+export declare function createSessionState({ maxSessions, maxLogEntries, onLog, loadState, persistState }?: SessionStateOptions): {
+    ensureLoaded(id: unknown): Promise<void>;
+    setEnabled(id: unknown, enabled: unknown): void;
+    snapshot(id: unknown): SessionSnapshot;
+    record(id: unknown, kind: string, outcome: string): void;
+    recordActual(id: unknown, outcome: string): void;
+    recordCheck(id: unknown, outcome: string, trend?: Record<string, unknown>): void;
+    recordNarrow(id: unknown, outcome: string, dropped?: number, applied?: boolean): void;
+    recordComplete(id: unknown, outcome: string, detail?: Record<string, unknown>): void;
+    log(id: unknown, entry: Record<string, unknown>): void;
+};