groundswell 0.0.2 → 1.0.0

package/plan/001_d3bb02af4886/docs/research/P3P4/caching-lru.md

@@ -1,116 +0,0 @@
-# LRU Cache Research Summary
-
-## Recommended Stack
-
-```json
-{
-  "dependencies": {
-    "lru-cache": "^10.0.0"
-  }
-}
-```
-
-## Key Patterns
-
-### 1. Deterministic Cache Key Generation
-
-```typescript
-import { createHash } from 'node:crypto';
-
-function deterministicStringify(value: unknown): string {
-  const seen = new WeakSet<object>();
-
-  function stringify(val: unknown): string {
-    if (val === null) return 'null';
-    if (typeof val === 'string') return JSON.stringify(val);
-    if (typeof val === 'number' || typeof val === 'boolean') return String(val);
-    if (typeof val === 'undefined') return 'undefined';
-
-    if (typeof val === 'object') {
-      if (seen.has(val as object)) {
-        throw new TypeError('Converting circular structure to JSON');
-      }
-      seen.add(val as object);
-
-      let result: string;
-      if (Array.isArray(val)) {
-        result = '[' + val.map(stringify).join(',') + ']';
-      } else {
-        const keys = Object.keys(val as Record<string, unknown>).sort();
-        const pairs = keys.map(k =>
-          JSON.stringify(k) + ':' + stringify((val as Record<string, unknown>)[k])
-        );
-        result = '{' + pairs.join(',') + '}';
-      }
-
-      seen.delete(val as object);
-      return result;
-    }
-
-    return String(val);
-  }
-
-  return stringify(value);
-}
-
-function generateCacheKey(data: unknown): string {
-  const hash = createHash('sha256');
-  const serialized = deterministicStringify(data);
-  hash.update(serialized, 'utf8');
-  return hash.digest('hex');
-}
-```
-
-### 2. LRU Cache Implementation with lru-cache
-
-```typescript
-import LRU from 'lru-cache';
-
-const cache = new LRU<string, CacheValue>({
-  max: 1000,                    // Maximum number of items
-  maxSize: 52428800,            // 50MB memory limit
-  sizeCalculation: (entry, key) => {
-    return JSON.stringify(entry).length;
-  },
-  ttl: 1000 * 60 * 60,         // 1 hour default TTL
-  updateAgeOnGet: true,
-  allowStale: false
-});
-```
-
-### 3. Cache Interface (PRD Section 9.2)
-
-```typescript
-interface Cache {
-  get(key: string): Promise<any | undefined>;
-  set(key: string, value: any): Promise<void>;
-  bust(key: string): Promise<void>;
-  bustPrefix(prefix: string): Promise<void>;
-}
-```
-
-### 4. Cache Key Fields (PRD Section 9.1)
-
-SHA-256 of deterministic JSON encoding of:
-- user message
-- data
-- system value
-- model settings
-- temperature
-- tools (names sorted)
-- mcps (names sorted)
-- skills (names sorted)
-- schema version/hash (from Zod responseFormat._def)
-
-## Gotchas
-
-1. **Non-deterministic JSON.stringify** - Must sort keys!
-2. **Memory exhaustion** - Set both `max` and `maxSize`
-3. **Stale data** - Include model version in cache key
-4. **Circular references** - Handle with WeakSet tracking
-
-## Sources
-
-- https://www.npmjs.com/package/lru-cache
-- https://nodejs.org/api/crypto.html
-- https://www.npmjs.com/package/json-stringify-deterministic

package/plan/001_d3bb02af4886/docs/research/P3P4/introspection-tools.md

