groundswell 0.0.1

package/src/__tests__/unit/decorators.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest';
+import { Workflow, Step, Task, ObservedState, getObservedState, WorkflowEvent, WorkflowObserver } from '../../index.js';
+
+describe('@Step decorator', () => {
+  class StepTestWorkflow extends Workflow {
+    stepCalled = false;
+
+    @Step({ trackTiming: true })
+    async myStep(): Promise<string> {
+      this.stepCalled = true;
+      return 'step result';
+    }
+
+    async run(): Promise<void> {
+      await this.myStep();
+    }
+  }
+
+  it('should execute the original method', async () => {
+    const wf = new StepTestWorkflow();
+    await wf.run();
+    expect(wf.stepCalled).toBe(true);
+  });
+
+  it('should emit stepStart and stepEnd events', async () => {
+    const wf = new StepTestWorkflow();
+    const events: WorkflowEvent[] = [];
+
+    wf.addObserver({
+      onLog: () => {},
+      onEvent: (e) => events.push(e),
+      onStateUpdated: () => {},
+      onTreeChanged: () => {},
+    });
+
+    await wf.run();
+
+    const startEvent = events.find((e) => e.type === 'stepStart');
+    const endEvent = events.find((e) => e.type === 'stepEnd');
+
+    expect(startEvent).toBeDefined();
+    expect(endEvent).toBeDefined();
+    if (endEvent?.type === 'stepEnd') {
+      expect(endEvent.duration).toBeGreaterThanOrEqual(0);
+    }
+  });
+
+  it('should wrap errors in WorkflowError', async () => {
+    class FailingWorkflow extends Workflow {
+      @Step()
+      async failingStep(): Promise<void> {
+        throw new Error('Step failed');
+      }
+
+      async run(): Promise<void> {
+        await this.failingStep();
+      }
+    }
+
+    const wf = new FailingWorkflow();
+
+    await expect(wf.run()).rejects.toMatchObject({
+      message: 'Step failed',
+      workflowId: wf.id,
+    });
+  });
+});
+
+describe('@ObservedState decorator', () => {
+  class StateTestWorkflow extends Workflow {
+    @ObservedState()
+    publicField: string = 'public';
+
+    @ObservedState({ redact: true })
+    secretField: string = 'secret';
+
+    @ObservedState({ hidden: true })
+    hiddenField: string = 'hidden';
+
+    async run(): Promise<void> {}
+  }
+
+  it('should include public fields in snapshot', () => {
+    const wf = new StateTestWorkflow();
+    const state = getObservedState(wf);
+    expect(state.publicField).toBe('public');
+  });
+
+  it('should redact secret fields', () => {
+    const wf = new StateTestWorkflow();
+    const state = getObservedState(wf);
+    expect(state.secretField).toBe('***');
+  });
+
+  it('should exclude hidden fields', () => {
+    const wf = new StateTestWorkflow();
+    const state = getObservedState(wf);
+    expect('hiddenField' in state).toBe(false);
+  });
+});

package/src/__tests__/unit/introspection-tools.test.ts

