@codebam/dsh-thinking-auditor 0.1.0

package/src/config.mjs

@@ -0,0 +1,243 @@
+/**
+ * `@codebam/dsh-thinking-auditor` configuration.
+ *
+ * Pure module: no dsh imports, so it is testable with plain `node --test`.
+ * The mounted Cordis `Config` schema is declarative (a configuration catalog);
+ * this module owns the one normalization path every consumer goes through,
+ * including values that arrive from the user settings layer (`thinking-audit`).
+ *
+ * Invalid configuration fails loud at `apply()` with a path-qualified error,
+ * never by silently drifting a threshold or a gate.
+ *
+ * @module @codebam/dsh-thinking-auditor/config
+ */
+
+/** Audit threat levels, ordered from least to most severe. */
+export const AUDIT_LEVELS = Object.freeze(['none', 'watch', 'verify', 'block'])
+
+/** Claim/evidence statuses a finding may carry. */
+export const CLAIM_STATUSES = Object.freeze(['supported', 'unsupported', 'contradicted', 'speculative'])
+
+/** Finding severities, ordered from least to most severe. */
+export const SEVERITIES = Object.freeze(['low', 'medium', 'high'])
+
+/** Maximum actuator tier a deployment may enable. */
+export const MAX_TIERS = Object.freeze(['observe', 'verify', 'block', 'cancel'])
+
+/** How a block-tier gate may present itself. */
+export const TIER2_MODES = Object.freeze(['ask', 'deny'])
+
+/** What T1 treats as sufficient deterministic evidence to force verification. */
+export const VERIFY_ON = Object.freeze(['speculative', 'unsupported', 'contradicted', 'never'])
+
+/** What T2 treats as sufficient deterministic evidence to gate an irreversible action. */
+export const BLOCK_ON = Object.freeze(['never', 'contradicted', 'confirmed'])
+
+/** What T3 treats as sufficient evidence to cancel a turn. */
+export const CANCEL_ON = Object.freeze(['never', 'confirmed'])
+
+/**
+ * One complete, resolved configuration. Every field is required after
+ * resolution; user/entry configuration is a partial overlay.
+ */
+export const DEFAULT_CONFIG = Object.freeze({
+  /** Master switch. `false` makes `apply()` a no-op. */
+  enabled: true,
+  /** Audit at a completed tool boundary when enough unaudited reasoning is pending. */
+  auditOnToolResult: true,
+  /** Audit the pending reasoning window before a turn is allowed to close. */
+  auditOnTurnStop: true,
+  /** Audit a short final reasoning slice when one model attempt ends. */
+  auditOnAttemptEnd: true,
+  /** Reasoning characters that force a background audit window. */
+  windowChars: 1800,
+  /** Minimum pending reasoning characters for an opportunistic audit trigger. */
+  minWindowChars: 500,
+  /** Hard cap on the trace excerpt sent to one audit; the oldest part is dropped. */
+  maxTraceChars: 12000,
+  /** Minimum spacing between background audits for one session, in milliseconds. */
+  cooldownMs: 1500,
+  /** Deadline for a background audit model call, in milliseconds. */
+  requestTimeoutMs: 20000,
+  /** Maximum time `agent/turn-stopping` will wait for an audit verdict, in milliseconds. */
+  turnStopTimeoutMs: 5000,
+  /** Maximum background audits one turn may start. */
+  maxAuditsPerTurn: 8,
+
+  auditor: Object.freeze({
+    /** Same-model route override; `null` follows the session's logged request header. */
+    provider: null,
+    /** Same-model id override; `null` follows the session's logged request header. */
+    model: null,
+    /** Maximum output tokens for one audit response. */
+    maxTokens: 1600,
+    /** Greedy decoding by default; the auditor should not be creative. */
+    temperature: 0,
+    /** Follow the session's reasoning-effort selection when the route advertises one. */
+    followReasoningEffort: true,
+    /** Hard cap on the decoded auditor response text before JSON parsing. */
+    maxResponseChars: 50000,
+  }),
+
+  evidence: Object.freeze({
+    /** Maximum tool calls retained per session. */
+    maxToolCalls: 120,
+    /** Per-result text cap in the evidence ledger. */
+    maxResultChars: 6000,
+    /** Overall evidence digest cap sent to the auditor. */
+    maxDigestChars: 16000,
+    /** Per-user-message text cap in the evidence digest. */
+    maxUserChars: 4000,
+  }),
+
+  gates: Object.freeze({
+    /** Highest actuator tier this deployment permits: observe | verify | block | cancel. */
+    maxTier: 'verify',
+    /** Findings below this severity do not drive a gate (they remain audited). */
+    minimumSeverity: 'medium',
+    /** Lowest deterministic status that makes T1 force an extra verification step. */
+    verifyOn: 'unsupported',
+    /** What T2 treats as sufficient to gate an irreversible action. */
+    blockOn: 'confirmed',
+    /** What T3 treats as sufficient to cancel a turn. */
+    cancelOn: 'never',
+    /** Windows at `verify`+ for T1; block needs this many, cancel needs one more. */
+    consecutive: 2,
+    /** T2 presentation: `ask` routes through the approval seam, `deny` blocks outright. */
+    t2Mode: 'ask',
+    /** If an audit is in flight at an irreversible boundary and no verdict exists, ask. */
+    askOnTimeoutForIrreversible: true,
+  }),
+
+  store: Object.freeze({
+    /** Persist verdict/action records to a private JSONL audit log beside the dsh home. */
+    persist: true,
+    /** Explicit audit directory; `null` derives from `dshHomePath` / `$DSH_HOME` / `~/.dsh`. */
+    dir: null,
+    /** Verdict records retained per session. */
+    maxRecordsPerSession: 200,
+    /** Sessions retained in the in-memory audit store. */
+    maxSessions: 200,
+  }),
+})
+
+const SEVERITY_RANK = Object.freeze({ low: 1, medium: 2, high: 3 })
+
+/** True for a plain JSON-style object (not an array or null). */
+function isPlainObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Deep-freeze a plain configuration tree in place. */
+export function deepFreeze(value) {
+  if (value === null || typeof value !== 'object' || Object.isFrozen(value)) return value
+  for (const nested of Object.values(value)) deepFreeze(nested)
+  return Object.freeze(value)
+}
+
+/** Recursively overlay `override` on `base`, treating arrays as leaf values. */
+function merge(base, override) {
+  if (!isPlainObject(base) || !isPlainObject(override)) {
+    return override === undefined ? base : override
+  }
+  const out = { ...base }
+  for (const [key, value] of Object.entries(override)) {
+    if (value === undefined) continue
+    out[key] = isPlainObject(base[key]) && isPlainObject(value) ? merge(base[key], value) : value
+  }
+  return out
+}
+
+/** Throw a path-qualified configuration error. */
+function fail(path, message) {
+  throw new TypeError(`thinking-auditor: invalid config at ${path}: ${message}`)
+}
+
+/** Validate one integer field. */
+function integer(config, path, { min, max } = {}) {
+  const value = path.split('.').reduce((node, key) => node?.[key], config)
+  if (!Number.isInteger(value)) fail(path, `expected an integer, got ${JSON.stringify(value)}`)
+  if (min !== undefined && value < min) fail(path, `expected >= ${min}, got ${value}`)
+  if (max !== undefined && value > max) fail(path, `expected <= ${max}, got ${value}`)
+}
+
+/** Validate one numeric field. */
+function number(config, path, { min, max } = {}) {
+  const value = path.split('.').reduce((node, key) => node?.[key], config)
+  if (typeof value !== 'number' || !Number.isFinite(value)) fail(path, `expected a finite number, got ${JSON.stringify(value)}`)
+  if (min !== undefined && value < min) fail(path, `expected >= ${min}, got ${value}`)
+  if (max !== undefined && value > max) fail(path, `expected <= ${max}, got ${value}`)
+}
+
+/** Validate one enum-like field. */
+function oneOf(config, path, allowed) {
+  const value = path.split('.').reduce((node, key) => node?.[key], config)
+  if (!allowed.includes(value)) fail(path, `expected one of ${allowed.join(', ')}, got ${JSON.stringify(value)}`)
+}
+
+/** Stop invalid scalar types before they reach a comparator. */
+function validateConfig(config) {
+  for (const section of ['auditor', 'evidence', 'gates', 'store']) {
+    if (!isPlainObject(config[section])) fail(section, 'expected an object')
+  }
+  if (typeof config.enabled !== 'boolean') fail('enabled', 'expected a boolean')
+  for (const key of ['auditOnToolResult', 'auditOnTurnStop', 'auditOnAttemptEnd']) {
+    if (typeof config[key] !== 'boolean') fail(key, 'expected a boolean')
+  }
+  integer(config, 'windowChars', { min: 200 })
+  integer(config, 'minWindowChars', { min: 50 })
+  integer(config, 'maxTraceChars', { min: 200 })
+  if (config.minWindowChars > config.windowChars) fail('minWindowChars', 'must be <= windowChars')
+  if (config.maxTraceChars < config.windowChars) fail('maxTraceChars', 'must be >= windowChars')
+  integer(config, 'cooldownMs', { min: 0 })
+  integer(config, 'requestTimeoutMs', { min: 1000 })
+  integer(config, 'turnStopTimeoutMs', { min: 250 })
+  if (config.turnStopTimeoutMs > config.requestTimeoutMs) fail('turnStopTimeoutMs', 'must be <= requestTimeoutMs')
+  integer(config, 'maxAuditsPerTurn', { min: 1 })
+
+  if (config.auditor.provider !== null && typeof config.auditor.provider !== 'string') fail('auditor.provider', 'expected a string or null')
+  if (config.auditor.model !== null && typeof config.auditor.model !== 'string') fail('auditor.model', 'expected a string or null')
+  integer(config, 'auditor.maxTokens', { min: 64 })
+  number(config, 'auditor.temperature', { min: 0, max: 2 })
+  if (typeof config.auditor.followReasoningEffort !== 'boolean') fail('auditor.followReasoningEffort', 'expected a boolean')
+  integer(config, 'auditor.maxResponseChars', { min: 1000 })
+
+  integer(config, 'evidence.maxToolCalls', { min: 1 })
+  integer(config, 'evidence.maxResultChars', { min: 256 })
+  integer(config, 'evidence.maxDigestChars', { min: 512 })
+  integer(config, 'evidence.maxUserChars', { min: 128 })
+
+  oneOf(config, 'gates.maxTier', MAX_TIERS)
+  oneOf(config, 'gates.minimumSeverity', SEVERITIES)
+  oneOf(config, 'gates.verifyOn', VERIFY_ON)
+  oneOf(config, 'gates.blockOn', BLOCK_ON)
+  oneOf(config, 'gates.cancelOn', CANCEL_ON)
+  integer(config, 'gates.consecutive', { min: 1, max: 12 })
+  oneOf(config, 'gates.t2Mode', TIER2_MODES)
+  if (typeof config.gates.askOnTimeoutForIrreversible !== 'boolean') fail('gates.askOnTimeoutForIrreversible', 'expected a boolean')
+
+  if (typeof config.store.persist !== 'boolean') fail('store.persist', 'expected a boolean')
+  if (config.store.dir !== null && (typeof config.store.dir !== 'string' || config.store.dir.trim().length === 0)) fail('store.dir', 'expected a non-empty string or null')
+  integer(config, 'store.maxRecordsPerSession', { min: 1 })
+  integer(config, 'store.maxSessions', { min: 1 })
+  return config
+}
+
+/**
+ * Resolve entry configuration plus an optional user-settings overlay onto the
+ * complete default. The returned value is detached and deep-frozen.
+ * @param {object|undefined} raw - partial configuration from the loader or settings section.
+ * @returns {object} the resolved, frozen configuration.
+ */
+export function resolveConfig(raw) {
+  if (raw === undefined || raw === null) return deepFreeze(merge(DEFAULT_CONFIG, {}))
+  if (!isPlainObject(raw)) fail('<root>', `expected an object, got ${JSON.stringify(raw)}`)
+  return deepFreeze(validateConfig(merge(DEFAULT_CONFIG, raw)))
+}
+
+/** Severity comparator used by policy and prompt assembly. */
+export function severityAtLeast(actual, minimum) {
+  return (SEVERITY_RANK[actual] ?? 0) >= (SEVERITY_RANK[minimum] ?? 0)
+}
+
+export { SEVERITY_RANK }

