@shardflux/sdk 0.14.0 → 0.16.0

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

@@ -731,6 +731,87 @@ export interface paths {
         patch?: never;
         trace?: never;
     };
+    "/v1/workspaces/{workspace_id}/computer": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        /**
+         * The workspace desktop's state (does not start it)
+         * @description Contracts §45.4. Tool `computer` (the token carries it only while the
+         *     workspace's computer use is on, §45.1).
+         */
+        get: operations["computerStatus"];
+        put?: never;
+        /**
+         * Start the workspace desktop (no-op while it runs)
+         * @description The size applies when this call starts the desktop; a running desktop
+         *     keeps its size (stop it first to change it). `409 conflict`
+         *     `details.reason computer_use_unavailable` when the workspace's template
+         *     cannot run a desktop.
+         */
+        post: operations["computerStart"];
+        /** Stop the workspace desktop (its windows close) */
+        delete: operations["computerStop"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/computer/actions": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Run a batch of computer actions, optionally ending with a screenshot
+         * @description Contracts §45.3. Starts the desktop when it does not run. The actions
+         *     run in order; the first failure stops the batch and the rest are
+         *     reported `skipped`. An invalid batch runs nothing: `422
+         *     validation_failed` with `details.index` (-1 for the batch itself).
+         */
+        post: operations["computerActions"];
+        delete?: never;
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
+    "/v1/workspaces/{workspace_id}/computer/stream": {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        get?: never;
+        put?: never;
+        /**
+         * Start the desktop viewer on its guest port
+         * @description Contracts §45.5. Expose the returned port with the ports API and open a
+         *     signed link whose `path` is the returned path. Port 61002 is view
+         *     only (the guest drops input); 61003 lets the viewer use the desktop.
+         */
+        post: operations["computerStreamStart"];
+        /** End every view of the desktop */
+        delete: operations["computerStreamStop"];
+        options?: never;
+        head?: never;
+        patch?: never;
+        trace?: never;
+    };
     "/v1/workspaces/{workspace_id}/wake-hint": {
         parameters: {
             query?: never;
@@ -1490,6 +1571,111 @@ export interface components {
             }[];
             stderr?: string;
         };
+        ComputerStartRequest: {
+            /** @default 1280 */
+            width?: number;
+            /** @default 800 */
+            height?: number;
+        };
+        ComputerStatus: {
+            running: boolean;
+            /** @example :1 */
+            display?: string;
+            width?: number;
+            height?: number;
+            /** Format: date-time */
+            started_at?: string;
+            /** @description The session command (window manager and panel). */
+            session?: string;
+            streams: {
+                view: boolean;
+                interactive: boolean;
+            };
+        };
+        /**
+         * @description One of Claude's computer toolset members with its parameters
+         *     (contracts §45.3). A parameter the action does not take is refused.
+         */
+        ComputerAction: {
+            /** @enum {string} */
+            action: "screenshot" | "zoom" | "left_click" | "right_click" | "middle_click" | "double_click" | "triple_click" | "left_click_drag" | "mouse_move" | "left_mouse_down" | "left_mouse_up" | "cursor_position" | "scroll" | "type" | "key" | "hold_key" | "wait";
+            /** @description [x, y] screen pixels. */
+            coordinate?: number[];
+            start_coordinate?: number[];
+            /** @description zoom: [x0, y0, x1, y1]. */
+            region?: number[];
+            /** @description type: the text; key/hold_key: key combinations; clicks, drag, scroll: modifiers held. */
+            text?: string;
+            /** @enum {string} */
+            scroll_direction?: "up" | "down" | "left" | "right";
+            scroll_amount?: number;
+            /** @description Seconds (wait */
+            duration?: number;
+            repeat?: number;
+        };
+        ComputerActionsRequest: {
+            actions: components["schemas"]["ComputerAction"][];
+            /**
+             * @description Append a screenshot after the last action that ran.
+             * @default false
+             */
+            screenshot?: boolean;
+            /** @default 250 */
+            settle_ms?: number;
+            /**
+             * @default png
+             * @enum {string}
+             */
+            format?: "png" | "jpeg";
+            /**
+             * @description jpeg only.
+             * @default 80
+             */
+            quality?: number;
+        };
+        ComputerImage: {
+            /** @enum {string} */
+            format: "png" | "jpeg";
+            width: number;
+            height: number;
+            data: string;
+        };
+        ComputerActionResult: {
+            action: string;
+            ok: boolean;
+            /** @description cursor_position: X=…, Y=… */
+            output?: string;
+            image?: components["schemas"]["ComputerImage"];
+            error?: {
+                /** @enum {string} */
+                code: "action_failed";
+                message: string;
+            };
+            /** @description An earlier action of the batch failed; this one did not run. */
+            skipped?: boolean;
+            /** Format: int64 */
+            took_ms: number;
+        };
+        ComputerActionsResult: {
+            results: components["schemas"]["ComputerActionResult"][];
+            screenshot?: components["schemas"]["ComputerImage"];
+            cursor: number[];
+            display: {
+                width: number;
+                height: number;
+            };
+        };
+        ComputerStreamRequest: {
+            /** @default false */
+            interactive?: boolean;
+        };
+        ComputerStream: {
+            /** @enum {integer} */
+            port: 61002 | 61003;
+            interactive: boolean;
+            /** @description The viewer page */
+            path: string;
+        };
         BrowserScreenshotRequest: {
             url: string;
             /** @default 1280 */
@@ -2074,6 +2260,8 @@ export interface operations {
         parameters: {
             query?: {
                 offset?: number;
+                /** @description Opt-in output representation. binary sends a u64be log offset followed by up to 1 MiB raw bytes; control messages remain JSON. json (default) sends up to 64 KiB base64 chunks. */
+                output_format?: "json" | "binary";
                 ticket?: string;
             };
             header?: never;
@@ -2582,6 +2770,152 @@ export interface operations {
             default: components["responses"]["Error"];
         };
     };
+    computerStatus: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Desktop state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStatus"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ComputerStartRequest"];
+            };
+        };
+        responses: {
+            /** @description Desktop state. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStatus"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStop: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Stopped */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerActions: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody: {
+            content: {
+                "application/json": components["schemas"]["ComputerActionsRequest"];
+            };
+        };
+        responses: {
+            /** @description Per-action results. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerActionsResult"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStreamStart: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: {
+            content: {
+                "application/json": components["schemas"]["ComputerStreamRequest"];
+            };
+        };
+        responses: {
+            /** @description Viewer started. */
+            200: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content: {
+                    "application/json": components["schemas"]["ComputerStream"];
+                };
+            };
+            default: components["responses"]["Error"];
+        };
+    };
+    computerStreamStop: {
+        parameters: {
+            query?: never;
+            header?: never;
+            path: {
+                workspace_id: components["parameters"]["WorkspaceId"];
+            };
+            cookie?: never;
+        };
+        requestBody?: never;
+        responses: {
+            /** @description Viewers stopped. */
+            204: {
+                headers: {
+                    [name: string]: unknown;
+                };
+                content?: never;
+            };
+            default: components["responses"]["Error"];
+        };
+    };
     workspaceWakeHint: {
         parameters: {
             query?: never;

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.14.0";
+export declare const SDK_VERSION = "0.16.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;
@@ -70,6 +70,12 @@ export declare const POOL_OPTIONS: {
  * native pooling. An explicitly supplied fetch is untouched. Idle pooled sockets do not keep the process alive.
  */
 export declare function defaultFetch(env?: Record<string, string | undefined> | undefined, undiciVersion?: string | undefined): typeof fetch;
+/** Snapshot the caller's env; empty overrides keep a supplied env independent of process.env. */
+export declare function proxyOptions(env: Record<string, string | undefined> | undefined): {
+    httpProxy: string;
+    httpsProxy: string;
+    noProxy: string;
+};
 export declare function buildUrl(base: string, path: string, query?: RequestOptions['query']): string;
 /**
  * True when fetch failed because its connection closed or reset before a response arrived: what a request sees when

package/dist/http.js

@@ -11,7 +11,7 @@
  */
 import { ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
 import { describeFailure } from "./progress.js";
-export const SDK_VERSION = '0.14.0';
+export const SDK_VERSION = '0.16.0';
 export const defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /**
  * How long an idle pooled connection stays reusable (ms): 5 minutes, instead of undici's 4 s default, so the request
@@ -36,7 +36,7 @@ export const POOL_OPTIONS = {
     connect: { keepAlive: true, keepAliveInitialDelay: TCP_KEEPALIVE_INITIAL_DELAY_MS },
 };
 /** One private HTTP/1.1 pool on Node 26+, shared by SDK clients. No global dispatcher changes. */
-let nodeFetch;
+const nodeFetches = new Map();
 /**
  * Reuses TLS connections. Node 26's bundled undici 8.9 can stall reused connections: use pinned undici with a
  * private HTTP/1.1-only dispatcher whose idle connections stay reusable for KEEP_ALIVE_TIMEOUT_MS. Other runtimes
@@ -46,27 +46,48 @@ let nodeFetch;
 export function defaultFetch(env = globalThis.process?.env, undiciVersion = globalThis.process?.versions?.undici) {
     // Why a fresh connection on Node 26 (its bundled HTTP client, measured): docs/progress/startup-latency.md.
     const base = (input, init) => fetch(input, init);
-    if (env?.SHARDFLUX_HTTP_KEEPALIVE === '0')
+    const proxy = proxyOptions(env);
+    const useProxy = Boolean(proxy.httpProxy || proxy.httpsProxy || proxy.noProxy || env?.NODE_USE_ENV_PROXY === '1');
+    if (!useProxy && env?.SHARDFLUX_HTTP_KEEPALIVE === '0')
         return (input, init) => {
             const headers = new Headers(init?.headers);
             headers.set('connection', 'close');
             return base(input, { ...init, headers });
         };
-    if (Number((undiciVersion ?? '').split('.')[0]) < 8 || !undiciVersion || env?.SHARDFLUX_HTTP_KEEPALIVE === '1')
+    if (!useProxy && (Number((undiciVersion ?? '').split('.')[0]) < 8 || !undiciVersion || env?.SHARDFLUX_HTTP_KEEPALIVE === '1'))
         return base;
+    const poolKey = useProxy ? JSON.stringify(proxy) : 'direct';
     return async (input, init) => {
-        nodeFetch ??= import('undici').then(({ Agent, fetch: pooledFetch }) => {
-            const dispatcher = new Agent({ ...POOL_OPTIONS, connect: { ...POOL_OPTIONS.connect } });
-            return async (input, init) => {
-                const response = await pooledFetch(input, { ...init, dispatcher });
-                // Web-standard runtime shape; undici and DOM iterator declarations differ.
-                // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Required by consumers compiling with lib.dom instead of only Node types.
-                return response;
-            };
-        });
+        let nodeFetch = nodeFetches.get(poolKey);
+        if (!nodeFetch) {
+            nodeFetch = import('undici').then(({ Agent, EnvHttpProxyAgent, fetch: pooledFetch }) => {
+                const options = { ...POOL_OPTIONS, connect: { ...POOL_OPTIONS.connect } };
+                const dispatcher = useProxy ? new EnvHttpProxyAgent({ ...options, ...proxy }) : new Agent(options);
+                return async (input, init) => {
+                    const response = await pooledFetch(input, { ...init, dispatcher });
+                    // Web-standard runtime shape; undici and DOM iterator declarations differ.
+                    // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-assertion -- Required by consumers compiling with lib.dom instead of only Node types.
+                    return response;
+                };
+            });
+            nodeFetches.set(poolKey, nodeFetch);
+        }
+        if (env?.SHARDFLUX_HTTP_KEEPALIVE === '0') {
+            const headers = new Headers(init?.headers);
+            headers.set('connection', 'close');
+            init = { ...init, headers };
+        }
         return (await nodeFetch)(input, init);
     };
 }
+/** Snapshot the caller's env; empty overrides keep a supplied env independent of process.env. */
+export function proxyOptions(env) {
+    return {
+        httpProxy: env?.http_proxy ?? env?.HTTP_PROXY ?? '',
+        httpsProxy: env?.https_proxy ?? env?.HTTPS_PROXY ?? '',
+        noProxy: env?.no_proxy ?? env?.NO_PROXY ?? '',
+    };
+}
 export function buildUrl(base, path, query) {
     const u = new URL(base.replace(/\/+$/, '') + path);
     for (const [k, v] of Object.entries(query ?? {})) {

package/dist/index.d.ts

@@ -14,8 +14,12 @@
  */
 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, AllocationMode, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResizeAppliesAt, ResizeCpu, ResizeDeferReason, ResizeDisk, ResizeLimitReason, ResizeMemory, ResizeParams, ResizeResult, ResizeResponse, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export { ProjectsRetentionApi, BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from './client.js';
+export { WorkspaceRef } from './workspace-ref.js';
+export { ReverseTunnel, WorkspaceTunnels } from './tunnels.js';
+export type { ReverseTunnelOptions, ReverseTunnelStats } from './tunnels.js';
+export type { WorkspaceRefFiles, WorkspaceRefParams } from './workspace-ref.js';
+export type { AgentSession, AllocationMode, ComputerUse, BillingCatalog, BillingSubscription, Caps, CheckoutSession, DiskLayout, Entitlements, FindByKeyOptions, ForkTarget, Invoice, InvoicePage, LifetimeFilter, ListParams, Me, RetentionPolicy, ProjectRetentionPolicy, OpenParams, OpenResponse, Operation, Page, PortalSession, PurposeFilter, ResetWorkspaceBody, ResizeAppliesAt, ResizeCpu, ResizeDeferReason, ResizeDisk, ResizeLimitReason, ResizeMemory, ResizeParams, ResizeResult, ResizeResponse, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
 export type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 export { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from './progress.js';
 export type { ColdBootReason, Durability, HostLost, LostSuspend, LifecycleAction, LifecyclePhase, LifecycleTiming, ProgressEvent, ProgressListener, RetryRecord, ServerTiming, TimingOutcome, TimingPhase, } from './progress.js';
@@ -30,7 +34,10 @@ 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, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
 export { WorkspacePorts } from './ports.js';
-export type { ExposePortResult, ExposedPort, PortCallbackResponse, PortCallbackUrl, PortLink, PortLinkOptions, PortLinkResponse, PortToken, PortTokenOptions, PortTokenResponse, PortView } from './ports.js';
+export { exitCodePosix } from './exit-code.js';
+export { COMPUTER_TOOLSET, WorkspaceComputer, computerToolset, decodeComputerImage } from './computer.js';
+export type { BeforeComputerAction, ComputerActOptions, ComputerScreenshot, ComputerStream, ComputerStreamOptions, ComputerToolResult, ComputerToolsetOptions, ToolUseBlockLike } from './computer.js';
+export type { ExposePortResult, ExposedPort, PortCallbackResponse, PortCallbackUrl, PortLink, PortEmbedOptions, PortLinkOptions, PortLinkResponse, PortToken, PortTokenOptions, PortTokenResponse, PortView } from './ports.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';
@@ -44,15 +51,15 @@ export type { HintOptions, HintResult, WakeOptions } from './workspace.js';
 export { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS, cellPath, ndjson } from './cell.js';
 export { EXECUTION_ID, ExecutionResult, newExecutionId } from './executions.js';
 export type { ExecutionChange, ExecutionError, ExecutionGetOptions, ExecutionResultBody, ExecutionRunOptions, ExecutionState } from './executions.js';
-export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ExecSession, ExecStartRequest, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, ResourceHint, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
+export type { TreeRevisionOptions, BrowserContent, BrowserContentRequest, BrowserScreenshotRequest, CellClientOptions, ComputerAction, ComputerActionName, ComputerActionResult, ComputerActionsRequest, ComputerActionsResult, ComputerImage, ComputerStartRequest, ComputerStatus, ComputerStreamInfo, ExecSession, ExecStartRequest, MemoryGrow, BurstSummary, BurstError, FileEdit, FileInfo, FileList, FilePatchEdit, FilePatchParams, FilePatchRequest, FilePatchResult, FileReadResult, FileRevision, FileSearchMatch, FileSearchOptions, FileSearchRequest, FileSearchResponse, FileSearchResult, FileWriteResult, GitResult, GitStatus, OutputEvent, ProcessList, PtyOpenRequest, PtySession, Residency, ResourceHint, RunOptions, RunResult, ServedFrom, Signal, WakeHintResult, WorkspaceChange, WorkspaceChangeKind, WorkspaceChangesPage, WorkspaceChangesParams, WorkspaceChangesSummary, } from './cell.js';
 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 { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, OpenAIResponsesToolDefinition, ToolTarget, 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 { DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
+export { FileNotFoundError, DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from './errors.js';
 export type { AppErrorCode, CellErrorCode, ErrorCode, ErrorReason, KnownErrorReason, WorkspaceMode } from './errors.js';
 export { SDK_VERSION } from './http.js';
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from './account.js';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
+export { ProjectsRetentionApi, BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from "./client.js";
+export { WorkspaceRef } from "./workspace-ref.js";
+export { ReverseTunnel, WorkspaceTunnels } from "./tunnels.js";
 export { COLD_BOOT_REASONS, durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from "./progress.js";
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from "./feedback.js";
 export { UsageApi } from "./usage.js";
@@ -6,6 +8,9 @@ export { TemplateBuildTimeoutError, TemplateBuildsApi, TemplateDraftApi, Templat
 export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile } from "./template-file.js";
 export { tarEnd, tarHeader, tarPadding } from "./tar.js";
 export { WorkspacePorts } from "./ports.js";
+// Computer use (0.15.0+, contracts §45).
+export { exitCodePosix } from "./exit-code.js";
+export { COMPUTER_TOOLSET, WorkspaceComputer, computerToolset, decodeComputerImage } from "./computer.js";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
@@ -16,7 +21,7 @@ export { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 export { ToolTokenManager } from "./tokens.js";
 export { ToolArgumentError, executeToolCall, toAnthropicTools, toOpenAITools, validateArgs, workspaceTools } from "./tools.js";
 export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
-export { DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
+export { FileNotFoundError, DurabilityLostError, ExecStartError, NotSupportedForModeError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError, TreeRevisionMismatchError } from "./errors.js";
 export { SDK_VERSION } from "./http.js";
 export { API_KEY_TOOL_PERMISSIONS, AccountApiKeysApi, AccountAuditApi, AccountAuthApi, AccountBillingApi, AccountExportsApi, AccountInvitationsApi, AccountMembersApi, AccountOrganizationsApi, AccountProjectsApi, AccountTemplatesApi, AccountTotpApi, AccountUserApi, CheckoutTimeoutError, OrganizationExportsApi, SESSION_TOKEN_PATTERN, ShardfluxAccount, isSessionToken, parseEmailToken, } from "./account.js";
 export { codexIdentityProof } from "./codex-proof.js";

package/dist/ports.d.ts

@@ -75,7 +75,14 @@ export interface PortTokenOptions {
     /** Lifetime in seconds: 60-86400 (default 3600). */
     ttlSeconds?: number;
 }
+/** Origins allowed to frame the linked port (§48). Validated by the API. */
+export interface PortEmbedOptions {
+    /** 1–10 distinct canonical HTTPS origins, without paths or wildcards; 256 characters each, 2048 total. */
+    origins: string[];
+}
 export interface PortLinkOptions {
+    /** Opt in to a partitioned browser session and this frame allowlist. */
+    embed?: PortEmbedOptions;
     /** Lifetime of the link and of the browser session it starts, in seconds: 60-604800 (default 86400). */
     ttlSeconds?: number;
     /** Where the link lands: a path starting with one `/`, printable ASCII, query allowed (default `/`). */

package/dist/ports.js

@@ -47,7 +47,7 @@ export class WorkspacePorts {
     }
     /** A signed link that opens the port in a browser. Share it like a password: anyone with it can open the port until it expires. */
     async link(port, opts = {}) {
-        const body = await this.#ctx.http.json('POST', this.#path(port, '/links'), { json: { ...(opts.ttlSeconds !== undefined ? { ttl_seconds: opts.ttlSeconds } : {}), ...(opts.path !== undefined ? { path: opts.path } : {}) } }, this.#ctx.authorization);
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/links'), { json: { ...(opts.embed !== undefined ? { embed: opts.embed } : {}), ...(opts.ttlSeconds !== undefined ? { ttl_seconds: opts.ttlSeconds } : {}), ...(opts.path !== undefined ? { path: opts.path } : {}) } }, this.#ctx.authorization);
         return { url: body.url, expiresAt: body.expires_at };
     }
     /** Creates the port's callback URL, or replaces it (the previous one stops working). Its secret is shown only here. */

package/dist/progress.d.ts

@@ -18,7 +18,7 @@
 import type { components } from './generated/app-api.js';
 type Operation = components['schemas']['Operation'];
 /** The SDK call a trace follows. `wait` is a direct waitForOperation(); `token` a tool token fetched for tool calls. */
-export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'resize' | 'wake' | 'wait' | 'token';
+export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'resize' | 'upgrade' | 'wake' | 'wait' | 'token';
 /**
  * - `request`: an API request that starts or joins the operation. A held open (`Prefer: wait`) spends the server's
  *   hold here (reason `held`), so the states inside it show only in the server timing.
@@ -160,7 +160,7 @@ export interface LostSuspend {
  */
 export type ColdBootReason = (typeof COLD_BOOT_REASONS)[number] | (string & {});
 /** Every {@link ColdBootReason} this version knows (0.14.0+). */
-export declare const COLD_BOOT_REASONS: readonly ["runtime_changed", "host_lost", "runtime_retired"];
+export declare const COLD_BOOT_REASONS: readonly ["runtime_changed", "host_lost", "runtime_retired", "upgraded"];
 /**
  * `result.host_lost` (0.13.1+), camelCased: the machine the workspace ran on failed. The workspace was moved to
  * `suspended` at that moment, and its next use (a resume, a tool call's wake, an open) restored it. See the lifecycle

package/dist/progress.js

@@ -1,5 +1,5 @@
 /** Every {@link ColdBootReason} this version knows (0.14.0+). */
-export const COLD_BOOT_REASONS = ['runtime_changed', 'host_lost', 'runtime_retired'];
+export const COLD_BOOT_REASONS = ['runtime_changed', 'host_lost', 'runtime_retired', 'upgraded'];
 const DURABILITY_STATES = new Set(['pending', 'durable', 'lost']);
 /**
  * The durable copy of a suspend or fork operation (0.12.0+): `result.durability` camelCased, or null when the result has

package/dist/templates.d.ts

@@ -215,6 +215,8 @@ export interface TemplateSummary {
         memory_mib: number | null;
         idle_policy: string | null;
     };
+    /** Computer use (0.15.0+, contracts §45.1): the template's switch for its workspaces (a workspace may override it). */
+    computer_use: boolean;
     open_version: TemplateVersion | null;
     /** The live draft (organization templates in dev mode), or null. */
     draft: TemplateDraftSummary | null;
@@ -900,6 +902,16 @@ export declare class TemplatesApi {
         includeArchived?: boolean;
         owner?: TemplateOwner;
     }): Promise<TemplateDetail>;
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    setComputerUse(slug: string, enabled: boolean, params?: {
+        organizationId?: string;
+    }): Promise<{
+        enabled: boolean;
+    }>;
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     find(slug: string, params?: {
         organizationId?: string;

package/dist/templates.js

@@ -693,6 +693,15 @@ export class TemplatesApi {
         const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}`;
         return this.#ctx().http.json('GET', path, { query: { include_archived: params.includeArchived, owner: params.owner } }, this.#ctx().authorization);
     }
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    async setComputerUse(slug, enabled, params = {}) {
+        const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}/computer-use` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}/computer-use`;
+        return this.#ctx().http.json('PUT', path, { json: { enabled } }, this.#ctx().authorization);
+    }
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     async find(slug, params = {}) {
         try {