@shardflux/sdk 0.13.1 → 0.14.0

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

@@ -953,6 +953,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[];

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.14.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.14.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

@@ -15,9 +15,9 @@
 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 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 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 +29,8 @@ 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 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,7 +44,7 @@ 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, 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';
@@ -54,7 +56,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,11 @@
 export { BillingApi, Shardflux, WorkspacesApi, fetchBillingCatalog, pickByKey } from "./client.js";
-export { durabilityOf, formatTiming, hostLostOf, isDurable, lostSuspendOf } from "./progress.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";
 export { SecretsApi, WorkspaceSecrets } from "./secrets.js";
 export { EgressPolicyApi } from "./egress.js";
 export { VolumesApi } from "./volumes.js";
@@ -18,6 +19,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);
+    }
+}

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' | 'wake' | 'wait' | 'token';
+export type LifecycleAction = 'open' | 'suspend' | 'resume' | 'snapshot' | 'fork' | 'delete' | 'close' | 'reset' | 'resize' | '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.
@@ -89,8 +89,9 @@ export interface ServerTiming {
     memoryRestored?: boolean | null;
     /**
      * `result.cold_boot_reason` (0.11.0+), with `resumePath` `cold_boot`: why the memory could not be restored:
-     * `runtime_changed` (the platform's VM runtime changed after the suspend) or `host_lost` (0.13.1+: the machine the
-     * workspace ran on failed; it booted from its disk, files kept, see `hostLost`). Null otherwise.
+     * `runtime_changed` (the platform's VM runtime changed after the suspend), `host_lost` (0.13.1+: the machine the
+     * workspace ran on failed; it booted from its disk, files kept, see `hostLost`) or `runtime_retired` (0.14.0+: the
+     * runtime the workspace was suspended on was retired after an announced window). Null otherwise.
      */
     coldBootReason?: ColdBootReason | null;
     /**
@@ -152,11 +153,14 @@ export interface LostSuspend {
     stateAsOf: string | null;
 }
 /**
- * `result.cold_boot_reason` (0.11.0+): `runtime_changed` (the platform's VM runtime changed after the suspend) or
- * `host_lost` (0.13.1+: the machine the workspace ran on failed). Any other string is a reason this version does not
- * know.
+ * `result.cold_boot_reason` (0.11.0+): `runtime_changed` (the platform's VM runtime changed after the suspend),
+ * `host_lost` (0.13.1+: the machine the workspace ran on failed) or `runtime_retired` (0.14.0+: the runtime the
+ * workspace was suspended on was retired after an announced window). Any other string is a reason this version does
+ * not know.
  */
-export type ColdBootReason = 'runtime_changed' | 'host_lost' | (string & {});
+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"];
 /**
  * `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,3 +1,5 @@
+/** Every {@link ColdBootReason} this version knows (0.14.0+). */
+export const COLD_BOOT_REASONS = ['runtime_changed', 'host_lost', 'runtime_retired'];
 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/tools.d.ts

@@ -33,6 +33,8 @@ export interface WorkspaceTool<A extends Record<string, unknown> = Record<string
     };
     /** Which workspace tool permission the call needs (exec, files, pty, process, git, browser). */
     permission: ToolName;
