@shardflux/sdk 0.15.0 → 0.16.0

package/dist/tunnels.js

@@ -0,0 +1,454 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { gunzipSync } from 'node:zlib';
+import { setTimeout as delay } from 'node:timers/promises';
+import { ShardfluxApiError, ShardfluxProtocolError } from "./errors.js";
+import { TUNNEL_ASSETS } from "./tunnel-assets.js";
+import { PtyTunnelTransport } from "./tunnel-pty.js";
+const READY = 1, OPEN = 2, DATA = 3, FIN = 4, RESET = 5, CREDIT = 6;
+const CHUNK = 65536, WINDOW = 4194304;
+export function tunnelTarget(target) {
+    const m = /^(?:\[([^\]]+)\]|([^\s:[\]]+)):([0-9]+)$/.exec(target);
+    const port = Number(m?.[3]);
+    if (!m || !Number.isInteger(port) || port < 1 || port > 65535)
+        throw new TypeError('target must be host:port or [IPv6]:port (1..65535)');
+    return { host: m[1] ?? m[2], port };
+}
+function frame(kind, id, body = Buffer.alloc(0)) {
+    const h = Buffer.alloc(9);
+    h[0] = kind;
+    h.writeUInt32BE(id, 1);
+    h.writeUInt32BE(body.length, 5);
+    return Buffer.concat([h, body]);
+}
+function retryable(e) {
+    if (e instanceof ShardfluxApiError)
+        return e.retryable || e.code === 'workspace_not_running' || e.reason === 'workspace_not_running';
+    return e instanceof TypeError || (e instanceof ShardfluxProtocolError && e.status === 0);
+}
+/** An owned foreground connection to the developer machine. Close in finally. */
+export class ReverseTunnel {
+    sessionId;
+    remotePort;
+    target;
+    transport;
+    closed;
+    #resolve;
+    #reject;
+    #ready;
+    #readyError;
+    #transport;
+    #dir;
+    #target;
+    #controller = new AbortController();
+    #peers = new Map();
+    #writes = [];
+    #sending = false;
+    #inputOffset = 0;
+    #nextInputOffset = 0;
+    #newWrites;
+    #outputOffset = 0;
+    #stderrOffset = 0;
+    #buffer = Buffer.alloc(0);
+    #stderr = '';
+    #closing;
+    #stats = { connections: 0, activeConnections: 0, bytesToTarget: 0, bytesToWorkspace: 0, reconnects: 0 };
+    #abort;
+    #signal;
+    constructor(transport, sessionId, dir, opts) {
+        this.#transport = transport;
+        this.sessionId = sessionId;
+        this.#dir = dir;
+        this.remotePort = opts.remotePort;
+        this.target = opts.target;
+        this.#target = tunnelTarget(opts.target);
+        this.transport = transport.kind ?? 'exec';
+        this.closed = new Promise((resolve, reject) => { this.#resolve = resolve; this.#reject = reject; });
+        // Ownership remains with the handle even when the caller observes failure later through closed.
+        void this.closed.catch(() => { });
+    }
+    get stats() { return { ...this.#stats, activeConnections: this.#peers.size }; }
+    /** Internal transport entry point, also exercised against the real helper in tests. */
+    static async attach(transport, sessionId, dir, opts) {
+        const t = new ReverseTunnel(transport, sessionId, dir, opts);
+        const ready = new Promise((resolve, reject) => { t.#ready = resolve; t.#readyError = reject; });
+        const timer = setTimeout(() => t.#fail(new Error('reverse tunnel listener did not become ready within 30 seconds')), 30_000);
+        t.#signal = opts.signal;
+        t.#abort = () => { void t.close().catch(() => { }); };
+        opts.signal?.addEventListener('abort', t.#abort, { once: true });
+        void t.#read().catch(e => t.#fail(e));
+        if (opts.signal?.aborted)
+            t.#fail(opts.signal.reason);
+        try {
+            await ready;
+            return t;
+        }
+        catch (e) {
+            await t.close();
+            throw e;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    #fail(e) {
+        if (this.#closing)
+            return;
+        this.#readyError(e);
+        void this.#teardown(e).catch(() => { });
+    }
+    #send(kind, id, body) {
+        if (this.#closing)
+            return Promise.reject(new Error('reverse tunnel is closed'));
+        const result = new Promise((resolve, reject) => { this.#writes.push({ bytes: frame(kind, id, body), resolve, reject }); });
+        this.#newWrites?.();
+        if (!this.#sending) {
+            this.#sending = true;
+            queueMicrotask(() => { void this.#flush().catch(e => this.#fail(e)); });
+        }
+        return result;
+    }
+    async #flush() {
+        const active = new Set();
+        while ((this.#writes.length || active.size) && !this.#closing) {
+            while (this.#writes.length && active.size < (this.#transport.maxInputConcurrency ?? 1)) {
+                const batch = [], complete = [], parts = [];
+                let size = 0;
+                while (this.#writes.length && size < 65536) {
+                    const w = this.#writes[0];
+                    const n = Math.min(w.bytes.length, 65536 - size);
+                    batch.push(w);
+                    parts.push(w.bytes.subarray(0, n));
+                    size += n;
+                    if (n === w.bytes.length) {
+                        this.#writes.shift();
+                        complete.push(w);
+                    }
+                    else
+                        w.bytes = w.bytes.subarray(n);
+                }
+                const bytes = Buffer.concat(parts);
+                const offset = this.#nextInputOffset;
+                this.#nextInputOffset += bytes.length;
+                const work = this.#writeBatch(bytes, offset).then(() => { for (const w of complete)
+                    w.resolve(); }, (e) => {
+                    for (const w of batch)
+                        w.reject(e);
+                    this.#fail(e);
+                });
+                active.add(work);
+                void work.then(() => active.delete(work));
+            }
+            if (active.size)
+                await Promise.race([...active, new Promise(resolve => { this.#newWrites = resolve; })]);
+        }
+        this.#newWrites = undefined;
+        this.#sending = false;
+    }
+    async #writeBatch(bytes, start) {
+        let sent = 0;
+        while (sent < bytes.length && !this.#closing) {
+            try {
+                const ack = await this.#transport.exec.input(this.sessionId, bytes.subarray(sent), { offset: start + sent, signal: this.#controller.signal });
+                const n = ack.offset - (start + sent);
+                if (!Number.isInteger(n) || n < 0 || n > bytes.length - sent || ack.closed)
+                    throw new Error('invalid reverse tunnel stdin acknowledgement');
+                sent += n;
+                this.#inputOffset = Math.max(this.#inputOffset, ack.offset);
+                if (n === 0)
+                    await delay(25, undefined, { signal: this.#controller.signal });
+            }
+            catch (e) {
+                if (!retryable(e) || this.#closing)
+                    throw e;
+                this.#stats.reconnects++;
+                await delay(250, undefined, { signal: this.#controller.signal });
+            }
+        }
+    }
+    async #read() {
+        while (!this.#closing) {
+            try {
+                const events = await this.#transport.exec.output(this.sessionId, { stdoutOffset: this.#outputOffset, stderrOffset: this.#stderrOffset, signal: this.#controller.signal });
+                for await (const ev of events) {
+                    if (this.#closing)
+                        return;
+                    if (ev.type === 'exit')
+                        throw new Error(`reverse tunnel forwarder exited${this.#stderr ? ': ' + this.#stderr : ''}`);
+                    if (ev.type === 'error') {
+                        if (ev.error)
+                            throw new ShardfluxApiError(502, ev.error, 'cell');
+                        throw new Error('reverse tunnel output failed without an error envelope');
+                    }
+                    if (ev.type !== 'output')
+                        continue;
+                    const bytes = Buffer.from(ev.data ?? '', 'base64');
+                    const stderr = ev.stream === 'stderr';
+                    const offset = stderr ? this.#stderrOffset : this.#outputOffset;
+                    const start = ev.offset ?? offset;
+                    if (start > offset)
+                        throw new Error('reverse tunnel output has a byte gap');
+                    const fresh = bytes.subarray(Math.min(bytes.length, Math.max(0, offset - start)));
+                    if (stderr) {
+                        this.#stderrOffset += fresh.length;
+                        this.#stderr = (this.#stderr + fresh.toString()).slice(-4096);
+                    }
+                    else {
+                        this.#outputOffset += fresh.length;
+                        this.#decode(fresh);
+                    }
+                }
+            }
+            catch (e) {
+                if (this.#closing)
+                    return;
+                if (!retryable(e))
+                    throw e;
+            }
+            this.#stats.reconnects++;
+            await delay(250, undefined, { signal: this.#controller.signal });
+        }
+    }
+    #decode(bytes) {
+        this.#buffer = Buffer.concat([this.#buffer, bytes]);
+        while (this.#buffer.length >= 9) {
+            const n = this.#buffer.readUInt32BE(5);
+            if (n > 65536)
+                throw new Error('oversized reverse tunnel frame');
+            if (this.#buffer.length < n + 9)
+                return;
+            const kind = this.#buffer[0];
+            const id = this.#buffer.readUInt32BE(1);
+            const body = this.#buffer.subarray(9, n + 9);
+            this.#buffer = this.#buffer.subarray(n + 9);
+            this.#dispatch(kind, id, body);
+        }
+    }
+    #dispatch(kind, id, body) {
+        if (kind === READY && id === 0 && body.length === 0) {
+            this.#ready();
+            return;
+        }
+        if (kind === OPEN && id !== 0 && body.length === 0) {
+            if (this.#peers.has(id) || this.#peers.size >= 128)
+                throw new Error('invalid reverse tunnel connection');
+            const socket = createConnection({ ...this.#target, allowHalfOpen: true });
+            const p = { socket, credit: WINDOW, receiveCredit: WINDOW, pendingCredit: 0, remoteEnded: false, localEnded: false };
+            this.#peers.set(id, p);
+            this.#stats.connections++;
+            socket.on('error', () => this.#reset(id));
+            // Normal TCP EOF can close the socket while #pump still awaits acknowledgement of its final chunk.
+            socket.on('close', () => { if (!socket.readableEnded && this.#peers.get(id) === p)
+                this.#reset(id); });
+            void this.#pump(id, p).catch(() => this.#reset(id));
+            return;
+        }
+        const p = this.#peers.get(id);
+        if (!p) {
+            if (![DATA, FIN, RESET, CREDIT].includes(kind))
+                throw new Error('unknown reverse tunnel frame');
+            return;
+        }
+        if (kind === DATA) {
+            if (!body.length || p.remoteEnded || body.length > p.receiveCredit)
+                throw new Error('reverse tunnel receive window overflow');
+            p.receiveCredit -= body.length;
+            this.#stats.bytesToTarget += body.length;
+            p.socket.write(body, (e) => {
+                if (e || this.#peers.get(id) !== p)
+                    return;
+                p.pendingCredit += body.length;
+                if (p.pendingCredit >= 262144) {
+                    const credit = Buffer.alloc(4);
+                    credit.writeUInt32BE(p.pendingCredit);
+                    p.receiveCredit += p.pendingCredit;
+                    p.pendingCredit = 0;
+                    void this.#send(CREDIT, id, credit).catch(e => this.#fail(e));
+                }
+            });
+        }
+        else if (kind === CREDIT) {
+            if (body.length !== 4 || !body.readUInt32BE(0) || p.credit + body.readUInt32BE(0) > WINDOW)
+                throw new Error('invalid reverse tunnel credit');
+            p.credit += body.readUInt32BE(0);
+            p.wake?.();
+        }
+        else if (kind === FIN && body.length === 0) {
+            if (p.remoteEnded)
+                throw new Error('duplicate reverse tunnel fin');
+            p.remoteEnded = true;
+            p.socket.end();
+            this.#ended(id, p);
+        }
+        else if (kind === RESET && body.length === 0)
+            this.#reset(id, false);
+        else
+            throw new Error('invalid reverse tunnel frame');
+    }
+    async #pump(id, p) {
+        const pending = [];
+        for await (const value of p.socket) {
+            const bytes = Buffer.isBuffer(value) ? value : Buffer.from(value);
+            let pos = 0;
+            while (pos < bytes.length && this.#peers.get(id) === p && !this.#closing) {
+                if (!p.credit)
+                    await new Promise(resolve => { p.wake = resolve; });
+                if (this.#peers.get(id) !== p || this.#closing)
+                    return;
+                const n = Math.min(CHUNK, p.credit, bytes.length - pos);
+                p.credit -= n;
+                if (this.#transport.kind === 'pty') {
+                    const write = this.#send(DATA, id, bytes.subarray(pos, pos + n));
+                    void write.catch(() => { });
+                    pending.push(write);
+                    if (pending.length >= 128)
+                        await Promise.all(pending.splice(0));
+                }
+                else
+                    await this.#send(DATA, id, bytes.subarray(pos, pos + n));
+                pos += n;
+                this.#stats.bytesToWorkspace += n;
+            }
+        }
+        if (this.#peers.get(id) !== p || this.#closing)
+            return;
+        await Promise.all(pending);
+        // A guest can release this connection and accept the next before the HTTP stdin acknowledgement arrives.
+        p.localEnded = true;
+        this.#ended(id, p);
+        await this.#send(FIN, id);
+    }
+    #ended(id, p) { if (p.localEnded && p.remoteEnded) {
+        this.#peers.delete(id);
+        p.wake?.();
+    } }
+    #reset(id, notify = true) {
+        const p = this.#peers.get(id);
+        if (!p)
+            return;
+        this.#peers.delete(id);
+        p.wake?.();
+        p.socket.destroy();
+        if (notify && !this.#closing)
+            void this.#send(RESET, id).catch(e => this.#fail(e));
+    }
+    close() { return this.#teardown(); }
+    #teardown(failure) {
+        if (this.#closing)
+            return this.#closing;
+        this.#closing = (async () => {
+            // Yield so #closing is set before output abort and socket callbacks run.
+            await Promise.resolve();
+            this.#readyError(failure ?? new Error('reverse tunnel closed before ready'));
+            this.#controller.abort();
+            this.#newWrites?.();
+            if (this.#abort)
+                this.#signal?.removeEventListener('abort', this.#abort);
+            for (const id of this.#peers.keys())
+                this.#reset(id, false);
+            for (const w of this.#writes.splice(0))
+                w.reject(new Error('reverse tunnel closed'));
+            const errors = failure === undefined ? [] : [failure];
+            try {
+                await this.#transport.exec.cancel(this.sessionId, 1000);
+            }
+            catch (e) {
+                errors.push(e);
+            }
+            try {
+                await this.#transport.files.remove(this.#dir, { recursive: true });
+            }
+            catch (e) {
+                errors.push(e);
+            }
+            if (errors.length) {
+                const e = new AggregateError(errors, 'reverse tunnel ended with errors');
+                this.#reject(e);
+                throw e;
+            }
+            this.#resolve();
+        })();
+        return this.#closing;
+    }
+}
+/** Workspace → this client's machine; unused workspaces pay no tunnel setup or lifecycle cost. */
+export class WorkspaceTunnels {
+    #cell;
+    #grants;
+    #owned = new Set();
+    constructor(cell, grants = () => null) { this.#cell = cell; this.#grants = grants; }
+    async reverse(opts) {
+        tunnelTarget(opts.target);
+        if (!Number.isInteger(opts.remotePort) || opts.remotePort < 1 || opts.remotePort > 65535)
+            throw new TypeError('remotePort must be 1..65535');
+        const bind = opts.bindAddress ?? '127.0.0.1';
+        if (bind !== '127.0.0.1' && bind !== '0.0.0.0')
+            throw new TypeError('bindAddress must be 127.0.0.1 or 0.0.0.0');
+        const choice = opts.transport ?? 'auto';
+        if (!['auto', 'pty', 'exec'].includes(choice))
+            throw new TypeError('transport must be auto, pty or exec');
+        opts.signal?.throwIfAborted();
+        const cell = this.#cell();
+        const archResult = await cell.exec.run(['uname', '-m'], { signal: opts.signal, timeoutMs: 5000 });
+        const arch = archResult.stdout.trim();
+        if (arch !== 'x86_64' && arch !== 'aarch64')
+            throw new Error(`reverse tunnel: unsupported guest architecture ${arch}`);
+        const asset = TUNNEL_ASSETS[arch];
+        const binary = gunzipSync(readFileSync(new URL(`./tunnel-assets/${asset.file}`, import.meta.url)));
+        if (createHash('sha256').update(binary).digest('hex') !== asset.sha256)
+            throw new Error('reverse tunnel helper checksum mismatch');
+        const dir = `/tmp/shardflux-tunnel-${randomUUID()}`;
+        const sessionId = randomUUID().replaceAll('-', '');
+        const fast = choice === 'pty' || (choice === 'auto' && this.#grants()?.includes('pty'));
+        const transport = fast ? new PtyTunnelTransport(cell) : cell;
+        let startAttempted = false, attached = false;
+        try {
+            await cell.files.mkdir(dir, { mode: '0700' });
+            await cell.files.write(`${dir}/forwarder`, binary, { mode: '0700' });
+            startAttempted = true;
+            const argv = [`${dir}/forwarder`, '--port', String(opts.remotePort), '--bind', bind];
+            const session = fast
+                ? await cell.pty.open({ session_id: sessionId, argv: ['bash', '-c', 'stty raw -echo; exec "$@"', 'sh', ...argv, '--packets'] })
+                : await cell.exec.start({ session_id: sessionId, argv, stdin_open: true }, opts.signal);
+            if (session.state === 'failed_to_start')
+                throw new Error(`reverse tunnel could not start: ${session.error ?? ''}`);
+            attached = true;
+            const tunnel = await ReverseTunnel.attach(transport, sessionId, dir, opts);
+            this.#owned.add(tunnel);
+            void tunnel.closed.finally(() => this.#owned.delete(tunnel)).catch(() => { });
+            return tunnel;
+        }
+        catch (e) {
+            if (attached)
+                throw e; // attach() already owns teardown and reports its errors.
+            // A start may have reached the guest even if its answer was lost.
+            const errors = [e];
+            if (startAttempted) {
+                try {
+                    await transport.exec.cancel(sessionId, 1000);
+                }
+                catch (cleanup) {
+                    if (!(cleanup instanceof ShardfluxApiError && cleanup.status === 404))
+                        errors.push(cleanup);
+                }
+            }
+            try {
+                await cell.files.remove(dir, { recursive: true });
+            }
+            catch (cleanup) {
+                if (!(cleanup instanceof ShardfluxApiError && cleanup.status === 404))
+                    errors.push(cleanup);
+            }
+            if (errors.length > 1)
+                throw new AggregateError(errors, 'reverse tunnel startup cleanup failed', { cause: e });
+            throw e;
+        }
+    }
+    async close() {
+        const results = await Promise.allSettled([...this.#owned].map(t => t.close()));
+        const errors = results.filter((r) => r.status === 'rejected').map(r => r.reason);
+        if (errors.length)
+            throw new AggregateError(errors, 'reverse tunnel cleanup failed');
+    }
+}

package/dist/workspace-ref.d.ts

@@ -66,6 +66,10 @@ export declare class WorkspaceRef implements ToolTarget {
         agentLabel?: string;
         tools?: ToolName[];
     } & CellClientOptions): Promise<CellClient>;
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    turn<T>(fn: (workspace: this) => T | Promise<T>, { afterSeconds }?: {
+        afterSeconds?: number;
+    }): Promise<T>;
     /**
      * 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()`.

package/dist/workspace-ref.js

@@ -110,6 +110,30 @@ export class WorkspaceRef {
     async cell(opts = {}) {
         return (await this.open()).cell(opts);
     }
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    async turn(fn, { afterSeconds = 0 } = {}) {
+        void this.hint().catch(() => undefined);
+        let result;
+        let failure;
+        let failed = false;
+        try {
+            result = await fn(this);
+        }
+        catch (err) {
+            failed = true;
+            failure = err;
+        }
+        try {
+            await this.#use((ws) => ws.suspendWhenIdle({ afterSeconds }));
+        }
+        catch (err) {
+            if (!failed)
+                throw err;
+        }
+        if (failed)
+            throw failure;
+        return result;
+    }
     /**
      * 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()`.

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, ComputerUse, 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, RetentionPolicy, 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';
@@ -12,6 +12,7 @@ import { Trace } from './progress.js';
 import type { LifecycleTiming, ProgressListener } from './progress.js';
 import { WorkspaceComputer } from './computer.js';
 import { WorkspacePorts } from './ports.js';
+import { WorkspaceTunnels } from './tunnels.js';
 import { WorkspaceSecrets } from './secrets.js';
 import type { CellClientOptions, Residency, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
 import type { SaveAsTemplateParams, SaveAsTemplateResponse, WorkspaceStartup } from './templates.js';
@@ -91,6 +92,8 @@ export declare class Workspace {
     get cellEndpoint(): string | null;
     /** Actual grants reported by the cell for the running workspace (null until known). */
     get grants(): WorkspaceView['grants'];
+    /** Stored caps every later start uses, as of the latest workspace view. */
+    get caps(): WorkspaceView['caps'];
     get ceilings(): WorkspaceView['ceilings'];
     get template(): WorkspaceView['template'];
     /**
@@ -168,6 +171,8 @@ export declare class Workspace {
      *   const link = await workspace.ports.link(3000);            // open link.url in a browser
      */
     get ports(): WorkspacePorts;
+    /** Forward a guest TCP port to this machine. Close the returned handle in finally. */
+    get tunnels(): WorkspaceTunnels;
     /**
      * 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
@@ -186,6 +191,8 @@ export declare class Workspace {
     inputs(): Promise<Record<string, string>>;
     get labels(): Record<string, string>;
     setLabels(labels: Record<string, string>): Promise<this>;
+    get retention(): WorkspaceView['retention'];
+    setRetention(policy: RetentionPolicy | null): Promise<this>;
     setIdlePolicy(policy: IdlePolicy | null): Promise<this>;
     idle(signal?: AbortSignal): ReturnType<CellClient['idle']>;
     keepalive(seconds: number, signal?: AbortSignal): ReturnType<CellClient['keepalive']>;
@@ -300,6 +307,12 @@ export declare class Workspace {
      * confirm_destructive). Returns the `reset` operation: requested, or with `{ wait: true }` finished. Tool tokens of
      * the old epoch are dropped.
      */
+    /** Upgrade in place: keep files/packages/home; cold start drops memory and processes. */
+    upgrade(opts?: LifecycleOptions & {
+        at?: 'now' | 'next_resume';
+    }): Promise<Operation>;
+    get upgradeAvailable(): WorkspaceView['upgrade_available'];
+    get upgradePending(): WorkspaceView['upgrade_pending'];
     reset(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
     reset(opts?: LifecycleOptions): Promise<Operation>;
     /**
@@ -363,6 +376,10 @@ export declare class Workspace {
      * (`server.memoryRestored === false`, `server.resumePath` `cold_boot`, `server.coldBootReason`).
      */
     wake(opts?: WakeOptions): Promise<boolean>;
+    /** Hints without waiting, runs the turn, and requests idle suspension even if the body throws. */
+    turn<T>(fn: (workspace: this) => T | Promise<T>, { afterSeconds }?: {
+        afterSeconds?: number;
+    }): Promise<T>;
     /**
      * Announces an imminent tool call (cell `POST /wake-hint`; 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