groundswell 0.0.1 → 0.0.3

package/plan/P3P4/research/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/P3P4/research/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/P3P4/research/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 }
-```