@shardflux/sdk 0.14.0 → 0.16.0

package/dist/testing/index.d.ts

@@ -0,0 +1,62 @@
+/** In-memory transport for the real SDK. Import only from @shardflux/sdk/testing. */
+import { Shardflux } from '../client.js';
+import type { WorkspaceView } from '../client.js';
+import type { ExecStartRequest } from '../cell.js';
+export interface FakeExecResult {
+    stdout?: string;
+    stderr?: string;
+    exitCode?: number;
+    termSignal?: number;
+    timedOut?: boolean;
+    canceled?: boolean;
+}
+export interface FakeWorkspaceFaults {
+    busy?: boolean;
+    deleted?: boolean;
+    failed?: boolean;
+    legacyLayout?: boolean;
+    computerUnavailable?: boolean;
+    resizeRefusal?: 'shrink_not_supported' | 'resize_not_available' | null;
+    /** A plan clamps the requested size; it does not invent a validation error. */
+    memoryLimitMib?: number;
+}
+export interface FakeShardfluxOptions {
+    /** Explicit command results. null leaves a command running until testing.completeCommand(). */
+    onExec?: (request: ExecStartRequest, workspace: WorkspaceView) => FakeExecResult | null;
+    nowMs?: number;
+    latencyMs?: number;
+    /** Replace the latency wait, e.g. advance a test runner's clock. */
+    sleep?: (ms: number) => Promise<void>;
+    quota?: 'retained_state' | 'concurrent_workspaces' | null;
+    faults?: FakeWorkspaceFaults;
+    templates?: Record<string, {
+        desktop: boolean;
+        memoryMib?: number;
+        cpuMillis?: number;
+        diskGib?: number;
+    }>;
+}
+export declare class FakeUnsupportedError extends Error {
+    constructor(operation: string);
+}
+/** Controls are separate from the customer client surface; inspect() returns a copy. */
+export declare class FakeShardfluxTesting {
+    #private;
+    readonly requests: {
+        method: string;
+        path: string;
+        query: string;
+    }[];
+    quota: FakeShardfluxOptions['quota'];
+    latencyMs: number;
+    constructor(options: FakeShardfluxOptions);
+    inspect(id: string): WorkspaceView;
+    setFaults(id: string, faults: FakeWorkspaceFaults): void;
+    advance(ms: number): void;
+    completeCommand(id: string, sessionId: string, result?: FakeExecResult): void;
+    readonly fetch: typeof fetch;
+}
+/** A real Shardflux client using an isolated in-memory HTTP transport; no request reaches the network. */
+export declare function createFakeShardflux(options?: FakeShardfluxOptions): Shardflux & {
+    testing: FakeShardfluxTesting;
+};

package/dist/testing/index.js

