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

package/dist/two-phase-conversational.d.ts

@@ -0,0 +1,173 @@
+/**
+ * Two-Phase Conversational Assistant Pattern
+ *
+ * Provides a declarative API for building conversational agents that gather
+ * information naturally through dialogue (Phase 1), then extract structured
+ * data when ready (Phase 2).
+ *
+ * This pattern solves the "JSON every turn" anti-pattern where LLMs are asked
+ * to return JSON on every conversational turn, fighting their natural
+ * conversational behavior.
+ */
+import { type z } from 'zod';
+import type { Agent, ConversationalContext } from './types.js';
+/**
+ * Defines a single piece of information to gather
+ */
+export interface FactorDefinition {
+    /** Unique name for this factor (e.g., "musicPreference") */
+    name: string;
+    /** Human-readable description of what this factor represents */
+    description?: string;
+    /** Data type of this factor */
+    type: 'string' | 'enum' | 'boolean' | 'number';
+    /** Valid enum values (required if type is 'enum') */
+    values?: string[];
+    /** Whether this factor is required to proceed to extraction phase */
+    required?: boolean;
+    /** Weight/importance multiplier (default: 1) */
+    weight?: number;
+    /** Guidance for handling user input that doesn't map to valid values */
+    clarificationHint?: string;
+    /**
+     * Natural language mappings from common user phrases to formal values
+     * Example: { "big house": "large-house", "flat": "apartment" }
+     */
+    naturalLanguageMappings?: Record<string, string>;
+    /**
+     * Examples of valid values to help the LLM understand
+     * Example: ["classical", "jazz", "rock"]
+     */
+    examples?: string[];
+}
+/**
+ * Configuration for Phase 1: Gathering
+ */
+export interface GatheringPhaseConfig {
+    /** Conversational tone (e.g., "friendly", "professional", "enthusiastic") */
+    tone?: string;
+    /** Factors to gather during conversation */
+    factors: FactorDefinition[];
+    /**
+     * Function to determine if enough information has been gathered
+     * Default: all required factors are present
+     */
+    readinessCheck?: (profile: Record<string, unknown>) => boolean;
+    /**
+     * Custom guidance to include in the gathering phase prompt
+     * Use this to add domain-specific context or instructions
+     */
+    customGuidance?: string;
+    /**
+     * Whether to prioritize certain factors in conversation flow
+     * If provided, LLM will ask about these factors early
+     */
+    priorityFactors?: string[];
+}
+/**
+ * Configuration for Phase 2: Extraction
+ */
+export interface ExtractionPhaseConfig {
+    /**
+     * Optional function to generate recommendations/results from gathered profile
+     * This is called after structured extraction to enhance the output
+     */
+    generateRecommendations?: (profile: Record<string, unknown>) => unknown;
+    /**
+     * Whether to use Structured Outputs API (OpenAI gpt-4o-2024-08-06+)
+     * for 100% schema adherence. Default: false
+     */
+    useStructuredOutputs?: boolean;
+    /**
+     * Custom prompt for extraction phase
+     * If not provided, a default extraction prompt is generated
+     */
+    customExtractionPrompt?: string;
+}
+/**
+ * Complete configuration for two-phase conversational assistant
+ */
+export interface TwoPhaseConversationalConfig<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 (used in extraction phase) */
+    outputSchema: z.ZodType<TOutput>;
+    /** Gathering phase configuration */
+    gatheringPhase: GatheringPhaseConfig;
+    /** Extraction phase configuration */
+    extractionPhase: ExtractionPhaseConfig;
+    /** Whether this agent can be mocked in tests (default: true) */
+    mockable?: boolean;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Generates the system prompt for Phase 1: Gathering
+ */
+export declare function generateGatheringPrompt(config: GatheringPhaseConfig): string;
+/**
+ * Generates the system prompt for Phase 2: Extraction
+ */
+export declare function generateExtractionPrompt(config: ExtractionPhaseConfig, gatheredProfile: Record<string, unknown>): string;
+/**
+ * Defines a two-phase conversational assistant agent.
+ *
+ * Phase 1 (Gathering): Natural conversation to collect information
+ * - No JSON output required
+ * - Conversational text responses
+ * - Accumulates factors informally
+ *
+ * Phase 2 (Extraction): Structured data extraction
+ * - JSON output with schema validation
+ * - Triggered when readiness check passes
+ * - Uses Structured Outputs API if configured
+ *
+ * @param config - Two-phase configuration
+ * @param handler - Optional custom handler (if you want full control)
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const breedAdvisor = defineTwoPhaseConversationalAssistant({
+ *   name: 'breed-advisor',
+ *   description: 'Helps users find their perfect cat breed',
+ *   version: '1.0.0',
+ *   inputSchema: BreedAdvisorInputSchema,
+ *   gatheringPhase: {
+ *     tone: 'enthusiastic',
+ *     factors: [
+ *       {
+ *         name: 'musicPreference',
+ *         description: 'User\'s music taste',
+ *         type: 'enum',
+ *         values: ['classical', 'jazz', 'rock', 'pop'],
+ *         required: true,
+ *         weight: 2,
+ *       },
+ *       {
+ *         name: 'livingSpace',
+ *         type: 'enum',
+ *         values: ['apartment', 'house', 'farm'],
+ *         naturalLanguageMappings: {
+ *           'flat': 'apartment',
+ *           'big house': 'house',
+ *         },
+ *       },
+ *     ],
+ *     readinessCheck: (profile) => Object.keys(profile).length >= 4,
+ *   },
+ *   extractionPhase: {
+ *     outputSchema: BreedRecommendationSchema,
+ *     generateRecommendations: matchBreeds,
+ *   },
+ * });
+ * ```
+ */
+export declare function defineTwoPhaseConversationalAssistant<TInput, TOutput>(config: TwoPhaseConversationalConfig<TInput, TOutput>, handler?: (input: TInput, ctx: ConversationalContext) => Promise<TOutput>): Agent<TInput, TOutput>;
+//# sourceMappingURL=two-phase-conversational.d.ts.map

