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

package/README.md

@@ -0,0 +1,295 @@
+# @vibe-agent-toolkit/agent-runtime
+
+Runtime framework for building portable AI agents across multiple agent archetypes.
+
+## Features
+
+- **Agent Archetypes**: Pre-defined patterns for common agent types
+- **Type-Safe**: Full TypeScript support with Zod schema validation
+- **Framework Agnostic**: Agents work with any LLM provider
+- **Declarative Configuration**: Minimal boilerplate, maximum clarity
+
+## Agent Archetypes
+
+### 1. Pure Function Tool
+Stateless, deterministic functions with no external dependencies.
+
+```typescript
+import { definePureFunction } from '@vibe-agent-toolkit/agent-runtime';
+import { z } from 'zod';
+
+export const haiku Validator = definePureFunction({
+  name: 'haiku-validator',
+  description: 'Validates haiku structure (5-7-5 syllables)',
+  version: '1.0.0',
+  inputSchema: z.object({ line1: z.string(), line2: z.string(), line3: z.string() }),
+  outputSchema: z.object({ valid: z.boolean(), errors: z.array(z.string()) }),
+}, (input) => {
+  // Implementation
+  return { valid: true, errors: [] };
+});
+```
+
+### 2. LLM Analyzer
+Single LLM call for classification or extraction tasks.
+
+```typescript
+import { defineLLMAnalyzer } from '@vibe-agent-toolkit/agent-runtime';
+
+export const photoAnalyzer = defineLLMAnalyzer({
+  name: 'photo-analyzer',
+  description: 'Analyzes cat photos using vision LLM',
+  version: '1.0.0',
+  inputSchema: PhotoInputSchema,
+  outputSchema: CatCharacteristicsSchema,
+  systemPrompt: 'You are an expert cat analyzer...',
+}, async (input, ctx) => {
+  const analysis = await ctx.callLLM(`Analyze this cat: ${input.imagePath}`);
+  return JSON.parse(analysis);
+});
+```
+
+### 3. Conversational Assistant
+Multi-turn dialogue with conversation history.
+
+```typescript
+import { defineConversationalAssistant } from '@vibe-agent-toolkit/agent-runtime';
+
+export const chatAgent = defineConversationalAssistant({
+  name: 'breed-advisor',
+  description: 'Helps users find their perfect cat breed',
+  version: '1.0.0',
+  inputSchema: InputSchema,
+  outputSchema: OutputSchema,
+  systemPrompt: 'You are a friendly cat breed advisor...',
+}, async (input, ctx) => {
+  ctx.addToHistory('user', input.message);
+  const response = await ctx.callLLM(ctx.history);
+  ctx.addToHistory('assistant', response);
+  return { reply: response };
+});
+```
+
+### 3a. Two-Phase Conversational Assistant ⭐ NEW
+
+**Recommended pattern for conversational agents that gather information.**
+
+The two-phase pattern solves the "JSON every turn" anti-pattern by separating:
+- **Phase 1 (Gathering)**: Natural conversational text responses
+- **Phase 2 (Extraction)**: Structured data extraction when ready
+
+```typescript
+import { defineTwoPhaseConversationalAssistant } from '@vibe-agent-toolkit/agent-runtime';
+
+export const breedAdvisor = defineTwoPhaseConversationalAssistant({
+  name: 'breed-advisor',
+  description: 'Helps users find their perfect cat breed',
+  version: '2.0.0',
+  inputSchema: BreedAdvisorInputSchema,
+  outputSchema: BreedAdvisorOutputSchema,
+
+  gatheringPhase: {
+    tone: 'enthusiastic',
+    factors: [
+      {
+        name: 'musicPreference',
+        type: 'enum',
+        values: ['classical', 'jazz', 'rock', 'pop'],
+        required: true,
+        clarificationHint: 'Ask which category fits best for non-standard genres',
+      },
+      {
+        name: 'livingSpace',
+        type: 'enum',
+        values: ['apartment', 'house', 'farm'],
+        naturalLanguageMappings: {
+          'flat': 'apartment',
+          'big house': 'house',
+        },
+      },
+    ],
+    readinessCheck: (profile) => Object.keys(profile).length >= 4,
+  },
+
+  extractionPhase: {
+    generateRecommendations: (profile) => matchBreeds(profile),
+    useStructuredOutputs: false, // Set true for OpenAI gpt-4o-2024-08-06+
+  },
+});
+```
+
+**Key Benefits:**
+- **Declarative Configuration**: 200+ lines of manual prompts → 50 lines of config
+- **Automatic Validation**: Enum guidance generated from factor definitions
+- **Natural Language Mappings**: Common phrases → formal values
+- **Priority Factors**: Guide conversation flow
+
+See [docs/structured-outputs.md](../../docs/structured-outputs.md) for detailed pattern comparison and best practices.
+
+### 4. Agentic Researcher
+ReAct pattern with tool calling and iterative reasoning.
+
+```typescript
+import { defineAgenticResearcher } from '@vibe-agent-toolkit/agent-runtime';
+
+export const researcher = defineAgenticResearcher({
+  name: 'breed-historian',
+  description: 'Researches cat breed history with web search',
+  version: '1.0.0',
+  inputSchema: ResearchInputSchema,
+  outputSchema: ResearchOutputSchema,
+  tools: {
+    webSearch: async (query: string) => { /* ... */ },
+  },
+}, async (input, ctx) => {
+  // ReAct loop: Thought → Action → Observation
+  for (let i = 0; i < ctx.maxIterations; i++) {
+    const thought = await ctx.callLLM(`Research: ${input.query}`);
+    const result = await ctx.callTool('webSearch', thought);
+    // Process result...
+  }
+});
+```
+
+### 5. Function Workflow Orchestrator
+Deterministic multi-agent coordination.
+
+```typescript
+import { defineFunctionOrchestrator } from '@vibe-agent-toolkit/agent-runtime';
+
+export const orchestrator = defineFunctionOrchestrator({
+  name: 'adoption-pipeline',
+  description: 'Coordinates multi-step adoption process',
+  version: '1.0.0',
+  inputSchema: AdoptionInputSchema,
+  outputSchema: AdoptionOutputSchema,
+}, async (input, ctx) => {
+  // Call multiple agents in sequence
+  const analysis = await ctx.call('photo-analyzer', { image: input.photo });
+  const validation = await ctx.call('name-validator', { name: input.name });
+  const approval = await ctx.call('human-approval', { data: { analysis, validation } });
+
+  return { approved: approval.approved };
+});
+```
+
+### 6. LLM Intelligent Coordinator
+LLM-based routing decisions in workflows.
+
+```typescript
+import { defineLLMCoordinator } from '@vibe-agent-toolkit/agent-runtime';
+
+export const coordinator = defineLLMCoordinator({
+  name: 'smart-router',
+  description: 'Routes submissions based on complexity',
+  version: '1.0.0',
+  inputSchema: SubmissionSchema,
+  outputSchema: RoutingSchema,
+  systemPrompt: 'Route submissions to the right handler...',
+}, async (input, ctx) => {
+  const decision = await ctx.callLLM(`Route: ${input.submission}`);
+
+  return ctx.route(decision, {
+    simple: async () => ctx.call('auto-approver', input),
+    complex: async () => ctx.call('human-review', input),
+  });
+});
+```
+
+### 7. Function Event Consumer
+Event-triggered execution without LLM.
+
+```typescript
+import { defineFunctionEventConsumer } from '@vibe-agent-toolkit/agent-runtime';
+
+export const processor = defineFunctionEventConsumer({
+  name: 'pedigree-processor',
+  description: 'Processes uploaded pedigree files',
+  version: '1.0.0',
+  inputSchema: FileEventSchema,
+  outputSchema: ProcessingResultSchema,
+}, async (input, ctx) => {
+  const file = await parseFile(input.filePath);
+  await ctx.emit('pedigree-processed', { result: file });
+  return { status: 'processed' };
+});
+```
+
+### 8. LLM Event Handler
+Event-triggered with LLM processing.
+
+```typescript
+import { defineLLMEventHandler } from '@vibe-agent-toolkit/agent-runtime';
+
+export const handler = defineLLMEventHandler({
+  name: 'triage-handler',
+  description: 'Triages incoming submissions with LLM',
+  version: '1.0.0',
+  inputSchema: SubmissionEventSchema,
+  outputSchema: TriageResultSchema,
+  systemPrompt: 'Triage submissions by urgency...',
+}, async (input, ctx) => {
+  const priority = await ctx.callLLM(`Triage: ${input.submission}`);
+  await ctx.emit('submission-triaged', { priority });
+  return { priority };
+});
+```
+
+### 9. External Event Integrator
+Human-in-the-loop approval gates.
+
+```typescript
+import { defineExternalEventIntegrator } from '@vibe-agent-toolkit/agent-runtime';
+
+export const approvalGate = defineExternalEventIntegrator({
+  name: 'human-approval',
+  description: 'Waits for human approval',
+  version: '1.0.0',
+  inputSchema: ApprovalRequestSchema,
+  outputSchema: ApprovalResultSchema,
+  timeoutMs: 60000,
+  onTimeout: 'reject',
+}, async (input, ctx) => {
+  await ctx.emit('approval-requested', input);
+  const result = await ctx.waitFor('approval-response', ctx.timeoutMs);
+  return result;
+});
+```
+
+## Agent Manifest
+
+Every agent exposes a manifest describing its interface:
+
+```typescript
+const agent = defineAgentType(config, handler);
+
+console.log(agent.manifest);
+// {
+//   name: 'agent-name',
+//   description: 'What this agent does',
+//   version: '1.0.0',
+//   archetype: 'archetype-name',
+//   inputSchema: { /* JSON Schema */ },
+//   outputSchema: { /* JSON Schema */ },
+//   metadata: { /* Additional info */ }
+// }
+```
+
+## Runtime Adapters
+
+Agents are framework-agnostic. Use runtime adapters to integrate with specific LLM frameworks:
+
+- `@vibe-agent-toolkit/runtime-openai` - OpenAI SDK
+- `@vibe-agent-toolkit/runtime-vercel-ai-sdk` - Vercel AI SDK
+- `@vibe-agent-toolkit/runtime-langchain` - LangChain
+- `@vibe-agent-toolkit/runtime-claude-agent-sdk` - Claude Agent SDK
+
+See individual runtime packages for usage examples.
+
+## Examples
+
+See `@vibe-agent-toolkit/vat-example-cat-agents` for complete examples across all archetypes.
+
+## License
+
+MIT

