@shardflux/sdk 0.15.0 → 0.16.0

package/dist/computer.js

@@ -6,6 +6,11 @@ export function decodeComputerImage(img) {
 /** 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;
     }
@@ -16,7 +21,7 @@ export class WorkspaceComputer {
     act(actions, opts = {}) {
         return this.#deps.cell().computer.act({
             actions,
-            ...(opts.screenshot !== undefined ? { screenshot: opts.screenshot } : {}),
+            ...(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 } : {}),
@@ -47,14 +52,57 @@ export class WorkspaceComputer {
      * 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, { path: info.path, ...(opts.ttlSeconds !== undefined ? { ttlSeconds: opts.ttlSeconds } : {}) });
+        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). */
-    async stopStream() {
+    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();
@@ -96,23 +144,24 @@ function actionOf(block) {
  * 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) {
+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 workspace.computer.act(calls.map(actionOf), {
+                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') {
@@ -144,3 +193,37 @@ export function computerToolset(workspace) {
         },
     };
 }
+/** 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;
+}