@@ -1,177 +0,0 @@
-# Agent Introspection Tools Research
-
-## Overview (PRD Section 11)
-
-Standard tools that allow agents to inspect and manipulate their position in the workflow hierarchy.
-
-## Tool Definitions (Anthropic Tool Format)
-
-### 1. inspect_current_node
-
-```typescript
-const inspectCurrentNode: Tool = {
-  name: 'inspect_current_node',
-  description: 'Get information about the current workflow node including ID, name, status, and parent reference',
-  input_schema: {
-    type: 'object',
-    properties: {},
-    required: []
-  }
-};
-
-// Handler returns:
-interface CurrentNodeInfo {
-  id: string;
-  name: string;
-  status: WorkflowStatus;
-  parentId?: string;
-  parentName?: string;
-  childCount: number;
-  depth: number;
-}
-```
-
-### 2. read_ancestor_chain
-
-```typescript
-const readAncestorChain: Tool = {
-  name: 'read_ancestor_chain',
-  description: 'Get all ancestor nodes from current position up to the root workflow',
-  input_schema: {
-    type: 'object',
-    properties: {
-      maxDepth: {
-        type: 'number',
-        description: 'Maximum ancestors to return (default: all)'
-      }
-    },
-    required: []
-  }
-};
-
-// Handler returns:
-interface AncestorInfo {
-  ancestors: Array<{
-    id: string;
-    name: string;
-    status: WorkflowStatus;
-    depth: number;
-  }>;
-  totalDepth: number;
-}
-```
-
-### 3. list_siblings_children
-
-```typescript
-const listSiblingsChildren: Tool = {
-  name: 'list_siblings_children',
-  description: 'List sibling or child nodes relative to current position',
-  input_schema: {
-    type: 'object',
-    properties: {
-      type: {
-        type: 'string',
-        enum: ['siblings', 'children'],
-        description: 'Type of nodes to list'
-      }
-    },
-    required: ['type']
-  }
-};
-```
-
-### 4. inspect_prior_outputs
-
-```typescript
-const inspectPriorOutputs: Tool = {
-  name: 'inspect_prior_outputs',
-  description: 'Get outputs from prior steps or prompt executions',
-  input_schema: {
-    type: 'object',
-    properties: {
-      nodeId: {
-        type: 'string',
-        description: 'Specific node ID to inspect (default: most recent)'
-      },
-      count: {
-        type: 'number',
-        description: 'Number of prior outputs to return (default: 1)'
-      }
-    },
-    required: []
-  }
-};
-```
-
-### 5. inspect_cache_status
-
-```typescript
-const inspectCacheStatus: Tool = {
-  name: 'inspect_cache_status',
-  description: 'Check if a prompt response is cached',
-  input_schema: {
-    type: 'object',
-    properties: {
-      promptHash: {
-        type: 'string',
-        description: 'Hash of the prompt to check'
-      }
-    },
-    required: ['promptHash']
-  }
-};
-```
-
-### 6. request_spawn_workflow
-
-```typescript
-const requestSpawnWorkflow: Tool = {
-  name: 'request_spawn_workflow',
-  description: 'Request to spawn a new child workflow dynamically',
-  input_schema: {
-    type: 'object',
-    properties: {
-      name: {
-        type: 'string',
-        description: 'Name for the new workflow'
-      },
-      description: {
-        type: 'string',
-        description: 'Description of what the workflow should do'
-      }
-    },
-    required: ['name', 'description']
-  }
-};
-```
-
-## Security Considerations
-
-1. **Read-only by default**: Most introspection tools should be read-only
-2. **Sanitize sensitive data**: Remove API keys, credentials from output
-3. **Limit spawning**: request_spawn_workflow should have rate limits
-4. **Depth limits**: Prevent infinite recursion in hierarchy traversal
-
-## Tool Bundle Export
-
-```typescript
-export const INTROSPECTION_TOOLS: Tool[] = [
-  inspectCurrentNode,
-  readAncestorChain,
-  listSiblingsChildren,
-  inspectPriorOutputs,
-  inspectCacheStatus,
-  requestSpawnWorkflow
-];
-```
-
-## Usage Example
-
-```typescript
-const agent = new Agent({
-  name: 'IntrospectiveAgent',
-  tools: [...INTROSPECTION_TOOLS, ...customTools],
-  system: 'You can inspect your position in the workflow hierarchy using the introspection tools.'
-});
-```

package/plan/001_d3bb02af4886/docs/research/P3P4/reflection-patterns.md

