@agentuity/runtime 0.0.69 → 0.0.70

package/dist/agent.d.ts

@@ -1,31 +1,40 @@
-import { type KeyValueStorage, type ObjectStorage, type StandardSchemaV1, type StreamStorage, type VectorStorage } from '@agentuity/core';
+import { type KeyValueStorage, type StandardSchemaV1, type StreamStorage, type VectorStorage, type InferOutput } from '@agentuity/core';
 import { type Tracer } from '@opentelemetry/api';
 import type { Context, MiddlewareHandler } from 'hono';
 import type { Handler } from 'hono/types';
+import { AGENT_RUNTIME } from './_config';
 import type { Logger } from './logger';
-import type { Eval, EvalFunction, ExternalEvalMetadata } from './eval';
+import type { Eval, EvalFunction } from './eval';
 import type { Thread, Session } from './session';
 import type { AppState } from './index';
 export type AgentEventName = 'started' | 'completed' | 'errored';
 export type AgentEventCallback<TAgent extends Agent<any, any, any>> = ((eventName: 'started', agent: TAgent, context: AgentContext<any, any, any>) => Promise<void> | void) | ((eventName: 'completed', agent: TAgent, context: AgentContext<any, any, any>) => Promise<void> | void) | ((eventName: 'errored', agent: TAgent, context: AgentContext<any, any, any>, data: Error) => Promise<void> | void);
+/**
+ * Runtime state container for agents and event listeners.
+ * Isolates global state into context for better testing.
+ */
+export interface AgentRuntimeState {
+    agents: Map<string, Agent<any, any, any, any, any>>;
+    agentConfigs: Map<string, unknown>;
+    agentEventListeners: WeakMap<Agent<any, any, any, any, any>, Map<AgentEventName, Set<AgentEventCallback<any>>>>;
+}
 /**
  * Context object passed to every agent handler providing access to runtime services and state.
  *
  * @template TAgentRegistry - Registry of all available agents (auto-generated, strongly-typed)
- * @template TCurrent - Current agent runner type
- * @template TParent - Parent agent runner type (if called from another agent)
  * @template TConfig - Agent-specific configuration type from setup function
  * @template TAppState - Application-wide state type from createApp
  *
  * @example
  * ```typescript
- * const agent = createAgent({
+ * const agent = createAgent('my-agent', {
  *   handler: async (ctx, input) => {
  *     // Logging
  *     ctx.logger.info('Processing request', { input });
  *
- *     // Call another agent
- *     const result = await ctx.agent.otherAgent.run({ data: input });
+ *     // Call another agent (import it directly)
+ *     import otherAgent from './other-agent';
+ *     const result = await otherAgent.run({ data: input });
  *
  *     // Store data
  *     await ctx.kv.set('key', { value: result });
@@ -43,7 +52,14 @@ export type AgentEventCallback<TAgent extends Agent<any, any, any>> = ((eventNam
  * });
  * ```
  */
