@shardflux/sdk 0.13.1 → 0.15.0

package/dist/cell.d.ts

@@ -30,6 +30,12 @@ import type { RequestOptions } from './http.js';
 import type { ProgressListener } from './progress.js';
 import type { ToolTokenManager } from './tokens.js';
 type S = components['schemas'];
+/**
+ * How much memory a command needs at its start (0.14.0; `resource_hint` of an exec start): `heavy` grows an elastic
+ * workspace's memory before the command starts (a build, a test suite, a package install), `light` starts it at once,
+ * `auto` (the default) decides from the command. A fixed workspace has its memory already.
+ */
+export type ResourceHint = NonNullable<S['ExecStartRequest']['resource_hint']>;
 export type ExecStartRequest = S['ExecStartRequest'];
 export type ExecSession = S['ExecSession'];
 /**
@@ -141,6 +147,16 @@ export type GitCommitRequest = S['GitCommitRequest'];
 export type GitResult = S['GitResult'];
 export type GitStatus = S['GitStatus'];
 export type BrowserScreenshotRequest = S['BrowserScreenshotRequest'];
+/** Contracts §45 (0.15.0+): the workspace desktop. */
+export type ComputerAction = S['ComputerAction'];
+export type ComputerActionName = ComputerAction['action'];
+export type ComputerActionsRequest = S['ComputerActionsRequest'];
+export type ComputerActionsResult = S['ComputerActionsResult'];
+export type ComputerActionResult = S['ComputerActionResult'];
+export type ComputerImage = S['ComputerImage'];
+export type ComputerStatus = S['ComputerStatus'];
+export type ComputerStartRequest = S['ComputerStartRequest'];
+export type ComputerStreamInfo = S['ComputerStream'];
 export type BrowserContentRequest = S['BrowserContentRequest'];
 export type BrowserContent = S['BrowserContent'];
 export type Signal = S['SignalValue'];
@@ -293,6 +309,14 @@ export interface RunOptions {
     burstVcpus?: number;
     /** Burst VM memory in MiB (512-65536; default the host's, 8192, or the plan's ceiling when lower). */
     burstMemoryMib?: number;
+    /**
+     * How much memory the command needs at its start (0.14.0; sent as `resource_hint`, omitted when unset): `'heavy'`
+     * grows an elastic workspace's memory before the command starts, so a build, test suite or install sizes its heap and
+     * workers from the memory it gets; `'light'` starts it at once and the workspace grows while it runs; `'auto'` (the
+     * default) decides from the command (package installers, test runners, compilers, type checkers and bundlers are
+     * heavy). A value outside these is ShardfluxApiError 422 `validation_failed` (details.field `resource_hint`).
+     */
+    resourceHint?: ResourceHint;
 }
 /** The API error of a burst's recorded failure (`burst.error` of its session). Internal (the agent tools use it too). */
 export declare function burstFailure(e: BurstError): ShardfluxApiError;
@@ -516,6 +540,21 @@ export declare class CellClient {
         status: (path: string) => Promise<GitStatus>;
         commit: (req: GitCommitRequest) => Promise<GitResult>;
     };