package/dist/two-phase-conversational.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-phase-conversational.d.ts","sourceRoot":"","sources":["../src/two-phase-conversational.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,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,gBAAgB;IAC/B,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IAEb,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,+BAA+B;IAC/B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,CAAC;IAE/C,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAElB,qEAAqE;IACrE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAE3B;;;OAGG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAEjD;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,4CAA4C;IAC5C,OAAO,EAAE,gBAAgB,EAAE,CAAC;IAE5B;;;OAGG;IACH,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAE/D;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC;IAExE;;;OAGG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,4BAA4B,CAAC,MAAM,EAAE,OAAO;IAC3D,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,kEAAkE;IAClE,YAAY,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAEjC,oCAAoC;IACpC,cAAc,EAAE,oBAAoB,CAAC;IAErC,qCAAqC;IACrC,eAAe,EAAE,qBAAqB,CAAC;IAEvC,gEAAgE;IAChE,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,0BAA0B;IAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,oBAAoB,GAAG,MAAM,CA6E5E;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,qBAAqB,EAC7B,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACvC,MAAM,CAaR;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,wBAAgB,qCAAqC,CAAC,MAAM,EAAE,OAAO,EACnE,MAAM,EAAE,4BAA4B,CAAC,MAAM,EAAE,OAAO,CAAC,EACrD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,qBAAqB,KAAK,OAAO,CAAC,OAAO,CAAC,GACxE,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,CAuExB"}

package/dist/two-phase-conversational.js

