toolroll 0.9.63 → 0.9.65

package/dist/live-records.d.ts

@@ -0,0 +1,140 @@
+/**
+ * The live conversation's records (docs/plans/live-conversation.md): what a
+ * running agent said and did, one JSON object per line of `live/<run>.jsonl`.
+ *
+ * The recorder turns provider stream events into records. It names a step's
+ * target only from a closed list of argument fields, keeps a command's text
+ * and output only when the project turned "Show commands in the live view"
+ * on (the `commands` tier), and never writes a tool's own name — only our
+ * fixed kind. Every string is redacted, then cleaned of controls, then cut.
+ * The redaction is best effort; the opt-in is the real control.
+ *
+ * Readers trust nothing they read back: `parseLiveRecord` re-checks shape,
+ * caps and redaction, since the machine running the agent could alter the
+ * file. Display state, never evidence.
+ */
+/**
+ * The fixed tool vocabulary: known harness tools map to OUR kinds; anything
+ * unrecognized is "tool". The tool's own name never reaches the file.
+ */
+export type LiveActivityKind = "session" | "message" | "edit" | "command" | "read" | "search" | "lookup" | "plan" | "delegate" | "tool";
+export declare const LIVE_ACTIVITY_KINDS: readonly LiveActivityKind[];
+/** What a run's live file may hold: the base tier, or commands too (the project setting, read at open). */
+export type LiveDetail = "base" | "commands";
+/** One record. `at` is when the recorder saw it (ISO). */
+export type LiveRecord = 
+/** The file's first record: what this run's project allowed when it started, kept with the run. */
+{
+    k: "open";
+    at: string;
+    detail: LiveDetail;
+} | {
+    k: "start";
+    at: string;
+} | {
+    k: "say";
+    at: string;
+    t: string[];
+} | {
+    k: "step";
+    at: string;
+    id: string;
+    kind: LiveActivityKind;
+    target?: string;
+    once?: true;
+} | {
+    k: "done";
+    at: string;
+    id: string;
+    ok: boolean | null;
+    out?: string[];
+} | {
+    k: "cut";
+    at: string;
+} | {
+    k: "cap";
+    at: string;
+};
+/** A record's serialized size limit: a longer one is replaced by `cut`. */
+export declare const LIVE_RECORD_CAP: number;
+export declare const HIDDEN_TARGET = "[hidden]";
+export declare const HIDDEN_LINE = "[a line was hidden]";
+export declare const HIDDEN_KEY_BLOCK = "[a key block was hidden]";
+export declare const OUTSIDE_PROJECT = "a file outside the project";
+export declare const SOME_FILE = "a file";
+/** Whether a line looks like it carries a credential (best effort). */
+export declare function liveSecretHit(line: string): boolean;
+/** Controls, ANSI escapes and bidi overrides out; tabs to spaces. */
+export declare function cleanLiveText(text: string): string;
+/** An escape a line ended in the middle of, which the next line finishes: CSI, OSC, or a bare ESC. */
+export type EscapeCarry = "" | "C" | "O" | "E";
+/** Cut to at most `cap` UTF-8 bytes on a character boundary, "…" when cut. */
+export declare function capLive(text: string, cap: number): string;
+/** One line for the view: redacted whole when it hits, then cleaned and cut. */
+export declare function liveLine(raw: string, cap?: number): string;
+/**
+ * Lines redacted as a whole: each line on its own, and a key block hidden
+ * from its BEGIN line to its END (or to the end) as one line. Used for the
+ * agent's words, command output, and everything read back.
+ */
+/**
+ * Whether reading is inside a key block: carried from line to line, record to
+ * record and — through the reader's cursor — from one read to the next, so a
+ * block split anywhere stays hidden.
+ */
+export type KeyState = {
+    inKey: boolean;
+    /** Per reading, how much of "-----BEGIN" the stream has ended on so far, then the escape the last line left open:
+     * marker characters and one flag only, never content, so it may ride the cursor. Joined with "|" when carried. */
+    tail?: string;
+};
+/** Whether a carried tail is one this code could have produced: three BEGIN prefixes and an escape flag, or nothing. */
+export declare function validKeyTail(tail: string): boolean;
+export declare function redactLiveLines(lines: readonly string[], state?: KeyState): string[];
+/**
+ * Output for a command step: every line redacted first (a key block hidden
+ * from its BEGIN line to its END, or to the end), then the last 20 lines
+ * within 4 KiB — truncation never comes before redaction.
+ */
+export declare function liveOutput(raw: string, keys?: KeyState): string[];
+/**
+ * A path as the view shows it: relative to the run's own checkout when it
+ * lies inside it, judged lexically — nothing is opened or resolved on disk.
+ */
+export declare function livePath(base: string | null, given: unknown): string | null;
+/** A command's first line, "…" when more followed or it was cut. */
+export declare function liveCommand(given: unknown): string | null;
+export type LiveRecorderOptions = {
+    /** The run's own checkout; null when it has none (every path is "a file"). */
+    base: string | null;
+    /** The project's "Show commands in the live view" setting, read at open. */
+    commands: boolean;
+    clock?: () => Date;
+};
+export type LiveRecorder = {
+    /** The records one stream event adds. Never throws. */
+    observe(event: Record<string, unknown>): LiveRecord[];
+    /** The process ended: every step still open closes unknown. */
+    end(): LiveRecord[];
+};
+export declare function createLiveRecorder(options: LiveRecorderOptions): LiveRecorder;
+/** One record as its file line; an oversized one becomes `cut`. */
+export declare function serializeLiveRecord(record: LiveRecord): string;
+/**
+ * One file line back into a record, strictly: a known shape within its caps,
+ * every string redacted and cleaned again. Anything else is null — skipped,
+ * never shown raw.
+ */
+export declare function parseLiveRecord(line: string, keys?: KeyState): LiveRecord | null;
+/** Complete file lines (a window's text) into records; bad lines are skipped. */
+export declare function parseLiveRecords(text: string, keys?: KeyState): LiveRecord[];
+export declare const LIVE_CAP_WORDS = "[the live view stopped at its size cap \u2014 the run record continues]";
+export declare const LIVE_CUT_WORDS = "[a line was too long to show]";
+export declare const LIVE_KIND_HEADLINES: Readonly<Record<LiveActivityKind, string>>;
+/** A step's one line of words, with its target when it has one. */
+export declare function stepWords(step: {
+    kind: LiveActivityKind;
+    target?: string;
+}): string;
+/** Records as the plain lines the run page and `toolroll peek` show. */
+export declare function projectLiveText(records: readonly LiveRecord[]): string[];