@shardflux/sdk 0.6.1 → 0.7.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`). */
@@ -92,7 +95,11 @@ export interface ForkTarget {
     lifetime?: WorkspaceLifetime;
 }
 export interface WaitOptions {
-    /** Give up waiting after this long (default 300 000 ms); the operation continues server side. */
+    /**
+     * Give up waiting after this long (default 300 000 ms); the operation continues server side. A start waiting for
+     * capacity (`capacity_pending`) does so until its deadline (`error.details.deadline_at`, 15 minutes after it was
+     * created) and then fails with `capacity_unavailable` (retryable; nothing was started).
+     */
     timeoutMs?: number;
     /** First poll delay (default 250 ms); doubles up to `maxPollIntervalMs` with jitter. Used when the server does not wait. */
     pollIntervalMs?: number;
@@ -122,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
@@ -182,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;
@@ -200,7 +218,9 @@ export declare class WorkspacesApi {
      * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
      * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
      * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
-     * state change (queued, capacity_pending, running, with the server's reason) as it is observed.
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start waiting in
+     * capacity_pending gives up at its deadline (`deadlineAt` on the phase event) and fails with `capacity_unavailable`
+     * (`err.retryable` true: nothing was started, retry later); the SDK does not retry it.
      */
     waitForOperation(operationId: string, opts?: WaitOptions): Promise<Operation>;
     /** One operation (GET /v1/operations/{id}); lifecycle operations stay pollable after a workspace is deleted. */
@@ -283,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 ?? {});
@@ -170,7 +173,9 @@ export class WorkspacesApi {
      * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
      * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
      * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
-     * state change (queued, capacity_pending, running, with the server's reason) as it is observed.
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed. A start waiting in
+     * capacity_pending gives up at its deadline (`deadlineAt` on the phase event) and fails with `capacity_unavailable`
+     * (`err.retryable` true: nothing was started, retry later); the SDK does not retry it.
      */
     async waitForOperation(operationId, opts = {}) {
         const inherited = opts[TRACE];
@@ -297,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);
@@ -320,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 = {}) {
@@ -333,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 = {}) {
@@ -348,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 };
@@ -429,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 {
@@ -53,13 +60,19 @@ type Operation = AppComponents['schemas']['Operation'];
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
  * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
- * (it returns the same operation while it is active).
+ * (it returns the same operation while it is active). A start still waiting for capacity
+ * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
  */
 export declare class OperationTimeoutError extends Error {
     readonly operationId: string;
     readonly workspaceId: string | null;
     readonly lastState: Operation['state'];
     readonly lastReason: string | null;
+    /**
+     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
+     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     */
+    readonly deadlineAt: string | null;
     readonly waitedMs: number;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing: LifecycleTiming | undefined;
@@ -70,6 +83,12 @@ export declare class OperationFailedError extends Error {
     readonly operation: Operation;
     readonly operationId: string;
     readonly errorCode: string | null;
+    /**
+     * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
+     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
+     * retries a failed operation itself.
+     */
+    readonly retryable: boolean;
     /** Where the time went before the operation failed. */
     timing: LifecycleTiming | undefined;
     constructor(op: Operation);

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { capacityDeadlineOf } from "./progress.js";
 export function isErrorBody(v) {
     if (typeof v !== 'object' || v === null || !('error' in v))
         return false;
@@ -45,23 +46,32 @@ export class ShardfluxProtocolError extends Error {
 /**
  * Waiting for an operation ran out of time. The operation keeps running server side:
  * resume with `cloud.workspaces.waitForOperation(err.operationId)` or call open() again
- * (it returns the same operation while it is active).
+ * (it returns the same operation while it is active). A start still waiting for capacity
+ * (`capacity_pending`) gives up at `deadlineAt` and then fails with `capacity_unavailable`.
  */
 export class OperationTimeoutError extends Error {
     operationId;
     workspaceId;
     lastState;
     lastReason;
+    /**
+     * When the operation was last `capacity_pending`: when it gives up waiting for a host (`error.details.deadline_at`,
+     * RFC 3339) and fails with `capacity_unavailable`. Null in other states or from an API that does not report it.
+     */
+    deadlineAt;
     waitedMs;
     /** Where the time went: client phases, retries and the operation's own server timing so far. */
     timing = undefined;
     constructor(op, waitedMs) {
-        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; it continues server side.`);
+        const deadlineAt = capacityDeadlineOf(op);
+        const after = deadlineAt ? `it keeps waiting for a host server side until ${deadlineAt} and fails with capacity_unavailable if none admits it by then.` : 'it continues server side.';
+        super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; ${after}`);
         this.name = 'OperationTimeoutError';
         this.operationId = op.id;
         this.workspaceId = op.workspace_id;
         this.lastState = op.state;
         this.lastReason = op.state_reason ?? null;
+        this.deadlineAt = deadlineAt;
         this.waitedMs = waitedMs;
     }
 }
@@ -70,6 +80,12 @@ export class OperationFailedError extends Error {
     operation;
     operationId;
     errorCode;
+    /**
+     * `operation.error.retryable` (false when absent): the same request may succeed later. `capacity_unavailable` is
+     * retryable: no host could admit the start before its deadline, nothing was started, retry later. The SDK never
+     * retries a failed operation itself.
+     */
+    retryable;
     /** Where the time went before the operation failed. */
     timing = undefined;
     constructor(op) {
@@ -79,5 +95,6 @@ export class OperationFailedError extends Error {
         this.operation = op;
         this.operationId = op.id;
         this.errorCode = code;
+        this.retryable = op.error?.retryable === true;
     }
 }