Executions & control
Every run is durable — list it, replay its events, wait on it, cancel it.
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.
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
Router agents receive one lifecycle tool. REST and the TypeScript/Python SDKs keep direct methods for host applications and the dashboard.
| Tool/action | What it does |
|---|---|
STACKLINK_GET_OPERATION / get | Read an exact connection, approval, tool, batch, or Workbench operation. |
STACKLINK_GET_OPERATION / cancel | Request cancellation with an optional reason. |
| Runtime continuation | Studio suspends on connection or approval waits and resumes from terminal platform events. |
| SDK event stream | Host applications replay ordered durable events and reconnect from the last sequence. |
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,
});For live output, consume the durable stream. The SDK reconnects from the last sequence if a bounded stream connection ends; it does not poll execution status.
for await (const event of run.events()) {
console.log(event.eventType, event.outputDelta);
}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.
The REST stream is GET /v1/executions/:executionKind/:executionId/events/stream?sessionId=.... Its SSE id: is the durable event sequence, and Last-Event-ID resumes without losing output. Redis wakes live readers; PostgreSQL remains the replay and recovery source.
Idempotency
STACKLINK_EXECUTE_TOOLS accepts 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.