dsh-decision-layer 0.7.1 → 0.7.2

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,27 @@
+import type { AgentLike, CheckSettings, EvaluateInput, Evaluator, SessionsFace } from './types.js';
+export declare const DEFAULT_RUBRIC: readonly string[];
+export declare function scoreQuestion(output: unknown, rubric?: readonly string[]): EvaluateInput;
+export declare const DEFAULT_MIN_CONFIDENCE = 0.4;
+export type CheckTurn = {
+    agent?: AgentLike;
+    turn?: number;
+    signal?: AbortSignal;
+    output?: unknown;
+    userText?: unknown;
+};
+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,104 @@
+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) {
+  return {
+    state: { 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 };
+      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?.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), { 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;
+};

package/lib/host/session-state.js

@@ -0,0 +1,288 @@
+import { randomUUID } from "node:crypto";
+import { redactCredentials } from "./excerpt.js";
+import { advanceRun, severityOf } from "./quality-trend.js";
+const KINDS = ["gate", "check", "narrow", "complete"];
+const SEVERITIES = ["normal", "warn", "severe"];
+function sessionKey(value) {
+  if (typeof value !== "string" || !value.trim() || value.length > 512) throw new Error("Invalid session ID");
+  return value.trim();
+}
+function emptyCounters() {
+  return {
+    attempts: 0,
+    failures: 0,
+    gate: { attempts: 0, failures: 0, ask: 0, deny: 0, allow: 0, actual: { allow: 0, deny: 0, error: 0 } },
+    check: { attempts: 0, failures: 0, low: 0, run: 0, severity: "normal" },
+    narrow: { attempts: 0, failures: 0, applied: 0, dropped: 0 },
+    complete: { attempts: 0, failures: 0, unsatisfied: 0, satisfied: 0, insufficient: 0, steered: 0 },
+    log: []
+  };
+}
+function emptyState() {
+  return { enabled: true, ...emptyCounters() };
+}
+function safeTool(value) {
+  return typeof value === "string" && value.trim() ? value.trim().slice(0, 128) : void 0;
+}
+const toCount = (value) => Number.isSafeInteger(value) && value >= 0 ? value : 0;
+const asRecord = (value) => value && typeof value === "object" && !Array.isArray(value) ? value : void 0;
+function coerceState(raw) {
+  const state = emptyState();
+  const record = asRecord(raw);
+  if (!record) return state;
+  if (typeof record.enabled === "boolean") state.enabled = record.enabled;
+  state.attempts = toCount(record.attempts);
+  state.failures = toCount(record.failures);
+  const g = asRecord(record.gate);
+  if (g) {
+    state.gate.attempts = toCount(g.attempts);
+    state.gate.failures = toCount(g.failures);
+    state.gate.ask = toCount(g.ask);
+    state.gate.deny = toCount(g.deny);
+    state.gate.allow = toCount(g.allow);
+    const a = asRecord(g.actual);
+    if (a) {
+      state.gate.actual.allow = toCount(a.allow);
+      state.gate.actual.deny = toCount(a.deny);
+      state.gate.actual.error = toCount(a.error);
+    }
+  }
+  const c = asRecord(record.check);
+  if (c) {
+    state.check.attempts = toCount(c.attempts);
+    state.check.failures = toCount(c.failures);
+    state.check.low = toCount(c.low);
+    state.check.run = toCount(c.run);
+    state.check.severity = typeof c.severity === "string" && SEVERITIES.includes(c.severity) ? c.severity : "normal";
+  }
+  const n = asRecord(record.narrow);
+  if (n) {
+    state.narrow.attempts = toCount(n.attempts);
+    state.narrow.failures = toCount(n.failures);
+    state.narrow.applied = toCount(n.applied);
+    state.narrow.dropped = toCount(n.dropped);
+  }
+  const k = asRecord(record.complete);
+  if (k) {
+    state.complete.attempts = toCount(k.attempts);
+    state.complete.failures = toCount(k.failures);
+    state.complete.unsatisfied = toCount(k.unsatisfied);
+    state.complete.satisfied = toCount(k.satisfied);
+    state.complete.insufficient = toCount(k.insufficient);
+    state.complete.steered = toCount(k.steered);
+  }
+  if (Array.isArray(record.log)) {
+    state.log = record.log.filter((entry) => Boolean(asRecord(entry)) && typeof entry.kind === "string").map((entry) => ({ ...entry }));
+  }
+  return state;
+}
+function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loadState, persistState } = {}) {
+  if (!Number.isSafeInteger(maxSessions) || maxSessions < 1) throw new Error("Invalid session limit");
+  if (!Number.isSafeInteger(maxLogEntries) || maxLogEntries < 1) throw new Error("Invalid log limit");
+  const sessions = /* @__PURE__ */ new Map();
+  const sink = typeof onLog === "function" ? onLog : void 0;
+  const load = typeof loadState === "function" ? loadState : void 0;
+  const persist = typeof persistState === "function" ? persistState : void 0;
+  const loaded = /* @__PURE__ */ new Map();
+  const bump = (key, state) => {
+    if (persist) {
+      try {
+        persist(key, state);
+      } catch {
+      }
+    }
+  };
+  const writable = (id) => {
+    const key = sessionKey(id);
+    let state = sessions.get(key);
+    if (!state) {
+      if (sessions.size >= maxSessions) sessions.delete(sessions.keys().next().value);
+      state = emptyState();
+      sessions.set(key, state);
+    }
+    return state;
+  };
+  return {
+    // Rehydrate a session's live counters/log from the durable store the first
+    // time it is touched this process, before any new event mutates it — so disk
+    // history and in-process events never double-count. Memoized per id; a no-op
+    // when no loadState was given or the session already has live state. Callers
+    // should await this before the first snapshot/record of a resumed session
+    // (the plugin does so at the turn's first step and in the panel routes).
+    async ensureLoaded(id) {
+      if (!load) return;
+      let key;
+      try {
+        key = sessionKey(id);
+      } catch {
+        return;
+      }
+      const existing = loaded.get(key);
+      if (existing) return existing;
+      const promise = (async () => {
+        if (sessions.has(key)) return;
+        let raw;
+        try {
+          raw = await load(key);
+        } catch {
+          raw = void 0;
+        }
+        if (!raw) return;
+        if (sessions.has(key)) return;
+        const state = coerceState(raw);
+        if (state.log.length > maxLogEntries) state.log.splice(0, state.log.length - maxLogEntries);
+        if (sessions.size >= maxSessions) sessions.delete(sessions.keys().next().value);
+        sessions.set(key, state);
+      })();
+      if (loaded.size >= maxSessions) loaded.delete(loaded.keys().next().value);
+      loaded.set(key, promise);
+      return promise;
+    },
+    setEnabled(id, enabled) {
+      if (typeof enabled !== "boolean") throw new Error("Invalid enabled value");
+      const state = writable(id);
+      state.enabled = enabled;
+      bump(sessionKey(id), state);
+    },
+    snapshot(id) {
+      const stored = sessions.get(sessionKey(id));
+      const state = stored ?? emptyState();
+      const value = { enabled: state.enabled, hasAutomaticDecisions: state.attempts > 0, attempts: state.attempts, failures: state.failures };
+      if (state.gate.attempts > 0) value.gate = { ...state.gate, actual: { ...state.gate.actual } };
+      if (state.check.attempts > 0) value.check = { attempts: state.check.attempts, failures: state.check.failures, low: state.check.low, trend: { run: state.check.run, severity: state.check.severity } };
+      if (state.narrow.attempts > 0) value.narrow = { ...state.narrow };
+      if (state.complete.attempts > 0) value.complete = { ...state.complete };
+      if (state.log.length > 0) value.log = state.log.map((entry) => ({ ...entry }));
+      return value;
+    },
+    record(id, kind, outcome) {
+      if (kind !== "gate" || !["allow", "ask", "deny", "error"].includes(outcome)) throw new Error("Invalid automatic decision");
+      const state = writable(id);
+      state.attempts++;
+      state.gate.attempts++;
+      if (outcome === "error") {
+        state.failures++;
+        state.gate.failures++;
+      } else if (outcome === "allow") state.gate.allow++;
+      else if (outcome === "ask") state.gate.ask++;
+      else state.gate.deny++;
+      bump(sessionKey(id), state);
+    },
+    recordActual(id, outcome) {
+      if (!["allow", "deny", "error"].includes(outcome)) throw new Error("Invalid actual decision");
+      const state = writable(id);
+      const actual = state.gate.actual;
+      if (outcome === "allow") actual.allow++;
+      else if (outcome === "deny") actual.deny++;
+      else actual.error++;
+      bump(sessionKey(id), state);
+    },
+    recordCheck(id, outcome, trend) {
+      if (!["ok", "low", "error"].includes(outcome)) throw new Error("Invalid self-check outcome");
+      const state = writable(id);
+      const check = state.check;
+      state.attempts++;
+      check.attempts++;
+      if (outcome === "error") {
+        state.failures++;
+        check.failures++;
+      } else {
+        if (outcome === "low") check.low++;
+        if (trend && typeof trend === "object") {
+          check.run = advanceRun(check.run, { lowScore: outcome === "low", confident: trend.confident === true });
+          check.severity = severityOf(check.run, {
+            trendRun: typeof trend.trendRun === "number" ? trend.trendRun : void 0,
+            trendSevereRun: typeof trend.trendSevereRun === "number" ? trend.trendSevereRun : void 0
+          });
+        }
+      }
+      bump(sessionKey(id), state);
+    },
+    recordNarrow(id, outcome, dropped = 0, applied = outcome === "applied") {
+      if (!["ok", "applied", "error"].includes(outcome)) throw new Error("Invalid narrowing outcome");
+      const state = writable(id);
+      const narrow = state.narrow;
+      state.attempts++;
+      narrow.attempts++;
+      if (outcome === "error") {
+        state.failures++;
+        narrow.failures++;
+      } else if (outcome === "applied") {
+        if (applied) narrow.applied++;
+        if (Number.isSafeInteger(dropped) && dropped > 0) narrow.dropped += dropped;
+      }
+      bump(sessionKey(id), state);
+    },
+    // Task-completion checking. `ok`/`unsatisfied` are real evaluations; `error`
+    // is an unevaluated failure counted as a failure, never as "unsatisfied".
+    // The per-condition three-state tallies come from `detail`.
+    recordComplete(id, outcome, detail = {}) {
+      if (!["ok", "unsatisfied", "error"].includes(outcome)) throw new Error("Invalid task-completion outcome");
+      const state = writable(id);
+      const complete = state.complete;
+      state.attempts++;
+      complete.attempts++;
+      if (outcome === "error") {
+        state.failures++;
+        complete.failures++;
+      } else {
+        if (Number.isSafeInteger(detail.satisfied) && detail.satisfied > 0) complete.satisfied += detail.satisfied;
+        if (Number.isSafeInteger(detail.unsatisfied) && detail.unsatisfied > 0) complete.unsatisfied += detail.unsatisfied;
+        if (Number.isSafeInteger(detail.insufficient) && detail.insufficient > 0) complete.insufficient += detail.insufficient;
+        if (detail.steered === true) complete.steered++;
+      }
+      bump(sessionKey(id), state);
+    },
+    log(id, entry) {
+      if (entry === null || typeof entry !== "object" || Array.isArray(entry)) throw new Error("Invalid log entry");
+      const kind = entry.kind;
+      if (typeof kind !== "string" || !KINDS.includes(kind)) throw new Error("Invalid log entry");
+      const record = { id: randomUUID(), at: Date.now(), kind, outcome: typeof entry.outcome === "string" ? entry.outcome.slice(0, 32) : "" };
+      const tool = safeTool(entry.tool);
+      if (tool) record.tool = tool;
+      if (typeof entry.suggestion === "string" && entry.suggestion) record.suggestion = entry.suggestion.slice(0, 16);
+      if (typeof entry.action === "string" && entry.action) record.action = entry.action.slice(0, 16);
+      if (typeof entry.reason === "string" && entry.reason) record.reason = entry.reason.slice(0, 32);
+      if (typeof entry.subject === "string" && entry.subject.trim()) record.subject = redactCredentials(entry.subject).replace(/\s+/g, " ").trim().slice(0, 120);
+      if (typeof entry.command === "string" && entry.command.trim()) record.command = entry.command.replace(/\s+/g, " ").trim().slice(0, 512);
+      if (typeof entry.path === "string" && entry.path.trim()) record.path = entry.path.replace(/\s+/g, " ").trim().slice(0, 512);
+      if (typeof entry.task === "string" && entry.task.trim()) record.task = redactCredentials(entry.task).replace(/\s+/g, " ").trim().slice(0, 512);
+      if (Number.isSafeInteger(entry.turn) && entry.turn >= 0) record.turn = entry.turn;
+      if (typeof entry.mode === "string" && entry.mode) record.mode = entry.mode.slice(0, 16);
+      if (typeof entry.score === "number" && Number.isFinite(entry.score)) record.score = Math.round(entry.score * 100) / 100;
+      if (typeof entry.confidence === "number" && Number.isFinite(entry.confidence)) record.confidence = Math.round(entry.confidence * 100) / 100;
+      if (Number.isSafeInteger(entry.dropped) && entry.dropped >= 0) record.dropped = entry.dropped;
+      if (Number.isSafeInteger(entry.kept) && entry.kept >= 0) record.kept = entry.kept;
+      if (typeof entry.applied === "boolean") record.applied = entry.applied;
+      if (Number.isSafeInteger(entry.candidates) && entry.candidates >= 0) record.candidates = entry.candidates;
+      if (Number.isSafeInteger(entry.conditions) && entry.conditions >= 0) record.conditions = entry.conditions;
+      if (Number.isSafeInteger(entry.satisfied) && entry.satisfied >= 0) record.satisfied = entry.satisfied;
+      if (Number.isSafeInteger(entry.unsatisfied) && entry.unsatisfied >= 0) record.unsatisfied = entry.unsatisfied;
+      if (Number.isSafeInteger(entry.insufficient) && entry.insufficient >= 0) record.insufficient = entry.insufficient;
+      if (entry.steered === true) record.steered = true;
+      if (entry.lowConfidence === true) record.lowConfidence = true;
+      if (Array.isArray(entry.tools)) {
+        const names = entry.tools.filter((name) => typeof name === "string" && Boolean(name.trim())).slice(0, 12).map((name) => name.trim().slice(0, 64));
+        if (names.length > 0) record.tools = names;
+      }
+      const state = writable(id);
+      state.log.push(record);
+      if (state.log.length > maxLogEntries) state.log.splice(0, state.log.length - maxLogEntries);
+      if (sink) {
+        const full = { ...record, sessionId: sessionKey(id) };
+        if (Array.isArray(entry.tools)) {
+          const allNames = entry.tools.filter((name) => typeof name === "string" && Boolean(name.trim())).map((name) => name.trim());
+          if (allNames.length > 0) full.tools = allNames;
+        }
+        try {
+          sink(full);
+        } catch {
+        }
+      }
+      bump(sessionKey(id), state);
+    }
+  };
+}
+export {
+  createSessionState
+};

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

