@shardflux/sdk 0.6.2 → 0.8.0

package/dist/cell.d.ts

@@ -86,6 +86,8 @@ export interface CellClientOptions {
      * Through Workspace.cell() a wake reports here too (action `wake`).
      */
     onProgress?: ProgressListener;
+    /** Internal: see CAPTURE_BARRIER. */
+    [CAPTURE_BARRIER]?: (() => Promise<unknown> | undefined) | undefined;
 }
 /** Per-request transition handling (internal to CellClient). */
 interface TransitionOptions {
@@ -93,6 +95,11 @@ interface TransitionOptions {
     wake?: boolean;
 }
 export declare const DEFAULT_TRANSITION_TIMEOUT_MS = 120000;
+/**
+ * Internal (tool-call capture): a CellClient option whose function is awaited before every request, so calls wait for
+ * capture writes recorded before them (read-your-writes). Workspace.cell() sets it; the capture's own client does not.
+ */
+export declare const CAPTURE_BARRIER: unique symbol;
 export interface RunResult {
     sessionId: string;
     exitCode: number | null;

package/dist/cell.js

@@ -11,6 +11,11 @@ export function cellPath(template, params) {
     });
 }
 export const DEFAULT_TRANSITION_TIMEOUT_MS = 120_000;
+/**
+ * Internal (tool-call capture): a CellClient option whose function is awaited before every request, so calls wait for
+ * capture writes recorded before them (read-your-writes). Workspace.cell() sets it; the capture's own client does not.
+ */
+export const CAPTURE_BARRIER = Symbol('shardflux.captureBarrier');
 /** Wakes per call at most: a workspace that keeps being suspended again surfaces the refusal. */
 const MAX_WAKES = 3;
 const b64 = (bytes) => Buffer.from(typeof bytes === 'string' ? Buffer.from(bytes, 'utf8') : bytes).toString('base64');
