@agentick/core 0.0.1

package/dist/core/procedure.d.ts

@@ -0,0 +1,755 @@
+/**
+ * New Procedure Implementation - Variable Arity, Decorators, Pipelines
+ *
+ * Design Principles:
+ * - Everything is a Procedure
+ * - Variable arity support (0, 1, N args)
+ * - Decorator = Function (same type)
+ * - Hooks are Procedures (@hook decorator)
+ * - Pipelines for middleware bundles
+ * - Direct calls (no registration)
+ * - Automatic tracking (execution graph, telemetry)
+ */
+import { z } from "zod";
+import { type KernelContext } from "./context";
+import { type ExecutionBoundaryConfig } from "./execution-tracker";
+import type { ExecutionStatus } from "../engine/execution-types";
+import { EventBuffer, type TypedEvent } from "./event-buffer";
+/**
+ * Extract the result type from a handle-like object.
+ * If T has a `result` property that is a Promise, extract its resolved type.
+ */
+export type ResultOf<T> = T extends {
+    result: Promise<infer R>;
+} ? R : T;
+/**
+ * Enhanced Promise returned by all procedures.
+ *
+ * ProcedurePromise extends Promise<T> with a `.result` property that chains
+ * through to the inner result. This allows ergonomic access to final values
+ * without losing access to the handle.
+ *
+ * @typeParam T - The type the promise resolves to (usually a handle or value)
+ *
+ * @example Get the handle
+ * ```typescript
+ * const handle = await run(<Agent />, opts);
+ * handle.status;  // 'running'
+ * for await (const event of handle) { }
+ * ```
+ *
+ * @example Get the result directly
+ * ```typescript
+ * const result = await run(<Agent />, opts).result;
+ * // Equivalent to: (await run(<Agent />, opts)).result
+ * ```
+ *
+ * @example Both work
+ * ```typescript
+ * const promise = run(<Agent />, opts);
+ * const handle = await promise;           // Get handle
+ * const result = await promise.result;    // Get final result
+ * ```
+ */
+export interface ProcedurePromise<T> extends Promise<T> {
+    /**
+     * Promise that resolves to the final result.
+     * Chains through to T.result if T has a result property.
+     */
+    readonly result: Promise<ResultOf<T>>;
+}
+/**
+ * Create a ProcedurePromise from a regular Promise.
+ *
+ * Adds a `.result` property that chains through to the inner handle's result.
+ * If the resolved value has a `.result` property, `.result` resolves to that.
+ * Otherwise, `.result` resolves to the value itself.
+ *
+ * @param promise - The base promise to enhance
+ * @returns Enhanced ProcedurePromise with .result chaining
+ */
+export declare function createProcedurePromise<T>(promise: Promise<T>): ProcedurePromise<T>;
+/**
+ * Symbol used to brand Procedure objects for deterministic type checking.
+ * Using Symbol.for() ensures the same symbol across module instances.
+ */
+export declare const PROCEDURE_SYMBOL: unique symbol;
+/**
+ * Check if a value is a Procedure using Symbol branding.
+ *
+ * This is more reliable than duck typing because it uses a unique Symbol
+ * that can only be present on objects created by the procedure system.
+ *
+ * @param value - The value to check
+ * @returns True if the value is a branded Procedure
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure(async (x: number) => x * 2);
+ * isProcedure(proc); // true
+ * isProcedure(() => {}); // false
+ * isProcedure({ use: () => {} }); // false (duck typing would say true)
+ * ```
+ */
+export declare function isProcedure(value: any): value is Procedure<any>;
+/**
+ * Middleware function that can intercept and transform procedure execution.
+ *
+ * Middleware can:
+ * - Transform input arguments before passing to the next middleware/handler
+ * - Modify the result after `next()` returns
+ * - Short-circuit execution by not calling `next()`
+ * - Handle or transform errors
+ *
+ * @typeParam TArgs - The argument types of the procedure
+ *
+ * @example
+ * ```typescript
+ * const loggingMiddleware: Middleware<[string]> = async (args, envelope, next) => {
+ *   console.log(`${envelope.operationName} called with:`, args);
+ *   const start = Date.now();
+ *   try {
+ *     const result = await next();
+ *     console.log(`Completed in ${Date.now() - start}ms`);
+ *     return result;
+ *   } catch (error) {
+ *     console.error(`Failed:`, error);
+ *     throw error;
+ *   }
+ * };
+ * ```
+ *
+ * @example Transform arguments
+ * ```typescript
+ * const upperMiddleware: Middleware<[string]> = async (args, envelope, next) => {
+ *   return next([args[0].toUpperCase()]);
+ * };
+ * ```
+ *
+ * @see {@link ProcedureEnvelope} - The envelope containing execution metadata
+ * @see {@link createPipeline} - Bundle multiple middleware for reuse
+ */
+export type Middleware<TArgs extends any[] = any[]> = (args: TArgs, envelope: ProcedureEnvelope<TArgs>, next: (transformedArgs?: TArgs) => Promise<any>) => Promise<any>;
+/**
+ * Metadata envelope passed to middleware containing execution context.
+ *
+ * @typeParam TArgs - The argument types of the procedure
+ *
+ * @example
+ * ```typescript
+ * const middleware: Middleware<[string]> = async (args, envelope, next) => {
+ *   if (envelope.sourceType === 'hook') {
+ *     console.log(`Hook ${envelope.operationName} from ${envelope.sourceId}`);
+ *   }
+ *   return next();
+ * };
+ * ```
+ */
+export interface ProcedureEnvelope<TArgs extends any[]> {
+    /** Whether this is a regular procedure or a hook */
+    sourceType: "procedure" | "hook";
+    /** Identifier of the source (e.g., class name for decorated methods) */
+    sourceId?: string;
+    /** Name of the operation being executed */
+    operationName: string;
+    /** The arguments passed to the procedure */
+    args: TArgs;
+    /** The current kernel context */
+    context: KernelContext;
+}
+/**
+ * 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.
+ *
+ * @typeParam TResult - The return type of the procedure
+ * @typeParam TEvent - The event type for streaming (defaults to any)
+ *
+ * @example Get handle, then result
+ * ```typescript
+ * const handle = await myProc('input');
+ * handle.status;  // 'running'
+ * const result = await handle.result;
+ * ```
+ *
+ * @example Get result directly
+ * ```typescript
+ * const result = await myProc('input').result;
+ * ```
+ *
+ * @example Stream events
+ * ```typescript
+ * const handle = await myProc('input');
+ * for await (const event of handle) {
+ *   console.log('Event:', event);
+ * }
+ * ```
+ *
+ * @example Access status and control
+ * ```typescript
+ * const handle = await myProc('input');
+ * console.log('Status:', handle.status);  // 'running'
+ * handle.abort('user cancelled');
+ * console.log('Status:', handle.status);  // 'aborted'
+ * ```
+ *
+ * @see {@link ExecutionHandleImpl} - Default implementation
+ * @see {@link HandleFactory} - Custom handle factory function type
+ */
+export interface ExecutionHandle<TResult, TEvent extends TypedEvent = any> extends AsyncIterable<TEvent> {
+    /** Current execution status */
+    readonly status: "running" | "completed" | "error" | "aborted" | ExecutionStatus;
+    /** Trace ID for distributed tracing correlation */
+    readonly traceId: string;
+    /**
+     * 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.
+     */
+    readonly events: EventBuffer<TEvent>;
+    /**
+     * @deprecated Use `events` instead. This is now an alias for backwards compatibility.
+     */
+    readonly eventBuffer: EventBuffer<TEvent>;
+    /** Abort the execution */
+    abort(reason?: string): void;
+    /**
+     * Promise that resolves with the final result.
+     * Use `await handle.result` to get the value.
+     */
+    readonly result: Promise<TResult>;
+    [Symbol.asyncIterator](): AsyncIterator<TEvent>;
+}
+/**
+ * Default implementation of ExecutionHandle.
+ *
+ * Creates a handle that wraps a result promise and event stream.
+ * Uses EventBuffer for dual consumption - multiple iterators can independently
+ * consume all events, and late subscribers receive replayed events.
+ *
+ * @typeParam TResult - The return type of the procedure
+ * @typeParam TEvent - The event type for streaming
+ */
+export declare class ExecutionHandleImpl<TResult, TEvent extends TypedEvent = any> implements ExecutionHandle<TResult, TEvent> {
+    readonly result: Promise<TResult>;
+    readonly traceId: string;
+    private _status;
+    private _abortController;
+    readonly events: EventBuffer<TEvent>;
+    constructor(result: Promise<TResult>, events: EventBuffer<TEvent>, traceId: string, abortController?: AbortController);
+    /**
+     * @deprecated Use `events` instead. This getter exists for backwards compatibility.
+     */
+    get eventBuffer(): EventBuffer<TEvent>;
+    get status(): "running" | "completed" | "error" | "aborted";
+    abort(reason?: string): void;
+    /**
+     * Push an event to the buffer.
+     * This is the primary way to emit events from procedure handlers.
+     */
+    pushEvent(event: TEvent): void;
+    [Symbol.asyncIterator](): AsyncIterator<TEvent>;
+}
+/**
+ * Factory function for creating custom execution handles.
+ *
+ * Use this to provide custom handle implementations with additional
+ * functionality like cancellation, status tracking, or specialized events.
+ *
+ * @typeParam THandle - The custom handle type (must extend ExecutionHandle)
+ * @typeParam TContext - The context type (must extend KernelContext)
+ *
+ * @example
+ * ```typescript
+ * const customHandleFactory: HandleFactory = (events, traceId, result, context, abortController) => {
+ *   const handle = new ExecutionHandleImpl(result, events, traceId, abortController);
+ *   // Add custom properties/methods
+ *   return Object.assign(handle, {
+ *     customMethod() { ... }
+ *   });
+ * };
+ *
+ * const proc = createProcedure(
+ *   { handleFactory: customHandleFactory },
+ *   async (input) => input
+ * );
+ * ```
+ *
+ * @see {@link ExecutionHandle} - The base handle interface
+ * @see {@link ExecutionHandleImpl} - Default implementation
+ */
+export type HandleFactory<THandle extends ExecutionHandle<any, any> = ExecutionHandle<any, any>, TContext extends KernelContext = KernelContext> = (events: EventBuffer<any>, traceId: string, result: Promise<any>, context: TContext, abortController?: AbortController) => THandle;
+/**
+ * Configuration options for creating a procedure.
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure({
+ *   name: 'myProcedure',
+ *   schema: z.object({ input: z.string() }),
+ *   middleware: [loggingMiddleware],
+ *   timeout: 5000,
+ * }, async ({ input }) => input.toUpperCase());
+ * ```
+ *
+ * @see {@link createProcedure} - Create a procedure with these options
+ */
+export interface ProcedureOptions {
+    /** Name of the procedure (used in telemetry and logging) */
+    name?: string;
+    /** Middleware pipeline to apply to this procedure */
+    middleware?: (Middleware<any[]> | MiddlewarePipeline)[];
+    /**
+     * Factory for creating execution handles.
+     *
+     * - `undefined` (default): Creates ExecutionHandleImpl, returns ExecutionHandle
+     * - `HandleFactory`: Creates custom handle, returns that handle type
+     * - `false`: Pass-through mode - no handle created, returns handler result directly
+     *
+     * Use `false` for procedures that delegate to other procedures returning handles,
+     * avoiding double-wrapping.
+     *
+     * @example Pass-through procedure
+     * ```typescript
+     * const run = createProcedure(
+     *   { name: 'tentickle:run', handleFactory: false },
+     *   (element, input) => app.run(input)  // Returns SessionExecutionHandle directly
+     * );
+     * ```
+     */
+    handleFactory?: HandleFactory | true | false;
+    /** Zod schema for input validation */
+    schema?: z.ZodType<any>;
+    /** Parent procedure name (for hooks) */
+    parentProcedure?: string;
+    /** @internal Whether this is a procedure or hook */
+    sourceType?: "procedure" | "hook";
+    /** @internal Source identifier (e.g., class name) */
+    sourceId?: string;
+    /** Metadata for telemetry span attributes (e.g., { type: 'tool', id: 'myTool' }) */
+    metadata?: Record<string, any>;
+    /** Timeout in milliseconds. If exceeded, throws AbortError.timeout() */
+    timeout?: number;
+    /**
+     * Skip ExecutionTracker procedure tracking for this procedure.
+     * Used for transparent wrappers like withContext() that delegate to another procedure.
+     * @internal
+     */
+    skipTracking?: boolean;
+    /**
+     * Declarative execution boundary configuration.
+     *
+     * - `'always'`: Always create a new root execution (engine:execute, engine:stream)
+     * - `'child'`: Always create a new child execution (component_tool, fork, spawn)
+     * - `'auto'`: Create only if not already in an execution (model:generate, model:stream)
+     * - `false`: Never create an execution boundary (compile:tick, internal procedures)
+     *
+     * @default 'auto'
+     */
+    executionBoundary?: ExecutionBoundaryConfig;
+    /**
+     * Explicit execution type (e.g., 'engine', 'model', 'component_tool', 'fork', 'spawn').
+     * If not provided, derived from procedure name.
+     * Only used when this procedure becomes an execution boundary.
+     */
+    executionType?: string;
+}
+/**
+ * A callable function wrapper with middleware, validation, and execution control.
+ *
+ * Procedures are the core execution primitive in Tentickle. They wrap any async function
+ * and provide:
+ * - **Middleware pipeline** - Transform args, intercept results, handle errors
+ * - **Schema validation** - Zod-based input validation
+ * - **Execution handles** - Every call returns ExecutionHandle for control
+ * - **Automatic tracking** - Every call is tracked in the procedure graph
+ * - **Composition** - Chain procedures with `.pipe()`
+ *
+ * Procedures return ExecutionHandle which is both PromiseLike AND AsyncIterable:
+ * - `await proc(args)` → resolves to the result
+ * - `for await (const event of proc(args))` → streams events
+ *
+ * @typeParam THandler - The function type being wrapped
+ *
+ * @example Direct call - await for result
+ * ```typescript
+ * const greet = createProcedure(async (name: string) => `Hello, ${name}!`);
+ * const result = await greet('World'); // 'Hello, World!'
+ * ```
+ *
+ * @example Stream events
+ * ```typescript
+ * const handle = proc(input);
+ * for await (const event of handle) {
+ *   console.log('Event:', event);
+ * }
+ * ```
+ *
+ * @example Access handle status
+ * ```typescript
+ * const handle = proc(input);
+ * console.log('Status:', handle.status);  // 'running'
+ * handle.abort('cancelled');
+ * ```
+ *
+ * @example With middleware
+ * ```typescript
+ * const proc = createProcedure(async (x: number) => x * 2)
+ *   .use(loggingMiddleware)
+ *   .use(timingMiddleware);
+ * ```
+ *
+ * @see {@link createProcedure} - Create a new procedure
+ * @see {@link Middleware} - Middleware function type
+ * @see {@link ExecutionHandle} - Handle for execution control
+ */
+export interface Procedure<THandler extends (...args: any[]) => any, TPassThrough extends boolean = false> {
+    /**
+     * Call the procedure directly.
+     * Returns ProcedurePromise<ExecutionHandle<T>>.
+     *
+     * Usage:
+     * - `await proc()` → ExecutionHandle (with status, streaming, abort)
+     * - `await proc().result` → T (the final value)
+     */
+    (...args: ExtractArgs<THandler>): TPassThrough extends true ? Promise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>>>;
+    /**
+     * Execute the procedure with explicit arguments.
+     * Equivalent to direct call.
+     */
+    exec(...args: ExtractArgs<THandler>): TPassThrough extends true ? Promise<ExtractReturn<THandler>> : ProcedurePromise<ExecutionHandle<ExtractReturn<THandler>>>;
+    /**
+     * Add middleware to the procedure. Returns a new Procedure (immutable).
+     * @param middleware - Middleware functions or pipelines to add
+     */
+    use(...middleware: (Middleware<ExtractArgs<THandler>> | MiddlewarePipeline)[]): Procedure<THandler, TPassThrough>;
+    /**
+     * Create a procedure variant with merged context. Returns a new Procedure.
+     * @param ctx - Partial context to merge with the current context
+     */
+    withContext(ctx: Partial<KernelContext>): Procedure<THandler, TPassThrough>;
+    /**
+     * Add a single middleware. Returns a new Procedure.
+     * Convenience method equivalent to `.use(mw)`.
+     */
+    withMiddleware(mw: Middleware<ExtractArgs<THandler>> | MiddlewarePipeline): Procedure<THandler, TPassThrough>;
+    /**
+     * Create a procedure variant with a timeout. Returns a new Procedure.
+     * Throws `AbortError.timeout()` if the timeout is exceeded.
+     * @param ms - Timeout in milliseconds
+     */
+    withTimeout(ms: number): Procedure<THandler, TPassThrough>;
+    /**
+     * 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.
+     *
+     * @param metadata - Metadata to merge with existing procedure metadata
+     *
+     * @example
+     * ```typescript
+     * // Model adapter passes model info
+     * const result = await model.generate
+     *   .withMetadata({ modelId: 'gpt-4o', provider: 'openai' })
+     *   .exec(messages);
+     *
+     * // Tool passes tool info
+     * const result = await tool.execute
+     *   .withMetadata({ toolName: 'search', toolId: 'search-v2' })
+     *   .exec(input);
+     * ```
+     */
+    withMetadata(metadata: Record<string, unknown>): Procedure<THandler, TPassThrough>;
+    /**
+     * Pipe the output of this procedure to another procedure.
+     * Creates a new procedure that runs this procedure, then passes its result to the next.
+     *
+     * @example
+     * ```typescript
+     * 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"}');
+     * ```
+     */
+    pipe<TNext extends (arg: ExtractReturn<THandler>) => any>(next: Procedure<TNext>): Procedure<(...args: ExtractArgs<THandler>) => Promise<ExtractReturn<TNext>>, TPassThrough>;
+}
+/**
+ * Helper type to extract argument types from a function signature.
+ * Handles functions with `this` parameters and generator functions.
+ *
+ * @example
+ * ```typescript
+ * type Args1 = ExtractArgs<(input: string) => void>; // [string]
+ * type Args2 = ExtractArgs<(this: Test, input: string) => void>; // [string]
+ * type Args3 = ExtractArgs<() => Generator<string>>; // []
+ * ```
+ */
+export type ExtractArgs<T> = T extends {
+    (this: infer _This, ...args: infer Args): any;
+} ? Args : T extends {
+    (...args: infer Args): any;
+} ? Args : T extends {
+    (this: infer _This, ...args: infer Args): Generator<infer _Y, infer _R, infer _N>;
+} ? Args : T extends {
+    (...args: infer Args): Generator<infer _Y, infer _R, infer _N>;
+} ? Args : T extends {
+    (this: infer _This, ...args: infer Args): AsyncGenerator<infer _Y, infer _R, infer _N>;
+} ? Args : T extends {
+    (...args: infer Args): AsyncGenerator<infer _Y, infer _R, infer _N>;
+} ? Args : never;
+/**
+ * Helper type to extract return type from a function signature.
+ * Handles both Promise and direct returns, and unwraps Promise.
+ * Preserves AsyncIterable as-is.
+ */
+export type ExtractReturn<T> = T extends (...args: any[]) => infer Return ? Return extends Promise<infer U> ? U : Return extends AsyncIterable<any> ? Return : Return : never;
+/**
+ * Helper type to transform a method signature to Procedure type.
+ * Extracts args and return type, then creates Procedure<TArgs, TOutput>.
+ *
+ * Use this type to get proper IntelliSense for decorated methods:
+ *
+ * @example
+ * ```typescript
+ * class Model {
+ *   @procedure()
+ *   async execute(input: string): Promise<string> { ... }
+ * }
+ *
+ * // For IntelliSense, you can use:
+ * type ModelWithProcedures = {
+ *   execute: AsProcedure<Model['execute']>;
+ * };
+ *
+ * // Or cast at usage:
+ * const model = new Model();
+ * const execute = model.execute as AsProcedure<typeof model.execute>;
+ * ```
+ */
+export type AsProcedure<T extends (...args: any[]) => any> = Procedure<T>;
+/**
+ * Helper type to transform all methods in a class to Procedures.
+ *
+ * **Primary Use Case**: Use with decorators when you need IntelliSense.
+ *
+ * ```typescript
+ * class Model {
+ *   @procedure()
+ *   async execute(input: string): Promise<string> { ... }
+ * }
+ *
+ * // Most of the time - runtime works perfectly, no types needed
+ * const model = new Model();
+ * await model.execute('test');  // ✅ Works
+ *
+ * // When you need IntelliSense - cast once
+ * const typedModel = model as WithProcedures<Model>;
+ * typedModel.execute.use(...);        // ✅ Full IntelliSense
+ * typedModel.execute.withHandle();    // ✅ Full IntelliSense
+ * ```
+ *
+ * **Alternative**: Use property initializers for full types everywhere:
+ * ```typescript
+ * class Model {
+ *   execute = createProcedure(async (input: string) => input);
+ *   // ✅ Full types always, but more verbose
+ * }
+ * ```
+ */
+export type WithProcedures<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? AsProcedure<T[K]> : T[K];
+};
+/**
+ * A reusable bundle of middleware that can be applied to procedures.
+ *
+ * Pipelines allow you to define common middleware combinations once
+ * and reuse them across multiple procedures.
+ *
+ * @example
+ * ```typescript
+ * const commonPipeline = createPipeline()
+ *   .use(loggingMiddleware)
+ *   .use(timingMiddleware)
+ *   .use(errorHandlingMiddleware);
+ *
+ * const proc1 = createProcedure(handler1).use(commonPipeline);
+ * const proc2 = createProcedure(handler2).use(commonPipeline);
+ * ```
+ *
+ * @see {@link createPipeline} - Create a new middleware pipeline
+ * @see {@link Middleware} - Individual middleware function type
+ */
+export interface MiddlewarePipeline {
+    /** Add middleware to this pipeline. Returns the pipeline for chaining. */
+    use(...middleware: Middleware<any[]>[]): MiddlewarePipeline;
+    /** Get all middleware in this pipeline. */
+    getMiddleware(): Middleware<any[]>[];
+}
+/**
+ * Create a reusable middleware pipeline.
+ *
+ * Pipelines bundle multiple middleware together for reuse across procedures.
+ * They can be passed to `procedure.use()` just like individual middleware.
+ *
+ * @param middleware - Initial middleware to include in the pipeline
+ * @returns A new MiddlewarePipeline
+ *
+ * @example
+ * ```typescript
+ * // Create a pipeline with initial middleware
+ * const authPipeline = createPipeline([authMiddleware, rateLimitMiddleware]);
+ *
+ * // Or build it up with .use()
+ * const logPipeline = createPipeline()
+ *   .use(requestLogging)
+ *   .use(responseLogging);
+ *
+ * // Apply to procedures
+ * const proc = createProcedure(handler)
+ *   .use(authPipeline)
+ *   .use(logPipeline);
+ * ```
+ *
+ * @see {@link MiddlewarePipeline} - The pipeline interface
+ */
+export declare function createPipeline(middleware?: Middleware<any[]>[]): MiddlewarePipeline;
+export declare function isAsyncIterable(obj: any): obj is AsyncIterable<any>;
+/**
+ * Helper to create a generator procedure that captures 'this' context.
+ */
+type Handler<TArgs extends any[]> = ((...args: TArgs) => any) | ((this: any, ...args: TArgs) => any);
+export declare function generatorProcedure<TThis, TArgs extends any[], THandler extends Handler<TArgs>>(optionsOrFn?: ProcedureOptions | THandler, fn?: THandler): Procedure<THandler>;
+/**
+ * Create a Procedure from a function.
+ *
+ * By default, calling the procedure returns an ExecutionHandle.
+ * Use `handleFactory: false` for pass-through mode where the handler's
+ * return value is returned directly (useful for delegating to other procedures).
+ *
+ * @example Standard procedure (returns ExecutionHandle)
+ * ```typescript
+ * const greet = createProcedure(async (name: string) => `Hello, ${name}!`);
+ * const handle = greet('World');  // ExecutionHandle
+ * const result = await handle;    // "Hello, World!"
+ * ```
+ *
+ * @example Pass-through procedure (returns handler result directly)
+ * ```typescript
+ * const run = createProcedure(
+ *   { name: 'tentickle:run', handleFactory: false },
+ *   (element, input) => app.run(input)  // Returns SessionExecutionHandle
+ * );
+ * const handle = run(<jsx />, opts);  // SessionExecutionHandle directly
+ * ```
+ */
+export declare function createProcedure<THandler extends (...args: any[]) => any>(handler: THandler): Procedure<THandler>;
+export declare function createProcedure<THandler extends (...args: any[]) => any>(options: ProcedureOptions & {
+    handleFactory: false;
+}, handler: THandler): Procedure<THandler, true>;
+export declare function createProcedure<THandler extends (...args: any[]) => any>(options: ProcedureOptions, handler: THandler): Procedure<THandler>;
+/**
+ * Pipe multiple procedures together, passing the output of each to the next.
+ *
+ * @example
+ * ```typescript
+ * const parse = createProcedure(async (json: string) => JSON.parse(json));
+ * const validate = createProcedure(async (data: unknown) => schema.parse(data));
+ * const transform = createProcedure(async (valid: Valid) => transform(valid));
+ *
+ * // Create a pipeline that parses, validates, then transforms
+ * const pipeline = pipe(parse, validate, transform);
+ * const result = await pipeline('{"name": "test"}');
+ * ```
+ */
+export declare function pipe<T1 extends (...args: any[]) => any>(p1: Procedure<T1>): Procedure<T1>;
+export declare function pipe<T1 extends (...args: any[]) => any, T2 extends (arg: ExtractReturn<T1>) => any>(p1: Procedure<T1>, p2: Procedure<T2>): Procedure<(...args: ExtractArgs<T1>) => Promise<ExtractReturn<T2>>>;
+export declare function pipe<T1 extends (...args: any[]) => any, T2 extends (arg: ExtractReturn<T1>) => any, T3 extends (arg: ExtractReturn<T2>) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>): Procedure<(...args: ExtractArgs<T1>) => Promise<ExtractReturn<T3>>>;
+export declare function pipe<T1 extends (...args: any[]) => any, T2 extends (arg: ExtractReturn<T1>) => any, T3 extends (arg: ExtractReturn<T2>) => any, T4 extends (arg: ExtractReturn<T3>) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>, p4: Procedure<T4>): Procedure<(...args: ExtractArgs<T1>) => Promise<ExtractReturn<T4>>>;
+export declare function pipe<T1 extends (...args: any[]) => any, T2 extends (arg: ExtractReturn<T1>) => any, T3 extends (arg: ExtractReturn<T2>) => any, T4 extends (arg: ExtractReturn<T3>) => any, T5 extends (arg: ExtractReturn<T4>) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>, p4: Procedure<T4>, p5: Procedure<T5>): Procedure<(...args: ExtractArgs<T1>) => Promise<ExtractReturn<T5>>>;
+/**
+ * Compose multiple procedures into a single procedure (right-to-left execution).
+ * This is the functional programming convention: compose(a, b, c)(x) = a(b(c(x)))
+ *
+ * For left-to-right execution, use `pipe()` instead.
+ *
+ * @example
+ * ```typescript
+ * const format = createProcedure((s: string) => s.toUpperCase());
+ * const validate = createProcedure((s: string) => s.trim());
+ * const parse = createProcedure((input: string) => input);
+ *
+ * // compose executes right-to-left: parse -> validate -> format
+ * const pipeline = compose(format, validate, parse);
+ * const result = await pipeline('  hello  '); // "HELLO"
+ * ```
+ */
+export declare function compose<T1 extends (...args: any[]) => any>(p1: Procedure<T1>): Procedure<T1>;
+export declare function compose<T1 extends (arg: ExtractReturn<T2>) => any, T2 extends (...args: any[]) => any>(p1: Procedure<T1>, p2: Procedure<T2>): Procedure<(...args: ExtractArgs<T2>) => Promise<ExtractReturn<T1>>>;
+export declare function compose<T1 extends (arg: ExtractReturn<T2>) => any, T2 extends (arg: ExtractReturn<T3>) => any, T3 extends (...args: any[]) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>): Procedure<(...args: ExtractArgs<T3>) => Promise<ExtractReturn<T1>>>;
+export declare function compose<T1 extends (arg: ExtractReturn<T2>) => any, T2 extends (arg: ExtractReturn<T3>) => any, T3 extends (arg: ExtractReturn<T4>) => any, T4 extends (...args: any[]) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>, p4: Procedure<T4>): Procedure<(...args: ExtractArgs<T4>) => Promise<ExtractReturn<T1>>>;
+export declare function compose<T1 extends (arg: ExtractReturn<T2>) => any, T2 extends (arg: ExtractReturn<T3>) => any, T3 extends (arg: ExtractReturn<T4>) => any, T4 extends (arg: ExtractReturn<T5>) => any, T5 extends (...args: any[]) => any>(p1: Procedure<T1>, p2: Procedure<T2>, p3: Procedure<T3>, p4: Procedure<T4>, p5: Procedure<T5>): Procedure<(...args: ExtractArgs<T5>) => Promise<ExtractReturn<T1>>>;
+/**
+ * Create a Hook Procedure from a function.
+ *
+ * @example
+ * ```typescript
+ * const processChunk = createHook(async (chunk: string) => chunk.toUpperCase());
+ * // Type inferred: Procedure<[string], string>
+ * ```
+ */
+export declare function createHook<THandler extends (...args: any[]) => any>(handler: THandler): Procedure<THandler>;
+export declare function createHook<THandler extends (...args: any[]) => any>(options: ProcedureOptions, handler: THandler): Procedure<THandler>;
+/**
+ * Type-safe helper to apply middleware to a Procedure while preserving types.
+ *
+ * This helper ensures that middleware types are correctly matched to the Procedure's
+ * argument types, avoiding the need for type assertions.
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure({ name: 'test' }, async (input: string) => input);
+ * const middleware: Middleware<[string]>[] = [...];
+ * const procWithMw = applyMiddleware(proc, middleware);
+ * // procWithMw is still Procedure<[string], string> - types preserved!
+ * ```
+ */
+export declare function applyMiddleware<TArgs extends any[], TOutput>(procedure: Procedure<(...args: TArgs) => TOutput>, ...middleware: (Middleware<TArgs> | MiddlewarePipeline)[]): Procedure<(...args: TArgs) => TOutput>;
+/**
+ * Type-safe helper to apply middleware from a registry/hook system.
+ *
+ * This is useful when middleware comes from hook registries where types might
+ * be unions or `Middleware<any[]>`. The helper ensures type safety by requiring
+ * the middleware to match the Procedure's argument types.
+ *
+ * @example
+ * ```typescript
+ * const proc = createProcedure({ name: 'test' }, async (input: string) => input);
+ * const registryMiddleware = registry.getMiddleware('test'); // Middleware<any[]>[]
+ * const procWithMw = applyRegistryMiddleware(proc, registryMiddleware);
+ * // Types are preserved and validated
+ * ```
+ */
+export declare function applyRegistryMiddleware<THandler extends (...args: any[]) => any>(procedure: Procedure<THandler>, ...middleware: (Middleware<any[]> | MiddlewarePipeline)[]): Procedure<THandler>;
+export declare function wrapProcedure(middleware: Middleware<any[]>[]): {
+    <THandler extends (...args: any[]) => any>(handler: THandler): Procedure<THandler>;
+    <THandler extends (...args: any[]) => any>(config: ProcedureOptions, handler: THandler): Procedure<THandler>;
+};
+export declare function wrapHook(middleware: Middleware<any[]>[]): {
+    <THandler extends (...args: any[]) => any>(handler: THandler): Procedure<THandler>;
+    <THandler extends (...args: any[]) => any>(config: ProcedureOptions, handler: THandler): Procedure<THandler>;
+};
+export {};
+//# sourceMappingURL=procedure.d.ts.map