AIDK API Reference / aidk-kernel / Procedure

Interface: Procedure()<THandler>

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

A callable function wrapper with middleware, validation, and execution control.

Procedures are the core execution primitive in AIDK. They wrap any async function and provide:

• Middleware pipeline - Transform args, intercept results, handle errors
• Schema validation - Zod-based input validation
• Execution handles - Events and cancellation for long-running operations
• Automatic tracking - Every call is tracked in the procedure graph
• Composition - Chain procedures with .pipe()

Examples

const greet = createProcedure(async (name: string) => `Hello, ${name}!`);
const result = await greet('World'); // 'Hello, World!'

const proc = createProcedure(async (x: number) => x * 2)
  .use(loggingMiddleware)
  .use(timingMiddleware);

const { handle, result } = proc.withHandle()(input);
handle.events.on('stream:chunk', console.log);
const output = await result;

See

• createProcedure - Create a new procedure
• Middleware - Middleware function type
• ExecutionHandle - Handle for execution control

Type Parameters

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

Procedure(...args: ExtractArgs<THandler>): Promise<ExtractReturn<THandler>>;

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

Call the procedure directly. For streams, returns Promise&lt;AsyncIterable<ChunkType&gt;>.

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

Promise<ExtractReturn<THandler>>

Methods

call()

call(...args: ExtractArgs<THandler>): Promise<ExtractReturn<THandler>>;

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

Call the procedure (alias for direct call).

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

Promise<ExtractReturn<THandler>>

Deprecated

Use .run() or direct call instead.

---

pipe()

pipe<TNext>(next: Procedure<TNext>): Procedure<(...args: ExtractArgs<THandler>) => Promise<ExtractReturn<TNext>>>;

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

Pipe the output of this procedure to another procedure. Creates a new procedure that runs this procedure, then passes its result to the next.

Type Parameters

Type Parameter
TNext extends (arg: ExtractReturn<THandler>) => any

Parameters

Parameter	Type
next	Procedure<TNext>

Returns

Procedure<(...args: ExtractArgs<THandler>) => Promise<ExtractReturn<TNext>>>

Example

const parse = createProcedure(async (input: string) => JSON.parse(input));
const validate = createProcedure(async (data: object) => schema.parse(data));
const transform = createProcedure(async (valid: Valid) => transform(valid));

const pipeline = parse.pipe(validate).pipe(transform);
const result = await pipeline('{"name": "test"}');

---

run()

run(...args: ExtractArgs<THandler>): Promise<ExtractReturn<THandler>>;

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

Run the procedure with explicit arguments. Equivalent to direct call.

Parameters

Parameter	Type
...args	ExtractArgs<THandler>

Returns

Promise<ExtractReturn<THandler>>

---

use()

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

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

Add middleware to the procedure. Returns a new Procedure (immutable).

Parameters

Parameter	Type	Description
...middleware	( | MiddlewarePipeline | Middleware<ExtractArgs<THandler>>)[]	Middleware functions or pipelines to add

Returns

Procedure<THandler>

---

withContext()

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

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

Create a procedure variant with merged context. Returns a new Procedure.

Parameters

Parameter	Type	Description
ctx	Partial<KernelContext>	Partial context to merge with the current context

Returns

Procedure<THandler>

---

withHandle()

withHandle(): ProcedureWithHandle<THandler>;

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

Get a procedure variant that returns an execution handle. Useful for subscribing to events and tracking long-running operations.

Returns

ProcedureWithHandle<THandler>

---

withMetadata()

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

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

Create a procedure variant with merged metadata. Returns a new Procedure. Metadata is passed to ExecutionTracker and included in procedure events. Useful for passing model IDs, tool names, or other execution-specific info.

Parameters

Parameter	Type	Description
metadata	Record<string, unknown>	Metadata to merge with existing procedure metadata

Returns

Procedure<THandler>

Example

// Model adapter passes model info
const result = await model.generate
  .withMetadata({ modelId: 'gpt-4o', provider: 'openai' })
  .call(messages);

// Tool passes tool info
const result = await tool.run
  .withMetadata({ toolName: 'search', toolId: 'search-v2' })
  .call(input);

---

withMiddleware()

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

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

Add a single middleware. Returns a new Procedure. Convenience method equivalent to .use(mw).

Parameters

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

Returns

Procedure<THandler>

---

withTimeout()

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

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

Create a procedure variant with a timeout. Returns a new Procedure. Throws AbortError.timeout() if the timeout is exceeded.

Parameters

Parameter	Type	Description
ms	number	Timeout in milliseconds

Returns

Procedure<THandler>