toolroll 0.9.104 → 0.9.105

package/dist/link.d.ts

@@ -1,72 +0,0 @@
-/**
- * Putting the command on PATH, as an explicit act.
- *
- * Toolroll refuses to install things on an operator's behalf — it prints
- * the command and its side effects and lets them run it. A tool that applied
- * that rule to `bd init` and then quietly edited PATH during its own install
- * would not deserve to be believed, so this is a command you run, it shows
- * you what it will do before it does it, and `unlink` undoes it exactly.
- *
- * Three rules hold throughout: never sudo, never a directory outside the home
- * directory unless explicitly named, and never delete anything that is not
- * something we put there.
- *
- * Two mechanisms, because "a command on PATH" means different things. On POSIX
- * it is a symlink with the execute bit set. On Windows the shell resolves
- * commands through PATHEXT, so an extensionless symlink is invisible no matter
- * which directory it sits in — there it is a `.cmd` shim, which is also what
- * npm writes, and which needs no Developer Mode to create.
- */
-/** What you type. */
-export declare const BIN_NAME = "toolroll";
-/** What lands on disk. Windows needs the extension to resolve it through PATHEXT. */
-export declare const LINK_FILE: string;
-export type TargetChoice = {
-    dir: string;
-    onPath: boolean;
-};
-export type LinkPlan = {
-    action: "create";
-    source: string;
-    target: string;
-} | {
-    action: "already";
-    source: string;
-    target: string;
-} | {
-    action: "replace";
-    source: string;
-    target: string;
-    current: string;
-} | {
-    action: "conflict";
-    source: string;
-    target: string;
-    reason: string;
-};
-export type UnlinkPlan = {
-    action: "remove";
-    target: string;
-    current: string;
-} | {
-    action: "absent";
-    target: string;
-} | {
-    action: "foreign";
-    target: string;
-    reason: string;
-};
-/**
- * Where the link should go. Only directories inside the home directory are
- * ever proposed: everything else needs sudo, and needing sudo to read your own
- * git repositories would be absurd.
- */
-export declare function chooseTarget(options: {
-    pathEntries: readonly string[];
-    home: string;
-    override?: string;
-}): TargetChoice;
-export declare function planLink(source: string, dir: string): Promise<LinkPlan>;
-export declare function applyLink(plan: LinkPlan): Promise<void>;
-export declare function planUnlink(dir: string): Promise<UnlinkPlan>;
-export declare function applyUnlink(plan: UnlinkPlan): Promise<void>;

package/dist/live-backup.d.ts

@@ -1,39 +0,0 @@
-import { type LiveBackupCopy, type LiveBackupSettings, type Store } from "./store.js";
-/** The choices Settings offers, in minutes (0: off is its own choice). */
-export declare const LIVE_EVERY_MINUTES: readonly [1, 5, 15, 30];
-/** Daily copies are kept this many days besides the newest `keep`. */
-export declare const LIVE_DAILY_DAYS = 7;
-/** `backups/live` beside the database, through its real path (the folder check refuses a path through a link). */
-export declare function defaultLiveFolder(databaseFile: string): string;
-export declare const liveFolderOf: (settings: LiveBackupSettings, databaseFile: string) => string;
-/** Why a folder can't hold the copies, or null. Missing is fine (it is made on first use, then checked again). */
-export declare function liveFolderProblem(folder: string, forbidden: readonly string[], protectedRoot?: string): string | null;
-/** This database's copies in a folder, newest first (plain files named for it only). */
-export declare function liveCopies(folder: string, tag: string): {
-    name: string;
-    path: string;
-    day: string;
-}[];
-/** Keep the newest `keep`, the newest of each of the last LIVE_DAILY_DAYS days, and `protect`; remove the rest (and
- * this database's partial files older than an hour). Never anything not named for this database. */
-export declare function pruneLiveCopies(folder: string, tag: string, keep: number, now: Date, protect: string | null): number;
-/** One copy on a worker thread: copied, checked, hashed and renamed into place, or a problem (nothing left behind). */
-export declare function copyOffThread(source: string, folder: string, tag: string, now: Date): Promise<{
-    ok: true;
-    copy: Omit<LiveBackupCopy, "madeAt">;
-} | {
-    ok: false;
-    problem: string;
-}>;
-/** Whether a copy is due: on, and the latest (or the latest try) is at least the schedule old. */
-export declare function liveCopyDue(store: Store, now: Date): boolean;
-/** One pass: hold the lease, and when due check the folder, copy, record and prune. */
-export declare function liveBackupPass(store: Store, databaseFile: string, holder: string, forbidden: () => readonly string[], clock?: () => Date): Promise<{
-    ok: true;
-    copy: LiveBackupCopy;
-} | {
-    ok: false;
-    problem: string;
-} | null>;
-/** The loop in the worker: a pass a minute (the first after 30 s). The returned stop waits for a copy under way. */
-export declare function startLiveBackups(store: Store, databaseFile: string, forbidden: () => readonly string[], everyMs?: number): () => Promise<void>;

