@shardflux/sdk 0.8.0 → 0.10.0

package/dist/workspace.js

@@ -1,13 +1,16 @@
 import { CAPTURE_BARRIER, CellClient, DEFAULT_TRANSITION_TIMEOUT_MS } from "./cell.js";
 import { ToolCallCapture } from "./capture.js";
-import { OperationFailedError, ShardfluxApiError } from "./errors.js";
-import { defaultSleep, randomId } from "./http.js";
-import { AFTER_WAIT, TRACE } from "./lifecycle.js";
+import { NotSupportedForModeError, OperationFailedError, ShardfluxApiError } from "./errors.js";
+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 { WorkspaceSecrets } from "./secrets.js";
 import { ToolTokenManager } from "./tokens.js";
+const notRunning = (e) => e instanceof ShardfluxApiError && (e.code === 'workspace_not_running' || (e.code === 'conflict' && e.reason === 'workspace_not_running'));
 export class Workspace {
     #view;
+    /** The background wake started by hint(), shared by concurrent hints until it settles. */
+    #hintWake = null;
     #ctx;
     #defaults;
     #managers = new Map();
@@ -15,14 +18,27 @@ export class Workspace {
     /** The open() that produced this handle; its timing is final once open() has returned. */
     #openTrace;
     #lastTiming;
+    /** The newest tree revision seen (file-first): the view's, or any cell response's since. */
+    #treeRevision;
     constructor(ctx, view, opts = {}) {
         this.#ctx = ctx;
         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 };
         this.#openTrace = opts.trace;
         if (opts.token)
             this.tokens().seed(opts.token);
     }
+    #noteTreeRevision(rev) {
+        if (this.#treeRevision === null || rev > this.#treeRevision)
+            this.#treeRevision = rev;
+    }
+    /** The local refusal of a lifecycle call a file-first workspace does not have (contracts §29.7). */
+    #needsVm(operation) {
+        if (this.#view.mode !== 'file_first')
+            return null;
+        return NotSupportedForModeError.local('file_first', operation, 'api', `${operation} is not available for a file-first workspace: it has no VM between executions and is never suspended; its state is its file tree (workspace.treeRevision).`);
+    }
     /**
      * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
      * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
@@ -116,10 +132,45 @@ export class Workspace {
     get startup() {
         return this.#view.startup ?? null;
     }
+    /**
+     * The pending suspend-when-idle request as of the last view (0.10.0; `idle.suspend_request`): `{requested_at,
+     * after_seconds, not_before}`, or null when there is none, when the workspace is not running, or once a tool call or
+     * a resume after the request cancelled it. `refresh()` reads it again.
+     */
+    get suspendRequest() {
+        return this.#view.idle?.suspend_request ?? null;
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;
     }
+    /**
+     * `processful` (one VM keeps processes, memory and files) or `file_first` (0.9.0; contracts §29: a versioned file
+     * tree, commands run as executions). Immutable. A view without the field (older API) is processful.
+     */
+    get mode() {
+        return this.#view.mode ?? 'processful';
+    }
+    /**
+     * File-first workspaces: the newest tree revision this handle has seen (0 when created; each mutating files call or
+     * execution that changed something publishes the next). It follows every response of this handle's cell clients
+     * (`X-Tree-Revision`), execution results and refresh(); another writer's changes appear once a response reports
+     * them. Pass it as `ifTreeRevision` to make a write conditional. Null for processful workspaces.
+     */
+    get treeRevision() {
+        return this.mode === 'file_first' ? this.#treeRevision : null;
+    }
+    /**
+     * Executions of this file-first workspace (contracts §29.8) through `cell()`'s default client: `run(argv, opts)` runs
+     * a command in a fresh VM on the latest tree and returns an ExecutionResult (output, exit code, `changed`,
+     * `treeRevision`); `get(id, { waitMs })` reads one. See CellClient.executions.
+     *
+     *   const r = await workspace.executions.run(['bash', '-lc', 'pytest -q'], { timeoutMs: 600_000 });
+     *   console.log(r.exitCode, r.stdoutText, r.changed, r.treeRevision);
+     */
+    get executions() {
+        return this.cell().executions;
+    }
     /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
     get secrets() {
         return new WorkspaceSecrets(this.#ctx, this.id);
@@ -130,6 +181,8 @@ export class Workspace {
     }
     async refresh() {
         this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
+        if (this.#view.mode === 'file_first' && typeof this.#view.tree_revision === 'number')
+            this.#noteTreeRevision(this.#view.tree_revision);
         return this;
     }
     /** Waits for the active operation (if any) and refreshes. */
@@ -143,15 +196,67 @@ export class Workspace {
         return this.#ctx.workspaces.delete(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     suspend(opts = {}) {
+        const refusal = this.#needsVm('suspend');
+        if (refusal)
+            return Promise.reject(refusal);
         return this.#ctx.workspaces.suspend(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
+    /**
+     * Suspends the workspace once it has been idle for `afterSeconds` (30..3600; 0.9.0): call it when your agent's turn
+     * ends, so the workspace stops using RAM soon after instead of waiting out its idle policy. A command still running,
+     * an attached stream or a keepalive postpones the suspend until `afterSeconds` after it ends; the next tool call (the
+     * next turn) or a resume cancels it. Resolves with the recorded `suspendRequest` (also `workspace.suspendRequest`), or
+     * with the suspend already in progress as `operation`. See WorkspacesApi.suspendWhenIdle for the errors. A file-first
+     * workspace (never suspended) is refused locally with NotSupportedForModeError.
+     *
+     *   const { suspendRequest } = await workspace.suspendWhenIdle({ afterSeconds: 60 });
+     */
+    async suspendWhenIdle(opts) {
+        const refusal = this.#needsVm('suspend_when_idle');
+        if (refusal)
+            throw refusal;
+        const out = await this.#ctx.workspaces.suspendWhenIdle(this.id, opts);
+        this.#view = out.workspace.data;
+        return { ...out, workspace: this };
+    }
+    /**
+     * Cancels a pending suspend-when-idle request (0.10.0; idempotent, in any state) and refreshes this handle's view.
+     * A suspend the request already started is not undone (it shows as `activeOperation`).
+     */
+    async cancelSuspendWhenIdle() {
+        this.#view = (await this.#ctx.workspaces.cancelSuspendWhenIdle(this.id)).data;
+        return this;
+    }
     resume(opts = {}) {
-        return this.#ctx.workspaces.resume(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
+        const refusal = this.#needsVm('resume');
+        if (refusal)
+            return Promise.reject(refusal);
+        // With `wait` the held resume's view and token go straight into this handle (the token for agentLabel/tools).
+        const manager = this.tokens({ ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}), ...(opts.tools !== undefined ? { tools: opts.tools } : {}) });
+        return this.#ctx.workspaces.resume(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait(), [HELD_RESUME]: this.#heldTarget(manager) });
+    }
+    /** A held resume's 200 (contracts §22.6) goes straight into this handle: the view, and the token for `manager`. */
+    #heldTarget(manager) {
+        return {
+            agentLabel: manager.agentLabel,
+            tools: manager.tools,
+            adopt: (view, token) => {
+                this.#view = view;
+                if (token)
+                    manager.seed(token);
+            },
+        };
     }
     snapshot(opts = {}) {
+        const refusal = this.#needsVm('snapshot');
+        if (refusal)
+            return Promise.reject(refusal);
         return this.#ctx.workspaces.snapshot(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     fork(target, opts = {}) {
+        const refusal = this.#needsVm('fork');
+        if (refusal)
+            return Promise.reject(refusal);
         return this.#ctx.workspaces.fork(this.id, target, this.#tracked(opts));
     }
     async close(opts = {}) {
@@ -169,6 +274,9 @@ export class Workspace {
         return out.operation;
     }
     async reset(opts = {}) {
+        const refusal = this.#needsVm('reset');
+        if (refusal)
+            throw refusal;
         const op = await this.#ctx.workspaces.reset(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
         for (const m of this.#managers.values())
             m.invalidate();
@@ -197,7 +305,7 @@ export class Workspace {
             maxRetries: 0,
             ...(opts.transitionTimeoutMs !== undefined ? { transitionTimeoutMs: opts.transitionTimeoutMs } : {}),
             ...(this.#ctx.onProgress ? { onProgress: this.#ctx.onProgress } : {}),
-            wake: opts.wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}) }) : opts.wake,
+            wake: opts.wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}), ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) }) : opts.wake,
         });
         return new ToolCallCapture({ workspaceId: this.id, cell, registry: this.#ctx.captures, ...(this.#ctx.sleep !== defaultSleep ? { sleep: this.#ctx.sleep } : {}) }, opts);
     }
@@ -207,11 +315,15 @@ export class Workspace {
     }
     /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
     saveAsTemplate(params) {
+        const refusal = this.#needsVm('save_as_template');
+        if (refusal)
+            return Promise.reject(refusal);
         return this.#ctx.workspaces.saveAsTemplate(this.id, params);
     }
     /**
      * The workspace's changes against its template (cell gateway GET /v1/workspaces/{id}/changes; needs the `files` tool).
      * 409 workspace_not_running, or conflict with details.reason legacy_disk_layout / guest_feature_unavailable.
+     * File-first workspaces: NotSupportedForModeError (each execution result lists what it changed).
      */
     changes(opts = {}) {
         const { agentLabel, tools, ...params } = opts;
@@ -249,8 +361,14 @@ export class Workspace {
                 userAgent: this.#ctx.userAgent,
                 sleep: this.#ctx.sleep,
                 ...cellOpts,
+                // The view's mode (undefined from an older API: calls are sent and the server decides).
+                mode: () => this.#view.mode,
+                onTreeRevision: (rev) => this.#noteTreeRevision(rev),
                 ...(listener ? { onProgress: listener } : {}),
-                wake: wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}), ...(onProgress ? { onProgress } : {}) }) : wake,
+                // The wake's held resume brings back this client's token (its label and tools).
+                wake: wake === undefined
+                    ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}), ...(onProgress ? { onProgress } : {}), ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) })
+                    : wake,
                 [CAPTURE_BARRIER]: () => this.#ctx.captures.settle(this.id),
             });
             this.#cells.set(k, c);
