@toolpack-sdk/agents 2.0.0-alpha.1

package/dist/testing/index.d.ts

@@ -0,0 +1,389 @@
+import { C as ChannelInterface, d as AgentOutput, A as AgentInput, B as BaseAgentOptions } from '../types-BWoRx1ZE.js';
+import { Chunk, QueryOptions, QueryResult, Knowledge } from '@toolpack-sdk/knowledge';
+import { Toolpack } from 'toolpack-sdk';
+import { B as BaseAgent } from '../base-agent-Cx2kWzLF.js';
+import 'events';
+
+/**
+ * Mock channel for testing agents without external integrations.
+ * Simulates a channel that can receive messages and capture outputs.
+ *
+ * @example
+ * ```ts
+ * const mockChannel = new MockChannel();
+ *
+ * // Simulate an incoming message
+ * await mockChannel.receive({
+ *   message: 'Analyse this week\'s leads',
+ *   intent: 'morning_analysis',
+ *   conversationId: 'test-thread-1',
+ * });
+ *
+ * // Assert what the agent sent back
+ * expect(mockChannel.lastOutput?.output).toContain('leads');
+ * expect(mockChannel.outputs).toHaveLength(1);
+ * ```
+ */
+declare class MockChannel implements ChannelInterface {
+    name: string;
+    isTriggerChannel: boolean;
+    private _handler?;
+    private _outputs;
+    private _inputs;
+    private _listening;
+    /**
+     * All outputs sent to this channel.
+     */
+    get outputs(): AgentOutput[];
+    /**
+     * The most recent output sent to this channel, or undefined if none.
+     */
+    get lastOutput(): AgentOutput | undefined;
+    /**
+     * All inputs received by this channel.
+     */
+    get inputs(): AgentInput[];
+    /**
+     * The most recent input received by this channel, or undefined if none.
+     */
+    get lastInput(): AgentInput | undefined;
+    /**
+     * Number of messages received.
+     */
+    get receivedCount(): number;
+    /**
+     * Number of outputs sent.
+     */
+    get sentCount(): number;
+    /**
+     * Whether the channel is currently "listening".
+     */
+    get isListening(): boolean;
+    /**
+     * Set the message handler. Called by AgentRegistry.
+     */
+    onMessage(handler: (input: AgentInput) => Promise<void>): void;
+    /**
+     * Start listening. Called by AgentRegistry.
+     * For MockChannel, this just sets a flag.
+     */
+    listen(): void;
+    /**
+     * Stop listening.
+     */
+    stop(): void;
+    /**
+     * Send output to this channel.
+     * Captures the output for later assertions.
+     */
+    send(output: AgentOutput): Promise<void>;
+    /**
+     * Normalize an incoming event into AgentInput.
+     */
+    normalize(incoming: unknown): AgentInput;
+    /**
+     * Simulate receiving a message on this channel.
+     * Normalizes the input and invokes the registered handler.
+     *
+     * @param incoming The raw incoming message data
+     * @returns A promise that resolves when the handler completes
+     * @throws If no handler is registered (channel not wired to agent)
+     */
+    receive(incoming: unknown): Promise<void>;
+    /**
+     * Simulate receiving a message with a specific conversation ID.
+     *
+     * @param message The message text
+     * @param conversationId The conversation ID
+     * @param intent Optional intent
+     * @param context Optional context
+     */
+    receiveMessage(message: string, conversationId?: string, intent?: string, context?: Record<string, unknown>): Promise<void>;
+    /**
+     * Clear all captured inputs and outputs.
+     */
+    clear(): void;
+    /**
+     * Assert that an output containing the given text was sent.
+     *
+     * @param text The text to search for
+     * @throws If no matching output is found
+     */
+    assertOutputContains(text: string): void;
+    /**
+     * Assert that the last output matches the expected text.
+     *
+     * @param expected The expected text
+     * @throws If the last output doesn't match
+     */
+    assertLastOutput(expected: string): void;
+}
+
+/**
+ * Options for creating mock knowledge.
+ */
+interface MockKnowledgeOptions {
+    /** Initial chunks to populate the knowledge base */
+    initialChunks?: Array<{
+        content: string;
+        metadata?: Record<string, unknown>;
+    }>;
+    /** Dimensions for the mock embedder (default: 384) */
+    dimensions?: number;
+    /** Description for the knowledge tool */
+    description?: string;
+}
+/**
+ * Creates an in-memory mock Knowledge instance for testing.
+ * No embedder, no provider needed — everything is in-memory.
+ *
+ * @example
+ * ```ts
+ * const knowledge = await createMockKnowledge({
+ *   initialChunks: [
+ *     { content: 'Lead: Acme Corp, score: 85', metadata: { source: 'crm' } },
+ *   ],
+ * });
+ *
+ * // Use with SDK
+ * const toolpack = await Toolpack.init({
+ *   provider: 'openai',
+ *   knowledge, // Available to all agents
+ * });
+ * ```
+ */
+declare function createMockKnowledge(options?: MockKnowledgeOptions): Promise<Knowledge>;
+/**
+ * Synchronous version of createMockKnowledge for simple test cases.
+ * Returns a mock knowledge-like object that's not a full Knowledge instance
+ * but implements the key methods needed for testing.
+ *
+ * This is useful when you don't want to deal with async setup in tests.
+ */
+declare function createMockKnowledgeSync(options?: MockKnowledgeOptions): MockKnowledge;
+/**
+ * A simplified mock Knowledge for synchronous test setup.
+ * Implements the key methods that agents use: query() and add()
+ */
+declare class MockKnowledge {
+    private chunks;
+    private generateVector;
+    private _description;
+    constructor(initialChunks: Chunk[] | undefined, generateVector: (text: string) => number[], description?: string);
+    /**
+     * Query the mock knowledge base using simple keyword matching.
+     * This doesn't do real semantic search but is sufficient for most tests.
+     */
+    query(text: string, options?: QueryOptions): Promise<QueryResult[]>;
+    /**
+     * Add content to the mock knowledge base.
+     */
+    add(content: string, metadata?: Record<string, unknown>): Promise<string>;
+    /**
+     * Get all chunks in the knowledge base.
+     */
+    getAllChunks(): Chunk[];
+    /**
+     * Clear all chunks.
+     */
+    clear(): void;
+    /**
+     * Convert to a tool format for use with agents.
+     */
+    toTool(): {
+        name: string;
+        displayName: string;
+        description: string;
+        category: string;
+        cacheable: boolean;
+        parameters: {
+            type: string;
+            properties: Record<string, unknown>;
+            required: string[];
+        };
+        execute: (params: {
+            query: string;
+            limit?: number;
+            threshold?: number;
+            filter?: Record<string, unknown>;
+        }) => Promise<Array<{
+            content: string;
+            score: number;
+            metadata: Record<string, unknown>;
+        }>>;
+    };
+}
+
+/**
+ * Configuration for mock responses in createTestAgent.
+ */
+interface MockResponse {
+    /** String or regex to match against the message */
+    trigger: string | RegExp;
+    /** The response to return when triggered */
+    response: string;
+    /** Optional usage metadata */
+    usage?: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+}
+/**
+ * Options for createTestAgent.
+ */
+interface CreateTestAgentOptions {
+    /** Mock responses for the toolpack.generate() call */
+    mockResponses?: MockResponse[];
+    /** Default response when no trigger matches */
+    defaultResponse?: string;
+    /** Provider name for the mock toolpack */
+    provider?: string;
+    /** Model name for the mock toolpack */
+    model?: string;
+}
+/**
+ * Result from createTestAgent.
+ */
+interface TestAgentResult<TAgent extends BaseAgent> {
+    /** The agent instance */
+    agent: TAgent;
+    /** The mock channel wired to the agent */
+    channel: MockChannel;
+    /** The mock toolpack instance */
+    toolpack: Toolpack;
+    /** Helper to add more mock responses */
+    addMockResponse: (response: MockResponse) => void;
+}
+/**
+ * Creates an agent instance wired to a mock channel and mock toolpack.
+ * Perfect for unit testing agents in isolation.
+ *
+ * @example
+ * ```ts
+ * const { agent, channel, toolpack } = createTestAgent(CustomerSupportAgent, {
+ *   mockResponses: [
+ *     { trigger: 'refund', response: 'Refund processed successfully.' },
+ *   ],
+ * });
+ *
+ * const result = await agent.invokeAgent({
+ *   intent: 'refund_request',
+ *   message: 'I want a refund for order #123',
+ * });
+ *
+ * expect(result.output).toBe('Refund processed successfully.');
+ * ```
+ *
+ * @param AgentClass The agent class to instantiate
+ * @param options Configuration options
+ * @returns Test agent setup with agent, channel, and mock toolpack
+ */
+declare function createTestAgent<TAgent extends BaseAgent>(AgentClass: new (options: BaseAgentOptions) => TAgent, options?: CreateTestAgentOptions): TestAgentResult<TAgent>;
+/**
+ * Creates a minimal mock Toolpack for simple test cases.
+ * Returns the same response for all generate() calls.
+ *
+ * @example
+ * ```ts
+ * const toolpack = createMockToolpackSimple('Hello!');
+ * const agent = new MyAgent(toolpack);
+ * const result = await agent.run('Hi');
+ * expect(result.output).toBe('Hello!');
+ * ```
+ */
+declare function createMockToolpackSimple(response?: string): Toolpack;
+/**
+ * Creates a mock Toolpack that returns different responses based on a sequence.
+ * Useful for testing multi-turn conversations or stateful interactions.
+ *
+ * @example
+ * ```ts
+ * const toolpack = createMockToolpackSequence([
+ *   'First response',
+ *   'Second response',
+ *   'Third response',
+ * ]);
+ *
+ * // First call returns 'First response', second call 'Second response', etc.
+ * ```
+ */
+declare function createMockToolpackSequence(responses: string[]): Toolpack;
+
+type AgentEventName = 'agent:start' | 'agent:complete' | 'agent:error';
+interface CapturedEvent {
+    name: AgentEventName;
+    data: any;
+    timestamp: number;
+}
+interface EventCapture {
+    /** All captured events */
+    events: CapturedEvent[];
+    /** Number of events captured */
+    count: number;
+    /** Clear all captured events */
+    clear(): void;
+    /** Stop capturing events and remove listeners */
+    stop(): void;
+    /** Check if an event with the given name was captured */
+    hasEvent(name: AgentEventName): boolean;
+    /** Get all events with the given name */
+    getEvents(name: AgentEventName): CapturedEvent[];
+    /** Get the first event with the given name, or undefined if none */
+    getFirstEvent(name: AgentEventName): CapturedEvent | undefined;
+    /** Get the last event with the given name, or undefined if none */
+    getLastEvent(name: AgentEventName): CapturedEvent | undefined;
+    /** Assert that an event was captured (throws if not) */
+    assertEvent(name: AgentEventName): void;
+    /** Assert that an event was NOT captured (throws if it was) */
+    assertNoEvent(name: AgentEventName): void;
+}
+/**
+ * Captures events emitted by a BaseAgent during testing.
+ * Useful for asserting that certain lifecycle events were fired.
+ *
+ * @example
+ * ```ts
+ * const { agent } = createTestAgent(MyAgent);
+ * const events = captureEvents(agent);
+ *
+ * await agent.invokeAgent({ message: 'Do something' });
+ *
+ * expect(events.hasEvent('agent:start')).toBe(true);
+ * expect(events.hasEvent('agent:complete')).toBe(true);
+ * expect(events.hasEvent('agent:error')).toBe(false);
+ *
+ * // Or use assertion helpers
+ * events.assertEvent('agent:start');
+ * events.assertEvent('agent:complete');
+ * events.assertNoEvent('agent:error');
+ * ```
+ *
+ * @param agent The agent to capture events from
+ * @returns Event capture object with assertion helpers
+ */
+declare function captureEvents(agent: BaseAgent): EventCapture;
+/**
+ * Custom Vitest/Jest matcher for asserting captured events.
+ * Add this to your test setup for more readable assertions.
+ *
+ * @example
+ * ```ts
+ * // In your test setup file
+ * import { expect } from 'vitest';
+ * import { registerEventMatchers } from '@toolpack-sdk/agents/testing';
+ * registerEventMatchers(expect);
+ *
+ * // In your tests
+ * expect(events).toContainEvent('agent:start');
+ * expect(events).not.toContainEvent('agent:error');
+ * ```
+ */
+declare function registerEventMatchers(expect: {
+    extend: (matchers: Record<string, (...args: unknown[]) => {
+        message: () => string;
+        pass: boolean;
+    }>) => void;
+}): void;
+
+export { type AgentEventName, type CapturedEvent, type CreateTestAgentOptions, type EventCapture, MockChannel, MockKnowledge, type MockKnowledgeOptions, type MockResponse, type TestAgentResult, captureEvents, createMockKnowledge, createMockKnowledgeSync, createMockToolpackSequence, createMockToolpackSimple, createTestAgent, registerEventMatchers };