package/src/file-sink.mjs

@@ -0,0 +1,76 @@
+/**
+ * Optional durable sink: private JSONL audit records beside the harness home.
+ *
+ * This is deliberately NOT a session-log event. The session format treats an
+ * unknown event type as required unless it carries an `ignorable` envelope
+ * marker, and `Session.append()` cannot set that marker; writing audit records
+ * into the monitored session would risk making the session unreadable on
+ * resume. A separate 0600 JSONL file keeps verdicts durable without touching
+ * session compatibility.
+ *
+ * @module @codebam/dsh-thinking-auditor/file-sink
+ */
+
+import { appendFile, mkdir, chmod } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, resolve } from 'node:path'
+
+/** Resolve the default audit directory from the harness home seam. */
+export function resolveAuditDir(ctx, configured) {
+  if (typeof configured === 'string' && configured.trim().length > 0) return resolve(configured.trim())
+  const dshHomePath = ctx?.get?.('dshHomePath')
+  if (typeof dshHomePath === 'function') {
+    try {
+      return dshHomePath('thinking-auditor')
+    } catch {
+      // Fall through to environment/home resolution.
+    }
+  }
+  if (typeof process.env.DSH_HOME === 'string' && process.env.DSH_HOME.trim().length > 0) {
+    return join(process.env.DSH_HOME.trim(), 'thinking-auditor')
+  }
+  return join(homedir(), '.dsh', 'thinking-auditor')
+}
+
+/**
+ * Create a serialized append sink for one JSONL file.
+ *
+ * @param {object} options - `ctx`, configured `dir`, `file`, and an optional logger.
+ * @returns {{ path: string, write: (record: object) => Promise<void>, disabled: boolean, error?: string }}
+ */
+export function createJsonlSink({ ctx, dir, file = 'audit.jsonl', log } = {}) {
+  const auditDir = resolveAuditDir(ctx, dir)
+  const path = join(auditDir, file)
+  let tail = Promise.resolve()
+  let disabled = false
+  let error
+  let secured = false
+
+  const ensureDir = mkdir(auditDir, { recursive: true, mode: 0o700 }).then(() => chmod(auditDir, 0o700)).catch((cause) => {
+    disabled = true
+    error = cause?.message ?? String(cause)
+    log?.warn?.(`thinking-auditor: audit store disabled: ${error}`)
+  })
+
+  const write = (record) => {
+    if (disabled) return Promise.resolve()
+    tail = tail
+      .then(async () => {
+        await ensureDir
+        if (disabled) return
+        await appendFile(path, `${JSON.stringify(record)}\n`, { mode: 0o600 })
+        if (!secured) {
+          secured = true
+          await chmod(path, 0o600).catch(() => {})
+        }
+      })
+      .catch((cause) => {
+        disabled = true
+        error = cause?.message ?? String(cause)
+        log?.warn?.(`thinking-auditor: audit store disabled after write failure: ${error}`)
+      })
+    return tail
+  }
+
+  return { path, write, get disabled() { return disabled }, get error() { return error } }
+}