@@ -0,0 +1,205 @@
+/**
+ * Two-Phase Conversational Assistant Pattern
+ *
+ * Provides a declarative API for building conversational agents that gather
+ * information naturally through dialogue (Phase 1), then extract structured
+ * data when ready (Phase 2).
+ *
+ * This pattern solves the "JSON every turn" anti-pattern where LLMs are asked
+ * to return JSON on every conversational turn, fighting their natural
+ * conversational behavior.
+ */
+import { buildManifest, createAsyncExecuteWrapperWithContext, createConversationalContextMapper, } from './execute-wrapper.js';
+/**
+ * Generates the system prompt for Phase 1: Gathering
+ */
+export function generateGatheringPrompt(config) {
+    const { tone, factors, customGuidance, priorityFactors } = config;
+    const toneValue = tone ?? 'friendly';
+    // Build factor descriptions
+    const factorDescriptions = factors
+        .map((factor) => {
+        const factorDesc = factor.description ?? factor.name;
+        let desc = `- **${factor.name}**: ${factorDesc}`;
+        if (factor.type === 'enum' && factor.values) {
+            const quotedValues = factor.values.map((v) => `"${v}"`).join(', ');
+            desc += `\n  Valid values: ${quotedValues}`;
+        }
+        if (factor.clarificationHint) {
+            desc += `\n  ${factor.clarificationHint}`;
+        }
+        if (factor.naturalLanguageMappings) {
+            const mappings = Object.entries(factor.naturalLanguageMappings)
+                .map(([phrase, value]) => {
+                const mapping = `"${phrase}" → "${value}"`;
+                return mapping;
+            })
+                .join(', ');
+            desc += `\n  Natural language mappings: ${mappings}`;
+        }
+        if (factor.required) {
+            desc += '\n  (REQUIRED)';
+        }
+        return desc;
+    })
+        .join('\n\n');
+    // Build priority guidance
+    const priorityGuidance = priorityFactors
+        ? `\nPrioritize asking about these factors early: ${priorityFactors.join(', ')}`
+        : '';
+    // Build enum validation rules
+    const enumFactors = factors.filter((f) => f.type === 'enum');
+    let enumGuidance = '';
+    if (enumFactors.length > 0) {
+        const enumRules = enumFactors
+            .map((f) => {
+            const quotedValues = f.values?.map((v) => `"${v}"`).join(', ') ?? '';
+            const fieldName = f.name;
+            return `- **${fieldName}**: ONLY use these exact values: ${quotedValues}
+  - If user mentions a value NOT in this list, DO NOT set ${fieldName} in your response
+  - Instead, ask the user to choose from the valid options
+  - Provide context about which valid option might fit their intent`;
+        })
+            .join('\n');
+        enumGuidance = `\n\nCRITICAL ENUM VALIDATION RULES:\n${enumRules}`;
+    }
+    return `You are a ${toneValue} conversational assistant.
+
+Your task is to gather the following information through natural conversation:
+
+${factorDescriptions}${priorityGuidance}
+
+CONVERSATION GUIDELINES:
+- Ask questions naturally, one topic at a time
+- Extract information from user responses
+- Track what you've learned across conversation turns
+- When the user provides information, acknowledge it and move to the next factor
+- Be patient and adapt to the user's communication style${enumGuidance}
+
+${customGuidance ? `ADDITIONAL GUIDANCE:\n${customGuidance}\n` : ''}
+READINESS INDICATOR:
+- When you have gathered enough information (at minimum, all required factors), acknowledge this to the user
+- Example: "I have enough information now! Ready to see the results?"
+- Wait for user confirmation before proceeding to recommendations`;
+}
+/**
+ * Generates the system prompt for Phase 2: Extraction
+ */
+export function generateExtractionPrompt(config, gatheredProfile) {
+    if (config.customExtractionPrompt) {
+        return config.customExtractionPrompt;
+    }
+    return `You are a data extraction assistant.
+
+Extract and validate the following profile information into structured format:
+
+${JSON.stringify(gatheredProfile, null, 2)}
+
+Return ONLY a valid JSON object matching the expected schema.
+Ensure all values match their expected types and constraints.`;
+}
+/**
+ * Defines a two-phase conversational assistant agent.
+ *
+ * Phase 1 (Gathering): Natural conversation to collect information
+ * - No JSON output required
+ * - Conversational text responses
+ * - Accumulates factors informally
+ *
+ * Phase 2 (Extraction): Structured data extraction
+ * - JSON output with schema validation
+ * - Triggered when readiness check passes
+ * - Uses Structured Outputs API if configured
+ *
+ * @param config - Two-phase configuration
+ * @param handler - Optional custom handler (if you want full control)
+ * @returns Agent with validated execute function and manifest
+ *
+ * @example
+ * ```typescript
+ * const breedAdvisor = defineTwoPhaseConversationalAssistant({
+ *   name: 'breed-advisor',
+ *   description: 'Helps users find their perfect cat breed',
+ *   version: '1.0.0',
+ *   inputSchema: BreedAdvisorInputSchema,
+ *   gatheringPhase: {
+ *     tone: 'enthusiastic',
+ *     factors: [
+ *       {
+ *         name: 'musicPreference',
+ *         description: 'User\'s music taste',
+ *         type: 'enum',
+ *         values: ['classical', 'jazz', 'rock', 'pop'],
+ *         required: true,
+ *         weight: 2,
+ *       },
+ *       {
+ *         name: 'livingSpace',
+ *         type: 'enum',
+ *         values: ['apartment', 'house', 'farm'],
+ *         naturalLanguageMappings: {
+ *           'flat': 'apartment',
+ *           'big house': 'house',
+ *         },
+ *       },
+ *     ],
+ *     readinessCheck: (profile) => Object.keys(profile).length >= 4,
+ *   },
+ *   extractionPhase: {
+ *     outputSchema: BreedRecommendationSchema,
+ *     generateRecommendations: matchBreeds,
+ *   },
+ * });
+ * ```
+ */
+export function defineTwoPhaseConversationalAssistant(config, handler) {
+    // Generate system prompts
+    const gatheringPrompt = generateGatheringPrompt(config.gatheringPhase);
+    // Build manifest
+    const manifest = buildManifest(config, 'two-phase-conversational-assistant', {
+        mockable: config.mockable ?? true,
+        gatheringPhase: {
+            tone: config.gatheringPhase.tone,
+            factorCount: config.gatheringPhase.factors.length,
+            requiredFactors: config.gatheringPhase.factors.filter((f) => f.required).map((f) => f.name),
+            priorityFactors: config.gatheringPhase.priorityFactors,
+        },
+        extractionPhase: {
+            useStructuredOutputs: config.extractionPhase.useStructuredOutputs ?? false,
+        },
+        systemPrompt: {
+            gathering: gatheringPrompt,
+        },
+    });
+    // If custom handler provided, use it
+    if (handler) {
+        const execute = createAsyncExecuteWrapperWithContext(config, handler, createConversationalContextMapper(config.mockable ?? true));
+        return {
+            name: config.name,
+            execute,
+            manifest,
+        };
+    }
+    // Default implementation: Two-phase pattern
+    const defaultHandler = async (_input, ctx) => {
+        // Check if gathering prompt is in history
+        const hasGatheringPrompt = ctx.history.some((msg) => msg.role === 'system' && msg.content.includes(gatheringPrompt));
+        if (!hasGatheringPrompt) {
+            ctx.addToHistory('system', gatheringPrompt);
+        }
+        // Determine current phase from session state or conversation history
+        // This would need access to session state from input
+        // For now, this is a placeholder - actual implementation would handle phase management
+        // Phase 1: Gathering
+        // Phase 2: Extraction
+        throw new Error('Default two-phase handler not yet implemented. ' +
+            'Please provide a custom handler or use the generated prompts manually.');
+    };
+    const execute = createAsyncExecuteWrapperWithContext(config, defaultHandler, createConversationalContextMapper(config.mockable ?? true));
+    return {
+        name: config.name,
+        execute,
+        manifest,
+    };
+}
+//# sourceMappingURL=two-phase-conversational.js.map

