toolroll 0.9.59 → 0.9.61

package/dist/store.d.ts

@@ -78,6 +78,15 @@ export declare const FLOW_SEND_SCHEMA = "\nCREATE TABLE IF NOT EXISTS flow_send
  * vocabulary and when — never text, tool names or arguments. Display state, not evidence;
  * a finished run's row goes with the live log's own retention (sweepRunActivity). */
 export declare const RUN_ACTIVITY_SCHEMA = "\nCREATE TABLE IF NOT EXISTS run_activity (\n  run  INTEGER PRIMARY KEY REFERENCES run(id) ON DELETE CASCADE,\n  kind TEXT NOT NULL CHECK (kind IN ('session','message','edit','command','read','search','lookup','plan','delegate','tool')),\n  at   TEXT NOT NULL\n);\n";
+/** Pausing a running Claude build (live steering, v121: additive only). A person's Pause asks the build to
+ * stop its current turn and keep its session: one row per request, bound to the exact run it was asked of, under the
+ * request id the asker chose (a repeated request is the same request). `note` is the steering note a Pause and steer
+ * sends right after the interrupt. The builder's dispatcher stamps sent_at when the interrupt is written, paused_at when
+ * the turn stopped, resumed_at when a later note continued the session, and ended_at when the run stopped taking input
+ * first. Never a stop: nothing here ends, holds or reclaims an attempt (run_stop does that). A person's Resume (run_resume)
+ * continues a paused build with a short continue frame and no note: one row per request, bound to the exact paused run;
+ * sent_at when the frame was written, ended_at when the run was no longer paused to take it. */
+export declare const LIVE_STEER_SCHEMA = "\nCREATE TABLE IF NOT EXISTS run_pause (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  run           INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  task_ref      INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,\n  request_id    TEXT NOT NULL UNIQUE,\n  requested_by  TEXT NOT NULL,\n  requested_via TEXT NOT NULL CHECK (requested_via IN ('cli','web','chat')),\n  requested_at  TEXT NOT NULL,\n  note          INTEGER REFERENCES task_steer(id) ON DELETE SET NULL,\n  sent_at       TEXT,\n  paused_at     TEXT,\n  resumed_at    TEXT,\n  ended_at      TEXT\n);\nCREATE INDEX IF NOT EXISTS run_pause_by_run ON run_pause (run, id);\nCREATE TABLE IF NOT EXISTS run_resume (\n  id            INTEGER PRIMARY KEY AUTOINCREMENT,\n  run           INTEGER NOT NULL REFERENCES run(id) ON DELETE CASCADE,\n  task_ref      INTEGER NOT NULL REFERENCES task_ref(id) ON DELETE CASCADE,\n  request_id    TEXT NOT NULL UNIQUE,\n  requested_by  TEXT NOT NULL,\n  requested_via TEXT NOT NULL CHECK (requested_via IN ('cli','web','chat')),\n  requested_at  TEXT NOT NULL,\n  sent_at       TEXT,\n  ended_at      TEXT\n);\nCREATE INDEX IF NOT EXISTS run_resume_by_run ON run_resume (run, id);\n";
 export declare const CHAT_APPROVAL_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_approval_setting (\n  approver             TEXT NOT NULL,\n  scope                TEXT NOT NULL,\n  enabled              INTEGER NOT NULL CHECK (enabled IN (0,1)),\n  full_access          INTEGER NOT NULL DEFAULT 0 CHECK (full_access IN (0,1)),\n  attempt_cap_microusd INTEGER CHECK (attempt_cap_microusd IS NULL OR attempt_cap_microusd >= 0),\n  generation           INTEGER NOT NULL,\n  digest               TEXT NOT NULL,\n  updated_by           TEXT NOT NULL,\n  updated_at           TEXT NOT NULL,\n  PRIMARY KEY (approver, scope)\n);\n";
 export declare const CHAT_DECIDE_SCHEMA = "\nCREATE TABLE IF NOT EXISTS chat_decide_action (\n  token       TEXT PRIMARY KEY,\n  channel     TEXT NOT NULL,\n  binding     INTEGER NOT NULL,\n  chat        TEXT NOT NULL,\n  message     TEXT,\n  act         TEXT NOT NULL CHECK (act IN ('accept','changes','retry','approve','not-now','merge')),\n  phase       TEXT NOT NULL CHECK (phase IN ('offer','yes','cancel')),\n  task_id     TEXT NOT NULL,\n  run         INTEGER,\n  digest      TEXT NOT NULL,\n  created_at  TEXT NOT NULL,\n  expires_at  TEXT NOT NULL,\n  consumed_at TEXT\n);\nCREATE INDEX IF NOT EXISTS chat_decide_action_message ON chat_decide_action (channel, chat, message);\nCREATE TABLE IF NOT EXISTS chat_decide_prompt (\n  id          INTEGER PRIMARY KEY AUTOINCREMENT,\n  channel     TEXT NOT NULL,\n  binding     INTEGER NOT NULL,\n  chat        TEXT NOT NULL,\n  task_id     TEXT NOT NULL,\n  run         INTEGER NOT NULL,\n  digest      TEXT NOT NULL,\n  message     TEXT,\n  created_at  TEXT NOT NULL,\n  expires_at  TEXT NOT NULL,\n  consumed_at TEXT\n);\nCREATE INDEX IF NOT EXISTS chat_decide_prompt_open ON chat_decide_prompt (channel, binding, consumed_at);\n";
 export type LeadAsk = {
@@ -152,7 +161,7 @@ export type SealedLedgerEntry = LedgerEntry & {
         hash: string;
     } | null;
 };