package/dist/live-bus.d.ts

@@ -1,141 +0,0 @@
-/**
- * Live views push on write. Nothing here polls once a second.
- *
- * - The bus. Every connection's write wrapper (workspace-revision.ts)
- *   moves one counter per committed meaningful write. After each in-process
- *   transact() COMMIT, and whenever another process (the worker, the CLI)
- *   writes the database's write-ahead log, the revision is read once; when
- *   it moved, every subscriber hears `{ revision }`. A rolled-back or quiet
- *   write moves nothing and says nothing. A page left open with nothing
- *   being written costs no database work at all.
- * - The rooms. Each open task or flow is a room keyed by what it shows.
- *   When the bus speaks, a room rechecks every viewer's access (a signed-out
- *   or narrowed account is dropped), takes its fingerprint once, and only if
- *   that moved tells its pages `change` with the fingerprint and revision —
- *   an invalidation, never content. The page reads itself again under its
- *   own checks, so redaction stays the page's.
- * - The safety net. Every room also checks itself about every 30 s, so a
- *   missed signal heals; the page's connection sends a keep-alive between,
- *   each after every room proves its viewer again.
- * - One connection per page. A page opens one stream (GET /live) and joins
- *   every room it shows; each event names its room.
- * - Back-pressure. Each page's stream is bounded: a page that falls behind
- *   gets one `reload` and ends so its EventSource can reconnect.
- *
- * Transport seam: a future WebSocket (live cursors) subscribes to the same
- * LiveBus beside these SSE rooms; nothing in the Store or its write wrapper changes.
- */
-import { type FSWatcher } from "node:fs";
-import type { ServerResponse } from "node:http";
-import type { Store } from "./store.js";
-export type LiveChange = {
-    revision: string;
-};
-export type LiveBus = {
-    subscribe: (listener: (change: LiveChange) => void) => () => void;
-    publish: (change: LiveChange) => void;
-    /** The last revision heard, if any. */
-    revision: () => string | null;
-    listeners: () => number;
-};
-export declare function createLiveBus(): LiveBus;
-export type WorkspaceFollower = {
-    close: () => void; /** Read the revision now (tests, and a commit signal). */
-    check: () => void;
-};
-/**
- * Publish the workspace revision when it moves: after this process commits,
- * and when the database's write-ahead log changes under another process.
- * Signals in one turn of the event loop coalesce into one read.
- */
-export declare function followWorkspace(store: Store, current: () => string, bus: LiveBus, options?: {
-    file?: string | null;
-    watchFile?: (path: string, listener: () => void) => FSWatcher | null;
-}): WorkspaceFollower;
-/** About every 30 s a room checks itself; a keep-alive goes between. */
-export declare const SAFETY_NET_MS = 30000;
-export declare const KEEP_ALIVE_MS = 15000;
-/** What a page's stream may hold unsent before it is "behind". */
-export declare const STREAM_LIMIT_BYTES: number;
-/** One page's stream, bounded. Overflow is terminal, even below Node's drain threshold. */
-export declare class LiveStream {
-    readonly response: ServerResponse;
-    private readonly limit;
-    private readonly onOverflow;
-    private ended;
-    constructor(response: ServerResponse, limit?: number, onOverflow?: () => void);
-    get open(): boolean;
-    private overflow;
-    private write;
-    send(event: string, data: unknown): void;
-    keepAlive(): void;
-}
-/**
- * One page's live connection: its bounded stream, one keep-alive, and every
- * room it joined. Each event names its room, so one EventSource serves the
- * whole page. It ends when the page goes, when it falls behind (one
- * `reload`), or when its last room lets it go. A keep-alive is a delivery
- * too: every room proves its viewer again first, so a page whose session
- * lapsed with nothing written hears its rooms go, never another frame.
- */
-export declare class LiveConnection {
-    readonly response: ServerResponse;
-    readonly stream: LiveStream;
-    private readonly leaves;
-    private readonly proofs;
-    private readonly timer;
-    private closed;
-    private refusing;
-    constructor(response: ServerResponse, options?: {
-        limitBytes?: number;
-        keepAliveMs?: number;
-    });
-    private keepAlive;
-    /** Run before each keep-alive: a room proves its viewer again (and leaves if it no longer passes). Returns the undo. */
-    onKeepAlive(prove: () => void): () => void;
-    get open(): boolean;
-    /** An event for one room: its data says which. */
-    send(room: string, event: string, data?: Record<string, unknown>): void;
-    /** A room leaves because its proof failed (a sign-out, a revoked or narrowed account): if that departure ends the
-     * connection, the page is told the stream `ended` and stops, rather than reconnecting at once into a request that
-     * can't sign in. Any other close — the page going, a later shutdown, an overflow — says nothing of it. */
-    refuse(leave: () => void): void;
-    /** Run when the connection ends; returns the undo for a room that leaves first. */
-    onClose(leave: () => void): () => void;
-    close(): void;
-    /** Rooms joined and not yet left. */
-    get rooms(): number;
-}
-/** One page in one room: who, the room's name as the page asked for it, the page's connection, and its re-proof. */
-export type LiveViewer = {
-    name: string;
-    room: string;
-    connection: LiveConnection;
-    valid: () => boolean;
-};
-export type LiveRooms<K, V extends LiveViewer> = {
-    /** Keep this page on the room until it leaves; the first events say where the room stands (and who's here). */
-    join: (key: K, viewer: V) => void;
-    /** Every page leaves (the server is closing). */
-    close: () => void;
-    size: () => number;
-};
-/** `minIntervalMs`: a busy room says `change` at most this often — the first at once, the latest after. */
-export type LiveRoomOptions = {
-    bus?: LiveBus | null;
-    safetyNetMs?: number;
-    minIntervalMs?: number;
-    /** A room whose read is costly reads at most once per this window after a signal; every viewer is still re-proved
-     * the moment a signal arrives (and again at the read). */
-    readSettleMs?: number;
-    /** Told when a room's last viewer has left and the room is gone (state kept per room can go with it). */
-    onEmpty?: (key: unknown) => void;
-};
-/**
- * Rooms of open pages that hear the bus. `presence` says who else is here, as
- * each page should see it (null: the room has no presence). A viewer that no
- * longer passes its re-proof hears `gone` and leaves; a room whose subject is
- * gone (fingerprint null) sends everyone `gone`. A connection with no rooms
- * left ends.
- */
-export declare function createLiveRooms<K, V extends LiveViewer>(fingerprint: (key: K) => string | null, presence: ((viewers: readonly V[], me: string) => unknown) | null, options?: LiveRoomOptions): LiveRooms<K, V>;