package/dist/two-phase-conversational.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-phase-conversational.js","sourceRoot":"","sources":["../src/two-phase-conversational.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EACL,aAAa,EACb,oCAAoC,EACpC,iCAAiC,GAClC,MAAM,sBAAsB,CAAC;AA6H9B;;GAEG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAA4B;IAClE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC;IAClE,MAAM,SAAS,GAAG,IAAI,IAAI,UAAU,CAAC;IAErC,4BAA4B;IAC5B,MAAM,kBAAkB,GAAG,OAAO;SAC/B,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE;QACd,MAAM,UAAU,GAAG,MAAM,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC;QACrD,IAAI,IAAI,GAAG,OAAO,MAAM,CAAC,IAAI,OAAO,UAAU,EAAE,CAAC;QAEjD,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC;YAC5C,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACnE,IAAI,IAAI,qBAAqB,YAAY,EAAE,CAAC;QAC9C,CAAC;QAED,IAAI,MAAM,CAAC,iBAAiB,EAAE,CAAC;YAC7B,IAAI,IAAI,OAAO,MAAM,CAAC,iBAAiB,EAAE,CAAC;QAC5C,CAAC;QAED,IAAI,MAAM,CAAC,uBAAuB,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,uBAAuB,CAAC;iBAC5D,GAAG,CAAC,CAAC,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,EAAE;gBACvB,MAAM,OAAO,GAAG,IAAI,MAAM,QAAQ,KAAK,GAAG,CAAC;gBAC3C,OAAO,OAAO,CAAC;YACjB,CAAC,CAAC;iBACD,IAAI,CAAC,IAAI,CAAC,CAAC;YACd,IAAI,IAAI,kCAAkC,QAAQ,EAAE,CAAC;QACvD,CAAC;QAED,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;YACpB,IAAI,IAAI,gBAAgB,CAAC;QAC3B,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,IAAI,CAAC,MAAM,CAAC,CAAC;IAEhB,0BAA0B;IAC1B,MAAM,gBAAgB,GAAG,eAAe;QACtC,CAAC,CAAC,kDAAkD,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;QAChF,CAAC,CAAC,EAAE,CAAC;IAEP,8BAA8B;IAC9B,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC,CAAC;IAC7D,IAAI,YAAY,GAAG,EAAE,CAAC;IACtB,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3B,MAAM,SAAS,GAAG,WAAW;aAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;YACT,MAAM,YAAY,GAAG,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACrE,MAAM,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC;YACzB,OAAO,OAAO,SAAS,oCAAoC,YAAY;4DACnB,SAAS;;oEAED,CAAC;QAC/D,CAAC,CAAC;aACD,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,YAAY,GAAG,wCAAwC,SAAS,EAAE,CAAC;IACrE,CAAC;IAED,OAAO,aAAa,SAAS;;;;EAI7B,kBAAkB,GAAG,gBAAgB;;;;;;;0DAOmB,YAAY;;EAEpE,cAAc,CAAC,CAAC,CAAC,yBAAyB,cAAc,IAAI,CAAC,CAAC,CAAC,EAAE;;;;kEAID,CAAC;AACnE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,wBAAwB,CACtC,MAA6B,EAC7B,eAAwC;IAExC,IAAI,MAAM,CAAC,sBAAsB,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,sBAAsB,CAAC;IACvC,CAAC;IAED,OAAO;;;;EAIP,IAAI,CAAC,SAAS,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,CAAC;;;8DAGoB,CAAC;AAC/D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,MAAM,UAAU,qCAAqC,CACnD,MAAqD,EACrD,OAAyE;IAEzE,0BAA0B;IAC1B,MAAM,eAAe,GAAG,uBAAuB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAEvE,iBAAiB;IACjB,MAAM,QAAQ,GAAG,aAAa,CAAC,MAAM,EAAE,oCAAoC,EAAE;QAC3E,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,IAAI;QACjC,cAAc,EAAE;YACd,IAAI,EAAE,MAAM,CAAC,cAAc,CAAC,IAAI;YAChC,WAAW,EAAE,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM;YACjD,eAAe,EAAE,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;YAC3F,eAAe,EAAE,MAAM,CAAC,cAAc,CAAC,eAAe;SACvD;QACD,eAAe,EAAE;YACf,oBAAoB,EAAE,MAAM,CAAC,eAAe,CAAC,oBAAoB,IAAI,KAAK;SAC3E;QACD,YAAY,EAAE;YACZ,SAAS,EAAE,eAAe;SAC3B;KACF,CAAC,CAAC;IAEH,qCAAqC;IACrC,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,OAAO,GAAG,oCAAoC,CAClD,MAAM,EACN,OAAO,EACP,iCAAiC,CAAC,MAAM,CAAC,QAAQ,IAAI,IAAI,CAAC,CAC3D,CAAC;QAEF,OAAO;YACL,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,OAAO;YACP,QAAQ;SACT,CAAC;IACJ,CAAC;IAED,4CAA4C;IAC5C,MAAM,cAAc,GAAG,KAAK,EAAE,MAAc,EAAE,GAA0B,EAAoB,EAAE;QAC5F,0CAA0C;QAC1C,MAAM,kBAAkB,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,CACzC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAC,CACxE,CAAC;QAEF,IAAI,CAAC,kBAAkB,EAAE,CAAC;YACxB,GAAG,CAAC,YAAY,CAAC,QAAQ,EAAE,eAAe,CAAC,CAAC;QAC9C,CAAC;QAED,qEAAqE;QACrE,qDAAqD;QACrD,uFAAuF;QAEvF,qBAAqB;QACrB,sBAAsB;QAEtB,MAAM,IAAI,KAAK,CACb,iDAAiD;YAC/C,wEAAwE,CAC3E,CAAC;IACJ,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,oCAAoC,CAClD,MAAM,EACN,cAAc,EACd,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/types.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Core types for the VAT agent runtime framework
+ */
+import type { z } from 'zod';
+/**
+ * Represents an executable agent with a defined input/output contract
+ */
+export interface Agent<TInput, TOutput> {
+    /** Unique name for the agent */
+    name: string;
+    /** Execute the agent with validated input */
+    execute: (input: TInput, ...args: unknown[]) => TOutput | Promise<TOutput>;
+    /** Metadata describing the agent's interface and capabilities */
+    manifest: AgentManifest;
+}
+/**
+ * Base configuration shared by all agent types
+ * Eliminates duplication across archetype config interfaces
+ */
+export interface BaseAgentConfig<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>;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Represents a pure function agent with synchronous execution
+ */
+export interface PureFunctionAgent<TInput, TOutput> extends Agent<TInput, TOutput> {
+    /** Execute the agent synchronously with validated input */
+    execute: (input: TInput) => TOutput;
+}
+/**
+ * Metadata describing an agent's interface and capabilities
+ */
+export interface AgentManifest {
+    /** 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;
+    /** JSON Schema for input validation */
+    inputSchema: Record<string, unknown>;
+    /** JSON Schema for output validation */
+    outputSchema: Record<string, unknown>;
+    /** Agent archetype (e.g., "pure-function", "llm-analyzer") */
+    archetype: string;
+    /** Additional metadata (model, temperature, mockable, etc.) */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Message format for LLM communication
+ */
+export interface Message {
+    /** Message role (system, user, assistant) */
+    role: 'system' | 'user' | 'assistant';
+    /** Message content */
+    content: string;
+}
+/**
+ * Context provided to LLM-based agents
+ */
+export interface LLMAnalyzerContext {
+    /** Whether this agent can be mocked in tests */
+    mockable: boolean;
+    /** LLM model identifier (optional) */
+    model?: string;
+    /** Temperature for LLM generation (0-1, optional) */
+    temperature?: number;
+    /** Function to call the LLM with a prompt or messages */
+    callLLM: (prompt: string | Message[]) => Promise<string>;
+}
+/**
+ * Context provided to conversational assistant agents
+ */
+export interface ConversationalContext {
+    /** Whether this agent can be mocked in tests */
+    mockable: boolean;
+    /** Conversation history */
+    history: Message[];
+    /** Add a message to conversation history */
+    addToHistory: (role: 'system' | 'user' | 'assistant', content: string) => void;
+    /** Function to call the LLM with messages */
+    callLLM: (messages: Message[]) => Promise<string>;
+}
+/**
+ * Context provided to agentic researcher agents
+ */
+export interface ResearcherContext {
+    /** Whether this agent can be mocked in tests */
+    mockable: boolean;
+    /** Available tools for research */
+    tools: Record<string, Function>;
+    /** Function to call the LLM with a prompt */
+    callLLM: (prompt: string) => Promise<string>;
+    /** Function to call a tool by name */
+    callTool: (toolName: string, input: unknown) => Promise<unknown>;
+    /** Current iteration count */
+    iterationCount: number;
+    /** Maximum allowed iterations */
+    maxIterations: number;
+}
+/**
+ * Retry options for function calls
+ */
+export interface RetryOptions {
+    /** Maximum number of retry attempts */
+    maxAttempts?: number;
+    /** Delay between retries in milliseconds */
+    delayMs?: number;
+    /** Backoff multiplier for exponential backoff */
+    backoffMultiplier?: number;
+}
+/**
+ * Context provided to function orchestrator agents
+ */
+export interface OrchestratorContext {
+    /** Call another agent by name */
+    call: <T, R>(agentName: string, input: T) => Promise<R>;
+    /** Execute multiple calls in parallel */
+    parallel: <T>(calls: Array<() => Promise<T>>) => Promise<T[]>;
+    /** Retry a function call with exponential backoff */
+    retry: <T>(fn: () => Promise<T>, options?: RetryOptions) => Promise<T>;
+    /** Shared state for the orchestration */
+    state: Map<string, unknown>;
+}
+/**
+ * Context provided to LLM coordinator agents
+ */
+export interface CoordinatorContext {
+    /** Whether this agent can be mocked in tests */
+    mockable: boolean;
+    /** Call another agent by name */
+    call: <T, R>(agentName: string, input: T) => Promise<R>;
+    /** Function to call the LLM with a prompt */
+    callLLM: (prompt: string) => Promise<string>;
+    /** Route to different paths based on LLM decision */
+    route: (decision: string, routes: Record<string, () => Promise<unknown>>) => Promise<unknown>;
+    /** Shared state for coordination */
+    state: Map<string, unknown>;
+}
+/**
+ * Context provided to function event consumer agents
+ */
+export interface EventConsumerContext {
+    /** Type of the event being consumed */
+    eventType: string;
+    /** Data payload of the event */
+    eventData: unknown;
+    /** Shared state for the consumer */
+    state: Map<string, unknown>;
+    /** Emit a new event */
+    emit: (eventType: string, data: unknown) => Promise<void>;
+}
+/**
+ * Context provided to LLM event handler agents
+ */
+export interface LLMEventHandlerContext {
+    /** Whether this agent can be mocked in tests */
+    mockable: boolean;
+    /** Type of the event being handled */
+    eventType: string;
+    /** Data payload of the event */
+    eventData: unknown;
+    /** Function to call the LLM with a prompt */
+    callLLM: (prompt: string) => Promise<string>;
+    /** Emit a new event */
+    emit: (eventType: string, data: unknown) => Promise<void>;
+    /** Shared state for the handler */
+    state: Map<string, unknown>;
+}
+/**
+ * Context provided to external event integrator agents
+ */
+export interface ExternalEventContext {
+    /** Emit an event to external systems */
+    emit: (eventType: string, data: unknown) => Promise<void>;
+    /** Wait for an external event with timeout */
+    waitFor: <T>(eventType: string, timeoutMs: number) => Promise<T>;
+    /** Timeout in milliseconds (optional) */
+    timeoutMs?: number;
+    /** Action to take on timeout: approve, reject, or error */
+    onTimeout?: 'approve' | 'reject' | 'error';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,5 @@
+/**
+ * Core types for the VAT agent runtime framework
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@vibe-agent-toolkit/agent-runtime",
+  "version": "0.1.2-rc.3",
+  "type": "module",
+  "description": "Runtime framework for building and executing portable AI agents",
+  "keywords": [
+    "agent",
+    "runtime",
+    "ai",
+    "llm",
+    "portable",
+    "toolkit"
+  ],
+  "author": "Jeff Dutton",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./session/test-helpers": {
+      "types": "./dist/session/test-helpers/index.d.ts",
+      "import": "./dist/session/test-helpers/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist *.tsbuildinfo"
+  },
+  "dependencies": {
+    "@vibe-agent-toolkit/agent-schema": "0.1.2-rc.3",
+    "@vibe-agent-toolkit/utils": "0.1.2-rc.3",
+    "zod": "^3.23.8",
+    "zod-to-json-schema": "^3.23.5"
+  },
+  "devDependencies": {
+    "rimraf": "^6.0.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jdutton/vibe-agent-toolkit.git"
+  }
+}