@shardflux/sdk 0.14.0 → 0.16.0

package/dist/cell.js

@@ -1,4 +1,5 @@
 import { ExecStartError, NotSupportedForModeError, ShardfluxApiError, ShardfluxProtocolError, apiError, isErrorBody, isWorkingQuotaRefusal } from "./errors.js";
+import { exitCodePosix } from "./exit-code.js";
 import { EXECUTION_ID, ExecutionResult, newExecutionId } from "./executions.js";
 import { HttpClient, defaultSleep, randomId, treeRevisionOf } from "./http.js";
 import { describeFailure, emitTo } from "./progress.js";
@@ -590,6 +591,7 @@ export class CellClient {
         return {
             sessionId,
             exitCode: session.exit_code ?? null,
+            exitCodePosix: exitCodePosix({ exitCode: session.exit_code ?? null, termSignal: session.term_signal ?? null, timedOut: session.timed_out ?? false, canceled: session.canceled ?? false }),
             termSignal: session.term_signal ?? null,
             timedOut: session.timed_out ?? false,
             canceled: session.canceled ?? false,
@@ -1065,6 +1067,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,6 +14,8 @@ 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';
@@ -28,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'];
@@ -116,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;
@@ -155,7 +159,7 @@ export type AllocationMode = 'fixed' | 'elastic';
 export type WorkspaceMemory = WorkspaceView['memory'];
 export interface Caps {
     cpu_millis?: number;
-    /** Memory in MiB; for an elastic workspace the promise (what it may grow to). */
+    /** Memory in MiB; elastic promise, or fixed size (the template default when omitted). */
     memory_mib?: number;
     disk_gib?: number;
     /**
@@ -193,6 +197,10 @@ export interface ResizeParams {
     cpuMillis?: number;
     /** Disk in GiB; disks grow only. */
     diskGib?: number;
+    /** Only grow each named numeric resource; a smaller or equal value leaves it unchanged. */
+    atLeast?: boolean;
+    /** Wait for completion (default true); false returns the held server answer without operation polling. */
+    wait?: boolean;
     /** 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. */
@@ -256,10 +264,30 @@ export interface WaitOptions {
     onProgress?: ProgressListener;
 }
 export type IdlePolicy = 'adaptive' | 'never' | `fixed:${number}`;
+export interface RetentionPolicy {
+    delete_after_idle_days: number;
+}
+export interface ProjectRetentionPolicy extends RetentionPolicy {
+    labels?: Record<string, string>;
+}
+export declare class ProjectsRetentionApi {
+    #private;
+    constructor(ctx: () => ClientContext);
+    getRetention(projectId: string): Promise<ProjectRetentionPolicy | null>;
+    setRetention(projectId: string, policy: ProjectRetentionPolicy | null): Promise<ProjectRetentionPolicy | null>;
+}
 export interface OpenParams {
+    /** Opt-in idle deletion in days (1..3650), persistent workspaces only. Omitted leaves it unchanged. */
+    retention?: RetentionPolicy;
     /** 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;
@@ -403,6 +431,9 @@ export declare class WorkspacesApi {
     /** 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>;
+    setRetention(workspaceId: string, policy: RetentionPolicy | null): Promise<Workspace>;
     setIdlePolicy(workspaceId: string, idlePolicy: IdlePolicy | null): Promise<Workspace>;
     list(params?: ListParams): Promise<Page<Workspace>>;
     /** Iterates every page. */
@@ -516,6 +547,10 @@ export declare class WorkspacesApi {
      * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
      * for 7 days). Errors: 409 legacy_disk_layout, not_resettable, operation_in_progress.
      */
+    /** Opt-in cold start preserving the disk; next_resume schedules it without stopping the VM. */
+    upgrade(workspaceId: string, opts?: LifecycleOptions & {
+        at?: 'now' | 'next_resume';
+    }): Promise<Operation>;
     reset(workspaceId: string, opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(workspaceId: string, opts?: LifecycleOptions): Promise<Operation>;
     /**
@@ -571,6 +606,7 @@ export declare function fetchBillingCatalog(opts?: {
 }): Promise<BillingCatalog>;
 export declare class Shardflux {
     #private;
+    readonly projects: ProjectsRetentionApi;
     readonly workspaces: WorkspacesApi;
     readonly billing: BillingApi;
     /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */
@@ -585,7 +621,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>;
@@ -601,4 +644,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,6 +1,7 @@
 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";
@@ -13,6 +14,18 @@ import { AFTER_WAIT, HELD_RESUME, TRACE, runLifecycle, waitOptionsOf } from "./l
 import { Trace, combineListeners, durabilityOf, isDurable, traced } from "./progress.js";
 import { CaptureRegistry } from "./capture.js";
 import { sendFeedback } from "./feedback.js";
+export class ProjectsRetentionApi {
+    #ctx;
+    constructor(ctx) { this.#ctx = ctx; }
+    getRetention(projectId) {
+        const c = this.#ctx();
+        return c.http.json('GET', `/v1/projects/${encodeURIComponent(projectId)}/retention`, {}, c.authorization);
+    }
+    setRetention(projectId, policy) {
+        const c = this.#ctx();
+        return c.http.json('PUT', `/v1/projects/${encodeURIComponent(projectId)}/retention`, { json: policy }, c.authorization);
+    }
+}
 /**
  * The workspace a key names: the live row (deleted_at null) when there is one, since at most one live
  * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
@@ -62,6 +75,8 @@ function resizeBody(p) {
         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');
+    if (p.atLeast !== undefined)
+        body.at_least = p.atLeast;
     return body;
 }
 const RESIZE_KEYS = {
@@ -163,8 +178,12 @@ export class WorkspacesApi {
             body.inputs = params.inputs;
         if (params.labels !== undefined)
             body.labels = params.labels;
+        if (params.retention !== undefined)
+            body.retention = params.retention;
         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)
@@ -193,7 +212,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)) {
@@ -390,6 +411,13 @@ export class WorkspacesApi {
         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 setRetention(workspaceId, policy) {
+        return this.#wrap(await this.#http.json('PUT', `/v1/workspaces/${encodeURIComponent(workspaceId)}/retention`, { json: policy }, 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));
     }
@@ -465,7 +493,7 @@ export class WorkspacesApi {
             if (kind === 'delete' || kind === 'reset')
                 this.#ctx().captures.discard(workspaceId, kind);
             return operation;
-        }, opts, { settle: kind === 'suspend' || kind === 'snapshot' });
+        }, opts, { settle: kind === 'suspend' || kind === 'snapshot' || kind === 'upgrade' });
     }
     delete(workspaceId, opts = {}) {
         return this.#op('delete', workspaceId, undefined, opts);
@@ -631,7 +659,7 @@ export class WorkspacesApi {
                     // 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)
+                    if (params.wait === false || 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 {
@@ -649,6 +677,15 @@ export class WorkspacesApi {
             if (!operation || typeof operation !== 'object')
                 throw new ShardfluxProtocolError('resize: 202 response has no operation', res.status, 'api');
             trace.observe(operation);
+            if (params.wait === false) {
+                if (operation.state === 'failed' || operation.state === 'canceled')
+                    throw new OperationFailedError(operation);
+                const workspace = res.body.workspace;
+                const result = resizeResultBodyOf(operation);
+                return { workspaceId, operationId: operation.id, state: workspace?.observed_state ?? operation.state,
+                    memory: result.memory ?? null, cpu: result.cpu ?? null, disk: result.disk ?? null,
+                    caps: workspace?.caps ?? null, operation };
+            }
             let final = operation;
             if (operation.state !== 'succeeded') {
                 if (TERMINAL.has(operation.state))
@@ -676,6 +713,17 @@ export class WorkspacesApi {
         }, opts, { settle: true });
         return { operation, workspace: workspace };
     }
+    /**
+     * Resets a layered workspace to its template: every change in the workspace layer is wiped; key,
+     * id, template version, caps, secret bindings and volume attachments stay. Running: restarted on a blank layer
+     * (processes are gone; old tool tokens get 409 stale_epoch and the SDK refreshes them). Suspended: stays suspended and
+     * boots blank on the next resume. Returns the `reset` operation; its result names the recovery checkpoint (restorable
+     * for 7 days). Errors: 409 legacy_disk_layout, not_resettable, operation_in_progress.
+     */
+    /** Opt-in cold start preserving the disk; next_resume schedules it without stopping the VM. */
+    upgrade(workspaceId, opts = {}) {
+        return this.#op('upgrade', workspaceId, { at: opts.at ?? 'now' }, opts);
+    }
     reset(workspaceId, opts = {}) {
         const body = { confirm_destructive: true };
         return this.#op('reset', workspaceId, body, opts);
@@ -778,6 +826,7 @@ export async function fetchBillingCatalog(opts = {}) {
     return http.json('GET', '/v1/billing/catalog');
 }
 export class Shardflux {
+    projects;
     workspaces;
     billing;
     /** Usage, allowances, estimates, grants/leases and spend (Phase 9). */
@@ -793,12 +842,18 @@ 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}`;
         const sleep = opts.sleep ?? defaultSleep;
+        this.projects = new ProjectsRetentionApi(() => this.#ctx);
         this.workspaces = new WorkspacesApi(() => this.#ctx);
         this.billing = new BillingApi(() => this.#ctx);
         this.usage = new UsageApi(() => this.#ctx);
@@ -807,10 +862,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') ?? envVar('SHARDFLUX_BASE_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,
@@ -819,6 +874,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);
@@ -842,4 +905,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 };

package/dist/computer.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Computer use (0.15.0+, contracts §45): the workspace desktop, which the platform starts on the first call that needs
+ * it. `workspace.computer` drives it; `computerToolset(workspace)` answers Claude's computer toolset
+ * (`computer_toolset_20260801`) with one batch per model turn.
+ *
+ *   await workspace.setComputerUse(true);                  // or open({ ..., computerUse: true })
+ *   const shot = await workspace.computer.screenshot();     // { format: 'png', width: 1280, height: 800, data }
+ *   await workspace.computer.act([{ action: 'left_click', coordinate: [640, 400] }, { action: 'type', text: 'hello' }]);
+ *   const { url } = await workspace.computer.stream();      // a private link to watch the screen
+ */
+import type { CellClient, ComputerAction, ComputerActionsResult, ComputerImage, ComputerStatus } from './cell.js';
+import type { ComputerUse } from './client.js';
+import type { WorkspacePorts } from './ports.js';
+/** A decoded screen image. */
+export interface ComputerScreenshot {
+    format: 'png' | 'jpeg';
+    width: number;
+    height: number;
+    data: Uint8Array;
+}
+export interface ComputerActOptions {
+    /** Append a screenshot after the last action that ran (also after a failure). */
+    screenshot?: boolean;
+    /** Wait this long before that screenshot when an action changed the screen (default 250). */
+    settleMs?: number;
+    format?: 'png' | 'jpeg';
+    /** JPEG quality 1..100 (default 80). */
+    quality?: number;
+    signal?: AbortSignal;
+}
+export interface ComputerStreamOptions {
+    /** Mint a new link even when a cached link has more than 60 seconds left. */
+    fresh?: boolean;
+    /** Frame the viewer in these HTTPS origins with a partitioned browser session (§48). */
+    embed?: import('./ports.js').PortEmbedOptions;
+    /** Let the viewer use the mouse and keyboard (default false: view only, enforced in the workspace). */
+    interactive?: boolean;
+    /** How long the link works (60..604800 s; default 86400). */
+    ttlSeconds?: number;
+}
+/** A private link to the desktop's viewer: open it in a browser or an iframe. */
+export interface ComputerStream {
+    url: string;
+    expiresAt: string;
+    port: number;
+    interactive: boolean;
+}
+/** Decodes a result image (base64 in the API) to bytes. */
+export declare function decodeComputerImage(img: ComputerImage): ComputerScreenshot;
+interface ComputerDeps {
+    cell: () => CellClient;
+    ports: () => WorkspacePorts;
+    setEnabled: (enabled: boolean | null) => Promise<ComputerUse>;
+}
+/** The workspace desktop (workspace.computer). */
+export declare class WorkspaceComputer {
+    #private;
+    constructor(deps: ComputerDeps);
+    /**
+     * Runs actions in order (the first failure stops the batch; later actions come back `skipped`), optionally ending
+     * with a screenshot. The actions are Claude's computer toolset members with their parameter names.
+     */
+    act(actions: ComputerAction[], opts?: ComputerActOptions): Promise<ComputerActionsResult>;
+    /** The screen now (the pointer drawn in). */
+    screenshot(opts?: Pick<ComputerActOptions, 'format' | 'quality' | 'signal'>): Promise<ComputerScreenshot>;
+    /** Whether the desktop runs, its size and its viewers. Never starts it. */
+    status(): Promise<ComputerStatus>;
+    /** Starts the desktop (a no-op while it runs; the size applies to a start only: 640x480..2560x1600, default 1280x800). */
+    start(size?: {
+        width?: number;
+        height?: number;
+    }): Promise<ComputerStatus>;
+    /** Stops the desktop; its windows close. The next call that needs it starts a fresh one. */
+    stop(): Promise<void>;
+    /**
+     * A private link to watch the desktop (or use it, with `interactive`): starts the viewer in the workspace, exposes
+     * its port and signs a link to the viewer page (inbound ports, contracts §39). Anyone with the link can open it until
+     * it expires; `stopStream()` ends every view.
+     */
+    stream(opts?: ComputerStreamOptions): Promise<ComputerStream>;
+    /** Ends every view and closes the viewer ports (their links stop working). */
+    stopStream(): Promise<void>;
+    /** Switches computer use on or off for this workspace (null follows the template). */
+    setEnabled(enabled: boolean | null): Promise<ComputerUse>;
+}
+/** The `tools` entry of Claude's computer toolset (no name, no display size). */
+export declare const COMPUTER_TOOLSET: {
+    readonly type: "computer_toolset_20260801";
+};
+/** A `tool_use` content block (structurally the Anthropic SDK's, so its blocks pass as they are). */
+export interface ToolUseBlockLike {
+    type: string;
+    id: string;
+    name: string;
+    input: unknown;
+    toolset_name?: string | null;
+}
+type ResultContent = Array<{
+    type: 'text';
+    text: string;
+} | {
+    type: 'image';
+    source: {
+        type: 'base64';
+        media_type: 'image/png' | 'image/jpeg';
+        data: string;
+    };
+}>;
+/** A `tool_result` block answering a toolset call (each echoes `toolset_name: "computer"`, as the API requires). */
+export interface ComputerToolResult {
+    type: 'tool_result';
+    tool_use_id: string;
+    toolset_name: 'computer';
+    content: ResultContent;
+    is_error?: true;
+}
+export interface ComputerToolsetOptions {
+    /** Called just before each action. Return false/a refusal string, or throw, to stop the turn. */
+    beforeAction?: BeforeComputerAction;
+    /** Screenshot format (default png). */
+    format?: 'png' | 'jpeg';
+    quality?: number;
+    settleMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * Answers Claude's computer toolset (`tools: [COMPUTER_TOOLSET]`, Claude Opus 5.5 / Sonnet 5.5 and later on the
+ * Claude API) from this workspace's desktop:
+ *
+ *   const computer = computerToolset(workspace);
+ *   const msg = await anthropic.messages.create({ model, max_tokens, tools: [computer.definition], messages });
+ *   messages.push({ role: 'assistant', content: msg.content });
+ *   messages.push({ role: 'user', content: await computer.run(msg.content) });
+ *
+ * `run` takes the response content, runs every `toolset_name: "computer"` call of the turn as one batch (in order;
+ * the first failure stops it and the rest are answered "Not executed"), and returns one `tool_result` per call:
+ * images for screenshot and zoom, the position for cursor_position, `OK` otherwise. When the batch does not end with a
+ * look, a screenshot is attached to the last result, so the model sees the outcome without another round trip. A
+ * batch the desktop refuses as invalid (a coordinate outside the screen) is answered with the reason on every call.
+ */
+export declare function computerToolset(workspace: {
+    computer: WorkspaceComputer;
+}, defaults?: ComputerToolsetOptions): {
+    definition: {
+        readonly type: "computer_toolset_20260801";
+    };
+    run(content: readonly unknown[], opts?: ComputerToolsetOptions): Promise<ComputerToolResult[]>;
+};
+export type BeforeComputerAction = (action: Readonly<ComputerAction>) => void | boolean | string | Promise<void | boolean | string>;
+type ComputerBatchResult = Partial<ComputerActionsResult> & Pick<ComputerActionsResult, 'results'>;
+/** No hook: one batch as before. With a hook, check immediately before each individual action runs. */
+export declare function runComputerActions(act: (actions: ComputerAction[], opts: ComputerActOptions) => Promise<ComputerActionsResult>, actions: ComputerAction[], opts: ComputerActOptions, beforeAction?: BeforeComputerAction): Promise<ComputerBatchResult>;
+export {};