Documentation / @agentick/core / ExecutionHandle

Interface: ExecutionHandle<TResult, TEvent>

Handle for monitoring and controlling a running procedure execution.

ExecutionHandle is AsyncIterable for streaming events. Use .result to get the final value as a Promise.

NOTE: ExecutionHandle is NOT PromiseLike. This is intentional - it allows procedures to return ProcedurePromise<ExecutionHandle> where await proc() gives you the handle (not the result). Use await handle.result for the final value, or await proc().result for a one-liner.

Examples

typescript

const handle = await myProc('input');
handle.status;  // 'running'
const result = await handle.result;

typescript

const result = await myProc('input').result;

typescript

const handle = await myProc('input');
for await (const event of handle) {
  console.log('Event:', event);
}

typescript

const handle = await myProc('input');
console.log('Status:', handle.status);  // 'running'
handle.abort('user cancelled');
console.log('Status:', handle.status);  // 'aborted'

See

ExecutionHandleImpl - Default implementation
HandleFactory - Custom handle factory function type

Extends

AsyncIterable<TEvent>

Extended by

SessionExecutionHandle

Type Parameters

TResult

TResult

The return type of the procedure

TEvent

TEvent extends TypedEvent = any

The event type for streaming (defaults to any)

Properties

[ExecutionHandleBrand]

readonly [ExecutionHandleBrand]: true

Defined in: kernel/src/procedure.ts:260

Brand identifying this as an ExecutionHandle (not a plain AsyncIterable)

events

readonly events: EventBuffer<TEvent>

Defined in: kernel/src/procedure.ts:283

Event buffer for streaming execution events. Supports dual consumption - multiple iterators can independently consume all events. Late subscribers receive replayed events from the start.

API is compatible with EventEmitter: on, once, off, emit, addListener, removeListener. Use on('eventType', handler) to subscribe to specific event types. Use on(handler) or on('*', handler) for wildcard subscription.

result

readonly result: Promise<TResult>

Defined in: kernel/src/procedure.ts:292

Promise that resolves with the final result. Use await handle.result to get the value.

status

readonly status: "error" | "pending" | "running" | "completed" | "failed" | "cancelled" | "aborted"

Defined in: kernel/src/procedure.ts:262

Current execution status

traceId

readonly traceId: string

Defined in: kernel/src/procedure.ts:272

Trace ID for distributed tracing correlation

Methods

[asyncIterator]()

[asyncIterator](): AsyncIterator<TEvent>

Defined in: kernel/src/procedure.ts:295

Returns

AsyncIterator<TEvent>

Overrides

AsyncIterable.[asyncIterator]

abort()

abort(reason?): void

Defined in: kernel/src/procedure.ts:286

Abort the execution

Parameters

reason?

string

Returns

void

knob

Functions