AIDK API Reference / aidk-kernel / ProcedureWithHandle

Type Alias: ProcedureWithHandle()<THandler>

type ProcedureWithHandle<THandler> = {
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
};

Defined in: packages/kernel/src/procedure.ts:402

A procedure variant that returns an execution handle along with the result.

Obtained by calling .withHandle() on a Procedure. Useful for:

• Subscribing to execution events (progress, errors, completion)
• Correlating execution via trace ID
• Cancelling long-running operations

Example

const proc = createProcedure(async function* (count: number) {
  for (let i = 0; i < count; i++) {
    yield { progress: i / count };
  }
});

const { handle, result } = proc.withHandle()(10);
handle.events.on('stream:chunk', (e) => console.log('Progress:', e.payload));
const final = await result;

See

• Procedure.withHandle - Create a ProcedureWithHandle
• ExecutionHandle - The handle interface

Type Parameters

Type Parameter	Description
THandler extends (...args: any[]) => any	The function type being wrapped

type ProcedureWithHandle(...args: ExtractArgs<THandler>): {
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
};

Defined in: packages/kernel/src/procedure.ts:404

Call the procedure, returning both handle and result promise

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

{
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
}

Name	Type	Defined in
handle	ExecutionHandle<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:405
result	Promise<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:406

Methods

call()

call(...args: ExtractArgs<THandler>): {
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
};

Defined in: packages/kernel/src/procedure.ts:409

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

{
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
}

Name	Type	Defined in
handle	ExecutionHandle<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:410
result	Promise<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:411

Deprecated

Use direct call or .run() instead

---

run()

run(...args: ExtractArgs<THandler>): {
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
};

Defined in: packages/kernel/src/procedure.ts:414

Run the procedure, returning both handle and result promise

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

{
  handle: ExecutionHandle<ExtractReturn<THandler>>;
  result: Promise<ExtractReturn<THandler>>;
}

Name	Type	Defined in
handle	ExecutionHandle<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:415
result	Promise<ExtractReturn<THandler>>	packages/kernel/src/procedure.ts:416

---

use()

use(...middleware: (
  | MiddlewarePipeline
  | Middleware<ExtractArgs<THandler>>)[]): ProcedureWithHandle<THandler>;

Defined in: packages/kernel/src/procedure.ts:419

Add middleware. Returns a new ProcedureWithHandle.

Parameters

Parameter	Type
...middleware	( | MiddlewarePipeline | Middleware<ExtractArgs<THandler>>)[]

Returns

ProcedureWithHandle<THandler>

---

withContext()

withContext(ctx: Partial<KernelContext>): ProcedureWithHandle<THandler>;

Defined in: packages/kernel/src/procedure.ts:423

Create variant with merged context. Returns a new ProcedureWithHandle.

Parameters

Parameter	Type
ctx	Partial<KernelContext>

Returns

ProcedureWithHandle<THandler>

---

withMetadata()

withMetadata(metadata: Record<string, unknown>): ProcedureWithHandle<THandler>;

Defined in: packages/kernel/src/procedure.ts:431

Create variant with merged metadata. Returns a new ProcedureWithHandle.

Parameters

Parameter	Type
metadata	Record<string, unknown>

Returns

ProcedureWithHandle<THandler>

---

withMiddleware()

withMiddleware(mw: 
  | MiddlewarePipeline
  | Middleware<ExtractArgs<THandler>>): ProcedureWithHandle<THandler>;

Defined in: packages/kernel/src/procedure.ts:425

Add single middleware. Returns a new ProcedureWithHandle.

Parameters

Parameter	Type
mw	| MiddlewarePipeline | Middleware<ExtractArgs<THandler>>

Returns

ProcedureWithHandle<THandler>

---

withTimeout()

withTimeout(ms: number): ProcedureWithHandle<THandler>;

Defined in: packages/kernel/src/procedure.ts:429

Create variant with timeout. Returns a new ProcedureWithHandle.

Parameters

Parameter	Type
ms	number

Returns

ProcedureWithHandle<THandler>