@@ -0,0 +1,14 @@
+export declare function stateDir(): string;
+export declare function safeStateId(id: unknown): string | undefined;
+export type StateStoreOptions = {
+    dir?: string;
+    flushIntervalMs?: number;
+    retentionDays?: number;
+    now?: () => number;
+};
+export declare function createStateStore({ dir, flushIntervalMs, retentionDays, now }?: StateStoreOptions): {
+    load(id: unknown): Promise<Record<string, unknown> | undefined>;
+    save(id: unknown, state: unknown): void;
+    flush: () => Promise<void>;
+    dispose(): Promise<void>;
+};

package/lib/host/state-store.js

@@ -0,0 +1,109 @@
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { isObject } from "./types.js";
+function stateDir() {
+  return join(homedir(), ".config", "dsh-decision-layer", "state");
+}
+const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/;
+function safeStateId(id) {
+  return typeof id === "string" && SAFE_ID.test(id) && !id.includes("..") ? id : void 0;
+}
+function createStateStore({
+  dir = stateDir(),
+  flushIntervalMs = 2e3,
+  retentionDays = 30,
+  now = () => Date.now()
+} = {}) {
+  const pending = /* @__PURE__ */ new Map();
+  let timer;
+  let flushing = false;
+  let lastPrune = 0;
+  const fileFor = (id) => join(dir, `${id}.json`);
+  const writeOne = async (id, state) => {
+    const temporary = join(dir, `${id}.${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, `${JSON.stringify({ v: 1, at: now(), state })}
+`, { mode: 384, flag: "wx" });
+      await rename(temporary, fileFor(id));
+    } finally {
+      await rm(temporary, { force: true }).catch(() => {
+      });
+    }
+  };
+  const prune = async () => {
+    let names;
+    try {
+      names = await readdir(dir);
+    } catch {
+      return;
+    }
+    const cutoff = now() - retentionDays * 24 * 60 * 60 * 1e3;
+    await Promise.all(names.map(async (name) => {
+      if (!name.endsWith(".json")) return;
+      try {
+        const info = await stat(join(dir, name));
+        if (info.mtimeMs < cutoff) await rm(join(dir, name), { force: true }).catch(() => {
+        });
+      } catch {
+      }
+    }));
+  };
+  const flush = async () => {
+    if (flushing || pending.size === 0) return;
+    flushing = true;
+    const batch = [...pending.entries()];
+    pending.clear();
+    try {
+      await mkdir(dir, { recursive: true, mode: 448 });
+      for (const [id, state] of batch) await writeOne(id, state).catch(() => {
+      });
+      if (now() - lastPrune > 60 * 60 * 1e3) {
+        lastPrune = now();
+        await prune();
+      }
+    } catch {
+    } finally {
+      flushing = false;
+    }
+  };
+  return {
+    // Read a session's persisted state, or undefined when there is no usable file.
+    async load(id) {
+      const safe = safeStateId(id);
+      if (!safe) return void 0;
+      try {
+        const parsed = JSON.parse(await readFile(fileFor(safe), "utf8"));
+        if (isObject(parsed) && isObject(parsed.state)) {
+          return parsed.state;
+        }
+      } catch {
+      }
+      return void 0;
+    },
+    // Register the latest live state for a session and schedule a debounced flush.
+    save(id, state) {
+      const safe = safeStateId(id);
+      if (!safe || state === null || typeof state !== "object" || Array.isArray(state)) return;
+      pending.set(safe, state);
+      if (!timer) timer = setTimeout(() => {
+        timer = void 0;
+        void flush();
+      }, flushIntervalMs);
+    },
+    flush,
+    dispose() {
+      if (timer) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      return flush();
+    }
+  };
+}
+export {
+  createStateStore,
+  safeStateId,
+  stateDir
+};

package/lib/host/steer-once.d.ts

@@ -0,0 +1,13 @@
+export type SteerTurn = {
+    agent?: {
+        session?: {
+            id?: string;
+        };
+    };
+    turn?: number;
+};
+export declare function createSteerOnce({ maxTurns }?: {
+    maxTurns?: number;
+}): {
+    attempt(turn: SteerTurn | undefined, run: () => void): boolean;
+};

package/lib/host/steer-once.js

@@ -0,0 +1,25 @@
+function createSteerOnce({ maxTurns = 4096 } = {}) {
+  const steeredTurns = /* @__PURE__ */ new Set();
+  const keyOf = (turn) => {
+    const id = turn?.agent?.session?.id;
+    const index = turn?.turn;
+    return typeof id === "string" && Number.isInteger(index) ? `${id}:${index}` : void 0;
+  };
+  return {
+    attempt(turn, run) {
+      const key = keyOf(turn);
+      if (key === void 0 || steeredTurns.has(key)) return false;
+      try {
+        run();
+      } catch {
+        return false;
+      }
+      steeredTurns.add(key);
+      if (steeredTurns.size > maxTurns) steeredTurns.delete(steeredTurns.values().next().value);
+      return true;
+    }
+  };
+}
+export {
+  createSteerOnce
+};

package/lib/host/task-completion.d.ts

@@ -0,0 +1,29 @@
+import type { AgentLike, CompleteSettings, EvaluateInput, Evaluator, SessionsFace } from './types.js';
+export declare function extractConditions(userText: unknown): string[];
+export declare function completionQuestions(conditions: unknown, evidence: unknown, answer: unknown): EvaluateInput;
+export declare const DEFAULT_MIN_CONFIDENCE = 0.4;
+export type CompletionTurn = {
+    agent?: AgentLike;
+    turn?: number;
+    signal?: AbortSignal;
+    output?: unknown;
+    userText?: unknown;
+    evidence?: unknown;
+};
+export type CompletionResult = {
+    evaluated: boolean;
+    steered: boolean;
+    satisfied?: number;
+    unsatisfied?: number;
+    insufficient?: number;
+};
+export type TaskCompletionOptions = {
+    evaluate?: Evaluator;
+    sessions?: SessionsFace;
+    steer?: (agent: AgentLike, text: string) => unknown;
+    settings?: CompleteSettings | (() => Promise<CompleteSettings | undefined>);
+    minConfidence?: number;
+};
+export declare function createTaskCompletion({ evaluate, sessions, steer, settings, minConfidence }?: TaskCompletionOptions): {
+    review(turn: CompletionTurn | undefined): Promise<CompletionResult>;
+};