@providerprotocol/agents 0.0.2 → 0.0.3

package/tests/live/checkpoint.test.ts

@@ -1,243 +0,0 @@
-import { describe, test, expect, setDefaultTimeout, beforeEach, afterEach } from 'bun:test';
-import { rm } from 'node:fs/promises';
-import { anthropic } from '@providerprotocol/ai/anthropic';
-import type { Tool } from '@providerprotocol/ai';
-import { agent, AgentState } from '../../src/index.ts';
-import { fileCheckpoints } from '../../src/checkpoint/index.ts';
-import { loop } from '../../src/execution/index.ts';
-
-// Skip tests if no API key
-const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
-
-// Increase timeout for live API tests (60 seconds for multi-step tests)
-setDefaultTimeout(60_000);
-
-const TEST_CHECKPOINT_DIR = '.test-live-checkpoints';
-
-describe.skipIf(!ANTHROPIC_API_KEY)('Checkpointing with Live API', () => {
-  beforeEach(async () => {
-    // Clean up test directory before each test
-    try {
-      await rm(TEST_CHECKPOINT_DIR, { recursive: true, force: true });
-    } catch {
-      // Ignore if doesn't exist
-    }
-  });
-
-  afterEach(async () => {
-    // Clean up test directory after each test
-    try {
-      await rm(TEST_CHECKPOINT_DIR, { recursive: true, force: true });
-    } catch {
-      // Ignore
-    }
-  });
-
-  describe('agent with checkpoints', () => {
-    test('saves checkpoint after step_end', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 100 },
-        checkpoints: store,
-        sessionId: 'test-session-1',
-      });
-
-      const state = AgentState.initial();
-      await a.generate('Say hello.', state);
-
-      // Wait a bit for async checkpoint to complete
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Verify checkpoint was saved
-      const sessions = await store.list();
-      expect(sessions).toContain('test-session-1');
-
-      const saved = await store.load('test-session-1');
-      expect(saved).not.toBeNull();
-      expect(saved?.step).toBeGreaterThan(0);
-    });
-
-    test('auto-generates sessionId when not provided', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 50 },
-        checkpoints: store,
-        // sessionId not provided - should auto-generate
-      });
-
-      await a.generate('Hi', AgentState.initial());
-
-      // Wait for checkpoint
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      const sessions = await store.list();
-      expect(sessions.length).toBe(1);
-      // Should be a UUID
-      expect(sessions[0]).toMatch(/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i);
-    });
-
-    test('streaming also saves checkpoints', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 100 },
-        checkpoints: store,
-        sessionId: 'streaming-session',
-      });
-
-      const stream = a.stream('Say hello.', AgentState.initial());
-
-      // Consume the stream
-      for await (const event of stream) {
-        // Process events (need to consume them)
-        void event;
-      }
-
-      await stream.result;
-
-      // Wait for checkpoint
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      const saved = await store.load('streaming-session');
-      expect(saved).not.toBeNull();
-    });
-  });
-
-  describe('session resume', () => {
-    test('can resume conversation from checkpoint', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      // First agent - establish context
-      const a1 = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 100 },
-        checkpoints: store,
-        sessionId: 'resume-test',
-      });
-
-      // Use ask() to build conversation history properly
-      const result1 = await a1.ask('My favorite number is 42.', AgentState.initial());
-
-      // The checkpoint from generate() doesn't include ask()'s state enrichment,
-      // so we manually save the enriched state for realistic resume behavior
-      await store.save('resume-test', result1.state.toJSON());
-
-      // Verify checkpoint was saved with conversation
-      const saved = await store.load('resume-test');
-      expect(saved).not.toBeNull();
-      expect(saved?.messages.length).toBeGreaterThan(0);
-
-      // Second agent - resume from checkpoint
-      const a2 = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 100 },
-        checkpoints: store,
-        sessionId: 'resume-test',
-      });
-
-      // Restore state from checkpoint (saved is verified non-null above)
-      const restoredState = AgentState.fromJSON(saved as NonNullable<typeof saved>);
-
-      // Continue conversation
-      const result2 = await a2.ask('What is my favorite number?', restoredState);
-
-      expect(result2.turn.response.text).toContain('42');
-    });
-
-    test('checkpoint preserves tool execution results', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      const calculator: Tool = {
-        name: 'calculate',
-        description: 'Perform a calculation',
-        parameters: {
-          type: 'object',
-          properties: {
-            expression: { type: 'string', description: 'Math expression' },
-          },
-          required: ['expression'],
-        },
-        run: async (params: { expression: string }) => {
-          const result = Function(`"use strict"; return (${params.expression})`)();
-          return String(result);
-        },
-      };
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 200 },
-        tools: [calculator],
-        execution: loop(),
-        checkpoints: store,
-        sessionId: 'tool-test',
-      });
-
-      await a.generate(
-        'Calculate 7 * 8 using the calculate tool.',
-        AgentState.initial(),
-      );
-
-      // Wait for checkpoint
-      await new Promise((resolve) => setTimeout(resolve, 100));
-
-      // Load and verify checkpoint has the conversation with tool results
-      const saved = await store.load('tool-test');
-      expect(saved).not.toBeNull();
-      expect(saved?.messages.length).toBeGreaterThan(0);
-
-      // Should have tool result messages
-      const hasToolResult = saved?.messages.some((m) => m.role === 'tool_result');
-      expect(hasToolResult).toBe(true);
-    });
-  });
-
-  describe('checkpoint updates', () => {
-    test('checkpoints update with each step', async () => {
-      const store = fileCheckpoints({ dir: TEST_CHECKPOINT_DIR });
-
-      // Tool that requires multiple steps
-      let callCount = 0;
-      const countingTool: Tool = {
-        name: 'count',
-        description: 'Count calls',
-        parameters: {
-          type: 'object',
-          properties: {},
-        },
-        run: async () => {
-          callCount++;
-          return `Call count: ${callCount}`;
-        },
-      };
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 300 },
-        tools: [countingTool],
-        execution: loop(),
-        checkpoints: store,
-        sessionId: 'multi-step-test',
-      });
-
-      await a.generate(
-        'Call the count tool twice in separate requests. First call it once, then call it again.',
-        AgentState.initial(),
-      );
-
-      // Wait for checkpoints
-      await new Promise((resolve) => setTimeout(resolve, 200));
-
-      // Load final checkpoint
-      const saved = await store.load('multi-step-test');
-      expect(saved).not.toBeNull();
-
-      // Step count should reflect multiple steps
-      expect(saved?.step).toBeGreaterThanOrEqual(1);
-    });
-  });
-});

