@shardflux/sdk 0.14.0 → 0.15.0

package/dist/tools.js

@@ -82,6 +82,8 @@ 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'];
@@ -97,6 +99,45 @@ 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) {
@@ -245,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 } : {}),
@@ -297,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,
@@ -343,7 +384,7 @@ export function workspaceTools(workspace, opts = {}) {
                     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 } : {}),
@@ -359,7 +400,7 @@ 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 } : {}),
@@ -411,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))
@@ -461,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 };
                     },
                 },
@@ -472,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,
                 });
@@ -491,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 };
             },
         },
@@ -501,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 };
             },
         },
@@ -520,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 } : {}),
@@ -566,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.
@@ -582,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 })) };
             },
         },
@@ -592,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 };
             },
         },
@@ -602,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 } : {}),
@@ -616,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 };
             },
         },
@@ -626,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,
@@ -640,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 };
             },
         },
@@ -650,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 } : {}),
@@ -664,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',
@@ -672,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 } : {}),
@@ -696,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 };
             },

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 {};

package/dist/workspace-ref.js

@@ -0,0 +1,149 @@
+import { CAPTURE_BARRIER } from "./cell.js";
+import { ShardfluxApiError, isWorkspaceGone } from "./errors.js";
+import { workspaceTools } from "./tools.js";
+const FILE_METHODS = ['read', 'readText', 'readWithInfo', 'write', 'list', 'stat', 'remove', 'mkdir', 'move', 'search', 'patch'];
+/**
+ * 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 class WorkspaceRef {
+    key;
+    #api;
+    #params;
+    #grants;
+    #workspace = null;
+    #opening = null;
+    /** Internal: use `cloud.workspace(key, params)` or the module-level `workspace(key, params)`. */
+    constructor(api, key, params, grants) {
+        if (typeof key !== 'string' || key.length === 0)
+            throw new TypeError('workspace(key, params): key must be a non-empty string');
+        if (params.create !== false && (typeof params.template !== 'string' || params.template.length === 0)) {
+            throw new TypeError(`workspace("${key}", params): params.template is required (a template slug, e.g. "default")`);
+        }
+        this.key = key;
+        this.#api = api;
+        this.#params = params;
+        this.#grants = grants;
+    }
+    /**
+     * 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() {
+        if (!this.#workspace)
+            return undefined;
+        if (this.#params.create === false)
+            return false;
+        return this.#workspace.created ?? undefined;
+    }
+    /** The opened workspace's mode, else the params' (`processful` when neither says). */
+    get mode() {
+        return this.#workspace?.mode ?? this.#params.mode ?? 'processful';
+    }
+    /** Tools granted by the opened workspace's last token; null before the open. */
+    get grantedTools() {
+        return this.#workspace?.grantedTools ?? null;
+    }
+    /** The workspace: opened (or, with `create: false`, found) on the first call and kept. */
+    open() {
+        if (this.#workspace)
+            return Promise.resolve(this.#workspace);
+        this.#opening ??= this.#open().then((ws) => {
+            this.#workspace = ws;
+            this.#opening = null;
+            return ws;
+        }, (err) => {
+            this.#opening = null;
+            throw err;
+        });
+        return this.#opening;
+    }
+    async #open() {
+        const params = this.#params;
+        // open() sends only the open's own parameters (`create` is the ref's).
+        if (params.create !== false)
+            return this.#api.open({ ...params, key: this.key });
+        const found = await this.#api.findByKey(this.key, {
+            includeDeleted: false,
+            ...(params.projectId !== undefined ? { projectId: params.projectId } : {}),
+            ...(params.agentLabel !== undefined ? { agentLabel: params.agentLabel } : {}),
+            ...(params.tools !== undefined ? { tools: params.tools } : {}),
+        });
+        if (found)
+            return found;
+        throw new ShardfluxApiError(404, { error: { code: 'not_found', message: `No workspace with key "${this.key}" in this project (create: false).`, request_id: '', retryable: false, details: { key: this.key } } }, 'api');
+    }
+    /** Runs `fn` on the workspace; a workspace found deleted is forgotten so the next call opens the key again. */
+    async #use(fn) {
+        const ws = await this.open();
+        try {
+            return await fn(ws);
+        }
+        catch (err) {
+            if (isWorkspaceGone(err) && this.#workspace === ws)
+                this.#workspace = null;
+            throw err;
+        }
+    }
+    /**
+     * 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, opts = {}) {
+        const argv = typeof command === 'string' ? ['bash', '-lc', command] : [...command];
+        return this.#use((ws) => ws.cell().exec.run(argv, opts));
+    }
+    /** The workspace's files, as on `cell().files`. */
+    files = Object.fromEntries(FILE_METHODS.map((name) => [
+        name,
+        (...args) => this.#use((ws) => ws.cell().files[name](...args)),
+    ]));
+    /** A file-first workspace's executions (`run`, `get`), as on `Workspace.executions`. */
+    executions = {
+        run: (argv, opts = {}) => this.#use((ws) => ws.executions.run(argv, opts)),
+        get: (executionId, opts = {}) => this.#use((ws) => ws.executions.get(executionId, opts)),
+    };
+    /** The workspace's cell client (`Workspace.cell()`), opening the key first if needed. */
+    async cell(opts = {}) {
+        return (await this.open()).cell(opts);
+    }
+    /**
+     * 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()`.
+     */
+    async hint(opts = {}) {
+        if (this.#workspace)
+            return this.#workspace.hint(opts);
+        if (opts.wake === null)
+            return { residency: null, wake: null };
+        const wake = this.open().then(() => true);
+        wake.catch(() => undefined); // a failed open is left to the next call, which opens again
+        return { residency: null, wake };
+    }
+    /**
+     * 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.
+     */
+    async tools(opts = {}) {
+        // create: false finds the workspace now (a lookup, no VM start), so the tools match its mode.
+        if (this.#params.create === false)
+            await this.open();
+        let tools = opts.tools ?? this.grantedTools ?? undefined;
+        if (tools === undefined) {
+            const granted = await this.#grants();
+            if (granted) {
+                const computer = this.#workspace ? this.#workspace.computerUse.enabled : this.#params.computerUse === true;
+                tools = granted.filter((t) => t !== 'computer' || computer);
+            }
+        }
+        return workspaceTools(this, { ...opts, ...(tools !== undefined ? { tools } : {}) });
+    }
+    /** Internal: tool-call capture's read-your-writes barrier, once the workspace is open. */
+    [CAPTURE_BARRIER]() {
+        return this.#workspace?.[CAPTURE_BARRIER]();
+    }
+}

package/dist/workspace.d.ts

@@ -2,7 +2,7 @@
  * A workspace handle: the latest view from the application API plus managed
  * tool tokens and cell clients (one per agent label / tool set).
  */
-import type { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, ResizeParams, ResizeResult, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { AllocationMode, ComputerUse, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, ResizeParams, ResizeResult, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceMemory, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CAPTURE_BARRIER, CellClient } from './cell.js';
 import { ToolCallCapture } from './capture.js';
 import type { ToolCallCaptureOptions } from './capture.js';
@@ -10,6 +10,7 @@ import type { WorkspaceMode } from './errors.js';
 import type { FinishedOperation, ForkOptions, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedForkOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.js';
 import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
+import { WorkspaceComputer } from './computer.js';
 import { WorkspacePorts } from './ports.js';
 import { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
@@ -57,11 +58,18 @@ export interface HintResult {
 }
 export declare class Workspace {
     #private;
+    /**
+     * Whether the open() that returned this handle created the workspace (0.15.0+, contracts §46.2): true for a new key
+     * (or a key whose session ended), false when it reconnected to or resumed an existing workspace. Null for handles
+     * from get(), list() and findByKey(), and from an API that does not report it.
+     */
+    readonly created: boolean | null;
     constructor(ctx: ClientContext, view: WorkspaceView, opts?: {
         agentLabel?: string | undefined;
         tools?: ToolName[] | undefined;
         token?: ToolToken | null;
         trace?: Trace;
+        created?: boolean | null;
     });
     /**
      * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
@@ -160,6 +168,20 @@ export declare class Workspace {
      *   const link = await workspace.ports.link(3000);            // open link.url in a browser
      */
     get ports(): WorkspacePorts;
+    /**
+     * The workspace desktop (0.15.0+, contracts §45): `act(actions)`, `screenshot()`, `stream()` (a private link to watch
+     * it), `status()`, `start()`, `stop()`. Needs computer use on (`setComputerUse(true)`, or the template's switch); the
+     * platform starts the desktop on the first call that needs it.
+     */
+    get computer(): WorkspaceComputer;
+    /** Computer use (0.15.0+): `enabled` is what tool tokens carry; `workspace` null follows the `template`'s switch. */
+    get computerUse(): ComputerUse;
+    /**
+     * Switches computer use on or off for this workspace (null follows the template). Takes effect on the next tool token:
+     * this handle's cached tokens are dropped. 409 `computer_use_unavailable` when its template version cannot run a
+     * desktop.
+     */
+    setComputerUse(enabled: boolean | null): Promise<this>;
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs(): Promise<Record<string, string>>;
     get labels(): Record<string, string>;

package/dist/workspace.js

@@ -4,6 +4,7 @@ import { NotSupportedForModeError, OperationFailedError, ShardfluxApiError } fro
 import { SERVER_WAIT_MAX_S, defaultSleep, randomId } from "./http.js";
 import { AFTER_WAIT, HELD_RESUME, TRACE } from "./lifecycle.js";
 import { Trace, combineListeners, traced } from "./progress.js";
+import { WorkspaceComputer } from "./computer.js";
 import { WorkspacePorts } from "./ports.js";
 import { WorkspaceSecrets } from "./secrets.js";
 import { ToolTokenManager } from "./tokens.js";
@@ -21,8 +22,15 @@ export class Workspace {
     #lastTiming;
     /** The newest tree revision seen (file-first): the view's, or any cell response's since. */
     #treeRevision;
+    /**
+     * Whether the open() that returned this handle created the workspace (0.15.0+, contracts §46.2): true for a new key
+     * (or a key whose session ended), false when it reconnected to or resumed an existing workspace. Null for handles
+     * from get(), list() and findByKey(), and from an API that does not report it.
+     */
+    created;
     constructor(ctx, view, opts = {}) {
         this.#ctx = ctx;
+        this.created = opts.created ?? null;
         this.#view = view;
         this.#treeRevision = view.mode === 'file_first' && typeof view.tree_revision === 'number' ? view.tree_revision : null;
         this.#defaults = { agentLabel: opts.agentLabel, tools: opts.tools };
@@ -212,6 +220,34 @@ export class Workspace {
     get ports() {
         return new WorkspacePorts(this.#ctx, this.id);
     }
+    /**
+     * The workspace desktop (0.15.0+, contracts §45): `act(actions)`, `screenshot()`, `stream()` (a private link to watch
+     * it), `status()`, `start()`, `stop()`. Needs computer use on (`setComputerUse(true)`, or the template's switch); the
+     * platform starts the desktop on the first call that needs it.
+     */
+    get computer() {
+        return new WorkspaceComputer({
+            cell: () => this.cell(),
+            ports: () => this.ports,
+            setEnabled: (enabled) => this.setComputerUse(enabled).then(() => this.computerUse),
+        });
+    }
+    /** Computer use (0.15.0+): `enabled` is what tool tokens carry; `workspace` null follows the `template`'s switch. */
+    get computerUse() {
+        return this.#view.computer_use;
+    }
+    /**
+     * Switches computer use on or off for this workspace (null follows the template). Takes effect on the next tool token:
+     * this handle's cached tokens are dropped. 409 `computer_use_unavailable` when its template version cannot run a
+     * desktop.
+     */
+    async setComputerUse(enabled) {
+        const cu = await this.#ctx.workspaces.setComputerUse(this.id, enabled);
+        this.#view = { ...this.#view, computer_use: cu };
+        for (const m of this.#managers.values())
+            m.invalidate();
+        return this;
+    }
     /** The workspace's text inputs `{NAME: value}` (0.7.0; secret inputs are bound secrets, never listed here). */
     inputs() {
         return this.#ctx.workspaces.inputs(this.id);