package/dist/live-children-read.d.ts

@@ -1,52 +0,0 @@
-import { type LiveRecord } from "./live-records.js";
-export declare const CURSOR_CAP: number;
-/** Longer than any real key block: past this much of a stream's text with no END marker, its key state is known again. */
-export declare const UNKNOWN_KEY_BYTES: number;
-export type ChildView = {
-    k: "child";
-    s: number;
-    at?: string;
-    parent: string | null;
-    via?: number;
-    desc?: string;
-} | {
-    k: "end";
-    s: number;
-    at?: string;
-    ok: boolean | null;
-} | {
-    k: "over";
-}
-/** The file stopped at its size cap: nothing more will be written. */
- | {
-    k: "cap";
-} | (LiveRecord & {
-    s: number;
-});
-export type ChildWindow = {
-    ok: true;
-    records: ChildView[];
-    cursor: string;
-    /** A cursor was given but didn't hold (forged, stale, another run's or file's): this read started over. */
-    restarted: boolean;
-    /** Output before this read's start isn't shown (the read began at a checkpoint, or waits for one). */
-    earlier: boolean;
-    /** Records that failed a check: counted, never shown. */
-    quarantined: number;
-    /** Lines too long to show that were skipped. */
-    skipped: number;
-    /** More is already written: read again. */
-    more: boolean;
-} | {
-    ok: false;
-    reason: "missing" | "unavailable";
-};
-/** Seal a reader's state under the caller's key (the same form for the run's own file and its subagents'). */
-export declare function sealCursor(state: object, key: Buffer): string;
-/** A sealed state's object when the seal holds and it is within the cap; null otherwise (the caller re-checks it). */
-export declare function openCursor(cursor: string, key: Buffer): Record<string, unknown> | null;
-/** One window of a run's subagents' file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
-export declare function readChildWindow(root: string, runId: number, cursor: string | null, options: {
-    key: Buffer;
-    commands: boolean;
-}): ChildWindow;

package/dist/live-children.d.ts

@@ -1,73 +0,0 @@
-import { type LiveRecord, type LiveRecorderOptions } from "./live-records.js";
-export declare const CHILD_STREAMS_CAP = 16;
-export declare const CHILD_DELEGATIONS_CAP = 32;
-export declare const CHILD_OPEN_STEPS_CAP = 32;
-export declare const CHILD_DEPTH_CAP = 2;
-/** A checkpoint at least this often, in bytes of child records. */
-export declare const CHILD_CHECKPOINT_BYTES: number;
-export type ChildCheckpoint = {
-    s: number;
-    parent: string | null;
-    via?: number;
-    open: string[];
-    inKey: boolean;
-    tail?: string;
-    ended?: true;
-    /** What the reader shows for a stream it first learns of here (a read that starts mid-file): its description, start,
-     * open steps (as written, already redacted) and, once ended, when and how. Display only; never sealed in a cursor. */
-    desc?: string;
-    at?: string;
-    steps?: {
-        id: string;
-        kind: string;
-        target?: string;
-    }[];
-    endedAt?: string;
-    ok?: boolean | null;
-};
-export type ChildRecord = (LiveRecord & {
-    s: number;
-}) | {
-    k: "child";
-    s: number;
-    at: string;
-    parent: string | null;
-    via?: number;
-    desc?: string;
-} | {
-    k: "end";
-    s: number;
-    at: string;
-    ok: boolean | null;
-} | {
-    k: "over";
-    at: string;
-} | {
-    k: "ckpt";
-    at: string;
-    streams: ChildCheckpoint[];
-    dropped: number;
-};
-/** At most about this many bytes of one event's records reach the file; past it words and one-off steps give way to one
- * `cut`, so a checkpoint (written between events) is never far behind any position. */
-export declare const CHILD_EVENT_WORDS_CAP: number;
-/** The child recorder: every stream event in, the subagents' records out. Hand `parentStep` to the run's own recorder
- * (LiveRecorderOptions.onStep) so a delegation names the parent's step it really opened. Never throws. */
-export declare function createChildRecorder(options: Omit<LiveRecorderOptions, "keyState" | "onStep">): {
-    observe(event: Record<string, unknown>): ChildRecord[];
-    parentStep(call: string | null, id: string, target: string | null): void;
-    end(): ChildRecord[];
-    checkpoint(): ChildRecord;
-};
-/**
- * The subagents' file, opened the first time a subagent speaks (a run without one has none): created here (O_EXCL,
- * O_NOFOLLOW, 0600, the live directory 0700), appended to, and closed with the run. It stops at LIVE_SUB_FILE_CAP
- * with one `cap` record, reserved inside the cap. Fail-soft: no live view is ever worth a build.
- */
-export declare function childLogWriter(root: string, runId: number): {
-    /** Whether the next batch should be preceded by a checkpoint (take it BEFORE the batch is recorded: its state is then
-     * exactly the state at that position in the file). */
-    due(): boolean;
-    append(records: readonly ChildRecord[], before: ChildRecord | null): void;
-    close(): void;
-};

