dsh-decision-layer 0.7.1 → 0.7.2

package/lib/host/log-read.js

@@ -0,0 +1,34 @@
+import { createReadStream } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { createInterface } from "node:readline";
+import { join } from "node:path";
+import { logsDir } from "./log-store.js";
+async function* createReadableStream({ dir = logsDir(), port } = {}) {
+  const prefix = Number.isInteger(port) && port > 0 ? `decisions-${port}-` : "decisions-";
+  let names;
+  try {
+    names = await readdir(dir);
+  } catch {
+    return;
+  }
+  const files = names.filter((name) => name.startsWith(prefix) && name.endsWith(".jsonl")).sort();
+  for (const name of files) {
+    const stream = createReadStream(join(dir, name), { encoding: "utf8" });
+    const lines = createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of lines) {
+        if (!line.trim()) continue;
+        try {
+          yield JSON.parse(line);
+        } catch {
+        }
+      }
+    } finally {
+      lines.close();
+      stream.close();
+    }
+  }
+}
+export {
+  createReadableStream
+};

package/lib/host/log-store.d.ts

@@ -0,0 +1,15 @@
+export declare function logsDir(): string;
+export type LogStoreOptions = {
+    port?: number;
+    dir?: string;
+    flushIntervalMs?: number;
+    maxBuffer?: number;
+    retentionDays?: number;
+    now?: () => Date;
+};
+export declare function createLogStore({ port, dir, flushIntervalMs, maxBuffer, retentionDays, now }?: LogStoreOptions): {
+    append(entry: unknown): void;
+    appendAnnotation(entry: Record<string, unknown>): Promise<Record<string, unknown>>;
+    flush: () => Promise<void>;
+    dispose(): Promise<void>;
+};

package/lib/host/log-store.js

@@ -0,0 +1,98 @@
+import { mkdir, appendFile, readdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function logsDir() {
+  return join(homedir(), ".config", "dsh-decision-layer", "logs");
+}
+const dayStamp = (date) => date.toISOString().slice(0, 10);
+function createLogStore({
+  port,
+  dir = logsDir(),
+  flushIntervalMs = 5e3,
+  maxBuffer = 200,
+  retentionDays = 30,
+  now = () => /* @__PURE__ */ 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 * 1e3;
+    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: 448 });
+      const byFile = /* @__PURE__ */ 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)}
+`);
+      }
+      for (const [file, lines] of byFile) await appendFile(file, lines.join(""), { mode: 384 });
+      await prune();
+    } catch {
+    } 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 = void 0;
+        void flush();
+      }, flushIntervalMs);
+    },
+    // An annotation is an explicit user action, not telemetry: write it
+    // immediately (not batched) and surface failure to the caller instead of
+    // dropping it. It lands in the same JSONL directory as a `kind:"annotation"`
+    // event and is pruned with the decision logs on the next flush.
+    async appendAnnotation(entry) {
+      if (entry === null || typeof entry !== "object") throw new Error("Invalid annotation");
+      const at = Number.isFinite(entry.at) ? entry.at : now().getTime();
+      const record = { ...entry, at };
+      await mkdir(dir, { recursive: true, mode: 448 });
+      await appendFile(fileFor(new Date(at)), `${JSON.stringify(record)}
+`, { mode: 384 });
+      return record;
+    },
+    flush,
+    dispose() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      return flush();
+    }
+  };
+}
+export {
+  createLogStore,
+  logsDir
+};

package/lib/host/loop-guard.d.ts

@@ -0,0 +1,10 @@
+import type { SessionsFace, ToolExec } from './types.js';
+export declare function fingerprintCall(exec: ToolExec | undefined): string;
+export declare function createLoopGuard({ threshold, maxSessions, sessions }?: {
+    threshold?: number;
+    maxSessions?: number;
+    sessions?: SessionsFace;
+}): {
+    check(exec: ToolExec | undefined): string | undefined;
+    runLength(id: string): number;
+};

package/lib/host/loop-guard.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+const MAX_FINGERPRINT_INPUT = 16 * 1024;
+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");
+}
+function createLoopGuard({ threshold = 3, maxSessions = 1024, sessions } = {}) {
+  if (!Number.isSafeInteger(threshold) || threshold < 2) throw new Error("Invalid loop threshold");
+  const runs = /* @__PURE__ */ new Map();
+  const runFor = (id) => {
+    let run = runs.get(id);
+    if (!run) {
+      if (runs.size >= maxSessions) runs.delete(runs.keys().next().value);
+      run = { key: void 0, count: 0 };
+      runs.set(id, run);
+    }
+    return run;
+  };
+  return {
+    check(exec) {
+      const id = exec?.agent?.session?.id;
+      if (typeof id !== "string") return void 0;
+      if (sessions) {
+        try {
+          if (sessions.snapshot(id).enabled === false) return void 0;
+        } catch {
+        }
+      }
+      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 void 0;
+    },
+    runLength(id) {
+      return runs.get(id)?.count ?? 0;
+    }
+  };
+}
+export {
+  createLoopGuard,
+  fingerprintCall
+};

package/lib/host/manager-api.d.ts

@@ -0,0 +1,20 @@
+import type { Evaluator, ManagerRoute, SessionsFace } from './types.js';
+export declare const API_PREFIX = "/plugins/dsh-decision-layer/api";
+export type ManagerRouteDeps = {
+    path?: string;
+    sessions: SessionsFace;
+    backend: {
+        evaluate: Evaluator;
+    };
+    logStore?: {
+        appendAnnotation: (entry: Record<string, unknown>) => Promise<unknown>;
+    };
+    analyze?: (id: string) => Promise<unknown>;
+    listRows?: (id: string, options: {
+        page: number;
+        pageSize: number;
+    }) => Promise<unknown>;
+    env?: Record<string, string | undefined>;
+    bindHost?: string;
+};
+export declare function createManagerRoutes({ path, sessions, backend, logStore, analyze, listRows, env, bindHost }: ManagerRouteDeps): ManagerRoute[];

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,48 @@
+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;
+    signal?: AbortSignal;
+    state?: 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,213 @@
+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?.state);
+      const context = task ? { task } : {};
+      if (Number.isSafeInteger(turn?.turn) && turn?.turn >= 0) context.turn = turn?.turn;
+      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?.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;