@ddse/acm-aicoder 0.5.0

package/README.md

@@ -0,0 +1,490 @@
+# ACM AI Coder - Phase 2
+
+<!-- markdownlint-disable MD024 MD032 -->
+
+An advanced AI-powered developer workflow automation tool with an interactive full-screen TUI that showcases the complete ACM (Agentic Contract Model) framework v0.5.
+
+## Overview
+
+The ACM AI Coder Phase 2 introduces an **interactive-only experience** with a three-column terminal UI:
+
+- **Left Column**: Chat interface with streaming planner and nucleus reasoning
+- **Middle Column**: Current goal, tasks with live status, and budget metrics
+- **Right Column**: Event stream showing ledger entries, tool calls, and context updates
+
+### Key Features
+
+- ✅ **Interactive-Only TUI**: Full-screen terminal interface with real-time updates
+- ✅ **Mandatory Configuration**: Requires `--provider`, `--model`, and `--workspace` flags with optional `--base-url`
+- ✅ **Budget Governance**: Pre-inference cost checks with live spend tracking
+- ✅ **Streaming Reasoning**: Watch planner and nucleus think in real-time
+- ✅ **File Mentions**: Reference workspace files with `#path/to/file` syntax
+- ✅ **Memory Lifecycle**: Automatic cleanup and replay bundle persistence
+- ✅ **ACM Framework Integration**: Built entirely on ACM primitives (planner, runtime, nucleus, ledger)
+
+## Installation
+
+```bash
+# From the workspace root
+pnpm install
+
+# Build the package
+pnpm --filter @ddse/acm-aicoder build
+```
+
+## Quick Start
+
+### Phase 2 Interactive Mode (Recommended)
+
+```bash
+# Start the interactive AI Coder
+acm-aicoder \
+  --provider vllm \
+  --model Qwen/Qwen3-Coder-30B-A3B-Instruct-FP8 \
+  --base-url http://localhost:8001/v1 \
+  --workspace /path/to/your/project
+```
+
+**Required Parameters:**
+
+- `--provider <ollama|vllm>` - LLM provider (default: ollama)
+- `--model <name>` - Model identifier provided by the selected provider
+- `--workspace <path>` - Project workspace root directory (must exist and be a readable directory)
+
+**Optional Parameters:**
+
+- `--base-url <url>` - Override provider base URL when using a custom endpoint
+- `--temperature <0-2>` - LLM temperature (default: 0.7)
+- `--seed <number>` - Random seed for reproducibility
+- `--plans <1|2>` - Number of alternative plans to generate (default: 1)
+
+### Commands in Interactive Mode
+
+Once running, you can use these commands:
+
+- `/exit`, `/quit` - Exit the application
+- `/help` - Show available commands
+- `/budget` - Display detailed budget information
+- `/context` - Show current context information
+- `/reset` - Reset the session (clear goal and tasks)
+- `#path/to/file` - Mention files from your workspace in chat
+
+**Example Session:**
+
+```text
+> Analyze the src/index.ts file and find potential bugs
+
+[Planner will reason about the task, select appropriate capabilities]
+[Tasks will execute with live status updates]
+[Events will stream in the right column]
+```
+
+## ACM Framework Integration
+
+Phase 2 is built strictly on ACM v0.5 components:
+
+### Planner & Nucleus
+
+- Chat pane visualizes ACM planner tool-call loops and nucleus inferences in real-time
+- Streaming tokens show reasoning as it happens
+- Budget checks run before each inference
+
+#### Nucleus configuration requirements
+
+- Every runtime invocation now passes a `nucleusFactory` and `nucleusConfig` to `executePlan`. The CLI wires these from the `--llm-provider`, `--llm-model`, `--llm-base-url`, and `--llm-engine` flags to build a shared `DeterministicNucleus` instance.
+- If you embed AI Coder components elsewhere, supply your own factory that returns a `Nucleus` subclass and include at minimum an `llmCall` block with `provider`, `model`, and token limits.
+- Tests and examples provide lightweight stub nuclei; use them as a reference when authoring new scripts or integrations.
+
+### Tools & Tasks
+
+- All tools extend `Tool<I, O>` from `@ddse/acm-sdk`
+- Tasks extend `Task<I, O>` and leverage context builder
+- Tool call envelopes logged to ledger for determinism
+
+### Context Packets
+
+- Context orchestration uses Phase 4 `ContextBuilder`
+- Immutable packets with provenance and sources
+- View current context with `/context` command
+
+### Ledger & Replay
+
+- Event stream pane visualizes ledger entries
+- Replay bundles saved automatically to `.aicoder/replays/`
+- Includes session config, ledger, and budget summary
+
+### Budget Enforcement
+
+- BudgetManager enforces spending limits before inference
+- Provider metadata for OpenAI, Anthropic, Ollama, and more
+- Real-time budget display in Tasks column
+
+## Architecture
+
+The ACM AI Coder is built on the ACM framework and showcases all its capabilities:
+
+### ACM Framework Integration
+
+1. **SDK Layer**: All tools and tasks extend `Tool<I, O>` and `Task<I, O>` from `@ddse/acm-sdk`
+2. **Context Engine**: Intelligent repository understanding feeds into planning
+3. **Planning Phase**: LLM analyzes goal + context, generates Plan-A and Plan-B
+4. **Runtime Execution**: `@ddse/acm-runtime` executes plans with streaming, checkpoints, and verification
+5. **Policy Engine**: Safety guards with path restrictions and action gating
+6. **Replay Bundle**: Complete audit trail via `@ddse/acm-replay`
+
+### Workflow
+
+1. **Indexing**: Scan workspace, extract symbols, dependencies, and tests
+2. **Context Generation**: Create context pack with relevant files and symbols
+3. **Planning**: Feed context to LLM planner for multi-step plan generation
+4. **Approval**: User approves plan and operations that modify code
+5. **Execution**: ACM runtime executes with streaming progress
+6. **Checkpointing**: Automatic checkpoints after each task
+7. **Verification**: Tasks verify outputs match expectations
+
+### Safety Features
+
+- **Dry Run Mode**: Preview all changes without modifying files
+- **Approval Workflow**: User approval required for file modifications
+- **Policy Engine**: Path allowlists and action restrictions
+- **Automatic Backups**: `.backup` files created before edits
+- **Checkpointing**: Resume from any point if execution is interrupted
+- **Context Limits**: File size and result count limits prevent overload
+
+## How It Showcases ACM
+
+This tool demonstrates every aspect of the ACM framework:
+
+- **Capability Model**: Tasks are registered as capabilities with clear contracts
+- **Tool Composition**: Tasks compose multiple tools to accomplish goals
+- **Context Packets**: Immutable context with content-addressable refs
+- **Plan Alternatives**: Planner generates Plan-A and Plan-B with rationale
+- **Deterministic Execution**: Runtime executes plans with guards and verification
+- **Policy Integration**: Pre/post hooks for safety enforcement
+- **Memory Ledger**: Complete audit trail of all decisions
+- **Streaming**: Real-time progress via StreamSink
+- **Resumability**: FileCheckpointStore enables resume from crashes
+
+## Development
+
+### Running Tests
+
+```bash
+# Run integration tests
+pnpm --filter @ddse/acm-aicoder test
+```
+
+<!-- markdownlint-enable MD024 MD032 -->
+
+### Building
+
+```bash
+# Build TypeScript
+pnpm --filter @ddse/acm-aicoder build
+
+# Watch mode for development
+pnpm --filter @ddse/acm-aicoder dev
+```
+
+## Examples
+
+### Example 1: Deep Workspace Analysis
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal analyze --workspace .
+```
+
+This will:
+
+1. Index all files in the workspace (respecting gitignore)
+2. Extract symbols (functions, classes, interfaces)
+3. Map dependencies from package.json
+4. Identify test files and their targets
+5. Generate a comprehensive report with statistics
+
+Output includes:
+
+- Total files scanned
+- Code files by language
+- Symbols extracted (functions, classes, etc.)
+- Dependencies found
+- Test file mappings
+
+### Example 2: Search for Code Patterns
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal custom
+# Enter: "Search for all error handling patterns in the codebase"
+```
+
+This will:
+
+1. Build BM25 index of code files
+2. Search for "error handling try catch" patterns
+3. Return top-k results with context
+4. Show file paths, line numbers, and code snippets
+
+### Example 3: Implement a New Function
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal custom
+# Enter: "Implement a function to validate email addresses in src/utils.ts"
+```
+
+This will:
+
+1. Read the target file
+2. Analyze existing code patterns
+3. Generate function implementation (with LLM)
+4. Show diff preview
+5. Request approval
+6. Apply changes with automatic backup
+
+### Example 4: Refactor Symbol Names
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal custom
+# Enter: "Rename function getUserData to fetchUserData everywhere"
+```
+
+This will:
+
+1. Search for all occurrences of the symbol
+2. Generate list of affected files
+3. Show preview of changes
+4. Request approval
+5. Apply rename across all files (with backup)
+
+### Example 5: Fix TypeScript Errors
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal custom
+# Enter: "Fix all TypeScript compilation errors"
+```
+
+This will:
+
+1. Run build to collect TypeScript errors
+2. Analyze each error with context
+3. Generate fixes (with LLM)
+4. Show diffs for each fix
+5. Request approval
+6. Apply fixes and verify build succeeds
+
+### Example 6: Generate Unit Tests
+
+```bash
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal custom
+# Enter: "Generate unit tests for the validateEmail function in src/utils.ts"
+```
+
+This will:
+
+1. Read and analyze the target function
+2. Generate test cases (with LLM)
+3. Create test file (e.g., `src/utils.test.ts`)
+4. Show preview
+5. Request approval
+6. Apply and run tests to verify
+
+### Example 7: Resume from Checkpoint
+
+```bash
+# Start a long operation
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --goal implementFeature
+
+# If interrupted (Ctrl+C), resume later:
+pnpm --filter @ddse/acm-aicoder exec acm-aicoder --resume run-1696348800000
+```
+
+The resume will:
+
+1. Load checkpoint from disk
+2. Restore plan and completed tasks
+3. Continue from the next task
+4. Maintain all context and state
+
+## Key Components
+
+### Context Engine
+
+Located in `src/context/`:
+
+- **WorkspaceIndexer**: Fast file scanning with caching
+- **SymbolExtractor**: Parse TS/JS for symbols
+- **DependencyMapper**: Extract package.json dependencies
+- **TestMapper**: Identify test files
+- **CodeSearch**: BM25-based semantic search
+- **ContextPackGenerator**: Generate planning context
+
+### Tools V2
+
+Located in `src/tools-v2/`:
+
+- **read-tools.ts**: FileStatTool, FileReadToolV2, FileReadLinesTool, DiffTool
+- **search-tools.ts**: CodeSearchTool, GrepTool
+- **edit-tools.ts**: PatchApplyTool, CodeEditToolV2
+- **test-tools.ts**: RunTestsToolV2, BuildTool
+
+### Tasks V2
+
+Located in `src/tasks-v2/`:
+
+- **analysis-tasks.ts**: AnalyzeWorkspaceTask, CollectContextPackTask, SearchCodeTask
+- **developer-tasks.ts**: FindSymbolDefinitionTask, ImplementFunctionTask, RefactorRenameSymbolTask, FixTypeErrorTask, GenerateUnitTestsTask
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+MIT
+
+You can also use the AI Coder programmatically:
+
+```typescript
+import {
+  // Context Engine
+  WorkspaceIndexer,
+  SymbolExtractor,
+  CodeSearch,
+  ContextPackGenerator,
+  
+  // Tools V2
+  FileStatTool,
+  FileReadToolV2,
+  CodeSearchTool,
+  GrepTool,
+  DiffTool,
+  PatchApplyTool,
+  CodeEditToolV2,
+  RunTestsToolV2,
+  BuildTool,
+  
+  // Tasks V2
+  AnalyzeWorkspaceTask,
+  FindSymbolDefinitionTask,
+  ImplementFunctionTask,
+  RefactorRenameSymbolTask,
+  GenerateUnitTestsTask,
+  CollectContextPackTask,
+  
+  // Registries
+  SimpleCapabilityRegistry,
+  SimpleToolRegistry,
+  SimplePolicyEngine,
+} from '@ddse/acm-aicoder';
+
+import { executeResumablePlan } from '@ddse/acm-runtime';
+import { StructuredLLMPlanner } from '@ddse/acm-planner';
+import { createOllamaClient } from '@ddse/acm-llm';
+
+// Setup
+const rootPath = process.cwd();
+
+// 1. Build workspace index
+const indexer = new WorkspaceIndexer(rootPath);
+const index = await indexer.buildIndex();
+
+// 2. Setup search
+const search = new CodeSearch(rootPath);
+await search.indexFiles(index);
+
+// 3. Register tools
+const toolRegistry = new SimpleToolRegistry();
+toolRegistry.register(new FileStatTool());
+toolRegistry.register(new CodeSearchTool(rootPath));
+toolRegistry.register(new GrepTool(rootPath));
+toolRegistry.register(new CodeEditToolV2());
+toolRegistry.register(new RunTestsToolV2());
+toolRegistry.register(new BuildTool());
+
+// 4. Register tasks
+const capabilityRegistry = new SimpleCapabilityRegistry();
+capabilityRegistry.register(
+  { name: 'analyze_workspace', sideEffects: false },
+  new AnalyzeWorkspaceTask()
+);
+capabilityRegistry.register(
+  { name: 'find_symbol', sideEffects: false },
+  new FindSymbolDefinitionTask()
+);
+capabilityRegistry.register(
+  { name: 'implement_function', sideEffects: true },
+  new ImplementFunctionTask()
+);
+
+// 5. Create context pack
+const symbolExtractor = new SymbolExtractor(rootPath);
+const symbols = await symbolExtractor.extractSymbols(index);
+
+const packGenerator = new ContextPackGenerator(search);
+const contextPack = await packGenerator.generate(
+  'Find and fix all TypeScript errors',
+  index,
+  symbols,
+  [], // dependencies
+  [], // test mappings
+  { maxFiles: 10, maxSymbols: 30 }
+);
+
+// 6. Plan with context
+const llm = createOllamaClient('llama3.1');
+const planner = new StructuredLLMPlanner();
+
+const goal = {
+  id: 'goal-1',
+  intent: 'Find and fix all TypeScript errors',
+  constraints: {},
+};
+
+const context = {
+  id: 'ctx-1',
+  facts: { contextPack },
+  version: '1.0',
+};
+
+const plannerResult = await planner.plan({
+  goal,
+  context,
+  capabilities: capabilityRegistry.list(),
+  llm,
+});
+
+// 7. Execute with runtime
+const policy = new SimplePolicyEngine();
+policy.setAllowedPaths(['src/**']);
+
+const result = await executeResumablePlan({
+  goal,
+  context,
+  plan: plannerResult.plans[0],
+  capabilityRegistry,
+  toolRegistry,
+  policy,
+  verify: async (taskId, output, expressions) => true,
+  runId: `run-${Date.now()}`,
+});
+
+console.log('Execution complete:', result);
+```
+
+## Reference Pipeline Walkthrough
+
+### Build from Source
+
+```bash
+# Build TypeScript
+pnpm --filter @ddse/acm-aicoder build
+
+# Watch mode for development
+pnpm --filter @ddse/acm-aicoder dev
+```
+
+### Test Suite (Preview)
+
+```bash
+# Run integration tests (coming soon)
+pnpm --filter @ddse/acm-aicoder test
+```

package/bin/interactive.tsx

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+
+// ACM AI Coder - Phase 2 Interactive CLI
+// Full-screen TUI with three-column layout
+// Requires: --provider, --model, and --workspace (optional --base-url)
+
+import React from 'react';
+import { render } from 'ink';
+import { ExternalContextProviderAdapter } from '@ddse/acm-sdk';
+import { createOllamaClient, createVLLMClient } from '@ddse/acm-llm';
+import { App } from '../src/ui/App.js';
+import { AppStore } from '../src/ui/store.js';
+import { InteractiveRuntime } from '../src/runtime/interactive-runtime.js';
+import { parseCliArgs, validateAndNormalizeConfig } from '../src/config/session.js';
+import {
+  SimpleCapabilityRegistry,
+  SimpleToolRegistry,
+  SimplePolicyEngine,
+  // V2 Tools
+  FileStatTool,
+  FileReadToolV2,
+  CodeSearchTool,
+  GrepTool,
+  DiffTool,
+  CodeEditToolV2,
+  RunTestsToolV2,
+  WorkspaceContextRetrievalTool,
+  type WorkspaceContextOperation,
+  BuildTool,
+  // V2 Tasks
+  AnalyzeWorkspaceTask,
+  CollectContextPackTask,
+  SearchCodeTask,
+  FindSymbolDefinitionTask,
+  ImplementFunctionTask,
+  RefactorRenameSymbolTask,
+  FixTypeErrorTask,
+  GenerateUnitTestsTask,
+} from '../src/index.js';
+
+function buildWorkspaceContextInput(
+  directive: string,
+  goalIntent?: string
+): {
+  directive: string;
+  goal?: string;
+  operations: WorkspaceContextOperation[];
+} {
+  const separatorIndex = directive.indexOf(':');
+  const payload = separatorIndex >= 0 ? directive.slice(separatorIndex + 1).trim() : '';
+  const operations: WorkspaceContextOperation[] = [];
+
+  if (payload.length > 0) {
+    if (payload.startsWith('{')) {
+      try {
+        const parsed = JSON.parse(payload);
+        if (Array.isArray(parsed.operations)) {
+          return {
+            directive,
+            goal: goalIntent,
+            operations: parsed.operations as WorkspaceContextOperation[],
+          };
+        }
+        if (typeof parsed.query === 'string' && parsed.query.length > 0) {
+          operations.push({ type: 'search', query: parsed.query, includeContext: true });
+        }
+        if (typeof parsed.pattern === 'string' && parsed.pattern.length > 0) {
+          operations.push({ type: 'grep', pattern: parsed.pattern, maxResults: 20 });
+        }
+      } catch {
+        // Fall through to textual parsing
+      }
+    }
+
+    if (operations.length === 0) {
+      operations.push({ type: 'search', query: payload, includeContext: true });
+      operations.push({ type: 'grep', pattern: payload, maxResults: 20 });
+    }
+  }
+
+  return {
+    directive,
+    goal: goalIntent,
+    operations,
+  };
+}
+
+async function main() {
+  try {
+    // Parse and validate CLI arguments
+    const args = parseCliArgs(process.argv.slice(2));
+  const config = validateAndNormalizeConfig(args);
+
+  // Ensure the process operates within the validated workspace
+  process.chdir(config.workspace);
+
+    // Create LLM client based on provider selection
+    const llm = config.provider === 'vllm'
+      ? createVLLMClient(config.model, config.baseUrl)
+      : createOllamaClient(config.model, config.baseUrl);
+    
+    // Setup registries
+    const toolRegistry = new SimpleToolRegistry();
+    const capabilityRegistry = new SimpleCapabilityRegistry();
+    const policyEngine = new SimplePolicyEngine();
+    const contextProvider = new ExternalContextProviderAdapter();
+
+    // Register tools
+    const fileStatTool = new FileStatTool(config.workspace);
+    const fileReadTool = new FileReadToolV2(config.workspace);
+    const codeSearchTool = new CodeSearchTool(config.workspace);
+    const grepTool = new GrepTool(config.workspace);
+    const diffTool = new DiffTool(config.workspace);
+    const codeEditTool = new CodeEditToolV2(config.workspace);
+    const runTestsTool = new RunTestsToolV2(config.workspace);
+    const buildTool = new BuildTool(config.workspace);
+    const workspaceContextTool = new WorkspaceContextRetrievalTool(config.workspace);
+
+    toolRegistry.register(fileStatTool);
+    toolRegistry.register(fileReadTool);
+    toolRegistry.register(codeSearchTool);
+    toolRegistry.register(grepTool);
+    toolRegistry.register(diffTool);
+    toolRegistry.register(codeEditTool);
+    toolRegistry.register(runTestsTool);
+    toolRegistry.register(buildTool);
+    toolRegistry.register(workspaceContextTool);
+
+    contextProvider.register(workspaceContextTool, {
+      match: directive =>
+        directive.startsWith('workspace.context') || directive.startsWith('workspace_context'),
+      buildInput: (directive, ctx) =>
+        buildWorkspaceContextInput(directive, ctx.runContext?.goal.intent),
+      describe:
+        'Retrieve relevant workspace snippets, grep matches, and metadata to satisfy context requests.',
+      autoPromote: true,
+      maxArtifacts: 32,
+    });
+    
+    // Register capabilities (tasks)
+    capabilityRegistry.register(
+      { name: 'analyze_workspace', sideEffects: false },
+      new AnalyzeWorkspaceTask()
+    );
+    capabilityRegistry.register(
+      { name: 'collect_context_pack', sideEffects: false },
+      new CollectContextPackTask()
+    );
+    capabilityRegistry.register(
+      { name: 'search_code', sideEffects: false },
+      new SearchCodeTask()
+    );
+    capabilityRegistry.register(
+      { name: 'find_symbol_definition', sideEffects: false },
+      new FindSymbolDefinitionTask()
+    );
+    capabilityRegistry.register(
+      { name: 'implement_function', sideEffects: true },
+      new ImplementFunctionTask()
+    );
+    capabilityRegistry.register(
+      { name: 'refactor_rename_symbol', sideEffects: true },
+      new RefactorRenameSymbolTask()
+    );
+    capabilityRegistry.register(
+      { name: 'fix_type_error', sideEffects: true },
+      new FixTypeErrorTask()
+    );
+    capabilityRegistry.register(
+      { name: 'generate_unit_tests', sideEffects: true },
+      new GenerateUnitTestsTask()
+    );
+    
+    // Allow workspace operations
+  policyEngine.setAllowedPaths([config.workspace]);
+    
+    // Create app store and runtime
+    const store = new AppStore();
+    const runtime = new InteractiveRuntime({
+      config,
+      llm,
+      capabilityRegistry,
+      toolRegistry,
+      policyEngine,
+      store,
+      contextProvider,
+    });
+
+    const initialBudget = runtime.getBudgetManager().getStatus();
+    
+    // Welcome message
+    store.addMessage('system', 
+      `Welcome to ACM AI Coder (Phase 2)\n\n` +
+  `Configuration:\n` +
+  `  Provider: ${config.provider}\n` +
+      `  Model: ${config.model}\n` +
+      (config.baseUrl ? `  Base URL: ${config.baseUrl}\n` : '') +
+  `  Workspace: ${config.workspace}\n` +
+      (initialBudget.maxTokens !== undefined ? `  Token allowance: ${initialBudget.maxTokens}\n` : '') +
+      `\n` +
+      `Type your goal to start planning, or /help for commands.`
+    );
+    
+    // Update initial budget status
+    store.updateBudgetStatus(initialBudget);
+    
+    // Handle commands from UI
+    const handleCommand = async (command: string) => {
+      if (command.startsWith('/')) {
+        // Already handled by UI component
+        return;
+      }
+      
+      // Process as goal
+      await runtime.processGoal(command);
+    };
+    
+    // Render TUI
+    render(<App store={store} onCommand={handleCommand} />);
+    
+  } catch (error: any) {
+    console.error('Error starting ACM AI Coder:');
+    console.error(error.message);
+    console.error('\nFor help, run: acm-aicoder --help');
+    process.exit(1);
+  }
+}
+
+main().catch(err => {
+  console.error('Fatal error:', err);
+  process.exit(1);
+});