package/dist/adapter-types.d.ts

@@ -0,0 +1,48 @@
+import type { z } from 'zod';
+import type { Agent, PureFunctionAgent } from './types.js';
+/**
+ * Configuration for converting a pure function agent to a runtime-specific tool
+ */
+export interface ToolConversionConfig<TInput = unknown, TOutput = unknown> {
+    agent: PureFunctionAgent<TInput, TOutput>;
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+}
+/**
+ * Configuration for converting an LLM analyzer agent to a runtime-specific function
+ */
+export interface LLMAnalyzerConversionConfig<TInput = unknown, TOutput = unknown> {
+    agent: Agent<TInput, TOutput>;
+    inputSchema: z.ZodType<TInput>;
+    outputSchema: z.ZodType<TOutput>;
+}
+/**
+ * Batch conversion configuration for pure function tools
+ */
+export type ToolConversionConfigs = Record<string, ToolConversionConfig>;
+/**
+ * Batch conversion configuration for LLM analyzer functions
+ */
+export type LLMAnalyzerConversionConfigs = Record<string, LLMAnalyzerConversionConfig>;
+/**
+ * Generic batch conversion utility for converting multiple configs to results
+ * Eliminates code duplication in runtime adapters
+ *
+ * @param configs - Map of keys to conversion configurations
+ * @param converter - Function that converts a single config to a result
+ * @returns Map of keys to conversion results
+ *
+ * @example
+ * ```typescript
+ * const tools = batchConvert(configs, (config) => {
+ *   const { tool, metadata } = convertPureFunctionToTool(
+ *     config.agent,
+ *     config.inputSchema,
+ *     config.outputSchema,
+ *   );
+ *   return { tool, metadata };
+ * });
+ * ```
+ */
+export declare function batchConvert<TConfig, TResult>(configs: Record<string, TConfig>, converter: (config: TConfig) => TResult): Record<string, TResult>;
+//# sourceMappingURL=adapter-types.d.ts.map

