@gaunt-sloth/core 2.0.0-alpha.8 → 2.0.0-beta.0

package/dist/utils/debugDump.js

@@ -0,0 +1,381 @@
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { inspect } from 'node:util';
+import { ensureGlobalGslothDir } from '#src/utils/globalConfigUtils.js';
+import { env, getSlothVersion } from '#src/utils/systemUtils.js';
+import { getDebugLogBuffer } from '#src/utils/debugUtils.js';
+import { REDACTED, collectSecretValues, redactText, redactValue, } from '#src/utils/redactSecrets.js';
+/**
+ * Best-effort git repo state (branch/remote/dirty). Uses `execFileSync` — NOT the existing
+ * `execAsync` helper in systemUtils.ts (a promisified wrapper used elsewhere for `gh` calls) —
+ * because `SlashCommand.run()` is fully synchronous (no Promise support in the TUI's registry or
+ * dispatcher). Fails soft: any failure (not inside a repo, `git` missing, a detached/bare repo
+ * with no remote, etc.) returns `undefined` rather than throwing, so the command never errors —
+ * the git-state file is simply omitted from the archive.
+ */
+function collectGitState(cwd) {
+    try {
+        const run = (args) => execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+        const branch = run(['rev-parse', '--abbrev-ref', 'HEAD']);
+        let remote;
+        try {
+            remote = run(['remote', 'get-url', 'origin']);
+        }
+        catch {
+            remote = undefined; // no `origin` remote configured — not fatal, just omit it
+        }
+        const status = run(['status', '--porcelain']);
+        return { branch, remote, dirty: status.length > 0 };
+    }
+    catch {
+        return undefined; // not inside a git repo (or git unavailable) — omit the file entirely
+    }
+}
+/**
+ * Serialize a value as pretty JSON, tolerating the non-JSON-safe shapes real session state can
+ * contain (e.g. the resolved `GthConfig.llm` is a live LangChain client, not plain data):
+ * functions/bigints are stringified and circular references are broken rather than throwing.
+ * Falls back to `util.inspect` if `JSON.stringify` still fails for some other reason, so writing
+ * the dump can never throw partway through the archive.
+ *
+ * QA-6: `JSON.stringify` returns `undefined` (not a string) for a handful of top-level inputs —
+ * notably `undefined` itself, which `DebugDumpInput.config` legitimately is when the caller has
+ * no resolved config (verified live via the e2e fixture harness, which wires the real writer with
+ * `config` omitted). Passing `undefined` straight to `writeFileSync` throws
+ * `ERR_INVALID_ARG_TYPE`, defeating the "never throw partway through the archive" contract this
+ * function documents. Fall back to the literal `'null'` in that case, same as `JSON.stringify`
+ * would for a *nested* `undefined` value.
+ */
+function safeStringify(value) {
+    const seen = new WeakSet();
+    try {
+        const json = JSON.stringify(value, (_key, val) => {
+            if (typeof val === 'function')
+                return `[Function: ${val.name || 'anonymous'}]`;
+            if (typeof val === 'bigint')
+                return val.toString();
+            if (val && typeof val === 'object') {
+                if (seen.has(val))
+                    return '[Circular]';
+                seen.add(val);
+            }
+            return val;
+        }, 2);
+        return json ?? 'null';
+    }
+    catch {
+        return inspect(value, { showHidden: false, depth: 5, colors: false });
+    }
+}
+/**
+ * The filesystem-safe directory-name segment for one dump: the ISO timestamp with `:` and `.`
+ * (illegal on Windows, noisy everywhere) replaced by `-`. This is the ONLY path component
+ * debugDump generates — and the only one it is responsible for sanitizing. The parent it is joined
+ * under (the global `~/.gsloth` dir) is supplied by the environment and may legitimately carry a
+ * drive-letter colon on Windows (`C:\…`), which is not ours to strip. Exported so the invariant
+ * "the generated segment is colon-free" is testable on any platform without asserting anything
+ * about the (platform-dependent) parent path (GS2-50).
+ */
+export function debugDumpDirName(date = new Date()) {
+    return date.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * GS2-54 (gap 3) — a live LangChain chat model is detected structurally, NOT by field name: a real
+ * `BaseChatModel` exposes `_llmType()` and `invoke()` as functions. This duck-type is the LOAD-BEARING
+ * invariant that lets us strip a *live* model to a descriptor (below) WITHOUT also flattening a plain
+ * `{ type, model, apiKey }` config object — the latter must keep flowing through {@link redactValue}'s
+ * field-masking (key kept, value masked). Do NOT "simplify" this into an unconditional strip.
+ */
+function isLiveChatModel(llm) {
+    if (llm == null || typeof llm !== 'object')
+        return false;
+    const m = llm;
+    return typeof m._llmType === 'function' || typeof m.invoke === 'function';
+}
+/**
+ * GS2-54 (gap 3) — a short, secret-free descriptor for a live chat model, mirroring the spirit of
+ * `configCommand.ts`'s `redactConfigForPrint`. Never returns the live object or any of its internals
+ * (client instances, cached kwargs, inline keys) — only a `type` + `model` label. Each field probe
+ * is guarded so a hostile/exotic getter can't throw out of here.
+ */
+function describeLiveModel(config, llm) {
+    const m = llm;
+    let type = 'unknown';
+    try {
+        const t = (typeof m._llmType === 'function' ? m._llmType() : undefined) ??
+            (Array.isArray(m.lc_namespace) ? m.lc_namespace.join('/') : undefined) ??
+            (typeof config.type === 'string'
+                ? config.type
+                : undefined) ??
+            m.constructor?.name;
+        if (typeof t === 'string' && t.length > 0)
+            type = t;
+    }
+    catch {
+        // keep 'unknown' — a throwing getter must not defeat the strip
+    }
+    let model = 'unknown';
+    try {
+        const md = config.modelDisplayName;
+        const mdl = (typeof md === 'string' && md.length > 0 ? md : undefined) ??
+            (typeof m.model === 'string' ? m.model : undefined) ??
+            (typeof m.modelName === 'string' ? m.modelName : undefined);
+        if (typeof mdl === 'string' && mdl.length > 0)
+            model = mdl;
+    }
+    catch {
+        // keep 'unknown'
+    }
+    return { type, model };
+}
+/**
+ * GS2-54 (gap 3) + GS2-66 (residual 3) — defense-in-depth for the CONFIG artifact: return a shallow
+ * clone of `config` with the LIVE instances stripped to short descriptors so their large internal
+ * surface (client objects, cached kwargs, inline keys, and non-secret-NAMED opaque fields the
+ * `caCert` class that field-masking cannot catch) never reaches disk — rather than relying on
+ * {@link redactValue}'s field-masking alone. Mirrors `configCommand.ts`'s `redactConfigForPrint`:
+ *  - a *live* `llm` (a `BaseChatModel`) → a `{ type, model }` descriptor;
+ *  - a `tools` array → `[N tool instance(s)]`;
+ *  - a `middleware` array → `[N middleware]`.
+ * PURE: never mutates the caller's config (a fresh clone is made only if something is stripped).
+ * FAIL-SAFE: on any error, or when a field is absent / not a live instance, that field is left as-is
+ * so {@link redactValue}'s existing GS2-47 masking still applies (never less-redacted). The `llm`,
+ * `tools` and `middleware` strips are independent — `tools`/`middleware` are stripped even when the
+ * config carries no live `llm`.
+ */
+function stripLiveInstancesForConfig(config) {
+    try {
+        if (config == null || typeof config !== 'object' || Array.isArray(config))
+            return config;
+        const record = config;
+        // Clone lazily: only spread into a new object once we know a field is actually being replaced,
+        // so a config with no live instances is returned untouched (===).
+        let out = record;
+        const clone = () => {
+            if (out === record)
+                out = { ...record };
+            return out;
+        };
+        if ('llm' in record && isLiveChatModel(record.llm)) {
+            clone().llm = describeLiveModel(record, record.llm);
+        }
+        // Hoist before the mutating clone() call so TS keeps the `Array` narrowing on `.length`.
+        const tools = record.tools;
+        if (Array.isArray(tools)) {
+            clone().tools = `[${tools.length} tool instance(s)]`;
+        }
+        const middleware = record.middleware;
+        if (Array.isArray(middleware)) {
+            clone().middleware = `[${middleware.length} middleware]`;
+        }
+        return out;
+    }
+    catch {
+        return config; // fail safe: fall back to redactValue over the untouched config
+    }
+}
+/**
+ * GS2-47 — render the CONFIG artifact: {@link redactValue} applies sensitive-field masking (keys
+ * kept, values masked) plus literal/pattern string redaction, then {@link safeStringify}. Fail-safe:
+ * any throw yields the fully-withheld marker rather than raw content ("redact more on error, never
+ * write a raw artifact because redaction hiccuped").
+ *
+ * GS2-54 (gap 3) + GS2-66 (residual 3) — before redaction, {@link stripLiveInstancesForConfig} swaps
+ * a live `llm` for a `{ type, model }` descriptor and the `tools`/`middleware` arrays for count
+ * descriptors, so those live instances' internals never serialize. This runs on a fresh clone only;
+ * the caller's config (and the {@link collectSecretValues} harvest already taken from it) is
+ * untouched, so inline secrets inside those instances are still scrubbed from the OTHER artifacts.
+ */
+function renderConfig(config, redact, secrets) {
+    if (!redact)
+        return safeStringify(config);
+    try {
+        return safeStringify(redactValue(stripLiveInstancesForConfig(config), secrets));
+    }
+    catch {
+        return REDACTED;
+    }
+}
+/**
+ * GS2-47 — render a non-config STRUCTURED artifact (transcript, env, git-state): stringify (never
+ * throws), then literal/pattern-redact the text. Structural field-masking is intentionally NOT
+ * applied here (config-only, per the brief) so a legitimately `token`/`secret`-named field in tool
+ * output is not blanket-masked. {@link redactText} is itself fail-safe.
+ */
+function renderStructured(value, redact, secrets) {
+    const raw = safeStringify(value);
+    return redact ? redactText(raw, secrets) : raw;
+}
+/**
+ * Write one timestamped `/debug-dump` archive under the GLOBAL `~/.gsloth/debug-dumps/<timestamp>/`
+ * (via `ensureGlobalGslothDir()` — mirrors how `resolveHistoryDbPath()` builds its path under the
+ * same dir — NOT the per-project cwd-relative helper of the same name elsewhere in this codebase).
+ * Contains: the full transcript, the resolved config, env/version info, the in-memory debugLog
+ * ring buffer, and (best-effort) git repo state.
+ *
+ * GS2-47 — unless `input.redact === false`, the shared secret-redaction pass
+ * ({@link file://./redactSecrets.ts}) is applied to EVERY artifact before it is written: the literal
+ * values of secret-named env vars + inline config secrets are substituted everywhere, a tight set of
+ * provider-key/auth-header patterns is masked, and the config's sensitive fields are masked in place.
+ * On opt-out the archive is raw and the caller surfaces the loud "may contain secrets" warning.
+ */
+export function writeDebugDump(input) {
+    const redact = input.redact !== false; // default ON; only an explicit `false` opts out
+    const timestamp = debugDumpDirName();
+    const archiveDir = resolve(ensureGlobalGslothDir(), 'debug-dumps', timestamp);
+    mkdirSync(archiveDir, { recursive: true });
+    // Technique 1 (load-bearing): the literal secret values to scrub across ALL artifacts, gathered
+    // from env (by secret-named var) + the config (apiKeyEnvironmentVariable's target + inline
+    // secrets). `env` is the systemUtils accessor (process.env); collection is itself fail-safe.
+    const secrets = redact ? collectSecretValues(input.config, env) : [];
+    writeFileSync(resolve(archiveDir, 'transcript.json'), renderStructured(input.transcript, redact, secrets), 'utf8');
+    writeFileSync(resolve(archiveDir, 'config.json'), renderConfig(input.config, redact, secrets), 'utf8');
+    // GS2-56 — the always-on model-request snapshot: WHAT was actually fed to the model (the thing a
+    // bug report needs, previously omitted whenever the TUI `/debug` panel wasn't open). Written only
+    // when the caller threaded `agent.lastModelRequest` (a model call has happened), so before the
+    // first turn these files are simply absent. Both go through `renderStructured` (literal+pattern
+    // redaction, like transcript.json/env.json) rather than `renderConfig`'s field-masking, so a
+    // legitimately `token`/`secret`-named field inside a tool result or a schema isn't blanket-masked.
+    if (input.modelRequest) {
+        // model-request.json — the composed system prompt + tool defs (with JSON schema) + model params
+        // + tool-choice. `?? {}` keeps the artifact present-but-empty rather than serializing `undefined`.
+        writeFileSync(resolve(archiveDir, 'model-request.json'), renderStructured(input.modelRequest.extras ?? {}, redact, secrets), 'utf8');
+        // model-messages.json — the EXACT messages sent to the model for the last call (post-
+        // summarization / middleware), i.e. what the model actually saw. Deliberately a separate
+        // artifact from transcript.json (the conversation view): the two are distinct arrays.
+        writeFileSync(resolve(archiveDir, 'model-messages.json'), renderStructured(input.modelRequest.messages ?? [], redact, secrets), 'utf8');
+    }
+    // [[TUI-C27]] — approvals.json: the gate's own record of every gated decision, INCLUDING the
+    // approving branch, which previously left no trace anywhere in this archive. Each entry carries
+    // the exact prompt the rater was sent and its raw answer, so a reader can state what the rater was
+    // shown as well as what it said — specifically whether the user's own messages were in its view at
+    // round N, which is the first question anyone asks of a negotiation and the one no artifact here
+    // could answer. Same `renderStructured` pass as transcript.json (see `WriteDebugDumpInput`).
+    // Written only when there is something to write, so a session that gated nothing omits the file
+    // rather than shipping an empty array that reads as "the gate recorded nothing".
+    if (input.approvals && input.approvals.length > 0) {
+        writeFileSync(resolve(archiveDir, 'approvals.json'), renderStructured(input.approvals, redact, secrets), 'utf8');
+    }
+    // getSlothVersion() reads the installed package.json via the install dir set at CLI startup
+    // (setEntryPoint); guarded so a dump can never fail just because that wasn't wired (e.g. an
+    // unusual embedding), falling back to 'unknown'.
+    let gthVersion;
+    try {
+        gthVersion = getSlothVersion();
+    }
+    catch {
+        gthVersion = 'unknown';
+    }
+    const envInfo = {
+        gthVersion,
+        nodeVersion: process.version,
+        platform: process.platform,
+        model: input.modelDisplayName ?? 'unknown',
+    };
+    writeFileSync(resolve(archiveDir, 'env.json'), renderStructured(envInfo, redact, secrets), 'utf8');
+    writeFileSync(resolve(archiveDir, 'debug-log.txt'), redact ? redactText(getDebugLogBuffer().join('\n'), secrets) : getDebugLogBuffer().join('\n'), 'utf8');
+    const gitState = collectGitState(input.cwd ?? process.cwd());
+    if (gitState) {
+        writeFileSync(resolve(archiveDir, 'git-state.json'), renderStructured(gitState, redact, secrets), 'utf8');
+    }
+    return { archiveDir };
+}
+/**
+ * GS2-48 — how many trailing lines of the always-on in-memory debugLog ring buffer
+ * ({@link file://./debugUtils.ts}, cap {@link DEBUG_LOG_BUFFER_MAX} = 1000) the crash snapshot keeps.
+ * The buffer itself is the "always-on capture" the crash handler relies on (nothing is written to
+ * disk until a crash — O(N) memory, zero steady-state I/O); the snapshot copies only this TAIL to
+ * stay MINIMAL (a crash file is a triage artifact, not the full session). 200 is enough to show what
+ * the agent was doing in the moments before death without bloating the file.
+ */
+const CRASH_DEBUG_LOG_TAIL_LINES = 200;
+/**
+ * GS2-48 — flatten a thrown value (or a rejection reason, which need not be an `Error`) into a plain
+ * object BEFORE redaction. `Error.message`/`Error.stack` are NON-ENUMERABLE, so `Object.entries`
+ * (which {@link redactValue} walks with) would silently drop them — the crash file would carry no
+ * error and no stack. Explicitly copying them here is what makes the error survive the redaction pass.
+ * Tolerates a non-Error reason (string / number / object / undefined) without throwing.
+ */
+function normalizeError(error) {
+    if (error instanceof Error) {
+        return { name: error.name, message: error.message, stack: error.stack };
+    }
+    try {
+        return {
+            name: 'NonError',
+            message: typeof error === 'string' ? error : safeStringify(error),
+        };
+    }
+    catch {
+        return { name: 'NonError', message: String(error) };
+    }
+}
+/**
+ * GS2-48 — write a MINIMAL, ALWAYS-REDACTED crash snapshot to
+ * `~/.gsloth/debug-dumps/crash-<timestamp>/crash.json` and return its paths.
+ *
+ * This is the unattended sibling of {@link writeDebugDump}: it fires from the process-level crash
+ * handler ({@link file://./crashHandler.ts}) with no human present, so — unlike `/debug-dump` — it
+ * exposes NO `redact` opt-out. Redaction (GS2-47, hard-dep) is MANDATORY and applied to the whole
+ * snapshot. It reuses this module's location convention (`ensureGlobalGslothDir()` + `debug-dumps/`)
+ * and rendering helpers, but deliberately stays minimal and crash-safe:
+ *  - a SINGLE `crash.json` (not the multi-file interactive archive);
+ *  - it does NOT shell out for git state (a subprocess is unsafe/slow while the process is dying);
+ *  - it keeps only the last {@link CRASH_DEBUG_LOG_TAIL_LINES} debugLog lines and the transcript TAIL.
+ *
+ * Redaction shape (conscious choice): the entire normalized snapshot is passed through
+ * {@link redactValue} in one pass. That is stricter than {@link writeDebugDump}, which uses
+ * {@link redactText} (literal+pattern only) for its non-config artifacts to avoid field-masking a
+ * legitimately `token`/`secret`-named field in tool output. For an unattended crash file the
+ * over-masking is the SAFE direction and buys uniform circular-ref / depth / function handling in
+ * one place, so it is intended, not an oversight. The config subtree is stripped of live instances
+ * first (as `writeDebugDump` does) so a live LLM client's internals never serialize.
+ *
+ * Callers wrap this in their own try/catch (see {@link file://./crashHandler.ts}); it does its best
+ * to be fail-safe internally (`redactValue`/`safeStringify` never throw), but the ONE unavoidably
+ * throwing operation is the `mkdirSync`/`writeFileSync` to disk — an unwritable `~/.gsloth` is what
+ * the handler's degraded path is for.
+ */
+export function writeCrashSnapshot(input) {
+    const crashDir = resolve(ensureGlobalGslothDir(), 'debug-dumps', `crash-${debugDumpDirName()}`);
+    mkdirSync(crashDir, { recursive: true });
+    // Redaction is unconditional here (no opt-out) — gather the literal secret values to scrub from
+    // env + config, exactly as writeDebugDump does. `env` is the systemUtils accessor (process.env).
+    const secrets = collectSecretValues(input.config, env);
+    let gthVersion;
+    try {
+        gthVersion = getSlothVersion();
+    }
+    catch {
+        gthVersion = 'unknown';
+    }
+    const snapshot = {
+        kind: 'crash',
+        origin: input.origin,
+        timestamp: new Date().toISOString(),
+        // Flattened to plain enumerable fields so message/stack survive the redaction walk.
+        error: normalizeError(input.error),
+        env: {
+            gthVersion,
+            nodeVersion: process.version,
+            platform: process.platform,
+            model: input.modelDisplayName ?? 'unknown',
+        },
+        // Strip live LLM/tool/middleware instances to short descriptors before redaction (as the
+        // interactive config artifact does), so their internals never reach disk. `?? null` so an
+        // absent config serializes as an explicit `null` (JSON drops an `undefined`-valued key).
+        config: stripLiveInstancesForConfig(input.config) ?? null,
+        debugLogTail: getDebugLogBuffer().slice(-CRASH_DEBUG_LOG_TAIL_LINES),
+        transcriptTail: input.transcriptTail ?? null,
+    };
+    // Single fail-safe redaction pass over the whole normalized snapshot (see doc above).
+    const crashFile = resolve(crashDir, 'crash.json');
+    writeFileSync(crashFile, safeStringify(redactValue(snapshot, secrets)), 'utf8');
+    return { crashDir, crashFile };
+}
+//# sourceMappingURL=debugDump.js.map

package/dist/utils/debugDump.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debugDump.js","sourceRoot":"","sources":["../../src/utils/debugDump.ts"],"names":[],"mappings":"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"}

package/dist/utils/debugUtils.d.ts

@@ -1,20 +1,29 @@
+/**
+ * GS2-46 — read the current debug-log ring buffer (oldest first). Returns a copy so callers
+ * (e.g. the `/debug-dump` writer) can't mutate the live buffer.
+ */
+export declare function getDebugLogBuffer(): string[];
 /**
  * Initialize debug logging based on config
  */
 export declare function initDebugLogging(enabled: boolean): void;
 /**
- * Log a debug message to the log file
+ * Log a debug message. Always pushed into the in-memory ring buffer (GS2-46); only appended to
+ * the on-disk log file when debug logging is enabled.
  */
 export declare function debugLog(message: string): void;
 /**
- * Log multiple lines with proper formatting
+ * Log multiple lines with proper formatting. Always buffered (GS2-46); delegates to `debugLog`
+ * for the on-disk gating.
  */
 export declare function debugLogMultiline(title: string, content: string): void;
 /**
- * Log an object using Node.js inspect with reasonable depth
+ * Log an object using Node.js inspect with reasonable depth. Always buffered (GS2-46); delegates
+ * to `debugLogMultiline`/`debugLog` for the on-disk gating.
  */
 export declare function debugLogObject(title: string, obj: unknown): void;
 /**
- * Log error with stack trace
+ * Log error with stack trace. Always buffered (GS2-46); delegates to `debugLog` for the on-disk
+ * gating.
  */
 export declare function debugLogError(context: string, error: unknown): void;

package/dist/utils/debugUtils.js

@@ -3,6 +3,30 @@ import { dirname, resolve } from 'node:path';
 import { inspect } from 'node:util';
 const DEBUG_LOG_FILE = 'gaunt-sloth.log';
 let debugEnabled = false;
+/**
+ * GS2-46 — bounded in-memory ring buffer of debug-log lines, populated by every `debugLog*`
+ * variant UNCONDITIONALLY (independent of `debugEnabled`, which only gates the on-disk write
+ * below). This is deliberately always-on and forward-looking: GS2-48 (crash handler) expects
+ * "the last-N debugLog buffer lines already held in memory" to exist regardless of whether
+ * `config.debugLog` was ever turned on for the session, and `/debug-dump` (GS2-46) surfaces it
+ * verbatim. Capped so a long session can't grow this without bound.
+ */
+const DEBUG_LOG_BUFFER_MAX = 1000;
+const debugLogBuffer = [];
+/** Push one formatted line into the ring buffer, evicting the oldest entry once at capacity. */
+function pushToDebugLogBuffer(entry) {
+    debugLogBuffer.push(entry);
+    if (debugLogBuffer.length > DEBUG_LOG_BUFFER_MAX) {
+        debugLogBuffer.shift();
+    }
+}
+/**
+ * GS2-46 — read the current debug-log ring buffer (oldest first). Returns a copy so callers
+ * (e.g. the `/debug-dump` writer) can't mutate the live buffer.
+ */
+export function getDebugLogBuffer() {
+    return [...debugLogBuffer];
+}
 /**
  * Initialize debug logging based on config
  */
@@ -27,15 +51,17 @@ export function initDebugLogging(enabled) {
     }
 }
 /**
- * Log a debug message to the log file
+ * Log a debug message. Always pushed into the in-memory ring buffer (GS2-46); only appended to
+ * the on-disk log file when debug logging is enabled.
  */
 export function debugLog(message) {
+    const timestamp = new Date().toISOString();
+    const logEntry = `[${timestamp}] ${message}`;
+    pushToDebugLogBuffer(logEntry);
     if (!debugEnabled)
         return;
-    const timestamp = new Date().toISOString();
-    const logEntry = `[${timestamp}] ${message}\n`;
     try {
-        appendFileSync(resolve(DEBUG_LOG_FILE), logEntry, 'utf8');
+        appendFileSync(resolve(DEBUG_LOG_FILE), `${logEntry}\n`, 'utf8');
     }
     catch (error) {
         // Ignore logging errors to prevent breaking the main flow
@@ -43,21 +69,19 @@ export function debugLog(message) {
     }
 }
 /**
- * Log multiple lines with proper formatting
+ * Log multiple lines with proper formatting. Always buffered (GS2-46); delegates to `debugLog`
+ * for the on-disk gating.
  */
 export function debugLogMultiline(title, content) {
-    if (!debugEnabled)
-        return;
     debugLog(`=== ${title} ===`);
     debugLog(content);
     debugLog(`=== End ${title} ===\n`);
 }
 /**
- * Log an object using Node.js inspect with reasonable depth
+ * Log an object using Node.js inspect with reasonable depth. Always buffered (GS2-46); delegates
+ * to `debugLogMultiline`/`debugLog` for the on-disk gating.
  */
 export function debugLogObject(title, obj) {
-    if (!debugEnabled)
-        return;
     try {
         // Use Node.js inspect with reasonable depth and no colors for log files
         const formatted = inspect(obj, { showHidden: false, depth: 3, colors: false });
@@ -68,11 +92,10 @@ export function debugLogObject(title, obj) {
     }
 }
 /**
- * Log error with stack trace
+ * Log error with stack trace. Always buffered (GS2-46); delegates to `debugLog` for the on-disk
+ * gating.
  */
 export function debugLogError(context, error) {
-    if (!debugEnabled)
-        return;
     debugLog(`❌ Error in ${context}:`);
     if (error instanceof Error) {
         debugLog(`  Message: ${error.message}`);

package/dist/utils/debugUtils.js.map

@@ -1 +1 @@
-{"version":3,"file":"debugUtils.js","sourceRoot":"","sources":["../../src/utils/debugUtils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"debugUtils.js","sourceRoot":"","sources":["../../src/utils/debugUtils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,MAAM,cAAc,GAAG,iBAAiB,CAAC;AACzC,IAAI,YAAY,GAAG,KAAK,CAAC;AAEzB;;;;;;;GAOG;AACH,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,MAAM,cAAc,GAAa,EAAE,CAAC;AAEpC,gGAAgG;AAChG,SAAS,oBAAoB,CAAC,KAAa;IACzC,cAAc,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,IAAI,cAAc,CAAC,MAAM,GAAG,oBAAoB,EAAE,CAAC;QACjD,cAAc,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,CAAC,GAAG,cAAc,CAAC,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAgB;IAC/C,YAAY,GAAG,OAAO,CAAC;IACvB,IAAI,YAAY,EAAE,CAAC;QACjB,uCAAuC;QACvC,MAAM,OAAO,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;QACxC,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC;YACH,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACvC,6DAA6D;QAC/D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,8CAA8C;QAChD,CAAC;QAED,qBAAqB;QACrB,QAAQ,CAAC,mCAAmC,CAAC,CAAC;QAC9C,QAAQ,CAAC,cAAc,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACnD,QAAQ,CAAC,aAAa,OAAO,EAAE,CAAC,CAAC;QACjC,QAAQ,CAAC,oCAAoC,CAAC,CAAC;IACjD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,QAAQ,GAAG,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC;IAC7C,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IAE/B,IAAI,CAAC,YAAY;QAAE,OAAO;IAE1B,IAAI,CAAC;QACH,cAAc,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,GAAG,QAAQ,IAAI,EAAE,MAAM,CAAC,CAAC;IACnE,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,0DAA0D;QAC1D,OAAO,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAa,EAAE,OAAe;IAC9D,QAAQ,CAAC,OAAO,KAAK,MAAM,CAAC,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,CAAC;IAClB,QAAQ,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,GAAY;IACxD,IAAI,CAAC;QACH,wEAAwE;QACxE,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;QAC/E,iBAAiB,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;IACtC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,QAAQ,CAAC,qBAAqB,KAAK,KAAK,KAAK,EAAE,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,KAAc;IAC3D,QAAQ,CAAC,cAAc,OAAO,GAAG,CAAC,CAAC;IACnC,IAAI,KAAK,YAAY,KAAK,EAAE,CAAC;QAC3B,QAAQ,CAAC,cAAc,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,KAAK,CAAC,KAAK,EAAE,CAAC;YAChB,QAAQ,CAAC,gBAAgB,CAAC,CAAC;YAC3B,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC;QACrE,CAAC;IACH,CAAC;SAAM,CAAC;QACN,QAAQ,CAAC,YAAY,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACxC,CAAC;IACD,QAAQ,CAAC,EAAE,CAAC,CAAC;AACf,CAAC"}

package/dist/utils/displayWidth.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Terminal columns `text` occupies. Zero-width clusters (combining marks, default-ignorables)
+ * count 0, wide clusters (CJK, emoji, fullwidth forms) count 2, everything else 1. ANSI escape
+ * sequences are not counted, so a pre-coloured string measures as what the user sees — but the
+ * slices below do not share that awareness, so do not read this as a licence to feed them one.
+ */
+export declare function displayWidth(text: string): number;
+/**
+ * Terminal columns `text` occupies **at most** — the same measurement as {@link displayWidth} but
+ * counting East-Asian Ambiguous characters as two columns rather than one, which is the widest any
+ * terminal will render them.
+ *
+ * For a budget that must hold on a terminal whose ambiguous-width policy is unknown, this is the
+ * only sound ruler: it is the supremum over the policies a terminal can be configured with, so a
+ * string that fits under it fits under all of them. See the module docblock for when to reach for
+ * this rather than {@link displayWidth}.
+ */
+export declare function maxDisplayWidth(text: string): number;
+/**
+ * The first grapheme cluster of `text`, or `''` when it is empty — i.e. the smallest piece a cut
+ * can leave behind, for a caller that has to make progress through a string one drawable glyph at
+ * a time.
+ */
+export declare function firstCluster(text: string): string;
+/**
+ * The longest LEADING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the head, lose the tail. Total (never throws): a non-positive `maxWidth` yields `''`.
+ *
+ * A cluster is kept only if it fits ENTIRELY, so the result can come back one column short of
+ * `maxWidth` when the next cluster is two columns wide. That is the point: half a wide glyph
+ * cannot be drawn, and spending the column anyway is how text over-runs its budget.
+ *
+ * The clusters are produced one at a time and the walk stops at the budget, so the cost is the
+ * length of the RESULT rather than the length of the input — the input here is a whole tool-output
+ * line, which is unbounded.
+ */
+export declare function sliceToWidth(text: string, maxWidth: number): string;
+/**
+ * {@link sliceToWidth} measured by {@link maxDisplayWidth} — the head that fits the budget on any
+ * terminal, whatever it does with Ambiguous characters. The cut for a budget that must hold rather
+ * than merely look right.
+ */
+export declare function sliceToMaxWidth(text: string, maxWidth: number): string;
+/**
+ * The longest TRAILING run of whole clusters whose total width is at most `maxWidth` — i.e. keep
+ * the tail, lose the head. The mirror of {@link sliceToWidth}, for values whose end is the
+ * informative part (a path's leaf directory).
+ *
+ * This one materialises the clusters: it walks backwards, and cluster boundaries are only
+ * derivable from the front. Its callers pass a path or a model id, so the input is a line rather
+ * than a file.
+ */
+export declare function sliceEndToWidth(text: string, maxWidth: number): string;