@shardflux/sdk 0.12.0 → 0.13.0

package/dist/tools.js

@@ -10,8 +10,8 @@
  * application; toOpenAITools/toAnthropicTools export the definitions in those
  * providers' formats and executeToolCall dispatches a model's tool call.
  */
-import { CAPTURE_BARRIER } from "./cell.js";
-import { ExecStartError } from "./errors.js";
+import { CAPTURE_BARRIER, burstFailure } from "./cell.js";
+import { ExecStartError, ShardfluxApiError } from "./errors.js";
 import { newExecutionId } from "./executions.js";
 export class ToolArgumentError extends Error {
     tool;
@@ -98,6 +98,144 @@ function clip(text, max) {
         return { text, truncated: false };
     return { text: bytes.subarray(0, max).toString('utf8'), truncated: true };
 }
+const toolError = (e) => ({ code: e.code, message: e.message, reason: e.reason });
+/**
+ * Why a session ended without running to an exit code, as the exec tools report it: a burst's recorded failure, a
+ * command that could not start (as ExecStartError says it), or the session's own reason (e.g. lost). Null otherwise.
+ */
+function sessionError(s) {
+    if (s.burst?.error)
+        return toolError(burstFailure(s.burst.error));
+    if (s.state === 'failed_to_start')
+        return toolError(new ExecStartError(s));
+    if (s.error)
+        return { code: 'internal_error', message: `The command ended without an exit status: ${s.error}`, reason: undefined };
+    return null;
+}
+const running = (s) => s.state === 'starting' || s.state === 'running';
+/** A UTF-8 continuation byte (10xxxxxx). */
+const continuation = (b) => (b & 0xc0) === 0x80;
+/** The length of the UTF-8 sequence a lead byte starts (0 for a byte that cannot start one). */
+const sequenceLength = (b) => (b < 0x80 ? 1 : (b & 0xe0) === 0xc0 ? 2 : (b & 0xf0) === 0xe0 ? 3 : (b & 0xf8) === 0xf0 ? 4 : 0);
+/** `end`, moved back to the start of the UTF-8 sequence it would cut (unchanged when it cuts none). */
+function utf8End(bytes, end) {
+    for (let i = end - 1; i >= Math.max(0, end - 3); i--) {
+        const b = bytes[i];
+        if (continuation(b))
+            continue;
+        const n = sequenceLength(b);
+        return n > 0 && i + n > end ? i : end;
+    }
+    return end;
+}
+/**
+ * One stream of an exec_read: the bytes from `start`, kept up to the tools' limit plus one byte (which says that more
+ * follows). Chunks are byte ranges of the stream (`offset` is the stream offset of their first byte), split anywhere,
+ * also inside a character: the text is decoded once, from the bytes joined.
+ */
+class OutputWindow {
+    start;
+    #max;
+    #chunks = [];
+    #kept = 0;
+    /** How far the stream is known to reach: the session's size, or the end of a chunk seen after it. */
+    #end;
+    constructor(start, max, size) {
+        this.start = start;
+        this.#max = max;
+        this.#end = size;
+    }
+    get full() {
+        return this.#kept > this.#max;
+    }
+    push(offset, data) {
+        this.#end = Math.max(this.#end, offset + data.length);
+        const at = this.start + this.#kept;
+        if (this.full || offset > at || offset + data.length <= at)
+            return;
+        const part = data.subarray(at - offset, at - offset + this.#max + 1 - this.#kept);
+        this.#chunks.push(part);
+        this.#kept += part.length;
+    }
+    /**
+     * The text from the first character boundary at or after `start` (`offset`) to `next`: at most the limit, never a
+     * cut character (the cut moves back to its first byte, and a running command's last, incomplete character waits for
+     * the next read). `truncated`: the stream holds more than the limit past `start`.
+     */
+    result(ended) {
+        const bytes = Buffer.concat(this.#chunks);
+        let skip = 0;
+        if (this.start > 0)
+            while (skip < 3 && skip < bytes.length && continuation(bytes[skip]))
+                skip += 1;
+        const truncated = this.#end - this.start > this.#max;
+        let end = Math.min(bytes.length, this.#max);
+        if (truncated || !ended) {
+            const cut = utf8End(bytes, end);
+            // A limit too small for one character still makes progress.
+            end = cut > skip || !truncated ? Math.max(cut, skip) : Math.max(end, skip);
+        }
+        return { text: new TextDecoder().decode(bytes.subarray(skip, end)), offset: this.start + skip, next: this.start + end, truncated };
+    }
+}
+/** A failure event of an exec output stream: a burst's recorded outcome (on its session too), or a stream failure. */
+const BURST_FAILURES = new Set(['burst_unavailable', 'burst_apply_failed']);
+/**
+ * Reads the output that exists (follow=false) into the windows given, stopping once they are full. Returns the
+ * session of an `exit` event (the session ended meanwhile), else null.
+ */
+async function drainOutput(c, id, from, into, signal) {
+    const windows = [into.stdout, into.stderr].filter((w) => w !== undefined);
+    for await (const ev of await c.exec.output(id, { stdoutOffset: from.stdout, stderrOffset: from.stderr, follow: false, ...(signal ? { signal } : {}) })) {
+        if (ev.type === 'output' && ev.data !== undefined) {
+            const w = ev.stream === 'stderr' ? into.stderr : into.stdout;
+            w?.push(ev.offset ?? 0, Buffer.from(ev.data, 'base64'));
+            if (windows.every((x) => x.full))
+                return null;
+        }
+        else if (ev.type === 'exit' && ev.session) {
+            return ev.session;
+        }
+        else if (ev.type === 'error' && ev.error && !BURST_FAILURES.has(ev.error.error.code)) {
+            throw new ShardfluxApiError(502, ev.error, 'cell');
+        }
+    }
+    return null;
+}
+/**
+ * Waits up to `waitMs` for a running session to end and returns it as it is then. Follows the output from the current
+ * sizes, so only what the command writes meanwhile flows, and answers on the `exit` event; a dropped stream is
+ * followed again while time is left.
+ */
+async function waitForExit(c, s, waitMs, signal) {
+    const deadline = Date.now() + waitMs;
+    let current = s;
+    for (let attempt = 0; attempt < 5 && running(current) && Date.now() < deadline; attempt++) {
+        const timer = new AbortController();
+        const t = setTimeout(() => timer.abort(), Math.max(0, deadline - Date.now()));
+        const sig = signal ? AbortSignal.any([signal, timer.signal]) : timer.signal;
+        try {
+            for await (const ev of await c.exec.output(current.session_id, { stdoutOffset: current.stdout_size, stderrOffset: current.stderr_size, follow: true, signal: sig })) {
+                if (ev.type === 'exit')
+                    return ev.session ?? (await c.exec.get(current.session_id));
+                if (ev.type === 'error')
+                    break;
+            }
+        }
+        catch (e) {
+            if (signal?.aborted)
+                throw e;
+            // A refusal (e.g. an unknown session) is the answer; the end of the wait or a dropped stream is not.
+            if (!timer.signal.aborted && e instanceof ShardfluxApiError && !e.retryable)
+                throw e;
+        }
+        finally {
+            clearTimeout(t);
+        }
+        current = await c.exec.get(current.session_id);
+    }
+    return current;
+}
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export function workspaceTools(workspace, opts = {}) {
     const cell = () => workspace.cell({
@@ -117,6 +255,30 @@ export function workspaceTools(workspace, opts = {}) {
         timeout_ms: { type: 'integer', minimum: 1000, maximum: 3_600_000, description: 'Kill the command after this long (default 600000).' },
         stdin: { type: 'string', maxLength: 1_000_000, description: 'Text written to stdin.' },
     }, ['command']);
+    // The processful exec: background sessions (0.13.0; read with exec_read, stopped with exec_cancel), a timeout up to a
+    // day, and with burst execution (opt-in) its extra inputs.
+    const sessionId = { type: 'string', minLength: 1, maxLength: 64 };
+    const processfulExecParameters = obj({
+        command: execParameters.properties.command,
+        cwd: execParameters.properties.cwd,
+        timeout_ms: { type: 'integer', minimum: 1000, maximum: 86_400_000, description: 'Kill the command after this long (default 600000; with background, none unless set).' },
+        stdin: execParameters.properties.stdin,
+        background: {
+            type: 'boolean',
+            description: 'Start the command and return its session_id at once instead of waiting for it to exit (default false). Use it for anything that may run longer than a few minutes, such as a build, a test suite, a training run or a server. Keep using the other tools meanwhile, read it with exec_read and stop it with exec_cancel. Set timeout_ms to the longest it may run: the workspace stays awake until the command ends or that time passes (1 hour when unset).',
+        },
+        ...(opts.burst
+            ? {
+                burst: {
+                    type: 'string',
+                    enum: ['never', 'always'],
+                    description: 'always: run this heavy, self-terminating command (a cold build, a large test suite) on a larger, short-lived burst VM over a copy of the workspace, and apply its file changes back when it exits. Processes it starts do not survive; not with stdin. Default never.',
+                },
+                burst_vcpus: { type: 'integer', minimum: 1, maximum: 32, description: 'With burst always: the burst VM’s vCPUs (default 8, or the plan’s ceiling when lower).' },
+                burst_memory_mib: { type: 'integer', minimum: 512, maximum: 65536, description: 'With burst always: the burst VM’s memory in MiB (default 8192, or the plan’s ceiling when lower).' },
+            }
+            : {}),
+    }, ['command']);
     const defs = [
         fileFirst
             ? {
@@ -158,15 +320,42 @@ export function workspaceTools(workspace, opts = {}) {
             : {
                 name: 'exec',
                 permission: 'exec',
-                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls.',
-                parameters: execParameters,
+                description: 'Run a shell command in the persistent remote workspace (Linux; bash -lc) and return its exit code, stdout and stderr. Files, installed packages and background processes persist between calls. A command that may run longer than a few minutes can run in the background (background: true).',
+                parameters: processfulExecParameters,
+                // A burst fences the workspace until it applies its changes: the other tools could not run meanwhile.
+                refuse: (a) => a.background === true && opts.burst && a.burst === 'always'
+                    ? ['background cannot be combined with burst always: a burst holds the workspace until it applies its changes; run it without background']
+                    : [],
                 run: async (a, o) => {
+                    const burst = opts.burst && (a.burst === 'always' || a.burst === 'never') ? a.burst : undefined;
+                    const burstVcpus = opts.burst && typeof a.burst_vcpus === 'number' ? a.burst_vcpus : undefined;
+                    const burstMemoryMib = opts.burst && typeof a.burst_memory_mib === 'number' ? a.burst_memory_mib : undefined;
+                    const cwd = typeof a.cwd === 'string' ? a.cwd : opts.defaultCwd;
+                    if (a.background === true) {
+                        // A session of its own: the start answers at once, and exec_read / exec_cancel find it by session_id.
+                        // The command runs until it exits or its timeout_ms, if one is set. (Never a burst: refused above.)
+                        const s = await cell().exec.start({
+                            argv: ['bash', '-lc', String(a.command)],
+                            ...(cwd !== undefined ? { cwd } : {}),
+                            ...(typeof a.timeout_ms === 'number' ? { timeout_ms: a.timeout_ms } : {}),
+                            ...(typeof a.stdin === 'string' ? { stdin: Buffer.from(a.stdin, 'utf8').toString('base64') } : {}),
+                            ...(burst !== undefined ? { burst } : {}),
+                            ...(burstVcpus !== undefined ? { burst_vcpus: burstVcpus } : {}),
+                            ...(burstMemoryMib !== undefined ? { burst_memory_mib: burstMemoryMib } : {}),
+                        }, o.signal);
+                        // Nothing ran (e.g. a cwd that is not a directory): the reason, as the foreground exec gives it.
+                        const error = s.state === 'failed_to_start' ? sessionError(s) : null;
+                        return { session_id: s.session_id, state: s.state, ...(error ? { error } : {}) };
+                    }
                     let r;
                     try {
                         r = await cell().exec.run(['bash', '-lc', String(a.command)], {
-                            ...(typeof a.cwd === 'string' ? { cwd: a.cwd } : opts.defaultCwd ? { cwd: opts.defaultCwd } : {}),
+                            ...(cwd !== undefined ? { cwd } : {}),
                             timeoutMs: typeof a.timeout_ms === 'number' ? a.timeout_ms : 600_000,
                             ...(typeof a.stdin === 'string' ? { stdin: a.stdin } : {}),
+                            ...(burst !== undefined ? { burst } : {}),
+                            ...(burstVcpus !== undefined ? { burstVcpus } : {}),
+                            ...(burstMemoryMib !== undefined ? { burstMemoryMib } : {}),
                             maxOutputBytes: max,
                             ...(o.signal ? { signal: o.signal } : {}),
                         });
@@ -183,12 +372,89 @@ export function workspaceTools(workspace, opts = {}) {
                             stderr: '',
                             truncated: false,
                             session_id: e.sessionId,
-                            error: { code: e.code, message: e.message, reason: e.reason },
+                            error: toolError(e),
                         };
                     }
-                    return { exit_code: r.exitCode, term_signal: r.termSignal, timed_out: r.timedOut, stdout: r.stdout, stderr: r.stderr, truncated: r.truncated, session_id: r.sessionId };
+                    return {
+                        exit_code: r.exitCode,
+                        term_signal: r.termSignal,
+                        timed_out: r.timedOut,
+                        stdout: r.stdout,
+                        stderr: r.stderr,
+                        truncated: r.truncated,
+                        session_id: r.sessionId,
+                        // Elastic workspaces (0.13.0): the memory grow the command waited for, when one ran.
+                        ...(r.memoryGrow ? { memory_grow: r.memoryGrow } : {}),
+                        // Burst execution (0.13.0, opt-in): what the burst VM ran and applied.
+                        ...(r.burst ? { burst: r.burst } : {}),
+                    };
                 },
             },
+        // Background sessions (0.13.0): exec_read and exec_cancel need exec sessions, which a file-first workspace has none of.
+        ...(fileFirst
+            ? []
+            : [
+                {
+                    name: 'exec_read',
+                    permission: 'exec',
+                    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 id = String(a.session_id);
+                        let s = await c.exec.get(id);
+                        if (typeof a.wait_ms === 'number' && a.wait_ms > 0 && running(s))
+                            s = await waitForExit(c, s, a.wait_ms, o.signal);
+                        // Each stream from the offset given, else its last `max` bytes (as they are after the wait).
+                        const out = new OutputWindow(typeof a.stdout_offset === 'number' ? a.stdout_offset : Math.max(0, s.stdout_size - max), max, s.stdout_size);
+                        const err = new OutputWindow(typeof a.stderr_offset === 'number' ? a.stderr_offset : Math.max(0, s.stderr_size - max), max, s.stderr_size);
+                        if (out.start < s.stdout_size || err.start < s.stderr_size) {
+                            // The guest sends one stream's output up to its end before the other's: when stdout holds more than
+                            // a window past its offset, stderr is read by a request of its own.
+                            const ended = err.start < s.stderr_size && s.stdout_size - out.start > max
+                                ? (await Promise.all([
+                                    drainOutput(c, id, { stdout: out.start, stderr: s.stderr_size }, { stdout: out }, o.signal),
+                                    drainOutput(c, id, { stdout: s.stdout_size, stderr: err.start }, { stderr: err }, o.signal),
+                                ])).find((x) => x !== null)
+                                : await drainOutput(c, id, { stdout: out.start, stderr: err.start }, { stdout: out, stderr: err }, o.signal);
+                            if (ended)
+                                s = ended;
+                        }
+                        const done = !running(s);
+                        const so = out.result(done);
+                        const se = err.result(done);
+                        const error = sessionError(s);
+                        return {
+                            session_id: s.session_id,
+                            state: s.state,
+                            exit_code: done ? (s.exit_code ?? null) : null,
+                            term_signal: s.term_signal ?? null,
+                            timed_out: s.timed_out ?? false,
+                            canceled: s.canceled ?? false,
+                            stdout: so.text,
+                            stderr: se.text,
+                            stdout_offset: so.offset,
+                            stderr_offset: se.offset,
+                            next_stdout_offset: so.next,
+                            next_stderr_offset: se.next,
+                            truncated: so.truncated || se.truncated,
+                            ...(error ? { error } : {}),
+                            ...(s.burst ? { burst: s.burst } : {}),
+                        };
+                    },
+                },
+                {
+                    name: 'exec_cancel',
+                    permission: 'exec',
+                    description: 'Stop a command started with exec background: true: SIGTERM, then SIGKILL after grace_ms (default 5000).',
+                    // 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);
+                        return { session_id: s.session_id, state: s.state, exit_code: running(s) ? null : (s.exit_code ?? null), canceled: s.canceled ?? false };
+                    },
+                },
+            ]),
         {
             name: 'read_file',
             permission: 'files',
@@ -434,6 +700,8 @@ export function workspaceTools(workspace, opts = {}) {
         permission: d.permission,
         execute: async (args, options = {}) => {
             const issues = validateArgs(d.parameters, args);
+            if (issues.length === 0 && d.refuse)
+                issues.push(...d.refuse(args));
             if (issues.length > 0)
                 throw new ToolArgumentError(`${prefix}${d.name}`, issues);
             // Fire and forget: a parked workspace starts restoring while this call is prepared. Not for

package/dist/workspace.d.ts

@@ -2,12 +2,12 @@
  * 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 { ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, SuspendRequest, SuspendWhenIdleOptions, SuspendWhenIdleResult, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
+import type { AllocationMode, ClientContext, IdlePolicy, DiskLayout, ForkTarget, Operation, 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';
 import type { WorkspaceMode } from './errors.js';
-import type { FinishedOperation, LifecycleOptions, ResumeOptions, SuspendOptions, WaitedLifecycleOptions, WaitedResumeOptions, WaitedSuspendOptions } from './lifecycle.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 { WorkspaceSecrets } from './secrets.js';
@@ -82,6 +82,13 @@ export declare class Workspace {
     get grants(): WorkspaceView['grants'];
     get ceilings(): WorkspaceView['ceilings'];
     get template(): WorkspaceView['template'];
+    /**
+     * The template version whose immutable paths the workspace has mounted (0.13.0; `template.immutable_version`): the
+     * template's newest published version as of the workspace's last cold boot or resume, which can be newer than
+     * `template.version`. Null when the workspace mounts none (its version declares no immutable paths, it has not started
+     * since, or an older API).
+     */
+    get immutableVersion(): number | null;
     get pendingReason(): string | null;
     get activeOperation(): WorkspaceView['active_operation'];
     /** persistent or session; immutable. A view without the field (older API) is persistent. */
@@ -108,6 +115,14 @@ export declare class Workspace {
      * a resume after the request cancelled it. `refresh()` reads it again.
      */
     get suspendRequest(): SuspendRequest | null;
+    /**
+     * Memory of the workspace as of the last view (0.13.0): `{allocation_mode, promised_mib, held_mib,
+     * plugged_mib}`. An elastic workspace holds `held_mib` while idle and is grown towards `promised_mib` when a command
+     * needs it; `plugged_mib` is what is plugged above the floor now (null without a live allocation). Null on an older API.
+     */
+    get memory(): WorkspaceMemory | null;
+    /** `fixed` or `elastic` (0.13.0): the running VM's layout, else the next start's. Fixed on an older API. */
+    get allocationMode(): AllocationMode;
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
     /**
@@ -205,11 +220,11 @@ export declare class Workspace {
      * Forks into a new key. Resolves when the fork is REQUESTED (the copy's handle is returned at once); with
      * `{ wait: true }`, once the copy exists, with its handle refreshed.
      */
-    fork(target: ForkTarget, opts: WaitedLifecycleOptions): Promise<{
+    fork(target: ForkTarget, opts: WaitedForkOptions): Promise<{
         operation: FinishedOperation;
         workspace: Workspace;
     }>;
-    fork(target: ForkTarget, opts?: LifecycleOptions): Promise<{
+    fork(target: ForkTarget, opts?: ForkOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;

package/dist/workspace.js

@@ -96,6 +96,15 @@ export class Workspace {
     get template() {
         return this.#view.template;
     }
+    /**
+     * The template version whose immutable paths the workspace has mounted (0.13.0; `template.immutable_version`): the
+     * template's newest published version as of the workspace's last cold boot or resume, which can be newer than
+     * `template.version`. Null when the workspace mounts none (its version declares no immutable paths, it has not started
+     * since, or an older API).
+     */
+    get immutableVersion() {
+        return this.#view.template.immutable_version ?? null;
+    }
     get pendingReason() {
         return this.#view.pending_reason;
     }
@@ -142,6 +151,18 @@ export class Workspace {
     get suspendRequest() {
         return this.#view.idle?.suspend_request ?? null;
     }
+    /**
+     * Memory of the workspace as of the last view (0.13.0): `{allocation_mode, promised_mib, held_mib,
+     * plugged_mib}`. An elastic workspace holds `held_mib` while idle and is grown towards `promised_mib` when a command
+     * needs it; `plugged_mib` is what is plugged above the floor now (null without a live allocation). Null on an older API.
+     */
+    get memory() {
+        return this.#view.memory ?? null;
+    }
+    /** `fixed` or `elastic` (0.13.0): the running VM's layout, else the next start's. Fixed on an older API. */
+    get allocationMode() {
+        return this.#view.memory?.allocation_mode ?? this.#view.caps?.allocation_mode ?? 'fixed';
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.12.0",
+  "version": "0.13.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",