@shardflux/sdk 0.14.0 → 0.16.0

package/dist/computer.js

@@ -0,0 +1,229 @@
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+/** Decodes a result image (base64 in the API) to bytes. */
+export function decodeComputerImage(img) {
+    return { format: img.format, width: img.width, height: img.height, data: new Uint8Array(Buffer.from(img.data, 'base64')) };
+}
+/** The workspace desktop (workspace.computer). */
+export class WorkspaceComputer {
+    #deps;
+    #streams = new Map();
+    #minting = new Map();
+    #pendingStreams = new Set();
+    #stopping;
+    #streamGeneration = 0;
+    constructor(deps) {
+        this.#deps = deps;
+    }
+    /**
+     * 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, opts = {}) {
+        return this.#deps.cell().computer.act({
+            actions,
+            ...(LOOKS.has(actions.at(-1)?.action ?? '') ? { screenshot: false } : opts.screenshot !== undefined ? { screenshot: opts.screenshot } : {}),
+            ...(opts.settleMs !== undefined ? { settle_ms: opts.settleMs } : {}),
+            ...(opts.format !== undefined ? { format: opts.format } : {}),
+            ...(opts.quality !== undefined ? { quality: opts.quality } : {}),
+        }, opts.signal);
+    }
+    /** The screen now (the pointer drawn in). */
+    async screenshot(opts = {}) {
+        const r = await this.act([], { ...opts, screenshot: true });
+        if (!r.screenshot)
+            throw new ShardfluxProtocolError('POST /computer/actions: the desktop returned no screenshot', 200, 'cell');
+        return decodeComputerImage(r.screenshot);
+    }
+    /** Whether the desktop runs, its size and its viewers. Never starts it. */
+    status() {
+        return this.#deps.cell().computer.status();
+    }
+    /** Starts the desktop (a no-op while it runs; the size applies to a start only: 640x480..2560x1600, default 1280x800). */
+    start(size = {}) {
+        return this.#deps.cell().computer.start(size);
+    }
+    /** Stops the desktop; its windows close. The next call that needs it starts a fresh one. */
+    stop() {
+        return this.#deps.cell().computer.stop();
+    }
+    /**
+     * 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.
+     */
+    async stream(opts = {}) {
+        if (opts.embed !== undefined)
+            opts = { ...opts, embed: structuredClone(opts.embed) };
+        if (this.#stopping)
+            await this.#stopping;
+        const kind = JSON.stringify({ interactive: opts.interactive ?? false, ttlSeconds: opts.ttlSeconds, embed: opts.embed });
+        const cached = this.#streams.get(kind);
+        if (!opts.fresh && cached && Date.parse(cached.expiresAt) - Date.now() > 60_000)
+            return { ...cached };
+        const pending = this.#minting.get(kind);
+        if (!opts.fresh && pending)
+            return { ...await pending };
+        const generation = this.#streamGeneration;
+        const mint = this.#stream(opts).then((link) => {
+            if (generation === this.#streamGeneration && this.#minting.get(kind) === mint)
+                this.#streams.set(kind, link);
+            return link;
+        });
+        this.#minting.set(kind, mint);
+        this.#pendingStreams.add(mint);
+        try {
+            return { ...await mint };
+        }
+        finally {
+            this.#pendingStreams.delete(mint);
+            if (this.#minting.get(kind) === mint)
+                this.#minting.delete(kind);
+        }
+    }
+    async #stream(opts) {
+        const info = await this.#deps.cell().computer.streamStart({ interactive: opts.interactive ?? false });
+        const ports = this.#deps.ports();
+        await ports.expose(info.port);
+        const link = await ports.link(info.port, { ...(opts.embed !== undefined ? { embed: opts.embed } : {}), path: info.path, ...(opts.ttlSeconds !== undefined ? { ttlSeconds: opts.ttlSeconds } : {}) });
+        return { url: link.url, expiresAt: link.expiresAt, port: info.port, interactive: info.interactive };
+    }
+    /** Ends every view and closes the viewer ports (their links stop working). */
+    stopStream() {
+        if (this.#stopping)
+            return this.#stopping;
+        const stop = this.#stopStream();
+        this.#stopping = stop;
+        void stop.finally(() => { if (this.#stopping === stop)
+            this.#stopping = undefined; }).catch(() => undefined);
+        return stop;
+    }
+    async #stopStream() {
+        this.#streamGeneration += 1;
+        this.#streams.clear();
+        const pending = [...this.#pendingStreams];
+        this.#minting.clear();
+        await Promise.allSettled(pending);
+        const ports = this.#deps.ports();
+        await Promise.all([ports.close(61002), ports.close(61003)]);
+        await this.#deps.cell().computer.streamStop();
+    }
+    /** Switches computer use on or off for this workspace (null follows the template). */
+    setEnabled(enabled) {
+        return this.#deps.setEnabled(enabled);
+    }
+}
+// ---- Claude's computer toolset ------------------------------------------------------------------------------------------
+/** The `tools` entry of Claude's computer toolset (no name, no display size). */
+export const COMPUTER_TOOLSET = { type: 'computer_toolset_20260801' };
+/** Parameters the toolset members take; anything else a model sends is not forwarded. */
+const PARAMS = ['coordinate', 'start_coordinate', 'region', 'text', 'scroll_direction', 'scroll_amount', 'duration', 'repeat'];
+const LOOKS = new Set(['screenshot', 'zoom']);
+function imageContent(img) {
+    return { type: 'image', source: { type: 'base64', media_type: img.format === 'jpeg' ? 'image/jpeg' : 'image/png', data: img.data } };
+}
+function actionOf(block) {
+    const input = (block.input !== null && typeof block.input === 'object' ? block.input : {});
+    const a = { action: block.name };
+    for (const k of PARAMS)
+        if (input[k] !== undefined && input[k] !== null)
+            a[k] = input[k];
+    return a;
+}
+/**
+ * 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 function computerToolset(workspace, defaults = {}) {
+    return {
+        definition: COMPUTER_TOOLSET,
+        async run(content, opts = {}) {
+            opts = { ...defaults, ...opts };
+            const calls = content.filter((b) => b !== null && typeof b === 'object' && b.type === 'tool_use' && b.toolset_name === 'computer');
+            if (calls.length === 0)
+                return [];
+            const lastLooks = LOOKS.has(calls[calls.length - 1].name);
+            let r;
+            try {
+                r = await runComputerActions((actions, options) => workspace.computer.act(actions, options), calls.map(actionOf), {
+                    screenshot: !lastLooks,
+                    ...(opts.format !== undefined ? { format: opts.format } : {}),
+                    ...(opts.quality !== undefined ? { quality: opts.quality } : {}),
+                    ...(opts.settleMs !== undefined ? { settleMs: opts.settleMs } : {}),
+                    ...(opts.signal !== undefined ? { signal: opts.signal } : {}),
+                }, opts.beforeAction);
+            }
+            catch (err) {
+                if (err instanceof ShardfluxApiError && err.code === 'validation_failed') {
+                    const at = typeof err.details?.index === 'number' ? err.details.index : -1;
+                    return calls.map((c, i) => ({
+                        type: 'tool_result',
+                        tool_use_id: c.id,
+                        toolset_name: 'computer',
+                        is_error: true,
+                        content: [{ type: 'text', text: i === at || at < 0 ? err.message : 'Not executed: another computer action in this turn was invalid.' }],
+                    }));
+                }
+                throw err;
+            }
+            const out = calls.map((c, i) => {
+                const res = r.results[i];
+                if (!res || res.skipped) {
+                    return { type: 'tool_result', tool_use_id: c.id, toolset_name: 'computer', is_error: true, content: [{ type: 'text', text: 'Not executed: an earlier computer action in this turn failed.' }] };
+                }
+                if (!res.ok) {
+                    return { type: 'tool_result', tool_use_id: c.id, toolset_name: 'computer', is_error: true, content: [{ type: 'text', text: res.error?.message ?? 'The action failed.' }] };
+                }
+                const body = res.image ? [imageContent(res.image)] : [{ type: 'text', text: res.output ?? 'OK' }];
+                return { type: 'tool_result', tool_use_id: c.id, toolset_name: 'computer', content: body };
+            });
+            if (r.screenshot)
+                out[out.length - 1].content.push(imageContent(r.screenshot));
+            return out;
+        },
+    };
+}
+/** No hook: one batch as before. With a hook, check immediately before each individual action runs. */
+export async function runComputerActions(act, actions, opts, beforeAction) {
+    if (!beforeAction)
+        return act(actions, opts);
+    const out = { results: [] };
+    for (const [i, action] of actions.entries()) {
+        const checked = structuredClone(action);
+        let refusal;
+        try {
+            const decision = await beforeAction(structuredClone(checked));
+            if (decision === false || typeof decision === 'string')
+                refusal = typeof decision === 'string' && decision ? decision : 'Computer action refused by beforeAction.';
+        }
+        catch (err) {
+            refusal = (err instanceof Error ? err.message : String(err)) || 'Computer action refused by beforeAction.';
+        }
+        if (refusal !== undefined) {
+            out.results.push({ action: action.action, ok: false, took_ms: 0, error: { code: 'action_failed', message: refusal } });
+        }
+        else {
+            const r = await act([checked], { ...opts, screenshot: i === actions.length - 1 && opts.screenshot !== false && !LOOKS.has(action.action) });
+            out.results.push(...r.results);
+            out.cursor = r.cursor;
+            out.display = r.display;
+            if (r.screenshot)
+                out.screenshot = r.screenshot;
+        }
+        if (!out.results.at(-1)?.ok) {
+            out.results.push(...actions.slice(i + 1).map((a) => ({ action: a.action, ok: false, skipped: true, took_ms: 0 })));
+            break;
+        }
+    }
+    return out;
+}

package/dist/errors.d.ts

@@ -82,7 +82,7 @@ export type ErrorCode = AppErrorCode | CellErrorCode;
  * `retained_state` (details.limit_value and details.current in GiB) when opening a new key or forking with the plan's
  * Retained state used up. `details.limit` is not a reason: these are not in this union.
  */
-export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch' | 'allocation_mode_not_available' | 'requires_elastic' | 'exceeds_memory_mib' | 'burst_mode_not_supported' | 'burst_not_supported' | 'burst_size_exceeds_plan' | 'not_available' | 'shared_volumes' | 'fence_not_drained' | 'apply_pending' | 'park_failed' | 'workspace_resumed' | 'interrupted' | 'burst_lost' | 'disk_full' | 'apply_failed' | 'reverted' | 'revert_failed' | 'immutable_path_removed' | 'immutable_paths_unsupported_base' | 'read_only_path' | 'resize_not_available' | 'shrink_not_supported' | 'resize_failed' | 'host_lost' | 'inbound_ports_not_available' | 'port_not_exposed' | 'port_limit';
+export type KnownErrorReason = 'invalid_recipe' | 'base_not_layered' | 'language_unavailable' | 'language_conflict' | 'invalid_package' | 'too_many_files' | 'platform_owned_path' | 'upload_required' | 'upload_missing' | 'upload_digest_mismatch' | 'upload_too_large' | 'extra_hosts_without_auto' | 'invalid_settings' | 'services_unsupported' | 'input_required' | 'input_unknown' | 'input_invalid' | 'egress_widening' | 'reserved_session_id' | 'env_collision' | 'reserved_template_slug' | 'package_index_unavailable' | 'package_not_found' | 'startup_failed' | 'service_not_ready' | 'secrets_unavailable' | 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'already_current' | 'not_upgradable' | 'upgrade_base_unavailable' | 'upgrade_host_unavailable' | 'upgrade_host_unsupported' | 'upgrade_template_mismatch' | 'upgrade_runtime_mismatch' | 'checkpoint_template_mismatch' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found' | 'revision_mismatch' | 'edit_not_found' | 'edit_ambiguous' | 'edit_not_text' | 'patch_invalid' | 'host_capacity' | 'wake_failed' | 'workspace_fenced' | 'offline_unavailable' | 'offline_budget' | 'offline_changed' | 'host_feature_unavailable' | 'not_supported_for_mode' | 'mode_mismatch' | 'mode_not_available' | 'layout_unsupported' | 'tree_revision_mismatch' | 'outside_tree_root' | 'execution_in_progress' | 'execution_id_reused' | 'operation_id_reused' | 'no_execution_host' | 'lease_expired' | 'host_unreachable' | 'host_restarted' | 'tree_moved' | 'blob_missing' | 'blob_corrupt' | 'exec_failed_to_start' | 'invalid_cwd' | 'allowance_used' | 'overage_paused' | 'spend_cap_reached' | 'overage_unavailable' | 'spend_cap_required' | 'spend_cap_below_minimum' | 'spend_cap_above_plan_price' | 'spend_cap_below_charges' | 'version_mismatch' | 'allocation_mode_not_available' | 'requires_elastic' | 'exceeds_memory_mib' | 'burst_mode_not_supported' | 'burst_not_supported' | 'burst_size_exceeds_plan' | 'not_available' | 'shared_volumes' | 'fence_not_drained' | 'apply_pending' | 'park_failed' | 'workspace_resumed' | 'interrupted' | 'burst_lost' | 'disk_full' | 'apply_failed' | 'reverted' | 'revert_failed' | 'immutable_path_removed' | 'immutable_paths_unsupported_base' | 'read_only_path' | 'resize_not_available' | 'shrink_not_supported' | 'resize_failed' | 'host_lost' | 'inbound_ports_not_available' | 'port_not_exposed' | 'port_limit';
 /** A known reason, or any other string the server sends (reasons are open-ended). */
 export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
@@ -117,6 +117,10 @@ export declare class ShardfluxApiError extends Error {
     readonly treeRevision: number | undefined;
     constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
 }
+/** A cell file operation found that the requested path does not exist. */
+export declare class FileNotFoundError extends ShardfluxApiError {
+    constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number, treeRevision?: number);
+}
 /**
  * The cell gateway's working-at-once refusal (0.14.0+): 429 `quota_exceeded`, retryable, with Retry-After. The gateway
  * refuses the call at admission, before the workspace is touched, so nothing ran and any request (exec start, stdin,

package/dist/errors.js

@@ -40,6 +40,13 @@ export class ShardfluxApiError extends Error {
         this.reason = typeof reason === 'string' ? reason : undefined;
     }
 }
+/** A cell file operation found that the requested path does not exist. */
+export class FileNotFoundError extends ShardfluxApiError {
+    constructor(status, body, source, retryAfterSeconds, treeRevision) {
+        super(status, body, source, retryAfterSeconds, treeRevision);
+        this.name = 'FileNotFoundError';
+    }
+}
 /**
  * The cell gateway's working-at-once refusal (0.14.0+): 429 `quota_exceeded`, retryable, with Retry-After. The gateway
  * refuses the call at admission, before the workspace is touched, so nothing ran and any request (exec start, stdin,
@@ -126,6 +133,8 @@ export class ExecStartError extends ShardfluxApiError {
  * here, so `instanceof` works whichever call was refused.
  */
 export function apiError(status, body, source, retryAfterSeconds, treeRevision) {
+    if (source === 'cell' && status === 404 && body.error.code === 'not_found' && body.error.details?.reason === 'path_not_found')
+        return new FileNotFoundError(status, body, source, retryAfterSeconds, treeRevision);
     switch (body.error.details?.reason) {
         case 'not_supported_for_mode':
             return new NotSupportedForModeError(status, body, source, retryAfterSeconds, treeRevision);

package/dist/executions.d.ts

@@ -1,9 +1,3 @@
-/**
- * Executions of file-first workspaces: each `POST /exec` runs one command in a fresh VM on the
- * workspace's latest tree revision and answers when it ended; the files it changed under /home/user become the next
- * revision. The execution id is the idempotency key: a request retried with the same id returns the recorded result
- * (or waits for the running execution) and never runs the command a second time.
- */
 import type { components } from './generated/cell-api.js';
 type S = components['schemas'];
 /** The cell's `ExecutionResult` as sent on the wire (stdout/stderr base64). */
@@ -105,6 +99,8 @@ export declare class ExecutionResult {
     readonly replayed: boolean;
     /** The body as the cell sent it. */
     readonly raw: ExecutionResultBody;
+    /** POSIX status of the command. */
+    get exitCodePosix(): number;
     constructor(body: ExecutionResultBody, replayed: boolean);
     /** Still queued or running (only `executions.get()` returns such a result). */
     get pending(): boolean;

package/dist/executions.js

@@ -1,3 +1,10 @@
+/**
+ * Executions of file-first workspaces: each `POST /exec` runs one command in a fresh VM on the
+ * workspace's latest tree revision and answers when it ended; the files it changed under /home/user become the next
+ * revision. The execution id is the idempotency key: a request retried with the same id returns the recorded result
+ * (or waits for the running execution) and never runs the command a second time.
+ */
+import { exitCodePosix } from "./exit-code.js";
 /** `^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$` (cell-api.yaml ExecutionIdValue). */
 export const EXECUTION_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{7,127}$/;
 /** A fresh execution id: `ex-` plus a random UUID (39 characters, valid per EXECUTION_ID). */
@@ -43,6 +50,8 @@ export class ExecutionResult {
     replayed;
     /** The body as the cell sent it. */
     raw;
+    /** POSIX status of the command. */
+    get exitCodePosix() { return exitCodePosix(this); }
     constructor(body, replayed) {
         this.raw = body;
         this.executionId = body.execution_id;

package/dist/exit-code.d.ts

@@ -0,0 +1,7 @@
+/** The command's POSIX status, shared by exec results and the CLI. */
+export declare function exitCodePosix(result: {
+    exitCode: number | null;
+    termSignal: number | null;
+    timedOut: boolean;
+    canceled?: boolean;
+}): number;

package/dist/exit-code.js

@@ -0,0 +1,12 @@
+/** The command's POSIX status, shared by exec results and the CLI. */
+export function exitCodePosix(result) {
+    if (result.timedOut)
+        return 124;
+    if (result.canceled)
+        return 130;
+    if (result.exitCode !== null && result.exitCode >= 0)
+        return result.exitCode;
+    if (result.termSignal !== null && result.termSignal > 0)
+        return 128 + result.termSignal;
+    return 1;
+}