package/dist/testing/index.js

@@ -0,0 +1,3 @@
+var p=class{name="mock-channel";isTriggerChannel=!1;_handler;_outputs=[];_inputs=[];_listening=!1;get outputs(){return[...this._outputs]}get lastOutput(){return this._outputs[this._outputs.length-1]}get inputs(){return[...this._inputs]}get lastInput(){return this._inputs[this._inputs.length-1]}get receivedCount(){return this._inputs.length}get sentCount(){return this._outputs.length}get isListening(){return this._listening}onMessage(e){this._handler=e}listen(){this._listening=!0}stop(){this._listening=!1}async send(e){this._outputs.push(e)}normalize(e){let t=e;return{intent:t.intent,message:t.message,data:t.data,context:t.context||{},conversationId:t.conversationId||"test-conversation-1"}}async receive(e){if(!this._handler)throw new Error("MockChannel: no message handler registered. Call onMessage() first or ensure channel is registered with AgentRegistry.");let t=this.normalize(e);this._inputs.push(t),await this._handler(t)}async receiveMessage(e,t="test-conversation-1",o,i){await this.receive({message:e,conversationId:t,intent:o,context:i})}clear(){this._inputs=[],this._outputs=[]}assertOutputContains(e){if(!this._outputs.some(o=>o.output.includes(e)))throw new Error(`MockChannel: no output containing "${e}" found. Outputs: ${JSON.stringify(this._outputs.map(o=>o.output))}`)}assertLastOutput(e){let t=this.lastOutput;if(!t)throw new Error(`MockChannel: no output sent. Expected: "${e}"`);if(t.output!==e)throw new Error(`MockChannel: last output mismatch.
+Expected: "${e}"
+Actual: "${t.output}"`)}};async function v(c={}){let{Knowledge:e}=await import("@toolpack-sdk/knowledge"),{MemoryProvider:t}=await import("@toolpack-sdk/knowledge"),o=c.dimensions??384,i={dimensions:o,async embed(s){let r=[],u=0;for(let a=0;a<s.length;a++)u=(u+s.charCodeAt(a))%1e3;for(let a=0;a<o;a++){let d=Math.sin(u*(a+1))*.5+.5;r.push(d)}return r},async embedBatch(s){return Promise.all(s.map(r=>this.embed(r)))}},n=new t;if(await n.validateDimensions(o),c.initialChunks&&c.initialChunks.length>0){let s=[];for(let r of c.initialChunks){let u=await i.embed(r.content);s.push({id:`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`,content:r.content,metadata:r.metadata||{},vector:u})}await n.add(s)}return e.create({provider:n,embedder:i,sources:[],description:c.description??"Mock knowledge base for testing",reSync:!1})}function h(c={}){let e=c.dimensions??384,t=[],o=i=>{let n=[],s=0;for(let r=0;r<i.length;r++)s=(s+i.charCodeAt(r))%1e3;for(let r=0;r<e;r++){let u=Math.sin(s*(r+1))*.5+.5;n.push(u)}return n};if(c.initialChunks)for(let i of c.initialChunks)t.push({id:`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`,content:i.content,metadata:i.metadata||{},vector:o(i.content)});return new m(t,o,c.description)}var m=class{chunks;generateVector;_description;constructor(e=[],t,o="Mock knowledge base"){this.chunks=[...e],this.generateVector=t,this._description=o}async query(e,t){let o=t?.limit??10,i=t?.filter,n=e.toLowerCase().split(/\s+/);return this.chunks.filter(r=>{if(i){for(let[u,a]of Object.entries(i))if(r.metadata[u]!==a)return!1}return!0}).map(r=>{let u=r.content.toLowerCase(),a=0;for(let d of n)u.includes(d)&&(a+=.3,new RegExp(`\\b${d}\\b`).test(u)&&(a+=.2));return a=Math.min(a,1),{chunk:{id:r.id,content:r.content,metadata:t?.includeMetadata===!1?{}:r.metadata,vector:t?.includeVectors?r.vector:void 0},score:a,distance:1-a}}).filter(r=>r.score>0).sort((r,u)=>u.score-r.score).slice(0,o)}async add(e,t){let o=`mock-${Date.now()}-${Math.random().toString(36).slice(2)}`;return this.chunks.push({id:o,content:e,metadata:t||{},vector:this.generateVector(e)}),o}getAllChunks(){return[...this.chunks]}clear(){this.chunks=[]}toTool(){return{name:"knowledge_search",displayName:"Knowledge Search",description:this._description,category:"search",cacheable:!1,parameters:{type:"object",properties:{query:{type:"string",description:"Search query to find relevant information"},limit:{type:"number",description:"Maximum number of results to return (default: 10)"},threshold:{type:"number",description:"Minimum similarity threshold 0-1 (default: 0.7)"},filter:{type:"object",description:"Optional metadata filters"}},required:["query"]},execute:async e=>(await this.query(e.query,{limit:e.limit,filter:e.filter})).map(o=>({content:o.chunk.content,score:o.score,metadata:o.chunk.metadata}))}}};function k(c,e={}){let t=[...e.mockResponses??[]],o=e.defaultResponse??"Mock AI response",i=f(t,o,e.provider,e.model),n=new c({toolpack:i}),s=new p;return s.onMessage(async u=>{n._triggeringChannel=s.name,n._conversationId=u.conversationId,n._isTriggerChannel=!1;let a=await n.invokeAgent(u);await s.send({output:a.output,metadata:a.metadata})}),s.listen(),{agent:n,channel:s,toolpack:i,addMockResponse:u=>{t.push(u)}}}function f(c,e,t="openai",o){return{generate:async(i,n)=>{let u=i.messages.filter(a=>a.role==="user").pop()?.content??"";for(let a of c)if(typeof a.trigger=="string"){if(u.toLowerCase().includes(a.trigger.toLowerCase()))return{content:a.response,usage:a.usage??{prompt_tokens:10,completion_tokens:5,total_tokens:15}}}else if(a.trigger instanceof RegExp&&a.trigger.test(u))return{content:a.response,usage:a.usage??{prompt_tokens:10,completion_tokens:5,total_tokens:15}};return{content:e,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}},setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{},get provider(){return t},get model(){return o||"gpt-4"}}}function w(c="Mock AI response"){return{generate:async()=>({content:c,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}),setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{}}}function E(c){let e=0;return{generate:async()=>{let t=c[e]??"No more mock responses";return e++,{content:t,usage:{prompt_tokens:10,completion_tokens:5,total_tokens:15}}},setMode:()=>{},registerMode:()=>{},setProvider:()=>{},setModel:()=>{}}}function A(c){let e=[],t=[],o=n=>s=>{e.push({name:n,data:s,timestamp:Date.now()})},i=["agent:start","agent:complete","agent:error"];for(let n of i){let s=o(n);c.on(n,s),t.push({event:n,handler:s})}return{get events(){return[...e]},get count(){return e.length},clear(){e.length=0},stop(){for(let{event:n,handler:s}of t)c.off(n,s);t.length=0},hasEvent(n){return e.some(s=>s.name===n)},getEvents(n){return e.filter(s=>s.name===n)},getFirstEvent(n){return e.find(s=>s.name===n)},getLastEvent(n){let s=e.filter(r=>r.name===n);return s[s.length-1]},assertEvent(n){if(!this.hasEvent(n)){let s=e.map(r=>r.name).join(", ")||"(none)";throw new Error(`captureEvents: expected event "${n}" was not captured. Captured events: ${s}`)}},assertNoEvent(n){if(this.hasEvent(n)){let s=e.filter(r=>r.name===n).length;throw new Error(`captureEvents: unexpected event "${n}" was captured ${s} time(s)`)}}}}function M(c){c.extend({toContainEvent(...e){let t=e[0],o=e[1],i=t.hasEvent(o);return{message:()=>i?`expected events to NOT contain "${o}"`:`expected events to contain "${o}". Captured events: ${t.events.map(n=>n.name).join(", ")||"(none)"}`,pass:i}},toContainEventTimes(...e){let t=e[0],o=e[1],i=e[2],n=t.getEvents(o).length,s=n===i;return{message:()=>s?`expected event "${o}" to NOT be captured ${i} time(s), but it was`:`expected event "${o}" to be captured ${i} time(s), but it was captured ${n} time(s)`,pass:s}}})}export{p as MockChannel,m as MockKnowledge,A as captureEvents,v as createMockKnowledge,h as createMockKnowledgeSync,E as createMockToolpackSequence,w as createMockToolpackSimple,k as createTestAgent,M as registerEventMatchers};