toolroll 0.9.103 → 0.9.105

package/dist/live-records.d.ts

@@ -1,149 +0,0 @@
-/**
- * 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 (terminal-text.ts, the one sanitizer). */
-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;
-declare const short: (given: unknown) => string | null;
-/** A short display form of one field: its first line, cleaned, redacted and cut (a delegated task's description). */
-export declare const liveShort: typeof short;
-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;
-    /** The key-block state to carry (the caller's, so it can write it down in a checkpoint); a fresh one by default. */
-    keyState?: KeyState;
-    /** Told of each step as it is recorded: the provider's call id (null when it has none), our id, and the target as
-     * written (redacted, under the key state). Observation only: it changes nothing recorded. */
-    onStep?: (call: string | null, id: string, target: string | null) => void;
-};
-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(given: 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[];
-export {};

package/dist/live-reply.d.ts

@@ -1,83 +0,0 @@
-import type { LeadLiveTool, LeadProgress } from "./lead-progress.js";
-import { type ShapeOptions } from "./reply-shape.js";
-export type LiveView = {
-    phase: "queued";
-} | {
-    phase: "working";
-    status: string;
-} | {
-    phase: "writing";
-    status: string;
-    text: string;
-} | {
-    phase: "closed";
-    why: "answered" | "failed" | "blocked";
-};
-/** The status line's fixed words (§2.3). A running tool reads as its own label plus "…". */
-export declare const LIVE_STATUS: {
-    readonly queued: "Waiting for your earlier messages…";
-    readonly thinking: "Thinking…";
-    readonly writing: "Writing…";
-    readonly repair: "Fixing the reply…";
-    readonly shorten: "Shortening the reply…";
-    /** A preview closed because text looked like a password or key; the turn itself may still answer. */
-    readonly held: "Working on it…";
-};
-/** Could the end of this text be the start of a password or key? Then nothing of it shows yet. */
-export declare function secretMayStart(text: string): boolean;
-/**
- * What of a reply still being written is settled: everything before its last whitespace (the unfinished last word
- * stays out), then cut back before any code fence, code span, bold run or link that hasn't closed yet. Trailing
- * whitespace is trimmed.
- */
-export declare function settledText(raw: string): string;
-/**
- * A partial as it may be shown: `blocked` when it holds a password or key (the preview closes), `withheld` while its
- * tail could still become one (show nothing new), else the settled text shaped for display. A step's finished text
- * (`final`, secret-checked whole by the engine) shows whole.
- */
-export declare function partialDisplay(raw: string, final: boolean, shape?: ShapeOptions): {
-    kind: "blocked";
-} | {
-    kind: "withheld";
-} | {
-    kind: "shown";
-    text: string;
-};
-export type LiveReply = {
-    /** Feed one engine event; true when the view changed. Events after close are ignored. */
-    push(event: LeadProgress): boolean;
-    /** The turn ended (its outcome is the engine's, never inferred from text). Idempotent; a blocked close stays blocked. */
-    close(why: "answered" | "failed"): void;
-    view(): LiveView;
-    /** The status line now, also once a blocked preview closed while the turn runs on. */
-    status(): string;
-    /** Each step's tool calls, for a surface that lists them behind a disclosure. Fixed copy only, never model text. */
-    tools(): LeadLiveTool[][];
-    readonly turn: number | null;
-};
-/** One turn's live reply. `shape`: the owner's message (`asked`) and this app's origins, as the final reply is shaped. */
-export declare function createLiveReply(shape?: ShapeOptions, options?: {
-    queued?: boolean;
-}): LiveReply;
-export type LiveSender<V> = {
-    /** Offer the newest view: it replaces any view still waiting. Ignored once closed. */
-    offer(view: V): void;
-    /** Drop the waiting view, wait for the request in flight to settle, then refuse every later view. */
-    close(): Promise<void>;
-    /** Grows with every offered view; a transport may use it to refuse an older one. */
-    readonly generation: number;
-    readonly closed: boolean;
-};
-/**
- * The serialized sender for one live surface message (§2.4). `standing` re-proves the viewer's right to see this turn
- * before every send (it may await; the close is re-checked after it). `spacingMs` is the least time between two sends,
- * read before each one (a surface widens it after the platform asks for a pause). A failed send drops that view:
- * previews are best effort.
- */
-export declare function createLiveSender<V>(options: {
-    send: (view: V, generation: number) => unknown;
-    standing?: () => boolean | Promise<boolean>;
-    spacingMs?: number | (() => number);
-    now?: () => number;
-}): LiveSender<V>;

package/dist/live-terminal.d.ts

@@ -1,273 +0,0 @@
-import { type Git } from "./teardown-git.js";
-export type TerminalProgram = "claude" | "codex" | "shell";
-export declare const TERMINAL_PROGRAMS: readonly TerminalProgram[];
-/** At most this many running sessions per console, and this many kept at all (ended ones count until removed). */
-export declare const MAX_LIVE_TERMINALS = 8;
-export declare const MAX_KEPT_TERMINALS = 16;
-/** At most this many pages attached to one session (a desktop, a phone, a spare tab or two). */
-export declare const MAX_VIEWERS = 4;
-/** After SIGHUP, the terminal's processes have this long before SIGKILL. */
-export declare const CLOSE_GRACE_MS = 2000;
-/** Typed input not yet read by the program, per terminal: past this, more is refused until it reads. */
-export declare const MAX_PENDING_INPUT: number;
-/** How often a running terminal's processes are noted, so ones that outlive their parent are still known. */
-export declare const CUSTODY_REFRESH_MS = 5000;
-export declare const COLS: {
-    readonly min: 2;
-    readonly max: 500;
-};
-export declare const ROWS: {
-    readonly min: 1;
-    readonly max: 200;
-};
-/** The slice of node-pty this module uses, so tests can stand a fake in. */
-export type Pty = {
-    readonly pid: number;
-    /** The terminal device its processes have as their controlling terminal ("ttys012", "pts/3"); null when unknown. */
-    readonly tty: string | null;
-    /** Typed bytes queued for the program and not yet taken by the kernel; Infinity when it can't be measured. */
-    pendingInput(): number;
-    onData(listener: (data: string) => void): unknown;
-    onExit(listener: (exit: {
-        exitCode: number;
-        signal?: number;
-    }) => void): unknown;
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
-    kill(signal?: string): void;
-};
-export type PtySpawn = (file: string, args: string[], options: {
-    cwd: string;
-    env: NodeJS.ProcessEnv;
-    cols: number;
-    rows: number;
-}) => Pty;
-/** A device path as `ps` prints it: /dev/ttys012 → ttys012, /dev/pts/3 → pts/3. */
-export declare const ttyName: (path: unknown) => string | null;
-/**
- * node-pty's write queue (@lydell/node-pty 1.2.0-beta.15, pinned exactly): typed input waits in its
- * `_writeStream._writeQueue` until the kernel takes it. A shape this doesn't recognise is unmeasurable: Infinity, so
- * input is refused rather than queued without bound (a test pins the shape against the installed package).
- */
-export declare function pendingInputOf(pty: unknown): number;
-/** node-pty, if this install has it (an optional dependency with prebuilt binaries); null when it doesn't load. */
-export declare function loadPtySpawn(): PtySpawn | null;
-/** How many lines above the screen a terminal keeps for a page that attaches later. */
-export declare const SCREEN_SCROLLBACK_LINES = 5000;
-/**
- * The terminal as a page would see it now: every byte the program writes is parsed by a headless xterm here, so a page
- * that attaches later gets the screen, its scrollback and its modes (the alternate screen of a full-screen program, the
- * cursor, colours, bracketed paste, mouse reporting) — never a replay of raw output cut at an arbitrary byte, which
- * could split an escape sequence or redraw a full-screen program garbled.
- */
-export declare class ScreenMirror {
-    private readonly lines;
-    private readonly terminal;
-    private readonly serializer;
-    constructor(cols: number, rows: number, lines?: number);
-    write(data: string): void;
-    resize(cols: number, rows: number): void;
-    /** The screen as of this call (after everything written before it), handed to `done` once parsed. */
-    snapshot(done: (screen: string) => void): void;
-    dispose(): void;
-}
-/** One attached page. The host never waits on it. */
-export type TerminalViewer = {
-    output(data: Buffer): void;
-    control(message: TerminalControl): void;
-};
-export type TerminalControl = {
-    t: "hello";
-    cols: number;
-    rows: number;
-    program: TerminalProgram;
-    ended: boolean;
-} | {
-    t: "exit";
-    code: number | null;
-    signal: number | null;
-}
-/** The program isn't reading what's typed: input waits until it does. */
- | {
-    t: "input-full";
-};
-export type TerminalSummary = {
-    id: string;
-    owner: string;
-    /** The owner's account generation at start: a rotated credential or a re-sign-in elsewhere no longer reaches it. */
-    generation: number;
-    repo: string;
-    program: TerminalProgram;
-    branch: string;
-    worktree: string;
-    startedAt: string;
-    endedAt: string | null;
-    exit: {
-        code: number | null;
-        signal: number | null;
-    } | null;
-    /** Who ended it, when Toolroll did. */
-    endedBy: "owner" | "console" | null;
-    /**
-     * After it ends: "clean" once every process known to be its own is proved gone; "uncertain" when one outlived
-     * SIGKILL or the process table couldn't be read. Null while it runs or is being swept.
-     */
-    cleanup: "clean" | "uncertain" | null;
-};
-/**
- * Where a console's terminals are written down for the updater, which runs as another process (terminal-catalog.ts):
- * a start is reserved before any work and refused while an update owns admission; a program is running until its
- * sweep ends. The default keeps nothing (tests, a console without a database file).
- */
-export type TerminalLedger = {
-    /** Throws (with the reason in words) when no terminal may start now. */
-    reserve(id: string): void;
-    running(id: string): void;
-    release(id: string, cleanup: "clean" | "uncertain" | null): void;
-    /** The terminal is removed (its worktree went after a clean sweep): nothing of it is left to count. */
-    forget(id: string): void;
-};
-export declare class TerminalError extends Error {
-    constructor(message: string);
-}
-export type TerminalHostOptions = {
-    spawn: PtySpawn;
-    worktreeRoot: string;
-    /** Git for making and removing worktrees: hardened by default (teardown-git.ts), since a build can write .git/config. */
-    git?: Git;
-    /** How each program starts; the default looks up `claude`, `codex` and the login shell on PATH. */
-    programs?: Partial<Record<TerminalProgram, {
-        file: string;
-        args: string[];
-    }>>;
-    env?: () => NodeJS.ProcessEnv;
-    clock?: () => Date;
-    /** Start, close and remove, for the event log (never input or output). */
-    record?: (event: "start" | "close" | "remove" | "exit", session: TerminalSummary) => void;
-    maxSessions?: number;
-    /** Lines above the screen a terminal keeps for a page that attaches later (SCREEN_SCROLLBACK_LINES). */
-    scrollbackLines?: number;
-    closeGraceMs?: number;
-    ledger?: TerminalLedger;
-    /** The process table (tests stand a failing one in); null when it can't be read. */
-    processes?: () => ProcessTable | null;
-    /** Who else works in a worktree (tests stand theirs in); default worktreeResidents. */
-    residents?: (table: ProcessTable, worktreeReal: string, terminalStartedMs: number) => Set<number> | null;
-};
-/** The executable on PATH, or null. */
-export declare function onPath(name: string, env?: NodeJS.ProcessEnv): string | null;
-export declare class TerminalHost {
-    private readonly options;
-    private readonly sessions;
-    private starting;
-    private stopped;
-    private readonly clock;
-    private readonly env;
-    private readonly ledger;
-    private readonly processes;
-    private custodyTimer;
-    constructor(options: TerminalHostOptions);
-    private summary;
-    /** This person's sessions, newest first. */
-    list(owner: string): TerminalSummary[];
-    get(id: string): TerminalSummary | null;
-    private running;
-    /**
-     * Make the worktree and start the program in it. `admit` is asked again right before the program starts (after the
-     * slow git work): a person whose access or project went in between starts nothing.
-     */
-    start({ name: owner, generation }: {
-        name: string;
-        generation: number;
-    }, repoPath: string, program: TerminalProgram, size?: {
-        cols: number;
-        rows: number;
-    }, admit?: () => string | null): Promise<TerminalSummary>;
-    /**
-     * Attach a page: it gets the screen as it is now (ScreenMirror), then `hello`, then live output — what the program
-     * writes meanwhile is held and sent after the screen, in order. Returns its detach.
-     */
-    attach(id: string, viewer: TerminalViewer): () => void;
-    /** How many pages are attached now. */
-    viewerCount(id: string): number;
-    /** Type into the program. False (nothing queued) while it has MAX_PENDING_INPUT unread, or can't be measured. */
-    input(id: string, data: string): boolean;
-    resize(id: string, cols: number, rows: number): void;
-    private noteTimer;
-    /** Activity (output, typing) usually means a command started: note processes shortly after, at most every 250 ms. */
-    private noteSoon;
-    /** Note every running terminal's processes now, and keep doing so while any runs. */
-    private noteCustody;
-    /**
-     * End the program and everything that is its own: SIGHUP to every member (an interactive shell gives each job its own
-     * process group, so the leader's group is not enough), then SIGKILL, re-reading the process table each time so a
-     * child started during the close is caught too. Membership is the leader's descendants, every process with this
-     * terminal as its controlling terminal while the program runs, and every one noted while it ran, by pid and start
-     * time (membersOf). Each signal goes only to a process still that pid and start time; a process on the terminal after
-     * the program ended that was never noted, or a pid now someone else's, is never signalled and leaves the close
-     * uncertain. A process that detached itself from the terminal AND its parents before it was noted is not seen — the
-     * same as any terminal. Resolves when the sweep is done; never waits without bound.
-     */
-    close(id: string, by?: "owner" | "console"): Promise<void>;
-    private sweep;
-    /** Drop an ended session and its worktree (the branch stays: the work is there). Only after a clean sweep. */
-    remove(id: string): Promise<void>;
-    /** Whether new sessions may start (false once the console is stopping). */
-    get admitting(): boolean;
-    /**
-     * The console is stopping: admit nothing more, end every program, and wait (each sweep is bounded) for them.
-     * `clean` is false when any terminal's processes couldn't be proved gone.
-     */
-    stop(): Promise<{
-        clean: boolean;
-    }>;
-}
-/** One process: its parent, owner, controlling terminal and start time. */
-export type ProcessTable = Map<number, {
-    ppid: number;
-    uid: number;
-    tty: string;
-    started: string;
-}>;
-/** Every process from `ps` (macOS and Linux take these options); null when it can't be read, never an empty guess. */
-export declare function readProcessTable(): ProcessTable | null;
-/**
- * A terminal's processes in this table, by pid and start time: what was noted while it ran (still the same process),
- * the leader while it runs, everything whose controlling terminal is its terminal while it runs, and every descendant
- * of those. Never this console itself. Once the program has ended its terminal's name is no one's proof: the device
- * may already be someone else's, so a process on it that wasn't noted is not a member; it goes in `ambiguous` (when
- * given), and the close that meets one says it is uncertain rather than signal it.
- */
-export declare function membersOf(table: ProcessTable, session: {
-    leader: number;
-    tty: string | null;
-    known: ReadonlyMap<number, string>;
-    exitedAt: number | null;
-}, ambiguous?: Set<number>): Map<number, string>;
-/**
- * Each listed process's working directory (Linux: /proc; macOS: lsof), and which ones couldn't be read (a setgid
- * helper such as ssh-agent is unreadable even to its own user). Null when the lookup itself failed: a timeout, a signal
- * or partial output is never a smaller answer. A process gone in between is simply absent.
- */
-export declare function cwdsOf(pids: readonly number[]): {
-    cwds: Map<number, string>;
-    unreadable: number[];
-} | null;
-/**
- * This user's processes working inside a terminal's worktree, whoever started them. They are never signalled (one may
- * be the person's own shell or a server they started from elsewhere); while any remains, the terminal's cleanup is
- * uncertain and its worktree stays. Null when that can't be known: the lookup failed, or a process whose working
- * directory can't be read started after the terminal did (one from before — a login's ssh-agent — can't be its own).
- */
-export declare function worktreeResidents(table: ProcessTable, worktreeReal: string, terminalStartedMs?: number): Set<number> | null;
-/** One client frame, read strictly; null closes the socket. */
-export type TerminalInput = {
-    t: "in";
-    d: string;
-} | {
-    t: "resize";
-    cols: number;
-    rows: number;
-};
-export declare const MAX_FRAME_BYTES: number;
-export declare function parseTerminalFrame(text: string): TerminalInput | null;

package/dist/live.d.ts

@@ -1,152 +0,0 @@
-/**
- * The live window (arc 1): what the running agent is saying, on disk, for
- * the run page to poll — and NOTHING else.
- *
- * This file is display state, not evidence. No artifact row points at it,
- * no digest binds it, and the page that renders it says so: the machine
- * running the agent could alter it. It exists so a person can watch work
- * happen without a terminal, and every byte in it went through the same
- * sanitize discipline as the peek: controls stripped, credential-shaped
- * lines replaced whole, tool activity described in OUR fixed vocabulary —
- * event metadata is never echoed.
- *
- * Fail-soft everywhere: a live view that cannot be written must never
- * break, slow, or reclassify a build.
- */
-import { type KeyState, type LiveActivityKind, type LiveRecord, type LiveRecorderOptions } from "./live-records.js";
-export declare const LIVE_LINE_CAP: number;
-export declare const LIVE_FILE_CAP: number;
-export declare const LIVE_REDACTED_LINE = "[a credential-shaped line was redacted]";
-/** Finalized runs keep their live file this long for the final drain. */
-export declare const LIVE_RETAIN_MS: number;
-/** The bounded sweep: at most this many FINALIZED runs' files survive a pass (a run's records and its subagents' file
- * count as one). */
-export declare const LIVE_FILE_BOUND = 500;
-/** A run's subagent file (docs/plans/agents-view.md §2.3) is never larger than this; its writer stops there. */
-export declare const LIVE_SUB_FILE_CAP: number;
-/** All finished and orphan live files together stay under this; the oldest runs go first past it. */
-export declare const LIVE_TOTAL_BYTES: number;
-export declare function liveDir(root: string): string;
-/** The exact filename, from the numeric id and nothing else — no user
- * input is ever parsed into this path. Records (`.jsonl`) are what every
- * run writes now; the name is the format. */
-export declare function liveLogPath(root: string, runId: number): string;
-/** A run's subagents' records (docs/plans/agents-view.md §2.3): the run's file, swept with it. */
-export declare function liveSubLogPath(root: string, runId: number): string;
-/** The plain-text file runs wrote before the live conversation; read until it ages out. */
-export declare function legacyLiveLogPath(root: string, runId: number): string;
-export { LIVE_ACTIVITY_KINDS, type LiveActivityKind } from "./live-records.js";
-/**
- * What one stream event says the agent just did, as one fixed kind: the
- * last-activity line's only input. Never text, names or arguments; an
- * event that says nothing (results, deltas, subagent chatter) is null.
- */
-export declare function liveActivityKind(event: Record<string, unknown>): LiveActivityKind | null;
-/** Sanitize one display line: strip controls and bidi overrides, redact whole on any secret hit, cap. */
-export declare function sanitizeTranscriptLine(line: string): string;
-export type LiveLog = {
-    observe(event: Record<string, unknown>): void;
-    close(): void;
-};
-/**
- * Open the run's live file for appending records. The directory is 0700,
- * the file 0600 and CREATED HERE (O_EXCL: a name that already exists —
- * whatever put it there — is refused, not appended to), opened O_NOFOLLOW
- * with the descriptor retained for the run's whole duration. `options` is
- * the run's trusted context: its checkout, and whether its project shows
- * commands (read once, here). Returns null on any failure: no live view is
- * ever worth a build.
- */
-export declare function openLiveLog(root: string, runId: number, options?: Partial<LiveRecorderOptions>): LiveLog | null;
-export type LiveFormat = "records" | "text";
-export type LiveWindowRead = {
-    ok: true;
-    /** Complete lines read from `from`: records (JSON lines) or legacy text. */
-    text: string;
-    nextOffset: number;
-    eof: boolean;
-    format: LiveFormat;
-    /** Which file this offset belongs to: a client holding another resets. */
-    gen: string;
-} | {
-    ok: false;
-    reason: "missing" | "replaced" | "unreadable";
-};
-/**
- * Read the live file from a byte offset, returning only COMPLETE lines
- * (through the last LF in the window). The records file is read when it
- * exists, else the legacy text file. The descriptor is the authority:
- * opened O_NOFOLLOW | O_NONBLOCK inside a real live directory, proved a
- * regular file, measured and read through itself. A file smaller than the
- * offset was replaced — the caller resets, visibly, and `gen` names the file
- * so an offset is never reused against another one. A line longer than the
- * whole window is skipped through its end, so a reader never stalls.
- * `allowTail` (the final drain) returns the unterminated tail after
- * finalization. Legacy text is cleaned again on the way out.
- */
-export declare function readLiveWindow(root: string, runId: number, from: number, allowTail?: boolean): LiveWindowRead;
-/** A window's complete lines as the plain words the run page and `toolroll peek` show, whatever its format. `commands` is
- * the run's own captured answer (store.ts runLiveCommands), never the file's say. */
-export declare function liveWindowLines(read: {
-    text: string;
-    format: LiveFormat;
-}, commands: boolean, keys?: KeyState): string[];
-/** A window as records, whatever its format: an older plain file's lines become the agent's words. Command text and
- * output show only when the run's own captured answer (`commands`) is on. */
-export declare function liveWindowRecords(read: {
-    text: string;
-    format: LiveFormat;
-}, commands: boolean, keys?: KeyState): LiveRecord[];
-/**
- * Enforce a run's captured "Show commands" answer on read: the file is build-writable, so an `open` record, a command
- * step's text or a step's output may say anything. With the answer off, every `open` reads the base tier, command steps
- * lose their text and steps lose their output. (The older plain-text format predates command detail and is unchanged.)
- */
-export declare function withholdCommands(records: LiveRecord[], commands: boolean): LiveRecord[];
-export type LiveSweepVerdict = {
-    /** run id, or null when the name is not a run's file. */
-    runId: number | null;
-    fileName: string;
-    /** The most a file of this name is ever written to (records, subagents, older text); null for a name we never write. */
-    cap: number | null;
-};
-/**
- * Enumerate the live directory for the reconcile sweep: names only. Pure listing — the CALLER settles which runs are
- * finalized before it measures anything; this module only refuses to guess. Non-run names are reported with runId
- * null (orphans from nothing this plane wrote; aged on mtime like everything else).
- */
-export declare function listLiveFiles(root: string): LiveSweepVerdict[];
-/** Remove one live file, silently: a sweep never throws over display state. True when it is gone now. */
-export declare function removeLiveFile(root: string, fileName: string, unlink?: (path: string) => void): boolean;
-type SweepRun = {
-    outcome: string | null;
-    finishedAt: string | null;
-};
-/** What the sweep reads of the store: a run's state, and (production) the write lock run admission also takes. */
-export type LiveSweepStore = {
-    getRun(id: number): SweepRun | null;
-    transact?<T>(body: () => T): T;
-};
-/**
- * The reconcile sweep (arc 1 §2): ACTIVE runs are exempt ABSOLUTELY — the
- * transport's no-truncation assumption depends on it — and a run's files
- * (its records, its subagents' file, an older text file) go together, as one.
- * A run is settled finished (or absent) BEFORE its files are measured.
- * Finalized runs age from finished_at; orphans (no run row, or a name this
- * plane never writes) age from mtime. Among the finalized-or-orphan: a file
- * far past its own cap goes at once, then the day's retention, then the
- * 500-run bound, then the total byte limit, oldest first, until each limit is
- * really met or nothing eligible is left. Each removal re-proves, under the
- * store's write lock (the one run admission takes), that the run is still
- * not active and the file is the very one measured; otherwise it is kept. A
- * file that can't be removed stays counted and never stops the rest.
- */
-export declare function sweepLiveLogs(store: LiveSweepStore, root: string, now: Date, io?: {
-    unlink?: (path: string) => void;
-    lstat?: (path: string) => import("node:fs").Stats;
-    /** Test seams: before a removal starts, and right after its run-state check (before the claim). */
-    beforeRemove?: (fileName: string) => void;
-    afterCheck?: (fileName: string) => void;
-}): {
-    removed: string[];
-};