@@ -267,8 +385,16 @@ export class Workspace {
      * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`. A resume no
      * host admits within 15 minutes fails with `capacity_unavailable` (OperationFailedError, `retryable`: the workspace
      * stays suspended with its state; try again later).
+     *
+     * Since 0.9.0 the resume is held by the server until the workspace runs (contracts §22.6): one request returns the
+     * running workspace and a tool token for `agentLabel`/`tools`, which this handle keeps, so a tool call that woke the
+     * workspace is retried at once (refused call, resume, call). Timing: one `request` phase with reason `held`. A server
+     * that does not hold the request answers at once; the wake then waits for the operation and reads the view.
      */
     async wake(opts = {}) {
+        // A file-first workspace runs from creation and is never suspended (contracts §29.7): nothing to wake.
+        if (this.#view.mode === 'file_first')
+            return false;
         const trace = new Trace('wake', combineListeners(this.#ctx.onProgress, this.#tracked(opts).onProgress), { workspaceId: this.id });
         return traced(trace, () => this.#wake(opts, trace));
     }
@@ -276,17 +402,39 @@ export class Workspace {
         const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS);
         const waitFor = (operationId) => this.#ctx.workspaces.waitForOperation(operationId, { timeoutMs: Math.max(1, deadline - Date.now()), ...(opts.signal ? { signal: opts.signal } : {}), [TRACE]: trace });
         const resumePath = `/v1/workspaces/${encodeURIComponent(this.id)}/resume`;
+        // The held resume's token is for the caller's client (agent label and tools).
+        const target = this.#heldTarget(this.tokens({ ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}), ...(opts.tools !== undefined ? { tools: opts.tools } : {}) }));
         for (let i = 0; i < 4; i += 1) {
             if (opts.signal?.aborted)
                 throw opts.signal.reason;
             let active;
             try {
-                // Resume returns the active resume/open when there is one, so concurrent wakes join a single operation. The
-                // request is made here rather than through resume() so the wake is one trace.
-                trace.phase('request', i === 0 ? null : 'retry');
-                const { operation: op } = await this.#ctx.http.json('POST', resumePath, { idempotencyKey: randomId('op-'), onRetry: trace.onRetry }, this.#ctx.authorization);
-                trace.observe(op);
-                await waitFor(op.id);
+                // Held resume (contracts §22.6): answered once the workspace runs, with the view and a token; it returns the
+                // active resume/open when there is one, so concurrent wakes join a single operation. The request is made here
+                // rather than through resume() so the wake is one trace.
+                const waitS = Math.min(SERVER_WAIT_MAX_S, Math.floor((deadline - Date.now()) / 1000));
+                trace.phase('request', waitS >= 1 ? 'held' : i === 0 ? null : 'retry');
+                const answer = await this.#ctx.workspaces.requestResume(this.id, {
+                    waitS,
+                    agentLabel: target.agentLabel,
+                    tools: target.tools,
+                    idempotencyKey: randomId('op-'),
+                    signal: opts.signal,
+                    onRetry: trace.onRetry,
+                });
+                if (answer.operation)
+                    trace.observe(answer.operation);
+                if (answer.ready) {
+                    target.adopt(answer.workspace, answer.toolToken);
+                    // No operation: it was already running (after a conflict this wake did wait for an operation).
+                    return answer.operation !== null || i > 0;
+                }
+                // Not held (an older server), or not finished within the hold: wait for the operation, then read the view.
+                const op = answer.operation;
+                if (op.state === 'failed' || op.state === 'canceled')
+                    throw new OperationFailedError(op);
+                if (op.state !== 'succeeded')
+                    await waitFor(op.id);
                 await trace.span('view', () => this.refresh());
                 return true;
             }
@@ -318,6 +466,44 @@ export class Workspace {
         }
         throw new Error(`workspace ${this.id} did not become runnable after repeated lifecycle conflicts`);
     }
+    /**
+     * Announces an imminent tool call (cell `POST /wake-hint`, contracts §26.6; 0.9.0+) so a parked workspace is restored
+     * ahead of it: call it when the model starts emitting a tool call, before its arguments are complete. The agent tools
+     * of `workspaceTools()` send it when a call starts. Cheap and best effort: it returns what the host found. A workspace
+     * that is not running (suspended, or a token cannot be issued for it) is woken in the background (`wake`, not awaited
+     * here) so the call finds it running sooner. Other errors (network, auth) are thrown; callers that fire and forget
+     * should catch them.
+     */
+    async hint(opts = {}) {
+        // Nothing of a file-first workspace sleeps: resident, without a request.
+        if (this.#view.mode === 'file_first')
+            return { residency: 'resident', wake: null };
+        const { agentLabel, tools, signal } = opts;
+        try {
+            const r = await this.cell({ ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}), wake: null }).wakeHint(signal);
+            return { residency: r.residency, wake: null };
+        }
+        catch (err) {
+            if (!notRunning(err) || signal?.aborted)
+                throw err;
+            if (opts.wake === null)
+                return { residency: null, wake: null };
+            if (!this.#hintWake) {
+                const timeoutMs = opts.wakeTimeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS;
+                // The default wake brings back the token of the hinted client (its label and tools).
+                const started = opts.wake
+                    ? opts.wake(timeoutMs).then((r) => r !== false)
+                    : this.wake({ timeoutMs, ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) });
+                const shared = started.finally(() => {
+                    if (this.#hintWake === shared)
+                        this.#hintWake = null;
+                });
+                shared.catch(() => undefined); // nobody has to await it: a failed wake is left to the next tool call
+                this.#hintWake = shared;
+            }
+            return { residency: null, wake: this.#hintWake };
+        }
+    }
     /** Tools granted by the most recent token (null before one was issued). */
     get grantedTools() {
         for (const m of this.#managers.values())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Shardflux TypeScript SDK: open persistent agent workspaces by key and give your agent workspace tools (exec, files, processes, PTY, git, browser).",
   "license": "Apache-2.0",