@@ -1,117 +0,0 @@
-# Reflection Patterns Research
-
-## What is Reflection in AI Agent Contexts
-
-Reflection is a self-correction mechanism where an AI agent:
-1. Evaluates its own output
-2. Identifies errors or improvements
-3. Revises its approach based on feedback
-
-## Levels of Reflection (PRD Section 4.4)
-
-### 1. Workflow-Level Reflection
-- Triggered when a step fails
-- Has access to entire workflow state
-- Can retry failed steps with modified approach
-
-### 2. Agent-Level Reflection
-- Triggered via Agent.reflect() method
-- Adds reflection system prompt prefix
-- Reviews reasoning before final answer
-
-### 3. Prompt-Level Reflection
-- Enabled per-prompt via enableReflection flag
-- Validates response against schema
-- Retries with error context if validation fails
-
-## Implementation Patterns
-
-### Reflection Prompt Template
-
-```typescript
-const REFLECTION_PROMPT = `Before answering, reflect on your reasoning step by step:
-1. What is the core problem/question?
-2. What approaches could solve this?
-3. What are potential errors or edge cases?
-4. Review your answer for accuracy.
-
-Then provide your final answer.`;
-```
-
-### Auto-Retry with Reflection
-
-```typescript
-async function executeWithReflection<T>(
-  agent: Agent,
-  prompt: Prompt<T>,
-  maxAttempts: number = 3
-): Promise<T> {
-  let lastError: Error | null = null;
-
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      const result = await agent.prompt(prompt);
-      return result;
-    } catch (error) {
-      lastError = error as Error;
-
-      if (attempt < maxAttempts) {
-        // Create reflection prompt with error context
-        const reflectionPrompt = prompt.withData({
-          previousError: lastError.message,
-          attempt: attempt,
-          instruction: 'Reflect on the previous error and try again.'
-        });
-
-        // Emit reflection event
-        emitEvent({
-          type: 'reflectionStart',
-          level: 'prompt',
-          node: currentNode
-        });
-      }
-    }
-  }
-
-  throw lastError;
-}
-```
-
-### ReflectionAPI Interface (PRD Section 4.3)
-
-```typescript
-interface ReflectionAPI {
-  isEnabled(): boolean;
-  triggerReflection(reason?: string): Promise<void>;
-  getReflectionHistory(): ReflectionEntry[];
-}
-
-interface ReflectionEntry {
-  timestamp: number;
-  level: 'workflow' | 'agent' | 'prompt';
-  reason: string;
-  originalError?: Error;
-  resolution: 'retry' | 'skip' | 'abort';
-  success: boolean;
-}
-```
-
-## Best Practices
-
-1. **Maximum reflection attempts**: 2-3 attempts before failure
-2. **When NOT to reflect**:
-   - Rate limit errors (wait and retry instead)
-   - Authentication errors (cannot self-fix)
-   - Quota exceeded (needs external action)
-3. **Performance considerations**:
-   - Each reflection doubles token usage
-   - Cache reflection results when possible
-4. **State capture**: Always snapshot state before reflection for debugging
-
-## Integration with Workflow Events
-
-```typescript
-// Events to emit during reflection
-{ type: 'reflectionStart'; level: 'workflow' | 'agent' | 'prompt'; node: WorkflowNode }
-{ type: 'reflectionEnd'; level: 'workflow' | 'agent' | 'prompt'; success: boolean; node: WorkflowNode }
-```

package/plan/001_d3bb02af4886/docs/research/P4P5/RESEARCH_SUMMARY.md