+    /** Opt-in input-start hook (0.14.0+): call when the model starts this tool's input. Returns immediately. */
+    onInputStart?: () => void;
     /** `toolCallId` (0.7.0+): the model's call id, recorded by tool-call capture (executeToolCall passes it). */
     execute(args: A, options?: {
         signal?: AbortSignal;
@@ -74,6 +76,12 @@ export interface WorkspaceToolsOptions {
      * suspended workspace (or restore a hibernated one) that the read does not need.
      */
     hint?: boolean;
+    /**
+     * Add `onInputStart` hooks (0.14.0+) to tools that need the VM. Invoke the matching hook when the model starts
+     * streaming that tool's input, ahead of execute. Default false: no hook, timer or request is installed.
+     * Offline file reads and file-first workspaces have no hook.
+     */
+    prewake?: boolean;
     /**
      * The mode to build the tools for (0.9.0+; default `workspace.mode`). Given, the workspace is not touched until a tool
      * runs, so definitions can be built without one (e.g. to publish them before any workspace exists).

package/dist/tools.js

@@ -87,6 +87,13 @@ const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 const FILE_FIRST_TOOLS = ['exec', 'files'];
 /** Changed paths returned to the model per execution (the rest is flagged `changed_truncated`). */
 const MAX_CHANGED_LISTED = 200;
+/** The processful exec's memory hint (0.14.0; RunOptions.resourceHint). Sent only when the model sets it. */
+const RESOURCE_HINT_SCHEMA = {
+    type: 'string',
+    enum: ['auto', 'light', 'heavy'],
+    description: 'heavy: give this command more memory before it starts (a build, a test suite, a package install, a training run); light: start it at once. Default auto: decided from the command.',
+};
+const RESOURCE_HINTS = new Set(['auto', 'light', 'heavy']);
 /** Tools served from a sleeping workspace's disk without waking it: the runner sends no hint. */
 const DISK_READS = new Set(['read_file', 'list_files', 'search_files']);
 const obj = (properties, required = []) => ({ type: 'object', properties, required, additionalProperties: false });
@@ -267,6 +274,7 @@ export function workspaceTools(workspace, opts = {}) {
             type: 'boolean',
             description: 'Start the command and return its session_id at once instead of waiting for it to exit (default false). Use it for anything that may run longer than a few minutes, such as a build, a test suite, a training run or a server. Keep using the other tools meanwhile, read it with exec_read and stop it with exec_cancel. Set timeout_ms to the longest it may run: the workspace stays awake until the command ends or that time passes (1 hour when unset).',
         },
+        resource_hint: RESOURCE_HINT_SCHEMA,
         ...(opts.burst
             ? {
                 burst: {
@@ -330,6 +338,7 @@ export function workspaceTools(workspace, opts = {}) {
                     const burst = opts.burst && (a.burst === 'always' || a.burst === 'never') ? a.burst : undefined;
                     const burstVcpus = opts.burst && typeof a.burst_vcpus === 'number' ? a.burst_vcpus : undefined;
                     const burstMemoryMib = opts.burst && typeof a.burst_memory_mib === 'number' ? a.burst_memory_mib : undefined;
+                    const resourceHint = RESOURCE_HINTS.has(a.resource_hint) ? a.resource_hint : undefined;
                     const cwd = typeof a.cwd === 'string' ? a.cwd : opts.defaultCwd;
                     if (a.background === true) {
                         // A session of its own: the start answers at once, and exec_read / exec_cancel find it by session_id.
@@ -339,6 +348,7 @@ export function workspaceTools(workspace, opts = {}) {
                             ...(cwd !== undefined ? { cwd } : {}),
                             ...(typeof a.timeout_ms === 'number' ? { timeout_ms: a.timeout_ms } : {}),
                             ...(typeof a.stdin === 'string' ? { stdin: Buffer.from(a.stdin, 'utf8').toString('base64') } : {}),
+                            ...(resourceHint !== undefined ? { resource_hint: resourceHint } : {}),
                             ...(burst !== undefined ? { burst } : {}),
                             ...(burstVcpus !== undefined ? { burst_vcpus: burstVcpus } : {}),
                             ...(burstMemoryMib !== undefined ? { burst_memory_mib: burstMemoryMib } : {}),
@@ -353,6 +363,7 @@ export function workspaceTools(workspace, opts = {}) {
                             ...(cwd !== undefined ? { cwd } : {}),
                             timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
                             ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                            ...(resourceHint !== undefined ? { resourceHint } : {}),
                             ...(burst !== undefined ? { burst } : {}),
                             ...(burstVcpus !== undefined ? { burstVcpus } : {}),
                             ...(burstMemoryMib !== undefined ? { burstMemoryMib } : {}),
@@ -698,6 +709,15 @@ export function workspaceTools(workspace, opts = {}) {
         description: d.description,
         parameters: d.parameters,
         permission: d.permission,
+        ...(opts.prewake === true && !fileFirst && !DISK_READS.has(d.name) ? {
+            onInputStart: () => {
+                workspace.hint({
+                    ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
+                    wake: opts.wake ?? null,
+                    ...(opts.transitionTimeoutMs !== undefined ? { wakeTimeoutMs: opts.transitionTimeoutMs } : {}),
+                }).catch(() => undefined);
+            },
+        } : {}),
         execute: async (args, options = {}) => {
             const issues = validateArgs(d.parameters, args);
             if (issues.length === 0 && d.refuse)

package/dist/workspace.d.ts

@@ -2,7 +2,7 @@
  * A workspace handle: the latest view from the application API plus managed
  * tool tokens and cell clients (one per agent label / tool set).
  */
-import type { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, ResizeParams, ResizeResult, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CAPTURE_BARRIER, CellClient } from './cell.js';
 import { ToolCallCapture } from './capture.js';
 import type { ToolCallCaptureOptions } from './capture.js';
@@ -10,6 +10,7 @@ import type { WorkspaceMode } from './errors.js';
 import type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
+import { WorkspacePorts } from './ports.js';
 import { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
@@ -150,6 +151,15 @@ export declare class Workspace {
     get executions(): CellClient['executions'];
     /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
     get secrets(): WorkspaceSecrets;
+    /**
+     * Inbound ports (0.14.0): serve a TCP port of the workspace at its own private HTTPS URL. A request wakes a parked or
+     * suspended workspace and is served once it runs.
+     *
+     *   const { url } = await workspace.ports.expose(3000);       // the server listens on 0.0.0.0:3000
+     *   const { token } = await workspace.ports.token(3000);      // Authorization: Bearer <token>
+     *   const link = await workspace.ports.link(3000);            // open link.url in a browser
+     */
+    get ports(): WorkspacePorts;
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs(): Promise<Record<string, string>>;
     get labels(): Record<string, string>;
@@ -200,6 +210,21 @@ export declare class Workspace {
      * A suspend the request already started is not undone (it shows as `activeOperation`).
      */
     cancelSuspendWhenIdle(): Promise<this>;
+    /**
+     * Resizes this workspace (0.14.0): memory, the held floor, the allocation mode, CPU and disk, whether it is running or
+     * suspended, fixed or elastic, without a restart or a fork. Memory changes live on a running workspace (a shrink gives
+     * back what the guest frees: `memory.converged`); a suspended one gets its new size when it resumes, before its first
+     * call. CPU changes live up to the vCPUs the workspace booted with, beyond that at its next start. Disks grow online.
+     * The new caps are stored, so every later start uses them. Resolves once the resize has finished, with per resource
+     * when it applies (`now`, `resume` or `next_start` with the `reason`); the handle's view is refreshed. See
+     * WorkspacesApi.resize for the errors. A file-first workspace (no VM to resize) is refused locally with
+     * NotSupportedForModeError.
+     *
+     *   const r = await workspace.resize({ memoryMib: 6144, cpuMillis: 4000 });
+     *   r.memory?.applies_at; // 'now'
+     *   r.cpu?.applies_at;    // 'next_start' (reason 'boot_vcpus': more vCPUs than it booted with)
+     */
+    resize(params: ResizeParams): Promise<ResizeResult>;
     /**
      * Resumes a suspended workspace. Resolves when the resume is REQUESTED; with `{ wait: true }`, once the workspace runs.
      * Tool calls wake a suspended workspace by themselves, so this is rarely needed. With `wait` (0.9.0) it is one held

package/dist/workspace.js

@@ -4,6 +4,7 @@ import { NotSupportedForModeError, OperationFailedError, ShardfluxApiError } fro
 import { SERVER_WAIT_MAX_S, defaultSleep, randomId } from "./http.js";
 import { AFTER_WAIT, HELD_RESUME, TRACE } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
+import { WorkspacePorts } from "./ports.js";
 import { WorkspaceSecrets } from "./secrets.js";
 import { ToolTokenManager } from "./tokens.js";
 const notRunning = (e) => e instanceof ShardfluxApiError && (e.code === 'workspace_not_running' || (e.code === 'conflict' && e.reason === 'workspace_not_running'));
@@ -200,6 +201,17 @@ export class Workspace {
     get secrets() {
         return new WorkspaceSecrets(this.#ctx, this.id);
     }
+    /**
+     * Inbound ports (0.14.0): serve a TCP port of the workspace at its own private HTTPS URL. A request wakes a parked or
+     * suspended workspace and is served once it runs.
+     *
+     *   const { url } = await workspace.ports.expose(3000);       // the server listens on 0.0.0.0:3000
+     *   const { token } = await workspace.ports.token(3000);      // Authorization: Bearer <token>
+     *   const link = await workspace.ports.link(3000);            // open link.url in a browser
+     */
+    get ports() {
+        return new WorkspacePorts(this.#ctx, this.id);
+    }
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs() {
         return this.#ctx.workspaces.inputs(this.id);
@@ -274,6 +286,29 @@ export class Workspace {
         this.#view = (await this.#ctx.workspaces.cancelSuspendWhenIdle(this.id)).data;
         return this;
     }
+    /**
+     * Resizes this workspace (0.14.0): memory, the held floor, the allocation mode, CPU and disk, whether it is running or
+     * suspended, fixed or elastic, without a restart or a fork. Memory changes live on a running workspace (a shrink gives
+     * back what the guest frees: `memory.converged`); a suspended one gets its new size when it resumes, before its first
+     * call. CPU changes live up to the vCPUs the workspace booted with, beyond that at its next start. Disks grow online.
+     * The new caps are stored, so every later start uses them. Resolves once the resize has finished, with per resource
+     * when it applies (`now`, `resume` or `next_start` with the `reason`); the handle's view is refreshed. See
+     * WorkspacesApi.resize for the errors. A file-first workspace (no VM to resize) is refused locally with
+     * NotSupportedForModeError.
+     *
+     *   const r = await workspace.resize({ memoryMib: 6144, cpuMillis: 4000 });
+     *   r.memory?.applies_at; // 'now'
+     *   r.cpu?.applies_at;    // 'next_start' (reason 'boot_vcpus': more vCPUs than it booted with)
+     */
+    async resize(params) {
+        const refusal = this.#needsVm('resize');
+        if (refusal)
+            throw refusal;
+        const out = await this.#ctx.workspaces.resize(this.id, this.#tracked(params));
+        // The resize has happened: a failed view read leaves the old view (the next refresh() reads it again).
+        await this.refresh().catch(() => undefined);
+        return out;
+    }
     resume(opts = {}) {
         const refusal = this.#needsVm('resume');
         if (refusal)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",