zouroboros-swarm 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlandoj
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# zouroboros-swarm
+
+> Multi-agent orchestration with circuit breakers and 6-signal routing
+
+## Features
+
+- **Circuit Breaker V2** — CLOSED/OPEN/HALF_OPEN states with category-aware failure tracking
+- **6-Signal Composite Routing** — Capability, health, complexity fit, history, procedure, temporal
+- **Hierarchical Orchestration** — Hermes/Claude parent tasks can self-decompose under centralized delegation policy
+- **Executor Bridges** — Claude Code, Hermes, Gemini, Codex CLI integration
+- **DAG Execution** — Streaming and wave-based task execution modes
+- **Registry-Based** — JSON registry for executor configuration
+
+## Installation
+
+```bash
+npm install zouroboros-swarm
+# or
+pnpm add zouroboros-swarm
+```
+
+### ACP Adapter Prerequisites
+
+The swarm uses the [Agent Client Protocol (ACP)](https://github.com/agentclientprotocol) to communicate with Claude Code, Codex, and Gemini executors. Install the required adapter binaries before running:
+
+```bash
+# Install all ACP adapters
+bash packages/swarm/scripts/install-acp-adapters.sh
+
+# Verify installation
+bash packages/swarm/scripts/install-acp-adapters.sh --check
+
+# Update to latest versions
+bash packages/swarm/scripts/install-acp-adapters.sh --update
+```
+
+| Executor | Adapter | npm Package |
+|---|---|---|
+| Claude Code | `claude-agent-acp` | `@zed-industries/claude-agent-acp` |
+| Codex | `codex-acp` | `@zed-industries/codex-acp` |
+| Gemini | `gemini --acp` | `@google/gemini-cli` |
+| Hermes | bridge (no ACP adapter) | — |
+
+## Quick Start
+
+```typescript
+import { SwarmOrchestrator } from 'zouroboros-swarm';
+
+const orchestrator = new SwarmOrchestrator({
+  localConcurrency: 8,
+  timeoutSeconds: 600,
+  routingStrategy: 'balanced',
+  dagMode: 'streaming',
+});
+
+const tasks = [
+  { id: '1', persona: 'developer', task: 'Fix the auth bug in login.ts', priority: 'high' },
+  { id: '2', persona: 'reviewer', task: 'Review the PR for error handling', priority: 'medium', dependsOn: ['1'] },
+];
+
+const results = await orchestrator.run(tasks);
+```
+
+## CLI Usage
+
+```bash
+# Run a swarm campaign
+zouroboros-swarm ./tasks.json
+
+# With options
+zouroboros-swarm ./tasks.json --mode waves --concurrency 4 --strategy fast
+
+# Inspect a completed run
+zouroboros-swarm status <swarm-id>
+
+# Inspect executor routing and delegation history
+zouroboros-swarm history 10
+
+# Health check
+zouroboros-swarm doctor
+```
+
+`status <swarm-id>` now surfaces persisted hierarchical telemetry from the results file, including delegated parent count, child task count, artifact count, reroutes, and effective executors.
+
+`history [limit]` reads `executor-history.db` and prints delegation-aware routing history per executor/category, including:
+- base success rate
+- delegated attempt/success rate
+- child success rate
+- average child count
+- average child duration
+
+## Task Format
+
+```json
+[
+  {
+    "id": "task-1",
+    "persona": "developer",
+    "task": "Implement user authentication",
+    "priority": "high",
+    "executor": "claude-code",
+    "dependsOn": [],
+    "timeoutSeconds": 600
+  },
+  {
+    "id": "task-2",
+    "persona": "tester",
+    "task": "Write tests for auth",
+    "priority": "medium",
+    "dependsOn": ["task-1"]
+  }
+]
+```
+
+Hierarchical delegation is available through an optional `delegation` block on each task:
+
+```json
+{
+  "id": "implementation-safe",
+  "executor": "claude-code",
+  "task": "Implement the parser cleanup and synthesize the result.",
+  "delegation": {
+    "mode": "auto",
+    "maxChildren": 2,
+    "writeScopes": [
+      { "childId": "parser-a", "paths": ["src/parser/a.ts"] },
+      { "childId": "parser-b", "paths": ["src/parser/b.ts"] }
+    ]
+  }
+}
+```
+
+- `mode: "auto"` enables executor-side self-decomposition when policy allows it.
+- Mutation tasks require disjoint `writeScopes`; otherwise they are forced to remain leaf tasks.
+- Results now persist parent/child telemetry, including `delegated`, `effectiveExecutor`, `childRecords`, and artifact lists.
+
+Example status output for a completed hierarchical run:
+
+```text
+🔍 Swarm Status: hierarchical-broader-validation-test
+   Status: complete
+   Results: ~/.swarm/results/hierarchical-broader-validation-test.json
+   Outcome: 4/4 succeeded, 0 failed
+   Duration: 4s
+   Delegated: 3 parent / 5 child
+   Artifacts: 4
+   Reroutes: 1
+   Executors: hermes, claude-code
+```
+
+## Routing Strategies
+
+| Strategy | Best For | Weight Focus |
+|----------|----------|--------------|
+| `fast` | Quick iterations | Complexity fit (40%), Health (20%) |
+| `reliable` | Production tasks | Health (35%), History (18%) |
+| `balanced` | General use | Even distribution |
+| `explore` | New domains | Capability (35%), Complexity (18%) |
+
+## Circuit Breaker States
+
+- **CLOSED** — Normal operation, requests pass through
+- **OPEN** — Failure threshold exceeded, requests blocked
+- **HALF_OPEN** — Testing if service recovered
+
+## Executor Registry
+
+Create `~/.zouroboros/executors.json`:
+
+```json
+{
+  "executors": [
+    {
+      "id": "claude-code",
+      "name": "Claude Code",
+      "executor": "local",
+      "bridge": "bridges/claude-code-bridge.sh",
+      "expertise": ["code-generation", "debugging", "refactoring"],
+      "bestFor": ["Complex multi-file changes"]
+    }
+  ]
+}
+```
+
+## License
+
+MIT

package/dist/api/server.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Swarm API Server — embedded Hono server with SSE support.
+ *
+ * Exposes swarm state as REST endpoints + real-time SSE activity stream.
+ * Registered as a Zo user service for persistent hosting.
+ */
+import { Hono } from 'hono';
+import { BudgetGovernor } from '../budget/governor.js';
+import { HeartbeatScheduler } from '../heartbeat/scheduler.js';
+import { RoleRegistry } from '../roles/registry.js';
+export interface SwarmAPIConfig {
+    port: number;
+    authToken?: string;
+    dbPath?: string;
+}
+export interface SSEEvent {
+    type: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+export declare function createSwarmAPI(config: SwarmAPIConfig): {
+    app: Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;
+    budget: BudgetGovernor;
+    heartbeat: HeartbeatScheduler;
+    roles: RoleRegistry;
+    broadcastSSE: (event: SSEEvent) => void;
+};
+export declare function startSwarmServer(config?: Partial<SwarmAPIConfig>): void;

package/dist/api/server.js

@@ -0,0 +1,223 @@
+/**
+ * Swarm API Server — embedded Hono server with SSE support.
+ *
+ * Exposes swarm state as REST endpoints + real-time SSE activity stream.
+ * Registered as a Zo user service for persistent hosting.
+ */
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { BudgetGovernor } from '../budget/governor.js';
+import { HeartbeatScheduler } from '../heartbeat/scheduler.js';
+import { RoleRegistry } from '../roles/registry.js';
+import { getDb } from '../db/schema.js';
+export function createSwarmAPI(config) {
+    const app = new Hono();
+    const budget = new BudgetGovernor(config.dbPath);
+    const heartbeat = new HeartbeatScheduler(config.dbPath);
+    const roles = new RoleRegistry(config.dbPath);
+    const db = getDb(config.dbPath);
+    const sseClients = new Set();
+    const eventLog = [];
+    app.use('*', cors());
+    if (config.authToken) {
+        app.use('/api/swarm/*', async (c, next) => {
+            const auth = c.req.header('authorization');
+            if (!auth?.startsWith('Bearer ') || auth.slice(7) !== config.authToken) {
+                return c.json({ error: 'Unauthorized' }, 401);
+            }
+            await next();
+        });
+    }
+    function broadcastSSE(event) {
+        eventLog.push(event);
+        if (eventLog.length > 1000)
+            eventLog.splice(0, eventLog.length - 500);
+        const payload = `data: ${JSON.stringify(event)}\n\n`;
+        for (const controller of sseClients) {
+            try {
+                controller.enqueue(new TextEncoder().encode(payload));
+            }
+            catch {
+                sseClients.delete(controller);
+            }
+        }
+    }
+    budget.on((evt) => broadcastSSE({ type: evt.type, data: evt.data, timestamp: evt.timestamp }));
+    heartbeat.on((evt) => broadcastSSE({
+        type: 'heartbeat',
+        data: { swarmId: evt.swarmId, beat: evt.beatNumber, status: evt.status },
+        timestamp: evt.timestamp,
+    }));
+    // --- Status ---
+    app.get('/api/swarm/status', (c) => {
+        return c.json({
+            status: 'running',
+            timestamp: Date.now(),
+            executors: ['claude-code', 'gemini', 'codex', 'hermes'],
+            heartbeats: {
+                active: Array.from({ length: 4 }, (_, i) => ['claude-code', 'gemini', 'codex', 'hermes'][i])
+                    .filter(id => heartbeat.isRunning(id)),
+            },
+        });
+    });
+    // --- Tasks ---
+    app.get('/api/swarm/tasks', (c) => {
+        const executor = c.req.query('executor');
+        const status = c.req.query('status');
+        // Tasks are managed by the orchestrator runtime; return from event log
+        const taskEvents = eventLog.filter(e => e.type.startsWith('task:') &&
+            (!executor || e.data.executorId === executor) &&
+            (!status || e.data.status === status));
+        return c.json({ tasks: taskEvents, count: taskEvents.length });
+    });
+    app.get('/api/swarm/tasks/:id', (c) => {
+        const taskId = c.req.param('id');
+        const events = eventLog.filter(e => e.data.taskId === taskId);
+        return c.json({ taskId, events });
+    });
+    // --- Budget ---
+    app.get('/api/swarm/budget', (c) => {
+        const swarmId = c.req.query('swarmId') ?? 'default';
+        const state = budget.getState(swarmId);
+        return c.json(state);
+    });
+    app.post('/api/swarm/budget/init', async (c) => {
+        const body = await c.req.json();
+        budget.initSwarm({
+            swarmId: body.swarmId ?? 'default',
+            totalBudgetUSD: body.totalBudgetUSD,
+            perExecutorLimits: body.perExecutorLimits,
+            alertThresholdPct: body.alertThresholdPct,
+            hardCapAction: body.hardCapAction ?? 'downgrade',
+        });
+        return c.json({ success: true });
+    });
+    // --- Health ---
+    app.get('/api/swarm/health', (c) => {
+        const executors = ['claude-code', 'gemini', 'codex', 'hermes'];
+        const health = {};
+        for (const id of executors) {
+            health[id] = {
+                state: 'CLOSED',
+                failures: 0,
+                heartbeatActive: heartbeat.isRunning(id),
+                beatCount: heartbeat.getBeatCount(id),
+            };
+        }
+        return c.json({ executors: health, timestamp: Date.now() });
+    });
+    // --- Roles CRUD ---
+    app.get('/api/swarm/roles', (c) => {
+        return c.json({ roles: roles.list() });
+    });
+    app.get('/api/swarm/roles/:id', (c) => {
+        const role = roles.get(c.req.param('id'));
+        if (!role)
+            return c.json({ error: 'Role not found' }, 404);
+        return c.json(role);
+    });
+    app.post('/api/swarm/roles', async (c) => {
+        const body = await c.req.json();
+        try {
+            const role = roles.create(body);
+            broadcastSSE({ type: 'role:created', data: { role }, timestamp: Date.now() });
+            return c.json(role, 201);
+        }
+        catch (err) {
+            return c.json({ error: err.message }, 400);
+        }
+    });
+    app.put('/api/swarm/roles/:id', async (c) => {
+        const body = await c.req.json();
+        const updated = roles.update(c.req.param('id'), body);
+        if (!updated)
+            return c.json({ error: 'Role not found' }, 404);
+        broadcastSSE({ type: 'role:updated', data: { role: updated }, timestamp: Date.now() });
+        return c.json(updated);
+    });
+    app.delete('/api/swarm/roles/:id', (c) => {
+        const deleted = roles.delete(c.req.param('id'));
+        if (!deleted)
+            return c.json({ error: 'Role not found' }, 404);
+        broadcastSSE({ type: 'role:deleted', data: { roleId: c.req.param('id') }, timestamp: Date.now() });
+        return c.json({ success: true });
+    });
+    // --- SSE Activity Stream ---
+    app.get('/api/swarm/activity', (c) => {
+        const stream = new ReadableStream({
+            start(controller) {
+                sseClients.add(controller);
+                const recent = eventLog.slice(-20);
+                for (const event of recent) {
+                    controller.enqueue(new TextEncoder().encode(`data: ${JSON.stringify(event)}\n\n`));
+                }
+            },
+            cancel(controller) {
+                sseClients.delete(controller);
+            },
+        });
+        return new Response(stream, {
+            headers: {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            },
+        });
+    });
+    // --- Dispatch ---
+    app.post('/api/swarm/dispatch', async (c) => {
+        const body = await c.req.json();
+        const swarmId = body.swarmId ?? `swarm-${Date.now()}`;
+        broadcastSSE({
+            type: 'swarm:dispatched',
+            data: { swarmId, taskCount: body.tasks?.length ?? 0 },
+            timestamp: Date.now(),
+        });
+        return c.json({ swarmId, status: 'dispatched', message: 'Swarm dispatch queued' });
+    });
+    // --- Pause / Resume / Abort ---
+    app.post('/api/swarm/pause/:taskId', (c) => {
+        const taskId = c.req.param('taskId');
+        broadcastSSE({ type: 'task:paused', data: { taskId }, timestamp: Date.now() });
+        return c.json({ taskId, status: 'paused' });
+    });
+    app.post('/api/swarm/resume/:taskId', (c) => {
+        const taskId = c.req.param('taskId');
+        broadcastSSE({ type: 'task:resumed', data: { taskId }, timestamp: Date.now() });
+        return c.json({ taskId, status: 'resumed' });
+    });
+    app.post('/api/swarm/abort/:swarmId', (c) => {
+        const swarmId = c.req.param('swarmId');
+        heartbeat.stop(swarmId);
+        broadcastSSE({ type: 'swarm:aborted', data: { swarmId }, timestamp: Date.now() });
+        return c.json({ swarmId, status: 'aborted' });
+    });
+    // --- Heartbeat control ---
+    app.post('/api/swarm/heartbeat/start', async (c) => {
+        const body = await c.req.json();
+        heartbeat.start({
+            swarmId: body.swarmId ?? 'default',
+            intervalMs: body.intervalMs ?? 60000,
+            maxBeats: body.maxBeats ?? 0,
+            onIdle: body.onIdle ?? 'sleep',
+        });
+        return c.json({ success: true, swarmId: body.swarmId ?? 'default' });
+    });
+    app.post('/api/swarm/heartbeat/stop', async (c) => {
+        const body = await c.req.json();
+        heartbeat.stop(body.swarmId ?? 'default');
+        return c.json({ success: true });
+    });
+    return { app, budget, heartbeat, roles, broadcastSSE };
+}
+export function startSwarmServer(config) {
+    const port = config?.port ?? parseInt(process.env.PORT ?? '3847', 10);
+    const authToken = config?.authToken ?? process.env.SWARM_API_TOKEN;
+    const dbPath = config?.dbPath;
+    const { app } = createSwarmAPI({ port, authToken, dbPath });
+    Bun.serve({ port, fetch: app.fetch });
+    console.log(`Swarm API server listening on port ${port}`);
+}
+if (import.meta.main) {
+    startSwarmServer();
+}

package/dist/budget/governor.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Budget Governor — per-executor and per-swarm cost tracking with hard caps.
+ *
+ * Tracks token usage, normalizes to USD, emits alerts, and enforces caps.
+ * Hard cap action: "downgrade" switches remaining tasks to cheapest executor.
+ */
+export type HardCapAction = 'pause' | 'abort' | 'downgrade';
+export interface BudgetConfig {
+    swarmId: string;
+    totalBudgetUSD: number;
+    perExecutorLimits?: Record<string, number>;
+    alertThresholdPct?: number;
+    hardCapAction?: HardCapAction;
+}
+export interface BudgetState {
+    swarmId: string;
+    totalSpentUSD: number;
+    totalBudgetUSD: number;
+    remaining: number;
+    perExecutor: Record<string, number>;
+    alertFired: boolean;
+    capReached: boolean;
+    hardCapAction: HardCapAction;
+}
+export interface BudgetEvent {
+    type: 'budget:update' | 'budget:alert' | 'budget:cap' | 'budget:downgrade';
+    swarmId: string;
+    data: Record<string, unknown>;
+    timestamp: number;
+}
+type BudgetListener = (event: BudgetEvent) => void;
+export declare class BudgetGovernor {
+    private db;
+    private listeners;
+    constructor(dbPath?: string);
+    on(listener: BudgetListener): void;
+    private emit;
+    initSwarm(config: BudgetConfig): void;
+    recordUsage(swarmId: string, executorId: string, model: string, inputTokens: number, outputTokens: number): BudgetState;
+    getState(swarmId: string): BudgetState;
+    checkExecutorLimit(swarmId: string, executorId: string): boolean;
+    getDowngradeTarget(executorId: string): {
+        executorId: string;
+        model: string;
+    };
+    private getConfig;
+}
+export {};

package/dist/budget/governor.js

@@ -0,0 +1,114 @@
+/**
+ * Budget Governor — per-executor and per-swarm cost tracking with hard caps.
+ *
+ * Tracks token usage, normalizes to USD, emits alerts, and enforces caps.
+ * Hard cap action: "downgrade" switches remaining tasks to cheapest executor.
+ */
+import { getDb } from '../db/schema.js';
+import { estimateCostUSD, getCheapestModel } from './pricing.js';
+export class BudgetGovernor {
+    db;
+    listeners = [];
+    constructor(dbPath) {
+        this.db = getDb(dbPath);
+    }
+    on(listener) {
+        this.listeners.push(listener);
+    }
+    emit(event) {
+        for (const listener of this.listeners) {
+            try {
+                listener(event);
+            }
+            catch { }
+        }
+    }
+    initSwarm(config) {
+        this.db.run(`INSERT OR REPLACE INTO budget_config (swarm_id, total_budget_usd, alert_threshold_pct, hard_cap_action)
+       VALUES (?, ?, ?, ?)`, [config.swarmId, config.totalBudgetUSD, config.alertThresholdPct ?? 80, config.hardCapAction ?? 'downgrade']);
+        if (config.perExecutorLimits) {
+            const stmt = this.db.prepare('INSERT OR REPLACE INTO budget_per_executor (swarm_id, executor_id, limit_usd) VALUES (?, ?, ?)');
+            for (const [execId, limit] of Object.entries(config.perExecutorLimits)) {
+                stmt.run(config.swarmId, execId, limit);
+            }
+        }
+    }
+    recordUsage(swarmId, executorId, model, inputTokens, outputTokens) {
+        const cost = estimateCostUSD(model, inputTokens, outputTokens);
+        const totalTokens = inputTokens + outputTokens;
+        this.db.run(`INSERT INTO swarm_budget (swarm_id, executor_id, tokens_used, cost_usd, updated_at)
+       VALUES (?, ?, ?, ?, unixepoch())
+       ON CONFLICT(swarm_id, executor_id) DO UPDATE SET
+         tokens_used = tokens_used + excluded.tokens_used,
+         cost_usd = cost_usd + excluded.cost_usd,
+         updated_at = unixepoch()`, [swarmId, executorId, totalTokens, cost]);
+        const state = this.getState(swarmId);
+        this.emit({
+            type: 'budget:update',
+            swarmId,
+            data: { executorId, cost, totalSpent: state.totalSpentUSD },
+            timestamp: Date.now(),
+        });
+        // Check alert threshold
+        const config = this.getConfig(swarmId);
+        if (config) {
+            const pct = (state.totalSpentUSD / config.total_budget_usd) * 100;
+            if (pct >= config.alert_threshold_pct && !state.alertFired) {
+                this.emit({
+                    type: 'budget:alert',
+                    swarmId,
+                    data: { percentUsed: pct, spent: state.totalSpentUSD, budget: config.total_budget_usd },
+                    timestamp: Date.now(),
+                });
+            }
+            if (state.totalSpentUSD >= config.total_budget_usd) {
+                this.emit({
+                    type: 'budget:cap',
+                    swarmId,
+                    data: { action: config.hard_cap_action, spent: state.totalSpentUSD },
+                    timestamp: Date.now(),
+                });
+            }
+        }
+        return state;
+    }
+    getState(swarmId) {
+        const config = this.getConfig(swarmId);
+        const totalBudget = config?.total_budget_usd ?? 0;
+        const hardCapAction = (config?.hard_cap_action ?? 'downgrade');
+        const alertThreshold = config?.alert_threshold_pct ?? 80;
+        const rows = this.db.query('SELECT executor_id, cost_usd FROM swarm_budget WHERE swarm_id = ?').all(swarmId);
+        const perExecutor = {};
+        let totalSpent = 0;
+        for (const row of rows) {
+            perExecutor[row.executor_id] = row.cost_usd;
+            totalSpent += row.cost_usd;
+        }
+        const pct = totalBudget > 0 ? (totalSpent / totalBudget) * 100 : 0;
+        return {
+            swarmId,
+            totalSpentUSD: totalSpent,
+            totalBudgetUSD: totalBudget,
+            remaining: Math.max(0, totalBudget - totalSpent),
+            perExecutor,
+            alertFired: pct >= alertThreshold,
+            capReached: totalBudget > 0 && totalSpent >= totalBudget,
+            hardCapAction,
+        };
+    }
+    checkExecutorLimit(swarmId, executorId) {
+        const limit = this.db.query('SELECT limit_usd FROM budget_per_executor WHERE swarm_id = ? AND executor_id = ?').get(swarmId, executorId);
+        if (!limit)
+            return true;
+        const usage = this.db.query('SELECT cost_usd FROM swarm_budget WHERE swarm_id = ? AND executor_id = ?').get(swarmId, executorId);
+        return (usage?.cost_usd ?? 0) < limit.limit_usd;
+    }
+    getDowngradeTarget(executorId) {
+        const cheapestModel = getCheapestModel(executorId);
+        const cheapestExecutor = executorId === 'hermes' ? 'hermes' : 'gemini';
+        return { executorId: cheapestExecutor, model: cheapestModel };
+    }
+    getConfig(swarmId) {
+        return this.db.query('SELECT * FROM budget_config WHERE swarm_id = ?').get(swarmId);
+    }
+}

package/dist/budget/pricing.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Per-model pricing tables for budget normalization.
+ *
+ * Prices are in USD per 1M tokens. Updated to reflect published rates.
+ */
+export interface ModelPricing {
+    inputPer1M: number;
+    outputPer1M: number;
+}
+export declare function getModelPricing(model: string): ModelPricing;
+export declare function estimateCostUSD(model: string, inputTokens: number, outputTokens: number): number;
+export declare function getCheapestModel(executorId: string): string;

package/dist/budget/pricing.js

@@ -0,0 +1,44 @@
+/**
+ * Per-model pricing tables for budget normalization.
+ *
+ * Prices are in USD per 1M tokens. Updated to reflect published rates.
+ */
+const PRICING = {
+    // Anthropic
+    'opus': { inputPer1M: 15.00, outputPer1M: 75.00 },
+    'claude-opus-4-6': { inputPer1M: 15.00, outputPer1M: 75.00 },
+    'sonnet': { inputPer1M: 3.00, outputPer1M: 15.00 },
+    'claude-sonnet-4-6': { inputPer1M: 3.00, outputPer1M: 15.00 },
+    'haiku': { inputPer1M: 0.25, outputPer1M: 1.25 },
+    'claude-haiku-4-5': { inputPer1M: 0.25, outputPer1M: 1.25 },
+    // Google
+    'gemini-2.5-pro': { inputPer1M: 1.25, outputPer1M: 10.00 },
+    'gemini-2.5-flash': { inputPer1M: 0.15, outputPer1M: 0.60 },
+    'pro': { inputPer1M: 1.25, outputPer1M: 10.00 },
+    'flash': { inputPer1M: 0.15, outputPer1M: 0.60 },
+    // OpenAI
+    'gpt-5.x': { inputPer1M: 2.50, outputPer1M: 10.00 },
+    'gpt-4.1': { inputPer1M: 2.00, outputPer1M: 8.00 },
+    'o3': { inputPer1M: 10.00, outputPer1M: 40.00 },
+    // Free / BYOK
+    'byok': { inputPer1M: 0, outputPer1M: 0 },
+    'free': { inputPer1M: 0, outputPer1M: 0 },
+};
+export function getModelPricing(model) {
+    const key = model.toLowerCase();
+    return PRICING[key] ?? { inputPer1M: 1.00, outputPer1M: 5.00 };
+}
+export function estimateCostUSD(model, inputTokens, outputTokens) {
+    const pricing = getModelPricing(model);
+    return (inputTokens / 1_000_000) * pricing.inputPer1M +
+        (outputTokens / 1_000_000) * pricing.outputPer1M;
+}
+export function getCheapestModel(executorId) {
+    switch (executorId) {
+        case 'hermes': return 'byok';
+        case 'gemini': return 'flash';
+        case 'codex': return 'gpt-4.1';
+        case 'claude-code': return 'haiku';
+        default: return 'byok';
+    }
+}