compact-agent 1.27.2 → 1.28.0

package/bin/crowcoder.js

@@ -2,10 +2,9 @@
 // In-process best-effort: override process.emitWarning to drop DEP0040.
 // Catches the warning when it's emitted late (after this runs), but does NOT
 // catch warnings fired during Node's ESM bootstrap (before any user code).
-// For a fully clean stderr, invoke Crowcoder via:
+// For a fully clean stderr, invoke compact-agent via:
 //   node --no-deprecation bin/crowcoder.js
-//   NODE_OPTIONS=--no-deprecation crowcoder
-//   oag chat                                # already passes --no-deprecation
+//   NODE_OPTIONS=--no-deprecation compact-agent
 (() => {
   const orig = process.emitWarning;
   process.emitWarning = function patched(warning, ...rest) {
@@ -16,4 +15,50 @@
     return orig.call(this, warning, ...rest);
   };
 })();
+
+// ── --debug [level] flag ───────────────────────────────────
+// Parse here at the entry point so that the env var is set BEFORE
+// any module-level code in dist/index.js reads it. The debug
+// instrumentation in src/debug.ts checks $COMPACT_AGENT_DEBUG at
+// init time; setting it from argv keeps the implementation in one
+// place (env var as single source of truth).
+//
+// Accepted forms:
+//   --debug              → info
+//   --debug=trace        → trace
+//   --debug trace        → trace
+//   --debug=on           → info  (alias)
+//   --debug=off          → off
+//
+// Invalid levels fall back to 'info' with a one-line stderr notice.
+(() => {
+  const argv = process.argv;
+  const VALID = new Set(['off', 'info', 'debug', 'trace', 'on']);
+  for (let i = 2; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--debug') {
+      const next = argv[i + 1];
+      if (next && VALID.has(next.toLowerCase())) {
+        process.env.COMPACT_AGENT_DEBUG = next.toLowerCase() === 'on' ? 'info' : next.toLowerCase();
+        argv.splice(i, 2);
+      } else {
+        process.env.COMPACT_AGENT_DEBUG = 'info';
+        argv.splice(i, 1);
+      }
+      break;
+    }
+    if (a && a.startsWith('--debug=')) {
+      const lvl = a.slice('--debug='.length).toLowerCase();
+      if (VALID.has(lvl)) {
+        process.env.COMPACT_AGENT_DEBUG = lvl === 'on' ? 'info' : lvl;
+      } else {
+        process.stderr.write(`[compact-agent] unknown --debug level "${lvl}"; defaulting to 'info'.\n`);
+        process.env.COMPACT_AGENT_DEBUG = 'info';
+      }
+      argv.splice(i, 1);
+      break;
+    }
+  }
+})();
+
 import('../dist/index.js');

