@shardflux/sdk 0.5.0 → 0.6.1

package/dist/tokens.js

@@ -1,3 +1,4 @@
+import { Trace, traced } from "./progress.js";
 export class ToolTokenManager {
     workspaceId;
     agentLabel;
@@ -8,6 +9,7 @@ export class ToolTokenManager {
     #now;
     #current;
     #inflight;
+    #invalidated = false;
     /** Number of tokens fetched from the API (observability / tests). */
     fetched = 0;
     constructor(http, authorization, workspaceId, opts = {}) {
@@ -30,24 +32,33 @@ export class ToolTokenManager {
     #fresh(t) {
         return t !== undefined && Date.parse(t.expires_at) - this.#now() > this.#skew;
     }
-    async get() {
+    /**
+     * The current token, or a new one when there is none or it expires within the skew. A fetch is a traced `token` call:
+     * `onProgress` sees it (phase `request` with the reason `initial`, `expiring` or `invalidated`) and its timing.
+     */
+    async get(onProgress) {
         if (this.#fresh(this.#current))
             return this.#current;
-        return this.refresh();
+        return this.refresh(onProgress, this.#current ? 'expiring' : this.#invalidated ? 'invalidated' : 'initial');
     }
-    /** Forces a new token (single-flight). */
-    refresh() {
+    /** Forces a new token (single-flight: concurrent callers share one request, and the first caller's trace). */
+    refresh(onProgress, reason = 'forced') {
         this.#inflight ??= (async () => {
+            const trace = new Trace('token', onProgress, { workspaceId: this.workspaceId });
             try {
-                const body = {};
-                if (this.agentLabel !== undefined)
-                    body.agent_label = this.agentLabel;
-                if (this.tools !== undefined)
-                    body.tools = [...this.tools];
-                const token = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(this.workspaceId)}/tool-tokens`, { json: body }, this.#authorization);
-                this.fetched += 1;
-                this.#current = token;
-                return token;
+                return await traced(trace, async () => {
+                    trace.phase('request', reason);
+                    const body = {};
+                    if (this.agentLabel !== undefined)
+                        body.agent_label = this.agentLabel;
+                    if (this.tools !== undefined)
+                        body.tools = [...this.tools];
+                    const token = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(this.workspaceId)}/tool-tokens`, { json: body, onRetry: trace.onRetry }, this.#authorization);
+                    this.fetched += 1;
+                    this.#current = token;
+                    this.#invalidated = false;
+                    return token;
+                });
             }
             finally {
                 this.#inflight = undefined;
@@ -57,5 +68,6 @@ export class ToolTokenManager {
     }
     invalidate() {
         this.#current = undefined;
+        this.#invalidated = true;
     }
 }

package/dist/tools.d.ts

@@ -1,3 +1,16 @@
+/**
+ * Framework-neutral agent tools for a workspace (TEMPLATES.md):
+ *
+ *   await agent.run({ input, tools: workspaceTools(workspace) });
+ *
+ * Each tool is { name, description, parameters (JSON Schema 2020-12), execute }.
+ * `execute` validates its arguments against `parameters` (the same schema the
+ * model saw), then calls the cell gateway through the workspace's managed tool
+ * token. The customer's model and agent loop stay in the customer's
+ * application; toOpenAITools/toAnthropicTools export the definitions in those
+ * providers' formats and executeToolCall dispatches a model's tool call.
+ */
+import type { CellClientOptions } from './cell.js';
 import type { ToolName } from './tokens.js';
 import type { Workspace } from './workspace.js';
 export interface JsonSchema {
@@ -46,6 +59,10 @@ export interface WorkspaceToolsOptions {
     maxOutputBytes?: number;
     /** Working directory for exec when the model gives none (default the guest user's home). */
     defaultCwd?: string;
+    /** Wake on use for the tools' cell calls (CellClientOptions.wake): default `workspace.wake()`; `null` opts out. */
+    wake?: CellClientOptions['wake'];
+    /** Bound on lifecycle waits (busy waits plus wakes) per tool call (CellClientOptions.transitionTimeoutMs). */
+    transitionTimeoutMs?: number;
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export declare function workspaceTools(workspace: Workspace, opts?: WorkspaceToolsOptions): WorkspaceTool[];

package/dist/tools.js

@@ -77,7 +77,11 @@ function clip(text, max) {
 }
 /** Builds the tool list for a workspace. Synchronous: tokens are fetched on first use. */
 export function workspaceTools(workspace, opts = {}) {
-    const cell = () => workspace.cell(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {});
+    const cell = () => workspace.cell({
+        ...(opts.agentLabel !== undefined ? { agentLabel: opts.agentLabel } : {}),
+        ...(opts.wake !== undefined ? { wake: opts.wake } : {}),
+        ...(opts.transitionTimeoutMs !== undefined ? { transitionTimeoutMs: opts.transitionTimeoutMs } : {}),
+    });
     const max = opts.maxOutputBytes ?? 65_536;
     const prefix = opts.prefix ?? '';
     const allowed = new Set(opts.tools ?? workspace.grantedTools ?? ALL);

package/dist/workspace.d.ts

@@ -2,18 +2,37 @@
  * 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, Caps, Operation, WaitOptions, WorkspaceView } from './client.js';
+import type { ClientContext, DiskLayout, ForkTarget, Operation, WaitOptions, WorkspaceLifetime, WorkspaceOrigin, WorkspacePurpose, WorkspaceView } from './client.js';
 import { CellClient } from './cell.js';
-import type { CellClientOptions } from './cell.js';
+import type { FinishedOperation, LifecycleOptions, WaitedLifecycleOptions } from './lifecycle.js';
+import { Trace } from './progress.js';
+import type { LifecycleTiming, ProgressListener } from './progress.js';
+import { WorkspaceSecrets } from './secrets.js';
+import type { CellClientOptions, WorkspaceChangesPage, WorkspaceChangesParams } from './cell.js';
+import type { SaveAsTemplateParams, SaveAsTemplateResponse } from './templates.js';
 import { ToolTokenManager } from './tokens.js';
 import type { ToolName, ToolToken } from './tokens.js';
+export interface WakeOptions {
+    /** One deadline for the whole wake, across its retries (default 120 000 ms). */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    /** Progress of the wake: the resume request, observed states, conflicts retried, and `done` with the timing. */
+    onProgress?: ProgressListener;
+}
 export declare class Workspace {
     #private;
     constructor(ctx: ClientContext, view: WorkspaceView, opts?: {
         agentLabel?: string | undefined;
         tools?: ToolName[] | undefined;
         token?: ToolToken | null;
+        trace?: Trace;
     });
+    /**
+     * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
+     * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
+     * `formatTiming(workspace.lastTiming)` prints it.
+     */
+    get lastTiming(): LifecycleTiming | null;
     get id(): string;
     get key(): string;
     /** Observed lifecycle state reported by the cell. */
@@ -28,43 +47,116 @@ export declare class Workspace {
     get template(): WorkspaceView['template'];
     get pendingReason(): string | null;
     get activeOperation(): WorkspaceView['active_operation'];
+    /** persistent or session (contracts §19.11); immutable. A view without the field (older API) is persistent. */
+    get lifetime(): WorkspaceLifetime;
+    /** standard, template_draft or template_test (contracts §19.9). */
+    get purpose(): WorkspacePurpose;
+    /** legacy or layered (contracts §19.2); reset, save-as-template and changes need layered. */
+    get diskLayout(): DiskLayout;
+    /** Sessions: seconds without activity after which the session ends (null for persistent workspaces). */
+    get idleTimeoutSeconds(): number | null;
+    /** Where the disk came from: null, `{kind: "fork"}` or `{kind: "draft_state"}` (test instances). */
+    get origin(): WorkspaceOrigin | null;
+    /** How a session ended (closed, idle_timeout, draft_discarded); null while live or for a plain delete. */
+    get endedReason(): WorkspaceView['ended_reason'];
     /** The raw view (GET /v1/workspaces/{id}). */
     get data(): WorkspaceView;
+    /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
+    get secrets(): WorkspaceSecrets;
     refresh(): Promise<this>;
     /** Waits for the active operation (if any) and refreshes. */
     waitUntilReady(opts?: WaitOptions): Promise<this>;
-    delete(opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    suspend(opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    resume(opts?: {
-        idempotencyKey?: string;
-    }): Promise<Operation>;
-    snapshot(opts?: {
+    /**
+     * Deletes the workspace (tool access ends at once; keys are never reused). Resolves when the delete is REQUESTED;
+     * with `{ wait: true }`, once it has FINISHED.
+     */
+    delete(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    delete(opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Suspends the workspace: memory and processes are checkpointed, compute stops. Resolves when the suspend is
+     * REQUESTED (the operation is usually still `queued`, and the workspace still running); pass `{ wait: true }` to
+     * resolve once it has FINISHED, with `workspace.state` then `suspended`.
+     *
+     *   await workspace.suspend({ wait: true });
+     */
+    suspend(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    suspend(opts?: LifecycleOptions): Promise<Operation>;
+    /**
+     * Resumes a suspended workspace. Resolves when the resume is REQUESTED; with `{ wait: true }`, once the workspace runs.
+     * Tool calls wake a suspended workspace by themselves, so this is rarely needed.
+     */
+    resume(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    resume(opts?: LifecycleOptions): Promise<Operation>;
+    /** Takes a snapshot. Resolves when it is REQUESTED; with `{ wait: true }`, once it is taken. */
+    snapshot(opts: WaitedLifecycleOptions & {
+        label?: string;
+    }): Promise<FinishedOperation>;
+    snapshot(opts?: LifecycleOptions & {
         label?: string;
-        idempotencyKey?: string;
     }): Promise<Operation>;
-    fork(target: {
-        key: string;
-        caps?: Caps;
-    }, opts?: {
-        idempotencyKey?: string;
-    }): Promise<{
+    /**
+     * 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<{
+        operation: FinishedOperation;
+        workspace: Workspace;
+    }>;
+    fork(target: ForkTarget, opts?: LifecycleOptions): Promise<{
         operation: Operation;
         workspace: Workspace;
     }>;
+    /**
+     * Safe in a `finally` block for any workspace. It always closes this handle's local streams (in-flight cell requests,
+     * exec output streams and PTY reads started through `cell()` are aborted; later `cell()` calls get fresh clients).
+     * For a **session** workspace it also ends the session (POST /v1/workspaces/{id}/close): the workspace is deleted and
+     * the `delete` operation is returned (input.reason session_closed). For a **persistent** workspace no request is made
+     * and null is returned: the workspace keeps running (suspend() or delete() it explicitly). With `{ wait: true }`, a
+     * session's close resolves once the delete has finished.
+     */
+    close(opts: WaitedLifecycleOptions): Promise<FinishedOperation | null>;
+    close(opts?: LifecycleOptions): Promise<Operation | null>;
+    /**
+     * Wipes every change in this layered workspace and restarts it on its template (contracts §19.12; sends
+     * confirm_destructive). Returns the `reset` operation: requested, or with `{ wait: true }` finished. Tool tokens of
+     * the old epoch are dropped.
+     */
+    reset(opts: WaitedLifecycleOptions): Promise<FinishedOperation>;
+    reset(opts?: LifecycleOptions): Promise<Operation>;
+    /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
+    saveAsTemplate(params: SaveAsTemplateParams): Promise<SaveAsTemplateResponse>;
+    /**
+     * The workspace's changes against its template (cell gateway GET /v1/workspaces/{id}/changes; needs the `files` tool).
+     * 409 workspace_not_running, or conflict with details.reason legacy_disk_layout / guest_feature_unavailable.
+     */
+    changes(opts?: WorkspaceChangesParams & {
+        agentLabel?: string;
+        tools?: ToolName[];
+    }): Promise<WorkspaceChangesPage>;
     /** Token manager for an agent label / tool set (defaults: those given to open()). */
     tokens(opts?: {
         agentLabel?: string;
         tools?: ToolName[];
     }): ToolTokenManager;
-    /** Typed client for the cell gateway tools of this workspace. */
+    /**
+     * Typed client for the cell gateway tools of this workspace. Calls wake the workspace on use (`wake()`, bounded by
+     * `transitionTimeoutMs`); pass `wake: null` to get `workspace_not_running` back instead. One client per agent label,
+     * tool set and transition settings; the other options apply when that client is first created.
+     */
     cell(opts?: {
         agentLabel?: string;
         tools?: ToolName[];
     } & CellClientOptions): CellClient;
+    /**
+     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does (contracts §20.4): resume,
+     * or join the active resume/open; an active suspend (or other operation) is waited out first. Resolves `true` when it
+     * resumed or waited for a lifecycle operation, `false` when the workspace was already running. One deadline
+     * (`timeoutMs`, default 120 000 ms) covers every step. Throws OperationFailedError when the resume/open fails,
+     * OperationTimeoutError (naming the operation, its state and reason) when it is still queued, running or
+     * capacity_pending at the deadline, and any other API error (a conflict other than already_running /
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`.
+     */
+    wake(opts?: WakeOptions): Promise<boolean>;
     /** Tools granted by the most recent token (null before one was issued). */
     get grantedTools(): ToolName[] | null;
 }

package/dist/workspace.js

@@ -1,4 +1,9 @@
-import { CellClient } from "./cell.js";
+import { CellClient, DEFAULT_TRANSITION_TIMEOUT_MS } from "./cell.js";
+import { OperationFailedError, ShardfluxApiError } from "./errors.js";
+import { randomId } from "./http.js";
+import { AFTER_WAIT, TRACE } from "./lifecycle.js";
+import { Trace, combineListeners, traced } from "./progress.js";
+import { WorkspaceSecrets } from "./secrets.js";
 import { ToolTokenManager } from "./tokens.js";
 export class Workspace {
     #view;
@@ -6,13 +11,42 @@ export class Workspace {
     #defaults;
     #managers = new Map();
     #cells = new Map();
+    /** The open() that produced this handle; its timing is final once open() has returned. */
+    #openTrace;
+    #lastTiming;
     constructor(ctx, view, opts = {}) {
         this.#ctx = ctx;
         this.#view = view;
         this.#defaults = { agentLabel: opts.agentLabel, tools: opts.tools };
+        this.#openTrace = opts.trace;
         if (opts.token)
             this.tokens().seed(opts.token);
     }
+    /**
+     * Where the time went in the last lifecycle call made through this handle: open(), wake() (also when a tool call
+     * woke the workspace), or a lifecycle call with `wait`. Null for handles from get()/list() until such a call.
+     * `formatTiming(workspace.lastTiming)` prints it.
+     */
+    get lastTiming() {
+        return this.#lastTiming ?? this.#openTrace?.finished ?? null;
+    }
+    /** Adds this handle's timing capture to a call's listener. */
+    #tracked(opts) {
+        const capture = (e) => {
+            if (e.type === 'done' && e.action !== 'token')
+                this.#lastTiming = e.timing;
+        };
+        return { ...opts, onProgress: combineListeners(opts.onProgress, capture) };
+    }
+    /** Refreshes the view inside a waited call's trace (a deleted workspace may no longer be readable). */
+    #refreshAfterWait() {
+        return async (trace) => {
+            await trace.span('view', () => this.refresh()).catch((e) => {
+                if (!(e instanceof ShardfluxApiError && e.status === 404))
+                    throw e;
+            });
+        };
+    }
     get id() {
         return this.#view.id;
     }
@@ -49,10 +83,38 @@ export class Workspace {
     get activeOperation() {
         return this.#view.active_operation;
     }
+    /** persistent or session (contracts §19.11); immutable. A view without the field (older API) is persistent. */
+    get lifetime() {
+        return this.#view.lifetime ?? 'persistent';
+    }
+    /** standard, template_draft or template_test (contracts §19.9). */
+    get purpose() {
+        return this.#view.purpose ?? 'standard';
+    }
+    /** legacy or layered (contracts §19.2); reset, save-as-template and changes need layered. */
+    get diskLayout() {
+        return this.#view.disk_layout ?? 'legacy';
+    }
+    /** Sessions: seconds without activity after which the session ends (null for persistent workspaces). */
+    get idleTimeoutSeconds() {
+        return this.#view.idle_timeout_seconds ?? null;
+    }
+    /** Where the disk came from: null, `{kind: "fork"}` or `{kind: "draft_state"}` (test instances). */
+    get origin() {
+        return this.#view.origin ?? null;
+    }
+    /** How a session ended (closed, idle_timeout, draft_discarded); null while live or for a plain delete. */
+    get endedReason() {
+        return this.#view.ended_reason ?? null;
+    }
     /** The raw view (GET /v1/workspaces/{id}). */
     get data() {
         return this.#view;
     }
+    /** Secret names bound to this workspace (injected into every exec/PTY start): `get()`, `set(names)`. */
+    get secrets() {
+        return new WorkspaceSecrets(this.#ctx, this.id);
+    }
     async refresh() {
         this.#view = await this.#ctx.http.json('GET', `/v1/workspaces/${encodeURIComponent(this.id)}`, {}, this.#ctx.authorization);
         return this;
@@ -65,19 +127,49 @@ export class Workspace {
         return this.refresh();
     }
     delete(opts = {}) {
-        return this.#ctx.workspaces.delete(this.id, opts);
+        return this.#ctx.workspaces.delete(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     suspend(opts = {}) {
-        return this.#ctx.workspaces.suspend(this.id, opts);
+        return this.#ctx.workspaces.suspend(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     resume(opts = {}) {
-        return this.#ctx.workspaces.resume(this.id, opts);
+        return this.#ctx.workspaces.resume(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     snapshot(opts = {}) {
-        return this.#ctx.workspaces.snapshot(this.id, opts);
+        return this.#ctx.workspaces.snapshot(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
     }
     fork(target, opts = {}) {
-        return this.#ctx.workspaces.fork(this.id, target, opts);
+        return this.#ctx.workspaces.fork(this.id, target, this.#tracked(opts));
+    }
+    async close(opts = {}) {
+        for (const c of this.#cells.values())
+            c.close();
+        this.#cells.clear();
+        if (this.lifetime !== 'session')
+            return null;
+        const out = await this.#ctx.workspaces.closeWithView(this.id, this.#tracked(opts));
+        this.#view = out.workspace;
+        for (const m of this.#managers.values())
+            m.invalidate();
+        return out.operation;
+    }
+    async reset(opts = {}) {
+        const op = await this.#ctx.workspaces.reset(this.id, { ...this.#tracked(opts), [AFTER_WAIT]: this.#refreshAfterWait() });
+        for (const m of this.#managers.values())
+            m.invalidate();
+        return op;
+    }
+    /** Saves this layered workspace as the next version of an organization template (contracts §19.8). */
+    saveAsTemplate(params) {
+        return this.#ctx.workspaces.saveAsTemplate(this.id, params);
+    }
+    /**
+     * The workspace's changes against its template (cell gateway GET /v1/workspaces/{id}/changes; needs the `files` tool).
+     * 409 workspace_not_running, or conflict with details.reason legacy_disk_layout / guest_feature_unavailable.
+     */
+    changes(opts = {}) {
+        const { agentLabel, tools, ...params } = opts;
+        return this.cell({ ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) }).changes(params);
     }
     /** Token manager for an agent label / tool set (defaults: those given to open()). */
     tokens(opts = {}) {
@@ -91,18 +183,92 @@ export class Workspace {
         }
         return m;
     }
-    /** Typed client for the cell gateway tools of this workspace. */
+    /**
+     * Typed client for the cell gateway tools of this workspace. Calls wake the workspace on use (`wake()`, bounded by
+     * `transitionTimeoutMs`); pass `wake: null` to get `workspace_not_running` back instead. One client per agent label,
+     * tool set and transition settings; the other options apply when that client is first created.
+     */
     cell(opts = {}) {
-        const { agentLabel, tools, ...cellOpts } = opts;
+        const { agentLabel, tools, wake, onProgress, ...cellOpts } = opts;
         const manager = this.tokens({ ...(agentLabel !== undefined ? { agentLabel } : {}), ...(tools !== undefined ? { tools } : {}) });
-        const k = `${JSON.stringify([agentLabel ?? null, tools ?? null])}`;
+        const wakeMode = wake === null ? 'off' : wake ? 'custom' : 'on';
+        const k = `${JSON.stringify([agentLabel ?? null, tools ?? null, wakeMode, cellOpts.transitionTimeoutMs ?? null])}`;
         let c = this.#cells.get(k);
         if (!c) {
-            c = new CellClient(this.id, manager, { fetch: this.#ctx.fetch, userAgent: this.#ctx.userAgent, sleep: this.#ctx.sleep, ...cellOpts });
+            // Tool-call events (token fetches, busy waits, retries) go to the client listener and this cell's own; a wake
+            // adds the client listener itself.
+            const listener = combineListeners(this.#ctx.onProgress, onProgress);
+            c = new CellClient(this.id, manager, {
+                fetch: this.#ctx.fetch,
+                userAgent: this.#ctx.userAgent,
+                sleep: this.#ctx.sleep,
+                ...cellOpts,
+                ...(listener ? { onProgress: listener } : {}),
+                wake: wake === undefined ? (timeoutMs, signal) => this.wake({ timeoutMs, ...(signal ? { signal } : {}), ...(onProgress ? { onProgress } : {}) }) : wake,
+            });
             this.#cells.set(k, c);
         }
         return c;
     }
+    /**
+     * Makes a suspended (or suspending/resuming) workspace run again and resolves once it does (contracts §20.4): resume,
+     * or join the active resume/open; an active suspend (or other operation) is waited out first. Resolves `true` when it
+     * resumed or waited for a lifecycle operation, `false` when the workspace was already running. One deadline
+     * (`timeoutMs`, default 120 000 ms) covers every step. Throws OperationFailedError when the resume/open fails,
+     * OperationTimeoutError (naming the operation, its state and reason) when it is still queued, running or
+     * capacity_pending at the deadline, and any other API error (a conflict other than already_running /
+     * operation_in_progress) at once. Cell calls use it automatically when they meet `workspace_not_running`.
+     */
+    async wake(opts = {}) {
+        const trace = new Trace('wake', combineListeners(this.#ctx.onProgress, this.#tracked(opts).onProgress), { workspaceId: this.id });
+        return traced(trace, () => this.#wake(opts, trace));
+    }
+    async #wake(opts, trace) {
+        const deadline = Date.now() + (opts.timeoutMs ?? DEFAULT_TRANSITION_TIMEOUT_MS);
+        const waitFor = (operationId) => this.#ctx.workspaces.waitForOperation(operationId, { timeoutMs: Math.max(1, deadline - Date.now()), ...(opts.signal ? { signal: opts.signal } : {}), [TRACE]: trace });
+        const resumePath = `/v1/workspaces/${encodeURIComponent(this.id)}/resume`;
+        for (let i = 0; i < 4; i += 1) {
+            if (opts.signal?.aborted)
+                throw opts.signal.reason;
+            let active;
+            try {
+                // Resume returns the active resume/open when there is one, so concurrent wakes join a single operation. The
+                // request is made here rather than through resume() so the wake is one trace.
+                trace.phase('request', i === 0 ? null : 'retry');
+                const { operation: op } = await this.#ctx.http.json('POST', resumePath, { idempotencyKey: randomId('op-'), onRetry: trace.onRetry }, this.#ctx.authorization);
+                trace.observe(op);
+                await waitFor(op.id);
+                await trace.span('view', () => this.refresh());
+                return true;
+            }
+            catch (e) {
+                if (!(e instanceof ShardfluxApiError) || e.code !== 'conflict')
+                    throw e;
+                if (e.reason === 'already_running') {
+                    if (i > 0)
+                        await trace.span('view', () => this.refresh());
+                    return i > 0;
+                }
+                if (e.reason !== 'operation_in_progress')
+                    throw e;
+                const id = e.operationId ?? e.details?.['active_operation_id'];
+                active = typeof id === 'string' ? id : undefined;
+                trace.retry({ request: `POST ${resumePath}`, attempt: i + 1, cause: `conflict operation_in_progress${active ? ` (joins ${active})` : ''}`, delayMs: 0 });
+            }
+            if (active === undefined)
+                continue; // a concurrent start raced ours: ask again
+            try {
+                await waitFor(active);
+            }
+            catch (e) {
+                // A failed open/resume means the workspace will not run: fail fast. Another kind that failed (a suspend,
+                // snapshot or fork) leaves the workspace as it was, so the next resume attempt decides.
+                if (!(e instanceof OperationFailedError) || e.operation.kind === 'open' || e.operation.kind === 'resume')
+                    throw e;
+            }
+        }
+        throw new Error(`workspace ${this.id} did not become runnable after repeated lifecycle conflicts`);
+    }
     /** Tools granted by the most recent token (null before one was issued). */
     get grantedTools() {
         for (const m of this.#managers.values())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/sdk",
-  "version": "0.5.0",
+  "version": "0.6.1",
   "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",
@@ -30,6 +30,7 @@
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "publishConfig": {