dsh-decision-layer 0.7.1 → 0.7.3

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

@@ -0,0 +1,121 @@
+import type { LogRow, SessionSeed, TrendConfig } from './types.js';
+export type PersistedRecord = Record<string, unknown>;
+export type Annotation = {
+    rating?: unknown;
+    at: number;
+};
+export type TrendBacktest = {
+    warnHits: number;
+    severeHits: number;
+    maxRun: number;
+};
+export declare function foldSession(records: Iterable<unknown>): {
+    decisions: Map<string, PersistedRecord>;
+    annotations: Map<string, Annotation>;
+};
+export type Profile = {
+    gate: {
+        attempts: number;
+        allow: number;
+        ask: number;
+        deny: number;
+        error: number;
+    };
+    check: {
+        attempts: number;
+        ok: number;
+        low: number;
+        error: number;
+        scoreSum: number;
+        scoreCount: number;
+        confidence: {
+            lt40: number;
+            lt60: number;
+            lt80: number;
+            gte80: number;
+        };
+    };
+    narrow: {
+        attempts: number;
+        applied: number;
+        error: number;
+        droppedSum: number;
+        tooManyCandidates: number;
+    };
+    complete: {
+        attempts: number;
+        satisfied: number;
+        unsatisfied: number;
+        insufficient: number;
+        error: number;
+        steered: number;
+    };
+};
+export declare function buildProfile(decisions: ReadonlyMap<string, PersistedRecord> | Iterable<PersistedRecord>): Profile;
+export declare function backtestTrend(checkRecords: Iterable<unknown>, { trendMinConfidence, trendRun, trendSevereRun, lowScoreThreshold }?: TrendConfig): TrendBacktest;
+export declare function annotationSummary(decisions: ReadonlyMap<string, PersistedRecord>, annotations: ReadonlyMap<string, Annotation>): {
+    summary: {
+        rated: number;
+        good: number;
+        bad: number;
+        unsure: number;
+    };
+    ratings: Record<string, unknown>;
+};
+export declare function analyzeSession(records: Iterable<unknown>, trendConfig?: TrendConfig): {
+    totalDecisions: number;
+    profile: Profile;
+    trendBacktest: TrendBacktest;
+    annotations: {
+        rated: number;
+        good: number;
+        bad: number;
+        unsure: number;
+    };
+    ratings: Record<string, unknown>;
+};
+export type ReadStream = (options: {
+    dir?: string;
+    port?: number;
+}) => AsyncIterable<unknown>;
+export declare function analyzeSessionLogs(sessionId: unknown, { dir, port, trendConfig, readStream }?: {
+    dir?: string;
+    port?: number;
+    trendConfig?: TrendConfig;
+    readStream?: ReadStream;
+}): Promise<{
+    totalDecisions: number;
+    profile: Profile;
+    trendBacktest: TrendBacktest;
+    annotations: {
+        rated: number;
+        good: number;
+        bad: number;
+        unsure: number;
+    };
+    ratings: Record<string, unknown>;
+}>;
+export declare function buildSeed(decisions: ReadonlyMap<string, PersistedRecord>, { maxLog, trendConfig }?: {
+    maxLog?: number;
+    trendConfig?: TrendConfig;
+}): SessionSeed;
+export declare function reconstructSessionSeed(sessionId: unknown, { dir, port, trendConfig, maxLog, readStream }?: {
+    dir?: string;
+    port?: number;
+    trendConfig?: TrendConfig;
+    maxLog?: number;
+    readStream?: ReadStream;
+}): Promise<SessionSeed | undefined>;
+export declare function listSessionDecisions(sessionId: unknown, { dir, port, page, pageSize, readStream }?: {
+    dir?: string;
+    port?: number;
+    page?: number;
+    pageSize?: number;
+    readStream?: ReadStream;
+}): Promise<{
+    entries: LogRow[];
+    total: number;
+    page: number;
+    pageSize: number;
+    pages: number;
+}>;

