@sooneocean/agw 1.4.0

package/README.md

@@ -0,0 +1,116 @@
+# AGW — Agent Gateway
+
+Multi-agent task router and executor for **Claude Code**, **Codex CLI**, and **Gemini CLI**.
+
+Submit a task → AGW picks the best agent → agent executes → you get results + logs + cost data.
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Start the daemon
+npx agw daemon start
+
+# Run a task
+npx agw run "refactor auth.ts"
+
+# Run with specific agent
+npx agw run "quick rename" --agent codex --priority 5
+
+# Check costs
+npx agw costs
+
+# Multi-step workflow
+npx agw workflow run '{"name":"deploy","steps":[{"prompt":"run tests"},{"prompt":"build"}]}'
+
+# Open Web UI
+open http://127.0.0.1:4927/ui
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| **Smart Routing** | LLM classifier (Haiku) + keyword fallback |
+| **3 Agents** | Claude (complex reasoning), Codex (terminal ops), Gemini (research) |
+| **Auth** | Bearer token via `AGW_AUTH_TOKEN`, loopback-only without token |
+| **Priority Queue** | 1-5 priority with per-agent concurrency limits |
+| **Cost Tracking** | Per-task cost recording, daily/monthly quotas |
+| **Workflows** | Sequential or parallel multi-step task chains |
+| **Web UI** | Real-time dashboard at `/ui` |
+| **SSE Streaming** | Live stdout/stderr via `/tasks/:id/stream` |
+| **Workspace Sandbox** | `allowedWorkspaces` whitelist + realpath validation |
+| **Stdin Prompts** | Prompt delivery via stdin (no argv leakage) |
+
+## Configuration
+
+Config file: `~/.agw/config.json`
+
+```json
+{
+  "port": 4927,
+  "authToken": "your-secret-token",
+  "allowedWorkspaces": ["/home/user/projects"],
+  "maxConcurrencyPerAgent": 3,
+  "dailyCostLimit": 5.00,
+  "monthlyCostLimit": 50.00,
+  "maxPromptLength": 100000,
+  "maxWorkflowSteps": 20,
+  "agents": {
+    "claude": { "enabled": true, "command": "claude", "args": [] },
+    "codex": { "enabled": true, "command": "codex", "args": [] },
+    "gemini": { "enabled": false, "command": "gemini", "args": [] }
+  }
+}
+```
+
+Environment variables (override config file):
+- `AGW_PORT` — server port
+- `AGW_AUTH_TOKEN` — Bearer token
+- `ANTHROPIC_API_KEY` — for LLM routing
+
+## API
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | `/tasks` | Create and execute a task |
+| GET | `/tasks/:id` | Get task details |
+| GET | `/tasks/:id/stream` | SSE stream (stdout/stderr/done) |
+| GET | `/tasks` | List tasks |
+| POST | `/workflows` | Create workflow (returns 202) |
+| GET | `/workflows/:id` | Get workflow status |
+| GET | `/workflows` | List workflows |
+| GET | `/agents` | List agents |
+| POST | `/agents/:id/health` | Trigger health check |
+| GET | `/costs` | Cost summary |
+| GET | `/ui` | Web dashboard |
+
+## CLI Commands
+
+```
+agw run <prompt>       Submit a task (--agent, --priority, --background, --cwd)
+agw status <taskId>    Check task status
+agw history            List recent tasks (--limit N)
+agw agents             List agents / agw agents check
+agw daemon start|stop|status
+agw costs              Show cost summary
+agw workflow run|status|list
+```
+
+## Development
+
+```bash
+npm test          # Run 76 tests
+npm run build     # TypeScript compile
+npm run dev       # Start dev server
+```
+
+## Tech Stack
+
+TypeScript, Fastify, SQLite (better-sqlite3), Commander.js, Node.js 22+
+
+## License
+
+MIT

