Executions & control

Long-running work usually means lost work — a timeout hits and the agent has nothing. Not here: every tool call, batch, and workbench run is a recorded execution your agent can check on, wait for, replay, or cancel — even after a timeout or disconnect.

15 sDefault waitserver-side, no polling loops

50 sMax wait per callthen wait again — work keeps running

5 MBEvent output budgetbigger results become artifacts

ReplayableEvent streamresume from any sequence point

The model

Field	Values
`executionKind`	`tool` · `batch` · `workbench_bash` · `workbench_code`
Terminal `status`	`completed` · `failed` · `partial_failed` · `cancelled` · `timed_out`
Capability	`cancellable`, `streamingSupport`, `backgroundSupport` on every execution

The control surface

Workbench agents receive one lifecycle meta-tool. REST and the TypeScript/Python SDKs keep direct methods for all execution kinds used by host applications and the dashboard.

Tool/action	What it does
`STACKLINK_WORKBENCH_EXECUTION` / `list`	List Workbench history by runtime kind, workspace, status and cursor. Returns `nextCursor` and `liveCount`.
`STACKLINK_WORKBENCH_EXECUTION` / `get`	Read one Workbench execution and optionally its first event page.
`STACKLINK_WORKBENCH_EXECUTION` / `events`	Replay ordered durable events after `afterSequence`; returns `hasMore` and `nextCursor`.
`STACKLINK_WORKBENCH_EXECUTION` / `wait`	Wait up to 50 seconds; `wait_timeout` means the execution is still running.
`STACKLINK_WORKBENCH_EXECUTION` / `cancel`	Request or confirm cancellation with an optional `reason`.

Fire, work, then collect

const run = await session.runWorkbenchBash({ command: 'python build_report.py', background: true });

// ...do other work...

const result = await session.waitForExecution({
  executionKind: 'workbench_bash',
  executionId: run.executionId,
  waitTimeoutMs: 30_000,
});

Cancellation semantics

The cancellable capability tells you what cancel actually does:

Value	Meaning
`hard`	Workbench bash/code: the sandbox process is terminated; status moves `cancel_requested` → `cancelled`.
`request_only`	Tool/batch: the request is recorded and honored asynchronously — the provider call may still finish.

Event stream limits

Execution events carry sequence, eventType, status, message, progress/total, and outputDelta. Output captured into events is budgeted: 5 MB per execution (STACKLINK_EXECUTION_EVENT_OUTPUT_BUDGET_BYTES) in deltas of up to 64 KB (STACKLINK_EXECUTION_EVENT_DELTA_MAX_BYTES). Larger outputs come back as artifacts.

Idempotency

STACKLINK_EXECUTE_TOOL and STACKLINK_MULTI_EXECUTE_TOOL accept an idempotencyKey. Replaying the same key returns the original execution record instead of running the tool twice — use it for any mutation an agent might retry.

Reading executions requires the logs:read scope; executing requires tools:execute.