@pugi/cli 0.1.0-beta.18 → 0.1.0-beta.19

package/dist/core/denial-tracking/state.js

@@ -0,0 +1,264 @@
+/**
+ * α7 L11 (2026-05-27) — DenialTrackingState surface (Claude Code parity).
+ *
+ * Per the openclaude / anarchic-CC leak research (`gap-analysis-3-repos`
+ * §5.2): Claude Code's `QueryEngine.ts` maintains a per-session
+ * `DenialTrackingState` that records every tool-dispatch denial.
+ * Subsequent turns receive a compact reminder so the model does not
+ * loop on the same refused operation, the operator can audit pressure
+ * points via `/permissions denials` / `/doctor`, and hooks can react
+ * to recurring patterns.
+ *
+ * Pugi pre-L11 surfaced denials only as a one-line sentinel inside the
+ * tool error (`HOOK_BLOCKED:`, `PLAN_MODE_REFUSED:`, `STALE_READ:`).
+ * The model saw each refusal in isolation; no aggregate, no count, no
+ * "do not retry" context across turns. This module closes that gap.
+ *
+ * Design contract:
+ *
+ *   - Per-session in-memory state. The engine adapter creates one
+ *     instance at session open and threads it through `buildExecutor`
+ *     + `runEngineLoop`. No disk persistence — denial history is a
+ *     turn-scoped signal, not a forensic log (the audit ledger at
+ *     `.pugi/events.jsonl` already carries every refused dispatch).
+ *
+ *   - Pure: no I/O, no logging. Inputs are passed by caller, output
+ *     is in-memory only. The diagnostics probe + system-reminder
+ *     splice are pure functions over the snapshot.
+ *
+ *   - Canonical argHash: sha256 of `canonicalize(args)`. Same call
+ *     to same tool with same args = same key. Reordering JSON object
+ *     keys does NOT change the hash (we sort keys recursively before
+ *     stringification). This makes "repeated denial" detection
+ *     deterministic across model retries.
+ *
+ *   - Bounded: the map caps at 256 entries per session. Once full,
+ *     `recordDenial` evicts the oldest entry (lowest `lastDeniedAt`).
+ *     A session with > 256 distinct denials is already pathological;
+ *     the cap is defensive insurance against pathological loops
+ *     blowing memory.
+ *
+ *   - Reminder threshold: the reminder splice only injects when at
+ *     least one record has `count >= 2`. One-off denials are normal
+ *     (the operator is shaping the session); repeated denials = the
+ *     model is failing to learn from the refusal and we should
+ *     reinforce it.
+ */
+import { createHash } from 'node:crypto';
+/** Bound on the per-session map. See module header. */
+export const DENIAL_TRACKING_MAX_ENTRIES = 256;
+/** Threshold above which `buildDenialContext` injects a system reminder. */
+export const DENIAL_REMINDER_THRESHOLD = 2;
+/** Per-denial-args summary cap surfaced to the model. */
+export const DENIAL_ARGS_SUMMARY_BYTES = 240;
+/**
+ * Per-session denial tracker. Instances are mutable but threaded
+ * through `buildExecutor` so every dispatcher in the loop sees the
+ * same view.
+ */
+export class DenialTrackingState {
+    /** Insertion-ordered map. Eviction walks oldest `lastDeniedAt`. */
+    records = new Map();
+    /**
+     * Wall clock. Defaults to `Date.now`. Injected so tests can drive
+     * deterministic timestamps.
+     */
+    clock;
+    constructor(options = {}) {
+        this.clock = options.clock ?? Date.now;
+    }
+    /**
+     * Record a denial. Increments the count when the (tool, args) pair
+     * has been denied before; otherwise inserts a new record. The reason
+     * is always overwritten with the latest value so the system reminder
+     * surfaces the most-recent context.
+     */
+    recordDenial(toolName, args, reason) {
+        const argHash = canonicalArgHash(args);
+        const key = `${toolName}:${argHash}`;
+        const now = new Date(this.clock());
+        const existing = this.records.get(key);
+        if (existing) {
+            existing.count += 1;
+            existing.lastDeniedAt = now;
+            existing.lastReason = truncateReason(reason);
+            // Re-insert so the iteration order tracks lastDeniedAt (LRU-ish).
+            this.records.delete(key);
+            this.records.set(key, existing);
+            return existing;
+        }
+        if (this.records.size >= DENIAL_TRACKING_MAX_ENTRIES) {
+            // Evict the oldest entry (insertion order = LRU after our delete
+            // + set pattern above). Map iteration order is insertion order
+            // in JS; the first key is the LRU one.
+            const oldestKey = this.records.keys().next().value;
+            if (oldestKey !== undefined) {
+                this.records.delete(oldestKey);
+            }
+        }
+        const record = {
+            key,
+            toolName,
+            argsSummary: summariseArgs(args),
+            firstDeniedAt: now,
+            lastDeniedAt: now,
+            count: 1,
+            lastReason: truncateReason(reason),
+        };
+        this.records.set(key, record);
+        return record;
+    }
+    /**
+     * Snapshot of every recorded denial. Returned in insertion order
+     * (LRU-ish: most-recently-touched at the tail). The caller MUST
+     * treat the array as read-only — mutating it does not affect state.
+     */
+    getDenialHistory() {
+        return Array.from(this.records.values()).map((r) => ({ ...r }));
+    }
+    /** Lookup the record for a specific (tool, args) pair, or undefined. */
+    getPatternFor(toolName, args) {
+        const argHash = canonicalArgHash(args);
+        const key = `${toolName}:${argHash}`;
+        const record = this.records.get(key);
+        return record ? { ...record } : undefined;
+    }
+    /**
+     * Aggregate counts — handy for `/doctor`, `/permissions denials`,
+     * and the system-reminder threshold check.
+     */
+    summary() {
+        let totalDenials = 0;
+        let repeatedPatterns = 0;
+        for (const record of this.records.values()) {
+            totalDenials += record.count;
+            if (record.count >= DENIAL_REMINDER_THRESHOLD)
+                repeatedPatterns += 1;
+        }
+        return {
+            totalDenials,
+            uniquePatterns: this.records.size,
+            repeatedPatterns,
+        };
+    }
+    /** Drop every recorded denial. Called on session end. */
+    clear() {
+        this.records.clear();
+    }
+    /** Number of distinct (tool, args) pairs currently tracked. */
+    size() {
+        return this.records.size;
+    }
+}
+/**
+ * Build the operator-facing system-reminder block. Returns an empty
+ * string when no record meets the threshold — the caller short-circuits
+ * the splice in that case.
+ *
+ * Rendered shape:
+ *
+ *   <denial-context>
+ *     - Tool `bash` denied 3 times in this session.
+ *       Last reason: HOOK_BLOCKED: PreToolUse refused (exit=1).
+ *       Args: {"command":"rm -rf node_modules"}
+ *       Do not retry without operator intervention.
+ *     - Tool `edit` denied 2 times in this session.
+ *       Last reason: STALE_READ: file changed since last read.
+ *       Args: {"path":"src/index.ts","oldString":"..."}
+ *       Do not retry without operator intervention.
+ *   </denial-context>
+ *
+ * Determinism: same snapshot always produces the same block. We sort
+ * entries by `count` descending then `lastDeniedAt` descending so the
+ * most-pressing patterns surface first.
+ */
+export function buildDenialContext(state) {
+    const records = state.getDenialHistory()
+        .filter((r) => r.count >= DENIAL_REMINDER_THRESHOLD)
+        .sort((a, b) => {
+        if (b.count !== a.count)
+            return b.count - a.count;
+        return b.lastDeniedAt.getTime() - a.lastDeniedAt.getTime();
+    });
+    if (records.length === 0)
+        return '';
+    const lines = ['<denial-context>'];
+    for (const record of records) {
+        lines.push(`  - Tool \`${record.toolName}\` denied ${record.count} times in this session.`);
+        lines.push(`    Last reason: ${record.lastReason}`);
+        lines.push(`    Args: ${record.argsSummary}`);
+        lines.push('    Do not retry without operator intervention.');
+    }
+    lines.push('</denial-context>');
+    return lines.join('\n');
+}
+/**
+ * Canonical sha256 of the args. Object keys are sorted recursively
+ * before stringification so `{a:1,b:2}` and `{b:2,a:1}` hash to the
+ * same value. Undefined values + functions are stripped (JSON.stringify
+ * already does this); circular refs throw — the caller is expected to
+ * pass plain JSON objects (every Pugi tool argument set is a JSON
+ * object by contract).
+ *
+ * Returns the full 64-char hex digest. The denial key prepends the
+ * tool name (`<tool>:<hash>`) so a hash collision across tools cannot
+ * confuse the matcher.
+ */
+export function canonicalArgHash(args) {
+    const canonical = canonicalize(args);
+    const hash = createHash('sha256');
+    hash.update(canonical);
+    return hash.digest('hex');
+}
+function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    if (value === undefined)
+        return 'null';
+    const t = typeof value;
+    if (t === 'string')
+        return JSON.stringify(value);
+    if (t === 'number' || t === 'boolean')
+        return JSON.stringify(value);
+    if (t === 'bigint')
+        return JSON.stringify(value.toString());
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => canonicalize(entry)).join(',')}]`;
+    }
+    if (t === 'object') {
+        const obj = value;
+        const keys = Object.keys(obj).sort();
+        const parts = keys.map((k) => `${JSON.stringify(k)}:${canonicalize(obj[k])}`);
+        return `{${parts.join(',')}}`;
+    }
+    // Functions / symbols — neither should reach here for tool args.
+    // Stringify defensively so the hash is stable.
+    return JSON.stringify(String(value));
+}
+/**
+ * Short, operator-readable preview of the args object. Cap so a
+ * 32 KB write payload does not blow up the reminder block. Falls back
+ * к `[non-JSON args]` when stringification fails (e.g. a circular ref
+ * snuck through — unlikely for tool args by contract).
+ */
+function summariseArgs(args) {
+    let stringified;
+    try {
+        stringified = JSON.stringify(args);
+    }
+    catch {
+        return '[non-JSON args]';
+    }
+    if (stringified === undefined)
+        return '{}';
+    if (stringified.length <= DENIAL_ARGS_SUMMARY_BYTES)
+        return stringified;
+    return `${stringified.slice(0, DENIAL_ARGS_SUMMARY_BYTES)}…`;
+}
+/** Cap reason at a sane length so a hook script's stdout cannot flood the reminder. */
+function truncateReason(reason, cap = 240) {
+    if (reason.length <= cap)
+        return reason;
+    return `${reason.slice(0, cap)}…`;
+}
+//# sourceMappingURL=state.js.map

package/dist/core/diagnostics/probes/denial-tracking.js

@@ -0,0 +1,57 @@
+/**
+ * α7 L11 (2026-05-27) — DENIAL TRACKING probe for `pugi doctor`.
+ *
+ * Reports the current session's denial pressure: total denial count,
+ * unique (tool, args) patterns, and how many patterns have repeated
+ * past the reminder threshold. Operators read this to spot:
+ *
+ *   - A hook script refusing more dispatches than expected (mis-
+ *     configured `.pugi/hooks.json`).
+ *   - Plan-mode runs where the model keeps trying mutating tools
+ *     (a sign the prompt is not anchoring it correctly).
+ *   - Stale-read loops indicating concurrent multi-agent writes.
+ *
+ * Status semantics:
+ *
+ *   - `ok` when the tracker is empty OR carries denials but none have
+ *     repeated past the threshold. Single denials are normal session
+ *     hygiene; repeats are the signal.
+ *   - `warn` when one or more patterns repeated >= the reminder
+ *     threshold. The probe surfaces the count so the operator can act.
+ *   - `skipped` when no tracker is wired (e.g. doctor invoked outside
+ *     a live REPL session, top-level `pugi doctor`).
+ *
+ * Pure: takes a tracker snapshot — no I/O, no module-level state.
+ */
+import { DENIAL_REMINDER_THRESHOLD, } from '../../denial-tracking/state.js';
+export function probeDenialTracking(deps) {
+    if (!deps.tracker) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'skipped',
+            detail: 'No live session — run `pugi doctor` from inside the REPL to see denials.',
+        };
+    }
+    const summary = deps.tracker.summary();
+    if (summary.totalDenials === 0) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'ok',
+            detail: 'No tool denials this session.',
+        };
+    }
+    if (summary.repeatedPatterns === 0) {
+        return {
+            name: 'DENIAL TRACKING',
+            status: 'ok',
+            detail: `${summary.totalDenials} denial(s), ${summary.uniquePatterns} unique pattern(s), none repeated.`,
+        };
+    }
+    return {
+        name: 'DENIAL TRACKING',
+        status: 'warn',
+        detail: `${summary.totalDenials} denial(s), ${summary.repeatedPatterns} pattern(s) repeated >= ${DENIAL_REMINDER_THRESHOLD}.`,
+        remediation: 'Inspect via `/permissions denials` (when L6 lands) or check `.pugi/events.jsonl` for the latest refusals.',
+    };
+}
+//# sourceMappingURL=denial-tracking.js.map