@@ -1,151 +0,0 @@
-# Phase 4 & 5 Research Summary
-
-## Overview
-
-This document summarizes the research findings that informed the PRP for Phases 4 & 5 of the Groundswell orchestration framework.
-
-## Phase 4 Status: COMPLETE
-
-All Phase 4 implementations are complete and verified. The research from P3P4 was applied successfully:
-
-### Dynamic Factory Functions (P4.1)
-- **Implementation**: `/src/core/factory.ts` (124 lines)
-- **Functions**: `createWorkflow()`, `createAgent()`, `createPrompt()`, `quickWorkflow()`, `quickAgent()`
-- **Pattern**: Factory pattern for dynamic entity creation at runtime
-
-### Dynamic Context Revision (P4.2)
-- **Implementation**: `/src/core/workflow-context.ts` (349 lines)
-- **Method**: `replaceLastPromptResult<T>(newPrompt, agent)`
-- **Pattern**: Marks previous node as 'revised', attaches new result as sibling
-
-### Introspection Tools (P4.3-P4.5)
-- **Implementation**: `/src/tools/introspection.ts` (465 lines)
-- **Tools Defined**: 6 tools per PRD Section 11
-- **Pattern**: Anthropic Tool format with `input_schema` JSON Schema
-
-## Phase 5 Research: Example Implementation
-
-### Existing Example Patterns (Examples 1-6)
-
-**File Structure Pattern**:
-```
-/examples/examples/NN-feature-name.ts
-```
-
-**Code Structure**:
-1. JSDoc header with "Demonstrates:" section
-2. Imports (groundswell, then helpers)
-3. Workflow/Agent class definitions
-4. `run*Example()` export function with Parts 1-N
-5. Direct execution check via `import.meta.url`
-
-**Output Pattern**:
-- `printHeader()` for main sections
-- `printSection()` for subsections
-- Console output showing actual feature behavior
-- Tree visualization at end
-
-### Example 7: Agent Loops with Observability
-
-**Key Patterns to Demonstrate**:
-1. Agent.prompt() inside ctx.step() loop
-2. Multi-agent routing based on data type
-3. Full event tree with timing per iteration
-4. Cache metrics display
-
-**Reference Research**: `/plan/P3P4/research/caching-lru.md`
-- Shows cache hit/miss tracking
-- Metrics include: hits, misses, size, itemCount
-
-### Example 8: SDK Features
-
-**Key Patterns to Demonstrate**:
-1. Tool definition in Anthropic format
-2. MCPHandler registration pattern
-3. Hook lifecycle (pre/post tool, session start/end)
-4. Skill loading from path
-
-**Reference Research**: `/plan/P1P2/research/anthropic-sdk.md`
-- Tool schema follows JSON Schema spec
-- Hooks must be async functions
-- Skills inject SKILL.md content into system prompt
-
-### Example 9: Multi-level Reflection
-
-**Key Patterns to Demonstrate**:
-1. Prompt-level: `enableReflection: true` on Prompt
-2. Agent-level: `agent.reflect()` method
-3. Workflow-level: `enableReflection` on WorkflowConfig
-
-**Reference Research**: `/plan/P3P4/research/reflection-patterns.md`
-- Max 3 attempts before failure
-- Skip reflection for rate limits, auth errors
-- Emit reflectionStart/reflectionEnd events
-
-**Non-Retryable Errors**:
-- Rate limit exceeded
-- Authentication failure
-- Quota exceeded
-- Network errors (timeouts)
-
-### Example 10: Introspection Tools
-
-**Key Patterns to Demonstrate**:
-1. All 6 introspection tools in action
-2. Nested workflow hierarchy for context
-3. Agent using tools to describe position
-
-**Reference Research**: `/plan/P3P4/research/introspection-tools.md`
-- Tools are read-only (except spawn)
-- Use getExecutionContext() for context access
-- Security: filter secrets from responses
-
-**Tools to Demonstrate**:
-| Tool | Purpose | Returns |
-|------|---------|---------|
-| `inspect_current_node` | "Where am I?" | id, name, status, parentId, depth |
-| `read_ancestor_chain` | "What's above me?" | Array of ancestors to root |
-| `list_siblings_children` | "What's around me?" | Siblings or children array |
-| `inspect_prior_outputs` | "What happened before?" | Previous step outputs |
-| `inspect_cache_status` | "Is this cached?" | Cache entry info |
-| `request_spawn_workflow` | "Can I create children?" | Spawn request result |
-
-## Implementation Verification
-
-### Validation Commands
-```bash
-# Build check
-npm run build
-
-# Test check
-npm test
-
-# Export verification
-node -e "const g = require('./dist'); console.log(Object.keys(g).length, 'exports');"
-```
-
-### Expected Outputs
-- Build: 0 errors
-- Tests: All passing
-- Exports: ~60+ exports from main index
-
-## References
-
-### Primary Research Documents
-- `/plan/P3P4/research/caching-lru.md` - LRU cache patterns
-- `/plan/P3P4/research/reflection-patterns.md` - Reflection implementation
-- `/plan/P3P4/research/introspection-tools.md` - Tool specifications
-- `/plan/research/agent-introspection-patterns.md` - Hierarchy patterns
-- `/plan/research/introspection-security-guide.md` - Security boundaries
-
-### Implementation References
-- `/src/core/agent.ts` - Agent implementation (573 lines)
-- `/src/core/prompt.ts` - Prompt implementation (150 lines)
-- `/src/cache/cache.ts` - LLMCache implementation (237 lines)
-- `/src/reflection/reflection.ts` - ReflectionManager (407 lines)
-- `/src/tools/introspection.ts` - Introspection tools (465 lines)
-
-### Example References
-- `/examples/examples/01-basic-workflow.ts` - Basic patterns
-- `/examples/examples/04-observers-debugger.ts` - Debugging patterns
-- `/examples/examples/05-error-handling.ts` - Error patterns