Workspaces

A workspace binding is a runtime seat for the current external app × external agent × external user triple. It is what backs capabilities that need durable state — a context library of files, scripts, a container.

ensureWorkspace() is optional. Chat-only integrations never need it.

Materializing a binding

const workspace = await client.ensureWorkspace({
  requestedCapabilities: ['files'],
  clientWorkspaceKey: 'checkout-support-seat',
});

console.log(workspace.workspaceBindingRef, workspace.capabilitiesEnabled);

clientWorkspaceKey is an idempotency key. Reuse the same value for the same logical seat and you get the same binding back with created: false, instead of accumulating seats.

EnsureWorkspaceResult returns workspaceBindingRef, an optional workspaceRef, status, created, capabilitiesEnabled, and policy. Note that capabilitiesEnabled is what you were actually granted — it can be narrower than requestedCapabilities.

The call is headless HTTP client logic and returns public refs only. Raw AgentShelf workspace IDs, runtime IDs, storage IDs, bucket names, and tool binding IDs are never part of the response.

Waiting for the runtime

A binding can exist before its runtime is ready. Two methods cover this:

const status = await client.getWorkspaceRuntimeStatus();

if (!status.ready) {
  await client.waitForWorkspaceRuntime({
    timeoutMs: 60_000,
    pollIntervalMs: 2_000,
  });
}

WorkspaceRuntimeStatus reports lifecycleState, status, and the booleans worth branching on — ready, provisioning, failed, canRunScripts, hasContainer — plus an optional statusMessage you can surface while the user waits.

Both accept an AbortSignal, so a user navigating away can cancel the poll:

const controller = new AbortController();
await client.waitForWorkspaceRuntime({ signal: controller.signal });

waitForWorkspaceRuntime rejects with a timeout error code if the runtime does not become ready in time, and an aborted code if the signal fires. Treat failed: true as terminal — re-polling will not recover it.

When you need one

Scenario	Workspace needed
Chat, streaming, artifacts	No
Context-library file operations	Yes
Anything requiring canRunScripts	Yes

Context-library file operations require a materialized binding and policy support — see Files and artifacts.