agent-nuvira 3.3.3 → 3.3.5

package/dist/observability/debug-log.d.ts

@@ -0,0 +1,250 @@
+/**
+ * WS2 (#24) — the session debug log you attach to a bug report.
+ *
+ * WHY THIS EXISTS, and what it is NOT. This repository's bug reports keep
+ * arriving as prose: "the dashboard did not answer", "the gateway sent the
+ * wrong thing", "it worked yesterday". Every one of them is then re-litigated
+ * by reading code, because the failing run left nothing behind that records
+ * WHICH BACKEND SERVED IT. The trace store (`learning/reasoning-trace.ts`) is
+ * the audit of what the MODEL was asked; the DAG bridge and the gateway log are
+ * per-surface records. None of them is the thing a user can attach to a bug
+ * report, and none of them is reachable the same way from all five surfaces.
+ *
+ * So a session debug log is deliberately boring: a plain-text file, ordered,
+ * with a header that names the surface and THE BACKEND — provider, model,
+ * transport, engine — before a single line of detail. If a bug report can only
+ * carry one thing, that header is the thing that makes it actionable.
+ *
+ * FOUR RULES, each closing a way a debug log becomes worse than none:
+ *
+ *  1. OPT-IN, AND CHEAP WHEN OFF. `NUVIRA_DEBUG_LOG=1` turns it on; with it off
+ *     `sessionDebugLog()` returns `null` and every call site's `?.` makes the
+ *     cost one boolean check. A logging path that is on by default is a disk
+ *     leak and a privacy hazard wearing a helpful face.
+ *
+ *  2. REDACTED BY CONSTRUCTION. A log we ask a user to attach to a bug report
+ *     is a log that will be pasted into an issue tracker. Every event line is
+ *     scrubbed with the SAME `scrubSecrets` the gateway log uses (reused, not
+ *     re-implemented: two regex lists drift, and the one that drifts is the one
+ *     that leaks). The header carries the backend and versions — never a key.
+ *
+ *  3. BOUNDED. Events are capped, each line is truncated to a preview, and the
+ *     file is capped by bytes. An instrument must never be the reason a run
+ *     dies, and a nightly-failing turn must not fill a disk.
+ *
+ *  4. WRITTEN ONCE, AT CLOSE. The header has to name the backend that served
+ *     the turn, and the backend is only known at the end (the loop may fail
+ *     over between providers). So events buffer in memory and `write()`
+ *     produces the whole file — header first — at the end of the turn. That
+ *     also means a crashed process leaves NO half-written log, which is the
+ *     honest outcome: a log whose header lies about the backend is worse than
+ *     no log.
+ *
+ * The five surfaces each open one at their own turn seam (`cli/chat.ts`,
+ * `cli/loop-executor.ts`, `tools/child-agent-runtime.ts`, with the dashboard
+ * console and the gateway passing their identity down to the shared chat
+ * engine), and the parity harness reads the file back and asserts every
+ * surface's header names the SAME backend — the capability
+ * `debug-log@<surface>` is proved against.
+ *
+ * A log that a surface wrote into a directory the user has to find is only half
+ * the artifact. So a surface that HAS a conversation identity records it
+ * (`session`), which turns the file from readable into FINDABLE: the dashboard
+ * server can answer "the bundle for this chat" by looking up the logs whose
+ * header names that conversation, instead of guessing from timestamps and
+ * handing over someone else's. A surface with no such identity (the CLI's
+ * one-shot path) records nothing rather than inventing an id.
+ */
+/** The env var that turns session debug logging on (`NUVIRA_DEBUG_LOG=1`). */
+export declare const DEBUG_LOG_ENV = "DEBUG_LOG";
+/** Optional directory override for the log files (`NUVIRA_DEBUG_LOG_DIR`). */
+export declare const DEBUG_LOG_DIR_ENV = "DEBUG_LOG_DIR";
+/** Hard cap on the written file. Bounded on purpose — see rule 3 above. */
+export declare const DEBUG_LOG_MAX_BYTES: number;
+/** Per-line detail preview cap. Never the whole payload. */
+export declare const DEBUG_LOG_PREVIEW_CHARS = 300;
+/** Event cap. Beyond it the OLDEST events are dropped, and the count is stated. */
+export declare const DEBUG_LOG_MAX_EVENTS = 2000;
+/** Cap on a session id as a FILENAME component, so a long id cannot fail a write. */
+export declare const DEBUG_LOG_SESSION_CHARS = 48;
+/** The backend that served a turn — the fact the header exists to carry. */
+export interface DebugLogBackend {
+    provider?: string | null;
+    model?: string | null;
+    /** Tool transport: `native` / `json` / `none`. */
+    transport?: string | null;
+    /** The engine label the surface ran under (`loop` / `pipeline`). */
+    engine?: string | null;
+}
+/**
+ * The parsed header. Every field is present (null when the surface never
+ * learned it), so a reader can tell "not reported" apart from "reading failed".
+ */
+export interface DebugLogHeader {
+    surface: string | null;
+    /**
+     * The chat/thread this turn belonged to, when the surface has one.
+     *
+     * This is what makes a log findable rather than merely readable: the dashboard
+     * cannot serve "the log for the conversation I am looking at" unless the log
+     * says which conversation it was. Null for a surface with no such identity —
+     * an absent id is honest, a fabricated one is not.
+     */
+    session: string | null;
+    engine: string | null;
+    provider: string | null;
+    model: string | null;
+    transport: string | null;
+    /** The agent-nuvira version that wrote the log. */
+    version: string | null;
+    startedAt: number | null;
+    /** The writing process — a forked subagent has its own, and that matters. */
+    pid: number | null;
+    platform: string | null;
+}
+/** One log file on disk, with its parsed header when it could be read. */
+export interface DebugLogFile {
+    path: string;
+    /** Null when the file is unreadable or its header is malformed. */
+    header: DebugLogHeader | null;
+}
+/**
+ * Is session debug logging on?
+ *
+ * `NUVIRA_DEBUG_LOG` (or legacy `BUFF_DEBUG_LOG`) set to anything other than
+ * `0` / `false` / `off` enables it. Deliberately not "truthy string" only: a
+ * user who writes `NUVIRA_DEBUG_LOG=false` in an `.env` means off.
+ */
+export declare function debugLoggingEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Where the log files live.
+ *
+ * `NUVIRA_DEBUG_LOG_DIR` wins when set; otherwise `<config dir>/debug-logs`
+ * through `resolveNuviraDataPath`, so an isolated profile (tests, CI, the
+ * parity harness) can never write into the developer's real `~/.nuvira`.
+ */
+export declare function debugLogDir(env?: NodeJS.ProcessEnv): string;
+/**
+ * One session's debug log, buffered and written once.
+ *
+ * Deliberately a class rather than a bag of functions: the buffered state IS
+ * the object, and a surface that opens one and forgets to write it produces no
+ * file at all — which the parity harness reads as `written: false` rather than
+ * as agreement.
+ */
+export declare class SessionDebugLog {
+    readonly id: string;
+    readonly startedAt: number;
+    private readonly surface;
+    private readonly goal;
+    private backend;
+    private readonly extra;
+    private readonly entries;
+    private dropped;
+    private truncatedLines;
+    private readonly dir;
+    private readonly now;
+    /** The conversation this turn belongs to, or null (see `DebugLogHeader.session`). */
+    readonly session: string | null;
+    private writtenPath;
+    constructor(opts: {
+        surface: string;
+        goal?: string;
+        session?: string;
+        backend?: DebugLogBackend;
+        dir?: string | null;
+        now?: () => number;
+    });
+    /** The backend that served the turn. Set as it is learned; last call wins. */
+    backendOf(backend: DebugLogBackend): this;
+    /**
+     * Preview one detail value: flattened, cut to the cap, then redacted.
+     *
+     * The cut is counted BEFORE the scrub (the scrub only shortens), so the
+     * "truncated" line in the file reports how much was actually lost.
+     */
+    private detailText;
+    /** One ordered event. `detail` is previewed and redacted. */
+    event(name: string, detail?: unknown): this;
+    /** A non-secret header field (a version, a channel, a bound). */
+    detail(key: string, value: unknown): this;
+    /** The attachable text: header first, then the events in order. */
+    render(): string;
+    /**
+     * Write the file. Returns the path, or null when logging is disabled, no
+     * directory was resolved, or the write failed — every one of which is a
+     * normal outcome a caller must not have to handle.
+     */
+    write(): string | null;
+    /** The path after a successful `write()` (null before it / on failure). */
+    path(): string | null;
+}
+/**
+ * Open a session debug log, or `null` when logging is off (or in a unit test
+ * that passed no directory). Callers use `?.` throughout, so the off path costs
+ * one boolean.
+ */
+export declare function sessionDebugLog(opts: {
+    surface: string;
+    goal?: string;
+    /** The chat/thread this turn belongs to, when the surface has one. */
+    session?: string;
+    backend?: DebugLogBackend;
+    /** Explicit directory (tests / a harness that isolates the profile). */
+    dir?: string | null;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+}): SessionDebugLog | null;
+/**
+ * Parse a rendered log's header.
+ *
+ * Reads the leading `# key: value` comment block only, and returns null when
+ * `surface` is absent — the one field every header must have. Unknown keys are
+ * ignored rather than rejected, so an older reader can still open a newer log.
+ */
+export declare function parseDebugLogHeader(text: string): DebugLogHeader | null;
+/** Every log file in `dir`, newest first. Missing directory = empty list. */
+export declare function listDebugLogs(dir?: string): DebugLogFile[];
+/**
+ * The newest log a given surface wrote, or null.
+ *
+ * This is how the parity harness reads a surface's OWN durable artifact — the
+ * same reasoning the gateway driver uses to read `inbound.chat` from the
+ * gateway log rather than trusting a return value.
+ */
+export declare function readLatestDebugLog(surface: string, dir?: string): {
+    path: string;
+    header: DebugLogHeader;
+    text: string;
+} | null;
+/** One log file with its parsed header and text — what a support bundle carries. */
+export interface DebugLogRecord {
+    path: string;
+    header: DebugLogHeader;
+    text: string;
+}
+/**
+ * Every log a given conversation wrote, OLDEST FIRST — the findable half.
+ *
+ * This is what lets the dashboard answer "the debug log for the chat I am
+ * looking at" without guessing. Two rules make it safe to expose:
+ *
+ *  1. SELECTED BY THE LOG'S OWN HEADER, never by recency. "The newest few logs"
+ *     would hand a user somebody else's conversation — with a concurrent turn in
+ *     another tab, that is the common case, not the edge case.
+ *
+ *  2. OLDEST FIRST, because a bundle is read top to bottom as the story of what
+ *     happened, and a single turn's log already reads that way internally. The
+ *     newest-first order `listDebugLogs` uses is right for "what just happened"
+ *     and wrong for this.
+ *
+ * A file that cannot be read or parsed is skipped rather than failing the whole
+ * bundle: one unreadable turn must not cost the user the other four.
+ */
+export declare function debugLogsForSession(sessionId: string, dir?: string): DebugLogRecord[];
+/**
+ * A one-line notice a surface can print so the user knows a log exists to
+ * attach. Kept here so all five surfaces word it identically.
+ */
+export declare function debugLogNotice(surface: string, path: string | null): string | null;
+//# sourceMappingURL=debug-log.d.ts.map

package/dist/observability/debug-log.d.ts.map

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