@ddse/acm-aicoder 0.5.0

package/docs/TUI_MOCKUP.md

@@ -0,0 +1,180 @@
+# ACM AI Coder - Interactive TUI Mockup
+
+```
+╔═══════════════════════════════════════════════════════════════════════════════╗
+║               ACM AI Coder - Interactive Mode                      ⟳ Processing║
+╠═════════════════════════╤═════════════════════════════╤═════════════════════════╣
+║                         │                             │                         ║
+║  ┌─────────────────┐    │  ┌─────────────────────┐   │  ┌─────────────────┐   ║
+║  │      Chat       │    │  │ Goal/Tasks/Progress │   │  │   Event Stream  │   ║
+║  └─────────────────┘    │  └─────────────────────┘   │  └─────────────────┘   ║
+║                         │                             │                         ║
+║  System:                │  Goal:                      │  [14:23:45] GOAL_      ║
+║  Welcome to ACM AI      │  Analyze src/index.ts       │  CREATED: goal-123     ║
+║  Coder (Phase 2)        │  and find bugs              │                         ║
+║                         │                             │  [14:23:46] BUDGET_    ║
+║  Configuration:         │  Tasks:                     │  CHECK: $0.0024        ║
+║    Model: gpt-4o        │  ○ analyze_workspace        │                         ║
+║    Engine: langgraph    │  ○ collect_context_pack     │  [14:23:47] PLAN_      ║
+║    Workspace: /project  │  ○ search_code              │  SELECTED: plan-456    ║
+║    Budget: $10.00       │                             │                         ║
+║                         │  Budget:                    │  [14:23:48] TASK_      ║
+║  Type your goal to      │  Spent: $0.0024 / $10.00    │  START: task-0         ║
+║  start planning.        │  Used: 0.0%                 │                         ║
+║                         │  Remaining: $9.9976         │  [14:23:49] CONTEXT_   ║
+║  You:                   │  Calls: 1                   │  INTERNALIZED: 3 files ║
+║  Analyze src/index.ts   │                             │                         ║
+║  and find bugs          │                             │  [14:23:50] TASK_      ║
+║                         │                             │  END: task-0           ║
+║  Planner (streaming...):│                             │                         ║
+║  I'll analyze the file  │                             │  [14:23:51] NUCLEUS_   ║
+║  by first collecting    │                             │  INFERENCE: context ok ║
+║  context from the       │                             │                         ║
+║  workspace, then...     │                             │                         ║
+║                         │                             │                         ║
+║                         │                             │                         ║
+║                         │                             │                         ║
+╠═════════════════════════╧═════════════════════════════╧═════════════════════════╣
+║  > Type your goal or command (e.g., /help)...                                   ║
+╚═══════════════════════════════════════════════════════════════════════════════╝
+```
+
+## Layout Breakdown
+
+### Left Column (40%) - Chat Pane
+- **Purpose:** User messages, planner reasoning, nucleus thoughts, system messages
+- **Colors:**
+  - User: white
+  - Planner: yellow (streaming indicator when active)
+  - Nucleus: magenta
+  - System: gray
+- **Scrolling:** Shows most recent messages that fit in viewport
+
+### Middle Column (30%) - Goals/Tasks/Progress
+- **Goal Section:** Current goal intent
+- **Tasks Section:** Live task list with status icons
+  - ○ pending (gray)
+  - ◐ running (yellow)
+  - ● succeeded (green)
+  - ✗ failed (red)
+  - ⟳ retrying (yellow)
+- **Budget Section:** Real-time spend tracking
+  - Total spent vs. limit
+  - Percentage used (color-coded)
+  - Remaining budget
+  - API call count
+
+### Right Column (30%) - Event Stream
+- **Purpose:** Ledger entries, tool calls, context updates, policy decisions
+- **Format:** [timestamp] TYPE: data
+- **Colors:**
+  - PLAN_SELECTED, TASK_END: green
+  - TASK_START: blue
+  - ERROR: red
+  - POLICY_DECISION: yellow
+  - Others: gray
+- **Pruning:** Keeps last 100 events
+
+### Bottom - Command Input
+- **Text input:** Accepts goals or commands
+- **Commands:** /exit, /help, /budget, /context, /reset
+- **File mentions:** #path/to/file syntax
+- **Submit:** Press Enter to send
+
+## Example Session Flow
+
+### 1. Startup
+```
+> acm-aicoder --provider vllm --model gpt-4o --base-url https://api.openai.com \
+              --workspace /myproject
+
+[TUI launches with welcome message]
+```
+
+### 2. User Types Goal
+```
+> Find all TypeScript errors in src/ directory
+[ENTER]
+```
+
+### 3. Budget Check
+```
+Event Stream:
+[14:25:01] BUDGET_CHECK: estimated $0.0035, 1200 tokens
+```
+
+### 4. Planner Streams Reasoning
+```
+Chat Pane:
+Planner (streaming...):
+First, I'll analyze the TypeScript files in src/...
+Then I'll run the type checker...
+Finally, I'll categorize the errors...
+```
+
+### 5. Tasks Execute
+```
+Tasks Pane:
+◐ analyze_workspace (running)
+○ collect_context_pack
+○ fix_type_error
+
+Event Stream:
+[14:25:02] TASK_START: task-0
+[14:25:03] CONTEXT_INTERNALIZED: 15 files
+[14:25:04] TASK_END: task-0
+```
+
+### 6. Completion
+```
+System:
+Goal completed successfully!
+Replay bundle saved to: /myproject/.aicoder/replays/2025-01-04T14-25-05
+```
+
+## Interactive Commands
+
+### /help
+Shows available commands and usage examples.
+
+### /budget
+```
+Budget Status:
+  Total Spent: $0.0124
+  Limit: $10.00
+  Remaining: $9.9876
+  Used: 0.1%
+  API Calls: 4
+```
+
+### /context
+```
+Current Context:
+  ID: ctx-1735998305123
+  Facts: 3 entries
+```
+
+### /reset
+Clears current goal and tasks, resets budget, keeps chat history.
+
+### /exit or /quit
+Saves replay bundle and exits cleanly.
+
+## Visual Styling
+
+- **Borders:** Single-line for panes, double-line for header/footer
+- **Colors:** ANSI terminal colors (cyan, yellow, green, red, blue, magenta)
+- **Responsive:** Adjusts to terminal size (minimum 80 columns)
+- **Updates:** Real-time re-renders on state changes
+
+## Terminal Requirements
+
+- **Minimum Width:** 80 columns
+- **Minimum Height:** 24 rows
+- **Terminal Type:** xterm-compatible (supports ANSI colors)
+- **Not Recommended:** tmux/screen nested sessions (may cause layout issues)
+
+---
+
+This mockup represents the actual TUI layout implemented in Phase 2.
+All components are functional and wired to the ACM framework.

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@ddse/acm-aicoder",
+  "version": "0.5.0",
+  "description": "ACM AI Coder Demo - Production-ready developer workflow automation",
+  "type": "module",
+  "main": "./dist/src/index.js",
+  "types": "./dist/src/index.d.ts",
+  "bin": {
+    "acm-aicoder": "./dist/bin/interactive.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "import": "./dist/src/index.js"
+    }
+  },
+  "dependencies": {
+    "enquirer": "^2.4.1",
+    "chalk": "^5.3.0",
+    "ora": "^8.0.1",
+    "execa": "^9.0.0",
+    "ink": "^5.0.1",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1",
+    "@ddse/acm-sdk": "0.5.0",
+    "@ddse/acm-runtime": "0.5.0",
+    "@ddse/acm-planner": "0.5.0",
+    "@ddse/acm-replay": "0.5.0",
+    "@ddse/acm-framework": "0.5.0",
+    "@ddse/acm-llm": "0.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.3",
+    "typescript": "^5.3.0"
+  },
+  "keywords": [
+    "acm",
+    "ai",
+    "coder",
+    "developer",
+    "automation"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "test": "tsc && node ./dist/tests/integration.test.js",
+    "dev": "tsc --watch",
+    "acm-aicoder": "node ./dist/bin/interactive.js"
+  }
+}

