@providerprotocol/agents 0.0.1

package/tests/unit/checkpoint.test.ts

@@ -0,0 +1,232 @@
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test';
+import { rm, mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { UserMessage, AssistantMessage } from '@providerprotocol/ai';
+import { fileCheckpoints } from '../../src/checkpoint/file.ts';
+import { AgentState } from '../../src/state/index.ts';
+import type { CheckpointStore } from '../../src/checkpoint/types.ts';
+
+const TEST_DIR = '.test-checkpoints';
+
+describe('fileCheckpoints()', () => {
+  let store: CheckpointStore;
+
+  beforeEach(async () => {
+    // Clean up test directory before each test
+    try {
+      await rm(TEST_DIR, { recursive: true, force: true });
+    } catch {
+      // Ignore if doesn't exist
+    }
+    store = fileCheckpoints({ dir: TEST_DIR });
+  });
+
+  afterEach(async () => {
+    // Clean up test directory after each test
+    try {
+      await rm(TEST_DIR, { recursive: true, force: true });
+    } catch {
+      // Ignore
+    }
+  });
+
+  describe('save()', () => {
+    test('saves state to disk', async () => {
+      const state = AgentState.initial()
+        .withMessage(new UserMessage('Hello'))
+        .withStep(1);
+
+      await store.save('session-1', state.toJSON());
+
+      // Verify file exists
+      const file = Bun.file(join(TEST_DIR, 'session-1', 'checkpoint.json'));
+      expect(await file.exists()).toBe(true);
+    });
+
+    test('saves metadata alongside state', async () => {
+      const state = AgentState.initial().withStep(5);
+
+      await store.save('session-1', state.toJSON());
+
+      // Verify metadata file exists
+      const file = Bun.file(join(TEST_DIR, 'session-1', 'metadata.json'));
+      expect(await file.exists()).toBe(true);
+
+      const metadata = await file.json();
+      expect(metadata.sessionId).toBe('session-1');
+      expect(metadata.step).toBe(5);
+      expect(metadata.timestamp).toBeDefined();
+    });
+
+    test('creates directory if it does not exist', async () => {
+      const state = AgentState.initial();
+
+      await store.save('new-session', state.toJSON());
+
+      const loaded = await store.load('new-session');
+      expect(loaded).not.toBeNull();
+    });
+
+    test('overwrites existing checkpoint', async () => {
+      const state1 = AgentState.initial().withStep(1);
+      const state2 = AgentState.initial().withStep(2);
+
+      await store.save('session-1', state1.toJSON());
+      await store.save('session-1', state2.toJSON());
+
+      const loaded = await store.load('session-1');
+      expect(loaded?.step).toBe(2);
+    });
+  });
+
+  describe('load()', () => {
+    test('loads saved state', async () => {
+      const original = AgentState.initial()
+        .withMessage(new UserMessage('Hello'))
+        .withMessage(new AssistantMessage('Hi there!'))
+        .withStep(3)
+        .withMetadata('key', 'value');
+
+      await store.save('session-1', original.toJSON());
+
+      const loaded = await store.load('session-1');
+
+      expect(loaded).not.toBeNull();
+      expect(loaded?.id).toBe(original.id);
+      expect(loaded?.step).toBe(3);
+      expect(loaded?.metadata).toEqual({ key: 'value' });
+      expect(loaded?.messages).toHaveLength(2);
+    });
+
+    test('returns null for non-existent session', async () => {
+      const loaded = await store.load('non-existent');
+      expect(loaded).toBeNull();
+    });
+
+    test('returns null for corrupt file', async () => {
+      // Create corrupt checkpoint file
+      const sessionDir = join(TEST_DIR, 'corrupt-session');
+      await mkdir(sessionDir, { recursive: true });
+      await Bun.write(join(sessionDir, 'checkpoint.json'), 'not valid json');
+
+      const loaded = await store.load('corrupt-session');
+      expect(loaded).toBeNull();
+    });
+  });
+
+  describe('delete()', () => {
+    test('removes session directory', async () => {
+      const state = AgentState.initial();
+      await store.save('session-to-delete', state.toJSON());
+
+      // Verify exists
+      expect(await store.load('session-to-delete')).not.toBeNull();
+
+      await store.delete('session-to-delete');
+
+      // Verify deleted
+      expect(await store.load('session-to-delete')).toBeNull();
+    });
+
+    test('does not throw for non-existent session', async () => {
+      // Should not throw
+      await store.delete('non-existent-session');
+    });
+  });
+
+  describe('list()', () => {
+    test('returns empty array when no sessions', async () => {
+      const sessions = await store.list();
+      expect(sessions).toEqual([]);
+    });
+
+    test('returns all session IDs', async () => {
+      const state = AgentState.initial();
+
+      await store.save('session-a', state.toJSON());
+      await store.save('session-b', state.toJSON());
+      await store.save('session-c', state.toJSON());
+
+      const sessions = await store.list();
+
+      expect(sessions).toHaveLength(3);
+      expect(sessions).toContain('session-a');
+      expect(sessions).toContain('session-b');
+      expect(sessions).toContain('session-c');
+    });
+
+    test('does not include deleted sessions', async () => {
+      const state = AgentState.initial();
+
+      await store.save('keep', state.toJSON());
+      await store.save('delete-me', state.toJSON());
+      await store.delete('delete-me');
+
+      const sessions = await store.list();
+
+      expect(sessions).toEqual(['keep']);
+    });
+  });
+
+  describe('round-trip', () => {
+    test('preserves full state through save/load cycle', async () => {
+      const original = AgentState.initial()
+        .withMessage(new UserMessage('User message'))
+        .withMessage(new AssistantMessage('Assistant response'))
+        .withStep(10)
+        .withMetadata('count', 42)
+        .withMetadata('enabled', true)
+        .withReasoning('First reasoning')
+        .withReasoning('Second reasoning')
+        .withPlan([
+          { id: '1', description: 'Step 1', dependsOn: [], status: 'completed' },
+          { id: '2', description: 'Step 2', dependsOn: ['1'], status: 'pending' },
+        ]);
+
+      await store.save('full-state', original.toJSON());
+      const loaded = await store.load('full-state');
+
+      expect(loaded).not.toBeNull();
+
+      // Verify can restore to AgentState (loaded is verified non-null above)
+      const restored = AgentState.fromJSON(loaded as NonNullable<typeof loaded>);
+
+      expect(restored.id).toBe(original.id);
+      expect(restored.step).toBe(original.step);
+      expect(restored.messages.length).toBe(original.messages.length);
+      expect(restored.metadata).toEqual(original.metadata);
+      expect([...restored.reasoning]).toEqual([...original.reasoning]);
+      expect(restored.plan?.length).toBe(original.plan?.length);
+    });
+  });
+});
+
+describe('CheckpointStore interface', () => {
+  test('default directory is .checkpoints', () => {
+    // This is a documentation/contract test
+    const store = fileCheckpoints();
+    // We can't easily verify the directory without saving,
+    // but we can verify the store is created
+    expect(store).toBeDefined();
+    expect(store.save).toBeDefined();
+    expect(store.load).toBeDefined();
+    expect(store.delete).toBeDefined();
+    expect(store.list).toBeDefined();
+  });
+
+  test('custom directory is respected', async () => {
+    const customDir = '.custom-checkpoint-dir';
+    const store = fileCheckpoints({ dir: customDir });
+
+    try {
+      const state = AgentState.initial();
+      await store.save('test', state.toJSON());
+
+      // Verify file is in custom directory
+      const file = Bun.file(join(customDir, 'test', 'checkpoint.json'));
+      expect(await file.exists()).toBe(true);
+    } finally {
+      await rm(customDir, { recursive: true, force: true });
+    }
+  });
+});

package/tests/unit/execution/equivalence.test.ts

@@ -0,0 +1,402 @@
+/**
+ * Stream/Generate Equivalence Tests
+ *
+ * UAP-1.0 Spec Section 11.4 states:
+ * > The `state` returned by `stream.result` MUST include the complete execution history...
+ * > The returned state MUST be identical to what `generate()` would return for the same execution.
+ *
+ * These tests verify that stream() and generate() produce structurally equivalent final states.
+ */
+import { describe, test, expect } from 'bun:test';
+import { UserMessage, AssistantMessage } from '@providerprotocol/ai';
+import type { Turn, LLMInstance, ToolCall, ToolExecution } from '@providerprotocol/ai';
+import { loop } from '../../../src/execution/loop.ts';
+import { react } from '../../../src/execution/react.ts';
+import { AgentState } from '../../../src/state/index.ts';
+import type { ExecutionContext } from '../../../src/execution/types.ts';
+
+// Deterministic mock Turn factory
+function createMockTurn(options: {
+  text?: string;
+  toolCalls?: ToolCall[];
+  toolExecutions?: ToolExecution[];
+}): Turn {
+  const response = new AssistantMessage(options.text ?? 'Response', options.toolCalls);
+  return {
+    response,
+    messages: [response],
+    toolExecutions: options.toolExecutions ?? [],
+    usage: {
+      inputTokens: 10,
+      outputTokens: 20,
+      totalTokens: 30,
+    },
+    cycles: 1,
+  } as unknown as Turn;
+}
+
+// Mock LLM that returns consistent results for both generate and stream
+function createDeterministicLLM(turns: Turn[]): () => LLMInstance {
+  return () => {
+    let callIndex = 0;
+
+    return {
+      generate: async () => {
+        const turn = turns[callIndex] ?? turns[turns.length - 1];
+        callIndex++;
+        return turn;
+      },
+      stream: () => {
+        const turn = turns[callIndex] ?? turns[turns.length - 1];
+        callIndex++;
+
+        const events: Array<{ type: string; delta?: { text?: string } }> = [];
+        if (turn) {
+          events.push({ type: 'text_delta', delta: { text: turn.response.text } });
+          events.push({ type: 'message_stop' });
+        }
+
+        return {
+          async *[Symbol.asyncIterator]() {
+            for (const event of events) {
+              yield event;
+            }
+          },
+          turn: Promise.resolve(turn),
+        };
+      },
+    } as unknown as LLMInstance;
+  };
+}
+
+/**
+ * Compare two states for structural equivalence.
+ * We don't compare IDs since those are unique per state instance.
+ */
+function statesAreEquivalent(a: AgentState, b: AgentState): boolean {
+  // Compare step
+  if (a.step !== b.step) {
+    return false;
+  }
+
+  // Compare message count
+  if (a.messages.length !== b.messages.length) {
+    return false;
+  }
+
+  // Compare reasoning count
+  if (a.reasoning.length !== b.reasoning.length) {
+    return false;
+  }
+
+  // Compare reasoning content
+  for (let i = 0; i < a.reasoning.length; i++) {
+    if (a.reasoning[i] !== b.reasoning[i]) {
+      return false;
+    }
+  }
+
+  // Compare plan presence
+  if ((a.plan === undefined) !== (b.plan === undefined)) {
+    return false;
+  }
+
+  // Compare plan length if present
+  if (a.plan && b.plan && a.plan.length !== b.plan.length) {
+    return false;
+  }
+
+  return true;
+}
+
+describe('Stream/Generate Equivalence (Section 11.4)', () => {
+  describe('loop() strategy', () => {
+    test('stream() and generate() produce equivalent states for simple case', async () => {
+      const mockTurn = createMockTurn({ text: 'Simple response' });
+      const createLLM = createDeterministicLLM([mockTurn]);
+
+      const strategy = loop();
+      const input = new UserMessage('Hello');
+      const initialState = AgentState.initial();
+
+      // Execute with generate()
+      const generateContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const generateResult = await strategy.execute(generateContext);
+
+      // Execute with stream()
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const streamResult = strategy.stream(streamContext);
+
+      // Consume the stream
+      for await (const event of streamResult) {
+        // Consume events (required to complete stream)
+        void event;
+      }
+      const streamFinalResult = await streamResult.result;
+
+      // Compare states
+      expect(statesAreEquivalent(generateResult.state, streamFinalResult.state)).toBe(true);
+      expect(generateResult.state.step).toBe(streamFinalResult.state.step);
+      expect(generateResult.state.messages.length).toBe(streamFinalResult.state.messages.length);
+    });
+
+    test('stream() and generate() produce equivalent states with tool calls', async () => {
+      const toolCall: ToolCall = {
+        toolCallId: 'call-1',
+        toolName: 'test_tool',
+        arguments: {},
+      };
+
+      const turn1 = createMockTurn({
+        text: 'Using tool',
+        toolCalls: [toolCall],
+        toolExecutions: [{
+          toolCallId: 'call-1',
+          toolName: 'test_tool',
+          arguments: {},
+          result: 'ok',
+          duration: 10,
+          isError: false,
+        }],
+      });
+      const turn2 = createMockTurn({ text: 'Done' });
+
+      const createLLM = createDeterministicLLM([turn1, turn2]);
+      const strategy = loop();
+      const input = new UserMessage('Do something');
+      const initialState = AgentState.initial();
+
+      // Execute with generate()
+      const generateContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const generateResult = await strategy.execute(generateContext);
+
+      // Execute with stream()
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const streamResult = strategy.stream(streamContext);
+
+      for await (const event of streamResult) {
+        void event;
+      }
+      const streamFinalResult = await streamResult.result;
+
+      // Compare states
+      expect(statesAreEquivalent(generateResult.state, streamFinalResult.state)).toBe(true);
+    });
+  });
+
+  describe('react() strategy', () => {
+    test('stream() and generate() produce equivalent states', async () => {
+      const reasoningTurn = createMockTurn({ text: 'Thinking about this...' });
+      const actionTurn = createMockTurn({ text: 'Here is my answer.' });
+
+      const createLLM = createDeterministicLLM([reasoningTurn, actionTurn]);
+      const strategy = react();
+      const input = new UserMessage('Question');
+      const initialState = AgentState.initial();
+
+      // Execute with generate()
+      const generateContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const generateResult = await strategy.execute(generateContext);
+
+      // Execute with stream()
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const streamResult = strategy.stream(streamContext);
+
+      for await (const event of streamResult) {
+        void event;
+      }
+      const streamFinalResult = await streamResult.result;
+
+      // Compare states
+      expect(statesAreEquivalent(generateResult.state, streamFinalResult.state)).toBe(true);
+
+      // Reasoning should be captured in both
+      expect(generateResult.state.reasoning.length).toBe(streamFinalResult.state.reasoning.length);
+    });
+
+    test('stream() and generate() capture same reasoning content', async () => {
+      const reasoningText = 'Step by step reasoning process';
+      const reasoningTurn = createMockTurn({ text: reasoningText });
+      const actionTurn = createMockTurn({ text: 'Final answer.' });
+
+      const createLLM = createDeterministicLLM([reasoningTurn, actionTurn]);
+      const strategy = react();
+      const input = new UserMessage('Think');
+      const initialState = AgentState.initial();
+
+      // Execute with generate()
+      const generateContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const generateResult = await strategy.execute(generateContext);
+
+      // Execute with stream()
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+      const streamResult = strategy.stream(streamContext);
+
+      for await (const event of streamResult) {
+        void event;
+      }
+      const streamFinalResult = await streamResult.result;
+
+      // Both should have captured the reasoning
+      expect(generateResult.state.reasoning[0]).toBe(reasoningText);
+      expect(streamFinalResult.state.reasoning[0]).toBe(reasoningText);
+    });
+  });
+
+  describe('state completeness', () => {
+    test('stream result includes all messages from execution', async () => {
+      const toolCall: ToolCall = {
+        toolCallId: 'call-1',
+        toolName: 'test_tool',
+        arguments: {},
+      };
+
+      const turns = [
+        createMockTurn({
+          text: 'First',
+          toolCalls: [toolCall],
+          toolExecutions: [{
+            toolCallId: 'call-1',
+            toolName: 'test_tool',
+            arguments: {},
+            result: 'ok',
+            duration: 10,
+            isError: false,
+          }],
+        }),
+        createMockTurn({ text: 'Second' }),
+      ];
+
+      const createLLM = createDeterministicLLM(turns);
+      const strategy = loop();
+      const input = new UserMessage('Test');
+      const initialState = AgentState.initial();
+
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+
+      const streamResult = strategy.stream(streamContext);
+
+      for await (const event of streamResult) {
+        void event;
+      }
+      const result = await streamResult.result;
+
+      // Should have messages from both iterations
+      expect(result.state.messages.length).toBeGreaterThan(1);
+      expect(result.state.step).toBe(2); // Two iterations
+    });
+
+    test('stream result includes correct step count', async () => {
+      const reasoningTurn = createMockTurn({ text: 'Reasoning' });
+      const actionWithTool = createMockTurn({
+        text: 'Action',
+        toolCalls: [{
+          toolCallId: 'call-1',
+          toolName: 'tool',
+          arguments: {},
+        }],
+        toolExecutions: [{
+          toolCallId: 'call-1',
+          toolName: 'tool',
+          arguments: {},
+          result: 'ok',
+          duration: 10,
+          isError: false,
+        }],
+      });
+      const reasoning2 = createMockTurn({ text: 'More reasoning' });
+      const finalAction = createMockTurn({ text: 'Done' });
+
+      const createLLM = createDeterministicLLM([
+        reasoningTurn, actionWithTool,
+        reasoning2, finalAction,
+      ]);
+      const strategy = react();
+      const input = new UserMessage('Multi-step task');
+      const initialState = AgentState.initial();
+
+      const streamContext: ExecutionContext = {
+        agent: { id: 'test-agent' },
+        llm: createLLM(),
+        input,
+        state: initialState,
+        tools: [],
+        strategy: {},
+      };
+
+      const streamResult = strategy.stream(streamContext);
+
+      for await (const event of streamResult) {
+        void event;
+      }
+      const result = await streamResult.result;
+
+      // Should have completed 2 ReAct steps
+      expect(result.state.step).toBe(2);
+      expect(result.state.reasoning).toHaveLength(2);
+    });
+  });
+});