agentic-flow 1.9.0 → 1.9.1

package/agentic-flow/docs/architecture/RESEARCH_SUMMARY.md

@@ -1,652 +0,0 @@
-# Claude Agent SDK Research Summary
-
-## Executive Summary
-
-The Claude Agent SDK (v0.1.5) provides a production-ready framework for building autonomous AI agents. Our current implementation uses only 5% of its capabilities. This research identifies critical gaps and provides a roadmap to unlock 10x more value.
-
-## SDK Capabilities Discovered
-
-### 1. Query API - Core Interface
-
-```typescript
-import { query, Options } from '@anthropic-ai/claude-agent-sdk';
-
-const result = query({
-  prompt: string | AsyncIterable<SDKUserMessage>,
-  options: Options
-});
-
-for await (const message of result) {
-  // Stream of SDKMessage types
-}
-```
-
-**Message Types**:
-- `SDKAssistantMessage`: Model responses with content
-- `SDKUserMessage`: User inputs
-- `SDKResultMessage`: Final results with usage/cost
-- `SDKSystemMessage`: System initialization info
-- `SDKPartialAssistantMessage`: Streaming events (real-time)
-- `SDKCompactBoundaryMessage`: Context compaction events
-
-### 2. Options API - 30+ Configuration Parameters
-
-#### Essential Options
-```typescript
-interface Options {
-  // Core Configuration
-  systemPrompt?: string;              // Define agent role
-  model?: string;                     // 'claude-sonnet-4-5-20250929'
-  maxTurns?: number;                  // Conversation length limit
-
-  // Tool Control
-  allowedTools?: string[];            // Whitelist tools
-  disallowedTools?: string[];         // Blacklist tools
-  mcpServers?: Record<string, McpServerConfig>;
-
-  // Permission & Security
-  permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions' | 'plan';
-  canUseTool?: CanUseTool;            // Custom authorization
-  additionalDirectories?: string[];   // Sandbox paths
-
-  // Session Management
-  resume?: string;                    // Resume session ID
-  resumeSessionAt?: string;           // Resume from message ID
-  forkSession?: boolean;              // Fork instead of resume
-  continue?: boolean;                 // Continue previous context
-
-  // Advanced
-  hooks?: Record<HookEvent, HookCallbackMatcher[]>;
-  abortController?: AbortController;  // Cancellation
-  maxThinkingTokens?: number;         // Extended thinking
-  includePartialMessages?: boolean;   // Stream events
-}
-```
-
-#### Options We're Not Using
-- ✅ `systemPrompt` - Using basic version
-- ❌ `allowedTools` - **Critical gap**
-- ❌ `mcpServers` - **Critical gap**
-- ❌ `hooks` - **Critical gap**
-- ❌ `permissionMode` - **Critical gap**
-- ❌ `resume` - Missing session management
-- ❌ `maxTurns` - No conversation limits
-- ❌ `includePartialMessages` - No streaming UI
-
-### 3. Built-in Tools (17 Available)
-
-#### File System Tools
-- `FileRead`: Read files with offset/limit
-- `FileWrite`: Write new files
-- `FileEdit`: String replacement editing
-- `Glob`: Pattern-based file discovery
-- `NotebookEdit`: Jupyter notebook editing
-
-#### Code Execution
-- `Bash`: Shell command execution (with timeout)
-- `BashOutput`: Read background process output
-- `KillShell`: Terminate background processes
-
-#### Web Tools
-- `WebSearch`: Search the web
-- `WebFetch`: Fetch and analyze web pages
-
-#### Agent Tools
-- `Agent`: Spawn subagents
-- `TodoWrite`: Task tracking
-
-#### MCP Tools
-- `McpInput`: Call MCP server tools
-- `ListMcpResources`: List MCP resources
-- `ReadMcpResource`: Read MCP resources
-
-#### Planning Tools
-- `ExitPlanMode`: Submit plans for approval
-
-#### Code Analysis
-- `Grep`: Pattern search in files
-
-**Current Usage**: 0 tools
-**Recommended**: Enable 10-15 tools based on agent role
-
-### 4. Hook System - Observability & Control
-
-```typescript
-type HookEvent =
-  | 'PreToolUse'      // Before tool execution
-  | 'PostToolUse'     // After tool execution
-  | 'Notification'    // System notifications
-  | 'UserPromptSubmit' // User input received
-  | 'SessionStart'    // Session initialization
-  | 'SessionEnd'      // Session termination
-  | 'Stop'            // Execution stopped
-  | 'SubagentStop'    // Subagent stopped
-  | 'PreCompact';     // Before context compaction
-
-type HookCallback = (
-  input: HookInput,
-  toolUseID: string | undefined,
-  options: { signal: AbortSignal }
-) => Promise<HookJSONOutput>;
-```
-
-#### Example: Logging Hook
-```typescript
-const hooks: Options['hooks'] = {
-  PreToolUse: [{
-    hooks: [async (input, toolUseID) => {
-      console.log(`[${input.tool_name}] Starting...`);
-      return { continue: true };
-    }]
-  }],
-
-  PostToolUse: [{
-    hooks: [async (input, toolUseID) => {
-      console.log(`[${input.tool_name}] Completed`);
-      return { continue: true };
-    }]
-  }]
-};
-```
-
-#### Example: Permission Hook
-```typescript
-const hooks: Options['hooks'] = {
-  PreToolUse: [{
-    hooks: [async (input) => {
-      if (input.tool_name === 'Bash') {
-        const cmd = input.tool_input.command;
-        if (cmd.includes('rm -rf')) {
-          return {
-            decision: 'block',
-            reason: 'Destructive command blocked',
-            continue: false
-          };
-        }
-      }
-      return { continue: true };
-    }]
-  }]
-};
-```
-
-**Current Usage**: No hooks
-**Impact**: Zero observability, no security controls
-
-### 5. Subagent Pattern
-
-```typescript
-// Enable subagent spawning
-options: {
-  allowedTools: ['Agent'],
-  agents: {
-    'security-expert': {
-      description: 'Security analysis specialist',
-      prompt: 'You are a security expert...',
-      tools: ['FileRead', 'Grep'],
-      model: 'sonnet'
-    },
-    'performance-expert': {
-      description: 'Performance optimization specialist',
-      prompt: 'You optimize code performance...',
-      tools: ['FileRead', 'Bash'],
-      model: 'sonnet'
-    }
-  }
-}
-
-// Agent can spawn subagents
-"Use the Agent tool to spawn a security-expert to review auth.ts"
-```
-
-**Benefits**:
-- Isolated contexts per subagent
-- Parallel execution within single query
-- Specialized system prompts
-- Independent tool access
-
-**Current Usage**: Not implemented
-**Impact**: Can't handle complex multi-step tasks
-
-### 6. MCP Integration - Custom Tools
-
-```typescript
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-
-const customTools = createSdkMcpServer({
-  name: 'my-tools',
-  version: '1.0.0',
-  tools: [
-    tool(
-      'database_query',
-      'Execute database query',
-      {
-        sql: z.string(),
-        limit: z.number().optional()
-      },
-      async (args) => {
-        const result = await db.query(args.sql);
-        return {
-          content: [{ type: 'text', text: JSON.stringify(result) }]
-        };
-      }
-    )
-  ]
-});
-
-// Use in agents
-options: {
-  mcpServers: {
-    'my-tools': customTools
-  }
-}
-```
-
-**Current Usage**: Not implemented
-**Impact**: Can't integrate with our systems (Supabase, Flow Nexus, etc.)
-
-### 7. Session Management
-
-```typescript
-// Long-running task with checkpoints
-const sessionId = crypto.randomUUID();
-
-// Initial execution
-const result1 = await query({
-  prompt: 'Complex multi-hour task...',
-  options: {
-    resume: sessionId,
-    maxTurns: 100
-  }
-});
-
-// Resume after interruption
-const result2 = await query({
-  prompt: 'Continue previous task',
-  options: {
-    resume: sessionId,
-    resumeSessionAt: lastMessageId,
-    continue: true
-  }
-});
-
-// Fork for experimentation
-const result3 = await query({
-  prompt: 'Try alternative approach',
-  options: {
-    resume: sessionId,
-    forkSession: true
-  }
-});
-```
-
-**Current Usage**: Not implemented
-**Impact**: Can't handle tasks longer than single execution
-
-### 8. Permission System
-
-```typescript
-const secureOptions: Options = {
-  permissionMode: 'default', // Ask for dangerous operations
-
-  allowedTools: [
-    'FileRead',   // Always safe
-    'Glob',       // Always safe
-    'WebFetch'    // Monitor but allow
-  ],
-
-  disallowedTools: [
-    'Bash'  // Too dangerous for this agent
-  ],
-
-  canUseTool: async (toolName, input, { suggestions }) => {
-    if (toolName === 'FileWrite') {
-      const path = input.file_path as string;
-
-      // Block writes outside workspace
-      if (!path.startsWith('/workspace')) {
-        return {
-          behavior: 'deny',
-          message: 'Can only write to /workspace',
-          interrupt: true
-        };
-      }
-
-      // Require approval for critical files
-      if (path.includes('package.json')) {
-        const approved = await askUser(`Allow write to ${path}?`);
-        if (approved) {
-          return {
-            behavior: 'allow',
-            updatedInput: input,
-            updatedPermissions: suggestions // Remember choice
-          };
-        }
-      }
-    }
-
-    return { behavior: 'allow', updatedInput: input };
-  },
-
-  additionalDirectories: ['/workspace/project']
-};
-```
-
-**Current Usage**: No permission controls
-**Impact**: Security risk in production
-
-### 9. Context Management
-
-```typescript
-const options: Options = {
-  maxTurns: 100,  // Allow long conversations
-
-  hooks: {
-    PreCompact: [{
-      hooks: [async (input) => {
-        console.log('Context compaction triggered', {
-          trigger: input.trigger,  // 'auto' or 'manual'
-          tokensBeforeCompact: input.compact_metadata.pre_tokens
-        });
-
-        // Provide compaction guidance
-        return {
-          continue: true,
-          systemMessage: 'Preserve all test results and function signatures'
-        };
-      }]
-    }]
-  }
-};
-```
-
-**Benefits**:
-- Automatic context compression
-- Preserves important information
-- Enables longer agent sessions
-- Reduces cost (cached prompts)
-
-**Current Usage**: Not implemented
-**Impact**: Hit token limits quickly
-
-### 10. Control API
-
-```typescript
-const query = query({ prompt, options });
-
-// Interrupt execution
-await query.interrupt();
-
-// Change permission mode mid-execution
-await query.setPermissionMode('bypassPermissions');
-
-// Change model mid-execution
-await query.setModel('claude-opus-4-20250514');
-
-// Query capabilities
-const commands = await query.supportedCommands();
-const models = await query.supportedModels();
-const mcpStatus = await query.mcpServerStatus();
-```
-
-**Current Usage**: Not using any control APIs
-**Impact**: No dynamic control over agents
-
-## Critical Gaps Analysis
-
-### Architecture Gaps
-
-| Capability | SDK Provides | We Use | Impact |
-|-----------|--------------|---------|---------|
-| Tool Integration | 17+ tools | 0 tools | **CRITICAL** - Agents can't do anything |
-| Error Handling | Retry, graceful degradation | None | **CRITICAL** - 40% failure rate |
-| Streaming | Real-time updates | Buffer entire response | **HIGH** - Poor UX |
-| Observability | Hooks for all events | No logging | **HIGH** - Can't debug |
-| Permissions | Fine-grained control | None | **HIGH** - Security risk |
-| Session Management | Resume/fork/checkpoint | None | **MEDIUM** - Can't handle long tasks |
-| Context Optimization | Auto-compaction | None | **MEDIUM** - Hit token limits |
-| Subagents | Parallel specialized agents | None | **MEDIUM** - Complex tasks fail |
-| MCP Integration | Custom tool framework | None | **MEDIUM** - Can't extend |
-| Cost Tracking | Usage/cost in results | Not collected | **LOW** - No budget control |
-
-### Production Readiness Gaps
-
-| Feature | Required for Production | Current State | Gap |
-|---------|------------------------|---------------|-----|
-| Health Checks | ✅ Required | ❌ None | **CRITICAL** |
-| Monitoring | ✅ Required | ❌ None | **CRITICAL** |
-| Error Recovery | ✅ Required | ❌ None | **CRITICAL** |
-| Rate Limiting | ✅ Required | ❌ None | **HIGH** |
-| Security Controls | ✅ Required | ❌ None | **HIGH** |
-| Logging | ✅ Required | ❌ Basic console | **HIGH** |
-| Metrics | ⚠️ Recommended | ❌ None | **MEDIUM** |
-| Testing | ⚠️ Recommended | ❌ None | **MEDIUM** |
-| Documentation | ⚠️ Recommended | ❌ Basic README | **LOW** |
-
-## Best Practices from Anthropic Engineering
-
-### 1. Agent Loop Pattern
-
-```
-Context Gathering → Action Taking → Work Verification
-      ↑                                      ↓
-      └──────────────────────────────────────┘
-```
-
-**Implementation**:
-```typescript
-async function agentLoop(task: string) {
-  let context = await gatherContext(task);
-
-  while (!isComplete(context)) {
-    const action = await planAction(context);
-    const result = await executeAction(action);
-    const verification = await verifyWork(result);
-
-    if (verification.passed) {
-      context = updateContext(context, result);
-    } else {
-      context = adjustApproach(context, verification.feedback);
-    }
-  }
-
-  return finalizeResult(context);
-}
-```
-
-### 2. Agentic Search Over Semantic Search
-
-Don't pre-process context. Let agent discover what it needs:
-
-```typescript
-// ❌ Bad: Pre-process everything
-const allFiles = await readAllFiles();
-const embeddings = await generateEmbeddings(allFiles);
-const relevantFiles = await semanticSearch(embeddings, query);
-
-// ✅ Good: Let agent explore
-const agent = createAgent({
-  systemPrompt: 'Explore the codebase to understand the auth system',
-  allowedTools: ['Glob', 'FileRead', 'Grep']
-});
-
-// Agent will:
-// 1. Glob for *auth*.ts files
-// 2. Read promising files
-// 3. Grep for specific patterns
-// 4. Build mental model iteratively
-```
-
-### 3. Subagents for Parallel Context
-
-```typescript
-// ❌ Bad: Sequential with shared context
-const research = await agent.query('Research X');
-const analysis = await agent.query('Analyze Y based on research');
-
-// ✅ Good: Parallel with isolated contexts
-const [research, analysis] = await Promise.all([
-  researchAgent.query('Research X'),
-  analysisAgent.query('Analyze Y')
-]);
-
-const synthesis = await synthesisAgent.query(
-  `Combine: ${research} + ${analysis}`
-);
-```
-
-### 4. Start Simple, Add Complexity
-
-```typescript
-// Phase 1: Basic tools
-allowedTools: ['FileRead', 'FileWrite']
-
-// Phase 2: Add capabilities
-allowedTools: ['FileRead', 'FileWrite', 'Bash', 'WebSearch']
-
-// Phase 3: Custom integrations
-mcpServers: { 'custom': customToolServer }
-
-// Phase 4: Full orchestration
-agents: { 'specialist1': config1, 'specialist2': config2 }
-```
-
-### 5. Verification Over Trust
-
-```typescript
-async function verifyWork(result: string) {
-  // Code linting
-  const lintResult = await runLinter(result);
-
-  // Unit tests
-  const testResult = await runTests(result);
-
-  // Secondary model evaluation
-  const reviewAgent = createAgent({
-    systemPrompt: 'You review code quality'
-  });
-  const review = await reviewAgent.query(`Review: ${result}`);
-
-  return {
-    passed: lintResult.ok && testResult.passed && review.approved,
-    feedback: combineeFeedback(lintResult, testResult, review)
-  };
-}
-```
-
-## Recommended Architecture
-
-```typescript
-┌──────────────────────────────────────────────────────────┐
-│                    Orchestrator                          │
-│  - Task decomposition (plan mode)                        │
-│  - Agent selection                                       │
-│  - Result synthesis                                      │
-└──────────────────────────────────────────────────────────┘
-                         │
-        ┌────────────────┼────────────────┐
-        ▼                ▼                ▼
-   ┌─────────┐      ┌─────────┐     ┌─────────┐
-   │Research │      │  Code   │     │  Data   │
-   │ Agent   │      │ Agent   │     │ Agent   │
-   └─────────┘      └─────────┘     └─────────┘
-        │                │                │
-        └────────────────┼────────────────┘
-                         ▼
-              ┌──────────────────┐
-              │   Tool Layer     │
-              │  - File Ops      │
-              │  - Bash          │
-              │  - Web Tools     │
-              │  - MCP Custom    │
-              └──────────────────┘
-                         │
-        ┌────────────────┼────────────────┐
-        ▼                ▼                ▼
-   ┌─────────┐      ┌─────────┐     ┌─────────┐
-   │ Logging │      │ Metrics │     │ Storage │
-   └─────────┘      └─────────┘     └─────────┘
-```
-
-## ROI Calculation
-
-### Current State
-- **Capabilities**: Text generation only
-- **Reliability**: ~60% success rate
-- **Performance**: 30-60s perceived latency
-- **Scalability**: 3 agents max
-- **Cost Visibility**: None
-- **Debugging**: Manual log inspection
-
-### With Improvements
-- **Capabilities**: Full tooling (files, bash, web, custom)
-- **Reliability**: 99.9% with retry logic
-- **Performance**: 5-10s perceived (streaming)
-- **Scalability**: Unlimited with orchestration
-- **Cost Visibility**: Real-time tracking
-- **Debugging**: Structured logs + metrics
-
-### Investment
-- **Week 1**: Foundation (tools, errors, streaming) - 40 hours
-- **Week 2**: Observability (hooks, logging, metrics) - 40 hours
-- **Week 3**: Advanced (orchestration, subagents, sessions) - 40 hours
-- **Week 4**: Production (permissions, MCP, rate limits) - 40 hours
-- **Total**: 160 hours (1 month)
-
-### Return
-- **10x capabilities** (text → full automation)
-- **3x reliability** (60% → 99%+)
-- **5x performance** (perceived, streaming)
-- **Infinite scale** (vs 3 agent limit)
-- **Cost savings** (30% via monitoring)
-
-**Payback Period**: 2 months
-**5-Year ROI**: 500%+
-
-## Immediate Next Steps
-
-1. **Quick Wins** (Week 1, 6.5 hours)
-   - Add tool integration (2h)
-   - Enable streaming (1h)
-   - Add error handling (2h)
-   - Add basic logging (1h)
-   - Add health check (30m)
-
-2. **Production Baseline** (Week 2)
-   - Implement hook system
-   - Add structured logging
-   - Set up Prometheus metrics
-   - Add Docker monitoring stack
-
-3. **Advanced Features** (Week 3)
-   - Hierarchical orchestration
-   - Subagent support
-   - Session management
-   - Context optimization
-
-4. **Enterprise Ready** (Week 4)
-   - Permission system
-   - MCP custom tools
-   - Rate limiting
-   - Cost tracking
-   - Security audit
-
-## Key Learnings
-
-1. **SDK is Production-Ready**: Anthropic built this for Claude Code - it's battle-tested
-2. **We're Using 5%**: Current implementation barely scratches the surface
-3. **Quick Wins Available**: 6.5 hours → 10x improvement
-4. **Tool Integration is Critical**: Without tools, agents just generate text
-5. **Hooks Enable Everything**: Observability, security, optimization all via hooks
-6. **Subagents Scale Better**: Parallel isolated contexts beat sequential shared context
-7. **Start Simple**: Don't need all features day 1, but need core features (tools, errors, streaming)
-
-## References
-
-- [Claude Agent SDK Docs](https://docs.claude.com/en/api/agent-sdk/overview)
-- [Building Agents Engineering Post](https://www.anthropic.com/engineering/building-agents-with-the-claude-agent-sdk)
-- [Claude Code Autonomy Post](https://www.anthropic.com/news/enabling-claude-code-to-work-more-autonomously)
-- [Sonnet 4.5 Announcement](https://www.anthropic.com/news/claude-sonnet-4-5)
-- [Multi-Agent Research System](https://www.anthropic.com/engineering/built-multi-agent-research-system)
-- [Model Context Protocol](https://modelcontextprotocol.io/)

package/agentic-flow/docs/guides/.claude-flow/metrics/agent-metrics.json

@@ -1 +0,0 @@
-{}

package/agentic-flow/docs/guides/.claude-flow/metrics/performance.json

@@ -1,9 +0,0 @@
-{
-  "startTime": 1759674877006,
-  "totalTasks": 1,
-  "successfulTasks": 1,
-  "failedTasks": 0,
-  "totalAgents": 0,
-  "activeAgents": 0,
-  "neuralEvents": 0
-}

package/agentic-flow/docs/guides/.claude-flow/metrics/task-metrics.json

@@ -1,10 +0,0 @@
-[
-  {
-    "id": "cmd-hooks-1759674877140",
-    "type": "hooks",
-    "success": true,
-    "duration": 7.498020000000054,
-    "timestamp": 1759674877147,
-    "metadata": {}
-  }
-]