-export interface AgentContext<TAgentRegistry extends AgentRegistry = AgentRegistry, TCurrent extends AgentRunner<any, any, any> | undefined = AgentRunner<any, any, any> | undefined, TParent extends AgentRunner<any, any, any> | undefined = AgentRunner<any, any, any> | undefined, TConfig = unknown, TAppState = Record<string, never>> {
+export interface AgentContext<_TAgentRegistry extends AgentRegistry = AgentRegistry, TConfig = unknown, TAppState = Record<string, never>> {
+    /**
+     * Internal runtime state (agents, configs, event listeners).
+     * Stored with Symbol key to prevent accidental access.
+     * Use getAgentRuntime(ctx) to access.
+     * @internal
+     */
+    [AGENT_RUNTIME]: AgentRuntimeState;
     /**
      * Schedule a background task that continues after the response is sent.
      * Useful for cleanup, logging, or async operations that don't block the response.
@@ -59,30 +75,6 @@ export interface AgentContext<TAgentRegistry extends AgentRegistry = AgentRegist
      * ```
      */
     waitUntil: (promise: Promise<void> | (() => void | Promise<void>)) => void;
-    /**
-     * Registry of all agents in the application. Strongly-typed and auto-generated.
-     * Use to call other agents from within your handler.
-     *
-     * @example
-     * ```typescript
-     * const emailResult = await ctx.agent.email.run({ to: 'user@example.com' });
-     * const smsResult = await ctx.agent.sms.run({ phone: '+1234567890' });
-     * ```
-     */
-    agent: TAgentRegistry;
-    /**
-     * Information about the currently executing agent.
-     */
-    current: TCurrent;
-    /**
-     * Information about the parent agent (if this agent was called by another agent).
-     * Use ctx.agent.parentName for strongly-typed access.
-     */
-    parent: TParent;
-    /**
-     * Name of the current agent being executed.
-     */
-    agentName: AgentName;
     /**
      * Structured logger with OpenTelemetry integration.
      * Logs are automatically correlated with traces.
@@ -127,18 +119,6 @@ export interface AgentContext<TAgentRegistry extends AgentRegistry = AgentRegist
      * ```
      */
     kv: KeyValueStorage;
-    /**
-     * Object storage for files and blobs (S3-compatible).
-     *
-     * @example
-     * ```typescript
-     * await ctx.objectstore.put('images/photo.jpg', buffer);
-     * const file = await ctx.objectstore.get('images/photo.jpg');
-     * await ctx.objectstore.delete('images/photo.jpg');
-     * const objects = await ctx.objectstore.list('images/');
-     * ```
-     */
-    objectstore: ObjectStorage;
     /**
      * Stream storage for real-time data streams and logs.
      *
@@ -218,13 +198,13 @@ export interface AgentContext<TAgentRegistry extends AgentRegistry = AgentRegist
 }
 type InternalAgentMetadata = {
     /**
-     * the unique identifier for this project, agent and deployment.
+     * the unique name for the agent (user-provided).
      */
-    id: string;
+    name: string;
     /**
-     * the unique identifier for this project and agent across multiple deployments.
+     * the unique identifier for this project, agent and deployment.
      */
-    identifier: string;
+    id: string;
     /**
      * the unique identifier for this agent across multiple deployments
      */
@@ -247,10 +227,6 @@ type InternalAgentMetadata = {
     outputSchemaCode?: string;
 };
 type ExternalAgentMetadata = {
-    /**
-     * the human readable name for the agent.
-     */
-    name: string;
     /**
      * the human readable description for the agent
      */
@@ -260,22 +236,19 @@ type AgentMetadata = InternalAgentMetadata & ExternalAgentMetadata;
 /**
  * Configuration object for creating an agent evaluation function.
  *
- * @template TInput - Input schema type from the parent agent
- * @template TOutput - Output schema type from the parent agent
+ * @template TInput - Input schema type from the agent
+ * @template TOutput - Output schema type from the agent
  */
 export interface CreateEvalConfig<TInput extends StandardSchemaV1 | undefined = any, TOutput extends StandardSchemaV1 | undefined = any> {
     /**
-     * Optional metadata for the evaluation function.
+     * Optional description of what this evaluation does.
      *
      * @example
      * ```typescript
-     * metadata: {
-     *   name: 'Validate positive output',
-     *   description: 'Ensures output is greater than zero'
-     * }
+     * description: 'Ensures output is greater than zero'
      * ```
      */
-    metadata?: Partial<ExternalEvalMetadata>;
+    description?: string;
     /**
      * Evaluation handler function that tests the agent's behavior.
      * Return true if the evaluation passes, false if it fails.
@@ -308,9 +281,9 @@ export interface CreateEvalConfig<TInput extends StandardSchemaV1 | undefined =
      * }
      * ```
      */
-    handler: EvalFunction<TInput extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TInput> : undefined, TOutput extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TOutput> : undefined>;
+    handler: EvalFunction<TInput extends StandardSchemaV1 ? InferOutput<TInput> : undefined, TOutput extends StandardSchemaV1 ? InferOutput<TOutput> : undefined>;
 }
-type CreateEvalMethod<TInput extends StandardSchemaV1 | undefined = any, TOutput extends StandardSchemaV1 | undefined = any> = (config: CreateEvalConfig<TInput, TOutput>) => Eval<TInput, TOutput>;
+type CreateEvalMethod<TInput extends StandardSchemaV1 | undefined = any, TOutput extends StandardSchemaV1 | undefined = any> = (name: string, config: CreateEvalConfig<TInput, TOutput>) => Eval<TInput, TOutput>;
 /**
  * Validator function type with method overloads for different validation scenarios.
  * Provides type-safe validation middleware that integrates with Hono's type system.
@@ -359,7 +332,7 @@ export interface AgentValidator<TInput extends StandardSchemaV1 | undefined, _TO
     (): TInput extends StandardSchemaV1 ? Handler<any, any, {
         in: {};
         out: {
-            json: StandardSchemaV1.InferOutput<TInput>;
+            json: InferOutput<TInput>;
         };
     }> : Handler<any, any, any>;
     /**
@@ -387,7 +360,7 @@ export interface AgentValidator<TInput extends StandardSchemaV1 | undefined, _TO
     }): Handler<any, any, {
         in: {};
         out: {
-            json: StandardSchemaV1.InferOutput<TOverrideOutput>;
+            json: InferOutput<TOverrideOutput>;
         };
     }>;
     /**
@@ -426,7 +399,7 @@ export interface AgentValidator<TInput extends StandardSchemaV1 | undefined, _TO
     }): Handler<any, any, {
         in: {};
         out: {
-            json: StandardSchemaV1.InferOutput<TOverrideInput>;
+            json: InferOutput<TOverrideInput>;
         };
     }>;
 }
@@ -457,7 +430,8 @@ export interface AgentValidator<TInput extends StandardSchemaV1 | undefined, _TO
  * });
  *
  * // Create evals for testing
- * const eval1 = agent.createEval({
+ * const eval1 = agent.createEval('check-positive', {
+ *   description: 'Ensures result is greater than 5',
  *   handler: async (run, result) => {
  *     return result > 5; // Assert output is greater than 5
  *   }
@@ -471,9 +445,9 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
     metadata: AgentMetadata;
     /**
      * The main handler function that processes agent requests.
-     * Receives AgentContext and validated input, returns output or stream.
+     * Gets AgentContext from AsyncLocalStorage, receives validated input, returns output or stream.
      */
-    handler: (ctx: AgentContext<any, any, any, TConfig, TAppState>, ...args: any[]) => any | Promise<any>;
+    handler: (...args: any[]) => any | Promise<any>;
     /**
      * Creates a type-safe validation middleware for routes using StandardSchema validation.
      *
@@ -564,8 +538,8 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
      * });
      *
      * // Create eval to validate output
-     * agent.createEval({
-     *   metadata: { name: 'Check positive output' },
+     * agent.createEval('check-positive', {
+     *   description: 'Ensures output is a positive number',
      *   handler: async (run, result) => {
      *     return result > 0; // Assert output is positive
      *   }
@@ -596,7 +570,7 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
      * });
      * ```
      */
-    addEventListener(eventName: 'started', callback: (eventName: 'started', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>) => Promise<void> | void): void;
+    addEventListener(eventName: 'started', callback: (eventName: 'started', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>) => Promise<void> | void): void;
     /**
      * Register an event listener for when the agent completes successfully.
      *
@@ -610,7 +584,7 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
      * });
      * ```
      */
-    addEventListener(eventName: 'completed', callback: (eventName: 'completed', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>) => Promise<void> | void): void;
+    addEventListener(eventName: 'completed', callback: (eventName: 'completed', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>) => Promise<void> | void): void;
     /**
      * Register an event listener for when the agent throws an error.
      *
@@ -624,28 +598,28 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
      * });
      * ```
      */
-    addEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>, data: Error) => Promise<void> | void): void;
+    addEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>, data: Error) => Promise<void> | void): void;
     /**
      * Remove a previously registered 'started' event listener.
      *
      * @param eventName - Must be 'started'
      * @param callback - The callback function to remove
      */
