@shardflux/sdk 0.13.1 → 0.15.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;
@@ -953,6 +1034,12 @@ export interface components {
             burst_vcpus?: number;
             /** @description The burst VM's memory in MiB (burst always only; default the host's, 8192), at most the plan's workspace memory ceiling. */
             burst_memory_mib?: number;
+            /**
+             * @description Contracts §41.1: whether an elastic workspace's memory grows before the command starts. `heavy` grows it to the exec-start size first; `light` starts at once (pressure grows cover a spike); `auto` (default) grows only for a heavy command family (package installers, test runners, compilers, type checkers, bundlers). Changes only elastic workspaces in memory layout v2; any other value is 422 validation_failed (details.field resource_hint).
+             * @default auto
+             * @enum {string}
+             */
+            resource_hint?: "auto" | "light" | "heavy";
         };
         /** @description Names of customer secrets (contracts §17) to inject as environment variables NAME=value of this process only. The cell resolves them at session start through the API with the caller's tool token (permission-checked and audited by the API); values are never logged, persisted or returned by the cell. Any name the caller may not use (unknown, not permitted for this workspace/project/tool) refuses the whole start with 403 forbidden (details.reason secret_not_available, details.names); nothing is started. A name that is also a key of `env` is refused (422 validation_failed). Requires a workspace tool token (browser stream tickets cannot resolve secrets: 403, details.reason secret_refs_require_tool_token). Resolution failures: 401 (token revoked/expired), 409 stale_epoch, 429 rate_limited, 503 dependency_unavailable. A retried start with the same session_id re-resolves the names; if a value changed since the first start the host refuses the different request (409 conflict). */
         SecretRefs: string[];
@@ -1484,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 */
@@ -2576,6 +2768,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.13.1";
+export declare const SDK_VERSION = "0.15.0";
 export interface RequestOptions {
     query?: Record<string, string | number | boolean | undefined | null>;
     json?: unknown;

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.13.1';
+export const SDK_VERSION = '0.15.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

package/dist/index.d.ts

@@ -14,10 +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, ResumeAnswer, ResumeRequestOptions, ResumeResponse, ShardfluxOptions, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResponse, SuspendWhenIdleResult, WaitOptions, WorkspaceInputs, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView, } from './client.js';
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from './client.js';
+export { WorkspaceRef } from './workspace-ref.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, 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 { durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from './progress.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';
 export { FEEDBACK_CATEGORIES, FEEDBACK_MESSAGE_MAX_LENGTH } from './feedback.js';
 export type { AccountFeedbackParams, FeedbackCategory, FeedbackContext, FeedbackReceipt, SendFeedbackParams } from './feedback.js';