package/dist/debug.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Debug instrumentation.
+ *
+ * Writes NDJSON event records to ~/.compact-agent/debug/<sessionId>.jsonl
+ * for offline analysis. Designed so that with `level === 'off'` (the
+ * default), every emit() call is a single boolean check + early return —
+ * zero file I/O and negligible CPU on the hot path.
+ *
+ * Levels (each includes everything below it):
+ *
+ *   off    — no logging (default; for end users)
+ *   info   — high-signal milestones: session start/end, API request/
+ *            response summary, tool call summary, hook block, stream
+ *            loop detection, mode/perm/model change
+ *   debug  — info + per-tool argument previews, per-chunk stream stats,
+ *            per-keypress trace at REPL, slash command dispatch
+ *   trace  — debug + raw API payloads (truncated), full tool I/O,
+ *            internal state transitions
+ *
+ * Toggling:
+ *
+ *   - CLI flag:     compact-agent --debug [level]
+ *   - Env var:      COMPACT_AGENT_DEBUG=trace
+ *   - Slash cmd:    /debug on [level]   /debug off   /debug tail [n]
+ *
+ * The event log is append-only. Each session gets its own file so
+ * concurrent compact-agent instances don't fight over a single sink.
+ * Files are subject to the same 24h GC window as the gateguard state.
+ *
+ * Design notes:
+ *
+ *   - We deliberately don't use console.error or any third-party logger.
+ *     console.error pollutes the user's REPL view; a third-party logger
+ *     adds startup time + a transitive dep. Direct fs.appendFileSync to
+ *     an NDJSON file is the lowest-overhead path that's also trivially
+ *     consumable by jq / Python / another agent.
+ *
+ *   - We DO accept the cost of synchronous appendFileSync — debug
+ *     instrumentation is rarely on the hot path of perf-sensitive code,
+ *     and the cost of one syscall per event (only when level >= info)
+ *     is dwarfed by the cost of the API call the event describes.
+ *
+ *   - Stack traces are NOT captured automatically. Each emit() takes an
+ *     explicit `data` object — callers include whatever they need.
+ *     Auto-traces would balloon the log file for limited extra value.
+ */
+export type DebugLevel = 'off' | 'info' | 'debug' | 'trace';
+/**
+ * Initialize debug at session start. Resolves level from (in priority order):
+ *   1. explicit `level` arg (passed in from --debug flag parsing)
+ *   2. $COMPACT_AGENT_DEBUG env var
+ *   3. existing state.level (typically 'off')
+ *
+ * Sets the log file path under ~/.compact-agent/debug/<sessionId>.jsonl
+ * but doesn't touch the filesystem until the first emit (lazy create).
+ */
+export declare function initDebug(sessionId: string, explicitLevel?: DebugLevel | string): void;
+/**
+ * Emit a debug event. The fastest path is the early-return when the
+ * configured level is below the event's level — a single integer compare.
+ *
+ * `data` is shallow-cloned to a JSON-safe form. Functions, BigInts, and
+ * circular refs are stripped via the replacer to keep emit cheap and
+ * crash-free regardless of what callers throw in.
+ */
+export declare function emit(eventLevel: Exclude<DebugLevel, 'off'>, eventName: string, data?: Record<string, unknown>): void;
+/**
+ * Public read-only state snapshot for /debug status output.
+ */
+export declare function getDebugStatus(): {
+    level: DebugLevel;
+    logPath: string | null;
+    eventCount: number;
+    uptimeMs: number;
+};
+/**
+ * Change the active debug level at runtime. Called from /debug on/off.
+ * If transitioning OFF → non-off, we ensure the log dir exists; if
+ * transitioning to OFF we leave the file alone (it's append-only and
+ * read by external tools).
+ */
+export declare function setDebugLevel(level: DebugLevel): void;
+/**
+ * Read the last N events from the current session's log. Used by
+ * /debug tail. Returns lines as JSON strings (one per event); the
+ * caller can pretty-print or pass through to jq.
+ */
+export declare function tailDebug(n: number): string[];
+/**
+ * True if any non-off level is active. Use this to gate expensive
+ * data preparation that you don't want to run when debug is off:
+ *
+ *   if (isDebugActive()) {
+ *     emit('debug', 'event-name', { detail: computeExpensiveDetail() });
+ *   }
+ */
+export declare function isDebugActive(): boolean;

package/dist/debug.js