@@ -0,0 +1,585 @@
+/** In-memory transport for the real SDK. Import only from @shardflux/sdk/testing. */
+import { Shardflux } from "../client.js";
+import { createHash } from 'node:crypto';
+import { constants } from 'node:os';
+import { matchesGlob } from 'node:path';
+import { seed } from "./seed.js";
+export class FakeUnsupportedError extends Error {
+    constructor(operation) {
+        super(`Shardflux fake has no scripted implementation for ${operation}`);
+        this.name = 'FakeUnsupportedError';
+    }
+}
+const clone = (x) => structuredClone(x);
+const json = (body, status = 200, headers = {}) => new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json', ...headers } });
+const error = (status, code, message, details) => json({ error: { code, message, request_id: 'fake-request', retryable: false, ...(details ? { details } : {}) } }, status);
+const capturedError = (body, status) => json(body, status);
+const stamp = (ms) => new Date(ms).toISOString();
+/** Controls are separate from the customer client surface; inspect() returns a copy. */
+export class FakeShardfluxTesting {
+    requests = [];
+    #options;
+    #stored = new Map();
+    #operations = new Map();
+    #counter = 0;
+    #now;
+    quota;
+    latencyMs;
+    constructor(options) {
+        this.#options = options;
+        this.#now = options.nowMs ?? Date.UTC(2026, 9, 4);
+        this.quota = options.quota;
+        this.latencyMs = options.latencyMs ?? 0;
+    }
+    #id() { return `00000000-0000-7000-8000-${(++this.#counter).toString(16).padStart(12, '0')}`; }
+    #get(id) {
+        const ws = this.#stored.get(id);
+        if (!ws)
+            throw new Error(`Unknown fake workspace ${id}`);
+        return ws;
+    }
+    inspect(id) { return clone(this.#get(id).view); }
+    setFaults(id, faults) {
+        const ws = this.#get(id);
+        ws.faults = { ...ws.faults, ...faults };
+        if (faults.deleted)
+            this.#delete(ws);
+        if (faults.failed)
+            ws.view.observed_state = 'failed';
+        if (faults.legacyLayout !== undefined)
+            ws.view.disk_layout = faults.legacyLayout ? 'legacy' : 'layered';
+        if (faults.computerUnavailable !== undefined) {
+            ws.view.computer_use.available = !faults.computerUnavailable;
+            ws.view.computer_use.enabled = !faults.computerUnavailable && (ws.view.computer_use.workspace ?? ws.view.computer_use.template);
+        }
+    }
+    advance(ms) {
+        if (!Number.isFinite(ms) || ms < 0)
+            throw new TypeError('advance needs nonnegative milliseconds');
+        this.#now += ms;
+        for (const ws of this.#stored.values())
+            this.#evaluate(ws);
+    }
+    #busy(ws) { return ws.faults.busy === true || [...ws.commands.values()].some((c) => c.session.state === 'running') || ws.keepalive > this.#now; }
+    #evaluate(ws) {
+        if (ws.view.deleted_at !== null)
+            return;
+        if (ws.view.lifetime === 'session' && !this.#busy(ws) && this.#now >= ws.lastTool + (ws.view.idle_timeout_seconds ?? 600) * 1000) {
+            this.#delete(ws);
+            ws.view.ended_reason = 'idle_timeout';
+        }
+        else if (ws.suspendAfter !== null && !this.#busy(ws) && this.#now >= Math.max(ws.lastTool, ws.requestedAt, ws.keepalive) + ws.suspendAfter * 1000) {
+            this.#state(ws, 'suspended');
+            ws.suspendAfter = null;
+            if (ws.view.idle)
+                ws.view.idle.suspend_request = null;
+        }
+    }
+    #state(ws, state) {
+        if (state === 'running' && ws.view.observed_state !== 'running') {
+            for (const [key, value] of ws.pending) {
+                Object.assign(ws.view.grants, { [key]: value });
+                ws.sizes[key] = value;
+            }
+            if (ws.pending.has('memory_mib')) {
+                const memory = ws.pending.get('memory_mib');
+                const mode = ws.view.caps.allocation_mode;
+                if (mode === 'elastic')
+                    Object.assign(ws.view.grants, { memory_mib: ws.view.caps.memory_mib_held ?? 1024, memory_mib_max: memory, memory_mib_held: ws.view.caps.memory_mib_held ?? 1024 });
+                ws.view.memory = { allocation_mode: mode, promised_mib: memory, held_mib: mode === 'elastic' ? ws.view.caps.memory_mib_held ?? 1024 : memory, plugged_mib: mode === 'elastic' ? 0 : null };
+            }
+            ws.pending.clear();
+        }
+        ws.view.observed_state = state;
+        ws.view.desired_state = state;
+        ws.view.updated_at = stamp(this.#now);
+    }
+    #delete(ws) {
+        this.#state(ws, 'deleted');
+        ws.view.deleted_at = stamp(this.#now);
+        for (const c of ws.commands.values()) {
+            if (c.session.state === 'running')
+                this.#finish(c, { canceled: true, termSignal: 15 });
+        }
+    }
+    #activity(ws) {
+        ws.lastTool = this.#now;
+        ws.suspendAfter = null;
+        if (ws.view.idle)
+            ws.view.idle.suspend_request = null;
+    }
+    #op(ws, kind, result = {}) {
+        const op = { id: this.#id(), kind, state: 'succeeded', workspace_id: ws.view.id, created_at: stamp(this.#now), updated_at: stamp(this.#now), started_at: stamp(this.#now), completed_at: stamp(this.#now), result };
+        this.#operations.set(op.id, op);
+        return op;
+    }
+    #token(ws, body) {
+        const tools = (Array.isArray(body.tools) ? body.tools : ['exec', 'files', 'processes', 'computer']).filter((t) => t !== 'computer' || ws.view.computer_use.enabled);
+        return { ...clone(seed.token), workspace_id: ws.view.id, tools, cell_endpoint: ws.view.cell_endpoint, ownership_epoch: ws.view.ownership_epoch };
+    }
+    #idle(ws) {
+        const horizons = [...ws.commands.values()].filter((c) => c.session.state === 'running').map((c) => c.until);
+        const since = Math.max(ws.lastTool, ws.keepalive, ...horizons, ws.faults.busy ? this.#now + 3600000 : 0);
+        return { ...clone(seed.idle), observed_state: ws.view.observed_state, last_tool_at: stamp(ws.lastTool), running_since: ws.view.created_at, idle_since: stamp(since), keepalive_until: ws.keepalive ? stamp(ws.keepalive) : null, suspend_request: ws.view.idle?.suspend_request ?? null, suspend_at: ws.suspendAfter === null ? null : stamp(Math.max(since, ws.requestedAt) + ws.suspendAfter * 1000) };
+    }
+    #finish(c, result) {
+        c.stdout = result.stdout ?? '';
+        c.stderr = result.stderr ?? '';
+        c.session = { ...c.session, state: 'exited', created: false, exit_code: result.exitCode ?? (result.termSignal ? -1 : 0), ...(result.termSignal ? { term_signal: result.termSignal } : {}), timed_out: result.timedOut ?? false, canceled: result.canceled ?? false, stdout_size: Buffer.byteLength(c.stdout), stderr_size: Buffer.byteLength(c.stderr), ended_at: stamp(this.#now) };
+        for (const listener of c.listeners)
+            listener();
+    }
+    completeCommand(id, sessionId, result = {}) {
+        const ws = this.#get(id);
+        const c = ws.commands.get(sessionId);
+        if (!c)
+            throw new Error(`Unknown fake command ${sessionId}`);
+        this.#finish(c, result);
+        ws.lastTool = this.#now;
+        this.#evaluate(ws);
+    }
+    #output(c, url, signal) {
+        const encoder = new TextEncoder();
+        const stream = new ReadableStream({
+            start: (controller) => {
+                let ended = false;
+                const done = () => {
+                    if (ended || c.session.state === 'running')
+                        return;
+                    ended = true;
+                    c.listeners.delete(done);
+                    signal?.removeEventListener('abort', abort);
+                    for (const name of ['stdout', 'stderr']) {
+                        const offset = Number(url.searchParams.get(`${name}_offset`) ?? 0);
+                        const data = Buffer.from(c[name]).subarray(offset);
+                        if (data.length)
+                            controller.enqueue(encoder.encode(JSON.stringify({ type: 'output', stream: name, offset, data: data.toString('base64') }) + '\n'));
+                    }
+                    controller.enqueue(encoder.encode(JSON.stringify({ type: 'exit', session: c.session }) + '\n'));
+                    controller.close();
+                };
+                const abort = () => { if (!ended) {
+                    ended = true;
+                    c.listeners.delete(done);
+                    controller.error(signal?.reason ?? new Error('aborted'));
+                } };
+                if (signal?.aborted)
+                    abort();
+                else {
+                    signal?.addEventListener('abort', abort, { once: true });
+                    c.listeners.add(done);
+                    done();
+                }
+            },
+        });
+        return new Response(stream, { headers: { 'content-type': 'application/x-ndjson' } });
+    }
+    fetch = async (input, init) => {
+        const url = new URL(input instanceof Request ? input.url : String(input));
+        const method = init?.method ?? (input instanceof Request ? input.method : 'GET');
+        this.requests.push({ method, path: url.pathname, query: url.search });
+        if (this.latencyMs > 0) {
+            await (this.#options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))))(this.latencyMs);
+        }
+        init?.signal?.throwIfAborted();
+        const body = typeof init?.body === 'string' && new Headers(init.headers).get('content-type')?.startsWith('application/json') ? JSON.parse(init.body) : {};
+        const path = url.pathname;
+        if (path === '/healthz')
+            return json({ ok: true });
+        if (path === '/v1/me')
+            return json(seed.me);
+        if (path === '/v1/workspaces/open' && method === 'POST')
+            return this.#open(body);
+        if (path === '/v1/workspaces' && method === 'GET')
+            return this.#list(url);
+        const op = /^\/v1\/operations\/(.+)$/.exec(path);
+        if (op)
+            return this.#operations.has(op[1]) ? json({ operation: this.#operations.get(op[1]) }) : error(404, 'not_found', 'Operation not found.');
+        const match = /^\/v1\/workspaces\/([^/]+)(.*)$/.exec(path);
+        if (!match)
+            throw new FakeUnsupportedError(`${method} ${path}`);
+        const ws = this.#stored.get(match[1]);
+        const tail = match[2];
+        if (!ws)
+            return error(404, 'not_found', 'Workspace not found.');
+        this.#evaluate(ws);
+        const cell = url.hostname === 'cell.fake.invalid';
+        if (ws.view.deleted_at !== null && (cell || (tail !== '' && tail !== '/delete' && tail !== '/close')))
+            return cell ? error(404, 'not_found', 'Workspace not found.') : capturedError(seed.gone, 409);
+        if (cell && ws.view.observed_state !== 'running' && tail !== '/idle')
+            return error(409, 'workspace_not_running', 'Workspace is not running.', { reason: 'workspace_not_running' });
+        if (!tail && method === 'GET')
+            return json(ws.view);
+        if (tail === '/tool-tokens')
+            return json(this.#token(ws, body), 201);
+        if (tail === '/labels' && method === 'PUT') {
+            ws.view.labels = clone(body.labels);
+            return json(ws.view);
+        }
+        if (tail === '/computer-use' && method === 'PUT') {
+            if (body.enabled && !ws.view.computer_use.available)
+                return capturedError(seed.computerUnavailable, 409);
+            ws.view.computer_use.workspace = body.enabled;
+            ws.view.computer_use.enabled = ws.view.computer_use.available && (ws.view.computer_use.workspace ?? ws.view.computer_use.template);
+            return json(ws.view.computer_use);
+        }
+        if ((!tail && method === 'DELETE') || tail === '/delete' || tail === '/close') {
+            this.#delete(ws);
+            if (tail === '/close')
+                ws.view.ended_reason = 'closed';
+            return json({ workspace: ws.view, operation: this.#op(ws, 'delete') }, 202);
+        }
+        if (tail === '/resume') {
+            this.#state(ws, 'running');
+            this.#activity(ws);
+            return json({ workspace: ws.view, operation: this.#op(ws, 'resume'), tool_token: this.#token(ws, body) }, 200, { 'preference-applied': 'wait=20' });
+        }
+        if (tail === '/suspend' || tail === '/suspend-when-idle')
+            return this.#suspend(ws, tail, method, body);
+        if (tail === '/caps' && method === 'PATCH')
+            return this.#resize(ws, body);
+        if (tail === '/wake-hint')
+            return json({ residency: 'resident' });
+        if (tail === '/idle')
+            return json(this.#idle(ws));
+        if (tail === '/keepalive') {
+            ws.keepalive = Math.max(ws.keepalive, this.#now + Number(body.seconds) * 1000);
+            return json({ keepalive_until: stamp(ws.keepalive) });
+        }
+        if (tail.startsWith('/exec'))
+            return this.#exec(ws, tail, method, body, url, init);
+        if (tail.startsWith('/files')) {
+            this.#activity(ws);
+            return this.#files(ws, tail, method, body, url, init);
+        }
+        if (tail.startsWith('/computer')) {
+            this.#activity(ws);
+            return this.#computer(ws, tail, method, body);
+        }
+        if (tail.startsWith('/ports'))
+            return this.#ports(ws, tail, method, body);
+        throw new FakeUnsupportedError(`${method} ${path}`);
+    };
+    #open(body) {
+        if (body.retention !== undefined)
+            throw new FakeUnsupportedError('open.retention (extend from a live capture)');
+        let ws = [...this.#stored.values()].find((s) => s.view.workspace_key === body.key && s.view.deleted_at === null);
+        const created = !ws;
+        if (this.quota && (!ws || this.quota === 'concurrent_workspaces'))
+            return error(403, 'quota_exceeded', 'The plan limit has been reached.', { limit: this.quota, limit_value: 1, current: 1, plan: 'free' });
+        if (ws) {
+            if (body.lifetime && body.lifetime !== ws.view.lifetime)
+                return error(409, 'conflict', 'Workspace lifetime differs.', { reason: 'lifetime_mismatch' });
+            this.#state(ws, 'running');
+            this.#activity(ws);
+            if (body.labels)
+                ws.view.labels = clone(body.labels);
+        }
+        else {
+            if (body.mode === 'file_first')
+                throw new FakeUnsupportedError('file_first workspaces');
+            const templates = this.#options.templates ?? { 'python-node-browser': { desktop: true }, 'ubuntu-24.04': { desktop: false }, default: { desktop: true } };
+            const template = templates[String(body.template)];
+            if (!template)
+                throw new FakeUnsupportedError(`template ${String(body.template)} (configure options.templates)`);
+            const view = clone(seed.workspace);
+            view.id = this.#id();
+            view.workspace_key = String(body.key);
+            view.labels = clone((body.labels ?? {}));
+            view.created_at = view.updated_at = stamp(this.#now);
+            view.project_id = body.project_id ?? view.project_id;
+            const slug = body.template === 'default' ? 'python-node-browser' : String(body.template);
+            view.template = clone(seed.templateViews[slug] ?? view.template);
+            view.template.slug = slug;
+            view.template_version_id = view.template.version_id;
+            view.lifetime = body.lifetime === 'session' ? 'session' : 'persistent';
+            view.idle_timeout_seconds = view.lifetime === 'session' ? 600 : null;
+            view.idle = view.lifetime === 'session' ? null : { policy: 'adaptive', source: 'default', mode: 'adaptive', timeout_seconds: null, basis: null, next_eligible_at: null, suspend_request: null };
+            view.caps = { ...clone(seed.defaultWorkspace.caps), ...(body.caps ?? {}) };
+            if (view.caps.allocation_mode === 'fixed')
+                delete view.caps.memory_mib_held;
+            const memory = view.caps.memory_mib ?? template.memoryMib ?? 8192;
+            const held = view.caps.allocation_mode === 'elastic' ? view.caps.memory_mib_held ?? 1024 : memory;
+            view.memory = { allocation_mode: view.caps.allocation_mode, promised_mib: memory, held_mib: held, plugged_mib: view.caps.allocation_mode === 'elastic' ? 0 : null };
+            view.grants = { ...clone(view.caps.allocation_mode === 'elastic' ? seed.defaultWorkspace.grants : seed.workspace.grants), memory_mib: held, ...(view.caps.allocation_mode === 'elastic' ? { memory_mib_max: memory, memory_mib_held: held } : {}), cpu_millis: view.caps.cpu_millis ?? template.cpuMillis ?? 4000, disk_gib: view.caps.disk_gib ?? template.diskGib ?? 20, allocation_mode: view.caps.allocation_mode };
+            view.ceilings = { cpu_millis: Number(view.grants.cpu_millis), memory_mib: memory, disk_gib: Number(view.grants.disk_gib), sources: { cpu_millis: view.caps.cpu_millis === null ? 'plan' : 'user', memory_mib: view.caps.memory_mib === null ? 'plan' : 'user', disk_gib: view.caps.disk_gib === null ? 'plan' : 'user' }, resolved_at: stamp(this.#now) };
+            view.computer_use = { available: template.desktop, workspace: body.computer_use ?? null, template: false, enabled: template.desktop && body.computer_use === true };
+            if (body.computer_use && !template.desktop)
+                return capturedError(seed.computerUnavailable, 409);
+            ws = { view, files: new Map(), dirs: new Set(['/home/user', '/tmp', '/']), commands: new Map(), faults: { ...this.#options.faults }, lastTool: this.#now, keepalive: 0, suspendAfter: null, requestedAt: 0, computerRunning: false, streams: { view: false, interactive: false }, ports: new Map(), pending: new Map(), sizes: { cpu_millis: Number(view.grants.cpu_millis), disk_gib: Number(view.grants.disk_gib) } };
+            this.#stored.set(view.id, ws);
+            this.setFaults(view.id, ws.faults);
+        }
+        return json({ workspace: ws.view, operation: null, tool_token: this.#token(ws, body), created });
+    }
+    #list(url) {
+        const q = url.searchParams;
+        const labels = JSON.parse(q.get('labels') ?? '{}');
+        const all = [...this.#stored.values()].filter(({ view: v }) => (q.get('include_deleted') === 'true' || !v.deleted_at) && v.workspace_key.startsWith(q.get('key_prefix') ?? '') && (q.get('lifetime') === 'any' || v.lifetime === (q.get('lifetime') ?? 'persistent')) && (q.get('purpose') === 'any' || v.purpose === (q.get('purpose') ?? 'standard')) && (!q.get('state') || v.observed_state === q.get('state')) && (!q.get('desired_state') || v.desired_state === q.get('desired_state')) && (!q.get('project_id') || v.project_id === q.get('project_id')));
+        // All supplied labels match exactly; page cursors are opaque to customers.
+        const filtered = all.filter(({ view }) => Object.entries(labels).every(([k, v]) => view.labels[k] === v));
+        const offset = Number(q.get('cursor') ?? 0);
+        const limit = Number(q.get('limit') ?? 100);
+        return json({ data: filtered.slice(offset, offset + limit).map((s) => s.view), next_cursor: offset + limit < filtered.length ? String(offset + limit) : null });
+    }
+    #suspend(ws, tail, method, body) {
+        if (method === 'DELETE') {
+            ws.suspendAfter = null;
+            if (ws.view.idle)
+                ws.view.idle.suspend_request = null;
+            return json(ws.view);
+        }
+        if (ws.view.lifetime === 'session')
+            return capturedError(seed.sessionLifetime, 409);
+        if (tail === '/suspend') {
+            this.#state(ws, 'suspended');
+            return json({ operation: this.#op(ws, 'suspend', { durable: true }), workspace: ws.view }, 202);
+        }
+        const seconds = Number(body.after_seconds);
+        if (!Number.isInteger(seconds) || seconds < 0 || seconds > 3600)
+            return error(422, 'validation_failed', 'after_seconds must be between 0 and 3600.', { field: 'after_seconds' });
+        if (ws.view.observed_state !== 'running')
+            return error(409, 'conflict', 'Workspace is not running.', { reason: 'not_running' });
+        ws.suspendAfter = seconds;
+        ws.requestedAt = this.#now;
+        const request = { requested_at: stamp(this.#now), after_seconds: seconds, not_before: stamp(this.#now + seconds * 1000) };
+        if (ws.view.idle)
+            ws.view.idle.suspend_request = request;
+        this.#evaluate(ws);
+        const suspended = ws.view.desired_state === 'suspended';
+        return json({ workspace: ws.view, suspend_request: suspended ? null : request, operation: suspended ? this.#op(ws, 'suspend', { durable: true }) : null }, 202);
+    }
+    #resize(ws, body) {
+        if (body.at_least === true)
+            throw new FakeUnsupportedError('resize mode at_least (extend from a live capture)');
+        if (ws.faults.resizeRefusal === 'resize_not_available')
+            return error(409, 'conflict', 'Resize is not enabled.', { reason: 'resize_not_available' });
+        const currentDisk = ws.sizes.disk_gib ?? 20;
+        if (ws.faults.resizeRefusal === 'shrink_not_supported' || (body.disk_gib !== undefined && Number(body.disk_gib) < currentDisk))
+            return error(422, 'validation_failed', `The disk can only grow: it is ${currentDisk} GiB.`, { field: 'disk_gib', reason: 'shrink_not_supported', current_disk_gib: currentDisk });
+        const out = { workspace_id: ws.view.id, operation_id: this.#id(), state: ws.view.observed_state, memory: null, cpu: null, disk: null };
+        const at = ws.view.observed_state === 'suspended' ? 'resume' : ws.faults.legacyLayout ? 'next_start' : 'now';
+        const reason = at === 'resume' ? 'suspended' : at === 'next_start' ? 'legacy_layout' : null;
+        const mode = body.allocation_mode ?? ws.view.caps.allocation_mode;
+        if (body.memory_mib_held !== undefined && mode !== 'elastic')
+            return error(422, 'validation_failed', 'memory_mib_held requires elastic memory.', { field: 'memory_mib_held', reason: 'requires_elastic' });
+        const memory = Number(body.memory_mib ?? ws.view.memory.promised_mib);
+        if (body.memory_mib_held !== undefined && Number(body.memory_mib_held) > memory)
+            return error(422, 'validation_failed', 'The held floor exceeds maximum memory.', { field: 'memory_mib_held', reason: 'exceeds_memory_mib', memory_mib: memory });
+        for (const [resource, key, suffix] of [['memory', 'memory_mib', 'mib'], ['cpu', 'cpu_millis', 'millis'], ['disk', 'disk_gib', 'gib']]) {
+            if (body[key] === undefined && !(resource === 'memory' && (body.allocation_mode !== undefined || body.memory_mib_held !== undefined)))
+                continue;
+            const requested = Number(body[key] ?? ws.view.memory.promised_mib);
+            const previous = resource === 'memory' ? ws.view.memory.promised_mib : ws.sizes[key];
+            const target = resource === 'memory' ? Math.min(requested, ws.faults.memoryLimitMib ?? requested) : requested;
+            const part = { applies_at: at, [`requested_${suffix}`]: requested, [`target_${suffix}`]: target, [`previous_${suffix}`]: previous, [`applied_${suffix}`]: at === 'now' ? target : at === 'resume' ? null : previous, limit_reason: target < requested ? 'plan' : null, reason };
+            if (resource === 'memory')
+                Object.assign(part, { allocation_mode: mode, held_mib: mode === 'elastic' ? body.memory_mib_held ?? 1024 : null, converged: at === 'now' ? true : null });
+            out[resource] = part;
+            if (body[key] !== undefined)
+                Object.assign(ws.view.caps, { [key]: requested });
+            if (at === 'now')
+                ws.sizes[key] = target; // grants are the captured report of the last start, not current memory.
+            if (at === 'resume')
+                ws.pending.set(key, target);
+            if (ws.view.ceilings) {
+                Object.assign(ws.view.ceilings, { [key]: target });
+                Object.assign(ws.view.ceilings.sources, { [key]: target < requested ? 'plan' : 'user' });
+                ws.view.ceilings.resolved_at = stamp(this.#now);
+            }
+            if (resource === 'memory' && at === 'now')
+                ws.view.memory = { allocation_mode: mode, promised_mib: target, held_mib: mode === 'elastic' ? Number(body.memory_mib_held ?? 1024) : target, plugged_mib: mode === 'elastic' ? 0 : null };
+        }
+        ws.view.caps.allocation_mode = mode;
+        if (body.memory_mib_held !== undefined)
+            ws.view.caps.memory_mib_held = Number(body.memory_mib_held);
+        return json({ ...out, caps: ws.view.caps });
+    }
+    #exec(ws, tail, method, body, url, init) {
+        if (tail === '/exec' && method === 'POST') {
+            this.#activity(ws);
+            const req = body;
+            req.session_id ??= `fake-exec-${this.#id()}`;
+            let c = ws.commands.get(req.session_id);
+            if (!c) {
+                if (!this.#options.onExec)
+                    throw new FakeUnsupportedError('exec (configure options.onExec)');
+                const result = this.#options.onExec(clone(req), clone(ws.view));
+                c = { session: { ...clone(seed.execSession), session_id: req.session_id, created: true, state: 'running', exit_code: null, stdout_size: 0, stderr_size: 0, created_at: stamp(this.#now), started_at: stamp(this.#now), ended_at: undefined }, stdout: '', stderr: '', until: this.#now + (req.timeout_ms ?? 3600000), listeners: new Set() };
+                ws.commands.set(req.session_id, c);
+                if (result !== null)
+                    this.#finish(c, result);
+            }
+            return new Headers(init?.headers).get('accept')?.includes('ndjson') ? this.#output(c, url, init?.signal) : json(c.session, 201);
+        }
+        const match = /^\/exec\/([^/]+)(.*)$/.exec(tail);
+        const c = match && ws.commands.get(match[1]);
+        if (!c)
+            return error(404, 'not_found', 'Exec session not found.');
+        const action = match[2];
+        if (!action)
+            return json(c.session);
+        if (action === '/output')
+            return this.#output(c, url, init?.signal);
+        if (action === '/cancel' || action === '/signal') {
+            const sig = action === '/cancel' ? 15 : typeof body.signal === 'string' ? constants.signals[body.signal] : Number(body.signal);
+            if (!sig)
+                return error(422, 'validation_failed', 'Unknown signal.', { field: 'signal' });
+            this.#finish(c, { termSignal: sig, canceled: action === '/cancel' });
+            ws.lastTool = this.#now;
+            this.#evaluate(ws);
+            return json(c.session);
+        }
+        throw new FakeUnsupportedError(`${method} ${tail}`);
+    }
+    #files(ws, tail, method, body, url, init) {
+        const path = url.searchParams.get('path') ?? body.path ?? '';
+        const info = (p) => ({ ...clone(seed.fileInfo), path: p, name: p.split('/').at(-1), size: ws.files.get(p)?.length ?? 0, type: ws.dirs.has(p) ? 'directory' : 'file', modified_at: stamp(this.#now), ...(url.searchParams.get('revision') === 'true' && ws.files.has(p) ? { revision: createHash('sha256').update(ws.files.get(p)).digest('hex') } : { revision: undefined }) });
+        if (tail === '/files' && method === 'GET') {
+            const data = ws.files.get(path);
+            if (!data)
+                return error(404, 'not_found', `open ${path}: no such file or directory`, { reason: 'path_not_found' });
+            const offset = Number(url.searchParams.get('offset') ?? 0);
+            const length = Number(url.searchParams.get('length') ?? data.length);
+            return new Response(data.slice(offset, offset + length), { headers: { 'content-type': 'application/octet-stream' } });
+        }
+        if (tail === '/files' && method === 'PUT') {
+            const raw = init?.body;
+            const bytes = typeof raw === 'string' ? new TextEncoder().encode(raw) : raw instanceof Uint8Array ? new Uint8Array(raw) : new Uint8Array();
+            ws.files.set(path, url.searchParams.get('append') === 'true' ? new Uint8Array([...ws.files.get(path) ?? [], ...bytes]) : bytes);
+            return json({ ...clone(seed.fileWrite), path, bytes_written: bytes.length, file: info(path), sha256: createHash('sha256').update(ws.files.get(path)).digest('hex') });
+        }
+        if (tail === '/files' && method === 'DELETE') {
+            ws.files.delete(path);
+            ws.dirs.delete(path);
+            return new Response(null, { status: 204 });
+        }
+        if (tail === '/files/stat')
+            return ws.files.has(path) || ws.dirs.has(path) ? json(info(path)) : error(404, 'not_found', `stat ${path}: no such file or directory`, { reason: 'path_not_found' });
+        if (tail === '/files/list')
+            return json({ ...clone(seed.fileList), path, entries: [...ws.files.keys(), ...ws.dirs].filter((p) => p !== path && p.slice(0, p.lastIndexOf('/')) === path.replace(/\/$/, '')).map(info) });
+        if (tail === '/files/mkdir') {
+            ws.dirs.add(path);
+            return json(info(path));
+        }
+        if (tail === '/files/move') {
+            const from = String(body.from);
+            const to = String(body.to);
+            const data = ws.files.get(from);
+            if (!data)
+                return error(404, 'not_found', `open ${from}: no such file or directory`, { reason: 'path_not_found' });
+            ws.files.set(to, data);
+            ws.files.delete(from);
+            return json(info(to));
+        }
+        if (tail === '/files/patch') {
+            const current = ws.files.get(path);
+            const previous = current ? createHash('sha256').update(current).digest('hex') : 'absent';
+            if (body.expected_revision !== undefined && body.expected_revision !== previous)
+                return error(409, 'conflict', 'The file revision changed.', { reason: 'revision_mismatch', current_revision: previous });
+            if (body.edits !== undefined && !current)
+                return error(404, 'not_found', `open ${path}: no such file or directory`, { reason: 'path_not_found' });
+            let text = typeof body.content === 'string' ? body.content : new TextDecoder().decode(current);
+            let replacements = 0;
+            for (const [index, edit] of (body.edits ?? []).entries()) {
+                const count = edit.old_text ? text.split(edit.old_text).length - 1 : 0;
+                if (!count)
+                    return error(422, 'validation_failed', 'The edit text was not found.', { reason: 'edit_not_found', index });
+                if (count > 1 && !edit.replace_all)
+                    return error(422, 'validation_failed', 'The edit text occurs more than once.', { reason: 'edit_ambiguous', index });
+                text = edit.replace_all ? text.split(edit.old_text).join(edit.new_text) : text.replace(edit.old_text, () => edit.new_text);
+                replacements += edit.replace_all ? count : 1;
+            }
+            const data = new TextEncoder().encode(text);
+            ws.files.set(path, data);
+            return json({ ...clone(seed.filePatch), path, previous_revision: previous, revision: createHash('sha256').update(data).digest('hex'), bytes_written: data.length, ...(body.edits !== undefined ? { replacements } : { replacements: undefined }), file: info(path) });
+        }
+        if (tail === '/files/search') {
+            const matches = [];
+            let scanned = 0;
+            const root = path.replace(/\/$/, '');
+            const max = Number(body.max_matches ?? 200);
+            const pattern = body.pattern;
+            const regex = body.regex ? new RegExp(pattern, body.case_insensitive ? 'i' : '') : null;
+            for (const [p, data] of [...ws.files].sort(([a], [b]) => a.localeCompare(b))) {
+                if (p !== root && !p.startsWith(root + '/'))
+                    continue;
+                const include = body.include;
+                const exclude = body.exclude;
+                if (include && !include.some((g) => matchesGlob(p, g)))
+                    continue;
+                if ((exclude ?? ['**/.git/**', '**/node_modules/**']).some((g) => matchesGlob(p, g)))
+                    continue;
+                if (data.length > Number(body.max_file_bytes ?? 1048576) || data.includes(0))
+                    continue;
+                scanned += 1;
+                const lines = new TextDecoder().decode(data).split('\n');
+                for (const [index, text] of lines.entries()) {
+                    const at = regex ? text.search(regex) : (body.case_insensitive ? text.toLowerCase().indexOf(pattern.toLowerCase()) : text.indexOf(pattern));
+                    if (at < 0)
+                        continue;
+                    const context = Number(body.context_lines ?? 0);
+                    matches.push({ path: p, line: index + 1, column: Buffer.byteLength(text.slice(0, at)) + 1, text: Buffer.from(text).subarray(0, 1000).toString(), ...(context ? { before: lines.slice(Math.max(0, index - context), index), after: lines.slice(index + 1, index + 1 + context) } : {}) });
+                    if (matches.length >= max)
+                        return json({ matches, truncated: true, stop_reason: 'max_matches', files_scanned: scanned });
+                }
+            }
+            return json({ matches, truncated: false, files_scanned: scanned });
+        }
+        throw new FakeUnsupportedError(`${method} ${tail}`);
+    }
+    #computer(ws, tail, method, body) {
+        if (!ws.view.computer_use.available)
+            return error(409, 'conflict', 'This template has no desktop runtime.', { reason: 'computer_use_unavailable' });
+        if (!ws.view.computer_use.enabled)
+            return error(409, 'conflict', 'Computer use is disabled.', { reason: 'computer_use_disabled' });
+        if (tail === '/computer/actions') {
+            ws.computerRunning = true;
+            const actions = body.actions;
+            const image = clone(seed.computerActions.screenshot);
+            return json({ ...clone(seed.computerActions), results: actions.map((a) => ({ action: a.action, ok: true, ...(['screenshot', 'zoom'].includes(a.action) ? { image } : {}) })), ...(body.screenshot === false ? { screenshot: undefined } : { screenshot: image }) });
+        }
+        if (tail === '/computer/stream') {
+            if (method === 'DELETE') {
+                ws.streams = { view: false, interactive: false };
+                return new Response(null, { status: 204 });
+            }
+            ws.computerRunning = true;
+            const interactive = body.interactive === true;
+            ws.streams[interactive ? 'interactive' : 'view'] = true;
+            return json({ port: interactive ? 61003 : 61002, path: '/view', interactive });
+        }
+        if (method === 'DELETE') {
+            ws.computerRunning = false;
+            return new Response(null, { status: 204 });
+        }
+        if (method === 'POST')
+            ws.computerRunning = true;
+        return json(ws.computerRunning ? { ...clone(seed.computerStatus), streams: ws.streams } : clone(seed.computerStopped));
+    }
+    #ports(ws, tail, method, body) {
+        if (tail === '/ports' && method === 'GET')
+            return json({ ports: [...ws.ports.values()].sort((a, b) => Number(a.port) - Number(b.port)) });
+        const match = /^\/ports\/(\d+)(.*)$/.exec(tail);
+        if (!match)
+            throw new FakeUnsupportedError(`${method} ${tail}`);
+        const port = Number(match[1]);
+        const url = `https://${port}-fake.shardflux.invalid`;
+        if (match[2] === '/links' && body.embed)
+            throw new FakeUnsupportedError('embedded port links (extend from a live capture)');
+        if (match[2] === '/links')
+            return json({ url: `${url}${body.path ?? '/'}`, expires_at: stamp(this.#now + Number(body.ttl_seconds ?? 86400) * 1000), port }, 201);
+        if (method === 'DELETE') {
+            ws.ports.delete(port);
+            return new Response(null, { status: 204 });
+        }
+        const view = { port, url, created_at: stamp(this.#now), closed_at: null };
+        ws.ports.set(port, view);
+        return json(view, 201);
+    }
+}
+/** A real Shardflux client using an isolated in-memory HTTP transport; no request reaches the network. */
+export function createFakeShardflux(options = {}) {
+    const testing = new FakeShardfluxTesting(options);
+    return Object.assign(new Shardflux({ apiKey: 'sfk_aaaaaaaaaaaaaaaa_fakeSecret', baseUrl: 'https://api.fake.invalid', fetch: testing.fetch, versionCheck: false, maxRetries: 0 }), { testing });
+}