@@ -29,6 +31,10 @@ 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, TemplateVersionImmutable, TemplateVersionRecipe, TemplateVersionState, UploadData, WaitForBuildOptions, WorkspaceStartup, } from './templates.js';
+export { WorkspacePorts } from './ports.js';
+export { COMPUTER_TOOLSET, WorkspaceComputer, computerToolset, decodeComputerImage } from './computer.js';
+export type { ComputerActOptions, ComputerScreenshot, ComputerStream, ComputerStreamOptions, ComputerToolResult, ComputerToolsetOptions, ToolUseBlockLike } from './computer.js';
+export type { ExposePortResult, ExposedPort, PortCallbackResponse, PortCallbackUrl, PortLink, 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';
@@ -42,11 +48,11 @@ 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, 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';
@@ -54,7 +60,9 @@ export { DurabilityLostError, ExecStartError, NotSupportedForModeError, Operatio
 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';
-export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, SpendPolicyUpdate, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
+export { codexIdentityProof } from './codex-proof.js';
+export type { CodexIdentityProof, CodexProofOptions, CodexProofUnavailable } from './codex-proof.js';
+export type { AccountClientOptions, AccountDeletion, AccountDeletionCanceled, AccountDeletionScheduled, ApiKey, ApiKeyPage, ApiKeyToolPermission, AuditExportParams, AuthSessionInfo, AuthSessionPage, AuthSessionState, AuthUser, BillingInvoicePage, BillingPortalSession, CheckoutStatus, CreateApiKeyParams, CreatedApiKey, DataExport, EmailChangeConfirmResult, EmailChangeResult, Invitation, InvitationPage, LoginResult, Member, MemberPage, MemberRole, MfaChallengeResult, Organization, OrganizationDeletion, OrganizationDeletionResult, OrganizationPage, OrganizationRole, OrganizationWorkspacePage, OrganizationWorkspacesParams, PageParams, PasswordChangeResult, PasswordResetConfirmResult, PasswordResetRequestResult, Project, ProjectPage, RecoveryCodes, RegisterResult, SignupResult, SignupAccess, EmailCodeResult, ResendVerificationResult, SessionTokenUpdate, ShardfluxAccountOptions, SpendPolicyUpdate, StepUpResult, TotpConfirmResult, TotpDisableResult, TotpEnrollment, VerifyEmailResult, WaitForCheckoutOptions, } from './account.js';
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from './version-check.js';
 export type { CheckClientVersionOptions, ClientEcosystem, ClientVersionEntry, ClientVersionStatus, ClientVersionStatusKind, ClientVersions, VersionCheckIdentity, VersionCheckOption, } from './version-check.js';
 export { isWorkspaceGone } from './errors.js';

package/dist/index.js

@@ -1,10 +1,14 @@
-export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
-export { durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from "./progress.js";
+export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } from "./client.js";
+export { WorkspaceRef } from "./workspace-ref.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";
 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 { WorkspacePorts } from "./ports.js";
+// Computer use (0.15.0+, contracts §45).
+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";
@@ -18,6 +22,7 @@ export { CaptureError, ToolCallCapture, captureTool } from "./capture.js";
 export { 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";
 export { checkClientVersion, clientVersionStatus, compareVersions, versionCheckDisabledByEnv } from "./version-check.js";
 export { isWorkspaceGone } from "./errors.js";
 export { defaultFetch } from "./http.js";

package/dist/ports.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Inbound ports (0.14.0; contracts §39.3): serve a TCP port of a processful workspace at its own HTTPS URL,
+ * `https://<port>-<handle>.<ingress domain>`. Every port is private: a request carries a port token
+ * (`Authorization: Bearer sfp_…`), a signed link's browser session, or arrives on the port's callback URL. A request
+ * to a suspended or parked workspace wakes it and is served once it runs.
+ *
+ *   const { url } = await workspace.ports.expose(3000);
+ *   const { token } = await workspace.ports.token(3000);
+ *   await fetch(url, { headers: { authorization: `Bearer ${token}` } });
+ *
+ * Types are written by hand (checked against the generated contract in type-checks.ts).
+ */
+import type { components, operations } from './generated/app-api.js';
+import type { ClientContext } from './client.js';
+type Created<Op> = Op extends {
+    responses: {
+        201: {
+            content: {
+                'application/json': infer T;
+            };
+        };
+    };
+} ? T : never;
+/** An exposed port as the API sends it (`Port`). */
+export type PortView = components['schemas']['Port'];
+/** POST …/ports/{port}/tokens (201). */
+export type PortTokenResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortTokens']>;
+/** POST …/ports/{port}/links (201). */
+export type PortLinkResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortLinks']>;
+/** POST …/ports/{port}/callback (201). */
+export type PortCallbackResponse = Created<operations['postV1WorkspacesWorkspaceIdPortsPortCallback']>;
+/** An exposed port of a workspace. */
+export interface ExposedPort {
+    /** TCP port inside the workspace (1-65535). */
+    port: number;
+    /** `https://<port>-<handle>.<ingress domain>`: requests need a port token, a link's browser session or the callback URL. */
+    url: string;
+    /** When the port was exposed (RFC 3339). Exposing it again after a close starts a new exposure. */
+    createdAt: string;
+    /** Set when the port has a callback URL (its secret is shown only by `createCallbackUrl()`). */
+    callback: {
+        createdAt: string;
+    } | null;
+}
+/** `expose()`: the port, and whether this call exposed it (201) or it already was (200, unchanged). */
+export interface ExposePortResult extends ExposedPort {
+    created: boolean;
+}
+/** A port token: send it as `Authorization: Bearer <token>` (or `X-Shardflux-Token`) to `url`. */
+export interface PortToken {
+    /** `sfp_…`. Revoked when the port is closed, the workspace is deleted or the API key that minted it is revoked. */
+    token: string;
+    /** RFC 3339. */
+    expiresAt: string;
+    /** The port's URL. */
+    url: string;
+}
+/** A signed link: opening it in a browser starts a session for the port (a cookie until `expiresAt`) and lands on its path. */
+export interface PortLink {
+    url: string;
+    /** RFC 3339: the link and the browser session it starts end then. */
+    expiresAt: string;
+}
+/**
+ * The port's callback URL: register `url` plus your own path with GitHub, Slack, Stripe or an OAuth provider. A request
+ * to `<url><rest>` reaches `/<rest>` (query kept) without a token header and wakes the workspace like any request.
+ */
+export interface PortCallbackUrl {
+    /** `https://<port>-<handle>.<domain>/__shardflux/callback/sfcb_…/`. Shown once: the API keeps only its hash. */
+    url: string;
+    /** RFC 3339. */
+    createdAt: string;
+}
+export interface PortTokenOptions {
+    /** Lifetime in seconds: 60-86400 (default 3600). */
+    ttlSeconds?: number;
+}
+export interface PortLinkOptions {
+    /** 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 `/`). */
+    path?: string;
+}
+export declare function exposedPortOf(view: PortView): ExposedPort;
+/**
+ * The exposed ports of one workspace (`workspace.ports`, `cloud.workspaces.ports(id)`). Errors are ShardfluxApiError:
+ * 403 `forbidden` reason `inbound_ports_not_available` (inbound ports are not enabled for the organization), 404
+ * `not_found` reason `port_not_exposed` (tokens, links and callback URLs of a port that is not exposed), 409 `conflict`
+ * reason `port_limit` (at most 10 exposed ports, `details.limit`) or `workspace_deleted`, NotSupportedForModeError for a
+ * file-first workspace, 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+ */
+export declare class WorkspacePorts {
+    #private;
+    constructor(ctx: ClientContext, workspaceId: string);
+    /**
+     * Exposes TCP `port` at its own HTTPS URL (idempotent: a port already exposed is returned unchanged, `created`
+     * false, and its tokens, links and callback URL stay valid). The server inside the workspace must listen on
+     * 0.0.0.0 (all interfaces), not only on 127.0.0.1.
+     */
+    expose(port: number): Promise<ExposePortResult>;
+    /** The exposed ports, ordered by port. */
+    list(): Promise<ExposedPort[]>;
+    /**
+     * Closes the port (idempotent: also when it is not exposed). Its tokens, links and callback URL stop working at once,
+     * and stay revoked if the port is exposed again.
+     */
+    close(port: number): Promise<void>;
+    /** Mints a port token for an exposed port (`use` bearer): `Authorization: Bearer <token>` on requests to `url`. */
+    token(port: number, opts?: PortTokenOptions): Promise<PortToken>;
+    /** 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. */
+    link(port: number, opts?: PortLinkOptions): Promise<PortLink>;
+    /** Creates the port's callback URL, or replaces it (the previous one stops working). Its secret is shown only here. */
+    createCallbackUrl(port: number): Promise<PortCallbackUrl>;
+    /** Revokes the port's callback URL (idempotent while the port is exposed). */
+    revokeCallbackUrl(port: number): Promise<void>;
+}
+export {};

package/dist/ports.js

@@ -0,0 +1,62 @@
+export function exposedPortOf(view) {
+    return { port: view.port, url: view.url, createdAt: view.created_at, callback: view.callback ? { createdAt: view.callback.created_at } : null };
+}
+/**
+ * The exposed ports of one workspace (`workspace.ports`, `cloud.workspaces.ports(id)`). Errors are ShardfluxApiError:
+ * 403 `forbidden` reason `inbound_ports_not_available` (inbound ports are not enabled for the organization), 404
+ * `not_found` reason `port_not_exposed` (tokens, links and callback URLs of a port that is not exposed), 409 `conflict`
+ * reason `port_limit` (at most 10 exposed ports, `details.limit`) or `workspace_deleted`, NotSupportedForModeError for a
+ * file-first workspace, 422 `validation_failed` for a port outside 1-65535 or an option out of range.
+ */
+export class WorkspacePorts {
+    #ctx;
+    #workspaceId;
+    constructor(ctx, workspaceId) {
+        this.#ctx = ctx;
+        this.#workspaceId = workspaceId;
+    }
+    #path(port, rest = '') {
+        const base = `/v1/workspaces/${encodeURIComponent(this.#workspaceId)}/ports`;
+        return port === undefined ? base : `${base}/${encodeURIComponent(String(port))}${rest}`;
+    }
+    /**
+     * Exposes TCP `port` at its own HTTPS URL (idempotent: a port already exposed is returned unchanged, `created`
+     * false, and its tokens, links and callback URL stay valid). The server inside the workspace must listen on
+     * 0.0.0.0 (all interfaces), not only on 127.0.0.1.
+     */
+    async expose(port) {
+        const r = await this.#ctx.http.jsonWithStatus('PUT', this.#path(port), { idempotent: true }, this.#ctx.authorization);
+        return { ...exposedPortOf(r.body), created: r.status === 201 };
+    }
+    /** The exposed ports, ordered by port. */
+    async list() {
+        const body = await this.#ctx.http.json('GET', this.#path(), {}, this.#ctx.authorization);
+        return body.ports.map(exposedPortOf);
+    }
+    /**
+     * Closes the port (idempotent: also when it is not exposed). Its tokens, links and callback URL stop working at once,
+     * and stay revoked if the port is exposed again.
+     */
+    async close(port) {
+        await this.#ctx.http.json('DELETE', this.#path(port), { idempotent: true }, this.#ctx.authorization);
+    }
+    /** Mints a port token for an exposed port (`use` bearer): `Authorization: Bearer <token>` on requests to `url`. */
+    async token(port, opts = {}) {
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/tokens'), { json: opts.ttlSeconds !== undefined ? { ttl_seconds: opts.ttlSeconds } : {} }, this.#ctx.authorization);
+        return { token: body.token, expiresAt: body.expires_at, url: body.url };
+    }
+    /** 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);
+        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. */
+    async createCallbackUrl(port) {
+        const body = await this.#ctx.http.json('POST', this.#path(port, '/callback'), {}, this.#ctx.authorization);
+        return { url: body.url, createdAt: body.created_at };
+    }
+    /** Revokes the port's callback URL (idempotent while the port is exposed). */
+    async revokeCallbackUrl(port) {
+        await this.#ctx.http.json('DELETE', this.#path(port, '/callback'), { idempotent: true }, this.#ctx.authorization);
+    }
+}