@agentuity/runtime 0.0.68 → 0.0.70

package/dist/agent.d.ts

@@ -1,30 +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 });
@@ -42,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.
@@ -58,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.
@@ -126,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.
      *
@@ -217,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
      */
@@ -246,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
      */
@@ -259,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.
@@ -307,9 +281,128 @@ 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> = (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.
+ *
+ * This validator automatically validates incoming JSON request bodies using StandardSchema-compatible
+ * schemas (Zod, Valibot, ArkType, etc.) and provides full TypeScript type inference for validated data
+ * accessible via `c.req.valid('json')`.
+ *
+ * The validator returns 400 Bad Request with validation error details if validation fails.
+ *
+ * @template TInput - Agent's input schema type (StandardSchemaV1 or undefined)
+ * @template _TOutput - Agent's output schema type (reserved for future output validation)
+ *
+ * @example Basic usage with agent's schema
+ * ```typescript
+ * router.post('/', agent.validator(), async (c) => {
+ *   const data = c.req.valid('json'); // Fully typed from agent's input schema
+ *   return c.json(data);
+ * });
+ * ```
+ *
+ * @example Override with custom input schema
+ * ```typescript
+ * router.post('/custom', agent.validator({ input: z.object({ id: z.string() }) }), async (c) => {
+ *   const data = c.req.valid('json'); // Typed as { id: string }
+ *   return c.json(data);
+ * });
+ * ```
+ */
+export interface AgentValidator<TInput extends StandardSchemaV1 | undefined, _TOutput extends StandardSchemaV1 | undefined> {
+    /**
+     * Validates using the agent's input schema (no override).
+     * Returns Hono middleware handler that validates JSON request body.
+     *
+     * @returns Middleware handler with type inference for validated data
+     *
+     * @example
+     * ```typescript
+     * // Agent has schema: { input: z.object({ name: z.string() }) }
+     * router.post('/', agent.validator(), async (c) => {
+     *   const data = c.req.valid('json'); // { name: string }
+     *   return c.json({ received: data.name });
+     * });
+     * ```
+     */
+    (): TInput extends StandardSchemaV1 ? Handler<any, any, {
+        in: {};
+        out: {
+            json: InferOutput<TInput>;
+        };
+    }> : Handler<any, any, any>;
+    /**
+     * Output-only validation override.
+     * Validates only the response body (no input validation).
+     *
+     * Useful for GET routes or routes where input validation is handled elsewhere.
+     * The middleware validates the JSON response body and throws 500 Internal Server Error
+     * if validation fails.
+     *
+     * @template TOverrideOutput - Custom output schema type
+     * @param override - Object containing output schema
+     * @returns Middleware handler that validates response output
+     *
+     * @example GET route with output validation
+     * ```typescript
+     * router.get('/', agent.validator({ output: z.array(z.object({ id: z.string() })) }), async (c) => {
+     *   // Returns array of objects - validated against schema
+     *   return c.json([{ id: '123' }, { id: '456' }]);
+     * });
+     * ```
+     */
+    <TOverrideOutput extends StandardSchemaV1>(override: {
+        output: TOverrideOutput;
+    }): Handler<any, any, {
+        in: {};
+        out: {
+            json: InferOutput<TOverrideOutput>;
+        };
+    }>;
+    /**
+     * Validates with custom input and optional output schemas (POST/PUT/PATCH/DELETE).
+     * Overrides the agent's schema for this specific route.
+     *
+     * @template TOverrideInput - Custom input schema type
+     * @template TOverrideOutput - Optional custom output schema type
+     * @param override - Object containing input (required) and output (optional) schemas
+     * @returns Middleware handler with type inference from custom schemas
+     *
+     * @example Custom input schema
+     * ```typescript
+     * router.post('/users', agent.validator({
+     *   input: z.object({ email: z.string().email(), name: z.string() })
+     * }), async (c) => {
+     *   const data = c.req.valid('json'); // { email: string, name: string }
+     *   return c.json({ id: '123', ...data });
+     * });
+     * ```
+     *
+     * @example Custom input and output schemas
+     * ```typescript
+     * router.post('/convert', agent.validator({
+     *   input: z.string(),
+     *   output: z.number()
+     * }), async (c) => {
+     *   const data = c.req.valid('json'); // string
+     *   return c.json(123);
+     * });
+     * ```
+     */
+    <TOverrideInput extends StandardSchemaV1, TOverrideOutput extends StandardSchemaV1 | undefined = undefined>(override: {
+        input: TOverrideInput;
+        output?: TOverrideOutput;
+    }): Handler<any, any, {
+        in: {};
+        out: {
+            json: InferOutput<TOverrideInput>;
+        };
+    }>;
 }
-type CreateEvalMethod<TInput extends StandardSchemaV1 | undefined = any, TOutput extends StandardSchemaV1 | undefined = any> = (config: CreateEvalConfig<TInput, TOutput>) => Eval<TInput, TOutput>;
 /**
  * Agent instance type returned by createAgent().
  * Represents a fully configured agent with metadata, handler, lifecycle hooks, and event listeners.
@@ -337,7 +430,8 @@ type CreateEvalMethod<TInput extends StandardSchemaV1 | undefined = any, TOutput
  * });
  *
  * // 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
  *   }
@@ -351,9 +445,78 @@ 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.
+     *
+     * This method validates incoming JSON request bodies against the agent's **input schema**
+     * and optionally validates outgoing JSON responses against the **output schema**.
+     * Provides full TypeScript type inference for validated input data accessible via `c.req.valid('json')`.
+     *
+     * **Validation behavior:**
+     * - **Input**: Validates request JSON body, returns 400 Bad Request on failure
+     * - **Output**: Validates response JSON body (if output schema provided), throws 500 on failure
+     * - Passes validated input data to handler via `c.req.valid('json')`
+     * - Full TypeScript type inference for validated input data
+     *
+     * **Supported schema libraries:**
+     * - Zod (z.object, z.string, etc.)
+     * - Valibot (v.object, v.string, etc.)
+     * - ArkType (type({ ... }))
+     * - Any StandardSchema-compatible library
+     *
+     * **Method overloads:**
+     * - `agent.validator()` - Validates using agent's input/output schemas
+     * - `agent.validator({ output: schema })` - Output-only validation (no input validation)
+     * - `agent.validator({ input: schema })` - Custom input schema override
+     * - `agent.validator({ input: schema, output: schema })` - Both input and output validated
+     *
+     * @returns Hono middleware handler with proper type inference
+     *
+     * @example Automatic validation using agent's schema
+     * ```typescript
+     * // Agent defined with: schema: { input: z.object({ name: z.string(), age: z.number() }) }
+     * router.post('/', agent.validator(), async (c) => {
+     *   const data = c.req.valid('json'); // Fully typed: { name: string, age: number }
+     *   return c.json({ greeting: `Hello ${data.name}, age ${data.age}` });
+     * });
+     * ```
+     *
+     * @example Override with custom schema per-route
+     * ```typescript
+     * router.post('/email', agent.validator({
+     *   input: z.object({ email: z.string().email() })
+     * }), async (c) => {
+     *   const data = c.req.valid('json'); // Typed as { email: string }
+     *   return c.json({ sent: data.email });
+     * });
+     * ```
+     *
+     * @example Works with any StandardSchema library
+     * ```typescript
+     * import * as v from 'valibot';
+     *
+     * router.post('/valibot', agent.validator({
+     *   input: v.object({ count: v.number() })
+     * }), async (c) => {
+     *   const data = c.req.valid('json'); // Typed correctly
+     *   return c.json({ count: data.count });
+     * });
+     * ```
+     *
+     * @example Validation error response (400)
+     * ```typescript
+     * // Request: { "name": "Bob" } (missing 'age')
+     * // Response: {
+     * //   "error": "Validation failed",
+     * //   "message": "age: Invalid input: expected number, received undefined",
+     * //   "issues": [{ "message": "...", "path": ["age"] }]
+     * // }
+     * ```
+     */
+    validator: AgentValidator<TInput, TOutput>;
     /**
      * Array of evaluation functions created via agent.createEval().
      * Used for testing and validating agent behavior.
@@ -375,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
      *   }
@@ -407,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.
      *
@@ -421,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.
      *
@@ -435,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;
 } : {
@@ -470,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;
@@ -481,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;
@@ -508,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`.
@@ -571,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).
@@ -621,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`.
@@ -674,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.
@@ -684,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()
@@ -704,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.
  *
@@ -722,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
@@ -734,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;
@@ -748,14 +1074,60 @@ 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
  */
 export declare const populateAgentsRegistry: (ctx: Context) => any;
 export declare const createAgentMiddleware: (agentName: AgentName | "") => MiddlewareHandler;
 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