@rryando/arcs 5.1.0 → 5.2.1

package/dist/web-server/routes/workspace.js

@@ -4,8 +4,8 @@
  * Two GETs and nothing else: `tree` lists a directory under the project's
  * registered workspace roots, `file` returns one file's text plus the head
  * revision it was read at, so the browser can build the `file` variant of
- * `sessionReferenceSchema` (path + line range + headRev) and hand it to a
- * session. There is deliberately NO write route here: an edit is something the
+ * the ask reference schema (path + line range + headRev) and hand it to a
+ * turn. There is deliberately NO write route here: an edit is something the
  * agent does in the workspace, never something this plane does on its behalf.
  *
  * Every path the caller supplies goes through `resolveInsideWorkspace` — the
@@ -69,8 +69,8 @@ function toPosix(path) {
 /**
  * The project's workspace roots, resolved and deduplicated.
  *
- * Read from `meta.workspacePaths` exactly as `primaryWorkspacePath` in
- * routes/sessions.ts reads it, including its rule: an unset workspace is an
+ * Read from `meta.workspacePaths` exactly as the ask route's
+ * `primaryWorkspacePath` reads it, including its rule: an unset workspace is an
  * ERROR, never a default. `resolveProject().workspacePath` returns `""` rather
  * than `process.cwd()` for the same reason — an empty root here would otherwise
  * quietly mean "contain everything", i.e. the whole filesystem.

package/dist/web-server/run-diff.d.ts

@@ -0,0 +1,188 @@
+/**
+ * Workspace diff snapshot + approve/revert review surface for Ask-AI runs.
+ *
+ * The allow-all gate: a run may change the workspace, the panel shows the
+ * diff, and the user approves (keeps) or rejects (reverts). Three layers:
+ *
+ *  - SNAPSHOT — captured in the ask route's spawn path, before the claim is
+ *    taken and before the child can write. This is the baseline every later
+ *    diff and revert computes against.
+ *  - DIFF — computed in the settle write-back, comparing the workspace to the
+ *    snapshot, and persisted as `changes.json` beside the run's event log.
+ *  - REVERT — restores the workspace to the snapshot baseline, scoped to this
+ *    run's own changes list, and marks the run record so a second revert is
+ *    refused.
+ *
+ * Two workspace modes:
+ *
+ *  - GIT — the snapshot records `{ mode, head, cwd, untracked[] }` and
+ *    NOTHING else. Diffs and reverts compute against git at review time
+ *    (`git diff HEAD`, `git restore`), because git already holds the exact
+ *    baseline — copying file contents would be redundant with the object DB.
+ *    `untracked` lists the paths that were already untracked at snapshot time:
+ *    the run is never credited with (and revert never deletes) a file that
+ *    merely remained untracked across the run. State the degradation plainly:
+ *    an untracked file that EXISTED before the run and was then edited by it
+ *    is invisible to this surface — git has no baseline for it, by design.
+ *  - TREE (non-git) — the snapshot walks the tree and records a hash+size
+ *    manifest. A pure manifest can answer modified/added/deleted but cannot
+ *    render a modified file's old bytes, so the snapshot ALSO stores each
+ *    file's bytes up to a total blob cap (RUN_SNAPSHOT_BLOB_MAX_BYTES). A
+ *    file whose baseline bytes were refused by the cap reports `diff: null`
+ *    with `capped: true` and cannot be reverted.
+ *
+ * Every failure here DEGRADES the review surface rather than failing the turn
+ * or the settle: an unreadable workspace, a wedged git, a refused blob — all
+ * record on the snapshot/change file and the client sees an empty changes
+ * list. The turn itself already happened.
+ *
+ * File keying follows run-event-log.ts exactly: `sessions/{slug}.run-{seg}`
+ * plus a `.snapshot.json` / `.changes.json` suffix, pruned together by
+ * `pruneRunEventLogs` under the same retention.
+ */
+/** Ceiling on files a non-git snapshot walk records. Past it the walk stops
+ *  (sorted order) and the rest of the tree is NOT in the manifest — a
+ *  documented truncation: files that sort after the cap compare as phantom
+ *  adds/deletes. */
+export declare const RUN_SNAPSHOT_MAX_FILES = 10000;
+/** Ceiling on levels below the workspace root a walk descends. */
+export declare const RUN_SNAPSHOT_MAX_DEPTH = 12;
+/** Ceiling on total baseline bytes a snapshot may keep for later diffs. A
+ *  modified/deleted file whose bytes were refused CANNOT render a diff or be
+ *  reverted — it reports `capped: true` instead. */
+export declare const RUN_SNAPSHOT_BLOB_MAX_BYTES: number;
+/** Ceiling on one change's diff text — the first N lines AND the first N
+ *  bytes, whichever lands first. Line counts are always parsed from the FULL
+ *  diff before the cap is applied. */
+export declare const RUN_DIFF_MAX_LINES = 300;
+export declare const RUN_DIFF_MAX_BYTES: number;
+/** Ceiling on one spawnSync git call. A wedged git (stalled mount, held
+ *  index.lock) must degrade the surface, never hang the request. */
+export declare const RUN_GIT_TIMEOUT_MS = 5000;
+export interface WorkspaceSnapshotFile {
+    /** Bytes at snapshot time. */
+    size: number;
+    /** Hex sha256 of the file's bytes at snapshot time. */
+    sha256: string;
+}
+/** Git-mode snapshot: diffs and reverts compute AGAINST GIT at review time —
+ *  no file bytes are copied, which is the point: an exact diff needs git's
+ *  whole object database, not our copy of HEAD. */
+export interface GitWorkspaceSnapshot {
+    mode: "git";
+    /** HEAD sha at snapshot time — what the run saw as "current". */
+    head: string;
+    /** Realpath'd workspace root the snapshot covers — what the run ran in. */
+    cwd: string;
+    /**
+     * Untracked paths at snapshot time. The settle-time diff never credits the
+     * run with a file that was ALREADY untracked (git has no baseline for it),
+     * and revert never deletes one. This list IS the git mode's "snapshot path
+     * list" that revert scopes itself to.
+     */
+    untracked: string[];
+    /** Non-fatal capture failure — the review surface is skipped for the run
+     *  (GET changes answers an empty list) rather than failing the turn. */
+    error?: string;
+}
+/** Tree-mode snapshot (non-git): a manifest walk plus baseline bytes. */
+export interface TreeWorkspaceSnapshot {
+    mode: "tree";
+    cwd: string;
+    /** Relative posix path → size + sha256, for every walked file. */
+    files: Record<string, WorkspaceSnapshotFile>;
+    /**
+     * Baseline bytes (base64) up to RUN_SNAPSHOT_BLOB_MAX_BYTES total, in
+     * sorted walk order — the only way a non-git modified/deleted file can
+     * render a diff or be reverted.
+     */
+    blobs: Record<string, string>;
+    /** The walk's caps, so the settle-time diff re-walks identically. */
+    walk: {
+        maxFiles: number;
+        maxDepth: number;
+    };
+    /** True when the walk hit the file cap — later files were not walked, so
+     *  they compare as phantom adds/removes. Documented degradation. */
+    truncated?: boolean;
+    /** True when at least one file was refused baseline bytes past the blob cap. */
+    blobCapped?: boolean;
+    /** Non-fatal capture failure — same degradation as the git-mode `error`. */
+    error?: string;
+}
+export type WorkspaceSnapshot = GitWorkspaceSnapshot | TreeWorkspaceSnapshot;
+export type WorkspaceChangeStatus = "modified" | "added" | "deleted";
+export interface WorkspaceChange {
+    /** Posix path relative to the workspace root. */
+    path: string;
+    status: WorkspaceChangeStatus;
+    /** `+` lines in the FULL diff (before capping). */
+    linesAdded: number;
+    /** `-` lines in the FULL diff (before capping). */
+    linesRemoved: number;
+    /** Capped diff text (RUN_DIFF_MAX_LINES × RUN_DIFF_MAX_BYTES), or `null`
+     *  when the bytes to render it were never captured (blob cap) or a git
+     *  call failed. */
+    diff: string | null;
+    /** True when `diff` is null because the file's baseline bytes were beyond
+     *  the snapshot's blob cap — the non-git degradation flag. Revert cannot
+     *  rebuild such a file either. */
+    capped?: boolean;
+}
+/** The persisted `changes.json` manifest beside a run's event log. */
+export interface RunChangesFile {
+    runId: string;
+    /** Epoch ms the settle-time diff was computed. */
+    computedAt: number;
+    changes: WorkspaceChange[];
+    /** Non-fatal diff failure — the client sees changes: []. */
+    error?: string;
+}
+export interface SnapshotOptions {
+    maxFiles?: number;
+    maxDepth?: number;
+    blobMaxBytes?: number;
+}
+/**
+ * Total by contract: NEVER throws. Every failure mode records `error` on the
+ * snapshot, and an errored snapshot skips the review surface for its run
+ * (changes: [], revert no-ops) — a baseline that cannot be computed must not
+ * fail the accepted turn.
+ */
+export declare function captureWorkspaceSnapshot(root: string, options?: SnapshotOptions): Promise<WorkspaceSnapshot>;
+/** The run's baseline snapshot path — a sibling of its event log. */
+export declare function runSnapshotPath(projectDir: string, sessionId: string, runId: string): string;
+/** The run's settle-time changes manifest path — a sibling of its event log. */
+export declare function runChangesPath(projectDir: string, sessionId: string, runId: string): string;
+/** Persists the baseline snapshot. Callers wrap this — a failed persist is a
+ *  degraded review surface, never a failed turn. */
+export declare function persistRunSnapshot(projectDir: string, sessionId: string, runId: string, snapshot: WorkspaceSnapshot): Promise<void>;
+export declare function readRunSnapshot(projectDir: string, sessionId: string, runId: string): Promise<WorkspaceSnapshot | undefined>;
+export declare function readRunChanges(projectDir: string, sessionId: string, runId: string): Promise<RunChangesFile | undefined>;
+/**
+ * What the workspace changed since the snapshot.
+ *
+ * Total by contract (never throws): the git-status failure path returns an
+ * empty list — a workspace whose git broke mid-run degrades to "no changes"
+ * rather than failing the settle. Every path it returns is root-relative, so
+ * downstream reads, diffs and reverts all go through `resolveInside`.
+ */
+export declare function computeWorkspaceChanges(snapshot: WorkspaceSnapshot): Promise<WorkspaceChange[]>;
+/**
+ * Computes the run's workspace diff and persists it as changes.json beside
+ * the run's event log. Never throws: a missing/errored snapshot leaves the
+ * changes file absent (GET answers `changes: []`), and a diff failure writes
+ * `{ changes: [], error }` so the run still reads as "no changes".
+ */
+export declare function writeSettledRunChanges(projectDir: string, sessionId: string, runId: string): Promise<void>;
+/**
+ * Restores the workspace to the snapshot baseline for THIS run's changes.
+ *
+ * Scoped strictly: every path goes through `resolveInside` against the
+ * snapshot root, and the paths acted on are exactly those in `changes` (never
+ * a bare `git clean`, never a walk). Returns the paths actually restored;
+ * un-restorable entries (a modified/deleted file whose baseline bytes were
+ * beyond the blob cap) are skipped and NOT reported as restored.
+ */
+export declare function revertWorkspaceChanges(snapshot: WorkspaceSnapshot, changes: WorkspaceChange[]): Promise<string[]>;
+//# sourceMappingURL=run-diff.d.ts.map

package/dist/web-server/run-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-diff.d.ts","sourceRoot":"","sources":["../../src/web-server/run-diff.ts"],"names":[],"mappings":"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"}