package/bin/agw.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+import { createCli } from '../src/cli/index.js';
+
+const program = createCli();
+program.parse();

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@sooneocean/agw",
+  "version": "1.4.0",
+  "description": "Agent Gateway — multi-agent task router for Claude, Codex, Gemini with combos, DAG, DSL",
+  "type": "module",
+  "bin": {
+    "agw": "./bin/agw.ts"
+  },
+  "scripts": {
+    "dev": "tsx src/daemon/server.ts",
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "keywords": [
+    "agent",
+    "gateway",
+    "multi-agent",
+    "claude",
+    "codex",
+    "gemini",
+    "ai",
+    "orchestration",
+    "combo",
+    "pipeline",
+    "dsl"
+  ],
+  "author": "sooneocean",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sooneocean/agw.git"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "ui/",
+    "package.json",
+    "tsconfig.json",
+    "README.md"
+  ],
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.52.0",
+    "better-sqlite3": "^11.8.0",
+    "commander": "^13.1.0",
+    "fastify": "^5.2.0",
+    "nanoid": "^5.1.0",
+    "tsx": "^4.19.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/node": "^22.13.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}

package/src/agents/base-adapter.ts

@@ -0,0 +1,113 @@
+import { spawn, exec } from 'node:child_process';
+import { EventEmitter } from 'node:events';
+import { promisify } from 'node:util';
+import type { TaskDescriptor, TaskResult, AgentDescriptor, UnifiedAgent } from '../types.js';
+
+const execAsync = promisify(exec);
+
+export abstract class BaseAdapter extends EventEmitter implements UnifiedAgent {
+  constructor(
+    protected timeout: number,
+    protected maxBufferSize: number,
+    protected commandOverride?: string,
+  ) {
+    super();
+  }
+
+  abstract describe(): AgentDescriptor;
+  protected abstract buildArgs(task: TaskDescriptor): string[];
+
+  /** Whether this adapter sends the prompt via stdin instead of argv. Override to return true. */
+  protected useStdin(): boolean {
+    return false;
+  }
+
+  async execute(task: TaskDescriptor): Promise<TaskResult> {
+    const descriptor = this.describe();
+    const args = this.buildArgs(task);
+    const start = Date.now();
+    const useStdin = this.useStdin();
+
+    return new Promise<TaskResult>((resolve) => {
+      let stdout = '';
+      let stderr = '';
+      let stdoutTruncated = false;
+      let stderrTruncated = false;
+      let killed = false;
+
+      const command = this.commandOverride ?? descriptor.command;
+      const proc = spawn(command, args, {
+        cwd: task.workingDirectory,
+        stdio: [useStdin ? 'pipe' : 'ignore', 'pipe', 'pipe'],
+        timeout: this.timeout,
+      });
+
+      // Send prompt via stdin if supported (avoids leaking prompt in ps/argv)
+      if (useStdin && proc.stdin) {
+        proc.stdin.write(task.prompt);
+        proc.stdin.end();
+      }
+
+      proc.stdout!.on('data', (chunk: Buffer) => {
+        const text = chunk.toString();
+        this.emit('stdout', text);
+        if (stdout.length < this.maxBufferSize) {
+          stdout += text;
+          if (stdout.length > this.maxBufferSize) {
+            stdout = stdout.slice(stdout.length - this.maxBufferSize);
+            stdoutTruncated = true;
+          }
+        } else {
+          stdoutTruncated = true;
+        }
+      });
+
+      proc.stderr!.on('data', (chunk: Buffer) => {
+        const text = chunk.toString();
+        this.emit('stderr', text);
+        if (stderr.length < this.maxBufferSize) {
+          stderr += text;
+          if (stderr.length > this.maxBufferSize) {
+            stderr = stderr.slice(stderr.length - this.maxBufferSize);
+            stderrTruncated = true;
+          }
+        } else {
+          stderrTruncated = true;
+        }
+      });
+
+      proc.on('error', (err) => {
+        resolve({
+          exitCode: 1,
+          stdout,
+          stderr: stderr + '\n' + err.message,
+          stdoutTruncated,
+          stderrTruncated,
+          durationMs: Date.now() - start,
+        });
+      });
+
+      proc.on('close', (code, signal) => {
+        if (signal === 'SIGTERM') killed = true;
+        resolve({
+          exitCode: code ?? (killed ? 137 : 1),
+          stdout,
+          stderr,
+          stdoutTruncated,
+          stderrTruncated,
+          durationMs: Date.now() - start,
+        });
+      });
+    });
+  }
+
+  async healthCheck(): Promise<boolean> {
+    const descriptor = this.describe();
+    try {
+      await execAsync(descriptor.healthCheckCommand, { timeout: 10_000 });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/agents/claude-adapter.ts

@@ -0,0 +1,29 @@
+import { BaseAdapter } from './base-adapter.js';
+import type { TaskDescriptor, AgentDescriptor } from '../types.js';
+
+export class ClaudeAdapter extends BaseAdapter {
+  constructor(timeout: number, maxBufferSize: number, private extraArgs: string[] = [], commandOverride?: string) {
+    super(timeout, maxBufferSize, commandOverride);
+  }
+
+  describe(): AgentDescriptor {
+    return {
+      id: 'claude',
+      name: 'Claude Code',
+      command: 'claude',
+      args: ['--print', ...this.extraArgs],
+      enabled: true,
+      available: true,
+      healthCheckCommand: 'claude --version',
+    };
+  }
+
+  protected useStdin(): boolean {
+    return true;
+  }
+
+  protected buildArgs(_task: TaskDescriptor): string[] {
+    // Prompt is sent via stdin, not argv (prevents ps/argv leakage)
+    return ['--print', '--output-format', 'json', ...this.extraArgs, '-'];
+  }
+}

package/src/agents/codex-adapter.ts

@@ -0,0 +1,29 @@
+import { BaseAdapter } from './base-adapter.js';
+import type { TaskDescriptor, AgentDescriptor } from '../types.js';
+
+export class CodexAdapter extends BaseAdapter {
+  constructor(timeout: number, maxBufferSize: number, private extraArgs: string[] = [], commandOverride?: string) {
+    super(timeout, maxBufferSize, commandOverride);
+  }
+
+  describe(): AgentDescriptor {
+    return {
+      id: 'codex',
+      name: 'Codex CLI',
+      command: 'codex',
+      args: ['exec', ...this.extraArgs],
+      enabled: true,
+      available: true,
+      healthCheckCommand: 'codex --version',
+    };
+  }
+
+  protected useStdin(): boolean {
+    return true;
+  }
+
+  protected buildArgs(_task: TaskDescriptor): string[] {
+    // Prompt is sent via stdin (reads from stdin when prompt arg is "-")
+    return ['exec', ...this.extraArgs, '-'];
+  }
+}

package/src/agents/gemini-adapter.ts

@@ -0,0 +1,29 @@
+import { BaseAdapter } from './base-adapter.js';
+import type { TaskDescriptor, AgentDescriptor } from '../types.js';
+
+export class GeminiAdapter extends BaseAdapter {
+  constructor(timeout: number, maxBufferSize: number, private extraArgs: string[] = [], commandOverride?: string) {
+    super(timeout, maxBufferSize, commandOverride);
+  }
+
+  describe(): AgentDescriptor {
+    return {
+      id: 'gemini',
+      name: 'Gemini CLI',
+      command: 'gemini',
+      args: [...this.extraArgs],
+      enabled: true,
+      available: true,
+      healthCheckCommand: 'gemini --version',
+    };
+  }
+
+  protected useStdin(): boolean {
+    return true;
+  }
+
+  protected buildArgs(_task: TaskDescriptor): string[] {
+    // Prompt via stdin
+    return [...this.extraArgs, '-'];
+  }
+}

package/src/cli/commands/agents.ts

@@ -0,0 +1,55 @@
+import type { Command } from 'commander';
+import { HttpClient } from '../http-client.js';
+import type { AgentDescriptor } from '../../types.js';
+
+export function registerAgentsCommand(program: Command): void {
+  const cmd = program
+    .command('agents')
+    .description('List agents and health status');
+
+  cmd.action(async () => {
+    const client = new HttpClient();
+    try {
+      const agents = await client.get<AgentDescriptor[]>('/agents');
+      console.log('Agent     Status      Last Check');
+      console.log('─'.repeat(40));
+      for (const a of agents) {
+        const status = !a.enabled ? '- Disabled' : a.available ? '✓ Ready' : '✗ N/A';
+        const lastCheck = a.lastHealthCheck
+          ? timeSince(new Date(a.lastHealthCheck))
+          : 'never';
+        console.log(`${a.id.padEnd(9)} ${status.padEnd(11)} ${lastCheck}`);
+      }
+    } catch (err) {
+      console.error(`Error: ${(err as Error).message}`);
+      process.exit(1);
+    }
+  });
+
+  cmd
+    .command('check')
+    .description('Trigger health checks for all agents')
+    .action(async () => {
+      const client = new HttpClient();
+      try {
+        const agents = await client.get<AgentDescriptor[]>('/agents');
+        for (const a of agents) {
+          if (!a.enabled) continue;
+          const result = await client.post<{ id: string; available: boolean }>(`/agents/${a.id}/health`, {});
+          console.log(`${a.id}: ${result.available ? '✓ available' : '✗ unavailable'}`);
+        }
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+}
+
+function timeSince(date: Date): string {
+  const seconds = Math.floor((Date.now() - date.getTime()) / 1000);
+  if (seconds < 60) return `${seconds}s ago`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ago`;
+  const hours = Math.floor(minutes / 60);
+  return `${hours}h ago`;
+}

package/src/cli/commands/combo.ts

@@ -0,0 +1,130 @@
+import type { Command } from 'commander';
+import { HttpClient } from '../http-client.js';
+import type { ComboDescriptor, ComboPreset } from '../../types.js';
+
+export function registerComboCommand(program: Command): void {
+  const combo = program
+    .command('combo')
+    .description('Multi-agent combo moves — agents collaborate and pass context');
+
+  // List presets
+  combo.command('presets')
+    .description('List built-in combo presets')
+    .action(async () => {
+      const client = new HttpClient();
+      try {
+        const presets = await client.get<ComboPreset[]>('/combos/presets');
+        console.log('Available Combo Presets:');
+        console.log('─'.repeat(60));
+        for (const p of presets) {
+          console.log(`  ${p.id.padEnd(25)} ${p.pattern.padEnd(14)} ${p.description}`);
+        }
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+
+  // Run a preset
+  combo.command('preset <presetId> <input...>')
+    .description('Run a built-in combo preset')
+    .option('--cwd <path>', 'Working directory')
+    .option('--priority <n>', 'Priority 1-5', '3')
+    .action(async (presetId: string, inputParts: string[], options: { cwd?: string; priority?: string }) => {
+      const client = new HttpClient();
+      try {
+        const combo = await client.post<ComboDescriptor>(`/combos/preset/${presetId}`, {
+          input: inputParts.join(' '),
+          workingDirectory: options.cwd,
+          priority: parseInt(options.priority ?? '3', 10),
+        });
+        console.log(`Combo: ${combo.comboId}  ${combo.name}`);
+        console.log(`Pattern: ${combo.pattern}`);
+        console.log(`Status: ${combo.status}`);
+        console.log(`Steps: ${combo.steps.length}`);
+        console.log(`\nCheck progress: agw combo status ${combo.comboId}`);
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+
+  // Run custom combo
+  combo.command('run')
+    .description('Run a custom combo from JSON')
+    .argument('<json>', 'Combo JSON')
+    .action(async (json: string) => {
+      const client = new HttpClient();
+      try {
+        const body = JSON.parse(json);
+        const combo = await client.post<ComboDescriptor>('/combos', body);
+        console.log(`Combo: ${combo.comboId}  ${combo.name}`);
+        console.log(`Pattern: ${combo.pattern}`);
+        console.log(`Status: ${combo.status}`);
+        console.log(`\nCheck progress: agw combo status ${combo.comboId}`);
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+
+  // Check combo status
+  combo.command('status <id>')
+    .description('Get combo status and results')
+    .action(async (id: string) => {
+      const client = new HttpClient();
+      try {
+        const c = await client.get<ComboDescriptor>(`/combos/${id}`);
+        console.log(`Combo:     ${c.comboId}`);
+        console.log(`Name:      ${c.name}`);
+        console.log(`Pattern:   ${c.pattern}`);
+        console.log(`Status:    ${c.status}`);
+        if (c.iterations) console.log(`Iterations: ${c.iterations}/${c.maxIterations}`);
+        console.log(`Tasks:     ${c.taskIds.join(', ') || 'none'}`);
+
+        // Show step results
+        const stepEntries = Object.entries(c.stepResults);
+        if (stepEntries.length > 0) {
+          console.log('\n─── Step Results ───');
+          for (const [idx, output] of stepEntries) {
+            const step = c.steps[parseInt(idx, 10)];
+            const label = step?.role ?? step?.agent ?? `step ${idx}`;
+            console.log(`\n[${label}] (${step?.agent}):`);
+            const trimmed = output.length > 500 ? output.slice(0, 500) + '...' : output;
+            console.log(trimmed);
+          }
+        }
+
+        if (c.finalOutput) {
+          console.log('\n─── Final Output ───');
+          console.log(c.finalOutput);
+        }
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+
+  // List combos
+  combo.command('list')
+    .description('List recent combos')
+    .option('--limit <n>', 'Number of combos', '20')
+    .action(async (options: { limit?: string }) => {
+      const client = new HttpClient();
+      try {
+        const combos = await client.get<ComboDescriptor[]>(`/combos?limit=${options.limit ?? '20'}`);
+        if (combos.length === 0) {
+          console.log('No combos found.');
+          return;
+        }
+        console.log('ID           Pattern        Status     Name');
+        console.log('─'.repeat(60));
+        for (const c of combos) {
+          console.log(`${c.comboId}  ${c.pattern.padEnd(14)} ${c.status.padEnd(10)} ${c.name}`);
+        }
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/cli/commands/costs.ts

@@ -0,0 +1,33 @@
+import type { Command } from 'commander';
+import { HttpClient } from '../http-client.js';
+import type { CostSummary } from '../../types.js';
+
+export function registerCostsCommand(program: Command): void {
+  program
+    .command('costs')
+    .description('Show cost summary')
+    .action(async () => {
+      const client = new HttpClient();
+      try {
+        const costs = await client.get<CostSummary>('/costs');
+        console.log('Cost Summary');
+        console.log('─'.repeat(40));
+        console.log(`  Daily:    $${costs.daily.toFixed(2)}${costs.dailyLimit ? ` / $${costs.dailyLimit.toFixed(2)}` : ''}`);
+        console.log(`  Monthly:  $${costs.monthly.toFixed(2)}${costs.monthlyLimit ? ` / $${costs.monthlyLimit.toFixed(2)}` : ''}`);
+        console.log(`  All Time: $${costs.allTime.toFixed(2)}`);
+        console.log('');
+        console.log('By Agent:');
+        const agents = Object.entries(costs.byAgent);
+        if (agents.length === 0) {
+          console.log('  (no cost data yet)');
+        } else {
+          for (const [id, cost] of agents) {
+            console.log(`  ${id.padEnd(10)} $${cost.toFixed(2)}`);
+          }
+        }
+      } catch (err) {
+        console.error(`Error: ${(err as Error).message}`);
+        process.exit(1);
+      }
+    });
+}