@shardflux/sdk 0.13.1 → 0.15.0

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/templates.d.ts

@@ -215,6 +215,8 @@ export interface TemplateSummary {
         memory_mib: number | null;
         idle_policy: string | null;
     };
+    /** Computer use (0.15.0+, contracts §45.1): the template's switch for its workspaces (a workspace may override it). */
+    computer_use: boolean;
     open_version: TemplateVersion | null;
     /** The live draft (organization templates in dev mode), or null. */
     draft: TemplateDraftSummary | null;
@@ -900,6 +902,16 @@ export declare class TemplatesApi {
         includeArchived?: boolean;
         owner?: TemplateOwner;
     }): Promise<TemplateDetail>;
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    setComputerUse(slug: string, enabled: boolean, params?: {
+        organizationId?: string;
+    }): Promise<{
+        enabled: boolean;
+    }>;
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     find(slug: string, params?: {
         organizationId?: string;

package/dist/templates.js

@@ -693,6 +693,15 @@ export class TemplatesApi {
         const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}`;
         return this.#ctx().http.json('GET', path, { query: { include_archived: params.includeArchived, owner: params.owner } }, this.#ctx().authorization);
     }
+    /**
+     * Computer use (0.15.0+, contracts §45.1): switches it on or off for every workspace of one of your organization's
+     * templates (a workspace may override it with setComputerUse). 403 for platform templates (switch a workspace on
+     * instead). Owners and admins (sessions) or API keys of the organization with a tool permission.
+     */
+    async setComputerUse(slug, enabled, params = {}) {
+        const path = params.organizationId === undefined ? `/v1/templates/${enc(slug)}/computer-use` : `/v1/organizations/${enc(params.organizationId)}/templates/${enc(slug)}/computer-use`;
+        return this.#ctx().http.json('PUT', path, { json: { enabled } }, this.#ctx().authorization);
+    }
     /** Like get() but resolves to null on 404 (unknown slug or outside the organization). */
     async find(slug, params = {}) {
         try {

package/dist/tools.d.ts

@@ -1,7 +1,7 @@
-import type { CellClientOptions } from './cell.js';
+import type { CellClient, CellClientOptions } from './cell.js';
 import type { WorkspaceMode } from './errors.js';
 import type { ToolName } from './tokens.js';
-import type { Workspace } from './workspace.js';
+import type { HintOptions, HintResult } from './workspace.js';
 /**
  * The JSON Schema subset of the tool definitions. A type alias rather than an interface (0.8.0+), so a schema is
  * assignable to the providers' open schema types (`{ [key: string]: unknown }`) without a cast, and an object literal
@@ -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;
@@ -46,6 +48,19 @@ export declare class ToolArgumentError extends Error {
 }
 /** Validates the JSON-Schema subset used by the tool definitions. Returns problems (empty = valid). */
 export declare function validateArgs(schema: JsonSchema, value: unknown, path?: string): string[];
+/**
+ * What workspace tools act on: an opened `Workspace`, or a `WorkspaceRef` (0.15.0+) whose first tool call opens the key.
+ * `cell()` may return a promise (a ref opens first); `mode` and `grantedTools` are read when the tools are built.
+ */
+export interface ToolTarget {
+    readonly mode: WorkspaceMode;
+    readonly grantedTools: ToolName[] | null;
+    cell(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    } & CellClientOptions): CellClient | Promise<CellClient>;
+    hint(opts?: HintOptions): Promise<HintResult>;
+}
 export interface WorkspaceToolsOptions {
     /**
      * Tool permissions to expose (default: the tools of the workspace's last token, else all). A file-first workspace
@@ -74,6 +89,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).
@@ -94,7 +115,7 @@ export interface WorkspaceToolsOptions {
     burst?: boolean;
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
-export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];
+export declare function workspaceTools(workspace: ToolTarget, opts?: WorkspaceToolsOptions): WorkspaceTool[];
 /** Anthropic Messages API tool definition; assignable to `Anthropic.Tool` (0.8.0+). */
 export type AnthropicToolDefinition = {
     name: string;

package/dist/tools.js

@@ -82,14 +82,62 @@ export function validateArgs(schema, value, path = '$') {
         issues.push(`${path} must be one of ${schema.enum.join(', ')}`);
     return issues;
 }
+// Without a token yet (no grantedTools) and no opts.tools, every tool but computer: computer is offered only when a
+// token grants it (the workspace's computer use is on) or opts.tools names it.
 const ALL = ['exec', 'files', 'pty', 'process', 'git', 'browser'];
 /** The tool permissions whose tools work on a file-first workspace: files and executions. */
 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 });
+/** One computer toolset action's parameters (the computer tool's and each computer_batch item's). */
+const COMPUTER_ACTION = {
+    action: {
+        type: 'string',
+        enum: ['screenshot', 'zoom', 'left_click', 'right_click', 'middle_click', 'double_click', 'triple_click', 'left_click_drag', 'mouse_move',
+            'left_mouse_down', 'left_mouse_up', 'cursor_position', 'scroll', 'type', 'key', 'hold_key', 'wait'],
+    },
+    coordinate: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 2, maxItems: 2, description: '[x, y]. Required for mouse_move and as the end of left_click_drag; optional for clicks and scroll (default: at the pointer).' },
+    start_coordinate: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 2, maxItems: 2, description: 'left_click_drag: where the drag starts.' },
+    region: { type: 'array', items: { type: 'integer', minimum: 0 }, minItems: 4, maxItems: 4, description: 'zoom: [x0, y0, x1, y1], shown enlarged.' },
+    text: { type: 'string', maxLength: 20_000, description: 'type: the text. key, hold_key: keys such as "Return", "ctrl+s", "alt+Tab" (space-separated for a sequence). Clicks, drag, scroll: modifiers held, e.g. "shift".' },
+    scroll_direction: { type: 'string', enum: ['up', 'down', 'left', 'right'] },
+    scroll_amount: { type: 'integer', minimum: 1, maximum: 100, description: 'scroll: wheel clicks.' },
+    duration: { type: 'number', minimum: 0, maximum: 300, description: 'Seconds: wait, hold_key.' },
+    repeat: { type: 'integer', minimum: 1, maximum: 100, description: 'key: presses (default 1).' },
+};
+/** The screenshot after input actions (0.15.0+). */
+const COMPUTER_LOOK = {
+    screenshot: { type: 'boolean', description: 'Take a screenshot after the input actions (default true); false when you do not need to look.' },
+    settle_ms: { type: 'integer', minimum: 0, maximum: 10_000, description: 'Wait this long before that screenshot when the screen may change (default 250).' },
+    format: { type: 'string', enum: ['png', 'jpeg'], description: 'Image format (default png; jpeg is smaller).' },
+    quality: { type: 'integer', minimum: 1, maximum: 100, description: 'JPEG quality (default 80).' },
+};
+const COMPUTER_ACTION_KEYS = ['coordinate', 'start_coordinate', 'region', 'text', 'scroll_direction', 'scroll_amount', 'duration', 'repeat'];
+function computerAction(a) {
+    const action = { action: a.action };
+    for (const k of COMPUTER_ACTION_KEYS)
+        if (a[k] !== undefined && a[k] !== null)
+            action[k] = a[k];
+    return action;
+}
+function computerImage(a) {
+    return {
+        ...(typeof a.settle_ms === 'number' ? { settle_ms: a.settle_ms } : {}),
+        ...(a.format === 'png' || a.format === 'jpeg' ? { format: a.format } : {}),
+        ...(typeof a.quality === 'number' ? { quality: a.quality } : {}),
+    };
+}
+const imageView = (img) => ({ mime_type: img.format === 'jpeg' ? 'image/jpeg' : 'image/png', width: img.width, height: img.height, data_base64: img.data });
 const path = (description = 'Absolute path inside the workspace, e.g. /home/user/project/main.py') => ({ type: 'string', minLength: 1, maxLength: 4096, description });
 const signal = { type: 'string', description: 'Signal name such as SIGTERM, SIGINT or SIGKILL.', minLength: 2, maxLength: 12 };
 function clip(text, max) {
@@ -238,7 +286,7 @@ async function waitForExit(c, s, waitMs, signal) {
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export function workspaceTools(workspace, opts = {}) {
-    const cell = () => workspace.cell({
+    const cell = async () => workspace.cell({
         ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
         ...(opts.wake !== undefined ? { wake: opts.wake } : {}),
         ...(opts.transitionTimeoutMs !== undefined ? { transitionTimeoutMs: opts.transitionTimeoutMs } : {}),
@@ -267,6 +315,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: {
@@ -289,7 +338,7 @@ export function workspaceTools(workspace, opts = {}) {
                 run: async (a, o) => {
                     const executionId = newExecutionId();
                     opts.onExecution?.(executionId);
-                    const r = await cell().executions.run(['bash', '-lc', String(a.command)], {
+                    const r = await (await cell()).executions.run(['bash', '-lc', String(a.command)], {
                         executionId,
                         ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
                         timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
@@ -330,15 +379,17 @@ 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.
                         // The command runs until it exits or its timeout_ms, if one is set. (Never a burst: refused above.)
-                        const s = await cell().exec.start({
+                        const s = await (await cell()).exec.start({
                             argv: ['bash', '-lc', String(a.command)],
                             ...(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 } : {}),
@@ -349,10 +400,11 @@ export function workspaceTools(workspace, opts = {}) {
                     }
                     let r;
                     try {
-                        r = await cell().exec.run(['bash', '-lc', String(a.command)], {
+                        r = await (await cell()).exec.run(['bash', '-lc', String(a.command)], {
                             ...(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 } : {}),
@@ -400,7 +452,7 @@ export function workspaceTools(workspace, opts = {}) {
                     description: 'Read a command started with exec background: true: its state, exit code and output. Without offsets it returns the end of each stream; pass next_stdout_offset and next_stderr_offset back to read only new output. wait_ms waits up to that long for the command to exit and returns as soon as it does.',
                     parameters: obj({ session_id: sessionId, stdout_offset: { type: 'integer', minimum: 0 }, stderr_offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
                     run: async (a, o) => {
-                        const c = cell();
+                        const c = await cell();
                         const id = String(a.session_id);
                         let s = await c.exec.get(id);
                         if (typeof a.wait_ms === 'number' && a.wait_ms > 0 && running(s))
@@ -450,7 +502,7 @@ export function workspaceTools(workspace, opts = {}) {
                     // The workspace waits 5 s without a grace and at most 60 s.
                     parameters: obj({ session_id: sessionId, grace_ms: { type: 'integer', minimum: 1, maximum: 60_000 } }, ['session_id']),
                     run: async (a) => {
-                        const s = await cell().exec.cancel(String(a.session_id), typeof a.grace_ms === 'number' ? a.grace_ms : undefined);
+                        const s = await (await cell()).exec.cancel(String(a.session_id), typeof a.grace_ms === 'number' ? a.grace_ms : undefined);
                         return { session_id: s.session_id, state: s.state, exit_code: running(s) ? null : (s.exit_code ?? null), canceled: s.canceled ?? false };
                     },
                 },
@@ -461,7 +513,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Read a text file from the workspace (UTF-8). Use offset/length for large files.',
             parameters: obj({ path: path(), offset: { type: 'integer', minimum: 0 }, length: { type: 'integer', minimum: 1, maximum: 10_485_760 } }, ['path']),
             run: async (a) => {
-                const bytes = await cell().files.read(String(a.path), {
+                const bytes = await (await cell()).files.read(String(a.path), {
                     ...(typeof a.offset === 'number' ? { offset: a.offset } : {}),
                     length: typeof a.length === 'number' ? Math.min(a.length, max) : max + 1,
                 });
@@ -480,7 +532,7 @@ export function workspaceTools(workspace, opts = {}) {
                 create_parents: { type: 'boolean', description: 'Create missing parent directories (default true).' },
             }, ['path', 'content']),
             run: async (a) => {
-                const r = await cell().files.write(String(a.path), String(a.content), { append: a.append === true, createParents: a.create_parents !== false });
+                const r = await (await cell()).files.write(String(a.path), String(a.content), { append: a.append === true, createParents: a.create_parents !== false });
                 return { path: r.path, bytes_written: r.bytes_written, sha256: r.sha256, durable: r.durable };
             },
         },
@@ -490,7 +542,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'List a directory in the workspace.',
             parameters: obj({ path: path('Absolute directory path.'), limit: { type: 'integer', minimum: 1, maximum: 10_000 } }, ['path']),
             run: async (a) => {
-                const r = await cell().files.list(String(a.path), typeof a.limit === 'number' ? { limit: a.limit } : { limit: 500 });
+                const r = await (await cell()).files.list(String(a.path), typeof a.limit === 'number' ? { limit: a.limit } : { limit: 500 });
                 return { entries: r.entries.map((e) => ({ name: e.name, path: e.path, type: e.type, size: e.size, modified_at: e.modified_at })), truncated: r.truncated };
             },
         },
@@ -509,7 +561,7 @@ export function workspaceTools(workspace, opts = {}) {
                 context_lines: { type: 'integer', minimum: 0, maximum: 5, description: 'Lines of context to return before and after each match.' },
             }, ['path', 'pattern']),
             run: async (a, o) => {
-                const r = await cell().files.search(String(a.path), String(a.pattern), {
+                const r = await (await cell()).files.search(String(a.path), String(a.pattern), {
                     ...(typeof a.regex === 'boolean' ? { regex: a.regex } : {}),
                     ...(typeof a.case_insensitive === 'boolean' ? { caseInsensitive: a.case_insensitive } : {}),
                     ...(Array.isArray(a.include) ? { include: a.include } : {}),
@@ -555,7 +607,7 @@ export function workspaceTools(workspace, opts = {}) {
                 },
             }, ['path', 'edits']),
             run: async (a, o) => {
-                const c = cell();
+                const c = await cell();
                 const file = String(a.path);
                 // Without a revision from the model, pin the edit to the content current now, so a concurrent change between
                 // this read and the patch is refused (revision_mismatch) instead of edited blindly.
@@ -571,7 +623,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'List processes running in the workspace.',
             parameters: obj({}),
             run: async () => {
-                const r = await cell().processes.list();
+                const r = await (await cell()).processes.list();
                 return { processes: r.data.map((p) => ({ pid: p.pid, ppid: p.ppid, comm: p.comm, cmdline: p.cmdline, state: p.state, rss_bytes: p.rss_bytes })) };
             },
         },
@@ -581,7 +633,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Send a signal to a process in the workspace (e.g. stop a server).',
             parameters: obj({ pid: { type: 'integer', minimum: 2 }, signal }, ['pid', 'signal']),
             run: async (a) => {
-                await cell().processes.signal(Number(a.pid), String(a.signal));
+                await (await cell()).processes.signal(Number(a.pid), String(a.signal));
                 return { signalled: true };
             },
         },
@@ -591,7 +643,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Open an interactive terminal (PTY) in the workspace; returns a session_id for terminal_send/terminal_read.',
             parameters: obj({ command: { type: 'string', maxLength: 10_000, description: 'Program to run (default: login shell).' }, rows: { type: 'integer', minimum: 1, maximum: 1000 }, cols: { type: 'integer', minimum: 1, maximum: 1000 } }),
             run: async (a) => {
-                const s = await cell().pty.open({
+                const s = await (await cell()).pty.open({
                     ...(typeof a.command === 'string' ? { argv: ['bash', '-lc', a.command] } : {}),
                     ...(typeof a.rows === 'number' ? { rows: a.rows } : {}),
                     ...(typeof a.cols === 'number' ? { cols: a.cols } : {}),
@@ -605,7 +657,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Type input into a terminal session (include "\\n" to press Enter).',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, input: { type: 'string', maxLength: 1_000_000 } }, ['session_id', 'input']),
             run: async (a) => {
-                const s = await cell().pty.input(String(a.session_id), String(a.input));
+                const s = await (await cell()).pty.input(String(a.session_id), String(a.input));
                 return { state: s.state, next_offset: s.output_size };
             },
         },
@@ -615,7 +667,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Read terminal output from an offset (returns next_offset to continue). Waits briefly for new output.',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 }, offset: { type: 'integer', minimum: 0 }, wait_ms: { type: 'integer', minimum: 0, maximum: 60_000 } }, ['session_id']),
             run: async (a) => {
-                const r = await cell().pty.read(String(a.session_id), {
+                const r = await (await cell()).pty.read(String(a.session_id), {
                     offset: typeof a.offset === 'number' ? a.offset : 0,
                     timeoutMs: typeof a.wait_ms === 'number' ? Math.max(100, a.wait_ms) : 3_000,
                     maxBytes: max,
@@ -629,7 +681,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Close a terminal session.',
             parameters: obj({ session_id: { type: 'string', minLength: 1, maxLength: 64 } }, ['session_id']),
             run: async (a) => {
-                const s = await cell().pty.close(String(a.session_id));
+                const s = await (await cell()).pty.close(String(a.session_id));
                 return { state: s.state };
             },
         },
@@ -639,7 +691,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Clone a git repository (HTTPS) into the workspace.',
             parameters: obj({ url: { type: 'string', minLength: 9, maxLength: 2048, description: 'https:// remote URL.' }, path: path('Destination directory.'), branch: { type: 'string', maxLength: 255 }, depth: { type: 'integer', minimum: 1 } }, ['url', 'path']),
             run: async (a) => {
-                const r = await cell().git.clone({
+                const r = await (await cell()).git.clone({
                     url: String(a.url),
                     path: String(a.path),
                     ...(typeof a.branch === 'string' ? { branch: a.branch } : {}),
@@ -653,7 +705,7 @@ export function workspaceTools(workspace, opts = {}) {
             permission: 'git',
             description: 'Show the git status of a repository in the workspace.',
             parameters: obj({ path: path('Repository directory.') }, ['path']),
-            run: async (a) => cell().git.status(String(a.path)),
+            run: async (a) => (await cell()).git.status(String(a.path)),
         },
         {
             name: 'git_commit',
@@ -661,17 +713,65 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Stage all changes and commit in a repository in the workspace.',
             parameters: obj({ path: path('Repository directory.'), message: { type: 'string', minLength: 1, maxLength: 65_536 } }, ['path', 'message']),
             run: async (a) => {
-                const r = await cell().git.commit({ path: String(a.path), message: String(a.message), all: true });
+                const r = await (await cell()).git.commit({ path: String(a.path), message: String(a.message), all: true });
                 return { exit_code: r.exit_code, commit: r.commit ?? null, stdout: clip(r.stdout, max).text, stderr: clip(r.stderr, max).text };
             },
         },
+        {
+            name: 'computer',
+            permission: 'computer',
+            description: 'Use the workspace desktop: its screen, mouse and keyboard. One action per call (computer_batch runs several); input actions answer with a screenshot taken after them, screenshot and zoom answer with the image, cursor_position with the pointer. Coordinates are screen pixels from the top-left of the latest screenshot. Start with action "screenshot". Programs started with exec in the background (e.g. "chromium https://example.com &") open on this desktop.',
+            parameters: obj({ ...COMPUTER_ACTION, ...COMPUTER_LOOK }, ['action']),
+            run: async (a, o) => {
+                const look = a.action === 'screenshot' || a.action === 'zoom' || a.action === 'cursor_position';
+                const r = await (await cell()).computer.act({ actions: [computerAction(a)], screenshot: !look && a.screenshot !== false, ...computerImage(a) }, o.signal);
+                const res = r.results[0];
+                const img = res?.image ?? r.screenshot;
+                return {
+                    ok: res?.ok ?? false,
+                    ...(res?.output !== undefined ? { output: res.output } : {}),
+                    ...(res?.error ? { error: res.error.message } : {}),
+                    cursor: r.cursor,
+                    display: r.display,
+                    ...(img ? { screenshot: imageView(img) } : {}),
+                };
+            },
+        },
+        {
+            name: 'computer_batch',
+            permission: 'computer',
+            description: 'Run several actions of the computer tool on the workspace desktop in one call, in order (e.g. click a field, type, press Return). The first failure stops the batch and the rest come back skipped. Answers with each action\'s result (zoom with its image, cursor_position with the pointer) and one screenshot after the last action that ran (screenshot: false skips it).',
+            parameters: obj({
+                actions: { type: 'array', minItems: 1, maxItems: 50, items: obj(COMPUTER_ACTION, ['action']), description: 'Actions with the computer tool\'s parameters, run in order.' },
+                ...COMPUTER_LOOK,
+            }, ['actions']),
+            run: async (a, o) => {
+                const actions = a.actions.map(computerAction);
+                const r = await (await cell()).computer.act({ actions, screenshot: a.screenshot !== false, ...computerImage(a) }, o.signal);
+                return {
+                    ok: r.results.every((x) => x.ok),
+                    results: r.results.map((x) => ({
+                        action: x.action,
+                        ok: x.ok,
+                        ...(x.skipped ? { skipped: true } : {}),
+                        ...(x.output !== undefined ? { output: x.output } : {}),
+                        ...(x.error ? { error: x.error.message } : {}),
+                        took_ms: x.took_ms,
+                        ...(x.image ? { image: imageView(x.image) } : {}),
+                    })),
+                    cursor: r.cursor,
+                    display: r.display,
+                    ...(r.screenshot ? { screenshot: imageView(r.screenshot) } : {}),
+                };
+            },
+        },
         {
             name: 'browser_screenshot',
             permission: 'browser',
             description: 'Open a URL in the workspace’s headless browser and return a PNG screenshot (base64).',
             parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, width: { type: 'integer', minimum: 100, maximum: 3840 }, height: { type: 'integer', minimum: 100, maximum: 2160 } }, ['url']),
             run: async (a) => {
-                const png = await cell().browser.screenshot({
+                const png = await (await cell()).browser.screenshot({
                     url: String(a.url),
                     ...(typeof a.width === 'number' ? { width: a.width } : {}),
                     ...(typeof a.height === 'number' ? { height: a.height } : {}),
@@ -685,7 +785,7 @@ export function workspaceTools(workspace, opts = {}) {
             description: 'Open a URL in the workspace’s headless browser and return the rendered page as text or HTML.',
             parameters: obj({ url: { type: 'string', minLength: 8, maxLength: 8192 }, format: { type: 'string', enum: ['text', 'html'] } }, ['url']),
             run: async (a) => {
-                const r = await cell().browser.content({ url: String(a.url), format: a.format === 'html' ? 'html' : 'text' });
+                const r = await (await cell()).browser.content({ url: String(a.url), format: a.format === 'html' ? 'html' : 'text' });
                 const c = clip(r.content, max);
                 return { url: r.url, format: r.format, content: c.text, truncated: r.truncated || c.truncated };
             },
@@ -698,6 +798,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-ref.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Workspaces by key (0.15.0+, contracts §46). `cloud.workspace(key, { template })` names a workspace without a request.
+ * Its first call opens the key (the workspace is created on first use and resumed afterwards, one held request that
+ * returns it with a tool token), and later calls go straight to the workspace, which wakes on use.
+ */
+import type { CellClient, CellClientOptions, RunOptions, RunResult } from './cell.js';
+import { CAPTURE_BARRIER } from './cell.js';
+import type { OpenParams, WorkspacesApi } from './client.js';
+import type { WorkspaceMode } from './errors.js';
+import type { ExecutionGetOptions, ExecutionResult, ExecutionRunOptions } from './executions.js';
+import type { ToolName } from './tokens.js';
+import type { ToolTarget, WorkspaceTool, WorkspaceToolsOptions } from './tools.js';
+import type { HintOptions, HintResult, Workspace } from './workspace.js';
+/**
+ * `cloud.workspace(key, params)`: the open's parameters without the key. `template` is required, unless `create: false`:
+ * then the first call finds the key's live workspace (a lookup, no VM start) and fails with ShardfluxApiError 404
+ * `not_found` when there is none. Default: the first call opens the key, creating the workspace.
+ */
+export type WorkspaceRefParams = (Omit<OpenParams, 'key'> & {
+    create?: true;
+}) | (Omit<OpenParams, 'key' | 'template'> & {
+    template?: string;
+    create: false;
+});
+type Files = CellClient['files'];
+type FileMethod = 'read' | 'readText' | 'readWithInfo' | 'write' | 'list' | 'stat' | 'remove' | 'mkdir' | 'move' | 'search' | 'patch';
+/** The workspace's files, as on `cell().files`; each call opens the key first if needed. */
+export type WorkspaceRefFiles = Pick<Files, FileMethod>;
+/**
+ * A workspace named by its key. Nothing is requested until the first call: `exec()`, `files`, a tool from `tools()`,
+ * `hint()` or `open()`. Concurrent first calls share one open; a failed open is not kept, so the next call opens again.
+ * A workspace deleted under the ref (409 `workspace_deleted`, `isWorkspaceGone`) fails the call that meets it and is
+ * forgotten: the next call opens the key again (a new workspace, as `open()` would). `open()` returns the full
+ * `Workspace` (suspend, fork, ports, computer, tool-call capture).
+ */
+export declare class WorkspaceRef implements ToolTarget {
+    #private;
+    readonly key: string;
+    /** Internal: use `cloud.workspace(key, params)` or the module-level `workspace(key, params)`. */
+    constructor(api: WorkspacesApi, key: string, params: WorkspaceRefParams, grants: () => Promise<ToolName[] | null>);
+    /**
+     * Whether the open that produced the current workspace created it (contracts §46.2): undefined until the ref has
+     * opened (or when the API does not report it), false for `create: false`.
+     */
+    get created(): boolean | undefined;
+    /** The opened workspace's mode, else the params' (`processful` when neither says). */
+    get mode(): WorkspaceMode;
+    /** Tools granted by the opened workspace's last token; null before the open. */
+    get grantedTools(): ToolName[] | null;
+    /** The workspace: opened (or, with `create: false`, found) on the first call and kept. */
+    open(): Promise<Workspace>;
+    /**
+     * Runs a command and collects its output (`cell().exec.run()`). A string runs through `bash -lc`, so shell syntax
+     * works; an argv array runs without a shell. A file-first workspace runs commands with `executions.run()`.
+     */
+    exec(command: string | readonly string[], opts?: RunOptions): Promise<RunResult>;
+    /** The workspace's files, as on `cell().files`. */
+    readonly files: WorkspaceRefFiles;
+    /** A file-first workspace's executions (`run`, `get`), as on `Workspace.executions`. */
+    readonly executions: {
+        run: (argv: string[], opts?: ExecutionRunOptions) => Promise<ExecutionResult>;
+        get: (executionId: string, opts?: ExecutionGetOptions) => Promise<ExecutionResult>;
+    };
+    /** The workspace's cell client (`Workspace.cell()`), opening the key first if needed. */
+    cell(opts?: {
+        agentLabel?: string;
+        tools?: ToolName[];
+    } & CellClientOptions): Promise<CellClient>;
+    /**
+     * Says a tool call is coming. Before the first open it starts the open in the background (`wake` resolves when the
+     * workspace runs; nothing has to await it), unless `wake: null`; afterwards it is `Workspace.hint()`.
+     */
+    hint(opts?: HintOptions): Promise<HintResult>;
+    /**
+     * Workspace tools for this key (`workspaceTools`), built before any VM exists: the definitions come from the API
+     * key's tool permissions (`GET /v1/me`, read once per client), and `computer` only with `computerUse: true` in the
+     * params or on an opened workspace whose computer use is on. The first tool call opens the key.
+     */
+    tools(opts?: WorkspaceToolsOptions): Promise<WorkspaceTool[]>;
+    /** Internal: tool-call capture's read-your-writes barrier, once the workspace is open. */
+    [CAPTURE_BARRIER](): Promise<void> | undefined;
+}
+export {};