groundswell 0.0.1

package/plan/P3P4/research/caching-lru.md

@@ -0,0 +1,116 @@
+# 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/P3P4/research/introspection-tools.md

@@ -0,0 +1,177 @@
+# 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/P3P4/research/reflection-patterns.md

@@ -0,0 +1,117 @@
+# 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 }
+```