@codebam/dsh-thinking-auditor 0.1.0

package/index.mjs

@@ -0,0 +1,674 @@
+/**
+ * @codebam/dsh-thinking-auditor
+ *
+ * A covert claim/evidence auditor for live DeepSeek Harness reasoning traces.
+ *
+ * The plugin taps `agent/assistant-stream`, copies each attempt's
+ * `reasoning-delta` chunks into a bounded per-session window, and passes every
+ * chunk through untouched. The monitored request and its context are never
+ * modified. At triggered boundaries it joins the trace against an incrementally
+ * maintained ledger of what the session actually saw (`tool/call`,
+ * `tool/result`, user messages), runs deterministic claim-vs-evidence checks,
+ * and asks the same provider/model route in a hand-built session-less call for
+ * a structured second opinion. A deterministic policy module owns escalation:
+ * T0 observe, T1 force verification at `agent/turn-stopping`, T2 ask/deny an
+ * irreversible `tools/pre-execute` action, T3 cancel only when explicitly
+ * configured.
+ *
+ * The monitor is not a mind reader. It reports claim-to-evidence relations;
+ * it never labels intent. CoT is an unfaithful generated artifact, so the
+ * defaults cap actuators at T1; nothing stops a turn or blocks an irreversible action on a single model opinion.
+ *
+ * @module @codebam/dsh-thinking-auditor
+ */
+
+import z from '@deepseek-ai/schemastery'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { resolveConfig } from './src/config.mjs'
+import { EvidenceLedger } from './src/ledger.mjs'
+import { extractClaims, summarizeFindings, verifyClaims } from './src/claims.mjs'
+import { buildAuditorPrompt, parseAuditorResponse } from './src/auditor.mjs'
+import { decideToolAction, decideTurnAction, mergeVerdict } from './src/policy.mjs'
+import { AuditStore } from './src/store.mjs'
+import { createJsonlSink } from './src/file-sink.mjs'
+import { SessionAuditState } from './src/state.mjs'
+import { classifyAction } from './src/stakes.mjs'
+import { deadlineSignal, isAbortError, raceDeadline } from './src/async.mjs'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'thinking-auditor'
+
+/** Services the plugin consumes; all are part of the dsh base bundle. */
+export const inject = ['llm', 'sessions', 'tools']
+
+/** Settings namespace for live user-owned thresholds and gates. */
+export const SETTINGS_NAMESPACE = 'thinking-audit'
+
+/** Stable producer id attached to every synthetic message and audit record. */
+export const PLUGIN_ID = '@codebam/dsh-thinking-auditor'
+
+/**
+ * Loader-facing configuration schema.
+ *
+ * This schema is declarative for the configuration catalog; normalization and
+ * validation live in `src/config.mjs` and own the real contract.
+ */
+export const Config = z.object({
+  enabled: z.boolean(),
+  auditOnToolResult: z.boolean(),
+  auditOnTurnStop: z.boolean(),
+  auditOnAttemptEnd: z.boolean(),
+  windowChars: z.number(),
+  minWindowChars: z.number(),
+  maxTraceChars: z.number(),
+  cooldownMs: z.number(),
+  requestTimeoutMs: z.number(),
+  turnStopTimeoutMs: z.number(),
+  maxAuditsPerTurn: z.number(),
+  auditor: z.object({
+    provider: z.union([z.string(), z.const(null)]),
+    model: z.union([z.string(), z.const(null)]),
+    maxTokens: z.number(),
+    temperature: z.number(),
+    followReasoningEffort: z.boolean(),
+    maxResponseChars: z.number(),
+  }),
+  evidence: z.object({
+    maxToolCalls: z.number(),
+    maxResultChars: z.number(),
+    maxDigestChars: z.number(),
+    maxUserChars: z.number(),
+  }),
+  gates: z.object({
+    maxTier: z.union(['observe', 'verify', 'block', 'cancel']),
+    minimumSeverity: z.union(['low', 'medium', 'high']),
+    verifyOn: z.union(['speculative', 'unsupported', 'contradicted', 'never']),
+    blockOn: z.union(['never', 'contradicted', 'confirmed']),
+    cancelOn: z.union(['never', 'confirmed']),
+    consecutive: z.number(),
+    t2Mode: z.union(['ask', 'deny']),
+    askOnTimeoutForIrreversible: z.boolean(),
+  }),
+  store: z.object({
+    persist: z.boolean(),
+    dir: z.union([z.string(), z.const(null)]),
+    maxRecordsPerSession: z.number(),
+    maxSessions: z.number(),
+  }),
+})
+
+/** Neutral T1 instruction; it asks for evidence, not for a behavior change. */
+export const VERIFY_MESSAGE = [
+  'Before finalizing: verify each factual claim against an actual tool result or file read from this session,',
+  'cite the evidence for anything you assert, and remove or explicitly mark as unverified any claim you cannot',
+  'support from this session’s evidence. Do not state a result you have not verified here.',
+].join(' ')
+
+/** Neutral T2 reason shown to the model on an ask/deny. */
+export const BLOCK_REASON =
+  'Blocked: this turn contains unresolved claim/evidence mismatches. Re-establish the facts from tool output or file reads, then run the intended action again.'
+
+/** Resolve a logger facade that works with the Cordis built-in and with mocks. */
+function resolveLogger(ctx) {
+  const fallback = {
+    info() {},
+    warn() {},
+    error() {},
+    debug() {},
+  }
+  const logger = ctx?.logger
+  if (typeof logger === 'function') {
+    try {
+      return logger('thinking-auditor')
+    } catch {
+      return fallback
+    }
+  }
+  if (logger !== undefined && logger !== null) return logger
+  return fallback
+}
+
+/** Stable string session key from either a live agent or session id. */
+function sessionKey(agent) {
+  return String(agent?.session?.id ?? agent?.id ?? 'unknown')
+}
+
+/**
+ * Resolve the auditor route: explicit config override first, then the session's
+ * latest logged `request/header` (which follows model changes), then the
+ * agent's creation options.
+ */
+export function resolveRoute(agent, config) {
+  const header = typeof agent?.session?.requestHeader === 'function' ? agent.session.requestHeader() : undefined
+  const headerConfig = header?.config
+  const options = agent?.options
+  const provider = config?.auditor?.provider ?? headerConfig?.provider ?? options?.provider
+  const model = config?.auditor?.model ?? headerConfig?.model ?? options?.model
+  if (typeof provider !== 'string' || provider.length === 0 || typeof model !== 'string' || model.length === 0) {
+    return undefined
+  }
+  const reasoningEffort = headerConfig?.reasoningEffort ?? options?.reasoningEffort
+  return { provider, model, reasoningEffort }
+}
+
+/** Collect focus anchors from extracted claims for evidence-digest ranking. */
+function focusTerms(claims) {
+  const terms = []
+  for (const claim of claims ?? []) {
+    for (const anchor of claim?.anchors ?? []) {
+      if (anchor.kind === 'term') continue
+      terms.push(anchor.value)
+    }
+  }
+  return [...new Set(terms)].slice(0, 24)
+}
+
+/** Merge mechanical findings with auditor claims, keeping mechanical status authoritative. */
+export function mergeClaims(mechanicalFindings, auditorClaims) {
+  const merged = (mechanicalFindings ?? []).slice(0, 24).map((finding) => ({ ...finding, source: 'mechanical' }))
+  const seen = new Set(merged.map((finding) => String(finding.quote ?? '').toLowerCase().replace(/\s+/g, ' ')))
+  for (const claim of auditorClaims ?? []) {
+    const key = String(claim?.quote ?? '').toLowerCase().replace(/\s+/g, ' ')
+    if (key.length === 0 || seen.has(key)) continue
+    seen.add(key)
+    merged.push({ ...claim, source: 'auditor' })
+  }
+  return merged.slice(0, 32)
+}
+
+/** Read the last real user request from the ledger, if any. */
+function lastUserRequest(ledger, sessionId) {
+  const view = ledger.view(sessionId)
+  for (let index = view.users.length - 1; index >= 0; index -= 1) {
+    const user = view.users[index]
+    if (user.sourceKind === 'user' || user.sourceKind === 'unknown') return user.text
+  }
+  return ''
+}
+
+/**
+ * Run one isolated auditor call on the same route as the monitored session.
+ *
+ * The request deliberately omits `sessionId` and `purpose`, so the call
+ * attaches to no session, enters no persistence log, and emits no
+ * `agent/assistant-stream` frame. Text is collected from delta chunks only, so
+ * reasoning content cannot contaminate the JSON audit.
+ */
+export async function callAuditor(ctx, config, route, prompt, signal) {
+  const options = {
+    provider: route.provider,
+    model: route.model,
+    messages: [
+      createUserMessage({
+        content: [{ type: 'text', text: prompt.user }],
+        source: { kind: 'plugin', plugin: PLUGIN_ID, form: 'notice', summary: 'audit request' },
+      }),
+    ],
+    system: prompt.system,
+    temperature: config.auditor.temperature,
+    maxTokens: config.auditor.maxTokens,
+    signal,
+  }
+  if (route.reasoningEffort !== undefined && config.auditor.followReasoningEffort) {
+    options.reasoningEffort = route.reasoningEffort
+  }
+  const textByIndex = new Map()
+  const deltaIndexes = new Set()
+  let finish
+  for await (const chunk of ctx.llm.stream(options)) {
+    if (chunk?.type === 'text-delta' && typeof chunk.text === 'string') {
+      const index = Number.isInteger(chunk.index) ? chunk.index : 0
+      deltaIndexes.add(index)
+      textByIndex.set(index, `${textByIndex.get(index) ?? ''}${chunk.text}`)
+    } else if (chunk?.type === 'block-end' && chunk.block?.type === 'text') {
+      const index = Number.isInteger(chunk.index) ? chunk.index : 0
+      // Delta-built blocks already have their text; one closed block without
+      // deltas is the adapter's delta-only fallback.
+      if (!deltaIndexes.has(index)) textByIndex.set(index, chunk.block.text)
+    } else if (chunk?.type === 'finish') {
+      finish = chunk.reason
+    }
+  }
+  const text = [...textByIndex.entries()]
+    .sort((left, right) => left[0] - right[0])
+    .map(([, value]) => value)
+    .join('\n')
+  if (finish?.kind === 'error' || finish?.kind === 'aborted') {
+    return { text, error: finish.failure?.message ?? finish.kind }
+  }
+  return { text }
+}
+
+/**
+ * Mount the auditor.
+ * @param {import('@deepseek-ai/cordis').Context} ctx - owning Cordis context.
+ * @param {object} [rawConfig] - entry configuration merged over defaults.
+ * @returns {void}
+ */
+export function apply(ctx, rawConfig = {}) {
+  const baseConfig = resolveConfig(rawConfig)
+  const log = resolveLogger(ctx)
+  if (!baseConfig.enabled) {
+    log.info?.('thinking-auditor: disabled by configuration')
+    return
+  }
+
+  /** Live configuration source: entry config, or the settings scope once present. */
+  let configSource = () => baseConfig
+  const getConfig = () => resolveConfig(configSource())
+
+  const pluginAbort = new AbortController()
+  ctx.effect(() => () => {
+    pluginAbort.abort(new Error('thinking-auditor disposed'))
+  }, 'thinking-auditor.dispose')
+
+  const store = new AuditStore({
+    maxSessions: baseConfig.store.maxSessions,
+    maxRecordsPerSession: baseConfig.store.maxRecordsPerSession,
+  })
+  const ledger = new EvidenceLedger({
+    maxToolCalls: baseConfig.evidence.maxToolCalls,
+    maxResultChars: baseConfig.evidence.maxResultChars,
+    maxUserChars: baseConfig.evidence.maxUserChars,
+  })
+  const sink = baseConfig.store.persist === true
+    ? createJsonlSink({ ctx, dir: baseConfig.store.dir, log })
+    : undefined
+  if (sink !== undefined) {
+    store.addSink((record) => {
+      if (getConfig().store.persist !== true) return undefined
+      return sink.write(record)
+    })
+  }
+
+  /** @type {Map<string, SessionAuditState>} */
+  const sessions = new Map()
+  const maxSessions = Math.max(1, baseConfig.store.maxSessions)
+  const ensureState = (id) => {
+    const key = String(id)
+    let state = sessions.get(key)
+    if (state !== undefined && !state.disposed) return state
+    while (sessions.size >= maxSessions) {
+      const oldestKey = sessions.keys().next().value
+      const oldest = sessions.get(oldestKey)
+      if (oldest !== undefined) {
+        oldest.disposed = true
+        if (oldest.cooldownTimer !== undefined) clearTimeout(oldest.cooldownTimer)
+      }
+      sessions.delete(oldestKey)
+    }
+    state = new SessionAuditState({ sessionId: key, maxTraceChars: baseConfig.maxTraceChars })
+    sessions.set(key, state)
+    return state
+  }
+
+  // ----- auditor execution -------------------------------------------------
+
+  /**
+   * Start one audit if none is in flight. The window is removed before the
+   * model call; a failed audit is not retried with the same text.
+   */
+  const runAudit = (agent, state, reason, config, options = {}) => {
+    if (state.inFlight !== undefined) {
+      state.rerunRequested = true
+      return state.inFlight
+    }
+    if (state.disposed || !config.enabled) return Promise.resolve(state.lastVerdict)
+    if (options.force !== true && !state.canAuditThisTurn(config.maxAuditsPerTurn)) {
+      return Promise.resolve(state.lastVerdict)
+    }
+    if (state.pending.length === 0) return Promise.resolve(state.lastVerdict)
+
+    const route = resolveRoute(agent, config)
+    if (route === undefined) {
+      log.warn?.('thinking-auditor: no provider/model route available; audit skipped')
+      return Promise.resolve(state.lastVerdict)
+    }
+
+    state.maxTraceChars = config.maxTraceChars
+    const window = state.takeWindow(config.maxTraceChars)
+    const signal = deadlineSignal(options.timeoutMs ?? config.requestTimeoutMs, pluginAbort.signal)
+    state.markAuditStarted()
+
+    const work = (async () => {
+      const started = Date.now()
+      const sessionId = state.sessionId
+      const claims = extractClaims(window.text, { maxClaims: 64 })
+      const evidenceView = ledger.view(sessionId)
+      const mechanicalFindings = verifyClaims(claims, evidenceView)
+      const mechanical = summarizeFindings(mechanicalFindings, config)
+      const prompt = buildAuditorPrompt({
+        route,
+        trace: window.text,
+        evidenceDigest: ledger.digest(sessionId, {
+          focus: focusTerms(claims),
+          maxChars: config.evidence.maxDigestChars,
+        }),
+        mechanical,
+        userRequest: lastUserRequest(ledger, sessionId),
+      })
+      const auditorCall = await callAuditor(ctx, config, route, prompt, signal)
+      const auditor = auditorCall.error !== undefined
+        ? { ...parseAuditorResponse(''), error: auditorCall.error, ok: false }
+        : parseAuditorResponse(auditorCall.text, {
+            maxClaims: 24,
+            maxResponseChars: config.auditor.maxResponseChars,
+          })
+      const verdict = mergeVerdict(mechanical, auditor)
+      const record = store.record({
+        sessionId,
+        turn: window.turn,
+        step: window.step,
+        trigger: reason,
+        route: { provider: route.provider, model: route.model },
+        traceChars: window.chars,
+        level: verdict.level,
+        confirmedFabrication: verdict.confirmedFabrication,
+        reasons: verdict.reasons,
+        mechanical: {
+          level: mechanical.level,
+          counts: mechanical.counts,
+          reasons: mechanical.reasons,
+          highestSeverity: mechanical.highestSeverity,
+        },
+        claims: mergeClaims(mechanicalFindings, auditor.claims),
+        auditor: {
+          ok: auditor.ok === true,
+          level: auditor.level,
+          confidence: auditor.confidence,
+          signals: auditor.signals,
+          summary: auditor.summary,
+          error: auditor.error,
+        },
+        latencyMs: Date.now() - started,
+      })
+      state.lastVerdict = record
+      state.pushHistory(record)
+      return record
+    })()
+
+    const tracked = work
+      .catch((error) => {
+        if (!isAbortError(error)) log.warn?.(`thinking-auditor: audit failed: ${error?.message ?? String(error)}`)
+        return undefined
+      })
+      .finally(() => {
+        state.inFlight = undefined
+        if (state.rerunRequested && !state.disposed) {
+          state.rerunRequested = false
+          queueMicrotask(() => {
+            try {
+              maybeSchedule(agent, state, 'rerun', getConfig())
+            } catch (error) {
+              log.warn?.(`thinking-auditor: rerun scheduling failed: ${error?.message ?? String(error)}`)
+            }
+          })
+        }
+      })
+    state.inFlight = tracked
+    return tracked
+  }
+
+  /** Schedule a background audit when the state says one is due. */
+  const maybeSchedule = (agent, state, reason, config) => {
+    if (!config.enabled || state.disposed) return
+    if (state.inFlight !== undefined) {
+      state.rerunRequested = true
+      return
+    }
+    if (!state.hasPending(config.minWindowChars) && state.pending.length < config.windowChars) return
+    if (!state.canAuditThisTurn(config.maxAuditsPerTurn)) return
+
+    const now = Date.now()
+    const wait = config.cooldownMs - (now - state.lastAuditAt)
+    if (wait > 0 && state.pending.length < config.windowChars) {
+      if (state.cooldownTimer === undefined) {
+        state.cooldownTimer = setTimeout(() => {
+          state.cooldownTimer = undefined
+          try {
+            maybeSchedule(agent, state, 'cooldown', getConfig())
+          } catch (error) {
+            log.warn?.(`thinking-auditor: cooldown scheduling failed: ${error?.message ?? String(error)}`)
+          }
+        }, wait)
+        state.cooldownTimer.unref?.()
+      }
+      return
+    }
+    void runAudit(agent, state, reason, config)
+  }
+
+  // ----- live reasoning capture -------------------------------------------
+
+  ctx.on('agent/assistant-stream', ({ agent, frame } = {}) => {
+    try {
+      const config = getConfig()
+      if (!config.enabled || agent === undefined || frame === undefined) return
+      const state = ensureState(sessionKey(agent))
+      if (frame.type === 'start') {
+        state.turn = frame.turn ?? state.turn
+        state.step = frame.step ?? state.step
+        state.attemptHasReasoningDelta = false
+        return
+      }
+      if (frame.type === 'end') {
+        state.attemptHasReasoningDelta = false
+        if (config.auditOnAttemptEnd && state.hasPending(Math.min(config.minWindowChars, config.windowChars))) {
+          maybeSchedule(agent, state, 'attempt-end', config)
+        }
+        return
+      }
+      if (frame.type !== 'chunk') return
+      state.turn = frame.turn ?? state.turn
+      state.step = frame.step ?? state.step
+      const chunk = frame.chunk
+      if (chunk?.type === 'reasoning-delta' && typeof chunk.text === 'string') {
+        state.attemptHasReasoningDelta = true
+        state.appendReasoning(chunk.text, { turn: frame.turn, step: frame.step })
+      } else if (chunk?.type === 'block-end' && chunk.block?.type === 'reasoning' && state.attemptHasReasoningDelta !== true) {
+        state.appendReasoning(chunk.block.text, { turn: frame.turn, step: frame.step })
+      }
+      if (state.pending.length >= config.windowChars) maybeSchedule(agent, state, 'window', config)
+    } catch (error) {
+      log.warn?.(`thinking-auditor: reasoning capture failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  // ----- evidence ledger ---------------------------------------------------
+
+  ctx.on('session/created', (session) => {
+    try {
+      if (session?.firstLiveSeq > 0) ledger.seedFromMessages(session.id, session.deriveMessages())
+    } catch (error) {
+      log.warn?.(`thinking-auditor: resume ledger backfill failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  ctx.on('session/disposed', (session) => {
+    try {
+      const key = String(session?.id ?? '')
+      const state = sessions.get(key)
+      if (state !== undefined) {
+        state.disposed = true
+        if (state.cooldownTimer !== undefined) clearTimeout(state.cooldownTimer)
+        sessions.delete(key)
+      }
+      ledger.dropSession(session?.id)
+    } catch (error) {
+      log.warn?.(`thinking-auditor: session cleanup failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  ctx.on('session/event', (session, event) => {
+    try {
+      ledger.onSessionEvent(session.id, event)
+      if (event?.type === 'turn/start') {
+        ensureState(session.id).startTurn(event.data?.turn)
+        return
+      }
+      // The durable tool/result append is the ordering point: `tools/result`
+      // fires before the agent loop records the result, so scheduling from
+      // there could audit without the very result that triggered it. Here the
+      // ledger is already updated.
+      if (event?.type === 'tool/result') {
+        const config = getConfig()
+        if (!config.enabled || config.auditOnToolResult !== true) return
+        const state = ensureState(session.id)
+        // The session itself is enough for route resolution; the latest logged
+        // request header owns the route.
+        const agentLike = { session }
+        if (state.hasPending(config.minWindowChars)) maybeSchedule(agentLike, state, 'tool-result', config)
+      }
+    } catch (error) {
+      log.warn?.(`thinking-auditor: ledger update failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  // ----- actuators ---------------------------------------------------------
+
+  ctx.on('agent/turn-stopping', async ({ agent, turn, signal } = {}) => {
+    try {
+      const config = getConfig()
+      if (!config.enabled || agent === undefined) return
+      const state = ensureState(sessionKey(agent))
+      state.turn = turn ?? state.turn
+
+      let record = state.lastVerdict
+      if (config.auditOnTurnStop === true) {
+        if (state.inFlight !== undefined) {
+          const raced = await raceDeadline(state.inFlight, config.turnStopTimeoutMs)
+          if (raced.settled && raced.value !== undefined) record = raced.value
+        } else if (state.hasPending(Math.min(config.minWindowChars, config.windowChars))) {
+          const audited = await runAudit(agent, state, 'turn-stop', config, {
+            force: true,
+            timeoutMs: config.turnStopTimeoutMs,
+          })
+          if (audited !== undefined) record = audited
+        }
+      }
+      if (record === undefined || signal?.aborted === true) return
+
+      const decision = decideTurnAction({
+        record,
+        history: state.history,
+        config,
+        alreadyVerified: state.wasVerified(state.turn),
+        alreadyCancelled: state.wasCancelled(state.turn),
+      })
+      if (decision.action === 'observe') return
+
+      store.recordAction({
+        sessionId: state.sessionId,
+        turn: state.turn,
+        tier: decision.tier,
+        action: decision.action,
+        reason: decision.reason,
+        verdictId: record.id,
+      })
+
+      if (decision.action === 'cancel') {
+        state.latchCancelled(state.turn)
+        agent.cancel({ kind: 'hook', reason: 'thinking-auditor: confirmed untrusted claims survived verification' })
+        return
+      }
+      if (decision.action === 'verify') {
+        state.latchVerified(state.turn)
+        agent.steer(createUserMessage({
+          content: [{ type: 'text', text: VERIFY_MESSAGE }],
+          source: { kind: 'plugin', plugin: PLUGIN_ID, form: 'notice', summary: 'verify claims before finalizing' },
+        }))
+      }
+    } catch (error) {
+      log.warn?.(`thinking-auditor: turn-stopping gate failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  ctx.on('tools/pre-execute', async (exec, next) => {
+    const decision = await next()
+    try {
+      const config = getConfig()
+      if (!config.enabled || exec?.agent === undefined || decision?.kind !== 'allow') return decision
+      const state = ensureState(sessionKey(exec.agent))
+      const stakes = classifyAction(exec.name, exec.arguments)
+      const gate = decideToolAction({
+        record: state.lastVerdict,
+        history: state.history,
+        config,
+        stakes,
+        auditPending: state.inFlight !== undefined,
+      })
+      if (gate.action === 'allow') return decision
+
+      store.recordAction({
+        sessionId: state.sessionId,
+        turn: state.turn,
+        tier: gate.tier,
+        action: gate.action,
+        reason: gate.reason,
+        toolName: String(exec.name ?? 'unknown'),
+        stakes,
+        verdictId: state.lastVerdict?.id,
+      })
+      if (gate.action === 'deny') {
+        return {
+          kind: 'deny',
+          reason: BLOCK_REASON,
+          info: { name: 'ThinkingAuditBlocked', code: 'THINKING_AUDIT_BLOCKED' },
+        }
+      }
+      return { kind: 'ask', reason: BLOCK_REASON }
+    } catch (error) {
+      log.warn?.(`thinking-auditor: pre-execute gate failed: ${error?.message ?? String(error)}`)
+      return decision
+    }
+  })
+
+  // ----- settings and public service --------------------------------------
+
+  ctx.inject(['settings'], (settingsCtx) => {
+    try {
+      settingsCtx.settings.installSection(ctx, SETTINGS_NAMESPACE, Config, baseConfig, {
+        setSource: (source) => {
+          configSource = typeof source === 'function' ? source : () => source
+        },
+        onChange: () => {},
+        validate: (value) => {
+          resolveConfig(value)
+        },
+      })
+    } catch (error) {
+      log.warn?.(`thinking-auditor: settings namespace install failed: ${error?.message ?? String(error)}`)
+    }
+  })
+
+  const service = {
+    plugin: PLUGIN_ID,
+    settingsNamespace: SETTINGS_NAMESPACE,
+    status() {
+      let config = baseConfig
+      try {
+        config = getConfig()
+      } catch {
+        // A bad external settings document must not make the status API throw.
+      }
+      return {
+        enabled: config.enabled,
+        maxTier: config.gates.maxTier,
+        sessions: sessions.size,
+        verdicts: store.verdictCount,
+        inFlight: [...sessions.values()].filter((state) => state.inFlight !== undefined).length,
+        auditStore: sink === undefined || sink.disabled ? null : sink.path,
+        auditStoreError: sink?.error ?? store.lastSinkError,
+      }
+    },
+    latest(sessionId) {
+      return store.latest(sessionId) ?? sessions.get(String(sessionId))?.lastVerdict
+    },
+    verdicts: (sessionId, limit) => store.verdicts(sessionId, limit),
+    actions: (sessionId, limit) => store.actions(sessionId, limit),
+    onRecord: (callback) => store.subscribe(callback),
+  }
+  if (typeof ctx.provide === 'function') ctx.provide('thinkingAudit', service)
+}
+
+export default { name, inject, Config, apply }