@vibe-agent-toolkit/agent-runtime 0.1.2-rc.3

package/dist/agent-helpers.js

@@ -0,0 +1,291 @@
+/**
+ * Helper functions for creating agents.
+ */
+/**
+ * Default LLM error for unknown failures.
+ * @internal
+ */
+const LLM_UNAVAILABLE_ERROR = 'llm-unavailable';
+/**
+ * Validate agent input against a Zod schema.
+ *
+ * Returns parsed data on success, or OneShotAgentOutput error envelope on failure.
+ *
+ * @example
+ * // For LLM agents
+ * const validatedOrError = validateAgentInput<MyInput, MyOutput, LLMError>(input, InputSchema, 'llm-invalid-output');
+ * if ('result' in validatedOrError) {
+ *   return validatedOrError; // Validation error
+ * }
+ * const { characteristics, mockable } = validatedOrError;
+ *
+ * @example
+ * // For external event agents
+ * const validatedOrError = validateAgentInput<MyInput, MyOutput, ExternalEventError>(
+ *   input,
+ *   InputSchema,
+ *   'event-invalid-response'
+ * );
+ */
+// eslint-disable-next-line sonarjs/function-return-type -- Intentional discriminated union pattern
+export function validateAgentInput(input, schema, invalidInputError = 'llm-invalid-output') {
+    const parsed = schema.safeParse(input);
+    if (!parsed.success) {
+        return {
+            result: { status: 'error', error: invalidInputError },
+        };
+    }
+    return parsed.data;
+}
+/**
+ * Wrap LLM calls to catch expected failures and map to result errors.
+ *
+ * Handles common LLM failure modes:
+ * - API timeouts → 'llm-timeout'
+ * - Rate limits → 'llm-rate-limit'
+ * - Content policy → 'llm-refusal'
+ * - Invalid output → 'llm-invalid-output'
+ * - Service errors → 'llm-unavailable'
+ *
+ * @example
+ * const llmResult = await executeLLMCall(
+ *   () => llm.chat.completions.create({...}),
+ *   {
+ *     parseOutput: (raw) => CatCharacteristicsSchema.parse(raw),
+ *     timeoutMs: 30000,
+ *   }
+ * );
+ */
+export async function executeLLMCall(fn, options) {
+    try {
+        const result = await fn();
+        // Optionally parse/validate output
+        if (options?.parseOutput) {
+            try {
+                const parsed = options.parseOutput(result);
+                return { status: 'success', data: parsed };
+            }
+            catch (error_) {
+                // Convert parse errors to llm-invalid-output
+                // Log the error for debugging but don't expose details in result
+                if (error_ instanceof Error) {
+                    console.warn('LLM output parse error:', error_.message);
+                }
+                return {
+                    status: 'error',
+                    error: 'llm-invalid-output',
+                };
+            }
+        }
+        return { status: 'success', data: result };
+    }
+    catch (err) {
+        // Map known LLM exceptions to error codes
+        const error = mapLLMException(err);
+        return { status: 'error', error };
+    }
+}
+/**
+ * Execute an LLM analyzer agent with mock/real mode support.
+ *
+ * Eliminates boilerplate for LLM analyzer agents by handling:
+ * - Mock vs real mode switching
+ * - Metadata generation
+ * - Error handling with llm-unavailable fallback
+ * - Consistent return envelope structure
+ *
+ * @example
+ * // With real implementation
+ * execute: async (input) => {
+ *   return executeLLMAnalyzer({
+ *     mockable: input.mockable ?? true,
+ *     mockFn: () => mockParseDescription(input.description),
+ *     realFn: async () => callLLM(...),
+ *     parseOutput: (raw) => CatCharacteristicsSchema.parse(JSON.parse(raw)),
+ *     errorContext: 'Description parsing',
+ *   });
+ * }
+ *
+ * @example
+ * // Mock-only (no real implementation)
+ * execute: async (input) => {
+ *   return executeLLMAnalyzer({
+ *     mockable: input.mockable ?? true,
+ *     mockFn: () => mockGenerateName(input.characteristics),
+ *     notImplementedMessage: 'Real LLM name generation requires runtime adapter',
+ *   });
+ * }
+ */
+export async function executeLLMAnalyzer(config) {
+    try {
+        // Mock mode: return mock data immediately
+        if (config.mockable) {
+            const data = config.mockFn();
+            return {
+                result: { status: 'success', data },
+                metadata: {
+                    mode: 'mock',
+                    executedAt: new Date().toISOString(),
+                },
+            };
+        }
+        // Real mode: check if implemented
+        if (!config.realFn) {
+            // Not implemented: return error with custom message
+            return {
+                result: {
+                    status: 'error',
+                    error: LLM_UNAVAILABLE_ERROR,
+                },
+                metadata: {
+                    mode: 'real',
+                    message: config.notImplementedMessage ?? 'Real LLM implementation not available',
+                    executedAt: new Date().toISOString(),
+                },
+            };
+        }
+        // Real mode: use LLM
+        const result = await executeLLMCall(config.realFn, config.parseOutput ? { parseOutput: config.parseOutput } : undefined);
+        return {
+            result,
+            metadata: {
+                mode: 'real',
+                executedAt: new Date().toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        // Unexpected errors
+        if (err instanceof Error && config.errorContext) {
+            console.warn(`${config.errorContext} error:`, err.message);
+        }
+        return {
+            result: { status: 'error', error: LLM_UNAVAILABLE_ERROR },
+        };
+    }
+}
+/**
+ * Execute an external event integrator agent (HITL, webhook, etc).
+ *
+ * Handles common external event failure modes:
+ * - Timeouts waiting for response
+ * - System unavailable
+ * - Explicit rejection
+ * - Invalid responses
+ *
+ * @example
+ * // With auto-response (testing)
+ * execute: async (input) => {
+ *   return executeExternalEvent({
+ *     autoResponse: input.autoResponse,
+ *     handler: async () => requestApproval(input.prompt, input.context),
+ *     timeoutMs: 60000,
+ *   });
+ * }
+ *
+ * @example
+ * // Production mode (waits for real human/external system)
+ * execute: async (input) => {
+ *   return executeExternalEvent({
+ *     handler: async () => requestApproval(input.prompt, input.context),
+ *     timeoutMs: input.timeoutMs ?? 60000,
+ *   });
+ * }
+ */
+export async function executeExternalEvent(config) {
+    try {
+        // Auto-response mode (testing)
+        if (config.autoResponse !== undefined) {
+            return {
+                result: { status: 'success', data: config.autoResponse },
+                metadata: {
+                    mode: 'auto',
+                    executedAt: new Date().toISOString(),
+                },
+            };
+        }
+        // Real mode: execute handler
+        const data = await config.handler();
+        return {
+            result: { status: 'success', data },
+            metadata: {
+                mode: 'real',
+                executedAt: new Date().toISOString(),
+                ...(config.timeoutMs !== undefined && { timeoutMs: config.timeoutMs }),
+            },
+        };
+    }
+    catch (err) {
+        // Map exceptions to external event errors
+        const error = mapExternalEventException(err, config.errorContext);
+        return {
+            result: { status: 'error', error },
+            metadata: {
+                mode: 'real',
+                executedAt: new Date().toISOString(),
+                ...(err instanceof Error && { errorMessage: err.message }),
+            },
+        };
+    }
+}
+/**
+ * Map common external event exceptions to standard error codes.
+ *
+ * @internal
+ */
+function mapExternalEventException(err, context) {
+    if (err instanceof Error) {
+        const message = err.message.toLowerCase();
+        // Timeouts
+        if (message.includes('timeout') || message.includes('timed out') || message.includes('etimedout')) {
+            return 'event-timeout';
+        }
+        // Rejected
+        if (message.includes('reject') || message.includes('denied') || message.includes('refused')) {
+            return 'event-rejected';
+        }
+        // Invalid response
+        if (message.includes('invalid') || message.includes('malformed') || message.includes('parse')) {
+            return 'event-invalid-response';
+        }
+        // Log unexpected errors for debugging
+        if (context) {
+            console.warn(`${context} error:`, err.message);
+        }
+    }
+    // Default to unavailable for unknown errors
+    return 'event-unavailable';
+}
+/**
+ * Map common LLM SDK exceptions to standard error codes.
+ *
+ * @internal
+ */
+function mapLLMException(err) {
+    if (err instanceof Error) {
+        const message = err.message.toLowerCase();
+        // Content policy violations
+        if (message.includes('content_policy') || message.includes('content filter') || message.includes('content policy')) {
+            return 'llm-refusal';
+        }
+        // Rate limiting
+        if (message.includes('rate limit') || message.includes('429')) {
+            return 'llm-rate-limit';
+        }
+        // Timeouts
+        if (message.includes('timeout') || message.includes('etimedout')) {
+            return 'llm-timeout';
+        }
+        // Token limits
+        if (message.includes('token') && message.includes('limit')) {
+            return 'llm-token-limit';
+        }
+        // Service unavailable
+        if (message.includes('503') || message.includes('502')) {
+            return LLM_UNAVAILABLE_ERROR;
+        }
+    }
+    // Default to unavailable for unknown errors
+    return LLM_UNAVAILABLE_ERROR;
+}
+//# sourceMappingURL=agent-helpers.js.map

package/dist/agent-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-helpers.js","sourceRoot":"","sources":["../src/agent-helpers.ts"],"names":[],"mappings":"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"}

package/dist/agentic-researcher.d.ts

@@ -0,0 +1,63 @@
+import { type z } from 'zod';
+import type { Agent, ResearcherContext } from './types.js';
+/**
+ * Configuration for defining an agentic researcher agent
+ */
+export interface AgenticResearcherConfig<TInput, TOutput> {
+    /** Unique name for the agent */
+    name: string;
+    /** Human-readable description of what the agent does */
+    description: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version: string;
+    /** Zod schema for input validation */
+    inputSchema: z.ZodType<TInput>;
+    /** Zod schema for output validation */
+    outputSchema: z.ZodType<TOutput>;
+    /** List of tool names this agent can use (optional) */
+    tools?: string[];
+    /** Maximum number of iterations (default: 10) */
+    maxIterations?: number;
+    /** Whether this agent can be mocked in tests (default: true) */
+    mockable?: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Defines an agentic researcher agent that iteratively uses tools and LLM
+ * reasoning to accomplish complex research tasks.
+ *
+ * The agent validates inputs and outputs using Zod schemas, provides
+ * access to tools and LLM context, and tracks iteration count.
+ *
+ * @param config - Agent configuration including schemas and tools
+ * @param handler - Async function that uses research context
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const researchAgent = defineAgenticResearcher(
+ *   {
+ *     name: 'web-researcher',
+ *     description: 'Researches topics using web search',
+ *     version: '1.0.0',
+ *     inputSchema: z.object({ topic: z.string() }),
+ *     outputSchema: z.object({ findings: z.string() }),
+ *     tools: ['search', 'scrape'],
+ *     maxIterations: 5,
+ *   },
+ *   async (input, ctx) => {
+ *     let findings = '';
+ *     while (ctx.iterationCount < ctx.maxIterations) {
+ *       const query = await ctx.callLLM(`What should I search next for: ${input.topic}`);
+ *       const results = await ctx.callTool('search', { query });
+ *       findings += results;
+ *       ctx.iterationCount++;
+ *     }
+ *     return { findings };
+ *   }
+ * );
+ * ```
+ */
+export declare function defineAgenticResearcher<TInput, TOutput>(config: AgenticResearcherConfig<TInput, TOutput>, handler: (input: TInput, ctx: ResearcherContext) => Promise<TOutput>): Agent<TInput, TOutput>;
+//# sourceMappingURL=agentic-researcher.d.ts.map

package/dist/agentic-researcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-researcher.d.ts","sourceRoot":"","sources":["../src/agentic-researcher.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAG7B,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,uBAAuB,CAAC,MAAM,EAAE,OAAO;IACtD,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/B,uCAAuC;IACvC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjC,uDAAuD;IACvD,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IAEjB,iDAAiD;IACjD,aAAa,CAAC,EAAE,MAAM,CAAC;IAEvB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,OAAO,EACrD,MAAM,EAAE,uBAAuB,CAAC,MAAM,EAAE,OAAO,CAAC,EAChD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,KAAK,OAAO,CAAC,OAAO,CAAC,GACnE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CA2BxB"}

package/dist/agentic-researcher.js

@@ -0,0 +1,60 @@
+import { buildManifest, createAsyncExecuteWrapperWithContext } from './execute-wrapper.js';
+/**
+ * Defines an agentic researcher agent that iteratively uses tools and LLM
+ * reasoning to accomplish complex research tasks.
+ *
+ * The agent validates inputs and outputs using Zod schemas, provides
+ * access to tools and LLM context, and tracks iteration count.
+ *
+ * @param config - Agent configuration including schemas and tools
+ * @param handler - Async function that uses research context
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const researchAgent = defineAgenticResearcher(
+ *   {
+ *     name: 'web-researcher',
+ *     description: 'Researches topics using web search',
+ *     version: '1.0.0',
+ *     inputSchema: z.object({ topic: z.string() }),
+ *     outputSchema: z.object({ findings: z.string() }),
+ *     tools: ['search', 'scrape'],
+ *     maxIterations: 5,
+ *   },
+ *   async (input, ctx) => {
+ *     let findings = '';
+ *     while (ctx.iterationCount < ctx.maxIterations) {
+ *       const query = await ctx.callLLM(`What should I search next for: ${input.topic}`);
+ *       const results = await ctx.callTool('search', { query });
+ *       findings += results;
+ *       ctx.iterationCount++;
+ *     }
+ *     return { findings };
+ *   }
+ * );
+ * ```
+ */
+export function defineAgenticResearcher(config, handler) {
+    // Build manifest
+    const manifest = buildManifest(config, 'agentic-researcher', {
+        mockable: config.mockable ?? true,
+        maxIterations: config.maxIterations ?? 10,
+        ...(config.tools && { tools: config.tools }),
+    });
+    // Create validated execute function
+    const execute = createAsyncExecuteWrapperWithContext(config, handler, (ctx) => ({
+        mockable: config.mockable ?? true,
+        tools: ctx.tools,
+        callLLM: ctx.callLLM,
+        callTool: ctx.callTool,
+        iterationCount: 0,
+        maxIterations: config.maxIterations ?? 10,
+    }));
+    return {
+        name: config.name,
+        execute,
+        manifest,
+    };
+}
+//# sourceMappingURL=agentic-researcher.js.map

package/dist/agentic-researcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agentic-researcher.js","sourceRoot":"","sources":["../src/agentic-researcher.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,oCAAoC,EAAE,MAAM,sBAAsB,CAAC;AAmC3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,uBAAuB,CACrC,MAAgD,EAChD,OAAoE;IAEpE,iBAAiB;IACjB,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,EAAE,oBAAoB,EAAE;QAC3D,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;QACzC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,CAAC;KAC7C,CAAC,CAAC;IAEH,oCAAoC;IACpC,MAAM,OAAO,GAAG,oCAAoC,CAClD,MAAM,EACN,OAAO,EACP,CAAC,GAAsB,EAAqB,EAAE,CAAC,CAAC;QAC9C,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,OAAO,EAAE,GAAG,CAAC,OAAO;QACpB,QAAQ,EAAE,GAAG,CAAC,QAAQ;QACtB,cAAc,EAAE,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC,aAAa,IAAI,EAAE;KAC1C,CAAC,CACH,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO;QACP,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/conversational-assistant.d.ts

@@ -0,0 +1,57 @@
+import { type z } from 'zod';
+import type { Agent, ConversationalContext } from './types.js';
+/**
+ * Configuration for defining a conversational assistant agent
+ */
+export interface ConversationalAssistantConfig<TInput, TOutput> {
+    /** Unique name for the agent */
+    name: string;
+    /** Human-readable description of what the agent does */
+    description: string;
+    /** Semantic version (e.g., "1.0.0") */
+    version: string;
+    /** Zod schema for input validation */
+    inputSchema: z.ZodType<TInput>;
+    /** Zod schema for output validation */
+    outputSchema: z.ZodType<TOutput>;
+    /** System prompt for the assistant (optional) */
+    systemPrompt?: string;
+    /** Whether this agent can be mocked in tests (default: true) */
+    mockable?: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Defines a conversational assistant agent that maintains context across
+ * multiple interactions using conversation history.
+ *
+ * The agent validates inputs and outputs using Zod schemas, provides
+ * conversation context to the handler, and generates a manifest describing
+ * its interface.
+ *
+ * @param config - Agent configuration including schemas and system prompt
+ * @param handler - Async function that uses conversation context
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const chatAgent = defineConversationalAssistant(
+ *   {
+ *     name: 'helpful-assistant',
+ *     description: 'A helpful conversational assistant',
+ *     version: '1.0.0',
+ *     inputSchema: z.object({ message: z.string() }),
+ *     outputSchema: z.object({ reply: z.string() }),
+ *     systemPrompt: 'You are a helpful assistant.',
+ *   },
+ *   async (input, ctx) => {
+ *     ctx.addToHistory('user', input.message);
+ *     const response = await ctx.callLLM(ctx.history);
+ *     ctx.addToHistory('assistant', response);
+ *     return { reply: response };
+ *   }
+ * );
+ * ```
+ */
+export declare function defineConversationalAssistant<TInput, TOutput>(config: ConversationalAssistantConfig<TInput, TOutput>, handler: (input: TInput, ctx: ConversationalContext) => Promise<TOutput>): Agent<TInput, TOutput>;
+//# sourceMappingURL=conversational-assistant.d.ts.map

package/dist/conversational-assistant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversational-assistant.d.ts","sourceRoot":"","sources":["../src/conversational-assistant.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,CAAC;AAO7B,OAAO,KAAK,EAAE,KAAK,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,6BAA6B,CAAC,MAAM,EAAE,OAAO;IAC5D,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IAEb,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IAEpB,uCAAuC;IACvC,OAAO,EAAE,MAAM,CAAC;IAEhB,sCAAsC;IACtC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/B,uCAAuC;IACvC,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjC,iDAAiD;IACjD,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,6BAA6B,CAAC,MAAM,EAAE,OAAO,EAC3D,MAAM,EAAE,6BAA6B,CAAC,MAAM,EAAE,OAAO,CAAC,EACtD,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,GACvE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAmBxB"}

package/dist/conversational-assistant.js

@@ -0,0 +1,48 @@
+import { buildManifest, createAsyncExecuteWrapperWithContext, createConversationalContextMapper, } from './execute-wrapper.js';
+/**
+ * Defines a conversational assistant agent that maintains context across
+ * multiple interactions using conversation history.
+ *
+ * The agent validates inputs and outputs using Zod schemas, provides
+ * conversation context to the handler, and generates a manifest describing
+ * its interface.
+ *
+ * @param config - Agent configuration including schemas and system prompt
+ * @param handler - Async function that uses conversation context
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const chatAgent = defineConversationalAssistant(
+ *   {
+ *     name: 'helpful-assistant',
+ *     description: 'A helpful conversational assistant',
+ *     version: '1.0.0',
+ *     inputSchema: z.object({ message: z.string() }),
+ *     outputSchema: z.object({ reply: z.string() }),
+ *     systemPrompt: 'You are a helpful assistant.',
+ *   },
+ *   async (input, ctx) => {
+ *     ctx.addToHistory('user', input.message);
+ *     const response = await ctx.callLLM(ctx.history);
+ *     ctx.addToHistory('assistant', response);
+ *     return { reply: response };
+ *   }
+ * );
+ * ```
+ */
+export function defineConversationalAssistant(config, handler) {
+    // Build manifest
+    const manifest = buildManifest(config, 'conversational-assistant', {
+        mockable: config.mockable ?? true,
+        ...(config.systemPrompt && { systemPrompt: config.systemPrompt }),
+    });
+    // Create validated execute function
+    const execute = createAsyncExecuteWrapperWithContext(config, handler, createConversationalContextMapper(config.mockable ?? true));
+    return {
+        name: config.name,
+        execute,
+        manifest,
+    };
+}
+//# sourceMappingURL=conversational-assistant.js.map

package/dist/conversational-assistant.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversational-assistant.js","sourceRoot":"","sources":["../src/conversational-assistant.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,aAAa,EACb,oCAAoC,EACpC,iCAAiC,GAClC,MAAM,sBAAsB,CAAC;AAgC9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,6BAA6B,CAC3C,MAAsD,EACtD,OAAwE;IAExE,iBAAiB;IACjB,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,EAAE,0BAA0B,EAAE;QACjE,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,GAAG,CAAC,MAAM,CAAC,YAAY,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;KAClE,CAAC,CAAC;IAEH,oCAAoC;IACpC,MAAM,OAAO,GAAG,oCAAoC,CAClD,MAAM,EACN,OAAO,EACP,iCAAiC,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,CAC3D,CAAC;IAEF,OAAO;QACL,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,OAAO;QACP,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/conversational-helpers.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Helper utilities for building conversational agent contexts
+ */
+import type { ConversationalContext, Message } from './types.js';
+/**
+ * Creates a conversational context with the given LLM function and history
+ * Reduces duplication between adapters and examples
+ *
+ * @param history - Conversation history array (will be mutated by addToHistory)
+ * @param callLLM - Function to call the LLM with messages
+ * @returns ConversationalContext object
+ *
+ * @example
+ * ```typescript
+ * const session = { history: [] };
+ * const context = createConversationalContext(
+ *   session.history,
+ *   async (messages) => {
+ *     // Call your LLM here
+ *     return "response";
+ *   }
+ * );
+ * ```
+ */
+export declare function createConversationalContext(history: Message[], callLLM: (messages: Message[]) => Promise<string>): ConversationalContext;
+//# sourceMappingURL=conversational-helpers.d.ts.map

package/dist/conversational-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversational-helpers.d.ts","sourceRoot":"","sources":["../src/conversational-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,qBAAqB,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,OAAO,EAAE,EAClB,OAAO,EAAE,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,MAAM,CAAC,GAChD,qBAAqB,CASvB"}

package/dist/conversational-helpers.js

@@ -0,0 +1,34 @@
+/**
+ * Helper utilities for building conversational agent contexts
+ */
+/**
+ * Creates a conversational context with the given LLM function and history
+ * Reduces duplication between adapters and examples
+ *
+ * @param history - Conversation history array (will be mutated by addToHistory)
+ * @param callLLM - Function to call the LLM with messages
+ * @returns ConversationalContext object
+ *
+ * @example
+ * ```typescript
+ * const session = { history: [] };
+ * const context = createConversationalContext(
+ *   session.history,
+ *   async (messages) => {
+ *     // Call your LLM here
+ *     return "response";
+ *   }
+ * );
+ * ```
+ */
+export function createConversationalContext(history, callLLM) {
+    return {
+        mockable: false,
+        history,
+        addToHistory: (role, content) => {
+            history.push({ role, content });
+        },
+        callLLM,
+    };
+}
+//# sourceMappingURL=conversational-helpers.js.map

package/dist/conversational-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"conversational-helpers.js","sourceRoot":"","sources":["../src/conversational-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAkB,EAClB,OAAiD;IAEjD,OAAO;QACL,QAAQ,EAAE,KAAK;QACf,OAAO;QACP,YAAY,EAAE,CAAC,IAAqC,EAAE,OAAe,EAAE,EAAE;YACvE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAClC,CAAC;QACD,OAAO;KACR,CAAC;AACJ,CAAC"}