@managoat/fountain-sdk 6.4.0 → 6.5.0

package/CHANGELOG.md

@@ -11,6 +11,15 @@ server releases.
 
 ---
 
+## [6.5.0] - 2026-10-02
+
+### Added
+
+- The generated types carry `snapshot_at` on `SandboxListing`, `SandboxFile`,
+  `SandboxDiff` and `SandboxStatus` (#2552, ADR 0063). It is set when the
+  sandbox is parked and the read was answered from the snapshot its park
+  took, and absent on a live read.
+
 ## [6.4.0] - 2026-10-02
 
 ### Added

package/dist/generated/openapi.d.ts

@@ -1987,7 +1987,7 @@ export interface paths {
         };
         /**
          * git diff on a sandbox
-         * @description `git diff` of the repository containing `path` (default: the agent's working directory), redacted like a file read. `staged=true` compares the index (`--cached`); `ref` compares against a commit, branch or tag (`422 invalid_ref` for a malformed one, `404 ref_not_found` for an unknown one). A directory outside any repository is `422 not_a_repository`. Full scope.
+         * @description `git diff` of the repository containing `path` (default: the agent's working directory), redacted like a file read. `staged=true` compares the index (`--cached`); `ref` compares against a commit, branch or tag (`422 invalid_ref` for a malformed one, `404 ref_not_found` for an unknown one). A directory outside any repository is `422 not_a_repository`. Full scope. A parked (`suspended`) sandbox is not woken: it answers from the snapshot its park took, with `snapshot_at` saying when, wherever that snapshot holds the answer — the git repositories under the working directory, their files up to 256 KiB, their listings, and the default diff and status (ADR 0063). Anything else on a parked sandbox, or a parked sandbox with no snapshot, is `409 sandbox_not_ready`.
          */
         get: operations["FountainWeb.SandboxFilesController.diff"];
         put?: never;
@@ -2007,7 +2007,7 @@ export interface paths {
         };
         /**
          * Read a file on a sandbox
-         * @description The bytes of one file, redacted: every value of the sandbox's environment and vault is replaced with `[REDACTED]`, as in the transcript. `content` is the text when it is valid UTF-8 (`encoding: utf-8`) and base64 otherwise (`encoding: base64`). `size` is the whole file; `truncated` says whether `content` is short of it, which happens when the file is longer than `max_bytes` and also when redaction grows what was read past that cap. Full scope.
+         * @description The bytes of one file, redacted: every value of the sandbox's environment and vault is replaced with `[REDACTED]`, as in the transcript. `content` is the text when it is valid UTF-8 (`encoding: utf-8`) and base64 otherwise (`encoding: base64`). `size` is the whole file; `truncated` says whether `content` is short of it, which happens when the file is longer than `max_bytes` and also when redaction grows what was read past that cap. Full scope. A parked (`suspended`) sandbox is not woken: it answers from the snapshot its park took, with `snapshot_at` saying when, wherever that snapshot holds the answer — the git repositories under the working directory, their files up to 256 KiB, their listings, and the default diff and status (ADR 0063). Anything else on a parked sandbox, or a parked sandbox with no snapshot, is `409 sandbox_not_ready`.
          */
         get: operations["FountainWeb.SandboxFilesController.show"];
         put?: never;
@@ -2027,7 +2027,7 @@ export interface paths {
         };
         /**
          * List a directory on a sandbox
-         * @description The entries of one directory, directories first then by name. Without `path`, the agent's working directory. Only a `ready` sandbox answers (`409 sandbox_not_ready`): a parked one is not woken for a read. A sandbox being parked or destroyed is `503 sandbox_unavailable`; retry after the `Retry-After`. Full scope.
+         * @description The entries of one directory, directories first then by name. Without `path`, the agent's working directory. A sandbox being parked or destroyed is `503 sandbox_unavailable`; retry after the `Retry-After`. Full scope. A parked (`suspended`) sandbox is not woken: it answers from the snapshot its park took, with `snapshot_at` saying when, wherever that snapshot holds the answer — the git repositories under the working directory, their files up to 256 KiB, their listings, and the default diff and status (ADR 0063). Anything else on a parked sandbox, or a parked sandbox with no snapshot, is `409 sandbox_not_ready`.
          */
         get: operations["FountainWeb.SandboxFilesController.index"];
         put?: never;
@@ -2047,7 +2047,7 @@ export interface paths {
         };
         /**
          * git status on a sandbox
-         * @description `git status` of the repository containing `path` (default: the agent's working directory), one entry per changed path. This is the view that shows a file the agent created and never staged: `/diff` compares tracked content, so an untracked file is invisible to it whatever flags it is given. Entries cover the whole repository whatever `path` names inside it, and each entry's `path` is relative to `repo_root`. `index` and `worktree` are git's two porcelain columns read separately, so a file staged and then edited again reports a state in both; an untracked file reads `untracked` in both. `renamed_from` is set only where that side is a rename or a copy. `branch` is null on a detached HEAD. A directory outside any repository is `422 not_a_repository`. Full scope.
+         * @description `git status` of the repository containing `path` (default: the agent's working directory), one entry per changed path. This is the view that shows a file the agent created and never staged: `/diff` compares tracked content, so an untracked file is invisible to it whatever flags it is given. Entries cover the whole repository whatever `path` names inside it, and each entry's `path` is relative to `repo_root`. `index` and `worktree` are git's two porcelain columns read separately, so a file staged and then edited again reports a state in both; an untracked file reads `untracked` in both. `renamed_from` is set only where that side is a rename or a copy. `branch` is null on a detached HEAD. A directory outside any repository is `422 not_a_repository`. Full scope. A parked (`suspended`) sandbox is not woken: it answers from the snapshot its park took, with `snapshot_at` saying when, wherever that snapshot holds the answer — the git repositories under the working directory, their files up to 256 KiB, their listings, and the default diff and status (ADR 0063). Anything else on a parked sandbox, or a parked sandbox with no snapshot, is `409 sandbox_not_ready`.
          */
         get: operations["FountainWeb.SandboxFilesController.git_status"];
         put?: never;
@@ -4808,6 +4808,11 @@ export interface components {
             ref?: string | null;
             /** @description The repository's top-level directory. */
             repo_root: string;
+            /**
+             * Format: date-time
+             * @description Present when the sandbox is parked and this answer comes from the snapshot its park took (ADR 0063): the disk as of this instant, not now. Absent on a live read.
+             */
+            snapshot_at?: string | null;
             /** @description True when the index was diffed (`--cached`). */
             staged: boolean;
             /** @description True when `diff` is not the whole diff: either it is longer than `max_bytes`, or redaction grew what was read past it. False means `diff` is everything. */
@@ -4843,6 +4848,11 @@ export interface components {
             path: string;
             /** @description The whole file, in bytes. */
             size: number;
+            /**
+             * Format: date-time
+             * @description Present when the sandbox is parked and this answer comes from the snapshot its park took (ADR 0063): the disk as of this instant, not now. Absent on a live read.
+             */
+            snapshot_at?: string | null;
             /** @description True when `content` is not the whole file: either the file is longer than `max_bytes`, or redaction grew what was read past it. False means `content` is everything. */
             truncated: boolean;
         };
@@ -4862,6 +4872,11 @@ export interface components {
             entries: components["schemas"]["SandboxEntry"][];
             /** @description The directory listed, absolute. */
             path: string;
+            /**
+             * Format: date-time
+             * @description Present when the sandbox is parked and this answer comes from the snapshot its park took (ADR 0063): the disk as of this instant, not now. Absent on a live read.
+             */
+            snapshot_at?: string | null;
             /** @description True when the directory holds more entries than were returned. */
             truncated: boolean;
         };
@@ -4918,6 +4933,11 @@ export interface components {
             path: string;
             /** @description The repository's top-level directory. */
             repo_root: string;
+            /**
+             * Format: date-time
+             * @description Present when the sandbox is parked and this answer comes from the snapshot its park took (ADR 0063): the disk as of this instant, not now. Absent on a live read.
+             */
+            snapshot_at?: string | null;
             /** @description True when the repository holds more changes than were returned. */
             truncated: boolean;
             /**
@@ -15142,7 +15162,7 @@ export interface operations {
                     "application/json": components["schemas"]["NegotiationError"];
                 };
             };
-            /** @description Sandbox is not ready */
+            /** @description Sandbox is not ready, and a parked one's snapshot cannot answer this read */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -15241,7 +15261,7 @@ export interface operations {
                     "application/json": components["schemas"]["NegotiationError"];
                 };
             };
-            /** @description Sandbox is not ready */
+            /** @description Sandbox is not ready, and a parked one's snapshot cannot answer this read */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -15338,7 +15358,7 @@ export interface operations {
                     "application/json": components["schemas"]["NegotiationError"];
                 };
             };
-            /** @description Sandbox is not ready */
+            /** @description Sandbox is not ready, and a parked one's snapshot cannot answer this read */
             409: {
                 headers: {
                     [name: string]: unknown;
@@ -15437,7 +15457,7 @@ export interface operations {
                     "application/json": components["schemas"]["NegotiationError"];
                 };
             };
-            /** @description Sandbox is not ready */
+            /** @description Sandbox is not ready, and a parked one's snapshot cannot answer this read */
             409: {
                 headers: {
                     [name: string]: unknown;

package/dist/http.d.ts

@@ -15,7 +15,7 @@ export interface RequestOptions {
  * this string is already what Fountain's request logs are keyed on. The
  * version half is asserted against `package.json` by a test.
  */
-export declare const USER_AGENT = "fountain-sdk-js/6.4.0";
+export declare const USER_AGENT = "fountain-sdk-js/6.5.0";
 export declare class HttpClient {
     readonly config: ResolvedConfig;
     private readonly fetchImpl;

package/dist/http.js

@@ -5,7 +5,7 @@ import { AuthError, ConnectionError, FountainError, errorForStatus } from "./err
  * this string is already what Fountain's request logs are keyed on. The
  * version half is asserted against `package.json` by a test.
  */
-export const USER_AGENT = "fountain-sdk-js/6.4.0";
+export const USER_AGENT = "fountain-sdk-js/6.5.0";
 /**
  * The thin layer everything else is built on: one bearer token, JSON in and
  * out, and errors that say which call failed. `Fountain#api` exposes it

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@managoat/fountain-sdk",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "Run a coding agent on a real computer, with your repos and your credentials, in one call.",
   "license": "Apache-2.0",
   "publishConfig": {