package/dist/live-detail.d.ts

@@ -1,27 +0,0 @@
-import { type Store } from "./store.js";
-/** The consent a "Show commands" form carries: a single-use nonce minted for this person and these exact terms. */
-export declare const LIVE_VIEW_CONSENT = "live-view";
-export declare function liveViewConsentDigest(repo: string): string;
-export type LiveDetailSetting = {
-    repo: string;
-    commands: boolean;
-    updatedBy: string;
-    updatedAt: string;
-};
-/** Whether this project's live conversations show commands. Unknown or absent is off. */
-export declare function liveCommandsShown(store: Store, repo: string | null): boolean;
-/** Save the setting and its ledger line in one transaction. The caller has proved who is asking (and, to turn it on, their password). */
-export declare function setLiveCommands(store: Store, change: {
-    repo: string;
-    commands: boolean;
-    by: string;
-    via: string;
-}, now: Date): {
-    said: string;
-};
-/** A run's trusted context for its live file: its own checkout, and its project's setting, captured for the run now —
- * before the file opens. The writer uses the captured answer: a capture that fails writes no commands. */
-export declare function liveLogContext(store: Store, runId: number, taskRef: number, worktree: string | null, now: Date): {
-    base: string | null;
-    commands: boolean;
-};

package/dist/live-input.d.ts

