dsh-decision-layer 0.7.4 → 0.7.5

package/lib/host/narrowing.js

@@ -1,3 +1,4 @@
+import { createEvaluationTrace } from "./evaluation-trace.js";
 import { taskExcerpt } from "./excerpt.js";
 import { errorReason, isObject, isProbability } from "./types.js";
 const narrowApplied = (record) => {
@@ -114,14 +115,14 @@ function createNarrowing({
     } catch {
     }
   };
-  const evaluateSplit = async (state, tools, signal) => {
+  const evaluateSplit = async (evaluate2, 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 reply = await evaluate2(relevanceQuestions(state, [tool]), { signal });
           const answer = reply?.answers?.[tool.name];
           return isObject(answer) ? [tool.name, answer] : void 0;
         } catch {
@@ -161,28 +162,29 @@ function createNarrowing({
       const effectiveMode = overCap ? "observe" : mode;
       const judged = overCap ? optional.slice(0, cap) : optional;
       const judgedNames = judged.map((tool) => tool.name);
+      const trace = createEvaluationTrace(evaluate);
       let result = null;
       if (batchMode === "split" || adaptiveSplit) {
-        result = await evaluateSplit(turn?.state, judged, turn?.signal);
+        result = await evaluateSplit(trace.evaluate, turn?.state, judged, turn?.signal);
         if (!result) {
-          record(turn, "error", { reason: "unreachable", mode: effectiveMode });
+          record(turn, "error", { ...trace.detail(), reason: "unreachable", mode: effectiveMode });
           return { ...skip, keep: names, mode: effectiveMode };
         }
       } else {
         try {
-          const reply = await evaluate(relevanceQuestions(turn?.state, judged), { signal: turn?.signal });
+          const reply = await trace.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);
+            result = await evaluateSplit(trace.evaluate, turn?.state, judged, turn?.signal);
             if (!result) {
-              record(turn, "error", { reason, mode: effectiveMode });
+              record(turn, "error", { ...trace.detail(), reason, mode: effectiveMode });
               return { ...skip, keep: names, mode: effectiveMode };
             }
           } else {
-            record(turn, "error", { reason, mode: effectiveMode });
+            record(turn, "error", { ...trace.detail(), reason, mode: effectiveMode });
             return { ...skip, keep: names, mode: effectiveMode };
           }
         }
@@ -198,7 +200,7 @@ function createNarrowing({
         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);
+      record(turn, dropped > 0 ? "applied" : "ok", { ...detail, ...trace.detail() });
       return { evaluated: true, applied, keep, drop, mode: effectiveMode, overCap, trustworthy };
     }
   };

package/lib/host/self-check.js

@@ -1,3 +1,4 @@
+import { createEvaluationTrace } from "./evaluation-trace.js";
 import { taskExcerpt } from "./excerpt.js";
 import { createSteerOnce } from "./steer-once.js";
 import { errorReason, isProbability } from "./types.js";
@@ -90,16 +91,17 @@ function createSelfCheck({ evaluate, sessions, steer, settings, minConfidence =
       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();
+      const trace = createEvaluationTrace(evaluate);
       let answer;
       try {
-        const result = await evaluate(scoreQuestion(output, rubric, turn?.context), { signal: turn?.signal });
+        const result = await trace.evaluate(scoreQuestion(output, rubric, turn?.context), { signal: turn?.signal });
         answer = result?.answers?.quality;
       } catch (error) {
-        record(turn, "error", { ...taskDetail, reason: errorReason(error) });
+        record(turn, "error", { ...taskDetail, ...trace.detail(), 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" });
+        record(turn, "error", { ...taskDetail, ...trace.detail(), reason: "invalid-response" });
         return { evaluated: false, lowScore: false, steered: false };
       }
       const confidence = typeof answer.confidence === "number" && Number.isFinite(answer.confidence) ? answer.confidence : void 0;
@@ -107,10 +109,13 @@ function createSelfCheck({ evaluate, sessions, steer, settings, minConfidence =
       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 };
+      if (!lowScore) {
+        record(turn, "ok", { score: answer.score, ...detail, ...trace.detail(), steered: false }, trend);
+        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;
+      record(turn, "low", { score: answer.score, ...detail, ...trace.detail(), steered }, trend);
       return { evaluated: true, lowScore: true, steered, score: answer.score };
     }
   };

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

@@ -5,8 +5,9 @@ export type SessionStateOptions = {
     onLog?: (entry: SessionSinkRow) => void;
     loadState?: (id: string) => Promise<unknown> | unknown;
     persistState?: (id: string, state: SessionState) => unknown;
+    onEnabled?: (id: string, enabled: boolean) => void;
 };
-export declare function createSessionState({ maxSessions, maxLogEntries, onLog, loadState, persistState }?: SessionStateOptions): {
+export declare function createSessionState({ maxSessions, maxLogEntries, onLog, loadState, persistState, onEnabled }?: SessionStateOptions): {
     ensureLoaded(id: unknown): Promise<void>;
     setEnabled(id: unknown, enabled: unknown): void;
     snapshot(id: unknown): SessionSnapshot;
@@ -15,5 +16,6 @@ export declare function createSessionState({ maxSessions, maxLogEntries, onLog,
     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;
+    recordCheckpoint(id: unknown, outcome: string): void;
     log(id: unknown, entry: Record<string, unknown>): void;
 };

package/lib/host/session-state.js

@@ -1,7 +1,6 @@
 import { randomUUID } from "node:crypto";
-import { redactCredentials } from "./excerpt.js";
+import { sanitizeLogRow } from "./log-row.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");
@@ -15,15 +14,13 @@ function emptyCounters() {
     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 },
+    checkpoint: { attempts: 0, failures: 0, concern: 0, uncertain: 0, skipped: 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) {
@@ -71,12 +68,12 @@ function coerceState(raw) {
     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 }));
-  }
+  const cp = asRecord(record.checkpoint);
+  if (cp) for (const key of ["attempts", "failures", "concern", "uncertain", "skipped"]) state.checkpoint[key] = toCount(cp[key]);
+  if (Array.isArray(record.log)) state.log = record.log.map(sanitizeLogRow).filter((row) => Boolean(row));
   return state;
 }
-function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loadState, persistState } = {}) {
+function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loadState, persistState, onEnabled } = {}) {
   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();
@@ -142,6 +139,10 @@ function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loa
       if (typeof enabled !== "boolean") throw new Error("Invalid enabled value");
       const state = writable(id);
       state.enabled = enabled;
+      try {
+        onEnabled?.(sessionKey(id), enabled);
+      } catch {
+      }
       bump(sessionKey(id), state);
     },
     snapshot(id) {
@@ -152,6 +153,7 @@ function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loa
       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.checkpoint.attempts > 0 || state.checkpoint.skipped > 0) value.checkpoint = { ...state.checkpoint };
       if (state.log.length > 0) value.log = state.log.map((entry) => ({ ...entry }));
       return value;
     },
@@ -233,48 +235,30 @@ function createSessionState({ maxSessions = 1024, maxLogEntries = 50, onLog, loa
       }
       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 (Number.isSafeInteger(entry.step) && entry.step >= 0) record.step = entry.step;
-      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;
+    recordCheckpoint(id, outcome) {
+      if (!["ok", "concern", "uncertain", "error", "skipped"].includes(outcome)) throw new Error("Invalid checkpoint outcome");
+      const state = writable(id);
+      const checkpoint = state.checkpoint;
+      if (outcome === "skipped") checkpoint.skipped++;
+      else {
+        checkpoint.attempts++;
+        if (outcome === "error") checkpoint.failures++;
+        else if (outcome === "concern") checkpoint.concern++;
+        else if (outcome === "uncertain") checkpoint.uncertain++;
       }
+      bump(sessionKey(id), state);
+    },
+    log(id, entry) {
+      const sanitized = sanitizeLogRow(entry);
+      if (!sanitized) throw new Error("Invalid log entry");
+      const fullRow = { ...sanitized, id: randomUUID(), at: Date.now() };
+      const record = { ...fullRow };
+      if (record.tools) record.tools = record.tools.slice(0, 12).map((name) => name.slice(0, 64));
       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;
-        }
+        const full = { ...fullRow, sessionId: sessionKey(id) };
         try {
           sink(full);
         } catch {

package/lib/host/task-completion.js

@@ -1,3 +1,4 @@
+import { createEvaluationTrace } from "./evaluation-trace.js";
 import { taskExcerpt } from "./excerpt.js";
 import { createSteerOnce } from "./steer-once.js";
 import { errorReason, isObject, isProbability } from "./types.js";
@@ -122,16 +123,17 @@ function createTaskCompletion({ evaluate, sessions, steer, settings, minConfiden
           return { ...skip };
         }
       }
+      const trace = createEvaluationTrace(evaluate);
       let answers;
       try {
-        const result = await evaluate(completionQuestions(conditions, evidence, output, turn?.context), { signal: turn?.signal });
+        const result = await trace.evaluate(completionQuestions(conditions, evidence, output, turn?.context), { signal: turn?.signal });
         answers = isObject(result?.answers) ? result.answers : void 0;
       } catch (error) {
-        record(turn, "error", { ...taskDetail, reason: errorReason(error) });
+        record(turn, "error", { ...taskDetail, ...trace.detail(), reason: errorReason(error) });
         return { ...skip };
       }
       if (!answers) {
-        record(turn, "error", { ...taskDetail, reason: "invalid-response" });
+        record(turn, "error", { ...taskDetail, ...trace.detail(), reason: "invalid-response" });
         return { ...skip };
       }
       let satisfied = 0, unsatisfied = 0, insufficient = 0;
@@ -153,7 +155,7 @@ function createTaskCompletion({ evaluate, sessions, steer, settings, minConfiden
       const confident = unsatisfied > 0 && unsatisfiedMinConf >= confidenceFloor;
       const steered = mode === "steer" && confident && typeof steer === "function" && turn?.agent ? steerOnce.attempt(turn, () => steer(turn.agent, STEER_TEXT)) : false;
       if (steered) detail.steered = true;
-      record(turn, outcome, detail);
+      record(turn, outcome, { ...detail, ...trace.detail(), steered });
       return { evaluated: true, steered, satisfied, unsatisfied, insufficient };
     }
   };

package/lib/host/types.d.ts

@@ -55,13 +55,24 @@ export type ChoiceAnswer = ScoredAnswer & {
 };
 export type Answer = NoulAnswer | ScoreAnswer | ChoiceAnswer;
 export type AnswerMap = Record<string, Answer>;
+export type EvaluationTelemetry = {
+    requestId: string;
+    latencyMs: number;
+    requestBytes?: number;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    backendAttempts?: number;
+};
 export type EvaluateResult = {
     model: string;
     answers: AnswerMap;
     usage?: {
-        input_tokens: number;
-        output_tokens: number;
+        input_tokens?: number;
+        output_tokens?: number;
     };
+    /** Local measurement only; never part of the backend wire request. */
+    telemetry?: EvaluationTelemetry;
 };
 export type Evaluator = (input: EvaluateInput, options?: {
     signal?: AbortSignal;
@@ -102,6 +113,19 @@ export type NarrowSettings = {
     maxCandidates?: number;
     batchMode?: BatchMode;
 };
+export type CheckpointSettings = {
+    enabled?: boolean;
+    heartbeatSteps?: number;
+    failureThreshold?: number;
+    timeoutMs?: number;
+};
+export type CheckpointTrigger = 'heartbeat' | 'unresolved_failure' | 'verification_after_change';
+export type CheckpointOutcome = 'ok' | 'concern' | 'uncertain' | 'error' | 'skipped';
+export type CheckpointCounters = SessionCounters & {
+    concern: number;
+    uncertain: number;
+    skipped: number;
+};
 export type CompleteSettings = {
     mode?: CheckMode;
     minConditions?: number;
@@ -126,6 +150,7 @@ export type ResolvedConfig = {
     checkSettings?: CheckSettings;
     narrowSettings?: NarrowSettings;
     completeSettings?: CompleteSettings;
+    checkpointSettings?: CheckpointSettings;
     features?: Features;
 };
 /** What the config page may read back: the API key is reduced to a flag. */
@@ -139,6 +164,7 @@ export type ConfigView = {
     checkSettings?: CheckSettings;
     narrowSettings?: NarrowSettings;
     completeSettings?: CompleteSettings;
+    checkpointSettings?: CheckpointSettings;
     features?: Features;
 };
 /** The quality-trend knobs, shared by the live path and the log backtest. */
@@ -148,7 +174,7 @@ export type TrendConfig = {
     trendSevereRun?: number;
     lowScoreThreshold?: number;
 };
-export type LogKind = 'gate' | 'check' | 'narrow' | 'complete';
+export type LogKind = 'gate' | 'check' | 'narrow' | 'complete' | 'checkpoint';
 /**
  * One decision-log row. Fields are optional because rows are also read back
  * from disk: persisted snapshots are untrusted input, and only `kind` is
@@ -183,6 +209,17 @@ export type LogRow = {
     steered?: boolean;
     lowConfidence?: boolean;
     tools?: string[];
+    trigger?: CheckpointTrigger;
+    throughSeq?: number;
+    evidenceCount?: number;
+    requestId?: string;
+    latencyMs?: number;
+    requestBytes?: number;
+    model?: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    backendAttempts?: number;
+    callId?: string;
 };
 /** The research-log sink record: the panel row plus its session tag. */
 export type SessionSinkRow = LogRow & {
@@ -226,6 +263,7 @@ export type SessionState = {
     check: CheckCounters;
     narrow: NarrowCounters;
     complete: CompleteCounters;
+    checkpoint: CheckpointCounters;
     log: LogRow[];
 };
 /** The panel-facing projection; sections without attempts are omitted. */
@@ -246,6 +284,7 @@ export type SessionSnapshot = {
     };
     narrow?: NarrowCounters;
     complete?: CompleteCounters;
+    checkpoint?: CheckpointCounters;
     log?: LogRow[];
 };
 /** The counter shape rebuilt from persisted JSONL, without the master switch. */
@@ -262,6 +301,7 @@ export type SessionsFace = {
     recordCheck?: (id: string, outcome: string, trend?: Record<string, unknown>) => void;
     recordNarrow?: (id: string, outcome: string, dropped: number, applied: boolean) => void;
     recordComplete?: (id: string, outcome: string, detail?: Record<string, unknown>) => void;
+    recordCheckpoint?: (id: string, outcome: CheckpointOutcome) => void;
     ensureLoaded?: (id: string) => Promise<unknown>;
     setEnabled?: (id: string, enabled: boolean) => void;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-decision-layer",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "A structured decision layer for the DeepSeek Harness agent loop: a danger-call gate, output self-check, tool narrowing, and loop guard backed by a pluggable adjudication model.",
   "keywords": [
     "dsh",