-    removeEventListener(eventName: 'started', callback: (eventName: 'started', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>) => Promise<void> | void): void;
+    removeEventListener(eventName: 'started', callback: (eventName: 'started', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>) => Promise<void> | void): void;
     /**
      * Remove a previously registered 'completed' event listener.
      *
      * @param eventName - Must be 'completed'
      * @param callback - The callback function to remove
      */
-    removeEventListener(eventName: 'completed', callback: (eventName: 'completed', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>) => Promise<void> | void): void;
+    removeEventListener(eventName: 'completed', callback: (eventName: 'completed', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>) => Promise<void> | void): void;
     /**
      * Remove a previously registered 'errored' event listener.
      *
      * @param eventName - Must be 'errored'
      * @param callback - The callback function to remove
      */
-    removeEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, any, any, TConfig, TAppState>, data: Error) => Promise<void> | void): void;
+    removeEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, TConfig, TAppState>, context: AgentContext<any, TConfig, TAppState>, data: Error) => Promise<void> | void): void;
 } & (TInput extends StandardSchemaV1 ? {
     inputSchema: TInput;
 } : {
@@ -659,8 +633,8 @@ export type Agent<TInput extends StandardSchemaV1 | undefined = any, TOutput ext
 } : {
     stream?: false;
 });