@@ -1,68 +0,0 @@
-/** The child's stdin, as the transport hands it over. */
-export type LiveInputIo = {
-    write(line: string): void;
-    end(): void;
-};
-/** Why stdin closed: the handoff was written, the session had nothing more owed, the turn budget ran out, a paused
- * session reached the idle limit, the process ended first, or a write failed. */
-export type LiveCloseReason = "finished" | "settled" | "turn-budget" | "paused-idle" | "ended" | "input-failed";
-/** What Resume sends a paused session: only a nudge to go on, never a note. */
-export declare const CONTINUE_TEXT = "continue";
-export type LiveInputOptions = {
-    /** Toolroll's total for the whole session: distinct assistant turns across every message. */
-    maxTurns: number;
-    /** The agent wrote its handoff (done, park or a plan revision): a turn that ends now closes stdin. */
-    finished?: () => boolean;
-    /** stdin is attached and the brief was written. */
-    onOpen?: () => void;
-    onClose?: (why: LiveCloseReason) => void;
-    /** The current turn stopped for a Pause (the harness confirmed the interrupt, or the turn's result arrived). */
-    onPaused?: () => void;
-};
-/** A stdin user frame, in the shape the harness reads. */
-export declare const userFrame: (text: string, uuid: string) => string;
-/** A stdin interrupt: stop the current turn, keep the session. */
-export declare const interruptFrame: (requestId: string, cancelQueued?: boolean) => string;
-export declare class LiveInput {
-    #private;
-    readonly maxTurns: number;
-    /** The brief's frame uuid, once begun. */
-    briefUuid: string | null;
-    constructor(options: LiveInputOptions);
-    /** Queue the brief as the first frame. Once, before the process is attached. */
-    begin(brief: string, uuid?: string): void;
-    /** The transport spawned the child with stdin piped: write what is queued, brief first. */
-    attach(io: LiveInputIo): void;
-    /** stdin is attached and still open: a note reaches the agent in seconds, and a Pause can stop its turn. */
-    get open(): boolean;
-    get paused(): boolean;
-    /** Distinct assistant turns so far, across every message. */
-    get turns(): number;
-    /** Why stdin closed, once it has. */
-    get closeReason(): LiveCloseReason | null;
-    /**
-     * Send a note (or anything the session should read next). A paused session continues. False once stdin is closed.
-     * Mid-turn, the harness folds it into the running turn; after an interrupt that turn is over, so the frame starts a
-     * turn of its own whose result is owed before stdin closes.
-     */
-    send(text: string, uuid: string): boolean;
-    /** Resume a paused session with a short continue frame and no note. "not-paused" when nothing waits to go on. */
-    resume(uuid: string): "sent" | "not-paused" | "closed";
-    /**
-     * The transport's idle limit was reached. A paused session closes stdin instead of being killed — the harness exits
-     * and the build settles from whatever handoff it saved — and true asks the watchdog to wait once more for that exit.
-     * Anything else is an ordinary idle timeout.
-     */
-    idleLimit(): boolean;
-    /**
-     * Pause: stop the current turn, keep the session. "sent" when an interrupt was written; "idle" when no turn was
-     * running (the session is already waiting, so it is paused as it stands); "closed" when stdin is gone.
-     */
-    interrupt(requestId: string): "sent" | "idle" | "closed";
-    /** Every parsed stdout event, in order. */
-    observe(event: Record<string, unknown>): void;
-    /** Close stdin: the harness finishes what it has and exits. Further sends refuse. */
-    close(why: LiveCloseReason): void;
-    /** The process ended (or its stdin failed): nothing more is written. */
-    detach(why?: "ended" | "input-failed"): void;
-}