package/dist/adapter-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-types.d.ts","sourceRoot":"","sources":["../src/adapter-types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,KAAK,EAAE,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE3D;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IACvE,KAAK,EAAE,iBAAiB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,2BAA2B,CAAC,MAAM,GAAG,OAAO,EAAE,OAAO,GAAG,OAAO;IAC9E,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,WAAW,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/B,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC;AAEzE;;GAEG;AACH,MAAM,MAAM,4BAA4B,GAAG,MAAM,CAAC,MAAM,EAAE,2BAA2B,CAAC,CAAC;AAEvF;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAC3C,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,SAAS,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,OAAO,GACtC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIzB"}

package/dist/adapter-types.js

@@ -0,0 +1,24 @@
+/**
+ * Generic batch conversion utility for converting multiple configs to results
+ * Eliminates code duplication in runtime adapters
+ *
+ * @param configs - Map of keys to conversion configurations
+ * @param converter - Function that converts a single config to a result
+ * @returns Map of keys to conversion results
+ *
+ * @example
+ * ```typescript
+ * const tools = batchConvert(configs, (config) => {
+ *   const { tool, metadata } = convertPureFunctionToTool(
+ *     config.agent,
+ *     config.inputSchema,
+ *     config.outputSchema,
+ *   );
+ *   return { tool, metadata };
+ * });
+ * ```
+ */
+export function batchConvert(configs, converter) {
+    return Object.fromEntries(Object.entries(configs).map(([key, config]) => [key, converter(config)]));
+}
+//# sourceMappingURL=adapter-types.js.map