@@ -0,0 +1,277 @@
+/**
+ * Unit tests for introspection tools
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import {
+  INTROSPECTION_TOOLS,
+  handleInspectCurrentNode,
+  handleReadAncestorChain,
+  handleListSiblingsChildren,
+  handleInspectPriorOutputs,
+  handleInspectCacheStatus,
+  handleRequestSpawnWorkflow,
+  executeIntrospectionTool,
+} from '../../tools/introspection.js';
+import { runInContext, type AgentExecutionContext } from '../../core/context.js';
+import type { WorkflowNode } from '../../types/index.js';
+import { defaultCache } from '../../cache/cache.js';
+
+describe('Introspection Tools', () => {
+  describe('INTROSPECTION_TOOLS', () => {
+    it('should export 6 tools', () => {
+      expect(INTROSPECTION_TOOLS).toHaveLength(6);
+    });
+
+    it('should have valid tool definitions', () => {
+      for (const tool of INTROSPECTION_TOOLS) {
+        expect(tool.name).toBeDefined();
+        expect(tool.description).toBeDefined();
+        expect(tool.input_schema).toBeDefined();
+        expect(tool.input_schema.type).toBe('object');
+      }
+    });
+
+    it('should include all expected tool names', () => {
+      const names = INTROSPECTION_TOOLS.map((t) => t.name);
+      expect(names).toContain('inspect_current_node');
+      expect(names).toContain('read_ancestor_chain');
+      expect(names).toContain('list_siblings_children');
+      expect(names).toContain('inspect_prior_outputs');
+      expect(names).toContain('inspect_cache_status');
+      expect(names).toContain('request_spawn_workflow');
+    });
+  });
+
+  describe('handlers', () => {
+    const createTestNode = (
+      id: string,
+      name: string,
+      parent: WorkflowNode | null = null
+    ): WorkflowNode => ({
+      id,
+      name,
+      parent,
+      children: [],
+      status: 'running',
+      logs: [],
+      events: [],
+      stateSnapshot: null,
+    });
+
+    const createContext = (node: WorkflowNode): AgentExecutionContext => ({
+      workflowNode: node,
+      emitEvent: () => {},
+      workflowId: 'test-workflow',
+    });
+
+    describe('handleInspectCurrentNode', () => {
+      it('should throw when not in workflow context', async () => {
+        await expect(handleInspectCurrentNode()).rejects.toThrow(
+          'Not in workflow context'
+        );
+      });
+
+      it('should return current node info', async () => {
+        const parent = createTestNode('parent-1', 'Parent');
+        const node = createTestNode('child-1', 'Child', parent);
+        parent.children.push(node);
+
+        const result = await runInContext(createContext(node), () =>
+          handleInspectCurrentNode()
+        );
+
+        expect(result.id).toBe('child-1');
+        expect(result.name).toBe('Child');
+        expect(result.status).toBe('running');
+        expect(result.parentId).toBe('parent-1');
+        expect(result.parentName).toBe('Parent');
+        expect(result.depth).toBe(1);
+      });
+
+      it('should handle root node (no parent)', async () => {
+        const node = createTestNode('root-1', 'Root');
+
+        const result = await runInContext(createContext(node), () =>
+          handleInspectCurrentNode()
+        );
+
+        expect(result.parentId).toBeUndefined();
+        expect(result.depth).toBe(0);
+      });
+    });
+
+    describe('handleReadAncestorChain', () => {
+      it('should throw when not in workflow context', async () => {
+        await expect(handleReadAncestorChain({})).rejects.toThrow(
+          'Not in workflow context'
+        );
+      });
+
+      it('should return ancestor chain', async () => {
+        const root = createTestNode('root-1', 'Root');
+        const parent = createTestNode('parent-1', 'Parent', root);
+        root.children.push(parent);
+        const child = createTestNode('child-1', 'Child', parent);
+        parent.children.push(child);
+
+        const result = await runInContext(createContext(child), () =>
+          handleReadAncestorChain({})
+        );
+
+        expect(result.ancestors).toHaveLength(2);
+        expect(result.ancestors[0].id).toBe('parent-1');
+        expect(result.ancestors[1].id).toBe('root-1');
+        expect(result.totalDepth).toBe(2);
+      });
+
+      it('should respect maxDepth limit', async () => {
+        const root = createTestNode('root-1', 'Root');
+        const parent = createTestNode('parent-1', 'Parent', root);
+        root.children.push(parent);
+        const child = createTestNode('child-1', 'Child', parent);
+        parent.children.push(child);
+
+        const result = await runInContext(createContext(child), () =>
+          handleReadAncestorChain({ maxDepth: 1 })
+        );
+
+        expect(result.ancestors).toHaveLength(1);
+        expect(result.ancestors[0].id).toBe('parent-1');
+      });
+    });
+
+    describe('handleListSiblingsChildren', () => {
+      it('should throw when not in workflow context', async () => {
+        await expect(
+          handleListSiblingsChildren({ type: 'children' })
+        ).rejects.toThrow('Not in workflow context');
+      });
+
+      it('should return children', async () => {
+        const parent = createTestNode('parent-1', 'Parent');
+        const child1 = createTestNode('child-1', 'Child 1', parent);
+        const child2 = createTestNode('child-2', 'Child 2', parent);
+        parent.children.push(child1, child2);
+
+        const result = await runInContext(createContext(parent), () =>
+          handleListSiblingsChildren({ type: 'children' })
+        );
+
+        expect(result.type).toBe('children');
+        expect(result.nodes).toHaveLength(2);
+      });
+
+      it('should return siblings (excluding self)', async () => {
+        const parent = createTestNode('parent-1', 'Parent');
+        const child1 = createTestNode('child-1', 'Child 1', parent);
+        const child2 = createTestNode('child-2', 'Child 2', parent);
+        parent.children.push(child1, child2);
+
+        const result = await runInContext(createContext(child1), () =>
+          handleListSiblingsChildren({ type: 'siblings' })
+        );
+
+        expect(result.type).toBe('siblings');
+        expect(result.nodes).toHaveLength(1);
+        expect(result.nodes[0].id).toBe('child-2');
+      });
+    });
+
+    describe('handleInspectPriorOutputs', () => {
+      it('should throw when not in workflow context', async () => {
+        await expect(handleInspectPriorOutputs({})).rejects.toThrow(
+          'Not in workflow context'
+        );
+      });
+
+      it('should return completed sibling outputs', async () => {
+        const parent = createTestNode('parent-1', 'Parent');
+        const completed = createTestNode('completed-1', 'Completed', parent);
+        completed.status = 'completed';
+        // Add a valid workflow event for testing
+        completed.events.push({
+          type: 'stepEnd',
+          node: completed,
+          step: 'test-step',
+          duration: 100,
+        } as never); // Cast to avoid strict type checking in tests
+        const current = createTestNode('current-1', 'Current', parent);
+        parent.children.push(completed, current);
+
+        const result = await runInContext(createContext(current), () =>
+          handleInspectPriorOutputs({})
+        );
+
+        expect(result).toHaveLength(1);
+        expect(result[0].nodeId).toBe('completed-1');
+        expect(result[0].status).toBe('completed');
+      });
+    });
+
+    describe('handleInspectCacheStatus', () => {
+      beforeEach(async () => {
+        await defaultCache.clear();
+      });
+
+      it('should return false for missing cache key', async () => {
+        const result = await handleInspectCacheStatus({
+          promptHash: 'nonexistent-key',
+        });
+
+        expect(result.exists).toBe(false);
+        expect(result.key).toBe('nonexistent-key');
+      });
+
+      it('should return true for existing cache key', async () => {
+        await defaultCache.set('test-key', { data: 'test' });
+
+        const result = await handleInspectCacheStatus({ promptHash: 'test-key' });
+
+        expect(result.exists).toBe(true);
+      });
+    });
+
+    describe('handleRequestSpawnWorkflow', () => {
+      it('should throw when not in workflow context', async () => {
+        await expect(
+          handleRequestSpawnWorkflow({ name: 'Test', description: 'Test workflow' })
+        ).rejects.toThrow('Not in workflow context');
+      });
+
+      it('should return spawn request', async () => {
+        const node = createTestNode('node-1', 'Node');
+
+        const result = await runInContext(createContext(node), () =>
+          handleRequestSpawnWorkflow({
+            name: 'NewWorkflow',
+            description: 'A new workflow',
+          })
+        );
+
+        expect(result.name).toBe('NewWorkflow');
+        expect(result.description).toBe('A new workflow');
+        expect(result.requestId).toMatch(/^spawn-/);
+        expect(result.status).toBe('pending');
+      });
+    });
+  });
+
+  describe('executeIntrospectionTool', () => {
+    it('should execute tool by name', async () => {
+      await defaultCache.set('cache-test', 'value');
+
+      const result = await executeIntrospectionTool('inspect_cache_status', {
+        promptHash: 'cache-test',
+      });
+
+      expect(result).toMatchObject({ exists: true, key: 'cache-test' });
+    });
+
+    it('should throw for unknown tool', async () => {
+      await expect(
+        executeIntrospectionTool('unknown_tool', {})
+      ).rejects.toThrow('Unknown introspection tool');
+    });
+  });
+});

package/src/__tests__/unit/prompt.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect } from 'vitest';
+import { z } from 'zod';
+import { Prompt } from '../../core/prompt.js';
+
+describe('Prompt', () => {
+  it('should create with unique id', () => {
+    const p1 = new Prompt({
+      user: 'Test',
+      responseFormat: z.object({ message: z.string() }),
+    });
+    const p2 = new Prompt({
+      user: 'Test',
+      responseFormat: z.object({ message: z.string() }),
+    });
+    expect(p1.id).not.toBe(p2.id);
+  });
+
+  it('should store user message and data', () => {
+    const prompt = new Prompt({
+      user: 'Hello world',
+      data: { key: 'value' },
+      responseFormat: z.object({ result: z.string() }),
+    });
+
+    expect(prompt.user).toBe('Hello world');
+    expect(prompt.data).toEqual({ key: 'value' });
+  });
+
+  it('should validate response successfully', () => {
+    const schema = z.object({
+      name: z.string(),
+      age: z.number(),
+    });
+
+    const prompt = new Prompt({
+      user: 'Get person',
+      responseFormat: schema,
+    });
+
+    const result = prompt.validateResponse({ name: 'John', age: 30 });
+    expect(result).toEqual({ name: 'John', age: 30 });
+  });
+
+  it('should throw on invalid response', () => {
+    const schema = z.object({
+      name: z.string(),
+      age: z.number(),
+    });
+
+    const prompt = new Prompt({
+      user: 'Get person',
+      responseFormat: schema,
+    });
+
+    expect(() => prompt.validateResponse({ name: 'John' })).toThrow();
+  });
+
+  it('should safely validate response', () => {
+    const schema = z.object({ value: z.number() });
+    const prompt = new Prompt({
+      user: 'Test',
+      responseFormat: schema,
+    });
+
+    const success = prompt.safeValidateResponse({ value: 42 });
+    expect(success.success).toBe(true);
+    if (success.success) {
+      expect(success.data).toEqual({ value: 42 });
+    }
+
+    const failure = prompt.safeValidateResponse({ value: 'not a number' });
+    expect(failure.success).toBe(false);
+  });
+
+  it('should build user message without data', () => {
+    const prompt = new Prompt({
+      user: 'Simple message',
+      responseFormat: z.string(),
+    });
+
+    expect(prompt.buildUserMessage()).toBe('Simple message');
+  });
+
+  it('should build user message with data', () => {
+    const prompt = new Prompt({
+      user: 'Message with data',
+      data: { items: ['a', 'b', 'c'] },
+      responseFormat: z.string(),
+    });
+
+    const message = prompt.buildUserMessage();
+    expect(message).toContain('Message with data');
+    expect(message).toContain('<items>');
+    expect(message).toContain('</items>');
+  });
+
+  it('should create new prompt with updated data', () => {
+    const original = new Prompt({
+      user: 'Test',
+      data: { a: 1 },
+      responseFormat: z.string(),
+    });
+
+    const updated = original.withData({ b: 2 });
+
+    expect(original.data).toEqual({ a: 1 });
+    expect(updated.data).toEqual({ a: 1, b: 2 });
+    expect(original.id).not.toBe(updated.id);
+  });
+
+  it('should store override fields', () => {
+    const prompt = new Prompt({
+      user: 'Test',
+      responseFormat: z.string(),
+      system: 'Custom system prompt',
+      tools: [{ name: 'test', description: 'Test tool', input_schema: { type: 'object', properties: {} } }],
+      enableReflection: true,
+    });
+
+    expect(prompt.systemOverride).toBe('Custom system prompt');
+    expect(prompt.toolsOverride).toHaveLength(1);
+    expect(prompt.enableReflection).toBe(true);
+  });
+
+  it('should be immutable', () => {
+    const prompt = new Prompt({
+      user: 'Test',
+      data: { key: 'value' },
+      responseFormat: z.string(),
+    });
+
+    expect(Object.isFrozen(prompt)).toBe(true);
+    expect(Object.isFrozen(prompt.data)).toBe(true);
+  });
+});