+    readonly computer: {
+        status: () => Promise<ComputerStatus>;
+        start: (req?: ComputerStartRequest) => Promise<ComputerStatus>;
+        stop: () => Promise<void>;
+        /**
+         * Runs a batch of actions in order (the first failure stops it; the rest are reported `skipped`), then a screenshot
+         * when `screenshot` is set. Waits and key holds may take up to 300 s per batch.
+         */
+        act: (req: ComputerActionsRequest, signal?: AbortSignal) => Promise<ComputerActionsResult>;
+        /** Starts the viewer in the guest; expose the returned port and open a link to `path` (Workspace.computer.stream does both). */
+        streamStart: (req?: {
+            interactive?: boolean;
+        }) => Promise<ComputerStreamInfo>;
+        streamStop: () => Promise<void>;
+    };
     readonly browser: {
         screenshot: (req: BrowserScreenshotRequest) => Promise<Uint8Array>;
         content: (req: BrowserContentRequest) => Promise<BrowserContent>;

package/dist/cell.js

@@ -444,6 +444,8 @@ export class CellClient {
                 req.kill_grace_ms = opts.killGraceMs;
             if (opts.secretRefs !== undefined)
                 req.secret_refs = opts.secretRefs;
+            if (opts.resourceHint !== undefined)
+                req.resource_hint = opts.resourceHint;
             if (opts.burst !== undefined)
                 req.burst = opts.burst;
             if (opts.burstVcpus !== undefined)
@@ -1063,6 +1065,75 @@ export class CellClient {
             return this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/git/commit'), { json: req });
         },
     };
+    // ---- computer (contracts §45, 0.15.0+) ---------------------------------------------------------
+    /**
+     * The workspace desktop. The platform starts it on the first call that needs it (actions, start, stream); status
+     * never starts it. Needs the `computer` tool, which tool tokens carry while the workspace's computer use is on.
+     */
+    /**
+     * A computer call with one retry on a fresh token when the cached one lacks the computer tool: computer use may have
+     * been switched on after the token was issued (tokens live up to 15 minutes).
+     */
+    async #computer(call) {
+        try {
+            return await call();
+        }
+        catch (err) {
+            if (!(err instanceof ShardfluxApiError && err.status === 403 && err.details?.tool === 'computer'))
+                throw err;
+            this.tokens.invalidate();
+            return call();
+        }
+    }
+    computer = {
+        status: () => {
+            const refusal = this.#needsVm('computer.status');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('GET', this.#p('/v1/workspaces/{workspace_id}/computer')));
+        },
+        start: (req = {}) => {
+            const refusal = this.#needsVm('computer.start');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer'), { json: req, timeoutMs: 90_000 }));
+        },
+        stop: async () => {
+            const refusal = this.#needsVm('computer.stop');
+            if (refusal)
+                throw refusal;
+            await this.#computer(() => this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/computer')));
+        },
+        /**
+         * Runs a batch of actions in order (the first failure stops it; the rest are reported `skipped`), then a screenshot
+         * when `screenshot` is set. Waits and key holds may take up to 300 s per batch.
+         */
+        act: (req, signal) => {
+            const refusal = this.#needsVm('computer.actions');
+            if (refusal)
+                return Promise.reject(refusal);
+            const waits = req.actions.reduce((sum, a) => sum + (a.duration ?? 0), 0);
+            const typing = req.actions.reduce((sum, a) => sum + (a.action === 'type' ? (a.text?.length ?? 0) : 0), 0);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer/actions'), {
+                json: req,
+                timeoutMs: 120_000 + waits * 1000 + typing * 25,
+                ...(signal ? { signal } : {}),
+            }));
+        },
+        /** Starts the viewer in the guest; expose the returned port and open a link to `path` (Workspace.computer.stream does both). */
+        streamStart: (req = {}) => {
+            const refusal = this.#needsVm('computer.stream');
+            if (refusal)
+                return Promise.reject(refusal);
+            return this.#computer(() => this.#json('POST', this.#p('/v1/workspaces/{workspace_id}/computer/stream'), { json: req, timeoutMs: 90_000 }));
+        },
+        streamStop: async () => {
+            const refusal = this.#needsVm('computer.stream_stop');
+            if (refusal)
+                throw refusal;
+            await this.#computer(() => this.#json('DELETE', this.#p('/v1/workspaces/{workspace_id}/computer/stream')));
+        },
+    };
     // ---- browser ---------------------------------------------------------------------------
     browser = {
         screenshot: (req) => {

package/dist/client.d.ts

@@ -14,8 +14,11 @@ import { HttpClient } from './http.js';
 import type { RequestOptions } from './http.js';
 import type { ToolName, ToolToken } from './tokens.js';
 import { Workspace } from './workspace.js';
+import { WorkspaceRef } from './workspace-ref.js';
+import type { WorkspaceRefParams } from './workspace-ref.js';
 import { AuditApi } from './audit.js';
 import { EgressPolicyApi } from './egress.js';
+import { WorkspacePorts } from './ports.js';
 import { SecretsApi } from './secrets.js';
 import { TemplatesApi } from './templates.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
@@ -27,6 +30,8 @@ import type { ProgressListener } from './progress.js';
 import { CaptureRegistry } from './capture.js';
 import type { FeedbackReceipt, SendFeedbackParams } from './feedback.js';
 export type WorkspaceView = components['schemas']['Workspace'];
+/** Contracts §45.1 (0.15.0+): the workspace's computer use switch. */
+export type ComputerUse = components['schemas']['ComputerUse'];
 export type Operation = components['schemas']['Operation'];
 /** persistent (kept until deleted) or session (discarded when the session ends: close(), idle timeout). */
 export type WorkspaceLifetime = components['schemas']['WorkspaceLifetime'];
@@ -115,9 +120,9 @@ export interface SuspendWhenIdleResult {
     workspace: Workspace;
 }
 export interface ShardfluxOptions {
-    /** Project API key: sfk_<key_id>_<secret>. */
-    apiKey: string;
-    /** Default https://api.shardflux.dev (override with `baseUrl`). */
+    /** Project API key: sfk_<key_id>_<secret>. Default (0.15.0+): the `SHARDFLUX_API_KEY` environment variable. */
+    apiKey?: string;
+    /** Default (0.15.0+): `SHARDFLUX_API_URL`, else https://api.shardflux.dev. */
     baseUrl?: string;
     /** Default: pooled HTTP/1.1 on Node 26+, native fetch on other runtimes (see defaultFetch in http.ts). */
     fetch?: typeof fetch;
@@ -158,8 +163,9 @@ export interface Caps {
     memory_mib?: number;
     disk_gib?: number;
     /**
-     * `fixed` (default) or `elastic` (0.13.0). Given caps replace the stored ones: caps without it make
-     * the workspace fixed again; omitted caps keep the stored layout. Elastic needs the organization's entitlement, else
+     * `fixed` or `elastic` (0.13.0). Omitted: fixed, or elastic where that is the organization's default (a reopen then
+     * keeps the stored mode); the SDK never fills it in. Given caps replace the stored ones; omitted caps keep the stored
+     * layout. `workspace.resize()` (0.14.0+) changes it on a running or suspended workspace. Elastic needs the organization's entitlement, else
      * ShardfluxApiError 422 `validation_failed` reason `allocation_mode_not_available` (nothing is created or changed);
      * a file-first workspace gets `not_supported_for_mode`. A promise that does not exceed the held floor by at least
      * 512 MiB is fixed at the promise (the returned `caps.allocation_mode` says which). Takes effect at the next VM start.
@@ -176,6 +182,64 @@ export interface ForkTarget {
     caps?: Caps;
     lifetime?: WorkspaceLifetime;
 }
+/**
+ * `workspace.resize()` / `workspaces.resize()` (0.14.0): the caps to change. Give at least one; the others keep their
+ * stored values. Each value is bounded by the plan's per-workspace maximum and the template's limit, as caps at open.
+ */
+export interface ResizeParams {
+    /** Memory in MiB: the size of a fixed workspace, the maximum an elastic one may grow to. */
+    memoryMib?: number;
+    /** Elastic only: the memory the workspace holds while idle, in MiB (at most the resulting `memoryMib`). */
+    memoryMibHeld?: number;
+    /** `fixed` or `elastic`: switches the mode, live on a running workspace. */
+    allocationMode?: AllocationMode;
+    /** CPU in millicores (1000 = one vCPU). */
+    cpuMillis?: number;
+    /** Disk in GiB; disks grow only. */
+    diskGib?: number;
+    /** Replays the stored response for a repeated request (default: a fresh key per call, so transport retries replay). */
+    idempotencyKey?: string;
+    /** Give up waiting for the resize after this long (default 300 000 ms); it continues server side. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Progress of the resize (the held request, the operation's states, retries, `done` with the timing). */
+    onProgress?: ProgressListener;
+}
+/** The held answer of `PATCH /v1/workspaces/{id}/caps` (and a finished resize operation's `result`). */
+export type ResizeResponse = components['schemas']['ResizeResult'];
+/** The memory part of a resize result (0.14.0). `*_mib` are MiB; `applied_mib` is what is live after the call (null when no VM runs), `held_mib` the elastic floor, `converged` whether a live change reached its target. */
+export type ResizeMemory = NonNullable<ResizeResponse['memory']>;
+/** The CPU part of a resize result (0.14.0), in millicores. */
+export type ResizeCpu = NonNullable<ResizeResponse['cpu']>;
+/** The disk part of a resize result (0.14.0), in GiB. */
+export type ResizeDisk = NonNullable<ResizeResponse['disk']>;
+/** When a resized resource takes effect (0.14.0): `now`, when the suspended workspace resumes, or at its next start. */
+export type ResizeAppliesAt = ResizeMemory['applies_at'];
+/** Why less than requested applied: clamped to the plan or template bound, the host had no room, or the guest kept memory it uses. */
+export type ResizeLimitReason = NonNullable<ResizeMemory['limit_reason']>;
+/**
+ * Why a resource applies later than now: `suspended` (at resume), `stopped` (at the next start), `boot_vcpus` (more CPU
+ * than the vCPUs the workspace booted with), `region` / `below_base` / `legacy_layout` (a memory size its running VM was
+ * not booted for).
+ */
+export type ResizeDeferReason = NonNullable<ResizeMemory['reason']>;
+/**
+ * What a resize did (0.14.0), per resource the request named (the others are null): when it applies (`applies_at`),
+ * what was asked, the bounded target, the size before, what is live now, and why less or later.
+ */
+export interface ResizeResult {
+    workspaceId: string;
+    operationId: string | null;
+    /** The workspace's state the result describes: `running`, `suspended` or `stopped`. */
+    state: string;
+    memory: ResizeMemory | null;
+    cpu: ResizeCpu | null;
+    disk: ResizeDisk | null;
+    /** The workspace's stored caps after the change: every later start uses them. */
+    caps: ResizeResponse['caps'] | null;
+    /** The finished `resize` operation when the API answered before it was done (202), else null. */
+    operation: Operation | null;
+}
 export interface WaitOptions {
     /**
      * Give up waiting after this long (default 300 000 ms); the operation continues server side. A queued start
@@ -200,6 +264,12 @@ export interface OpenParams {
     /** Searchable metadata; supplied labels replace the existing map. */
     labels?: Record<string, string>;
     idlePolicy?: IdlePolicy;
+    /**
+     * Computer use (0.15.0+, contracts §45.1): true or false sets the workspace's own switch, null follows the template;
+     * omitted leaves it unchanged. While it is on, tool tokens carry the `computer` tool and `workspace.computer` drives
+     * the workspace desktop. 409 `computer_use_unavailable` when the template version cannot run a desktop.
+     */
+    computerUse?: boolean | null;
     key: string;
     template: string;
     caps?: Caps;
@@ -338,9 +408,13 @@ export declare class WorkspacesApi {
         agentLabel?: string;
         tools?: ToolName[];
     }): Promise<Workspace>;
+    /** The exposed ports of a workspace by id (0.14.0; the same as `workspace.ports` without reading the workspace first). */
+    ports(workspaceId: string): WorkspacePorts;
     /** Replace labels. An empty map clears them. */
     setLabels(workspaceId: string, labels: Record<string, string>): Promise<Workspace>;
     /** null clears the override, restoring the template or platform policy. */
+    /** Computer use (0.15.0+): the workspace's own switch; null follows the template. Returns the switch. */
+    setComputerUse(workspaceId: string, enabled: boolean | null): Promise<ComputerUse>;
     setIdlePolicy(workspaceId: string, idlePolicy: IdlePolicy | null): Promise<Workspace>;
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
@@ -412,6 +486,28 @@ export declare class WorkspacesApi {
      * is not undone: it is the workspace's `activeOperation` (resume or open the workspace instead).
      */
     cancelSuspendWhenIdle(workspaceId: string): Promise<Workspace>;
+    /**
+     * Resizes a workspace (0.14.0; `PATCH /v1/workspaces/{id}/caps`): any of memory, the held floor, the allocation mode,
+     * CPU and disk, of a running, suspended or stopped workspace, fixed or elastic, without a restart or a fork. The new
+     * caps are stored, so every later start uses them. Resolves once the resize has finished, with what applied per
+     * resource: `now` (live), `resume` (a suspended workspace gets it when it resumes, before its first call) or
+     * `next_start` (with the `reason`). The request is held by the server while the resize runs; a resize still running
+     * after the hold is waited for like any operation.
+     *
+     * A resize that meets another lifecycle operation (409 `operation_in_progress`: a suspend, a resume, another resize)
+     * waits for it and is sent again, within `timeoutMs`.
+     *
+     * Errors: ShardfluxApiError 409 `conflict` (reason `resize_not_available`, `workspace_deleted`), 422
+     * `validation_failed` (reason `shrink_not_supported` with `details.current_disk_gib`, `requires_elastic`,
+     * `exceeds_memory_mib`, `allocation_mode_not_available`, `not_supported_for_mode`). A resize that fails is its
+     * error: ShardfluxApiError with `operationId` when the server held the request until then, OperationFailedError when
+     * the SDK waited for the operation. OperationTimeoutError after `timeoutMs`. Params without a resource throw
+     * TypeError before any request.
+     *
+     *   const r = await cloud.workspaces.resize(id, { memoryMib: 6144 });
+     *   r.memory?.applies_at; // 'now'
+     */
+    resize(workspaceId: string, params: ResizeParams): Promise<ResizeResult>;
     /**
      * Ends a session workspace now: the workspace is deleted exactly like delete() (ended_reason
      * closed) and returns the `delete` operation (input.reason session_closed); the key then opens a NEW workspace.
@@ -501,7 +597,14 @@ export declare class Shardflux {
     readonly audit: AuditApi;
     /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     readonly volumes: VolumesApi;
-    constructor(opts: ShardfluxOptions);
+    /** Reads `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL` (0.15.0+) for an `apiKey` or `baseUrl` that is not passed. */
+    constructor(opts?: ShardfluxOptions);
+    /**
+     * A workspace named by its key (0.15.0+, contracts §46): no request until its first call, which opens the key
+     * (created on first use with `params.template`, resumed afterwards). `workspace(key, { template: 'default' })
+     * .exec('...')` is a whole integration; see `WorkspaceRef`.
+     */
+    workspace(key: string, params: WorkspaceRefParams): WorkspaceRef;
     /** The authenticated principal (the API key, its organization and project). */
     me(): Promise<Me>;
     entitlements(organizationId: string): Promise<Entitlements>;
@@ -517,4 +620,10 @@ export declare class Shardflux {
     /** Raw access to any /v1 endpoint with the SDK's authentication and error handling. */
     request<T>(method: string, path: string, init?: Parameters<HttpClient['json']>[2]): Promise<T>;
 }
+/**
+ * A workspace named by its key, on a client from the environment (0.15.0+): `new Shardflux()` reads
+ * `SHARDFLUX_API_KEY` (and `SHARDFLUX_API_URL`) on the first call. `workspace(key, { template: 'default' }).exec('...')`
+ * creates the workspace on first use and resumes it afterwards. Use `cloud.workspace()` for a client of your own.
+ */
+export declare function workspace(key: string, params: WorkspaceRefParams): WorkspaceRef;
 export { ShardfluxApiError };

package/dist/client.js

@@ -1,8 +1,10 @@
 import { DurabilityLostError, OperationFailedError, OperationTimeoutError, ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
 import { HttpClient, SDK_VERSION, SERVER_WAIT_MAX_S, defaultFetch, defaultSleep, pollWithWait, randomId } from "./http.js";
 import { Workspace } from "./workspace.js";
+import { WorkspaceRef } from "./workspace-ref.js";
 import { AuditApi } from "./audit.js";
 import { EgressPolicyApi } from "./egress.js";
+import { WorkspacePorts } from "./ports.js";
 import { SecretsApi } from "./secrets.js";
 import { TemplatesApi, saveAsTemplateBody } from "./templates.js";
 import { UsageApi } from "./usage.js";
@@ -46,6 +48,70 @@ function alreadyRunning(answer) {
         },
     }, 'api');
 }
+/** The `PATCH .../caps` body of a resize: the given caps only, snake_case. Throws TypeError when none is given. */
+function resizeBody(p) {
+    const body = {};
+    if (p.memoryMib !== undefined)
+        body.memory_mib = p.memoryMib;
+    if (p.memoryMibHeld !== undefined)
+        body.memory_mib_held = p.memoryMibHeld;
+    if (p.allocationMode !== undefined)
+        body.allocation_mode = p.allocationMode;
+    if (p.cpuMillis !== undefined)
+        body.cpu_millis = p.cpuMillis;
+    if (p.diskGib !== undefined)
+        body.disk_gib = p.diskGib;
+    if (Object.keys(body).length === 0)
+        throw new TypeError('resize() needs at least one of memoryMib, memoryMibHeld, allocationMode, cpuMillis, diskGib');
+    return body;
+}
+const RESIZE_KEYS = {
+    memory: ['applies_at', 'allocation_mode', 'requested_mib', 'target_mib', 'previous_mib', 'applied_mib', 'held_mib', 'converged', 'limit_reason', 'reason'],
+    cpu: ['applies_at', 'requested_millis', 'target_millis', 'previous_millis', 'applied_millis', 'limit_reason', 'reason'],
+    disk: ['applies_at', 'requested_gib', 'target_gib', 'previous_gib', 'applied_gib', 'limit_reason', 'reason'],
+};
+const record = (v) => (v !== null && typeof v === 'object' && !Array.isArray(v) ? v : {});
+/**
+ * A finished resize operation's `result` in the held answer's shape (as the API builds its 200): each resource the
+ * cell reported with its documented keys, a key the cell left out taken from the operation's input (target, requested)
+ * or null; the cell's other keys (timings, the previous values of a retried attempt) are left out.
+ */
+function resizeResultBodyOf(op) {
+    const result = record(op.result);
+    const input = record(op.input);
+    const target = record(input.target);
+    const requested = record(input.requested);
+    const fallback = {
+        memory: { allocation_mode: target.allocation_mode, requested_mib: requested.memory_mib, target_mib: target.memory_mib, held_mib: target.memory_mib_held },
+        cpu: { requested_millis: requested.cpu_millis, target_millis: target.cpu_millis },
+        disk: { requested_gib: requested.disk_gib, target_gib: target.disk_gib },
+    };
+    const out = { workspace_id: result.workspace_id ?? op.workspace_id, operation_id: op.id, state: result.state };
+    for (const [name, keys] of Object.entries(RESIZE_KEYS)) {
+        if (result[name] === null || typeof result[name] !== 'object')
+            continue;
+        const r = record(result[name]);
+        out[name] = Object.fromEntries(keys.map((k) => [k, r[k] ?? fallback[name]?.[k] ?? null]));
+    }
+    return out;
+}
+/** A resize result body (the held 200, or a finished operation's `result`) as ResizeResult. */
+function resizeResultOf(body, status, operation, workspaceId) {
+    if (!body || typeof body !== 'object' || !['memory', 'cpu', 'disk'].some((k) => body[k] && typeof body[k] === 'object')) {
+        throw new ShardfluxProtocolError('resize: the result names no resource (memory, cpu or disk)', status, 'api');
+    }
+    const part = (k) => (body[k] && typeof body[k] === 'object' ? body[k] : null);
+    return {
+        workspaceId: typeof body.workspace_id === 'string' ? body.workspace_id : workspaceId,
+        operationId: typeof body.operation_id === 'string' ? body.operation_id : (operation?.id ?? null),
+        state: typeof body.state === 'string' ? body.state : 'unknown',
+        memory: part('memory'),
+        cpu: part('cpu'),
+        disk: part('disk'),
+        caps: body.caps && typeof body.caps === 'object' ? body.caps : null,
+        operation,
+    };
+}
 /** Races the injected sleep against the signal (the injected sleep itself may not be abortable). */
 function abortableSleep(sleep, ms, signal) {
     if (signal.aborted)
@@ -100,6 +166,8 @@ export class WorkspacesApi {
             body.labels = params.labels;
         if (params.idlePolicy !== undefined)
             body.idle_policy = params.idlePolicy;
+        if (params.computerUse !== undefined)
+            body.computer_use = params.computerUse;
         if (params.lifetime !== undefined)
             body.lifetime = params.lifetime;
         if (params.mode !== undefined)
@@ -128,7 +196,9 @@ export class WorkspacesApi {
             if (res.body.operation)
                 trace.observe(res.body.operation);
             this.#noteToken(res.body.tool_token);
-            const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token, trace };
+            // An API before contracts §46.2 does not say whether the open created the workspace.
+            const created = res.body.created ?? null;
+            const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token, trace, created };
             if (res.status === 200 || params.wait === false || res.body.operation === null)
                 return this.#wrap(res.body.workspace, wrapOpts);
             if (TERMINAL.has(res.body.operation.state)) {
@@ -316,11 +386,19 @@ export class WorkspacesApi {
     async get(workspaceId, opts = {}) {
         return this.#wrap(await this.#getView(workspaceId), opts);
     }
+    /** The exposed ports of a workspace by id (0.14.0; the same as `workspace.ports` without reading the workspace first). */
+    ports(workspaceId) {
+        return new WorkspacePorts(this.#ctx(), workspaceId);
+    }
     /** Replace labels. An empty map clears them. */
     async setLabels(workspaceId, labels) {
         return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/labels`, { json: { labels } }, this.#auth));
     }
     /** null clears the override, restoring the template or platform policy. */
+    /** Computer use (0.15.0+): the workspace's own switch; null follows the template. Returns the switch. */
+    async setComputerUse(workspaceId, enabled) {
+        return this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/computer-use`, { json: { enabled } }, this.#auth);
+    }
     async setIdlePolicy(workspaceId, idlePolicy) {
         return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/idle-policy`, { json: { idle_policy: idlePolicy } }, this.#auth));
     }
@@ -514,6 +592,85 @@ export class WorkspacesApi {
     async cancelSuspendWhenIdle(workspaceId) {
         return this.#wrap(await this.#http.json('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend-when-idle`, {}, this.#auth));
     }
+    /**
+     * Resizes a workspace (0.14.0; `PATCH /v1/workspaces/{id}/caps`): any of memory, the held floor, the allocation mode,
+     * CPU and disk, of a running, suspended or stopped workspace, fixed or elastic, without a restart or a fork. The new
+     * caps are stored, so every later start uses them. Resolves once the resize has finished, with what applied per
+     * resource: `now` (live), `resume` (a suspended workspace gets it when it resumes, before its first call) or
+     * `next_start` (with the `reason`). The request is held by the server while the resize runs; a resize still running
+     * after the hold is waited for like any operation.
+     *
+     * A resize that meets another lifecycle operation (409 `operation_in_progress`: a suspend, a resume, another resize)
+     * waits for it and is sent again, within `timeoutMs`.
+     *
+     * Errors: ShardfluxApiError 409 `conflict` (reason `resize_not_available`, `workspace_deleted`), 422
+     * `validation_failed` (reason `shrink_not_supported` with `details.current_disk_gib`, `requires_elastic`,
+     * `exceeds_memory_mib`, `allocation_mode_not_available`, `not_supported_for_mode`). A resize that fails is its
+     * error: ShardfluxApiError with `operationId` when the server held the request until then, OperationFailedError when
+     * the SDK waited for the operation. OperationTimeoutError after `timeoutMs`. Params without a resource throw
+     * TypeError before any request.
+     *
+     *   const r = await cloud.workspaces.resize(id, { memoryMib: 6144 });
+     *   r.memory?.applies_at; // 'now'
+     */
+    async resize(workspaceId, params) {
+        const body = resizeBody(params);
+        const trace = new Trace('resize', combineListeners(this.#ctx().onProgress, params.onProgress), { workspaceId });
+        return traced(trace, async () => {
+            const timeoutMs = params.timeoutMs ?? 300_000;
+            const started = Date.now();
+            const left = () => Math.max(1, timeoutMs - (Date.now() - started));
+            const idempotencyKey = params.idempotencyKey ?? randomId('op-');
+            const path = `/v1/workspaces/${encodeURIComponent(workspaceId)}/caps`;
+            let res;
+            for (let attempt = 0;; attempt += 1) {
+                const waitS = Math.min(SERVER_WAIT_MAX_S, Math.floor((attempt === 0 ? timeoutMs : left()) / 1000));
+                const init = { json: body, idempotencyKey, onRetry: trace.onRetry, ...(params.signal ? { signal: params.signal } : {}) };
+                if (waitS >= 1) {
+                    // Held: the server answers once the resize has finished (200) or the wait elapsed (202).
+                    init.headers = { prefer: `wait=${waitS}` };
+                    init.timeoutMs = Math.max(this.#http.opts.timeoutMs, waitS * 1000 + 10_000);
+                }
+                trace.phase('request', waitS >= 1 ? 'held' : attempt === 0 ? null : 'retry');
+                try {
+                    res = await this.#http.jsonWithStatus('PATCH', path, init, this.#auth);
+                    break;
+                }
+                catch (e) {
+                    // Another lifecycle operation (a suspend, a resume, another resize) holds the workspace: the refused request
+                    // changed nothing, so wait for that operation and send it again (bounded, within timeoutMs).
+                    const active = e instanceof ShardfluxApiError && e.code === 'conflict' && e.reason === 'operation_in_progress' ? (e.operationId ?? e.details?.['active_operation_id']) : undefined;
+                    if (typeof active !== 'string' || attempt >= 3 || Date.now() - started >= timeoutMs)
+                        throw e;
+                    trace.retry({ request: `PATCH ${path}`, attempt: attempt + 1, cause: `conflict operation_in_progress (waits for ${active})`, delayMs: 0 });
+                    try {
+                        await this.waitForOperation(active, { timeoutMs: left(), ...(params.signal ? { signal: params.signal } : {}), [TRACE]: trace });
+                    }
+                    catch (w) {
+                        if (!(w instanceof OperationFailedError))
+                            throw w;
+                    }
+                }
+            }
+            if (res.status !== 202)
+                return resizeResultOf(res.body, res.status, null, workspaceId);
+            const operation = res.body?.operation;
+            if (!operation || typeof operation !== 'object')
+                throw new ShardfluxProtocolError('resize: 202 response has no operation', res.status, 'api');
+            trace.observe(operation);
+            let final = operation;
+            if (operation.state !== 'succeeded') {
+                if (TERMINAL.has(operation.state))
+                    throw new OperationFailedError(operation);
+                const wait = { timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)), ...(params.signal ? { signal: params.signal } : {}), [TRACE]: trace };
+                final = await this.waitForOperation(operation.id, wait);
+            }
+            // The finished operation's result is the cell's: shaped like the held answer, whose caps come from the view.
+            const result = resizeResultBodyOf(final);
+            const view = await trace.span('view', () => this.#getView(workspaceId, trace.onRetry));
+            return resizeResultOf({ ...result, state: result.state ?? view.observed_state, caps: view.caps }, res.status, final, workspaceId);
+        });
+    }
     async close(workspaceId, opts = {}) {
         return (await this.closeWithView(workspaceId, opts)).operation;
     }
@@ -645,8 +802,13 @@ export class Shardflux {
     /** Shared volumes: persistent storage attached to workspaces at a mount path. */
     volumes;
     #ctx;
-    constructor(opts) {
-        if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(opts.apiKey))
+    #toolGrants = new GrantsCache(() => this.me());
+    /** Reads `SHARDFLUX_API_KEY` and `SHARDFLUX_API_URL` (0.15.0+) for an `apiKey` or `baseUrl` that is not passed. */
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? envVar('SHARDFLUX_API_KEY');
+        if (apiKey === undefined)
+            throw new Error('Missing API key: pass apiKey or set SHARDFLUX_API_KEY (a project key, sfk_<key_id>_<secret>)');
+        if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(apiKey))
             throw new Error('apiKey must be a Shardflux project key (sfk_<key_id>_<secret>)');
         const f = opts.fetch ?? defaultFetch();
         const userAgent = opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}`;
@@ -659,10 +821,10 @@ export class Shardflux {
         this.egress = new EgressPolicyApi(() => this.#ctx);
         this.audit = new AuditApi(() => this.#ctx);
         this.volumes = new VolumesApi(() => this.#ctx);
-        const baseUrl = opts.baseUrl ?? 'https://api.shardflux.dev';
+        const baseUrl = opts.baseUrl ?? envVar('SHARDFLUX_API_URL') ?? 'https://api.shardflux.dev';
         this.#ctx = {
             http: new HttpClient({ baseUrl, fetch: f, userAgent, timeoutMs: opts.timeoutMs ?? 30_000, maxRetries: opts.maxRetries ?? 2, source: 'api', sleep, onSuccess: versionCheckHook(opts.versionCheck, baseUrl, f, userAgent) }),
-            authorization: `Bearer ${opts.apiKey}`,
+            authorization: `Bearer ${apiKey}`,
             fetch: f,
             userAgent,
             sleep,
@@ -671,6 +833,14 @@ export class Shardflux {
             captures: new CaptureRegistry(),
         };
     }
+    /**
+     * A workspace named by its key (0.15.0+, contracts §46): no request until its first call, which opens the key
+     * (created on first use with `params.template`, resumed afterwards). `workspace(key, { template: 'default' })
+     * .exec('...')` is a whole integration; see `WorkspaceRef`.
+     */
+    workspace(key, params) {
+        return new WorkspaceRef(this.workspaces, key, params, () => this.#toolGrants.get());
+    }
     /** The authenticated principal (the API key, its organization and project). */
     me() {
         return this.#ctx.http.json('GET', '/v1/me', {}, this.#ctx.authorization);
@@ -694,4 +864,34 @@ export class Shardflux {
         return this.#ctx.http.json(method, path, init, this.#ctx.authorization);
     }
 }
+/** The client of the module-level `workspace()`: created on first use from the environment. */
+let defaultClient = null;
+/**
+ * A workspace named by its key, on a client from the environment (0.15.0+): `new Shardflux()` reads
+ * `SHARDFLUX_API_KEY` (and `SHARDFLUX_API_URL`) on the first call. `workspace(key, { template: 'default' }).exec('...')`
+ * creates the workspace on first use and resumes it afterwards. Use `cloud.workspace()` for a client of your own.
+ */
+export function workspace(key, params) {
+    defaultClient ??= new Shardflux();
+    return defaultClient.workspace(key, params);
+}
+/** An environment variable, trimmed; undefined when unset, empty or outside Node-like runtimes. */
+function envVar(name) {
+    return globalThis.process?.env?.[name]?.trim() || undefined;
+}
+/** The API key's tool permissions (GET /v1/me), read once; a failed read is not kept. Null for a non-key principal. */
+class GrantsCache {
+    #load;
+    #value = null;
+    constructor(load) {
+        this.#load = load;
+    }
+    get() {
+        this.#value ??= this.#load().then((me) => (me.api_key ? [...me.api_key.tool_permissions] : null), (err) => {
+            this.#value = null;
+            throw err;
+        });
+        return this.#value;
+    }
+}
 export { ShardfluxApiError };