@shardflux/sdk 0.15.0 → 0.16.0

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

@@ -2260,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;

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import type { RetryRecord } from './progress.js';
-export declare const SDK_VERSION = "0.15.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.15.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,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, workspace } 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, 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 { 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';
@@ -32,9 +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 { exitCodePosix } from './exit-code.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 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';
@@ -56,7 +59,7 @@ export type { AnthropicToolDefinition, JsonSchema, OpenAIChatToolDefinition, Ope
 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,5 +1,6 @@
-export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey, workspace } 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";
@@ -8,6 +9,7 @@ export { TemplateFileError, packDirectory, parseTemplateText, readTemplateFile }
 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";
@@ -19,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/testing/index.d.ts

@@ -0,0 +1,62 @@
+/** In-memory transport for the real SDK. Import only from @shardflux/sdk/testing. */
+import { Shardflux } from '../client.js';
+import type { WorkspaceView } from '../client.js';
+import type { ExecStartRequest } from '../cell.js';
+export interface FakeExecResult {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    termSignal?: number;
+    timedOut?: boolean;
+    canceled?: boolean;
+}
+export interface FakeWorkspaceFaults {
+    busy?: boolean;
+    deleted?: boolean;
+    failed?: boolean;
+    legacyLayout?: boolean;
+    computerUnavailable?: boolean;
+    resizeRefusal?: 'shrink_not_supported' | 'resize_not_available' | null;
+    /** A plan clamps the requested size; it does not invent a validation error. */
+    memoryLimitMib?: number;
+}
+export interface FakeShardfluxOptions {
+    /** Explicit command results. null leaves a command running until testing.completeCommand(). */
+    onExec?: (request: ExecStartRequest, workspace: WorkspaceView) => FakeExecResult | null;
+    nowMs?: number;
+    latencyMs?: number;
+    /** Replace the latency wait, e.g. advance a test runner's clock. */
+    sleep?: (ms: number) => Promise<void>;
+    quota?: 'retained_state' | 'concurrent_workspaces' | null;
+    faults?: FakeWorkspaceFaults;
+    templates?: Record<string, {
+        desktop: boolean;
+        memoryMib?: number;
+        cpuMillis?: number;
+        diskGib?: number;
+    }>;
+}
+export declare class FakeUnsupportedError extends Error {
+    constructor(operation: string);
+}
+/** Controls are separate from the customer client surface; inspect() returns a copy. */
+export declare class FakeShardfluxTesting {
+    #private;
+    readonly requests: {
+        method: string;
+        path: string;
+        query: string;
+    }[];
+    quota: FakeShardfluxOptions['quota'];
+    latencyMs: number;
+    constructor(options: FakeShardfluxOptions);
+    inspect(id: string): WorkspaceView;
+    setFaults(id: string, faults: FakeWorkspaceFaults): void;
+    advance(ms: number): void;
+    completeCommand(id: string, sessionId: string, result?: FakeExecResult): void;
+    readonly fetch: typeof fetch;
+}
+/** A real Shardflux client using an isolated in-memory HTTP transport; no request reaches the network. */
+export declare function createFakeShardflux(options?: FakeShardfluxOptions): Shardflux & {
+    testing: FakeShardfluxTesting;
+};