package/tests/live/execution-strategies.test.ts

@@ -1,255 +0,0 @@
-import { describe, test, expect, setDefaultTimeout } from 'bun:test';
-import { anthropic } from '@providerprotocol/ai/anthropic';
-import type { Tool } from '@providerprotocol/ai';
-import { agent, AgentState } from '../../src/index.ts';
-import { react, loop, orderToolCalls } from '../../src/execution/index.ts';
-import type { ToolWithDependencies } from '../../src/execution/index.ts';
-
-// Skip tests if no API key
-const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
-
-// Increase timeout for live API tests (60 seconds)
-setDefaultTimeout(60_000);
-
-describe.skipIf(!ANTHROPIC_API_KEY)('Execution Strategies (Live)', () => {
-  describe('react() strategy', () => {
-    test('captures reasoning during execution', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 400 },
-        execution: react({ maxSteps: 1 }),
-      });
-
-      const result = await a.generate(
-        'What is 7 multiplied by 8? Think step by step.',
-        AgentState.initial(),
-      );
-
-      // ReAct should capture reasoning
-      expect(result.state.reasoning.length).toBeGreaterThan(0);
-      // Answer should contain 56
-      expect(result.turn.response.text).toContain('56');
-    });
-
-    test('completes with response', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 400 },
-        execution: react({ maxSteps: 1 }),
-      });
-
-      const result = await a.generate(
-        'What is the capital of Japan?',
-        AgentState.initial(),
-      );
-
-      // Should have reasoning
-      expect(result.state.reasoning.length).toBeGreaterThan(0);
-      // Should have a response
-      expect(result.turn.response.text.toLowerCase()).toContain('tokyo');
-    });
-
-    test('streams with UAP reasoning events', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 300 },
-        execution: react({ maxSteps: 1 }),
-      });
-
-      const stream = a.stream('What is the capital of France?', AgentState.initial());
-
-      const uapEvents: Array<{ type: string }> = [];
-
-      for await (const event of stream) {
-        if (event.source === 'uap' && event.uap) {
-          uapEvents.push({ type: event.uap.type });
-        }
-      }
-
-      const result = await stream.result;
-
-      // Should have step_start and reasoning UAP events
-      expect(uapEvents.some((e) => e.type === 'step_start')).toBe(true);
-      expect(uapEvents.some((e) => e.type === 'reasoning')).toBe(true);
-      expect(result.turn.response.text.toLowerCase()).toContain('paris');
-    });
-  });
-
-  describe('tool dependency ordering (unit tests)', () => {
-    // These are pure unit tests for the orderToolCalls utility - no API calls needed
-    test('orderToolCalls groups independent tools together', () => {
-      const toolA: Tool = {
-        name: 'tool_a',
-        description: 'Tool A',
-        parameters: { type: 'object', properties: {} },
-        run: async () => 'a',
-      };
-
-      const toolB: Tool = {
-        name: 'tool_b',
-        description: 'Tool B',
-        parameters: { type: 'object', properties: {} },
-        run: async () => 'b',
-      };
-
-      const calls = [
-        { toolCallId: 'call-1', toolName: 'tool_a', arguments: {} },
-        { toolCallId: 'call-2', toolName: 'tool_b', arguments: {} },
-      ];
-
-      const groups = orderToolCalls(calls, [toolA, toolB]);
-
-      // Should group both in one group (parallel execution)
-      expect(groups.length).toBe(1);
-      expect(groups[0]?.calls.length).toBe(2);
-      expect(groups[0]?.isBarrier).toBe(false);
-    });
-
-    test('orderToolCalls respects dependsOn ordering', () => {
-      const toolRead: ToolWithDependencies = {
-        name: 'read',
-        description: 'Read',
-        parameters: { type: 'object', properties: {} },
-        run: async () => 'read result',
-      };
-
-      const toolWrite: ToolWithDependencies = {
-        name: 'write',
-        description: 'Write',
-        parameters: { type: 'object', properties: {} },
-        dependsOn: ['read'],
-        run: async () => 'write result',
-      };
-
-      const calls = [
-        { toolCallId: 'call-read', toolName: 'read', arguments: {} },
-        { toolCallId: 'call-write', toolName: 'write', arguments: {} },
-      ];
-
-      const groups = orderToolCalls(calls, [toolRead, toolWrite]);
-
-      // Should have 2 groups - read first, then write
-      expect(groups.length).toBe(2);
-
-      const readGroupIndex = groups.findIndex(
-        (g) => g.calls.some((c) => c.toolName === 'read'),
-      );
-      const writeGroupIndex = groups.findIndex(
-        (g) => g.calls.some((c) => c.toolName === 'write'),
-      );
-
-      expect(readGroupIndex).toBeLessThan(writeGroupIndex);
-    });
-
-    test('orderToolCalls creates barrier for sequential tools', () => {
-      const sequentialTool: ToolWithDependencies = {
-        name: 'sequential_tool',
-        description: 'Must run alone',
-        parameters: { type: 'object', properties: {} },
-        sequential: true,
-        run: async () => 'done',
-      };
-
-      const calls = [
-        { toolCallId: 'call-1', toolName: 'sequential_tool', arguments: {} },
-      ];
-
-      const groups = orderToolCalls(calls, [sequentialTool]);
-
-      expect(groups.length).toBe(1);
-      expect(groups[0]?.isBarrier).toBe(true);
-    });
-  });
-
-  describe('stream/generate equivalence', () => {
-    test('stream and generate produce equivalent final states', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 100 },
-        execution: loop(),
-      });
-
-      const input = 'Say exactly: "Test response"';
-      const state = AgentState.initial();
-
-      // Run with generate
-      const generateResult = await a.generate(input, state);
-
-      // Run with stream
-      const stream = a.stream(input, state);
-      for await (const event of stream) {
-        void event; // consume stream
-      }
-      const streamResult = await stream.result;
-
-      // Compare structural equivalence
-      expect(generateResult.state.step).toBe(streamResult.state.step);
-      expect(generateResult.state.messages.length).toBe(streamResult.state.messages.length);
-      // Both should have non-empty responses
-      expect(generateResult.turn.response.text.length).toBeGreaterThan(0);
-      expect(streamResult.turn.response.text.length).toBeGreaterThan(0);
-    });
-
-    test('react() stream and generate capture same reasoning count', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 300 },
-        execution: react({ maxSteps: 1 }),
-      });
-
-      const input = 'What is 5 + 5?';
-      const state = AgentState.initial();
-
-      // Run with generate
-      const generateResult = await a.generate(input, state);
-
-      // Run with stream
-      const stream = a.stream(input, state);
-      for await (const event of stream) {
-        void event; // consume stream
-      }
-      const streamResult = await stream.result;
-
-      // Both should have captured reasoning
-      expect(generateResult.state.reasoning.length).toBe(streamResult.state.reasoning.length);
-      expect(generateResult.state.reasoning.length).toBeGreaterThan(0);
-    });
-  });
-
-  describe('react() with tools', () => {
-    test('uses tools in loop and answers correctly', async () => {
-      const calculator: Tool = {
-        name: 'calculate',
-        description: 'Perform a mathematical calculation. Use this for any math operations.',
-        parameters: {
-          type: 'object',
-          properties: {
-            expression: { type: 'string', description: 'Math expression to evaluate, e.g., "2 + 3"' },
-          },
-          required: ['expression'],
-        },
-        run: async (params: { expression: string }) => {
-          const result = Function(`"use strict"; return (${params.expression})`)();
-          return String(result);
-        },
-      };
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 500 },
-        tools: [calculator],
-        execution: loop(), // Use loop() for simpler tool execution
-      });
-
-      const result = await a.generate(
-        'Use the calculate tool to compute 123 + 456. What is the result?',
-        AgentState.initial(),
-      );
-
-      // Should have tool executions
-      expect(result.turn.toolExecutions.length).toBeGreaterThan(0);
-      // Answer should contain 579
-      expect(result.turn.response.text).toContain('579');
-    });
-  });
-});

