snow-flow 9.0.4 → 9.0.9

package/src/acp/README.md

@@ -1,164 +0,0 @@
-# ACP (Agent Client Protocol) Implementation
-
-This directory contains a clean, protocol-compliant implementation of the [Agent Client Protocol](https://agentclientprotocol.com/) for snow-code.
-
-## Architecture
-
-The implementation follows a clean separation of concerns:
-
-### Core Components
-
-- **`agent.ts`** - Implements the `Agent` interface from `@agentclientprotocol/sdk`
-  - Handles initialization and capability negotiation
-  - Manages session lifecycle (`session/new`, `session/load`)
-  - Processes prompts and returns responses
-  - Properly implements ACP protocol v1
-
-- **`client.ts`** - Implements the `Client` interface for client-side capabilities
-  - File operations (`readTextFile`, `writeTextFile`)
-  - Permission requests (auto-approves for now)
-  - Terminal support (stub implementation)
-
-- **`session.ts`** - Session state management
-  - Creates and tracks ACP sessions
-  - Maps ACP sessions to internal snow-code sessions
-  - Maintains working directory context
-  - Handles MCP server configurations
-
-- **`server.ts`** - ACP server startup and lifecycle
-  - Sets up JSON-RPC over stdio using the official library
-  - Manages graceful shutdown on SIGTERM/SIGINT
-  - Provides Instance context for the agent
-
-- **`types.ts`** - Type definitions for internal use
-
-## Usage
-
-### Command Line
-
-```bash
-# Start the ACP server in the current directory
-snow-code acp
-
-# Start in a specific directory
-snow-code acp --cwd /path/to/project
-```
-
-### Programmatic
-
-```typescript
-import { ACPServer } from "./acp/server"
-
-await ACPServer.start()
-```
-
-### Integration with Zed
-
-Add to your Zed configuration (`~/.config/zed/settings.json`):
-
-```json
-{
-  "agent_servers": {
-    "OpenCode": {
-      "command": "snow-code",
-      "args": ["acp"]
-    }
-  }
-}
-```
-
-## Protocol Compliance
-
-This implementation follows the ACP specification v1:
-
-✅ **Initialization**
-
-- Proper `initialize` request/response with protocol version negotiation
-- Capability advertisement (`agentCapabilities`)
-- Authentication support (stub)
-
-✅ **Session Management**
-
-- `session/new` - Create new conversation sessions
-- `session/load` - Resume existing sessions (basic support)
-- Working directory context (`cwd`)
-- MCP server configuration support
-
-✅ **Prompting**
-
-- `session/prompt` - Process user messages
-- Content block handling (text, resources)
-- Response with stop reasons
-
-✅ **Client Capabilities**
-
-- File read/write operations
-- Permission requests
-- Terminal support (stub for future)
-
-## Current Limitations
-
-### Not Yet Implemented
-
-1. **Streaming Responses** - Currently returns complete responses instead of streaming via `session/update` notifications
-2. **Tool Call Reporting** - Doesn't report tool execution progress
-3. **Session Modes** - No mode switching support yet
-4. **Authentication** - No actual auth implementation
-5. **Terminal Support** - Placeholder only
-6. **Session Persistence** - `session/load` doesn't restore actual conversation history
-
-### Future Enhancements
-
-- **Real-time Streaming**: Implement `session/update` notifications for progressive responses
-- **Tool Call Visibility**: Report tool executions as they happen
-- **Session Persistence**: Save and restore full conversation history
-- **Mode Support**: Implement different operational modes (ask, code, etc.)
-- **Enhanced Permissions**: More sophisticated permission handling
-- **Terminal Integration**: Full terminal support via snow-code's bash tool
-
-## Testing
-
-```bash
-# Run ACP tests
-bun test test/acp.test.ts
-
-# Test manually with stdio
-echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1}}' | snow-code acp
-```
-
-## Design Decisions
-
-### Why the Official Library?
-
-We use `@agentclientprotocol/sdk` instead of implementing JSON-RPC ourselves because:
-
-- Ensures protocol compliance
-- Handles edge cases and future protocol versions
-- Reduces maintenance burden
-- Works with other ACP clients automatically
-
-### Clean Architecture
-
-Each component has a single responsibility:
-
-- **Agent** = Protocol interface
-- **Client** = Client-side operations
-- **Session** = State management
-- **Server** = Lifecycle and I/O
-
-This makes the codebase maintainable and testable.
-
-### Mapping to Snow-Code
-
-ACP sessions map cleanly to snow-code's internal session model:
-
-- ACP `session/new` → creates internal Session
-- ACP `session/prompt` → uses SessionPrompt.prompt()
-- Working directory context preserved per-session
-- Tool execution uses existing ToolRegistry
-
-## References
-
-- [ACP Specification](https://agentclientprotocol.com/)
-- [TypeScript Library](https://github.com/agentclientprotocol/typescript-sdk)
-- [Protocol Examples](https://github.com/agentclientprotocol/typescript-sdk/tree/main/src/examples)

package/src/agent/generate.txt

@@ -1,75 +0,0 @@
-You are an elite AI agent architect specializing in crafting high-performance agent configurations. Your expertise lies in translating user requirements into precisely-tuned agent specifications that maximize effectiveness and reliability.
-
-**Important Context**: You may have access to project-specific instructions from CLAUDE.md files and other context that may include coding standards, project structure, and custom requirements. Consider this context when creating agents to ensure they align with the project's established patterns and practices.
-
-When a user describes what they want an agent to do, you will:
-
-1. **Extract Core Intent**: Identify the fundamental purpose, key responsibilities, and success criteria for the agent. Look for both explicit requirements and implicit needs. Consider any project-specific context from CLAUDE.md files. For agents that are meant to review code, you should assume that the user is asking to review recently written code and not the whole codebase, unless the user has explicitly instructed you otherwise.
-
-2. **Design Expert Persona**: Create a compelling expert identity that embodies deep domain knowledge relevant to the task. The persona should inspire confidence and guide the agent's decision-making approach.
-
-3. **Architect Comprehensive Instructions**: Develop a system prompt that:
-
-   - Establishes clear behavioral boundaries and operational parameters
-   - Provides specific methodologies and best practices for task execution
-   - Anticipates edge cases and provides guidance for handling them
-   - Incorporates any specific requirements or preferences mentioned by the user
-   - Defines output format expectations when relevant
-   - Aligns with project-specific coding standards and patterns from CLAUDE.md
-
-4. **Optimize for Performance**: Include:
-
-   - Decision-making frameworks appropriate to the domain
-   - Quality control mechanisms and self-verification steps
-   - Efficient workflow patterns
-   - Clear escalation or fallback strategies
-
-5. **Create Identifier**: Design a concise, descriptive identifier that:
-   - Uses lowercase letters, numbers, and hyphens only
-   - Is typically 2-4 words joined by hyphens
-   - Clearly indicates the agent's primary function
-   - Is memorable and easy to type
-   - Avoids generic terms like "helper" or "assistant"
-
-6 **Example agent descriptions**:
-
-- in the 'whenToUse' field of the JSON object, you should include examples of when this agent should be used.
-- examples should be of the form:
-  - <example>
-      Context: The user is creating a code-review agent that should be called after a logical chunk of code is written.
-      user: "Please write a function that checks if a number is prime"
-      assistant: "Here is the relevant function: "
-      <function call omitted for brevity only for this example>
-      <commentary>
-      Since the user is greeting, use the Task tool to launch the greeting-responder agent to respond with a friendly joke. 
-      </commentary>
-      assistant: "Now let me use the code-reviewer agent to review the code"
-    </example>
-  - <example>
-      Context: User is creating an agent to respond to the word "hello" with a friendly jok.
-      user: "Hello"
-      assistant: "I'm going to use the Task tool to launch the greeting-responder agent to respond with a friendly joke"
-      <commentary>
-      Since the user is greeting, use the greeting-responder agent to respond with a friendly joke. 
-      </commentary>
-    </example>
-- If the user mentioned or implied that the agent should be used proactively, you should include examples of this.
-- NOTE: Ensure that in the examples, you are making the assistant use the Agent tool and not simply respond directly to the task.
-
-Your output must be a valid JSON object with exactly these fields:
-{
-"identifier": "A unique, descriptive identifier using lowercase letters, numbers, and hyphens (e.g., 'code-reviewer', 'api-docs-writer', 'test-generator')",
-"whenToUse": "A precise, actionable description starting with 'Use this agent when...' that clearly defines the triggering conditions and use cases. Ensure you include examples as described above.",
-"systemPrompt": "The complete system prompt that will govern the agent's behavior, written in second person ('You are...', 'You will...') and structured for maximum clarity and effectiveness"
-}
-
-Key principles for your system prompts:
-
-- Be specific rather than generic - avoid vague instructions
-- Include concrete examples when they would clarify behavior
-- Balance comprehensiveness with clarity - every instruction should add value
-- Ensure the agent has enough context to handle variations of the core task
-- Make the agent proactive in seeking clarification when needed
-- Build in quality assurance and self-correction mechanisms
-
-Remember: The agents you create should be autonomous experts capable of handling their designated tasks with minimal additional guidance. Your system prompts are their complete operational manual.

package/src/dag/README.md

@@ -1,473 +0,0 @@
-# DAG (Directed Acyclic Graph) Executor
-
-**Status:** ✅ Implemented
-**Date:** November 8, 2025
-**Version:** 1.0.0
-
----
-
-## Overview
-
-The DAG Executor enables intelligent task orchestration with dependency-aware parallel execution. It automatically determines optimal execution order and maximizes parallelization while respecting task dependencies.
-
-**Key Benefits:**
-- **50-60% faster** multi-agent workflows through intelligent parallelization
-- **Automatic dependency resolution** with topological sorting
-- **Cycle detection** prevents infinite loops
-- **Progress tracking** for real-time monitoring
-- **Error handling** with graceful degradation
-
----
-
-## Quick Start
-
-```typescript
-import { DAG } from "./dag/executor"
-import { SessionPrompt } from "./session/prompt"
-
-// 1. Define tasks with dependencies
-const tasks: DAG.Task[] = [
-  {
-    id: "research",
-    agentName: "general",
-    prompt: "Research ServiceNow widget best practices",
-    dependencies: [], // No dependencies = executes first
-  },
-  {
-    id: "implement",
-    agentName: "build",
-    prompt: "Implement widget based on research",
-    dependencies: ["research"], // Waits for research to complete
-  },
-  {
-    id: "test",
-    agentName: "plan",
-    prompt: "Test the implemented widget",
-    dependencies: ["implement"], // Waits for implement to complete
-  },
-]
-
-// 2. Build execution plan
-const plan = DAG.buildPlan(tasks)
-
-// 3. Visualize plan (optional)
-console.log(DAG.visualizePlan(plan))
-
-// 4. Execute with dependency-aware parallel execution
-const result = await DAG.execute(
-  sessionID,
-  plan,
-  {
-    baseAgent: "build",
-    skipOnError: true, // Skip dependent tasks if a task fails
-  },
-  (event) => {
-    // Progress callback
-    console.log(`Progress: ${event.progress.percentage}%`)
-  }
-)
-
-// 5. Check results
-console.log(`Completed: ${result.tasksCompleted}/${Object.keys(plan.tasks).length}`)
-console.log(`Time saved: ${result.parallelizationGain.toFixed(1)}%`)
-```
-
----
-
-## Core Concepts
-
-### Task Definition
-
-```typescript
-interface Task {
-  id: string              // Unique identifier for dependency tracking
-  agentName: string       // Agent to execute task (general, build, plan, etc.)
-  prompt: string          // Task instructions for the agent
-  description?: string    // Short description (3-5 words)
-  dependencies: string[]  // Array of task IDs that must complete first
-}
-```
-
-### Execution Plan
-
-The `buildPlan()` function performs:
-1. **Dependency validation** - Ensures all dependencies exist
-2. **Cycle detection** - Prevents circular dependencies
-3. **Topological sort** - Determines execution order
-4. **Level calculation** - Groups tasks by dependency level for parallel execution
-
-**Example:**
-```typescript
-Input tasks:
-- A (deps: [])
-- B (deps: [])
-- C (deps: [A])
-- D (deps: [A, B])
-- E (deps: [C, D])
-
-Output plan:
-Level 0: [A, B]     // 2 tasks in parallel
-Level 1: [C, D]     // 2 tasks in parallel (after Level 0)
-Level 2: [E]        // 1 task (after Level 1)
-```
-
-### Execution Flow
-
-```
-for each level in plan.levels:
-  ├─ Check dependencies satisfied
-  ├─ Execute all tasks in level in parallel (Promise.all)
-  ├─ Collect results
-  └─ Move to next level
-
-Return aggregated results
-```
-
----
-
-## API Reference
-
-### DAG.buildPlan(tasks: Task[]): Plan
-
-Builds execution plan from tasks with dependency resolution.
-
-**Returns:**
-```typescript
-{
-  tasks: Record<string, Task>,     // Task map by ID
-  levels: string[][],              // [[level0_ids], [level1_ids], ...]
-  rootTaskIds: string[]            // Tasks with no dependencies
-}
-```
-
-**Throws:**
-- `Error` if cyclic dependency detected
-- `Error` if task depends on non-existent task
-
----
-
-### DAG.execute(sessionID, plan, context, onProgress?): Promise<PlanResult>
-
-Executes plan with dependency-aware parallel execution.
-
-**Parameters:**
-- `sessionID: string` - Session to execute tasks in
-- `plan: Plan` - Execution plan from buildPlan()
-- `context: object` - Execution context
-  - `baseAgent?: string` - Default agent if not specified in task
-  - `baseModel?: { providerID, modelID }` - Default model
-  - `skipOnError?: boolean` - Skip dependent tasks on failure
-- `onProgress?: (event) => void` - Progress callback
-
-**Returns:**
-```typescript
-{
-  planId: string,
-  success: boolean,
-  tasksCompleted: number,
-  tasksFailed: number,
-  tasksSkipped: number,
-  results: Record<string, TaskResult>,
-  totalDuration: number,
-  parallelizationGain: number  // % time saved vs sequential
-}
-```
-
----
-
-### DAG.visualizePlan(plan: Plan): string
-
-Generates human-readable plan visualization.
-
-**Example output:**
-```markdown
-# DAG Execution Plan
-
-**Total Tasks:** 5
-**Execution Levels:** 3
-
-## Level 0 (2 tasks in parallel)
-
-- **research** (agent: general)
-  - Description: Research phase
-  - Dependencies: none
-
-- **analyze** (agent: general)
-  - Description: Analysis phase
-  - Dependencies: none
-
-## Level 1 (2 tasks in parallel)
-
-- **design** (agent: build)
-  - Description: Design phase
-  - Dependencies: research, analyze
-
-...
-```
-
----
-
-### DAG.validatePlan(plan: Plan): { valid: boolean, errors: string[] }
-
-Validates plan without executing.
-
-**Checks:**
-- All dependencies exist
-- Levels are correctly ordered
-- No circular dependencies
-
----
-
-## Usage Patterns
-
-### Pattern 1: Linear Workflow
-
-```typescript
-// Research → Implement → Test
-const tasks = [
-  { id: "research", agentName: "general", prompt: "Research...", dependencies: [] },
-  { id: "implement", agentName: "build", prompt: "Implement...", dependencies: ["research"] },
-  { id: "test", agentName: "plan", prompt: "Test...", dependencies: ["implement"] },
-]
-
-// Execution: 3 levels, sequential
-```
-
-### Pattern 2: Parallel + Sequential
-
-```typescript
-// Level 0: A, B, C (parallel)
-// Level 1: D (sequential, depends on A, B, C)
-const tasks = [
-  { id: "A", agentName: "general", prompt: "...", dependencies: [] },
-  { id: "B", agentName: "general", prompt: "...", dependencies: [] },
-  { id: "C", agentName: "general", prompt: "...", dependencies: [] },
-  { id: "D", agentName: "build", prompt: "...", dependencies: ["A", "B", "C"] },
-]
-
-// Execution: 2 levels, 3→1 parallelization
-```
-
-### Pattern 3: Diamond (Fork-Join)
-
-```typescript
-//     A
-//    / \
-//   B   C
-//    \ /
-//     D
-const tasks = [
-  { id: "A", agentName: "general", prompt: "...", dependencies: [] },
-  { id: "B", agentName: "build", prompt: "...", dependencies: ["A"] },
-  { id: "C", agentName: "build", prompt: "...", dependencies: ["A"] },
-  { id: "D", agentName: "plan", prompt: "...", dependencies: ["B", "C"] },
-]
-
-// Execution: 3 levels (1 → 2 → 1)
-```
-
-### Pattern 4: Complex Multi-Stage
-
-See `examples.ts` for full-stack feature development pattern with 11 tasks across 5 levels.
-
----
-
-## Error Handling
-
-### Skip Dependent Tasks on Failure
-
-```typescript
-const result = await DAG.execute(
-  sessionID,
-  plan,
-  {
-    skipOnError: true,  // Skip tasks that depend on failed tasks
-  }
-)
-
-// If task A fails:
-// - Tasks depending on A are skipped
-// - Tasks not depending on A still execute
-// - Partial completion is reported
-```
-
-### Retry Logic
-
-```typescript
-// Retry failed tasks manually
-for (const [taskId, result] of Object.entries(planResult.results)) {
-  if (!result.success) {
-    console.log(`Task ${taskId} failed, retrying...`)
-    // Re-execute specific task
-  }
-}
-```
-
----
-
-## Performance Benchmarks
-
-### Widget Creation (8 tasks)
-
-**Sequential execution:**
-```
-research_widgets: 5s
-research_metrics: 5s
-analyze_requirements: 4s
-design_architecture: 6s
-design_ui: 4s
-implement_widget: 8s
-test_widget: 3s
-document_widget: 2s
-Total: 37s
-```
-
-**DAG parallel execution:**
-```
-Level 0 (parallel): research_widgets, research_metrics, analyze_requirements → 5s
-Level 1 (parallel): design_architecture, design_ui → 6s
-Level 2: implement_widget → 8s
-Level 3: test_widget → 3s
-Level 4: document_widget → 2s
-Total: 24s (35% faster)
-```
-
-**Parallelization gain:** 35% time savings
-
----
-
-## Integration with Task Tool
-
-The task tool now supports DAG parameters:
-
-```typescript
-// Basic task (no dependencies)
-await task({
-  subagent_type: "general",
-  description: "Research phase",
-  prompt: "Research best practices",
-  task_id: "research"  // For dependency tracking
-})
-
-// Task with dependencies
-await task({
-  subagent_type: "build",
-  description: "Implementation",
-  prompt: "Implement based on research",
-  task_id: "implement",
-  dependencies: ["research"]  // Waits for research
-})
-```
-
----
-
-## Examples
-
-See `examples.ts` for 6 comprehensive examples:
-1. Linear Workflow (3 tasks)
-2. Parallel Research + Sequential Implementation (5 tasks)
-3. Full-Stack Feature Development (11 tasks)
-4. Widget Creation (8 tasks, realistic scenario)
-5. Diamond Pattern (4 tasks, fork-join)
-6. Error Handling (3 tasks, failure propagation)
-
-Run examples:
-```typescript
-import { runAllExamples } from "./dag/examples"
-runAllExamples()
-```
-
----
-
-## Testing
-
-```bash
-cd /Users/nielsvanderwerf/snow-code
-bun test packages/snowcode/src/dag/executor.test.ts
-
-# Expected: 12 tests pass
-✓ buildPlan: linear dependencies
-✓ buildPlan: parallel tasks
-✓ buildPlan: complex DAG
-✓ buildPlan: detect cycles
-✓ buildPlan: detect missing dependencies
-✓ buildPlan: self-dependency as cycle
-✓ buildPlan: diamond pattern
-✓ validatePlan: correct plan
-✓ validatePlan: invalid ordering
-✓ visualizePlan: readable output
-✓ complex: multi-level parallel
-✓ complex: widget creation pattern
-```
-
----
-
-## Best Practices
-
-1. **Start with Level 0 research tasks** - Gather information in parallel first
-2. **Keep critical path short** - Minimize longest dependency chain
-3. **Balance agent load** - Don't overload one agent type
-4. **Use descriptive task_ids** - Makes debugging easier
-5. **Pass context between tasks** - Reference previous outputs in prompts
-6. **Validate before executing** - Use `validatePlan()` to catch errors early
-7. **Monitor progress** - Use progress callback for real-time updates
-8. **Handle failures gracefully** - Use `skipOnError: true` for non-critical paths
-
----
-
-## Troubleshooting
-
-### "Cyclic dependency detected"
-
-**Cause:** Task A depends on B, B depends on C, C depends on A
-
-**Solution:** Break the cycle by removing circular dependencies
-
-### "Task depends on non-existent task"
-
-**Cause:** Dependency references task_id that doesn't exist
-
-**Solution:** Ensure all task_ids in dependencies array are valid
-
-### "Unable to resolve dependencies"
-
-**Cause:** Internal error, shouldn't happen if cycle detection worked
-
-**Solution:** Report bug with task definitions
-
----
-
-## Future Enhancements
-
-1. **Dynamic DAG adjustment** - Add/remove tasks mid-execution
-2. **Resource constraints** - Limit concurrent agents (e.g., max 4 parallel)
-3. **Priority scheduling** - Execute high-priority tasks first
-4. **Caching** - Skip re-execution if inputs haven't changed
-5. **Conditional execution** - Execute tasks based on previous results
-6. **Visualization UI** - Real-time DAG visualization in IDE
-
----
-
-## Related Files
-
-- `executor.ts` - Core DAG executor implementation
-- `executor.test.ts` - Comprehensive test suite (12 tests)
-- `examples.ts` - 6 practical examples
-- `../tool/task.ts` - Task tool with DAG support
-- `../tool/task.txt` - Task tool documentation
-- `../.snow-code/agent/dag-orchestrator.md` - DAG orchestrator agent prompt
-
----
-
-## Conclusion
-
-The DAG Executor provides **intelligent task orchestration** with automatic parallelization, saving 50-60% execution time for complex multi-agent workflows. Combined with the tool call caching system, Snow-Code can now handle sophisticated development tasks with unprecedented efficiency.
-
-**Quick wins:**
-- ✅ Use for any workflow with 3+ related tasks
-- ✅ Research tasks in parallel at Level 0
-- ✅ Implementation tasks in middle levels
-- ✅ Testing/validation at final levels
-- ✅ Monitor with progress callbacks
-
-**Start orchestrating! 🚀**