@@ -0,0 +1,217 @@
+/**
+ * Debug instrumentation.
+ *
+ * Writes NDJSON event records to ~/.compact-agent/debug/<sessionId>.jsonl
+ * for offline analysis. Designed so that with `level === 'off'` (the
+ * default), every emit() call is a single boolean check + early return —
+ * zero file I/O and negligible CPU on the hot path.
+ *
+ * Levels (each includes everything below it):
+ *
+ *   off    — no logging (default; for end users)
+ *   info   — high-signal milestones: session start/end, API request/
+ *            response summary, tool call summary, hook block, stream
+ *            loop detection, mode/perm/model change
+ *   debug  — info + per-tool argument previews, per-chunk stream stats,
+ *            per-keypress trace at REPL, slash command dispatch
+ *   trace  — debug + raw API payloads (truncated), full tool I/O,
+ *            internal state transitions
+ *
+ * Toggling:
+ *
+ *   - CLI flag:     compact-agent --debug [level]
+ *   - Env var:      COMPACT_AGENT_DEBUG=trace
+ *   - Slash cmd:    /debug on [level]   /debug off   /debug tail [n]
+ *
+ * The event log is append-only. Each session gets its own file so
+ * concurrent compact-agent instances don't fight over a single sink.
+ * Files are subject to the same 24h GC window as the gateguard state.
+ *
+ * Design notes:
+ *
+ *   - We deliberately don't use console.error or any third-party logger.
+ *     console.error pollutes the user's REPL view; a third-party logger
+ *     adds startup time + a transitive dep. Direct fs.appendFileSync to
+ *     an NDJSON file is the lowest-overhead path that's also trivially
+ *     consumable by jq / Python / another agent.
+ *
+ *   - We DO accept the cost of synchronous appendFileSync — debug
+ *     instrumentation is rarely on the hot path of perf-sensitive code,
+ *     and the cost of one syscall per event (only when level >= info)
+ *     is dwarfed by the cost of the API call the event describes.
+ *
+ *   - Stack traces are NOT captured automatically. Each emit() takes an
+ *     explicit `data` object — callers include whatever they need.
+ *     Auto-traces would balloon the log file for limited extra value.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { getHomeStateDir } from './config.js';
+const LEVEL_ORDER = {
+    off: 0,
+    info: 1,
+    debug: 2,
+    trace: 3,
+};
+const state = {
+    level: 'off',
+    sessionId: null,
+    logPath: null,
+    eventCount: 0,
+    startedAt: Date.now(),
+};
+/**
+ * Initialize debug at session start. Resolves level from (in priority order):
+ *   1. explicit `level` arg (passed in from --debug flag parsing)
+ *   2. $COMPACT_AGENT_DEBUG env var
+ *   3. existing state.level (typically 'off')
+ *
+ * Sets the log file path under ~/.compact-agent/debug/<sessionId>.jsonl
+ * but doesn't touch the filesystem until the first emit (lazy create).
+ */
+export function initDebug(sessionId, explicitLevel) {
+    state.sessionId = sessionId;
+    const envLevel = process.env.COMPACT_AGENT_DEBUG;
+    const requested = (explicitLevel || envLevel || state.level || 'off').toLowerCase();
+    state.level = isValidLevel(requested) ? requested : 'off';
+    if (state.level !== 'off') {
+        const dir = join(getHomeStateDir(), 'debug');
+        state.logPath = join(dir, `${sessionId}.jsonl`);
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch { /* if we can't create the dir, emit() will fail-safe */ }
+        // GC: drop any debug files older than 24h.
+        try {
+            const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+            for (const name of readdirSync(dir)) {
+                const p = join(dir, name);
+                try {
+                    const s = statSync(p);
+                    if (s.mtimeMs < cutoff)
+                        unlinkSync(p);
+                }
+                catch { /* noop */ }
+            }
+        }
+        catch { /* noop */ }
+        emit('info', 'debug.init', { level: state.level, sessionId });
+    }
+}
+function isValidLevel(s) {
+    return s === 'off' || s === 'info' || s === 'debug' || s === 'trace';
+}
+/**
+ * Emit a debug event. The fastest path is the early-return when the
+ * configured level is below the event's level — a single integer compare.
+ *
+ * `data` is shallow-cloned to a JSON-safe form. Functions, BigInts, and
+ * circular refs are stripped via the replacer to keep emit cheap and
+ * crash-free regardless of what callers throw in.
+ */
+export function emit(eventLevel, eventName, data) {
+    if (LEVEL_ORDER[state.level] < LEVEL_ORDER[eventLevel])
+        return;
+    if (!state.logPath)
+        return;
+    const record = {
+        t: new Date().toISOString(),
+        rel: Date.now() - state.startedAt,
+        lvl: eventLevel,
+        ev: eventName,
+        ...(data ? { data: safeClone(data) } : {}),
+    };
+    try {
+        appendFileSync(state.logPath, JSON.stringify(record) + '\n', 'utf-8');
+        state.eventCount++;
+    }
+    catch {
+        // If the log file write fails, we don't want to spam errors into
+        // the REPL — silently drop the event. The user can re-enable via
+        // /debug if the underlying issue is fixed.
+    }
+}
+/**
+ * JSON.stringify replacer that prevents crashes on circular refs,
+ * BigInt, functions, and overly-large strings. Truncates strings to
+ * 8KB so a single huge prompt or tool output doesn't bloat the log.
+ */
+function safeClone(input) {
+    const seen = new WeakSet();
+    return JSON.parse(JSON.stringify(input, (_key, value) => {
+        if (typeof value === 'bigint')
+            return value.toString() + 'n';
+        if (typeof value === 'function')
+            return '[function]';
+        if (typeof value === 'string' && value.length > 8192) {
+            return value.slice(0, 8192) + `…[truncated ${value.length - 8192}b]`;
+        }
+        if (value && typeof value === 'object') {
+            if (seen.has(value))
+                return '[circular]';
+            seen.add(value);
+        }
+        return value;
+    }));
+}
+/**
+ * Public read-only state snapshot for /debug status output.
+ */
+export function getDebugStatus() {
+    return {
+        level: state.level,
+        logPath: state.logPath,
+        eventCount: state.eventCount,
+        uptimeMs: Date.now() - state.startedAt,
+    };
+}
+/**
+ * Change the active debug level at runtime. Called from /debug on/off.
+ * If transitioning OFF → non-off, we ensure the log dir exists; if
+ * transitioning to OFF we leave the file alone (it's append-only and
+ * read by external tools).
+ */
+export function setDebugLevel(level) {
+    const old = state.level;
+    state.level = level;
+    if (level !== 'off' && !state.logPath && state.sessionId) {
+        const dir = join(getHomeStateDir(), 'debug');
+        state.logPath = join(dir, `${state.sessionId}.jsonl`);
+        try {
+            mkdirSync(dir, { recursive: true });
+        }
+        catch { /* noop */ }
+    }
+    if (level !== 'off' && old !== level) {
+        emit('info', 'debug.level-change', { from: old, to: level });
+    }
+}
+/**
+ * Read the last N events from the current session's log. Used by
+ * /debug tail. Returns lines as JSON strings (one per event); the
+ * caller can pretty-print or pass through to jq.
+ */
+export function tailDebug(n) {
+    if (!state.logPath || !existsSync(state.logPath))
+        return [];
+    try {
+        const raw = readFileSync(state.logPath, 'utf-8');
+        const lines = raw.split('\n').filter((l) => l.trim().length > 0);
+        return lines.slice(-Math.max(1, n));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * True if any non-off level is active. Use this to gate expensive
+ * data preparation that you don't want to run when debug is off:
+ *
+ *   if (isDebugActive()) {
+ *     emit('debug', 'event-name', { detail: computeExpensiveDetail() });
+ *   }
+ */
+export function isDebugActive() {
+    return state.level !== 'off';
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACjH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAI9C,MAAM,WAAW,GAA+B;IAC9C,GAAG,EAAE,CAAC;IACN,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;CACT,CAAC;AAUF,MAAM,KAAK,GAAe;IACxB,KAAK,EAAE,KAAK;IACZ,SAAS,EAAE,IAAI;IACf,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE;CACtB,CAAC;AAEF;;;;;;;;GAQG;AACH,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,aAAmC;IAC9E,KAAK,CAAC,SAAS,GAAG,SAAS,CAAC;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;IACjD,MAAM,SAAS,GAAG,CAAC,aAAa,IAAI,QAAQ,IAAI,KAAK,CAAC,KAAK,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAC;IACpF,KAAK,CAAC,KAAK,GAAG,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC;IAE1D,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;QAC7C,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,QAAQ,CAAC,CAAC;QAChD,IAAI,CAAC;YACH,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC,CAAC,uDAAuD,CAAC,CAAC;QACnE,2CAA2C;QAC3C,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;YAChD,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACpC,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;gBAC1B,IAAI,CAAC;oBACH,MAAM,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;oBACtB,IAAI,CAAC,CAAC,OAAO,GAAG,MAAM;wBAAE,UAAU,CAAC,CAAC,CAAC,CAAC;gBACxC,CAAC;gBAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;YACxB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;QACtB,IAAI,CAAC,MAAM,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,SAAS,YAAY,CAAC,CAAS;IAC7B,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,MAAM,IAAI,CAAC,KAAK,OAAO,IAAI,CAAC,KAAK,OAAO,CAAC;AACvE,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAClB,UAAsC,EACtC,SAAiB,EACjB,IAA8B;IAE9B,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,WAAW,CAAC,UAAU,CAAC;QAAE,OAAO;IAC/D,IAAI,CAAC,KAAK,CAAC,OAAO;QAAE,OAAO;IAC3B,MAAM,MAAM,GAAG;QACb,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC3B,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS;QACjC,GAAG,EAAE,UAAU;QACf,EAAE,EAAE,SAAS;QACb,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC3C,CAAC;IACF,IAAI,CAAC;QACH,cAAc,CAAC,KAAK,CAAC,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG,IAAI,EAAE,OAAO,CAAC,CAAC;QACtE,KAAK,CAAC,UAAU,EAAE,CAAC;IACrB,CAAC;IAAC,MAAM,CAAC;QACP,iEAAiE;QACjE,iEAAiE;QACjE,2CAA2C;IAC7C,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,KAAc;IAC/B,MAAM,IAAI,GAAG,IAAI,OAAO,EAAU,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CACf,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACpC,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC,QAAQ,EAAE,GAAG,GAAG,CAAC;QAC7D,IAAI,OAAO,KAAK,KAAK,UAAU;YAAE,OAAO,YAAY,CAAC;QACrD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,MAAM,GAAG,IAAI,EAAE,CAAC;YACrD,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,eAAe,KAAK,CAAC,MAAM,GAAG,IAAI,IAAI,CAAC;QACvE,CAAC;QACD,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvC,IAAI,IAAI,CAAC,GAAG,CAAC,KAAe,CAAC;gBAAE,OAAO,YAAY,CAAC;YACnD,IAAI,CAAC,GAAG,CAAC,KAAe,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC,CACH,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,cAAc;IAM5B,OAAO;QACL,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,OAAO,EAAE,KAAK,CAAC,OAAO;QACtB,UAAU,EAAE,KAAK,CAAC,UAAU;QAC5B,QAAQ,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS;KACvC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,KAAiB;IAC7C,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC;IACxB,KAAK,CAAC,KAAK,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,KAAK,KAAK,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QACzD,MAAM,GAAG,GAAG,IAAI,CAAC,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;QAC7C,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,QAAQ,CAAC,CAAC;QACtD,IAAI,CAAC;YAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,UAAU,CAAC,CAAC;IACnE,CAAC;IACD,IAAI,KAAK,KAAK,KAAK,IAAI,GAAG,KAAK,KAAK,EAAE,CAAC;QACrC,IAAI,CAAC,MAAM,EAAE,oBAAoB,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS;IACjC,IAAI,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAC;IAC5D,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjD,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACjE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,KAAK,CAAC,KAAK,KAAK,KAAK,CAAC;AAC/B,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@ import { readFileSync as fsReadFileSync, writeFileSync as fsWriteFileSync, unlin
 import { tmpdir } from 'node:os';
 import { join as pathJoin } from 'node:path';
 import { spawnSync } from 'node:child_process';
+import { initDebug, emit as dbgEmit, setDebugLevel, getDebugStatus, tailDebug } from './debug.js';
 import chalk from 'chalk';
 import { loadConfig, saveConfig, configExists, getConfigDir } from './config.js';
 import { resetClient } from './api.js';
@@ -544,6 +545,72 @@ export function handleSlashCommand(input, config, messages, session, mode) {
             console.log(chalk.dim(`  Sending ${result.length} chars from editor…`));
             return { handled: true, injectPrompt: result };
         }
+        // ── Debug — toggle instrumentation + tail event log ──
+        // Surface for the NDJSON debug stream written to
+        // ~/.compact-agent/debug/<sessionId>.jsonl. Used by reviewers
+        // driving the agent + by users diagnosing their own issues.
+        //
+        //   /debug              show current level + log path + event count
+        //   /debug on [level]   turn instrumentation on (default level: info)
+        //   /debug off          turn instrumentation off (existing log file is kept)
+        //   /debug tail [N]     print the last N events (default 20) inline
+        case '/debug': {
+            const parts = args.trim().split(/\s+/).filter(Boolean);
+            const sub = (parts[0] || '').toLowerCase();
+            if (!sub) {
+                const s = getDebugStatus();
+                console.log(chalk.dim(`  Debug level: ${s.level}`));
+                console.log(chalk.dim(`  Log file:    ${s.logPath || '(no log — level is off)'}`));
+                console.log(chalk.dim(`  Events:      ${s.eventCount} this session`));
+                console.log(chalk.dim(`  Uptime:      ${(s.uptimeMs / 1000).toFixed(1)}s`));
+                console.log('');
+                console.log(chalk.dim(`  /debug on [info|debug|trace]`));
+                console.log(chalk.dim(`  /debug off`));
+                console.log(chalk.dim(`  /debug tail [N]`));
+                return { handled: true };
+            }
+            if (sub === 'off') {
+                setDebugLevel('off');
+                console.log(chalk.green('  Debug: off'));
+                return { handled: true };
+            }
+            if (sub === 'on') {
+                const lvl = (parts[1] || 'info').toLowerCase();
+                if (lvl !== 'info' && lvl !== 'debug' && lvl !== 'trace') {
+                    console.log(chalk.yellow(`  Unknown level "${lvl}". Use info, debug, or trace.`));
+                    return { handled: true };
+                }
+                setDebugLevel(lvl);
+                const s = getDebugStatus();
+                console.log(chalk.green(`  Debug: ${lvl} — writing to ${s.logPath}`));
+                return { handled: true };
+            }
+            if (sub === 'tail') {
+                const n = parseInt(parts[1] || '20', 10);
+                const lines = tailDebug(Number.isFinite(n) && n > 0 ? n : 20);
+                if (lines.length === 0) {
+                    console.log(chalk.dim('  (no events — turn on with /debug on)'));
+                    return { handled: true };
+                }
+                console.log(chalk.dim(`  Last ${lines.length} debug events:`));
+                for (const ln of lines) {
+                    try {
+                        const rec = JSON.parse(ln);
+                        const ts = String(rec.rel || 0).padStart(6) + 'ms';
+                        const lvl = (rec.lvl || '').toUpperCase().padEnd(5);
+                        const ev = rec.ev || '';
+                        const d = rec.data ? '  ' + JSON.stringify(rec.data).slice(0, 120) : '';
+                        console.log(chalk.dim(`    ${ts}  ${lvl}  ${ev}${d}`));
+                    }
+                    catch {
+                        console.log(chalk.dim(`    ${ln.slice(0, 200)}`));
+                    }
+                }
+                return { handled: true };
+            }
+            console.log(chalk.yellow(`  Unknown /debug subcommand "${sub}". Try: /debug, /debug on, /debug off, /debug tail`));
+            return { handled: true };
+        }
         // ── History ───────────────────────────────────────
         case '/history': {
             const stats = getCompactionStats(messages);
@@ -2203,6 +2270,19 @@ async function main() {
     // Create session
     const mode = { current: 'dev' };
     const session = createSession(process.cwd(), config.model, config.provider, mode.current);
+    // ── Debug instrumentation ─────────────────────────────────
+    // Initialize early so subsequent emit() calls land in the right file.
+    // Reads $COMPACT_AGENT_DEBUG which bin/crowcoder.js may have set from
+    // the --debug CLI flag. Level 'off' is a no-op; non-off opens an
+    // NDJSON log at ~/.compact-agent/debug/<sessionId>.jsonl.
+    initDebug(session.id);
+    dbgEmit('info', 'session.start', {
+        cwd: process.cwd(),
+        model: config.model,
+        provider: config.provider,
+        mode: mode.current,
+        permissionMode: config.permissionMode,
+    });
     const messages = [];
     // Session start hook + memory persistence
     await runHooks({ event: 'SessionStart', sessionId: session.id, cwd: process.cwd(), permissionMode: config.permissionMode });
@@ -2868,6 +2948,8 @@ async function main() {
         }
         // Slash commands
         if (trimmed.startsWith('/')) {
+            // Truncate arg preview so debug logs don't blow up on /editor seeds etc.
+            dbgEmit('debug', 'slash.dispatch', { input: trimmed.slice(0, 200) });
             const result = handleSlashCommand(trimmed, config, messages, session, mode);
             if (result.shouldExit)
                 break;