package/src/config/providers.ts

@@ -0,0 +1,174 @@
+// Provider metadata for budget governance
+// Token costs and context limits per model/provider
+
+export interface ProviderMetadata {
+  provider: string;
+  model: string;
+  
+  // Cost per 1M tokens (USD)
+  inputCostPer1M?: number;
+  outputCostPer1M?: number;
+  
+  // Context window
+  maxContextTokens?: number;
+  
+  // Concurrency limits
+  maxConcurrentRequests?: number;
+  
+  // Recommended settings
+  recommendedTemperature?: number;
+  supportsStreaming: boolean;
+}
+
+// Provider metadata registry
+// Sources: OpenAI pricing, Anthropic pricing, Azure OpenAI, local models
+export const PROVIDER_METADATA: Record<string, ProviderMetadata> = {
+  // OpenAI models
+  'gpt-4o': {
+    provider: 'openai',
+    model: 'gpt-4o',
+    inputCostPer1M: 2.50,
+    outputCostPer1M: 10.00,
+    maxContextTokens: 128000,
+    maxConcurrentRequests: 10,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'gpt-4o-mini': {
+    provider: 'openai',
+    model: 'gpt-4o-mini',
+    inputCostPer1M: 0.15,
+    outputCostPer1M: 0.60,
+    maxContextTokens: 128000,
+    maxConcurrentRequests: 10,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'gpt-4-turbo': {
+    provider: 'openai',
+    model: 'gpt-4-turbo',
+    inputCostPer1M: 10.00,
+    outputCostPer1M: 30.00,
+    maxContextTokens: 128000,
+    maxConcurrentRequests: 10,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'gpt-3.5-turbo': {
+    provider: 'openai',
+    model: 'gpt-3.5-turbo',
+    inputCostPer1M: 0.50,
+    outputCostPer1M: 1.50,
+    maxContextTokens: 16385,
+    maxConcurrentRequests: 10,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  
+  // Anthropic models
+  'claude-3-opus-20240229': {
+    provider: 'anthropic',
+    model: 'claude-3-opus-20240229',
+    inputCostPer1M: 15.00,
+    outputCostPer1M: 75.00,
+    maxContextTokens: 200000,
+    maxConcurrentRequests: 5,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'claude-3-sonnet-20240229': {
+    provider: 'anthropic',
+    model: 'claude-3-sonnet-20240229',
+    inputCostPer1M: 3.00,
+    outputCostPer1M: 15.00,
+    maxContextTokens: 200000,
+    maxConcurrentRequests: 5,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'claude-3-haiku-20240307': {
+    provider: 'anthropic',
+    model: 'claude-3-haiku-20240307',
+    inputCostPer1M: 0.25,
+    outputCostPer1M: 1.25,
+    maxContextTokens: 200000,
+    maxConcurrentRequests: 5,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  
+  // Local/self-hosted models (no cost)
+  'llama3.1': {
+    provider: 'ollama',
+    model: 'llama3.1',
+    inputCostPer1M: 0,
+    outputCostPer1M: 0,
+    maxContextTokens: 128000,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'qwen2.5:7b': {
+    provider: 'ollama',
+    model: 'qwen2.5:7b',
+    inputCostPer1M: 0,
+    outputCostPer1M: 0,
+    maxContextTokens: 32768,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+  'deepseek-coder': {
+    provider: 'ollama',
+    model: 'deepseek-coder',
+    inputCostPer1M: 0,
+    outputCostPer1M: 0,
+    maxContextTokens: 16000,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  },
+};
+
+export function getProviderMetadata(model: string): ProviderMetadata {
+  // Try exact match first
+  if (PROVIDER_METADATA[model]) {
+    return PROVIDER_METADATA[model];
+  }
+  
+  // Try prefix match (e.g., "gpt-4o-2024-05-13" matches "gpt-4o")
+  for (const [key, metadata] of Object.entries(PROVIDER_METADATA)) {
+    if (model.startsWith(key)) {
+      return metadata;
+    }
+  }
+  
+  // Default metadata for unknown models (assume local/free)
+  return {
+    provider: 'unknown',
+    model,
+    inputCostPer1M: 0,
+    outputCostPer1M: 0,
+    maxContextTokens: 8192,
+    recommendedTemperature: 0.7,
+    supportsStreaming: true,
+  };
+}
+
+export function estimateTokenCount(text: string): number {
+  // Rough approximation: 1 token ≈ 4 characters for English text
+  // More accurate would use tiktoken library, but this is sufficient for budget estimation
+  return Math.ceil(text.length / 4);
+}
+
+export function estimateCost(
+  inputTokens: number,
+  outputTokens: number,
+  metadata: ProviderMetadata
+): number {
+  if (!metadata.inputCostPer1M || !metadata.outputCostPer1M) {
+    return 0;
+  }
+  
+  const inputCost = (inputTokens / 1_000_000) * metadata.inputCostPer1M;
+  const outputCost = (outputTokens / 1_000_000) * metadata.outputCostPer1M;
+  
+  return inputCost + outputCost;
+}

package/src/config/session.ts

@@ -0,0 +1,143 @@
+// Session configuration for AI Coder Phase 2
+// Manages CLI arguments and session metadata using provider/model semantics
+
+import { existsSync, statSync } from 'fs';
+import path from 'path';
+import os from 'os';
+
+export type Provider = 'ollama' | 'vllm';
+
+export interface SessionConfig {
+  provider: Provider;
+  model: string;
+  baseUrl?: string;
+  workspace: string;
+  temperature: number;
+  seed?: number;
+  planCount: 1 | 2;
+  sessionId: string;
+  timestamp: number;
+}
+
+export interface CLIArgs {
+  provider?: string;
+  model?: string;
+  'base-url'?: string;
+  workspace?: string;
+  temperature?: string;
+  seed?: string;
+  plans?: string;
+  [key: string]: string | undefined;
+}
+
+export function parseCliArgs(argv: string[]): CLIArgs {
+  const args: CLIArgs = {};
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith('--')) {
+      // Support --key=value form
+      if (arg.includes('=')) {
+        const pair = arg.slice(2);
+        const eqIndex = pair.indexOf('=');
+        const key = pair.slice(0, eqIndex);
+        const value = pair.slice(eqIndex + 1);
+        if (key.length > 0) {
+          args[key] = value;
+        }
+        continue;
+      }
+
+      // Support space-separated --key value form
+      const key = arg.slice(2);
+      const value = argv[i + 1];
+      if (value && !value.startsWith('--')) {
+        args[key] = value;
+        i++;
+      }
+    }
+  }
+
+  return args;
+}
+
+export function validateAndNormalizeConfig(args: CLIArgs): SessionConfig {
+  const provider = (args.provider as Provider) || 'ollama';
+  if (!['ollama', 'vllm'].includes(provider)) {
+    throw new Error(`Invalid --provider: ${args.provider}. Must be "ollama" or "vllm".`);
+  }
+
+  const model = args.model || (provider === 'ollama' ? 'llama3.1' : undefined);
+  const missing: string[] = [];
+
+  if (!model) missing.push('--model');
+  if (!args.workspace || args.workspace.trim().length === 0) missing.push('--workspace');
+
+  if (missing.length > 0) {
+    throw new Error(
+      `Missing required parameters: ${missing.join(', ')}\n\n` +
+      `ACM AI Coder requires these parameters to start:\n` +
+      `  --provider <ollama|vllm>  LLM provider (default: ollama)\n` +
+      `  --model <name>            Model identifier (e.g., llama3.1, gpt-4o)\n` +
+      `  --workspace <path>        REQUIRED: absolute or relative path to project root\n\n` +
+      `Optional parameters:\n` +
+      `  --base-url <url>          Override provider base URL\n` +
+      `  --temperature <0-2>       LLM temperature (default: 0.7)\n` +
+      `  --seed <number>           Random seed for reproducibility\n` +
+      `  --plans <1|2>             Number of alternative plans (default: 1)\n\n` +
+      `Examples:\n` +
+      `  acm-aicoder --provider vllm --model gpt-4o --workspace /abs/path\n` +
+      `  acm-aicoder --provider ollama --model llama3.1 --workspace=~/myproject`
+    );
+  }
+
+  const temperature = args.temperature ? parseFloat(args.temperature) : 0.7;
+  if (isNaN(temperature) || temperature < 0 || temperature > 2) {
+    throw new Error(`Invalid --temperature: must be between 0 and 2`);
+  }
+
+  const seed = args.seed ? parseInt(args.seed, 10) : undefined;
+  if (seed !== undefined && Number.isNaN(seed)) {
+    throw new Error(`Invalid --seed: must be a number`);
+  }
+
+  const planCount = args.plans === '2' ? 2 : 1;
+
+  // Enforce explicit workspace and normalize
+  const baseCwd = process.env.INIT_CWD || process.env.PWD || process.cwd();
+  let workspaceInput = args.workspace!;
+
+  // Expand ~ to user home
+  if (workspaceInput.startsWith('~/')) {
+    workspaceInput = path.join(os.homedir(), workspaceInput.slice(2));
+  }
+
+  const resolvedWorkspace = path.isAbsolute(workspaceInput)
+    ? workspaceInput
+    : path.resolve(baseCwd, workspaceInput);
+
+  if (!existsSync(resolvedWorkspace)) {
+    throw new Error(
+      `Workspace path "${resolvedWorkspace}" does not exist. Please provide a valid --workspace.`
+    );
+  }
+
+  const stats = statSync(resolvedWorkspace);
+  if (!stats.isDirectory()) {
+    throw new Error(
+      `Workspace path "${resolvedWorkspace}" is not a directory. Please provide a valid --workspace.`
+    );
+  }
+
+  return {
+    provider,
+    model: model!,
+    baseUrl: args['base-url'],
+    workspace: resolvedWorkspace,
+    temperature,
+    seed,
+    planCount,
+    sessionId: `session-${Date.now()}`,
+    timestamp: Date.now(),
+  };
+}