@@ -72,6 +77,7 @@ export class CellClient {
     workspaceId;
     tokens;
     #opts;
+    #barrier;
     #listener;
     #wake;
     #transitionTimeoutMs;
@@ -90,6 +96,7 @@ export class CellClient {
         this.#wake = opts.wake ?? null;
         this.#transitionTimeoutMs = opts.transitionTimeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS;
         this.#listener = opts.onProgress;
+        this.#barrier = opts[CAPTURE_BARRIER];
     }
     #http(endpoint) {
         let c = this.#clients.get(endpoint);
@@ -120,6 +127,12 @@ export class CellClient {
      */
     async request(method, path, init = {}) {
         const closer = this.#closer.signal;
+        if (closer.aborted)
+            throw closer.reason;
+        // Read-your-writes: tool-call capture writes recorded before this call land first (bounded; never throws).
+        const barrier = this.#barrier?.();
+        if (barrier)
+            await barrier;
         if (closer.aborted)
             throw closer.reason;
         const { wake: wakeAllowed = true, ...reqInit } = init;

package/dist/client.d.ts

@@ -21,6 +21,7 @@ import { UsageApi } from './usage.js';
 import { VolumesApi } from './volumes.js';
 import type { FinishedOperation, InternalLifecycleOptions, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
 import type { ProgressListener } from './progress.js';
+import { CaptureRegistry } from './capture.js';
 export type WorkspaceView = components['schemas']['Workspace'];
 export type Operation = components['schemas']['Operation'];
 /** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout; contracts §19.11). */
@@ -34,6 +35,8 @@ export type UpdatePolicy = components['schemas']['UpdatePolicy'];
 /** Where the workspace's disk came from: null, a fork, or a draft state (test instances). */
 export type WorkspaceOrigin = components['schemas']['WorkspaceOrigin'];
 export type ResetWorkspaceBody = components['schemas']['ResetWorkspaceBody'];
+/** GET /v1/workspaces/{id}/inputs (0.7.0): the workspace's text inputs. */
+export type WorkspaceInputs = components['schemas']['WorkspaceInputs'];
 /** List filter: a lifetime or `any` (the list default is `persistent`). */
 export type LifetimeFilter = WorkspaceLifetime | 'any';
 /** List filter: a purpose or `any` (the list default is `standard`). */
@@ -126,6 +129,15 @@ export interface OpenParams {
      * ShardfluxApiError 422 (details.reason `secret_not_available`, details.names) and nothing is created or changed.
      */
     secrets?: string[];
+    /**
+     * The template version's text inputs `{NAME: value}` (0.7.0; contracts §24.3), put into the environment of every
+     * exec, terminal, start command and service. A new key stores each given value, else the declared default; an
+     * existing key replaces them all (omitted leaves them unchanged). Secret inputs are not passed here: they bind the
+     * stored secret of the same name. ShardfluxApiError 422 with details.reason `input_unknown` (an undeclared name),
+     * `input_invalid` (a secret input, or a value over 4096 bytes or with CR, LF or NUL) or `input_required`
+     * (details.names, details.kind).
+     */
+    inputs?: Record<string, string>;
     /**
      * `session`: the workspace is discarded when its session ends (workspace.close(), or the idle timeout); the key then
      * opens a NEW workspace. Omitted: the template version's default, else `persistent`. Immutable: reopening a live key
@@ -186,6 +198,8 @@ export interface ClientContext {
     workspaces: WorkspacesApi;
     /** The client-level progress listener (ShardfluxOptions.onProgress). */
     onProgress?: ProgressListener | undefined;
+    /** Tool-call captures of this client by workspace id (read-your-writes barrier, discard on delete/reset). */
+    captures: CaptureRegistry;
 }
 export declare class WorkspacesApi {
     #private;
@@ -289,6 +303,8 @@ export declare class WorkspacesApi {
         operation: Operation;
         workspace: Workspace;
     }>;
+    /** The workspace's text inputs `{NAME: value}` (0.7.0; contracts §24.3). Secret inputs are bound secrets, never listed. */
+    inputs(workspaceId: string): Promise<Record<string, string>>;
     operations(workspaceId: string, params?: {
         limit?: number;
         cursor?: string;

package/dist/client.js

@@ -9,6 +9,7 @@ import { UsageApi } from "./usage.js";
 import { VolumesApi } from "./volumes.js";
 import { AFTER_WAIT, TRACE, runLifecycle } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
+import { CaptureRegistry } from "./capture.js";
 /**
  * The workspace a key names (contracts §19.11): the live row (deleted_at null) when there is one, since at most one live
  * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
@@ -76,6 +77,8 @@ export class WorkspacesApi {
             body.tools = params.tools;
         if (params.secrets !== undefined)
             body.secrets = params.secrets;
+        if (params.inputs !== undefined)
+            body.inputs = params.inputs;
         if (params.lifetime !== undefined)
             body.lifetime = params.lifetime;
         const waitOpts = params.wait === false ? null : (params.wait ?? {});
@@ -299,7 +302,13 @@ export class WorkspacesApi {
     }
     #op(kind, workspaceId, json, opts) {
         const path = `/v1/workspaces/${encodeURIComponent(workspaceId)}${kind === 'delete' ? '' : `/${kind}`}`;
-        return runLifecycle(this.#ctx(), kind, workspaceId, async (init) => (await this.#lifecycle(kind === 'delete' ? 'DELETE' : 'POST', path, json, opts.idempotencyKey, init)).operation, opts);
+        return runLifecycle(this.#ctx(), kind, workspaceId, async (init) => {
+            const { operation } = await this.#lifecycle(kind === 'delete' ? 'DELETE' : 'POST', path, json, opts.idempotencyKey, init);
+            // Pending tool-call capture writes would land on a deleted or wiped disk: dropped once the change is accepted.
+            if (kind === 'delete' || kind === 'reset')
+                this.#ctx().captures.discard(workspaceId, kind);
+            return operation;
+        }, opts, { settle: kind === 'suspend' || kind === 'snapshot' });
     }
     delete(workspaceId, opts = {}) {
         return this.#op('delete', workspaceId, undefined, opts);
@@ -322,8 +331,9 @@ export class WorkspacesApi {
         const operation = await runLifecycle(this.#ctx(), 'close', workspaceId, async (init) => {
             const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/close`, undefined, opts.idempotencyKey, init);
             workspace = out.workspace;
+            this.#ctx().captures.discard(workspaceId, 'delete'); // the session is deleted
             return out.operation;
-        }, opts);
+        }, opts, { settle: true });
         return { operation, workspace: workspace };
     }
     reset(workspaceId, opts = {}) {
@@ -335,7 +345,8 @@ export class WorkspacesApi {
      * captured briefly (`operation`, layer_snapshot); poll `build` with templates.builds.waitForBuild. Owners/admins and
      * API keys with a tool permission only.
      */
-    saveAsTemplate(workspaceId, params) {
+    async saveAsTemplate(workspaceId, params) {
+        await this.#ctx().captures.settle(workspaceId); // captured tool calls are part of the saved layer
         return this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/save-as-template`, { json: saveAsTemplateBody(params), idempotencyKey: params.idempotencyKey ?? randomId('save-') }, this.#auth);
     }
     async fork(workspaceId, target, opts = {}) {
@@ -350,9 +361,14 @@ export class WorkspacesApi {
                 await trace.span('view', () => copy.refresh());
                 await opts[AFTER_WAIT]?.(trace, op);
             },
-        });
+        }, { settle: true });
         return { operation, workspace: copy };
     }
+    /** The workspace's text inputs `{NAME: value}` (0.7.0; contracts §24.3). Secret inputs are bound secrets, never listed. */
+    async inputs(workspaceId) {
+        const body = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/inputs`, {}, this.#auth);
+        return body.inputs;
+    }
     async operations(workspaceId, params = {}) {
         const page = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/operations`, { query: { limit: params.limit, cursor: params.cursor, state: params.state, kind: params.kind } }, this.#auth);
         return { data: page.data, nextCursor: page.next_cursor };
@@ -431,6 +447,7 @@ export class Shardflux {
             sleep,
             workspaces: this.workspaces,
             onProgress: opts.onProgress,
+            captures: new CaptureRegistry(),
         };
     }
     /** The authenticated principal (the API key, its organization and project). */

package/dist/egress.d.ts

@@ -122,6 +122,24 @@ export interface WorkspaceEgressPolicy {
     /** Active organization override (null: none); when set, `effective.source` is 'organization'. */
     organization_override: OrganizationEgressOverride | null;
     enforcement: EgressEnforcement;
+    /**
+     * The template version's network ceiling (0.7.0; contracts §24.3 `defaults.egress`), or null. The host enforces
+     * `effective` intersected with it; a workspace policy it would narrow is refused with 422 egress_widening.
+     */
+    template_egress: {
+        mode: 'allowlist' | 'none';
+        allow_hosts: string[];
+    } | null;
+    /** What the host enforces (0.7.0): `effective` intersected with `template_egress` (equal to `effective` without one). */
+    effective_policy: {
+        mode: EgressMode;
+        rules: Array<{
+            host: string;
+            ports: number[];
+            protocols: Array<'tcp'>;
+        }>;
+        cidrs: string[];
+    };
 }
 export declare class EgressPolicyApi {
     #private;

package/dist/errors.d.ts

@@ -13,8 +13,15 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * file_list_indexing (retryable), guest_feature_unavailable; 422 validation_failed confirm_destructive_required,
  * reserved_key_prefix, invalid_defaults, update_policy_not_available, invalid_path, too_many_acknowledged_findings;
  * 403 forbidden template_dev_mode_role; 404 not_found draft_not_found, version_not_found, path_not_found.
+ * The template editor (contracts §24.6, 0.7.0) added: 422 validation_failed invalid_recipe, base_not_layered,
+ * language_unavailable, language_conflict, invalid_package, too_many_files, platform_owned_path, upload_required,
+ * upload_missing, upload_digest_mismatch, upload_too_large, extra_hosts_without_auto, invalid_settings,
+ * services_unsupported, input_required, input_unknown, input_invalid, egress_widening, reserved_session_id,
+ * env_collision, reserved_template_slug; 409 conflict package_index_unavailable; 404 package_not_found; the operation
+ * error `startup_failed` (details.reason startup_failed, service_not_ready, secrets_unavailable, secret_not_available,
+ * guest_feature_unavailable).
  */
-export type KnownErrorReason = 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found';
+export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {

package/dist/generated/app-api.d.ts

@@ -2132,6 +2132,46 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/organizations/{organization_id}/template-languages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The recipe languages a base offers: version, default, whether the base already has it, and the hosts its install needs
+         * @description The §24.1 language table read for the chain’s platform base of `base`, resolved as a build resolves `recipe.base` (422 validation_failed with details.field "base" and the build’s reasons: base_not_found, base_archived, base_not_published, architecture_not_supported). `included`: the base already has that version (python-node-browser: python and node), so the build installs nothing for it. A version the base has another version of is left out (a build would refuse it with language_conflict). Owners/admins and API keys with a tool permission.
+         */
+        get: operations["getV1OrganizationsOrganizationIdTemplateLanguages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/template-languages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The recipe languages a base offers: version, default, whether the base already has it, and the hosts its install needs (the API key’s organization)
+         * @description The §24.1 language table read for the chain’s platform base of `base`, resolved as a build resolves `recipe.base` (422 validation_failed with details.field "base" and the build’s reasons: base_not_found, base_archived, base_not_published, architecture_not_supported). `included`: the base already has that version (python-node-browser: python and node), so the build installs nothing for it. A version the base has another version of is left out (a build would refuse it with language_conflict). Owners/admins and API keys with a tool permission.
+         */
+        get: operations["getV1TemplateLanguages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/organizations/{organization_id}/template-builder-availability": {
         parameters: {
             query?: never;
@@ -2330,6 +2370,26 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/api/v1/organizations/{organization_id}/template-languages": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        /**
+         * The recipe languages a base offers: version, default, whether the base already has it, and the hosts its install needs
+         * @description The §24.1 language table read for the chain’s platform base of `base`, resolved as a build resolves `recipe.base` (422 validation_failed with details.field "base" and the build’s reasons: base_not_found, base_archived, base_not_published, architecture_not_supported). `included`: the base already has that version (python-node-browser: python and node), so the build installs nothing for it. A version the base has another version of is left out (a build would refuse it with language_conflict). Owners/admins and API keys with a tool permission.
+         */
+        get: operations["getApiV1OrganizationsOrganizationIdTemplateLanguages"];
+        put?: never;
+        post?: never;
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/api/v1/organizations/{organization_id}/template-builder-availability": {
         parameters: {
             query?: never;
@@ -4962,6 +5022,32 @@ export interface components {
             /** @description Known versions, newest first (at most 200). */
             versions: string[];
         };
+        TemplateLanguages: {
+            /** @description `<slug>@<version>` as asked. */
+            base: string;
+            /** @description The chain’s platform base (the base itself for a platform version): the table is read for it. */
+            platform_base: string;
+            /** @description Hosts apt installs need while an `auto` build runs (the platform base’s `build_inputs.apt_pin.hosts`, else snapshot.ubuntu.com). */
+            apt_hosts: string[];
+            /** @description In table order (python, node, go, rust, java), then newest version first as the table lists them. */
+            data: {
+                /** @enum {string} */
+                id: "python" | "node" | "go" | "rust" | "java";
+                /** @description Display name: Python, Node.js, Go, Rust, Java. */
+                name: string;
+                /** @description The version as a recipe names it (`{id, version}`): "3.12", "24", "1.27". */
+                version: string;
+                /** @description The version `{id}` without a version resolves to on this base. */
+                default: boolean;
+                /** @description The base already has this version (its manifest `tools`): the build installs nothing for it and needs no host (python still gets its /opt/venv). */
+                included: boolean;
+                base_version: string | null;
+                /** @description Hosts its download needs while an `auto` build runs ([] when included, or when it comes from apt). */
+                hosts: string[];
+                /** @description apt packages it installs ([] when included). An `auto` build then also allows `apt_hosts`. */
+                apt: string[];
+            }[];
+        };
         /** @description How the version was produced: a recipe build, a saved workspace (or draft), or git (reserved). */
         TemplateSource: {
             /** @enum {string} */
@@ -15102,6 +15188,91 @@ export interface operations {
             };
         };
     };
+    getV1OrganizationsOrganizationIdTemplateLanguages: {
+        parameters: {
+            query: {
+                /** @description `<slug>@<version>` (apt: the base whose apt index is searched). */
+                base: string;
+            };
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                organization_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TemplateLanguages"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
+    getV1TemplateLanguages: {
+        parameters: {
+            query: {
+                /** @description `<slug>@<version>` (apt: the base whose apt index is searched). */
+                base: string;
+            };
+            header?: never;
+            path?: never;
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TemplateLanguages"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     getV1OrganizationsOrganizationIdTemplateBuilderAvailability: {
         parameters: {
             query?: never;
@@ -17424,6 +17595,50 @@ export interface operations {
             };
         };
     };
+    getApiV1OrganizationsOrganizationIdTemplateLanguages: {
+        parameters: {
+            query: {
+                /** @description `<slug>@<version>` (apt: the base whose apt index is searched). */
+                base: string;
+            };
+            header?: never;
+            path: {
+                /** @description UUIDv7, lowercase canonical form. */
+                organization_id: string;
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Default Response */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["TemplateLanguages"];
+                };
+            };
+            /** @description Default Response */
+            "4XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+            /** @description Default Response */
+            "5XX": {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ErrorBody"];
+                };
+            };
+        };
+    };
     getApiV1OrganizationsOrganizationIdTemplateBuilderAvailability: {
         parameters: {
             query?: never;

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.6.2";
+export declare const SDK_VERSION = "0.8.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

package/dist/http.js

@@ -6,7 +6,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, isErrorBody } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.6.2';
+export const SDK_VERSION = '0.8.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * The fetch the SDK uses when none is given. On runtimes whose bundled undici is 8.x (Node 26) it sends

package/dist/index.d.ts

@@ -12,14 +12,18 @@
 export type { components, operations, paths } from './generated/app-api.js';
 export type { components as CellComponents, paths as CellPaths } from './generated/cell-api.js';
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from './client.js';
-export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export type { AgentSession, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ShardfluxOptions, UpdatePolicy, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
 export type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
 export { formatTiming } from './progress.js';
 export type { LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
 export { UsageApi } from './usage.js';
 export type { Grants, Spend, SpendPolicy, UsageEstimate, UsageMeter, UsageSeries, UsageSeriesParams, UsageSummary } from './usage.js';
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from './templates.js';
-export type { BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, DraftOpened, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRegistrationState, TemplateBuildState, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateOwner, TemplateRecipe, TemplateSource, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateVersion, TemplateVersionState, WaitForBuildOptions, } from './templates.js';
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from './templates.js';
+export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from './template-file.js';
+export type { PackedFile, YamlParser } from './template-file.js';
+export { tarEnd, tarHeader, tarPadding } from './tar.js';
+export type { TarEntry, TarEntryType } from './tar.js';
+export type { BuildFromFileEvent, BuildFromFileOptions, BuildFromFileResult, BuildFromRecipeOptions, BuilderAvailability, CreateDraftBody, CreateDraftParams, CreateTemplateBuildParams, CreateTestInstanceBody, CreateVersionTestInstanceBody, CreateVersionTestInstanceParams, DraftOpened, LocalUpload, DraftState, OpenTestInstanceParams, OrgTemplateStorage, PublishDraftBody, PublishDraftParams, PutUploadOptions, SaveAsTemplateBody, SaveAsTemplateParams, SaveAsTemplateResponse, TemplateBuild, TemplateBuildLogUrl, TemplateBuildRecipeV2, TemplateBuildRegistrationState, TemplateBuildState, TemplateCategory, TemplateDefaults, TemplateDefaultsInput, TemplateDetail, TemplateDiffChange, TemplateDiffEntry, TemplateDiffPage, TemplateDiffParams, TemplateDraft, TemplateDraftSummary, TemplateEgressDefault, TemplateFileEntry, TemplateFilePage, TemplateFilesParams, TemplateFilesSummary, TemplateInput, TemplateLanguage, TemplateLanguages, TemplateOwner, TemplatePackage, TemplatePackageEcosystem, TemplatePackagePage, TemplateRecipe, TemplateRecipeV2, TemplateRecipeV2File, TemplateService, TemplateSettings, TemplateSettingsInput, TemplateSource, TemplateStartCommand, TemplateStorage, TemplateStorageWarning, TemplateSummary, TemplateUpload, TemplateUploadRequest, TemplateUploadResponse, TemplateUploadResult, TemplateVersion, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { SecretsApi, WorkspaceSecrets } from './secrets.js';
 export type { BoundSecretStatus, CreateOrganizationSecretParams, CreateSecretParams, Secret, SecretAccessEvent, SecretPermissions, SecretScope, SecretVersion, UpdateSecretParams, WorkspaceSecretBindings, } from './secrets.js';
 export { EgressPolicyApi } from './egress.js';
@@ -35,7 +39,10 @@ export type { BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, C
 export { ToolTokenManager } from './tokens.js';
 export type { ToolName, ToolToken, ToolTokenOptions } from './tokens.js';
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from './tools.js';
-export type { JsonSchema, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export { CaptureError, ToolCallCapture, captureTool } from './capture.js';
+export type { CallLike, CallRef, CaptureCall, CaptureErrorKind, CaptureEvent, CaptureFlushResult, CapturePart, CaptureSelector, CaptureSource, CaptureStats, CaptureStatus, DropReason, ToolCallCaptureOptions, WrapOptions, } from './capture.js';
+export type { AiSdkAdapter, AiSdkToolEndEvent, AnthropicAdapter, ClaudeAdapter, ClaudeCaptureHooks, ClaudeHookCallback, ClaudeHookMatcher, LangChainAdapter, LangChainToolHandler, MastraAdapter, MastraAfterToolCallContext, McpAdapter, OpenAIAgentsAdapter, } from './capture-adapters.js';
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from './errors.js';
 export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason } from './errors.js';
 export { SDK_VERSION } from './http.js';

package/dist/index.js

@@ -1,7 +1,9 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
 export { formatTiming } from "./progress.js";
 export { UsageApi } from "./usage.js";
-export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatesApi, buildSettled, saveAsTemplateBody } from "./templates.js";
+export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, TemplatePackagesApi, TemplateUploadError, TemplateUploadsApi, TemplateVersionTestInstancesApi, TemplateVersionsApi, TemplatesApi, buildSettled, saveAsTemplateBody, } from "./templates.js";
+export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
+export { tarEnd, tarHeader, tarPadding } from "./tar.js";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
@@ -10,5 +12,6 @@ export { Workspace } from "./workspace.js";
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from "./cell.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
+export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
 export { OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";

package/dist/lifecycle.d.ts

@@ -46,4 +46,6 @@ export declare function waitOptionsOf(opts: LifecycleOptions): WaitOptions | nul
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions): Promise<Operation>;
+export declare function runLifecycle(ctx: ClientContext, kind: LifecycleAction, workspaceId: string, start: (init: Pick<RequestOptions, 'onRetry'>) => Promise<Operation>, opts: InternalLifecycleOptions, capture?: {
+    settle?: boolean;
+}): Promise<Operation>;

package/dist/lifecycle.js

@@ -13,10 +13,14 @@ export function waitOptionsOf(opts) {
  * Starts a lifecycle operation with `start` and, when `opts.wait` asks for it, waits for it to finish. The trace covers
  * the request, every observed state, and `AFTER_WAIT`; it ends with `done` either way.
  */
-export async function runLifecycle(ctx, kind, workspaceId, start, opts) {
+export async function runLifecycle(ctx, kind, workspaceId, start, opts, capture = {}) {
     const waitOpts = waitOptionsOf(opts);
     const trace = new Trace(kind, combineListeners(ctx.onProgress, opts.onProgress, waitOpts?.onProgress), { workspaceId });
     return traced(trace, async () => {
+        // Tool-call capture writes recorded before this call land first (snapshot, fork, suspend and close include them).
+        const pending = capture.settle ? ctx.captures.settle(workspaceId) : undefined;
+        if (pending)
+            await trace.span('capture_flush', () => pending);
         trace.phase('request');
         const operation = await start({ onRetry: trace.onRetry });
         trace.observe(operation);

package/dist/progress.d.ts

@@ -26,8 +26,10 @@ export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork
  *   operation's `state_reason` (e.g. `no_ready_host`, `template_downloading`).
  * - `view`: reading the workspace after the operation. `token`: issuing a tool token (concurrent with `view` in open()).
  * - `busy`: a tool call waiting out `workspace_busy` (only in `tool` events).
+ * - `capture_flush` (0.7.0+): a lifecycle call waiting for tool-call capture writes recorded before it (only when some
+ *   were pending).
  */
-export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy';
+export type LifecyclePhase = 'request' | 'queued' | 'capacity_pending' | 'running' | 'view' | 'token' | 'busy' | 'capture_flush';
 export interface TimingPhase {
     phase: LifecyclePhase;
     /** The server's state_reason, or why the SDK entered the phase (`held`, `initial`, `expiring`, `invalidated`). */

package/dist/tar.d.ts

@@ -0,0 +1,40 @@
+/**
+ * A small tar writer for build uploads of folders (contracts §24.2: uncompressed ustar/pax, extracted by the host's
+ * static tool). Pure: no Node imports, so the browser bundle can carry it.
+ *
+ * The bytes equal CPython's `tarfile.open(mode="w", format=tarfile.PAX_FORMAT)` with every member added by hand (the
+ * Python SDK's writer), so both SDKs upload the same bytes for the same folder and a template built from either has the
+ * same recipe_sha256:
+ * - a pax `x` header (`././@PaxHeader`) precedes a member whose name or link target is non-ASCII or longer than 100
+ *   characters (`path`, `linkpath` records), or whose size does not fit the 11 octal digits (`size`);
+ * - the ustar header then holds the name encoded as ASCII with `?` for each non-ASCII code point, truncated to 100 bytes;
+ * - the archive ends with two zero blocks and is padded to a multiple of 10240 bytes (tarfile's RECORDSIZE).
+ */
+export declare const TAR_BLOCK = 512;
+export declare const TAR_RECORD_SIZE: number;
+export type TarEntryType = 'file' | 'dir' | 'symlink';
+export interface TarEntry {
+    /** Relative path with `/` separators; directories get their trailing `/` from the writer. */
+    path: string;
+    type: TarEntryType;
+    /** Permission bits (masked to 0o7777 as tarfile does). */
+    mode: number;
+    /** Bytes of a regular file (0 for directories and symlinks). */
+    size: number;
+    /** Symlink target. */
+    linkname?: string;
+    mtime?: number;
+    uid?: number;
+    gid?: number;
+    uname?: string;
+    gname?: string;
+}
+/** Zero padding after `size` bytes of member data. */
+export declare function tarPadding(size: number): Uint8Array;
+/**
+ * The header block(s) of one member: an optional pax extended header with its records, then the ustar header.
+ * Member data (a file's bytes) follows, then tarPadding(size).
+ */
+export declare function tarHeader(entry: TarEntry): Uint8Array;
+/** The end of an archive written so far (`offset` bytes): two zero blocks, then zeros up to a multiple of 10240. */
+export declare function tarEnd(offset: number): Uint8Array;