package/dist/live-main-read.d.ts

@@ -1,19 +0,0 @@
-import { type LiveRecord } from "./live-records.js";
-export type MainWindow = {
-    ok: true;
-    records: LiveRecord[];
-    cursor: string;
-    restarted: boolean;
-    earlier: boolean;
-    quarantined: number;
-    skipped: number;
-    more: boolean;
-} | {
-    ok: false;
-    reason: "missing" | "unavailable";
-};
-/** One window of a run's own live file. `commands` is the run's own captured answer (store.ts runLiveCommands). */
-export declare function readMainWindow(root: string, runId: number, cursor: string | null, options: {
-    key: Buffer;
-    commands: boolean;
-}): MainWindow;

package/dist/live-notes.d.ts

@@ -1,20 +0,0 @@
-import type { Store } from "./store.js";
-export declare const RUN_NOTES_SHOWN = 20;
-export type RunNote = {
-    id: number;
-    author: string;
-    /** Whether the person looking wrote it: only then does the view say "You". */
-    mine: boolean;
-    at: string;
-    text: string;
-    standing: string;
-    readAt: string | null;
-};
-/** This run's notes, oldest first: the newest RUN_NOTES_SHOWN, and how many older ones the task page keeps. */
-export declare function runNotes(store: Store, run: {
-    id: number;
-    taskRef: number;
-}, viewer: string, now: Date): {
-    notes: RunNote[];
-    older: number;
-};

package/dist/live-open.d.ts

@@ -1,28 +0,0 @@
-export declare const READ_WINDOW: number;
-export declare const SCAN_BUDGET: number;
-export type LiveOpened = {
-    fd: number;
-    gen: string;
-    size: number;
-};
-/** Test seams only: run between the checks, to swap things under the opener. */
-export type OpenSeams = {
-    afterOpen?: () => void;
-};
-/** Open `name` in the run's live directory under `root`, or say it is missing or unavailable. */
-export declare function openLiveTrusted(root: string, name: string, seams?: OpenSeams): LiveOpened | "missing" | "unavailable";
-export type LineRead = {
-    /** Complete lines, each with the offset just past its newline. */
-    lines: {
-        text: string;
-        end: number;
-    }[];
-    /** Where the next request starts. */
-    next: number;
-    /** Lines too long to show that were skipped here. */
-    skipped: number;
-    /** The scan budget ran out inside a line: the next request resumes discarding through that line's end. */
-    skipping: boolean;
-};
-/** Read complete lines from `from` (discarding first through the next newline when `skipping`), within the budgets. */
-export declare function readLiveLines(fd: number, size: number, from: number, skipping?: boolean): LineRead;