@bridge4dev/runner 0.26.0 → 0.29.0

package/dist/checkpoints.d.ts

@@ -0,0 +1,175 @@
+/** Retention: nothing older than this survives, whatever the ordinal. */
+export declare const CHECKPOINT_MAX_AGE_MS: number;
+/** Retention: the newest N per session. */
+export declare const CHECKPOINT_MAX_PER_SESSION = 200;
+/**
+ * How long the points of a session nobody mentions are kept anyway.
+ *
+ * The list of live sessions arrives capped, so absence from it is weak
+ * evidence. A day of silence is strong evidence — and until then the cost of
+ * being wrong is disk, while the cost of being wrong the other way is the only
+ * copy of somebody's uncommitted work.
+ */
+export declare const ORPHAN_GRACE_MS: number;
+export type CheckpointKind = 'TURN' | 'SAFETY' | 'MANUAL';
+export interface CheckpointRecord {
+    ordinal: number;
+    commit: string;
+    kind: CheckpointKind;
+    /** HEAD of the worktree when the checkpoint was taken. */
+    headSha: string;
+    /** Paths that were staged in the project's index at that moment. */
+    stagedPaths: string[];
+    createdAt: number;
+    fileCount: number;
+    byteCount: number;
+    /**
+     * The agent's own name for the conversation at this instant (ticket #126) —
+     * a Claude message uuid or a Codex turn id.
+     *
+     * Kept HERE and never sent to the API: it is an identifier internal to a CLI
+     * on this machine, it is worth nothing to anybody else, and a database is a
+     * poor place for a value whose meaning only one process understands. The
+     * rewind command carries an ordinal; the runner looks the anchor up itself.
+     */
+    agentAnchor?: string;
+    /**
+     * The provider conversation the anchor belongs to.
+     *
+     * A conversation rewind FORKS, and a fork remaps every message id — so an
+     * anchor recorded against the old thread names nothing in the new one.
+     * Comparing this against the session's current provider id is what stops the
+     * button from offering a rewind that would silently do nothing.
+     */
+    agentSession?: string;
+    /** Feed seq of the user message this point sits in front of. */
+    messageSeq?: number;
+}
+export interface CreateCheckpointInput {
+    worktreePath: string;
+    sessionId: string;
+    kind: CheckpointKind;
+    /** Feed seq of the user message this point sits in front of (TURN only). */
+    messageSeq?: number;
+    agentAnchor?: string;
+    agentSession?: string;
+}
+export type CreateCheckpointResult = {
+    created: true;
+    record: CheckpointRecord;
+    messageSeq?: number;
+    skippedFiles: string[];
+} | {
+    created: false;
+    reason: 'not-a-repo' | 'too-large' | 'failed';
+    detail?: string;
+};
+export interface RewindPreview {
+    /** Files whose content goes back to the checkpoint. */
+    restore: string[];
+    /** Files that exist now and did not then — a rewind DELETES these. */
+    delete: string[];
+    /** Files that existed then and are gone now — a rewind recreates them. */
+    recreate: string[];
+    headSha: string;
+    checkpointHeadSha: string;
+    /**
+     * The git tree of the worktree AS THIS PREVIEW SAW IT (QA-120 B1).
+     *
+     * Echoed back with the rewind and re-derived on this side: any byte that
+     * moves in any covered file changes this oid, so it is a signature over the
+     * whole state the person was shown, not just over the list of deletions.
+     *
+     * The delete echo alone was half a guarantee. `read-tree --reset -u` writes
+     * the RESTORE list too, recomputed at apply time — so a file saved from an
+     * editor while the dialog sat open was overwritten from the checkpoint
+     * without ever appearing on any list. The dialog exists to make «nothing
+     * changes that was not named» true, and it was true of one half of the tree.
+     */
+    treeOid: string;
+    /** Set when a rewind must be refused; the UI shows this instead of a button. */
+    blockedReason?: 'head-moved' | 'merge-in-progress' | 'checkpoint-lost' | 'too-many-changes';
+    /** Commits made since the checkpoint, when `head-moved` is why we refuse. */
+    commitsSince?: Array<{
+        sha: string;
+        subject: string;
+    }>;
+    /** The change is larger than the dialog can honestly list — see `blockedReason`. */
+    truncated?: boolean;
+    totalChanges?: number;
+}
+/**
+ * Take a restore point for this worktree.
+ *
+ * Never throws for an ordinary failure: a checkpoint that could not be taken
+ * must not stop the message it was taken for from reaching the agent.
+ */
+export declare function createCheckpoint(input: CreateCheckpointInput): Promise<CreateCheckpointResult>;
+export declare function listCheckpoints(worktreePath: string, sessionId: string): Promise<CheckpointRecord[]>;
+/** What a rewind to this checkpoint would do, without doing any of it. */
+export declare function previewRewind(input: {
+    worktreePath: string;
+    sessionId: string;
+    ordinal: number;
+}): Promise<RewindPreview>;
+export interface ApplyRewindResult {
+    restored: number;
+    deleted: number;
+    recreated: number;
+    /** The point taken immediately before this rewind, so it can be undone. */
+    safety: CheckpointRecord;
+    /**
+     * What kind of point this rewind went TO.
+     *
+     * `SAFETY` means the rewind was itself an undo — and an undo of an undo is a
+     * redo, not an undo. The interface reads this to stop offering the same
+     * button forever under a name that stops being true after the first press.
+     */
+    rewoundToKind: CheckpointKind;
+}
+/**
+ * Put the working tree back to a checkpoint.
+ *
+ * The SAFETY point is taken FIRST and its ref is on disk before a single byte
+ * of the worktree changes — kill the process between the two steps and the way
+ * back still exists. `read-tree --reset -u` restores content but does NOT
+ * delete files created after the checkpoint (verified on live git), so the
+ * deletions are done explicitly from a list the caller echoed back. There is no
+ * `git clean` anywhere in this file, on purpose: it deletes by rule rather than
+ * by list, and a rule is exactly what nobody confirmed.
+ */
+export declare function applyRewind(input: {
+    worktreePath: string;
+    sessionId: string;
+    ordinal: number;
+    /** Echo of `preview.delete` — a mismatch means the tree moved under the user. */
+    confirmDeletes: string[];
+    /**
+     * Echo of `preview.treeOid` — the whole state the user was shown (QA-120 B1).
+     *
+     * Optional only for the wire: a dashboard newer than the runner will send it
+     * and an older one will not, and refusing the older one would break a client
+     * that is doing nothing wrong. Present ⇒ checked.
+     */
+    expectedTreeOid?: string;
+}): Promise<ApplyRewindResult>;
+export declare function rewindBlockMessage(reason: NonNullable<RewindPreview['blockedReason']>): string;
+/** Drop every restore point of one session (session deleted or purged). */
+export declare function dropCheckpoints(worktreePath: string, sessionId: string): Promise<void>;
+/**
+ * Garbage collection.
+ *
+ * Two jobs, and the second one is the reason this exists: deleting a session
+ * while its dev server is switched off leaves refs — a full copy of a working
+ * tree — with no row anywhere to point at them. The reconciliation on `hello`
+ * is what eventually removes those, so this takes a list of the sessions that
+ * still exist rather than a list of the ones that do not.
+ */
+export declare function pruneCheckpoints(input: {
+    liveSessionIds: ReadonlySet<string>;
+    now?: number;
+}): Promise<{
+    droppedSessions: string[];
+    droppedRefs: number;
+}>;
+//# sourceMappingURL=checkpoints.d.ts.map