@shardflux/sdk 0.5.0 → 0.6.1

package/dist/client.js

@@ -1,12 +1,32 @@
 import { OperationFailedError, OperationTimeoutError, ShardfluxApiError } from "./errors.js";
-import { HttpClient, SDK_VERSION, defaultSleep, randomId } from "./http.js";
+import { HttpClient, SDK_VERSION, SERVER_WAIT_MAX_S, defaultFetch, defaultSleep, pollWithWait, randomId } from "./http.js";
 import { Workspace } from "./workspace.js";
 import { AuditApi } from "./audit.js";
 import { EgressPolicyApi } from "./egress.js";
 import { SecretsApi } from "./secrets.js";
-import { TemplatesApi } from "./templates.js";
+import { TemplatesApi, saveAsTemplateBody } from "./templates.js";
 import { UsageApi } from "./usage.js";
 import { VolumesApi } from "./volumes.js";
+import { AFTER_WAIT, TRACE, runLifecycle } from "./lifecycle.js";
+import { Trace, combineListeners, traced } from "./progress.js";
+/**
+ * The workspace a key names (contracts §19.11): the live row (deleted_at null) when there is one, since at most one live
+ * workspace holds a key; otherwise the newest tombstone (ended sessions leave tombstones with the same key, and a
+ * deleted persistent key keeps its tombstone). Null when no row has exactly this key. Rows need not be sorted.
+ */
+export function pickByKey(rows, key) {
+    let tomb = null;
+    for (const r of rows) {
+        if (r.workspace_key !== key)
+            continue;
+        if (r.deleted_at === null)
+            return r;
+        // UUIDv7 ids sort by creation time: the greatest id is the newest tombstone.
+        if (tomb === null || r.id > tomb.id)
+            tomb = r;
+    }
+    return tomb;
+}
 const TERMINAL = new Set(['succeeded', 'failed', 'canceled']);
 /** Races the injected sleep against the signal (the injected sleep itself may not be abortable). */
 function abortableSleep(sleep, ms, signal) {
@@ -23,6 +43,8 @@ function abortableSleep(sleep, ms, signal) {
 }
 export class WorkspacesApi {
     #ctx;
+    /** The cell endpoint of the last tool token seen: an open pre-connects to it while the server works (contracts §22.3). */
+    #cellHint = null;
     constructor(ctx) {
         this.#ctx = ctx;
     }
@@ -39,6 +61,8 @@ export class WorkspacesApi {
      * Opens a workspace by key: creates it from the template's latest published version on first
      * use, reconnects (or resumes) afterwards; never resets an existing workspace. Waits until it is
      * ready unless `wait: false`; on timeout throws OperationTimeoutError carrying the operation id.
+     * The timing of the open (client phases, retries, the operation's server timing) is on `workspace.lastTiming`, on
+     * `onProgress` as it happens, and on the error's `timing` when the open fails.
      */
     async open(params) {
         const body = { key: params.key, template: params.template };
@@ -50,29 +74,130 @@ export class WorkspacesApi {
             body.agent_label = params.agentLabel;
         if (params.tools !== undefined)
             body.tools = params.tools;
-        const res = await this.#http.jsonWithStatus('POST', '/v1/workspaces/open', { json: body, idempotencyKey: params.idempotencyKey ?? randomId('open-') }, this.#auth);
-        const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token };
-        if (res.status === 200 || params.wait === false || res.body.operation === null)
-            return this.#wrap(res.body.workspace, wrapOpts);
-        await this.waitForOperation(res.body.operation.id, params.wait ?? {});
-        return this.#wrap(await this.#getView(res.body.workspace.id), { agentLabel: params.agentLabel, tools: params.tools });
+        if (params.secrets !== undefined)
+            body.secrets = params.secrets;
+        if (params.lifetime !== undefined)
+            body.lifetime = params.lifetime;
+        const waitOpts = params.wait === false ? null : (params.wait ?? {});
+        const trace = new Trace('open', combineListeners(this.#ctx().onProgress, params.onProgress, waitOpts?.onProgress));
+        return traced(trace, async () => {
+            // The wait's signal also ends the held request (it can take up to 20 s), not only the polls after it.
+            const init = { json: body, idempotencyKey: params.idempotencyKey ?? randomId('open-'), onRetry: trace.onRetry, ...(waitOpts?.signal ? { signal: waitOpts.signal } : {}) };
+            const started = Date.now();
+            const timeoutMs = waitOpts?.timeoutMs ?? 300_000;
+            if (waitOpts && waitOpts.serverWait !== false) {
+                // Held open (contracts §22.3): the server answers once the operation is terminal (200 with the running workspace
+                // and a tool token) or the wait elapsed (202); a server without it answers 202 at once and the poll below runs.
+                const s = Math.min(SERVER_WAIT_MAX_S, Math.floor(timeoutMs / 1000));
+                if (s >= 1) {
+                    init.headers = { prefer: `wait=${s}` };
+                    init.timeoutMs = Math.max(this.#http.opts.timeoutMs, s * 1000 + 10_000);
+                }
+                this.#preconnect();
+            }
+            const held = init.headers?.prefer !== undefined;
+            trace.phase('request', held ? 'held' : null);
+            const res = await this.#http.jsonWithStatus('POST', '/v1/workspaces/open', init, this.#auth);
+            trace.workspaceId = res.body.workspace.id;
+            if (res.body.operation)
+                trace.observe(res.body.operation);
+            this.#noteToken(res.body.tool_token);
+            const wrapOpts = { agentLabel: params.agentLabel, tools: params.tools, token: res.body.tool_token, trace };
+            if (res.status === 200 || params.wait === false || res.body.operation === null)
+                return this.#wrap(res.body.workspace, wrapOpts);
+            if (TERMINAL.has(res.body.operation.state)) {
+                if (res.body.operation.state !== 'succeeded')
+                    throw new OperationFailedError(res.body.operation);
+            }
+            else {
+                // A held open already spent part of the budget; without the preference the budget is the poll's (as before).
+                const wait = { ...(params.wait ?? {}), ...(held ? { timeoutMs: Math.max(1, timeoutMs - (Date.now() - started)) } : {}), [TRACE]: trace };
+                await this.waitForOperation(res.body.operation.id, wait);
+            }
+            // Ready: read the view and issue the first tool token in parallel (a 200 open returns both at once). A token
+            // failure (e.g. a key without tool permissions) is left to the first tool call, which fetches and reports it.
+            const id = res.body.workspace.id;
+            const [view, token] = await Promise.all([
+                trace.span('view', () => this.#getView(id, trace.onRetry)),
+                trace.span('token', () => this.#issueToken(id, params.agentLabel, params.tools, trace.onRetry)),
+            ]);
+            return this.#wrap(view, { ...wrapOpts, token });
+        });
+    }
+    #noteToken(token) {
+        if (token?.cell_endpoint)
+            this.#cellHint = token.cell_endpoint;
     }
     /**
-     * Polls GET /v1/operations/{id} with bounded exponential backoff (+-20 % jitter) until it
-     * succeeds (resolves), fails or is canceled (OperationFailedError), or `timeoutMs` passes
-     * (OperationTimeoutError; the operation keeps running and can be awaited again).
+     * Opens a connection to the last known cell endpoint in the background (GET /healthz, body discarded), so the
+     * first tool call after the open reuses it instead of paying the TCP and TLS handshakes. Best effort: errors are
+     * ignored, and a fetch that closes connections (Connection: close) simply gains nothing.
+     */
+    #preconnect() {
+        const hint = this.#cellHint;
+        if (!hint)
+            return;
+        const { fetch: f, userAgent } = this.#ctx();
+        let url;
+        try {
+            url = new URL('/healthz', hint).toString();
+        }
+        catch {
+            return;
+        }
+        void f(url, { method: 'GET', headers: { 'user-agent': userAgent }, signal: AbortSignal.timeout(5_000) })
+            .then((r) => r.body?.cancel())
+            .catch(() => undefined);
+    }
+    async #issueToken(workspaceId, agentLabel, tools, onRetry) {
+        const body = {};
+        if (agentLabel !== undefined)
+            body.agent_label = agentLabel;
+        if (tools !== undefined)
+            body.tools = [...tools];
+        try {
+            const token = await this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/tool-tokens`, { json: body, ...(onRetry ? { onRetry } : {}) }, this.#auth);
+            this.#noteToken(token);
+            return token;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Waits for an operation: each GET /v1/operations/{id} asks the server to hold the response until the state changes
+     * (`Prefer: wait`, at most 20 s, contracts §3), so completion is seen within one notification of the commit. A server
+     * that does not wait is polled with bounded exponential backoff (+-20 % jitter). Resolves when the operation
+     * succeeds; throws OperationFailedError when it fails or is canceled, OperationTimeoutError after `timeoutMs` (the
+     * operation keeps running and can be awaited again). Both errors carry the wait's `timing`; `onProgress` sees each
+     * state change (queued, capacity_pending, running, with the server's reason) as it is observed.
      */
     async waitForOperation(operationId, opts = {}) {
-        const { sleep } = this.#ctx();
+        const inherited = opts[TRACE];
+        const trace = inherited ?? new Trace('wait', combineListeners(this.#ctx().onProgress, opts.onProgress), { operationId });
+        const run = () => this.#poll(operationId, opts, trace);
+        if (inherited)
+            return run();
+        // A wait on its own starts with its first poll: a held poll can take seconds before the first state is known.
+        trace.phase('request');
+        return traced(trace, run);
+    }
+    async #poll(operationId, opts, trace) {
+        const { sleep, http, authorization } = this.#ctx();
         const timeoutMs = opts.timeoutMs ?? 300_000;
         const maxInterval = opts.maxPollIntervalMs ?? 5_000;
         let interval = opts.pollIntervalMs ?? 250;
         const started = Date.now();
         const aborted = () => (opts.signal?.reason instanceof Error ? opts.signal.reason : new Error('aborted'));
+        let lastKey = null;
         for (;;) {
             if (opts.signal?.aborted)
                 throw aborted();
-            const operation = await this.getOperation(operationId, opts.signal ? { signal: opts.signal } : {});
+            const waitS = opts.serverWait === false ? 0 : (timeoutMs - (Date.now() - started)) / 1000;
+            const t0 = Date.now();
+            const { body, applied } = await pollWithWait(http, `/v1/operations/${encodeURIComponent(operationId)}`, authorization, waitS, opts.signal, trace.onRetry);
+            const operation = body.operation;
+            trace.observe(operation);
             if (operation.state === 'succeeded')
                 return operation;
             if (TERMINAL.has(operation.state))
@@ -80,6 +205,13 @@ export class WorkspacesApi {
             const waited = Date.now() - started;
             if (waited >= timeoutMs)
                 throw new OperationTimeoutError(operation, waited);
+            const key = `${operation.state}/${operation.state_reason ?? ''}`;
+            // The server held the poll (or answered a change): ask again at once. An applied wait that returned quickly with
+            // no change falls through to the backoff, so a misbehaving server can never make this loop spin.
+            const changed = key !== lastKey;
+            lastKey = key;
+            if (applied && (changed || Date.now() - t0 >= 1_000))
+                continue;
             const jitter = interval * 0.2 * (Math.random() * 2 - 1);
             const delay = Math.max(10, Math.min(interval + jitter, timeoutMs - waited));
             // The wait itself is abortable: a signal ends it at once instead of after the sleep.
@@ -94,8 +226,8 @@ export class WorkspacesApi {
         const { operation } = await this.#http.json('GET', `/v1/operations/${encodeURIComponent(operationId)}`, opts.signal ? { signal: opts.signal } : {}, this.#auth);
         return operation;
     }
-    async #getView(workspaceId) {
-        return this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}`, {}, this.#auth);
+    async #getView(workspaceId, onRetry) {
+        return this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}`, onRetry ? { onRetry } : {}, this.#auth);
     }
     async get(workspaceId, opts = {}) {
         return this.#wrap(await this.#getView(workspaceId), opts);
@@ -109,6 +241,8 @@ export class WorkspacesApi {
                 project_id: params.projectId,
                 organization_id: params.organizationId,
                 include_deleted: params.includeDeleted,
+                lifetime: params.lifetime,
+                purpose: params.purpose,
                 limit: params.limit,
                 cursor: params.cursor,
             },
@@ -124,25 +258,98 @@ export class WorkspacesApi {
             cursor = page.nextCursor ?? undefined;
         } while (cursor);
     }
-    async #lifecycle(method, path, json, idempotencyKey) {
-        return this.#http.json(method, path, { ...(json === undefined ? {} : { json }), idempotencyKey: idempotencyKey ?? randomId('op-') }, this.#auth);
+    /**
+     * Looks a workspace up by its exact key across every lifetime and purpose (`lifetime=any&purpose=any`), preferring the
+     * live workspace over tombstones of ended sessions or deleted workspaces with the same key (see pickByKey). Null when
+     * no workspace of the project has the key. This is the lookup the CLI and the MCP server use.
+     */
+    async findByKey(key, opts = {}) {
+        const includeDeleted = opts.includeDeleted !== false;
+        const seen = [];
+        let cursor;
+        do {
+            if (opts.signal?.aborted)
+                throw opts.signal.reason instanceof Error ? opts.signal.reason : new Error('aborted');
+            const page = await this.#http.json('GET', '/v1/workspaces', {
+                query: {
+                    key_prefix: key,
+                    lifetime: 'any',
+                    purpose: 'any',
+                    include_deleted: includeDeleted,
+                    project_id: opts.projectId,
+                    organization_id: opts.organizationId,
+                    limit: 200,
+                    cursor,
+                },
+                ...(opts.signal ? { signal: opts.signal } : {}),
+            }, this.#auth);
+            const live = page.data.find((v) => v.workspace_key === key && v.deleted_at === null);
+            if (live)
+                return this.#wrap(live, { agentLabel: opts.agentLabel, tools: opts.tools });
+            seen.push(...page.data.filter((v) => v.workspace_key === key));
+            cursor = page.next_cursor ?? undefined;
+        } while (cursor);
+        const hit = pickByKey(seen, key);
+        return hit ? this.#wrap(hit, { agentLabel: opts.agentLabel, tools: opts.tools }) : null;
+    }
+    async #lifecycle(method, path, json, idempotencyKey, init = {}) {
+        return this.#http.json(method, path, { ...(json === undefined ? {} : { json }), idempotencyKey: idempotencyKey ?? randomId('op-'), ...init }, this.#auth);
+    }
+    #op(kind, workspaceId, json, opts) {
+        const path = `/v1/workspaces/${encodeURIComponent(workspaceId)}${kind === 'delete' ? '' : `/${kind}`}`;
+        return runLifecycle(this.#ctx(), kind, workspaceId, async (init) => (await this.#lifecycle(kind === 'delete' ? 'DELETE' : 'POST', path, json, opts.idempotencyKey, init)).operation, opts);
     }
-    /** Tombstones the workspace now (tool access revoked); storage cleanup happens asynchronously. */
-    async delete(workspaceId, opts = {}) {
-        return (await this.#lifecycle('DELETE', `/v1/workspaces/${encodeURIComponent(workspaceId)}`, undefined, opts.idempotencyKey)).operation;
+    delete(workspaceId, opts = {}) {
+        return this.#op('delete', workspaceId, undefined, opts);
     }
-    async suspend(workspaceId, opts = {}) {
-        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/suspend`, undefined, opts.idempotencyKey)).operation;
+    suspend(workspaceId, opts = {}) {
+        return this.#op('suspend', workspaceId, undefined, opts);
     }
-    async resume(workspaceId, opts = {}) {
-        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/resume`, undefined, opts.idempotencyKey)).operation;
+    resume(workspaceId, opts = {}) {
+        return this.#op('resume', workspaceId, undefined, opts);
     }
-    async snapshot(workspaceId, opts = {}) {
-        return (await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/snapshot`, opts.label === undefined ? {} : { label: opts.label }, opts.idempotencyKey)).operation;
+    snapshot(workspaceId, opts = {}) {
+        return this.#op('snapshot', workspaceId, opts.label === undefined ? {} : { label: opts.label }, opts);
+    }
+    async close(workspaceId, opts = {}) {
+        return (await this.closeWithView(workspaceId, opts)).operation;
+    }
+    /** close() plus the workspace view after the close (a tombstone). */
+    async closeWithView(workspaceId, opts = {}) {
+        let workspace;
+        const operation = await runLifecycle(this.#ctx(), 'close', workspaceId, async (init) => {
+            const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/close`, undefined, opts.idempotencyKey, init);
+            workspace = out.workspace;
+            return out.operation;
+        }, opts);
+        return { operation, workspace: workspace };
+    }
+    reset(workspaceId, opts = {}) {
+        const body = { confirm_destructive: true };
+        return this.#op('reset', workspaceId, body, opts);
+    }
+    /**
+     * Saves a layered workspace as the next version of an organization template (contracts §19.8). A running workspace is
+     * captured briefly (`operation`, layer_snapshot); poll `build` with templates.builds.waitForBuild. Owners/admins and
+     * API keys with a tool permission only.
+     */
+    saveAsTemplate(workspaceId, params) {
+        return this.#http.json('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/save-as-template`, { json: saveAsTemplateBody(params), idempotencyKey: params.idempotencyKey ?? randomId('save-') }, this.#auth);
     }
     async fork(workspaceId, target, opts = {}) {
-        const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, target, opts.idempotencyKey);
-        return { operation: out.operation, workspace: this.#wrap(out.workspace) };
+        let copy;
+        const operation = await runLifecycle(this.#ctx(), 'fork', workspaceId, async (init) => {
+            const out = await this.#lifecycle('POST', `/v1/workspaces/${encodeURIComponent(workspaceId)}/fork`, target, opts.idempotencyKey, init);
+            copy = this.#wrap(out.workspace);
+            return out.operation;
+        }, {
+            ...opts,
+            [AFTER_WAIT]: async (trace, op) => {
+                await trace.span('view', () => copy.refresh());
+                await opts[AFTER_WAIT]?.(trace, op);
+            },
+        });
+        return { operation, workspace: copy };
     }
     async operations(workspaceId, params = {}) {
         const page = await this.#http.json('GET', `/v1/workspaces/${encodeURIComponent(workspaceId)}/operations`, { query: { limit: params.limit, cursor: params.cursor, state: params.state, kind: params.kind } }, this.#auth);
@@ -203,7 +410,7 @@ export class Shardflux {
     constructor(opts) {
         if (!/^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/.test(opts.apiKey))
             throw new Error('apiKey must be a Shardflux project key (sfk_<key_id>_<secret>)');
-        const f = opts.fetch ?? fetch;
+        const f = opts.fetch ?? defaultFetch();
         const userAgent = opts.userAgent ?? `shardflux-sdk-ts/${SDK_VERSION}`;
         const sleep = opts.sleep ?? defaultSleep;
         this.workspaces = new WorkspacesApi(() => this.#ctx);
@@ -221,6 +428,7 @@ export class Shardflux {
             userAgent,
             sleep,
             workspaces: this.workspaces,
+            onProgress: opts.onProgress,
         };
     }
     /** The authenticated principal (the API key, its organization and project). */

package/dist/errors.d.ts

@@ -1,10 +1,22 @@
 import type { components as AppComponents } from './generated/app-api.js';
 import type { components as CellComponents } from './generated/cell-api.js';
+import type { LifecycleTiming } from './progress.js';
 export type AppErrorBody = AppComponents['schemas']['ErrorBody'];
 export type AppErrorCode = AppErrorBody['error']['code'];
 export type CellErrorCode = CellComponents['schemas']['ErrorCode'];
 /** Closed error codes of the application API and the cell gateway (both published in OpenAPI). */
 export type ErrorCode = AppErrorCode | CellErrorCode;
+/**
+ * `details.reason` values the SDK knows (the error code enum is closed; new cases add reasons). Templates v2
+ * (contracts §19.14) added: 409 conflict legacy_disk_layout, not_session, session_lifetime, lifetime_mismatch,
+ * not_resettable, template_not_layered, draft_exists, draft_stale, build_in_progress, file_list_unavailable,
+ * file_list_indexing (retryable), guest_feature_unavailable; 422 validation_failed confirm_destructive_required,
+ * reserved_key_prefix, invalid_defaults, update_policy_not_available, invalid_path, too_many_acknowledged_findings;
+ * 403 forbidden template_dev_mode_role; 404 not_found draft_not_found, version_not_found, path_not_found.
+ */
+export type KnownErrorReason = 'workspace_not_running' | 'operation_in_progress' | 'workspace_deleted' | 'secret_not_available' | 'legacy_disk_layout' | 'not_session' | 'session_lifetime' | 'lifetime_mismatch' | 'not_resettable' | 'template_not_layered' | 'draft_exists' | 'draft_stale' | 'build_in_progress' | 'file_list_unavailable' | 'file_list_indexing' | 'guest_feature_unavailable' | 'confirm_destructive_required' | 'reserved_key_prefix' | 'invalid_defaults' | 'update_policy_not_available' | 'invalid_path' | 'too_many_acknowledged_findings' | 'template_dev_mode_role' | 'draft_not_found' | 'version_not_found' | 'path_not_found';
+/** A known reason, or any other string the server sends (reasons are open-ended). */
+export type ErrorReason = KnownErrorReason | (string & {});
 export interface ErrorBodyLike {
     error: {
         code: string;
@@ -26,6 +38,10 @@ export declare class ShardfluxApiError extends Error {
     readonly operationId: string | undefined;
     readonly source: 'api' | 'cell';
     readonly retryAfterSeconds: number | undefined;
+    /** `details.reason` when it is a string (e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`). */
+    readonly reason: ErrorReason | undefined;
+    /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
+    timing: LifecycleTiming | undefined;
     constructor(status: number, body: ErrorBodyLike, source: 'api' | 'cell', retryAfterSeconds?: number);
 }
 /** The response was not the documented shape (e.g. a proxy error page). */
@@ -45,6 +61,8 @@ export declare class OperationTimeoutError extends Error {
     readonly lastState: Operation['state'];
     readonly lastReason: string | null;
     readonly waitedMs: number;
+    /** Where the time went: client phases, retries and the operation's own server timing so far. */
+    timing: LifecycleTiming | undefined;
     constructor(op: Operation, waitedMs: number);
 }
 /** The operation reached `failed` or `canceled`. */
@@ -52,6 +70,8 @@ export declare class OperationFailedError extends Error {
     readonly operation: Operation;
     readonly operationId: string;
     readonly errorCode: string | null;
+    /** Where the time went before the operation failed. */
+    timing: LifecycleTiming | undefined;
     constructor(op: Operation);
 }
 export {};

package/dist/errors.js

@@ -14,6 +14,10 @@ export class ShardfluxApiError extends Error {
     operationId;
     source;
     retryAfterSeconds;
+    /** `details.reason` when it is a string (e.g. `not_session`, `draft_not_found`, `legacy_disk_layout`). */
+    reason;
+    /** Where the time went when a traced call (open, a waited lifecycle call, a wake) failed with this error. */
+    timing = undefined;
     constructor(status, body, source, retryAfterSeconds) {
         super(body.error.message);
         this.name = 'ShardfluxApiError';
@@ -25,6 +29,8 @@ export class ShardfluxApiError extends Error {
         this.operationId = body.error.operation_id;
         this.source = source;
         this.retryAfterSeconds = retryAfterSeconds;
+        const reason = body.error.details?.reason;
+        this.reason = typeof reason === 'string' ? reason : undefined;
     }
 }
 /** The response was not the documented shape (e.g. a proxy error page). */
@@ -47,6 +53,8 @@ export class OperationTimeoutError extends Error {
     lastState;
     lastReason;
     waitedMs;
+    /** Where the time went: client phases, retries and the operation's own server timing so far. */
+    timing = undefined;
     constructor(op, waitedMs) {
         super(`Operation ${op.id} (${op.kind}) is still ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''} after ${Math.round(waitedMs)} ms; it continues server side.`);
         this.name = 'OperationTimeoutError';
@@ -62,6 +70,8 @@ export class OperationFailedError extends Error {
     operation;
     operationId;
     errorCode;
+    /** Where the time went before the operation failed. */
+    timing = undefined;
     constructor(op) {
         const code = typeof op.error?.code === 'string' ? op.error.code : null;
         super(`Operation ${op.id} (${op.kind}) ${op.state}${code ? `: ${code}` : ''}`);