package/dist/adapter-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter-types.js","sourceRoot":"","sources":["../src/adapter-types.ts"],"names":[],"mappings":"AAgCA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAgC,EAChC,SAAuC;IAEvC,OAAO,MAAM,CAAC,WAAW,CACvB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CACzE,CAAC;AACJ,CAAC"}

package/dist/agent-helpers.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Helper functions for creating agents.
+ */
+import type { AgentResult, ExternalEventError, LLMError, OneShotAgentOutput } from '@vibe-agent-toolkit/agent-schema';
+/**
+ * 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'
+ * );
+ */
+export declare function validateAgentInput<TInput, TData, TError extends string = LLMError>(input: unknown, schema: {
+    safeParse: (data: unknown) => {
+        success: boolean;
+        data?: TInput;
+    };
+}, invalidInputError?: TError): TInput | OneShotAgentOutput<TData, TError>;
+/**
+ * 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 declare function executeLLMCall<T>(fn: () => Promise<T>, options?: {
+    parseOutput?: (raw: unknown) => T;
+    timeoutMs?: number;
+}): Promise<AgentResult<T, LLMError>>;
+/**
+ * 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 declare function executeLLMAnalyzer<TData>(config: {
+    mockable: boolean;
+    mockFn: () => TData;
+    realFn?: () => Promise<unknown>;
+    parseOutput?: (raw: unknown) => TData;
+    errorContext?: string;
+    notImplementedMessage?: string;
+}): Promise<OneShotAgentOutput<TData, LLMError>>;
+/**
+ * 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 declare function executeExternalEvent<TData>(config: {
+    autoResponse?: TData;
+    handler: () => Promise<TData>;
+    timeoutMs?: number;
+    errorContext?: string;
+}): Promise<OneShotAgentOutput<TData, ExternalEventError>>;
+//# sourceMappingURL=agent-helpers.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-helpers.d.ts","sourceRoot":"","sources":["../src/agent-helpers.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,kBAAkB,EAClB,QAAQ,EACR,kBAAkB,EACnB,MAAM,kCAAkC,CAAC;AAQ1C;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,KAAK,EAAE,MAAM,SAAS,MAAM,GAAG,QAAQ,EAChF,KAAK,EAAE,OAAO,EACd,MAAM,EAAE;IAAE,SAAS,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CAAE,EAC7E,iBAAiB,GAAE,MAAuC,GACzD,MAAM,GAAG,kBAAkB,CAAC,KAAK,EAAE,MAAM,CAAC,CAQ5C;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE;IACR,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,CAAC,CAAC;IAClC,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,GACA,OAAO,CAAC,WAAW,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC,CA4BnC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAsB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE;IACtD,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,EAAE,MAAM,KAAK,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,KAAK,CAAC;IACtC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC,GAAG,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAoD/C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,oBAAoB,CAAC,KAAK,EAAE,MAAM,EAAE;IACxD,YAAY,CAAC,EAAE,KAAK,CAAC;IACrB,OAAO,EAAE,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GAAG,OAAO,CAAC,kBAAkB,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAoCzD"}