package/lib/host/log-analyze.js

@@ -0,0 +1,254 @@
+import { createReadableStream } from "./log-read.js";
+import { advanceRun, severityOf } from "./quality-trend.js";
+import { narrowApplied } from "./narrowing.js";
+import { isObject } from "./types.js";
+const DECISION_KINDS = /* @__PURE__ */ new Set(["gate", "check", "narrow", "complete"]);
+const atOf = (record) => {
+  const value = record.at;
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+};
+function foldSession(records) {
+  const decisions = /* @__PURE__ */ new Map();
+  const annotations = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    if (!isObject(record)) continue;
+    if (record.kind === "annotation") {
+      const target = typeof record.target === "string" ? record.target : void 0;
+      if (!target) continue;
+      const prev = annotations.get(target);
+      if (!prev || Number.isFinite(record.at) && record.at >= (prev.at ?? 0)) {
+        annotations.set(target, { rating: record.rating, at: Number.isFinite(record.at) ? record.at : 0 });
+      }
+      continue;
+    }
+    if (DECISION_KINDS.has(record.kind) && typeof record.id === "string") {
+      decisions.set(record.id, record);
+    }
+  }
+  return { decisions, annotations };
+}
+function confidenceBucket(value) {
+  if (typeof value !== "number" || !Number.isFinite(value)) return void 0;
+  if (value < 0.4) return "lt40";
+  if (value < 0.6) return "lt60";
+  if (value < 0.8) return "lt80";
+  return "gte80";
+}
+function emptyProfile() {
+  return {
+    gate: { attempts: 0, allow: 0, ask: 0, deny: 0, error: 0 },
+    check: { attempts: 0, ok: 0, low: 0, error: 0, scoreSum: 0, scoreCount: 0, confidence: { lt40: 0, lt60: 0, lt80: 0, gte80: 0 } },
+    narrow: { attempts: 0, applied: 0, error: 0, droppedSum: 0, tooManyCandidates: 0 },
+    complete: { attempts: 0, satisfied: 0, unsatisfied: 0, insufficient: 0, error: 0, steered: 0 }
+  };
+}
+function buildProfile(decisions) {
+  const profile = emptyProfile();
+  const rows = decisions instanceof Map ? [...decisions.values()] : [...decisions];
+  for (const record of rows) {
+    const kind = record.kind;
+    switch (kind) {
+      case "gate": {
+        const bucket = profile.gate;
+        bucket.attempts++;
+        if (record.outcome === "error") bucket.error++;
+        else if (record.outcome === "allow") bucket.allow++;
+        else if (record.outcome === "ask") bucket.ask++;
+        else if (record.outcome === "deny") bucket.deny++;
+        break;
+      }
+      case "check": {
+        const bucket = profile.check;
+        bucket.attempts++;
+        if (record.outcome === "error") bucket.error++;
+        else if (record.outcome === "low") bucket.low++;
+        else bucket.ok++;
+        if (typeof record.score === "number" && Number.isFinite(record.score)) {
+          bucket.scoreSum += record.score;
+          bucket.scoreCount++;
+        }
+        const cb = confidenceBucket(record.confidence);
+        if (cb) bucket.confidence[cb]++;
+        break;
+      }
+      case "narrow": {
+        const bucket = profile.narrow;
+        bucket.attempts++;
+        if (record.outcome === "error") bucket.error++;
+        else if (narrowApplied(record)) bucket.applied++;
+        if (Number.isSafeInteger(record.dropped) && record.dropped > 0) bucket.droppedSum += record.dropped;
+        if (record.reason === "too-many-candidates") bucket.tooManyCandidates++;
+        break;
+      }
+      case "complete": {
+        const bucket = profile.complete;
+        bucket.attempts++;
+        if (record.outcome === "error") bucket.error++;
+        if (Number.isSafeInteger(record.satisfied)) bucket.satisfied += record.satisfied;
+        if (Number.isSafeInteger(record.unsatisfied)) bucket.unsatisfied += record.unsatisfied;
+        if (Number.isSafeInteger(record.insufficient)) bucket.insufficient += record.insufficient;
+        if (record.steered === true) bucket.steered++;
+        break;
+      }
+      default:
+        break;
+    }
+  }
+  return profile;
+}
+function backtestTrend(checkRecords, { trendMinConfidence = 0.6, trendRun = 3, trendSevereRun = 5, lowScoreThreshold = 1 } = {}) {
+  const ordered = [...checkRecords].filter((record) => isObject(record) && record.kind === "check").sort((a, b) => atOf(a) - atOf(b));
+  let run = 0, warnHits = 0, severeHits = 0, maxRun = 0;
+  for (const record of ordered) {
+    if (record.outcome === "error") continue;
+    const isLow = record.outcome === "low" || typeof record.score === "number" && record.score <= lowScoreThreshold;
+    if (!isLow) {
+      run = 0;
+      continue;
+    }
+    const confident = typeof record.confidence === "number" && Number.isFinite(record.confidence) && record.confidence >= trendMinConfidence;
+    if (!confident) continue;
+    run++;
+    maxRun = Math.max(maxRun, run);
+    if (run === trendSevereRun) severeHits++;
+    else if (run === trendRun) warnHits++;
+  }
+  return { warnHits, severeHits, maxRun };
+}
+function annotationSummary(decisions, annotations) {
+  const summary = { rated: 0, good: 0, bad: 0, unsure: 0 };
+  const ratings = /* @__PURE__ */ Object.create(null);
+  for (const [id] of decisions) {
+    const annotation = annotations.get(id);
+    if (!annotation || typeof annotation.rating !== "string") continue;
+    summary.rated++;
+    if (annotation.rating === "good") summary.good++;
+    else if (annotation.rating === "bad") summary.bad++;
+    else if (annotation.rating === "unsure") summary.unsure++;
+    ratings[id] = annotation.rating;
+  }
+  return { summary, ratings };
+}
+function analyzeSession(records, trendConfig) {
+  const { decisions, annotations } = foldSession(records);
+  const annotation = annotationSummary(decisions, annotations);
+  return {
+    totalDecisions: decisions.size,
+    profile: buildProfile(decisions),
+    trendBacktest: backtestTrend([...decisions.values()], trendConfig),
+    annotations: annotation.summary,
+    ratings: annotation.ratings
+  };
+}
+async function analyzeSessionLogs(sessionId, { dir, port, trendConfig, readStream = createReadableStream } = {}) {
+  if (typeof sessionId !== "string" || !sessionId.trim()) throw new Error("Invalid session id");
+  const records = [];
+  for await (const record of readStream({ dir, port })) {
+    if (!isObject(record)) continue;
+    if (record.sessionId === sessionId) records.push(record);
+  }
+  return analyzeSession(records, trendConfig);
+}
+function buildSeed(decisions, { maxLog = 50, trendConfig = {} } = {}) {
+  const ordered = [...decisions.values()].filter((record) => DECISION_KINDS.has(record.kind)).sort((a, b) => atOf(a) - atOf(b));
+  const seed = {
+    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: []
+  };
+  const minConfidence = typeof trendConfig.trendMinConfidence === "number" ? trendConfig.trendMinConfidence : 0.6;
+  const thresholds = { trendRun: trendConfig.trendRun ?? 3, trendSevereRun: trendConfig.trendSevereRun ?? 5 };
+  let run = 0;
+  for (const record of ordered) {
+    seed.attempts++;
+    const isError = record.outcome === "error";
+    if (isError) seed.failures++;
+    if (record.kind === "gate") {
+      seed.gate.attempts++;
+      if (isError) seed.gate.failures++;
+      if (record.outcome === "allow") seed.gate.allow++;
+      else if (record.outcome === "ask") seed.gate.ask++;
+      else if (record.outcome === "deny") seed.gate.deny++;
+    } else if (record.kind === "check") {
+      seed.check.attempts++;
+      if (isError) seed.check.failures++;
+      if (!isError) {
+        if (record.outcome === "low") seed.check.low++;
+        const confident = typeof record.confidence === "number" && Number.isFinite(record.confidence) && record.confidence >= minConfidence;
+        run = advanceRun(run, { lowScore: record.outcome === "low", confident });
+      }
+    } else if (record.kind === "narrow") {
+      seed.narrow.attempts++;
+      if (isError) seed.narrow.failures++;
+      if (record.outcome === "applied") {
+        if (narrowApplied(record)) seed.narrow.applied++;
+        if (Number.isSafeInteger(record.dropped) && record.dropped > 0) seed.narrow.dropped += record.dropped;
+      }
+    } else if (record.kind === "complete") {
+      seed.complete.attempts++;
+      if (isError) seed.complete.failures++;
+      if (!isError) {
+        if (Number.isSafeInteger(record.satisfied)) seed.complete.satisfied += record.satisfied;
+        if (Number.isSafeInteger(record.unsatisfied)) seed.complete.unsatisfied += record.unsatisfied;
+        if (Number.isSafeInteger(record.insufficient)) seed.complete.insufficient += record.insufficient;
+        if (record.steered === true) seed.complete.steered++;
+      }
+    }
+  }
+  seed.check.run = run;
+  seed.check.severity = severityOf(run, thresholds);
+  seed.log = ordered.slice(-maxLog).map((record) => {
+    const rest = { ...record };
+    delete rest.sessionId;
+    return rest;
+  });
+  return seed;
+}
+async function reconstructSessionSeed(sessionId, { dir, port, trendConfig, maxLog, readStream = createReadableStream } = {}) {
+  if (typeof sessionId !== "string" || !sessionId.trim()) return void 0;
+  const records = [];
+  for await (const record of readStream({ dir, port })) {
+    if (!isObject(record)) continue;
+    if (record.sessionId === sessionId) records.push(record);
+  }
+  if (records.length === 0) return void 0;
+  const { decisions } = foldSession(records);
+  if (decisions.size === 0) return void 0;
+  return buildSeed(decisions, { maxLog, trendConfig });
+}
+async function listSessionDecisions(sessionId, { dir, port, page = 1, pageSize = 100, readStream = createReadableStream } = {}) {
+  if (typeof sessionId !== "string" || !sessionId.trim()) throw new Error("Invalid session id");
+  const size = Number.isSafeInteger(pageSize) && pageSize > 0 && pageSize <= 500 ? pageSize : 100;
+  const records = [];
+  for await (const record of readStream({ dir, port })) {
+    if (!isObject(record)) continue;
+    if (record.sessionId === sessionId) records.push(record);
+  }
+  const { decisions } = foldSession(records);
+  const rows = [...decisions.values()].sort((a, b) => atOf(b) - atOf(a));
+  const total = rows.length;
+  const pages = Math.max(1, Math.ceil(total / size));
+  const current = Math.min(Math.max(1, Number.isSafeInteger(page) ? page : 1), pages);
+  const start = (current - 1) * size;
+  const entries = rows.slice(start, start + size).map((record) => {
+    const rest = { ...record };
+    delete rest.sessionId;
+    return rest;
+  });
+  return { entries, total, page: current, pageSize: size, pages };
+}
+export {
+  analyzeSession,
+  analyzeSessionLogs,
+  annotationSummary,
+  backtestTrend,
+  buildProfile,
+  buildSeed,
+  foldSession,
+  listSessionDecisions,
+  reconstructSessionSeed
+};

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

@@ -0,0 +1,4 @@
+export declare function createReadableStream({ dir, port }?: {
+    dir?: string;
+    port?: number;
+}): AsyncGenerator<unknown>;

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[];