-export declare const SCHEMA_VERSION = 119;
+export declare const SCHEMA_VERSION = 121;
 /** v118: the tables merged into `credential`, in the order they move (a person's API tokens keep their ids first). */
 export declare const V118_MERGED_TABLES: Readonly<Record<string, CredentialKind>>;
 /**
@@ -209,7 +218,9 @@ export declare const V115_DROPPED_TABLES: readonly string[];
  * coordinator_credential and lead_credential moves into credential under its kind in one transaction that counts them
  * before the old tables drop, and the references that named them name credential in place, their rows untouched. v119 only adds four columns
  * (planning_generation on task_ref, run and plan_revision, defaulting to 0, and decision.superseded_reason, null);
- * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns).
+ * the rehearsal checks every saved row reads the declared default (HISTORY_RULES' added columns). v120 only adds
+ * three nullable task_steer columns (the running build's steering folder), checked the same way. v121 only adds
+ * new tables and the columns in V121_ADDED_COLUMNS (null, or no sends), checked the same way.
  */
 export declare const UPDATE_SAFE_MIGRATIONS: readonly number[];
 /** v119: the columns it adds, by table, with the value every row saved before it reads (toolroll-update's HISTORY_RULES). */
@@ -217,6 +228,28 @@ export declare const V119_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record
     definition: string;
     saved: string;
 }>>>>;