package/tests/live/plan-strategy.test.ts

@@ -1,160 +0,0 @@
-import { describe, test, expect, setDefaultTimeout } from 'bun:test';
-import { anthropic } from '@providerprotocol/ai/anthropic';
-import type { Tool } from '@providerprotocol/ai';
-import { agent, AgentState } from '../../src/index.ts';
-import { plan } from '../../src/execution/index.ts';
-
-// Skip tests if no API key
-const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
-
-// Increase timeout for live API tests (90 seconds for plan strategy)
-setDefaultTimeout(90_000);
-
-describe.skipIf(!ANTHROPIC_API_KEY)('Plan Strategy (Live)', () => {
-  describe('basic planning', () => {
-    test('generates and executes a plan', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 800 },
-        execution: plan({ maxPlanSteps: 3 }),
-      });
-
-      const result = await a.generate(
-        'Think about how you would describe the color blue to someone. Create a simple 2-step plan.',
-        AgentState.initial(),
-      );
-
-      // Should have generated a plan
-      expect(result.state.plan).toBeDefined();
-      expect(result.state.plan?.length).toBeGreaterThan(0);
-      // Should have a text response
-      expect(result.turn.response.text.length).toBeGreaterThan(0);
-    });
-
-    test('tracks plan step status', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 600 },
-        execution: plan({ maxPlanSteps: 2 }),
-      });
-
-      const result = await a.generate(
-        'Create a 1-step plan to say hello.',
-        AgentState.initial(),
-      );
-
-      // Plan should have executed
-      expect(result.state.plan).toBeDefined();
-      if (result.state.plan && result.state.plan.length > 0) {
-        // At least one step should have been completed
-        const completedSteps = result.state.plan.filter((s) => s.status === 'completed');
-        expect(completedSteps.length).toBeGreaterThanOrEqual(0);
-      }
-    });
-  });
-
-  describe('plan with tools', () => {
-    test('creates plan that uses tools', async () => {
-      const notepadContents: string[] = [];
-
-      const notepad: Tool = {
-        name: 'notepad',
-        description: 'Write a note to a notepad for later reference. You MUST use this tool to write notes.',
-        parameters: {
-          type: 'object',
-          properties: {
-            note: { type: 'string', description: 'The note to write' },
-          },
-          required: ['note'],
-        },
-        run: async (params: { note: string }) => {
-          notepadContents.push(params.note);
-          return `Note saved: ${params.note}`;
-        },
-      };
-
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 1200 },
-        tools: [notepad],
-        execution: plan({ maxPlanSteps: 2 }),
-        system: `You are a planning assistant. When asked to create a plan, you MUST respond with a valid JSON object.
-Your response MUST be a JSON object with a "steps" array. Each step must have:
-- "id": a unique string identifier
-- "description": what the step does
-- "dependsOn": array of step ids this depends on (empty array if no dependencies)
-- "tool": (optional) the tool to use
-
-Example response format:
-{"steps": [{"id": "step1", "description": "Write hello", "dependsOn": [], "tool": "notepad"}]}
-
-Do NOT include any text before or after the JSON. ONLY output valid JSON.`,
-      });
-
-      const result = await a.generate(
-        'Create a plan with 1 step: write "test" to the notepad. Respond ONLY with JSON.',
-        AgentState.initial(),
-      );
-
-      // Plan should be created (even if execution varies)
-      expect(result.state.plan).toBeDefined();
-      expect(result.state.plan?.length).toBeGreaterThanOrEqual(1);
-    });
-  });
-
-  describe('plan streaming', () => {
-    test('streams plan creation and execution events', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 600 },
-        execution: plan({ maxPlanSteps: 2 }),
-      });
-
-      const stream = a.stream(
-        'Create a simple 1-step plan to greet the user.',
-        AgentState.initial(),
-      );
-
-      const uapEvents: Array<{ type: string; data?: Record<string, unknown> }> = [];
-
-      for await (const event of stream) {
-        if (event.source === 'uap' && event.uap) {
-          uapEvents.push({ type: event.uap.type, data: event.uap.data });
-        }
-      }
-
-      const result = await stream.result;
-
-      // Should have step events
-      expect(uapEvents.some((e) => e.type === 'step_start')).toBe(true);
-
-      // Should have plan_created event
-      const planCreatedEvent = uapEvents.find((e) => e.type === 'plan_created');
-      expect(planCreatedEvent).toBeDefined();
-
-      // Final result should have plan
-      expect(result.state.plan).toBeDefined();
-    });
-  });
-
-  describe('plan respects maxPlanSteps', () => {
-    test('limits plan to maxPlanSteps', async () => {
-      const a = agent({
-        model: anthropic('claude-3-5-haiku-latest'),
-        params: { max_tokens: 800 },
-        execution: plan({ maxPlanSteps: 2 }),
-      });
-
-      const result = await a.generate(
-        'Create a 10-step plan to count from 1 to 10.',
-        AgentState.initial(),
-      );
-
-      // Plan should be limited to maxPlanSteps
-      expect(result.state.plan).toBeDefined();
-      if (result.state.plan) {
-        expect(result.state.plan.length).toBeLessThanOrEqual(2);
-      }
-    });
-  });
-});