@phnx-labs/agents-cli 1.22.83 → 1.22.85

package/dist/lib/session/timeline.d.ts

@@ -0,0 +1,182 @@
+/**
+ * The narration-anchored session timeline (PHNX-3939) — a pure, resumable fold.
+ *
+ * A transcript is a flat event stream: the agent says a line, runs six tools,
+ * says the next line. A person reading a sidebar wants the LINES, with the tool
+ * calls collapsed underneath them. That is the whole model here: one
+ * {@link SessionStep} per narration beat, the calls until the next beat folded
+ * into counts, failures and milestones.
+ *
+ * Two properties this module is built around:
+ *
+ *   - **Deterministic, no model.** The headline is the harness's OWN narration
+ *     (Claude assistant text, Codex `AgentMessage` commentary, Gemini thought
+ *     subject) and the per-tool label is the harness's own (`description`,
+ *     `state.title`, the parsed command). Nothing is invented; the optional
+ *     summarizer polishes ON TOP and is never required.
+ *   - **Resumable.** {@link foldTimeline} takes the state from the previous fold
+ *     and the events that arrived since, so the daemon reads only the bytes a
+ *     transcript grew by. Folding the appended tail onto the prior state is
+ *     identical to folding the whole file from zero — every piece of mutable
+ *     state lives in the serializable {@link TimelineState}, nothing in a
+ *     closure.
+ *
+ * No I/O: the pass (`timeline-pass.ts`) reads bytes and calls this. Same
+ * discipline as `digest.ts` and `trajectory.ts`.
+ */
+import type { SessionEvent, SessionFileChange, SessionFiles, SessionRequest, SessionStep, SessionTimeline, SessionVerbClass } from './types.js';
+/**
+ * Bumped when the fold's OUTPUT changes, so a cached state computed by an older
+ * CLI is recomputed rather than rendered. Same role as
+ * `SESSION_SUMMARY_EXTRACTOR_VERSION`.
+ */
+export declare const TIMELINE_EXTRACTOR_VERSION = 1;
+/** Steps carried on the row in full; everything older folds into a counter. */
+export declare const TIMELINE_KEEP_STEPS = 8;
+/** File rows carried on the row in full; `total` still reports the real count. */
+export declare const TIMELINE_KEEP_FILES = 8;
+/**
+ * Steps kept in the persisted resume state. A long session narrates for hours,
+ * and the state is re-read every tick, so the fold rolls everything past this
+ * into {@link TimelineState.dropped} — exact totals, bounded bytes.
+ */
+export declare const TIMELINE_STATE_MAX_STEPS = 200;
+/** Paths kept in the persisted resume state; older ones roll into `filesDropped`. */
+export declare const TIMELINE_STATE_MAX_FILES = 200;
+/** One file the session touched, as accumulated during the fold. */
+interface TimelineFileEntry {
+    op: SessionFileChange['op'];
+    edits: number;
+    at: string;
+    /** True when a harness file ledger (not a tool argument) recorded this path. */
+    harness: boolean;
+}
+/**
+ * Everything the fold needs to continue from where it stopped. Serialized into
+ * `session_timelines.state_json`; every field is plain JSON on purpose (`open`
+ * and `pending` are indices, not object references) so a resume is exact.
+ */
+export interface TimelineState {
+    version: number;
+    /** Byte offset just past the last COMPLETE record folded. */
+    offset: number;
+    steps: SessionStep[];
+    /** Index of the currently open step in {@link steps}, or -1. */
+    open: number;
+    /** Harness call id → index of the step that owns it, for results that arrive later. */
+    pending: Record<string, number>;
+    firstMs: number | null;
+    lastMs: number | null;
+    /** Genuine user turns seen so far. */
+    turns: number;
+    /** The latest genuine user turn, tidied — the session's operative request. */
+    request?: SessionRequest;
+    /** The FIRST genuine user turn, kept so history still shows where it started. */
+    firstRequest?: SessionRequest;
+    /** Path → accumulated change record. */
+    files: Record<string, TimelineFileEntry>;
+    /** Set when an event cap stopped the fold short: the projection reports `partial`. */
+    truncated?: boolean;
+    /**
+     * Steps rolled out of {@link steps} to keep the persisted state bounded. Their
+     * counts still ride the projection's `earlier` block and totals, so folding a
+     * compacted state and folding the whole file report the same numbers.
+     */
+    dropped?: {
+        steps: number;
+        tools: number;
+        failed: number;
+        blocked: number;
+    };
+    /** Paths rolled out of {@link files} for the same reason; `total` stays exact. */
+    filesDropped?: number;
+}
+/**
+ * Roll the oldest steps and file rows out of the state so a session that runs
+ * for hours does not grow its cached state without bound. Their tallies survive
+ * in {@link TimelineState.dropped} / {@link TimelineState.filesDropped}, which
+ * the projection adds back — so this changes the state's SIZE, never its
+ * reported numbers.
+ */
+export declare function compactTimelineState(state: TimelineState, maxSteps?: number, maxFiles?: number): TimelineState;
+/** A fresh state for a session nothing has been folded for yet. */
+export declare function emptyTimelineState(): TimelineState;
+/**
+ * Bucket one Bash command into a verb class, reusing the repo's single command
+ * classifier (`classifyBashCommand`) rather than re-deriving a second taxonomy.
+ * Its `category` answers most of it; the three things its taxonomy deliberately
+ * does not carry — a write redirection, `agents` subcommands, and whether a
+ * build tool is running tests — are added on top.
+ *
+ * Multi-segment commands take the most consequential class present, so
+ * `cd x && bun test` is a test, not a `cd`.
+ */
+export declare function classifyCommandVerb(command: string | undefined): SessionVerbClass;
+/** The verb class for one tool call: the harness's own if it classified it, else derived. */
+export declare function verbClassForEvent(event: SessionEvent): SessionVerbClass;
+/** Options the fold needs that are not on the events themselves. */
+export interface FoldTimelineOptions {
+    /** Row attachments, so an image the prose never named still rides the request. */
+    attachments?: import('./types.js').SessionAttachment[];
+    /** Stop after this many events and mark the state `truncated` (the projection reads `partial`). */
+    maxEvents?: number;
+    /** Byte offset the folded events end at; stored so the next fold resumes there. */
+    offset?: number;
+}
+/**
+ * Fold `events` onto `prior` (or a fresh state) and return the new state.
+ *
+ * Pure: no clock, no filesystem, no database. The rules, in the order they are
+ * applied per event, are the plan's fold table — narration opens, thinking opens
+ * only when there is nothing open or the open step is already a wall of calls,
+ * tools attach, a genuine user turn is its own step, results resolve
+ * failed-vs-blocked, and a harness file ledger both marks the step and feeds the
+ * files projection.
+ */
+export declare function foldTimeline(events: SessionEvent[], prior?: TimelineState, opts?: FoldTimelineOptions): TimelineState;
+/** The activity values that mean the agent is mid-step, so the newest step is live. */
+export type TimelineActivity = string | undefined;
+/** How {@link projectTimeline} scrubs the transcript text it is about to ship. */
+export interface ProjectTimelineOptions {
+    /** Redact secrets from every projected string. Default true — see below. */
+    redact?: boolean;
+    /** Known credential values to mask verbatim; defaults to {@link knownSecretValuesFromEnv}. */
+    knownSecrets?: readonly string[];
+}
+/**
+ * Project the folded state onto the bounded shape that rides a session row.
+ *
+ * `keep` newest steps travel in full; everything older collapses into
+ * `earlier`. The newest step is marked `live` while the session is working —
+ * that is what the sidebar renders with the amber now-line, using the `now`
+ * label the harness wrote for the call that is running.
+ *
+ * **This is the single place raw transcript text leaves the fold**, so it is
+ * where scrubbing happens — every consumer (the session row, the git-tracked
+ * fleet mirror `daemon-state.json`, and `sessions trace --steps`) is covered at
+ * the source rather than each remembering to do it. Two passes, and they are
+ * not the same thing:
+ *
+ *   - **Terminal escapes are ALWAYS stripped.** A transcript is untrusted input
+ *     and these labels are printed to a terminal; `sanitizeEvents` never runs on
+ *     the fold's parse path (only `tail.ts` / `stream-render.ts` call it), so
+ *     this is the only place that scrub happens for a timeline.
+ *   - **Secrets are redacted unless the caller opts out.** `redact` defaults to
+ *     ON; only the local-only `--no-redact` path passes `redact: false`, and it
+ *     buys exactly that — not raw control characters.
+ */
+export declare function projectTimeline(state: TimelineState, activity: TimelineActivity, keep?: number, options?: ProjectTimelineOptions): SessionTimeline;
+/** The honest empty timeline for a harness that writes no parseable transcript. */
+export declare function unavailableTimeline(reason: string): SessionTimeline;
+/**
+ * Project the files the session changed. Bounded to `keep` rows, newest first,
+ * with `total` reporting the real count.
+ *
+ * `source` reports where the OPERATIONS came from: `harness` when at least one
+ * entry was written by the harness's own ledger (Codex `FileChange` carries
+ * add/update/delete per path, OpenCode `patch` and Claude `file-history-delta`
+ * carry the path set), `tools` when everything was derived from Edit/Write
+ * arguments because the harness records no ledger at all.
+ */
+export declare function projectSessionFiles(state: TimelineState, keep?: number): SessionFiles | undefined;
+export {};