@lucascouts/claude-agent-tui 0.1.0

package/dist/jsonl.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Build the absolute glob pattern used to locate a session's transcript:
+ * the `<sessionId>.jsonl` basename anywhere under `~/.claude/projects`, with `~` expanded via os.homedir
+ * (globSync does NOT perform tilde expansion). Exposed so callers can report the
+ * EXACT pattern they globbed in a not-found/ambiguity diagnostic without
+ * re-deriving (and risking drift from) the string used by findTranscript (R1.3).
+ *
+ * @param sessionId the session id; equals the transcript filename basename.
+ * @returns the absolute glob pattern findTranscript passes to globSync.
+ */
+export declare function transcriptGlob(sessionId: string): string;
+/**
+ * Find Claude transcript file(s) for a given session id.
+ *
+ * Globs the `<sessionId>.jsonl` basename anywhere under `~/.claude/projects` (`~` expanded via os.homedir)
+ * so the file is found independent of the cwd→dir encoding (R1.1). Returns ALL
+ * matches (normally one) as absolute paths; an empty array means "not found".
+ *
+ * @param sessionId the session id; equals the transcript filename basename.
+ * @returns absolute paths to matching `<sessionId>.jsonl` files (possibly empty).
+ */
+export declare function findTranscript(sessionId: string): string[];
+/**
+ * The file-discovery watchdog window (ms): how long {@link locateTranscript} keeps polling the
+ * glob for the transcript to appear before failing with a not-found diagnostic (R1.3).
+ *
+ * DISTINCT from the 5583 ms turn watchdog — never conflate them. This story uses ONLY the
+ * file-discovery watchdog.
+ */
+export declare const FILE_DISCOVERY_WATCHDOG_MS = 2000;
+/** Default polling interval (ms) between glob attempts while waiting for the transcript. */
+export declare const DEFAULT_POLL_INTERVAL_MS = 50;
+/** Options for {@link locateTranscript} / {@link resolveWatchTarget}. */
+export interface LocateOptions {
+    /** File-discovery watchdog window (ms); defaults to {@link FILE_DISCOVERY_WATCHDOG_MS}. */
+    watchdogMs?: number;
+    /** Poll interval (ms) between glob attempts; defaults to {@link DEFAULT_POLL_INTERVAL_MS}. */
+    pollIntervalMs?: number;
+    /** Injected for tests: returns matches for a sessionId. Default: {@link findTranscript}. */
+    glob?: (sessionId: string) => string[];
+    /** Injected for tests: monotonic clock in ms. Default: a `performance.now`-based clock. */
+    now?: () => number;
+    /** Injected for tests: `sleep(ms)`. Default: a `setTimeout`-based sleep. */
+    sleep?: (ms: number) => Promise<void>;
+    /**
+     * Optional abort handle for a (possibly unbounded — see `watchdogMs: Infinity`) poll. Checked each
+     * iteration; when it aborts mid-poll the poll rejects with an AbortError sentinel (`.name ===
+     * "AbortError"`) — NOT the not-found fault — so a caller can swallow exactly the
+     * cancelled-before-the-transcript-appears case and surface everything else (R1.2).
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Poll the glob until EXACTLY ONE match appears or the file-discovery watchdog elapses (R1.1,
+ * R1.3, R1.4). Deterministic/test-friendly via injected `glob`/`now`/`sleep` so tests never wait
+ * a real 2000 ms.
+ *
+ * - 0 matches at watchdog expiry → throw a not-found error whose message carries the EXACT glob
+ *   pattern AND the elapsed ms (R1.3).
+ * - >1 matches → throw a multi-match error listing EVERY matched path, so the ambiguity is loud
+ *   rather than silently resolved (R1.4).
+ * - exactly 1 → resolve `{ transcriptPath }`.
+ *
+ * @param sessionId the session id; equals the transcript filename basename.
+ * @param opts injectable watchdog/poll/glob/clock/sleep seams.
+ */
+export declare function locateTranscript(sessionId: string, opts?: LocateOptions): Promise<{
+    transcriptPath: string;
+}>;
+/**
+ * Read the runtime cwd from the `.cwd` field of the FIRST event inside the file that carries it
+ * (R1.2). NEVER decode the directory name — the cwd→dir transform is irreversible, so the encoded
+ * dir is not a reliable cwd source.
+ *
+ * Scans complete lines top-to-bottom and returns the first record whose `.cwd` is a non-empty
+ * string. Returns `undefined` when the file has no complete line yet, or no event carries `.cwd`
+ * yet — the caller should DEFER (re-read after more lines land) rather than guess from the dir
+ * name. Corrupted/partial lines are skipped without throwing.
+ *
+ * @param transcriptPath absolute path to a `.jsonl` transcript (the path {@link locateTranscript}
+ *   resolved).
+ * @returns the inside `.cwd` value, or `undefined` if none is present yet.
+ */
+export declare function readCwdFromInside(transcriptPath: string): string | undefined;
+/**
+ * Convenience: {@link locateTranscript} + {@link readCwdFromInside} → the resolved watch target
+ * for the read-only tail watcher (R1.1, R1.2).
+ *
+ * Adopts the single globbed path as the watch target and sources the runtime cwd from an event
+ * INSIDE that file. `cwd` may be `undefined` when no event has carried `.cwd` yet — the caller
+ * DEFERS reading it until the first complete line provides it, rather than decoding the dir name.
+ *
+ * @param sessionId the session id; equals the transcript filename basename.
+ * @param opts injectable watchdog/poll/glob/clock/sleep seams (forwarded to locateTranscript).
+ */
+export declare function resolveWatchTarget(sessionId: string, opts?: LocateOptions): Promise<{
+    transcriptPath: string;
+    cwd: string | undefined;
+}>;
+/** Callback invoked once per newly-completed, top-level-parseable record (the append/write signal). */
+export type RecordHandler = (record: unknown) => void;
+/**
+ * Stateful line reader. Feed it raw chunks via {@link LineReader.push}; it forwards (via the
+ * `onRecord` passed to {@link createLineReader}) only the `\n`-terminated COMPLETE lines, carrying
+ * the trailing partial residue across pushes. Each complete line is `JSON.parse`'d in try/catch —
+ * a corrupt line is SKIPPED (continue), never throws (R2.2, R2.3, R3.1, R3.2).
+ */
+export interface LineReader {
+    /** Append a raw chunk; flush every now-complete `\n`-terminated line through onRecord. */
+    push(chunk: string): void;
+    /** The current buffered trailing partial (text after the last `\n`). Exposed for test introspection. */
+    readonly residue: string;
+}
+/**
+ * Create a stateful {@link LineReader}. Maintains a single residue buffer across {@link
+ * LineReader.push} calls: each push appends to the buffer, splits on `\n`, holds the final segment
+ * back as the new residue (it may be a partial write), and forwards every COMPLETE line through
+ * `onRecord` (skipping any that fail `JSON.parse`).
+ *
+ * This is the deterministic, filesystem-free core the 2.1/2.2 scenarios drive directly.
+ *
+ * @param onRecord invoked once per newly-completed, top-level-parseable record.
+ */
+export declare function createLineReader(onRecord: RecordHandler): LineReader;
+/**
+ * Feed an explicit sequence of chunks through a fresh {@link LineReader} (residue buffered ACROSS
+ * chunks), then flush the final residue as a last line. Exposed so the cross-chunk buffering +
+ * corrupt-skip logic is directly unit-testable WITHOUT touching the filesystem — mirrors how the
+ * experiments harness exposes `feedChunks`.
+ *
+ * Note the trailing flush: unlike a live tail (where a partial residue MUST stay withheld until its
+ * `\n` arrives), a finite chunk sequence is "closed", so a final non-`\n`-terminated record is
+ * treated as complete here. Tests that assert residue-withholding therefore drive {@link
+ * createLineReader} directly (and inspect `.residue`) rather than going through `feedChunks`.
+ *
+ * @param chunks ordered text fragments (a record may straddle two fragments).
+ * @param onRecord invoked once per successfully parsed record.
+ */
+export declare function feedChunks(chunks: Iterable<string>, onRecord: RecordHandler): void;
+/** Handle returned by {@link tailTranscript}; `stop()` detaches the watcher and drops the buffer. */
+export interface TranscriptTail {
+    stop(): void;
+}
+/** Options for {@link tailTranscript}. */
+export interface TailOptions {
+    /** Invoked once per newly-completed, top-level-parseable record (the append/write signal). */
+    onRecord: RecordHandler;
+    /** Injected for deterministic tests; default {@link defaultWatch} (fs.watch). Returns a closable subscription. */
+    watch?: (path: string, onChange: () => void) => {
+        close(): void;
+    };
+    /** Injected for tests; default {@link defaultReadSlice} reads bytes `[fromByte, EOF)` of `path` as utf8. */
+    readSlice?: (path: string, fromByte: number) => string;
+    /** Injected for tests; default {@link defaultFileSize} is `fs.statSync(path).size`. */
+    fileSize?: (path: string) => number;
+}
+/**
+ * Attach an fs.watch/tail-F to `path`. On each growth, read the appended bytes from the last byte
+ * offset, push them through a {@link LineReader}, and forward complete records via `opts.onRecord`.
+ * Tracks the read offset so each byte is read exactly once. Returns a {@link TranscriptTail} whose
+ * `stop()` detaches the watcher and drops the buffer.
+ *
+ * The residue buffer makes a large NON-ATOMIC append safe: a ~630 KB base64 `image` line split
+ * across two writes is withheld until its terminating `\n` is read, so the split can not corrupt
+ * parsing (R2.3). A complete line that fails `JSON.parse` is skipped, never thrown (R3.1).
+ *
+ * Seams (`watch`/`readSlice`/`fileSize`) are injectable so the wiring is testable without real
+ * fs.watch event timing; in production they default to fs.watch + a byte-offset read.
+ *
+ * @param path absolute path to the resolved transcript (what {@link locateTranscript} resolved).
+ * @param opts onRecord sink plus injectable watch/readSlice/fileSize seams.
+ */
+export declare function tailTranscript(path: string, opts: TailOptions): TranscriptTail;
+/**
+ * A typed Degrau-1 conversation event, projected from a `getSessionMessages` message.
+ *
+ * Fields the SDK return provides are populated directly; the rest are OPTIONAL (undefined in
+ * Degrau-1 — forward-compat — because they live only in the raw JSONL record, not in the REUSE-live
+ * source) and are populated only if the input happens to carry them (see {@link projectEvent}).
+ */
+export interface JsonlEvent {
+    /** Message uuid (the dedupe key upstream). Kept as-is; empty string if the input lacks one. */
+    uuid: string;
+    /** Message type, carried through verbatim — the taxonomy `switch(.type)` is story 016. */
+    type: string;
+    /** ISO timestamp, when present on the input. */
+    timestamp?: string;
+    /** Session id — projected from the input's `session_id`. */
+    sessionId?: string;
+    /** The API message object; `message.content` may be an ARRAY of blocks OR a raw STRING. */
+    message: unknown;
+    /** Projected from the input's `parent_tool_use_id`. */
+    parentToolUseId?: string | null;
+    /** Hardcoded `'external'` — the story asserts the user type is always external. */
+    userType?: "external";
+    parentUuid?: string | null;
+    cwd?: string;
+    gitBranch?: string;
+    version?: string;
+    isSidechain?: boolean;
+    entrypoint?: string;
+    /** assistant-only request id. */
+    requestId?: string;
+    /** user-only prompt id. */
+    promptId?: string;
+    /** user-only tool-use result payload. */
+    toolUseResult?: unknown;
+    /** user-only permission mode. */
+    permissionMode?: string;
+}
+/** Options for {@link projectEvent}. */
+export interface ProjectOptions {
+    /**
+     * Byte threshold above which an `image` block's base64 `source.data` is skipped (so a heavy
+     * ~630 KB PNG does not back-pressure the streaming read). Defaults to {@link DEFAULT_IMAGE_SKIP_BYTES}.
+     * Set `Infinity` to keep ALL image data inline.
+     */
+    imageSkipBytes?: number;
+}
+/**
+ * Default byte threshold for {@link stripHeavyImages} / {@link projectEvent}: an `image` block's
+ * base64 `source.data` larger than this (~64 KB) is skipped, while a small inline image is kept.
+ * Chosen so a ~630 KB PNG is dropped but a typical small icon survives.
+ */
+export declare const DEFAULT_IMAGE_SKIP_BYTES: number;
+/**
+ * Standalone heavy-image stripper (used by {@link projectEvent}; exported for direct testing).
+ *
+ * When `message.content` is an ARRAY, returns a SHALLOW-CLONED message whose content array has any
+ * heavy `image` block's base64 `source.data` replaced by a skipped marker — PRESERVING the block's
+ * `type`, `source.type`, `source.media_type`, adding `source.skipped = true` and `source.bytes =
+ * <original byte length>` so downstream stays structurally valid and keeps a size hint. Non-image
+ * blocks (e.g. `text`) and images below the threshold pass through UNCHANGED. When `message.content`
+ * is a raw STRING (or `message` is not an object / has no array content), the input is returned
+ * untouched. The input message and its blocks are NEVER mutated in place (the watcher may hold
+ * references) — only the heavy blocks are cloned (others are shared by reference, which is safe
+ * because we never mutate them).
+ *
+ * "Heavy" = `source.data` is a string whose UTF-8 byte length exceeds `imageSkipBytes`
+ * (default {@link DEFAULT_IMAGE_SKIP_BYTES}). A `data` getter could provide TRUE laziness, but a
+ * skip marker is sufficient for Degrau-1 and keeps the event serializable.
+ *
+ * @param message the API message object (or any value — non-matching shapes pass through).
+ * @param imageSkipBytes byte threshold; `source.data` larger than this is skipped.
+ * @returns the message with heavy image data skipped, or the original value untouched.
+ */
+export declare function stripHeavyImages(message: unknown, imageSkipBytes?: number): unknown;
+/**
+ * Project a `getSessionMessages` message (or a raw-shaped event) into a typed {@link JsonlEvent}.
+ *
+ * Maps the SDK-shape fields: `session_id → sessionId`, `parent_tool_use_id → parentToolUseId`,
+ * carries `uuid` / `type` / `timestamp` / `message` through, and hardcodes `userType: 'external'`.
+ * Every OPTIONAL universal field and per-type extra (parentUuid, cwd, gitBranch, version,
+ * isSidechain, entrypoint, requestId, promptId, toolUseResult, permissionMode) is passed through
+ * ONLY if it is present on the input (defensive forward-compat), else left `undefined`. Tolerates
+ * `message.content` as an ARRAY or a raw STRING. By default also strips heavy `image` base64 data
+ * via {@link stripHeavyImages} (see `opts.imageSkipBytes`; raw-string content is left untouched).
+ *
+ * Never throws on unusual input: a missing `uuid` becomes `''`; a non-object input yields an event
+ * with empty `uuid`, `type === ''`, and `message === undefined`.
+ *
+ * @param message a `getSessionMessages` message (or raw-shaped event); any value is tolerated.
+ * @param opts projection options (the heavy-image byte threshold).
+ * @returns the typed {@link JsonlEvent}.
+ */
+export declare function projectEvent(message: unknown, opts?: ProjectOptions): JsonlEvent;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/jsonl.d.ts.map

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