-type InferSchemaInput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> : never;
-type InferStreamOutput<TOutput, TStream extends boolean> = TStream extends true ? TOutput extends StandardSchemaV1 ? ReadableStream<StandardSchemaV1.InferOutput<TOutput>> : ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<TOutput> : void;
+type InferSchemaInput<T> = T extends StandardSchemaV1 ? InferOutput<T> : never;
+type InferStreamOutput<TOutput, TStream extends boolean> = TStream extends true ? TOutput extends StandardSchemaV1 ? ReadableStream<InferOutput<TOutput>> : ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? InferOutput<TOutput> : void;
 type SchemaInput<TSchema> = TSchema extends {
     input: infer I;
 } ? I : undefined;
@@ -670,13 +644,29 @@ type SchemaOutput<TSchema> = TSchema extends {
 type SchemaStream<TSchema> = TSchema extends {
     stream: infer S;
 } ? S extends boolean ? S : false : false;
-type SchemaHandlerReturn<TSchema> = SchemaStream<TSchema> extends true ? SchemaOutput<TSchema> extends StandardSchemaV1 ? ReadableStream<StandardSchemaV1.InferOutput<SchemaOutput<TSchema>>> : ReadableStream<unknown> : SchemaOutput<TSchema> extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<SchemaOutput<TSchema>> : void;
-type AgentHandlerFromConfig<TSchema, TSetupReturn, TAppState = AppState> = SchemaInput<TSchema> extends infer I ? I extends StandardSchemaV1 ? (ctx: AgentContext<any, any, any, TSetupReturn, TAppState>, input: StandardSchemaV1.InferOutput<I>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema> : (ctx: AgentContext<any, any, any, TSetupReturn, TAppState>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema> : (ctx: AgentContext<any, any, any, TSetupReturn, TAppState>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema>;
+type SchemaHandlerReturn<TSchema> = SchemaStream<TSchema> extends true ? SchemaOutput<TSchema> extends StandardSchemaV1 ? ReadableStream<InferOutput<SchemaOutput<TSchema>>> : ReadableStream<unknown> : SchemaOutput<TSchema> extends StandardSchemaV1 ? InferOutput<SchemaOutput<TSchema>> : void;
+type AgentHandlerFromConfig<TSchema, TSetupReturn, TAppState = AppState> = SchemaInput<TSchema> extends infer I ? I extends StandardSchemaV1 ? (ctx: AgentContext<any, TSetupReturn, TAppState>, input: InferOutput<I>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema> : (ctx: AgentContext<any, TSetupReturn, TAppState>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema> : (ctx: AgentContext<any, TSetupReturn, TAppState>) => Promise<SchemaHandlerReturn<TSchema>> | SchemaHandlerReturn<TSchema>;
 /**
  * Configuration object for creating an agent with automatic type inference.
  *
+ * Passed as the second parameter to createAgent(name, config).
+ *
  * @template TSchema - Schema definition object containing optional input, output, and stream properties
  * @template TConfig - Function type that returns agent-specific configuration from setup
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent('greeting', {
+ *   description: 'Generates personalized greetings',
+ *   schema: {
+ *     input: z.object({ name: z.string(), age: z.number() }),
+ *     output: z.string()
+ *   },
+ *   handler: async (ctx, { name, age }) => {
+ *     return `Hello, ${name}! You are ${age} years old.`;
+ *   }
+ * });
+ * ```
  */
 export interface CreateAgentConfig<TSchema extends {
     input?: StandardSchemaV1;
@@ -697,17 +687,21 @@ export interface CreateAgentConfig<TSchema extends {
      */
     schema?: TSchema;
     /**
-     * Agent metadata visible in the Agentuity platform.
+     * Optional description of what this agent does, visible in the Agentuity platform.
      *
      * @example
      * ```typescript
-     * metadata: {
-     *   name: 'Greeting Agent',
-     *   description: 'Returns personalized greetings'
-     * }
+     * description: 'Returns personalized greetings'
      * ```
      */
-    metadata: ExternalAgentMetadata;
+    description?: string;
+    /**
+     * Optional metadata object (typically injected by build plugin during compilation).
+     * Contains agent identification and versioning information.
+     *
+     * @internal - Usually populated by build tooling, not manually set
+     */
+    metadata?: Partial<AgentMetadata>;
     /**
      * Optional async function called once on app startup to initialize agent-specific resources.
      * The returned value is available in the handler via `ctx.config`.
@@ -760,10 +754,150 @@ export interface CreateAgentConfig<TSchema extends {
      */
     shutdown?: (app: AppState, config: TConfig extends (app: AppState) => infer R ? Awaited<R> : undefined) => Promise<void> | void;
 }
+/**
+ * The public interface returned by createAgent().
+ * Provides methods to run the agent, create evaluations, and manage event listeners.
+ *
+ * @template TInput - Input schema type (StandardSchemaV1 or undefined if no input)
+ * @template TOutput - Output schema type (StandardSchemaV1 or undefined if no output)
+ * @template TStream - Whether the agent returns a stream (true/false)
+ *
+ * @example
+ * ```typescript
+ * const agent = createAgent('greeting', {
+ *   schema: {
+ *     input: z.object({ name: z.string() }),
+ *     output: z.string()
+ *   },
+ *   handler: async (ctx, { name }) => `Hello, ${name}!`
+ * });
+ *
+ * // Run the agent
+ * const result = await agent.run({ name: 'Alice' });
+ *
+ * // Create evaluation
+ * const evalDef = agent.createEval('greeting-accuracy', {
+ *   description: 'Checks if greeting includes the user name',
+ *   handler: async (ctx, input, output) => {
+ *     return { score: output.includes(input.name) ? 1 : 0 };
+ *   }
+ * });
+ *
+ * // Listen to events
+ * agent.addEventListener('completed', async (eventName, agent, context) => {
+ *   console.log('Agent completed successfully');
+ * });
+ * ```
+ */
 export interface AgentRunner<TInput extends StandardSchemaV1 | undefined = any, TOutput extends StandardSchemaV1 | undefined = any, TStream extends boolean = false> {
+    /** Agent metadata (id, name, description, etc.) */
     metadata: AgentMetadata;
+    /**
+     * Execute the agent with validated input.
+     * If agent has no input schema, call with no arguments.
+     * If agent has input schema, pass validated input object.
+     *
+     * @example
+     * ```typescript
+     * // Agent with input
+     * const result = await agent.run({ name: 'Alice' });
+     *
+     * // Agent without input
+     * const result = await agent.run();
+     * ```
+     */
     run: undefined extends TInput ? () => Promise<InferStreamOutput<Exclude<TOutput, undefined>, TStream>> : (input: InferSchemaInput<Exclude<TInput, undefined>>) => Promise<InferStreamOutput<Exclude<TOutput, undefined>, TStream>>;
+    /**
+     * Create Hono validator middleware for this agent.
+     * Automatically validates request input against the agent's schema.
+     *
+     * @example
+     * ```typescript
+     * import myAgent from './my-agent';
+     * router.post('/', myAgent.validator(), async (c) => {
+     *   const data = c.req.valid('json'); // Fully typed!
+     *   return c.json(await myAgent.run(data));
+     * });
+     * ```
+     */
+    validator: AgentValidator<TInput, TOutput>;
+    /** Input schema (if defined) */
+    inputSchema?: TInput;
+    /** Output schema (if defined) */
+    outputSchema?: TOutput;
+    /** Whether agent returns a stream */
+    stream?: TStream;
+    /**
+     * Create an evaluation for this agent.
+     * Evaluations run automatically after the agent completes.
+     *
+     * @example
+     * ```typescript
+     * const accuracyEval = agent.createEval('accuracy', {
+     *   description: 'Validates output length is non-zero',
+     *   handler: async (ctx, input, output) => ({
+     *     score: output.length > 0 ? 1 : 0,
+     *     metadata: { outputLength: output.length }
+     *   })
+     * });
+     * ```
+     */
+    createEval: CreateEvalMethod<TInput, TOutput>;
+    /**
+     * Add event listener for 'started' or 'completed' events.
+     * Listeners fire sequentially in the order they were added.
+     *
+     * @param eventName - 'started' or 'completed'
+     * @param callback - Function to call when event fires
+     *
+     * @example
+     * ```typescript
+     * agent.addEventListener('started', async (eventName, agent, context) => {
+     *   context.logger.info('Agent execution started');
+     * });
+     * ```
+     */
+    addEventListener(eventName: 'started' | 'completed', callback: (eventName: 'started' | 'completed', agent: Agent<TInput, TOutput, TStream, any, any>, context: AgentContext<any, any, any>) => Promise<void> | void): void;
+    /**
+     * Add event listener for 'errored' event.
+     * Fires when agent handler throws an error.
+     *
+     * @param eventName - 'errored'
+     * @param callback - Function to call when error occurs
+     *
+     * @example
+     * ```typescript
+     * agent.addEventListener('errored', async (eventName, agent, context, error) => {
+     *   context.logger.error('Agent failed', { error: error.message });
+     * });
+     * ```
+     */
+    addEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, any, any>, context: AgentContext<any, any, any>, error: Error) => Promise<void> | void): void;
+    /**
+     * Remove event listener for 'started' or 'completed' events.
+     *
+     * @param eventName - 'started' or 'completed'
+     * @param callback - The same callback function that was added
+     */
+    removeEventListener(eventName: 'started' | 'completed', callback: (eventName: 'started' | 'completed', agent: Agent<TInput, TOutput, TStream, any, any>, context: AgentContext<any, any, any>) => Promise<void> | void): void;
+    /**
+     * Remove event listener for 'errored' event.
+     *
+     * @param eventName - 'errored'
+     * @param callback - The same callback function that was added
+     */
+    removeEventListener(eventName: 'errored', callback: (eventName: 'errored', agent: Agent<TInput, TOutput, TStream, any, any>, context: AgentContext<any, any, any>, error: Error) => Promise<void> | void): void;
 }
+/**
+ * Get the global runtime state (for production use).
+ * In tests, use TestAgentContext which has isolated runtime state.
+ */
+export declare function getGlobalRuntimeState(): AgentRuntimeState;
+/**
+ * Get the runtime state from an AgentContext.
+ * @internal
+ */
+export declare function getAgentRuntime(ctx: AgentContext<any, any, any>): AgentRuntimeState;
 /**
  * Union type of all registered agent names.
  * Falls back to `string` when no agents are registered (before augmentation).
@@ -810,17 +944,21 @@ export interface CreateAgentConfigExplicit<TInput extends StandardSchemaV1 | und
         stream?: TStream;
     };
     /**
-     * Agent metadata.
+     * Optional description of what this agent does.
      *
      * @example
      * ```typescript
-     * metadata: {
-     *   name: 'My Agent',
-     *   description: 'Does something useful'
-     * }
+     * description: 'Does something useful'
      * ```
      */
-    metadata: ExternalAgentMetadata;
+    description?: string;
+    /**
+     * Optional metadata object (typically injected by build plugin during compilation).
+     * Contains agent identification and versioning information.
+     *
+     * @internal - Usually populated by build tooling, not manually set
+     */
+    metadata?: Partial<AgentMetadata>;
     /**
      * Optional setup function receiving app state, returns agent config.
      * The returned value is available in the handler via `ctx.config`.
@@ -863,7 +1001,7 @@ export interface CreateAgentConfigExplicit<TInput extends StandardSchemaV1 | und
      * }
      * ```
      */
-    handler: TInput extends StandardSchemaV1 ? TStream extends true ? TOutput extends StandardSchemaV1 ? (c: AgentContext<any, any, any, TConfig, TAppState>, input: StandardSchemaV1.InferOutput<TInput>) => Promise<ReadableStream<StandardSchemaV1.InferOutput<TOutput>>> | ReadableStream<StandardSchemaV1.InferOutput<TOutput>> : (c: AgentContext<any, any, any, TConfig, TAppState>, input: StandardSchemaV1.InferOutput<TInput>) => Promise<ReadableStream<unknown>> | ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? (c: AgentContext<any, any, any, TConfig, TAppState>, input: StandardSchemaV1.InferOutput<TInput>) => Promise<StandardSchemaV1.InferOutput<TOutput>> | StandardSchemaV1.InferOutput<TOutput> : (c: AgentContext<any, any, any, TConfig, TAppState>, input: StandardSchemaV1.InferOutput<TInput>) => Promise<void> | void : TStream extends true ? TOutput extends StandardSchemaV1 ? (c: AgentContext<any, any, any, TConfig, TAppState>) => Promise<ReadableStream<StandardSchemaV1.InferOutput<TOutput>>> | ReadableStream<StandardSchemaV1.InferOutput<TOutput>> : (c: AgentContext<any, any, any, TConfig, TAppState>) => Promise<ReadableStream<unknown>> | ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? (c: AgentContext<any, any, any, TConfig, TAppState>) => Promise<StandardSchemaV1.InferOutput<TOutput>> | StandardSchemaV1.InferOutput<TOutput> : (c: AgentContext<any, any, any, TConfig, TAppState>) => Promise<void> | void;
+    handler: TInput extends StandardSchemaV1 ? TStream extends true ? TOutput extends StandardSchemaV1 ? (c: AgentContext<any, TConfig, TAppState>, input: InferOutput<TInput>) => Promise<ReadableStream<InferOutput<TOutput>>> | ReadableStream<InferOutput<TOutput>> : (c: AgentContext<any, TConfig, TAppState>, input: InferOutput<TInput>) => Promise<ReadableStream<unknown>> | ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? (c: AgentContext<any, TConfig, TAppState>, input: InferOutput<TInput>) => Promise<InferOutput<TOutput>> | InferOutput<TOutput> : (c: AgentContext<any, TConfig, TAppState>, input: InferOutput<TInput>) => Promise<void> | void : TStream extends true ? TOutput extends StandardSchemaV1 ? (c: AgentContext<any, TConfig, TAppState>) => Promise<ReadableStream<InferOutput<TOutput>>> | ReadableStream<InferOutput<TOutput>> : (c: AgentContext<any, TConfig, TAppState>) => Promise<ReadableStream<unknown>> | ReadableStream<unknown> : TOutput extends StandardSchemaV1 ? (c: AgentContext<any, TConfig, TAppState>) => Promise<InferOutput<TOutput>> | InferOutput<TOutput> : (c: AgentContext<any, TConfig, TAppState>) => Promise<void> | void;
 }
 /**
  * Creates an agent with schema validation and lifecycle hooks.
@@ -873,17 +1011,15 @@ export interface CreateAgentConfigExplicit<TInput extends StandardSchemaV1 | und
  * @template TSchema - Schema definition object containing optional input, output, and stream properties
  * @template TConfig - Function type that returns agent-specific configuration from setup
  *
+ * @param name - Unique agent name (must be unique within the project)
  * @param config - Agent configuration object
  *
- * @returns Agent instance that can be registered with the runtime
+ * @returns AgentRunner with a run method for executing the agent
  *
  * @example
  * ```typescript
- * const agent = createAgent({
- *   metadata: {
- *     name: 'Greeting Agent',
- *     description: 'Returns personalized greetings'
- *   },
+ * const agent = createAgent('greeting-agent', {
+ *   description: 'Returns personalized greetings',
  *   schema: {
  *     input: z.object({ name: z.string(), age: z.number() }),
  *     output: z.string()
@@ -893,13 +1029,16 @@ export interface CreateAgentConfigExplicit<TInput extends StandardSchemaV1 | und
  *     return `Hello, ${name}! You are ${age} years old.`;
  *   }
  * });
+ *
+ * // Call the agent directly
+ * const result = await agent.run({ name: 'Alice', age: 30 });
  * ```
  */
 export declare function createAgent<TSchema extends {
     input?: StandardSchemaV1;
     output?: StandardSchemaV1;
     stream?: boolean;
-} | undefined = undefined, TConfig extends (app: AppState) => any = any>(config: CreateAgentConfig<TSchema, TConfig>): Agent<SchemaInput<TSchema>, SchemaOutput<TSchema>, SchemaStream<TSchema>, TConfig extends (app: AppState) => infer R ? Awaited<R> : undefined, AppState>;
+} | undefined = undefined, TConfig extends (app: AppState) => any = any>(name: string, config: CreateAgentConfig<TSchema, TConfig>): AgentRunner<SchemaInput<TSchema>, SchemaOutput<TSchema>, SchemaStream<TSchema>>;
 /**
  * Creates an agent with explicit generic type parameters.
  *
@@ -911,9 +1050,10 @@ export declare function createAgent<TSchema extends {
  * @template TConfig - Type returned by setup function
  * @template TAppState - Custom app state type from createApp
  *
+ * @param name - Unique agent name (must be unique within the project)
  * @param config - Agent configuration object
  *
- * @returns Agent instance with explicit types
+ * @returns AgentRunner with explicit types and a run method
  *
  * @example
  * ```typescript
@@ -923,11 +1063,8 @@ export declare function createAgent<TSchema extends {
  * const agent = createAgent<
  *   z.ZodObject<any>, // TInput
  *   z.ZodString,      // TOutput
- *   false,            // TStream
- *   MyConfig,         // TConfig
- *   MyAppState        // TAppState
- * >({
- *   metadata: { name: 'Custom Agent' },
+ *   false            // TStream
+ * >('custom-agent', {
  *   setup: async (app) => ({ cache: new Map() }),
  *   handler: async (ctx, input) => {
  *     const db = ctx.app.db;
@@ -937,7 +1074,7 @@ export declare function createAgent<TSchema extends {
  * });
  * ```
  */
-export declare function createAgent<TInput extends StandardSchemaV1 | undefined = undefined, TOutput extends StandardSchemaV1 | undefined = undefined, TStream extends boolean = false, TConfig = unknown, TAppState = AppState>(config: CreateAgentConfigExplicit<TInput, TOutput, TStream, TConfig, TAppState>): Agent<TInput, TOutput, TStream, TConfig, TAppState>;
+export declare function createAgent<TInput extends StandardSchemaV1 | undefined = undefined, TOutput extends StandardSchemaV1 | undefined = undefined, TStream extends boolean = false, TConfig = unknown, TAppState = AppState>(name: string, config: CreateAgentConfigExplicit<TInput, TOutput, TStream, TConfig, TAppState>): AgentRunner<TInput, TOutput, TStream>;
 /**
  * Populate the agents object with all registered agents
  * Keys are converted to camelCase to match the generated TypeScript types
@@ -947,5 +1084,50 @@ export declare const createAgentMiddleware: (agentName: AgentName | "") => Middl
 export declare const getAgents: () => Map<string, Agent<any, any, any, any, any>>;
 export declare const runAgentSetups: (appState: AppState) => Promise<void>;
 export declare const runAgentShutdowns: (appState: AppState) => Promise<void>;
+/**
+ * Run an agent within a specific AgentContext.
+ * Sets up AsyncLocalStorage with the provided context and executes the agent.
+ *
+ * This is the recommended way to test agents in unit tests. It automatically:
+ * - Registers the agent in the runtime state so event listeners fire
+ * - Sets up AsyncLocalStorage so getAgentContext() works inside the agent
+ * - Handles both agents with input and agents without input
+ *
+ * **Use cases:**
+ * - Unit testing agents with TestAgentContext
+ * - Running agents outside HTTP request flow
+ * - Custom agent execution environments
+ * - Testing event listeners and evaluations
+ *
+ * @template TInput - Type of the input parameter
+ * @template TOutput - Type of the return value
+ *
+ * @param ctx - The AgentContext to use (typically TestAgentContext in tests)
+ * @param agent - The AgentRunner to execute (returned from createAgent)
+ * @param input - Input data (required if agent has input schema, omit otherwise)
+ *
+ * @returns Promise resolving to the agent's output
+ *
+ * @example
+ * ```typescript
+ * import { runInAgentContext, TestAgentContext } from '@agentuity/runtime/test';
+ *
+ * test('greeting agent', async () => {
+ *   const ctx = new TestAgentContext();
+ *   const result = await runInAgentContext(ctx, greetingAgent, {
+ *     name: 'Alice',
+ *     age: 30
+ *   });
+ *   expect(result).toBe('Hello, Alice! You are 30 years old.');
+ * });
+ *
+ * test('no-input agent', async () => {
+ *   const ctx = new TestAgentContext();
+ *   const result = await runInAgentContext(ctx, statusAgent);
+ *   expect(result).toEqual({ status: 'ok' });
+ * });
+ * ```
+ */
+export declare function runInAgentContext<TInput, TOutput>(ctx: AgentContext<any, any, any>, agent: AgentRunner<any, any, any>, input?: TInput): Promise<TOutput>;
 export {};
 //# sourceMappingURL=agent.d.ts.map