+/** v120: the columns it adds, by table, with the value every row saved before it reads. */
+export declare const V120_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/**
+ * Live steering's added columns (v121), with the value every row saved before them reads. A note carries the identity
+ * its stdin copy is sent under (live_uuid, minted when it is filed), how many times it was sent to the running build
+ * and when last, and when it was given up on as not picked up.
+ * A run says when its stdin session opened and closed: only then can a note reach it in seconds, or a Pause stop a turn;
+ * and how long a paused session may wait before it ends (the idle limit; none under a wall-clock limit).
+ */
+export declare const LIVE_STEER_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
+/** v121: the columns it adds, by table, with the value every row saved before it reads: live steering's, and a run's
+ * attempt key (the Agents board; runs admitted before it read none). Its new tables carry no saved rows. */
+export declare const V121_ADDED_COLUMNS: Readonly<Record<string, Readonly<Record<string, {
+    definition: string;
+    saved: string;
+}>>>>;
 /** Whether a database settled at `version` reaches this build's schema through update-safe migrations alone. */
 export declare function updateSafeSchema(version: number | null): boolean;
 export type OAuthClientRow = {
@@ -1137,6 +1170,9 @@ export type RunPhase = (typeof RUN_PHASES)[number];
  * One operator steering note (arc 1, v22). Attached ≠ delivered: attachment
  * says which build the note rode toward; delivery settles only on the
  * stream's own receipt. Superseded = the task ended with it still pending.
+ * v120: a note filed while a build runs is mailed into that build's steering
+ * folder (mailed), and is read only when the agent moves it to handled/
+ * (acked, which also settles it delivered to that build).
  */
 export type SteerNote = {
     /** v24 (ruling 11): "verified" = credentialed authorship; anything else is history, never brief-bound. */
@@ -1151,6 +1187,57 @@ export type SteerNote = {
     attachedAt: string | null;
     deliveredAt: string | null;
     supersededAt: string | null;
+    mailedRun: number | null;
+    mailedAt: string | null;
+    ackedAt: string | null;
+    /** Live steering: the identity its stdin copy is sent under, how often and when last it was sent to the running
+     * build, and when it was given up on as not picked up. Null/0 on notes filed before live steering. */
+    liveUuid: string | null;
+    liveSends: number;
+    liveSentAt: string | null;
+    liveMissedAt: string | null;
+};
+/** Who asked for a pause, and through which door. */
+export type PauseVia = "cli" | "web" | "chat";
+/** One Pause (or Pause and steer) asked of an exact running build (LIVE_STEER_SCHEMA). */
+export type RunPause = {
+    id: number;
+    run: number;
+    taskRef: number;
+    requestId: string;
+    requestedBy: string;
+    requestedVia: PauseVia;
+    requestedAt: string;
+    note: number | null;
+    sentAt: string | null;
+    pausedAt: string | null;
+    resumedAt: string | null;
+    endedAt: string | null;
+};
+/** Where a run's latest pause stands, and how long a paused build may wait before it ends (null: no idle limit). */
+export type LivePauseState = {
+    state: "pausing" | "paused";
+    pausedAt: string | null;
+    limitMs: number | null;
+};
+export type ResumeRequestResult = {
+    ok: true;
+    resume: number;
+    duplicate: boolean;
+} | {
+    ok: false;
+    reason: "invalid-request" | "duplicate" | "unknown-task" | "task-finished" | "stale" | "not-paused";
+    detail: string;
+};
+export type PauseRequestResult = {
+    ok: true;
+    pause: number;
+    note: number | null;
+    duplicate: boolean;
+} | {
+    ok: false;
+    reason: "invalid-request" | "duplicate" | "unknown-task" | "task-finished" | "stale" | "invalid-note";
+    detail: string;
 };
 /** One phone enrollment for web push (arc 3, v23). A row per ACTIVATION —
  * retirement is history, never deletion. */
@@ -4654,6 +4741,9 @@ export declare class Store {
         reason: "unknown-task" | "task-finished" | "invalid-note";
         problem?: string;
     };
+    /** One verified note, with the identity a running build's stdin copy is sent under: filing it is also what queues
+     * its live delivery, in the same transaction (the builder's dispatcher sends whatever is filed and unsent). */
+    private insertSteerNote;
     /** Every steering note of a task, filing order, delivery state included. */
     listSteerNotes(taskRef: number): SteerNote[];
     /** Undelivered, unsuperseded notes. */
@@ -4676,6 +4766,113 @@ export declare class Store {
      * first receipt wins, and a replay changes nothing.
      */
     settleSteerDelivered(runId: number, now: Date): number;
+    /**
+     * The task's build whose agent is running right now and reads its steering
+     * folder (v120): the current live lease's open builder run, in its
+     * agent-running phase, whose steering folder is open. Null otherwise — a
+     * note then waits for the next attempt. Display state, never evidence.
+     */
+    steeringLiveBuild(taskRef: number, now: Date): number | null;
+    /** This run made its steering folder (v120): its agent can read a note filed now. */
+    markSteerFolderOpened(runId: number, now: Date): void;
+    /** This run's steering folder is gone (v120): a note filed now reaches the next attempt. */
+    markSteerFolderClosed(runId: number, now: Date): void;
+    /**
+     * The notes a RUNNING build may still read (v120): verified, pending, not
+     * already quoted in this run's brief, and not already in its folder. The
+     * pulse mails exactly these, in filing order.
+     */
+    mailableSteerNotes(taskRef: number, runId: number): SteerNote[];
+    /** The pulse wrote this note into the run's steering folder. Mailing is not
+     * reading: delivery settles only on the agent's own acknowledgement. */
+    markSteerMailed(noteId: number, runId: number, now: Date): boolean;
+    /**
+     * The agent moved this note to handled/ (v120): it was read, by THIS run.
+     * Acknowledgement is the only road from mailed to delivered — a hook firing
+     * or a file written proves nothing. First acknowledgement wins; a note the
+     * task already ended, or mailed to another run since, is left alone.
+     */
+    ackSteerNote(noteId: number, runId: number, now: Date): boolean;
+    /**
+     * The task's build that takes live input right now (live steering): the steering build (steeringLiveBuild) whose
+     * Claude session reads stdin. Only this run can take a note in seconds, or a Pause. Null otherwise.
+     */
+    liveInputRun(taskRef: number, now: Date): number | null;
+    /** This run's Claude session reads stdin now (live steering), and how long a paused session may wait (null: no idle limit). */
+    markLiveInputOpened(runId: number, now: Date, pauseLimitMs?: number | null): void;
+    /** This run's stdin is closed (live steering): notes reach it only through its folder, and a Pause is over. */
+    markLiveInputClosed(runId: number, now: Date): void;
+    /** One steering note by id. */
+    steerNote(noteId: number): SteerNote | null;
+    /**
+     * The note's copy was written to this run's stdin (live steering): one more send, stamped. Sending is not reading —
+     * only the agent moving its file to handled/ is (ackSteerNote). Refused once the note is read, ended, given up on,
+     * or mailed to another run.
+     */
+    recordLiveSend(noteId: number, runId: number, now: Date): boolean;
+    /** The running build was sent this note every time it is owed and never moved it to handled/: Not picked up. A later
+     * acknowledgement still reads it (ackSteerNote ignores this), and an attempt that ends returns it to the next brief. */
+    markLiveMissed(noteId: number, runId: number, now: Date): boolean;
+    /**
+     * Pause a running Claude build, or Pause and steer it (live steering): asked of the exact run the person saw, under
+     * their request id. In one transaction the note (when there is one) is filed — Ruling 11's verified author — and the
+     * pause is queued ahead of it, so the dispatcher writes the interrupt before the note. A repeated request id is the
+     * same request; a run that no longer takes live input is stale. Pause never stops, holds or reclaims the attempt.
+     */
+    requestPause(request: {
+        taskId: string;
+        runId: number;
+        by: VerifiedAuthor;
+        via: PauseVia;
+        requestId: string;
+        note?: string;
+    }, now: Date): PauseRequestResult;
+    /** The pauses this run has not yet written to stdin, in request order (the dispatcher writes these first). */
+    unsentPauses(runId: number): RunPause[];
+    /** The interrupt for this pause was written to the run's stdin. */
+    markPauseSent(pauseId: number, now: Date): void;
+    /** The run's current turn stopped: every pause sent and still waiting reads paused. */
+    markRunPaused(runId: number, now: Date): void;
+    /** A note continued the paused session: its pauses are over. */
+    markRunResumed(runId: number, now: Date): void;
+    /** The run could not take this pause (its stdin closed first). */
+    endPause(pauseId: number, now: Date): void;
+    /** Where this run's latest pause stands: asked and not yet stopped (pausing), stopped (paused), or none. */
+    pauseStateOf(runId: number): "pausing" | "paused" | null;
+    /** This run's latest pause, when it paused, and how long a paused build may wait before it ends; null with none. */
+    livePauseOf(runId: number): LivePauseState | null;
+    /**
+     * Resume a paused Claude build (live steering): asked of the exact run the person saw, under their request id, and
+     * only while that run is paused. The dispatcher sends a short continue frame — never a note, so nothing is filed.
+     * A repeated request id is the same request; a run that no longer takes live input is stale.
+     */
+    requestResume(request: {
+        taskId: string;
+        runId: number;
+        by: VerifiedAuthor;
+        via: PauseVia;
+        requestId: string;
+    }, now: Date): ResumeRequestResult;
+    /** The resumes this run has not yet sent, in request order. */
+    unsentResumes(runId: number): {
+        id: number;
+        requestId: string;
+    }[];
+    /** The continue frame was written: the resume is sent, and the run's pauses are over. */
+    markResumeSent(resumeId: number, runId: number, now: Date): void;
+    /** The run was no longer paused (a note continued it first) or stopped taking input: nothing to send. */
+    endResume(resumeId: number, now: Date): void;
+    /** Every resume of a task, newest first (history and tests). */
+    resumesForTask(taskRef: number): {
+        id: number;
+        run: number;
+        requestId: string;
+        requestedVia: PauseVia;
+        sentAt: string | null;
+        endedAt: string | null;
+    }[];
+    /** Every pause of a task, newest first (history and tests). */
+    pausesForTask(taskRef: number): RunPause[];
     /** A finished task's pending notes settle superseded — shown, typed, done. */
     supersedeSteerNotes(taskRef: number, now: Date): number;
     /** The answers a run was given, exactly as it was given them. */
@@ -6496,6 +6693,9 @@ export declare class Store {
      * mark. The outbox's delivered_at is deliberately not consulted.
      */
     seedPushPairs(now: Date): number;
+    /** A pending pair about a run its person is watching waits for the watch to lapse; one about a finished run they have
+     * since seen retires unsent (agent-board.ts watchedPing). False when the pair must not be sent now. */
+    private settleWatchedPush;
     /**
      * Claim due pairs: pending (respecting next_attempt_at) or claimed-but-
      * expired (reclaim bumps the generation — the old owner loses every