@hwip/cli 0.0.1 → 0.1.0

package/dist/transcript-tail.d.ts

@@ -0,0 +1,312 @@
+/**
+ * Claude Code session transcript (`~/.claude/projects/<hash>/<uuid>.jsonl`) →
+ * the small events the agent chat timeline draws.
+ *
+ * Two pure pieces, deliberately split: reading bytes off a growing file, and
+ * deciding what of it is worth putting on the wire. Neither touches the socket,
+ * so both are testable without tmux, WebSocket, or a clock.
+ *
+ * Everything here is sized by what a real transcript actually contains, measured
+ * 2026-09-08 over 1443 files in `~/.claude/projects`: the largest file was
+ * 75.9 MB (p90 1.1 MB) and the longest single line 915,292 bytes. Those two
+ * numbers are why the reader starts near the end and refuses oversized lines
+ * before parsing them — a tail that starts at byte 0, or that hands a ~1 MB
+ * string to `JSON.parse` and only then decides to drop it, has already paid the
+ * cost the cap exists to avoid.
+ */
+import { type TodoItem, type TodoList } from './todo-fold.js';
+/**
+ * How far back from the end of the file the first read starts.
+ *
+ * Not zero: a fresh viewer that sees nothing until the *next* tool call is a
+ * blank screen for whoever just picked up their phone mid-turn. Not the whole
+ * file either — that is up to 75.9 MB. A fixed window from the end costs the
+ * same on an 8 KB transcript and a 76 MB one.
+ */
+export declare const TRANSCRIPT_BACKFILL_BYTES: number;
+/** Ceiling on one tick's read, so a burst of appends cannot be swallowed whole. */
+export declare const MAX_TAIL_BYTES_PER_TICK: number;
+/**
+ * A line longer than this is abandoned unparsed, the reader skipping to the next
+ * newline. The measured worst case is a 915 KB `tool_result`, whose body this
+ * module drops anyway — buffering one to completion would be paying megabytes to
+ * learn a tool id.
+ */
+export declare const MAX_TRANSCRIPT_LINE_CHARS: number;
+/**
+ * Ceiling on a tool's label — its name, and the short string saying what it
+ * acted on. A path or a one-line description; anything longer is a runaway
+ * input, not a label.
+ */
+export declare const MAX_EVENT_FIELD_CHARS = 512;
+/**
+ * Ceiling on prose — what the agent wrote, and what the person asked.
+ *
+ * Deliberately far above the label cap: 512 characters is a filename, and
+ * applying it here cut every reply off mid-sentence. 5000 is what the
+ * completion push already carries for the same text (`hwip-stop.sh`), so the
+ * live lane and the push that replaces it agree on how much of a reply is
+ * worth sending.
+ */
+export declare const MAX_EVENT_TEXT_CHARS = 5000;
+/**
+ * Where the reader is in one file.
+ *
+ * `size`/`mtimeMs` are the skip check: when neither moved there is nothing to
+ * read, and the tick returns without allocating. Since idle is this watcher's
+ * normal state, that check is what keeps it off the GC's back.
+ */
+export interface TailState {
+    readonly offset: number;
+    readonly size: number;
+    readonly mtimeMs: number;
+    /** Which file this offset belongs to. A new inode is a new file at the same path. */
+    readonly ino: number;
+    /** Bytes after the last newline seen — an incomplete line, held for the next tick. */
+    readonly carry: string;
+    /**
+     * How many bytes of the FILE `carry` stands for. Not `Buffer.byteLength(carry)`: a
+     * byte that is not valid UTF-8 decodes to U+FFFD, three bytes when written back, so
+     * the length of the string says nothing about the offset the line began at.
+     */
+    readonly carryBytes?: number;
+    /** Inside an oversized line: discard bytes until the next newline. */
+    readonly resyncing: boolean;
+    /** While `resyncing`: the offset where the oversized line began — the last place a restart can safely resume. */
+    readonly resyncFrom?: number;
+    /** tool_result ids read off the head of the oversized line being skipped, reported when it ends. */
+    readonly salvage: readonly string[];
+    /**
+     * Where a `TranscriptReader` that is not reading a file is, in its own
+     * terms (opencode's: a row position in its database). Opaque to everything
+     * but the reader that wrote it; the file tailer never sets it.
+     */
+    readonly cursor?: unknown;
+}
+export interface TailRead {
+    /** Whole lines, in file order. Never includes a partial line. */
+    readonly lines: string[];
+    readonly state: TailState;
+    readonly bytesRead: number;
+    /** Lines abandoned for exceeding MAX_TRANSCRIPT_LINE_CHARS. */
+    readonly droppedLines: number;
+}
+/**
+ * No state yet. `null` rather than a sentinel-filled record: "never read this
+ * file" and "read it and got nothing" are different, and an out-of-band value
+ * that has to stay below every real offset is a trap for the next `>=`.
+ */
+export declare const initialTailState: () => TailState | null;
+/**
+ * Read what was appended since `prev`, or `null` when there is nothing to do —
+ * the file is unreadable, or neither its size nor its mtime moved.
+ *
+ * `null` is the common case (an idle session) and is deliberately allocation
+ * free: no buffer, no string, no array.
+ */
+export declare const readTranscriptDelta: (path: string, prev: TailState | null, opts?: {
+    fromStart?: boolean;
+}) => TailRead | null;
+/**
+ * What the timeline draws. Stateless by design: a `tool_result` arrives as its
+ * own event rather than mutating an earlier one, because the call it answers is
+ * routinely in a previous tick's batch — merging by `id` is the viewer's job,
+ * and it is the only side that holds the whole turn.
+ */
+/**
+ * `at` is the transcript entry's own timestamp, carried so the viewer can place
+ * a live turn among the pushes in time order instead of parking the whole live
+ * block below them — where a message sent while reading lands above the turn it
+ * answers.
+ */
+export type TurnEvent = {
+    at?: string;
+} & ({
+    kind: 'tool';
+    id: string;
+    name: string;
+    target?: string;
+    add?: number;
+    del?: number;
+} | {
+    kind: 'tool_result';
+    id: string;
+    ok: boolean;
+    lines?: number;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'prompt';
+    text: string;
+} | {
+    kind: 'msg';
+    mid: string;
+    model?: string;
+    out: number;
+    ctx: number;
+    thinking?: number;
+} | {
+    kind: 'todo';
+    items: TodoItem[];
+    total?: number;
+    done?: number;
+});
+/**
+ * What a projector is told about the read it is projecting.
+ *
+ * Both flags are about the *read*, not about any one format, but only
+ * `sinceLastPrompt` means something to every agent: it is "this is a backfill,
+ * keep the turn still in flight". `includeSidechain` is Claude Code's word for
+ * its in-process subagents, and an agent with no such concept ignores it. A
+ * projector ignoring an option its format has no notion of is the contract, not
+ * an oversight — do not read an unused field here as a missed case.
+ */
+export interface ProjectorOptions {
+    sinceLastPrompt?: boolean;
+    includeSidechain?: boolean;
+    /**
+     * Told the name of each entry the projector skipped because it does not
+     * know the shape — a vendor format change otherwise thins the timeline
+     * without a word (C70). Called per skipped entry; the caller dedupes.
+     */
+    onUnknown?: (what: string) => void;
+    /**
+     * The to-do list as it stood before these lines. A projector that folds a
+     * list (Claude Code's task tools) starts from it and emits a `todo` event
+     * only when the list changed. The caller holds it between reads, because a
+     * projector holds nothing.
+     */
+    todo?: TodoList;
+    /**
+     * Told the list, whole and uncut, when these lines changed it — what the
+     * caller passes back as `todo` next time. The event itself is cut to the
+     * wire's budget and so cannot stand in for it.
+     */
+    onTodo?: (list: TodoList) => void;
+}
+/**
+ * One agent's transcript format, reduced to the events the timeline draws.
+ *
+ * Pure by contract: lines in, events out, no filesystem and no clock. That is
+ * what lets `readTranscriptDelta` above stay the single tailer for every agent
+ * whose transcript is an append-only text log — the bytes are the same problem
+ * for all of them, and only the shape of a line differs.
+ */
+export type TranscriptProjector = (lines: readonly string[], opts?: ProjectorOptions) => TurnEvent[];
+/**
+ * A transcript and the projector that can read it, resolved together.
+ *
+ * They travel as one because they are one answer: a path with no projector is a
+ * file nothing can parse, which reaches a viewer as an empty timeline — strictly
+ * worse than the honest `no_transcript` it would replace. Resolving them apart
+ * would also mean two `detectRemoteAgent` lookups per recheck, on a path that is
+ * uncached and blocking (see `TurnWatchDeps.resolveTranscript`).
+ */
+export interface TranscriptSource {
+    readonly path: string;
+    readonly project: TranscriptProjector;
+    /**
+     * How to read `path`, when it is not an append-only file. Absent for every
+     * agent that writes one — `readTranscriptDelta` reads those. opencode keeps
+     * its sessions in SQLite, so its row carries a reader of its own and its
+     * `path` names a session in the database rather than a file.
+     */
+    readonly read?: TranscriptReader;
+}
+/**
+ * What was added to a transcript since `prev`, or null when nothing was —
+ * `readTranscriptDelta`'s contract, for a transcript that is not a file.
+ */
+export type TranscriptReader = (path: string, prev: TailState | null) => TailRead | null;
+/** One read of a source, through its own reader when it has one. */
+export declare const readSource: (source: TranscriptSource, prev: TailState | null) => TailRead | null;
+/** Edits larger than this are counted, not diffed: splitting them into lines
+ *  is the one allocation here that scales with what the agent wrote. */
+export declare const EDIT_DIFF_MAX_CHARS: number;
+/** Lines of a result's text — a string, or the text blocks of a block list. Images and the like count as nothing. */
+/**
+ * How long a tool result was, from either shape a result body takes: a bare
+ * string, or blocks with a `text` field. Exported for the same reason as
+ * `clamp` — the shape is not one agent's vocabulary, and `lines` means the same
+ * number on the wire whoever produced it.
+ */
+export declare const resultLinesOf: (content: unknown) => number;
+/**
+ * One line, always.
+ *
+ * A label is not a paragraph: a tool argument that runs to hundreds of
+ * characters with newlines in it renders as a wall where a row's label belongs.
+ * Applied by the projectors that need it rather than inside `targetFrom`,
+ * because that helper feeds Claude's projector too and the Spec requires a
+ * Claude timeline to stay byte-identical.
+ */
+export declare const oneLine: (target: string | undefined) => string | undefined;
+/**
+ * The backfill window, applied the same way by every projector.
+ *
+ * This is about `TurnEvent` and `ProjectorOptions`, not about any one agent's
+ * vocabulary — unlike the per-format helpers beside it, which are deliberately
+ * not shared. Every projector ends with this call, and a fourth one should too.
+ */
+export declare const sliceSinceLastPrompt: (events: TurnEvent[], opts: ProjectorOptions) => TurnEvent[];
+/**
+ * Ceilings on a `todo` event: tasks kept, and characters per task. 30 tasks of
+ * 100 Hangul characters each is under 10KB of JSON, inside the 12KB frame
+ * (`MAX_TURN_FRAME_BYTES` in `turn-watch`), which sends an oversized event whole
+ * rather than cutting it.
+ */
+export declare const MAX_TODO_ITEMS = 30;
+export declare const MAX_TODO_TEXT_CHARS = 100;
+/**
+ * The `todo` event for a list. Over `MAX_TODO_ITEMS`, finished tasks go first,
+ * oldest first — what is left to do is what the phone is watching for — and
+ * `total` · `done` keep the real counts.
+ */
+export declare const todoEventOf: (list: TodoList, at: string | undefined) => Extract<TurnEvent, {
+    kind: "todo";
+}>;
+/** A usable number, or 0 — token counts are the one place a missing field must not become `NaN` on the wire. */
+export declare const finiteNumber: (value: unknown) => number;
+/**
+ * Cut one field to the wire's budget. Exported because every projector shares
+ * the same 12KB frame ceiling (`MAX_TURN_FRAME_BYTES` in `turn-watch`), so a
+ * second projector with its own idea of "long enough" would be a second way to
+ * overflow the one transport.
+ */
+export declare const clamp: (value: string, max?: number) => string;
+/**
+ * First of `keys` that holds a non-blank string, clamped — the loop every
+ * projector needs, without the key list every projector has to choose for
+ * itself. The keys stay the caller's: they are that agent's vocabulary, and
+ * merging them into one list is exactly what the `TARGET_KEYS` note forbids.
+ */
+export declare const targetFrom: (input: unknown, keys: readonly string[]) => string | undefined;
+/**
+ * Turn raw JSONL lines into wire events.
+ *
+ * Nothing a tool read or wrote survives this function: only the tool's name, a
+ * short label for what it acted on, whether it worked, and numbers about it —
+ * lines changed, result length, a message's tokens and model. That is the whole
+ * privacy story of the feature — the transcript holds file contents and command
+ * output, and this is the one place that decides none of it leaves the machine.
+ *
+ * `sinceLastPrompt` is for the backfill window: finished turns already exist in
+ * the chat as their completion pushes, so replaying them would double every
+ * message. Only the turn still in flight is new information.
+ *
+ * The prompt a person typed IS carried, unlike anything a tool read or wrote.
+ * It is their own words, it is the same class of content the completion push
+ * already sends, and without it the timeline is a list of tool names with no
+ * record of what was asked.
+ *
+ * Everything here — the block shapes, the entry types, `TARGET_KEYS` — is Claude
+ * Code's transcript format. Supporting another agent (pi, Codex) means a
+ * projector of its own alongside this one, satisfying `TranscriptProjector` and
+ * reached the way `REMOTE_AGENTS` already reaches per-agent session resolvers:
+ * `RemoteAgent.projectTranscript`, resolved together with the path as a
+ * `TranscriptSource`. `turn-watch` calls whichever projector it is handed and
+ * knows about none of them by name.
+ */
+export declare const projectTranscriptEntries: TranscriptProjector;
+//# sourceMappingURL=transcript-tail.d.ts.map