@kognai/orchestrator-core 0.1.0

package/dist/lib/llm-cost-table.d.ts

@@ -0,0 +1,36 @@
+/**
+ * llm-cost-table.ts — Per-model USD-per-million-tokens pricing + computeCost.
+ *
+ * Used by the orchestrator (after every callLLM) to compute the dollar cost
+ * of each LLM call from real input/output token counts, then write that to
+ * the wallet ledger so the anti-burn gates (sprint-runner's isOverDailyBudget
+ * + ceo-wallet's deductCost) actually have data to act on.
+ *
+ * Pricing as of 2026-05-20. Update when vendors change rates. Sources:
+ *   - Anthropic public pricing page
+ *   - MiniMax public pricing (M2.5)
+ *   - Google Gemini 2.5 Flash via OpenClaw gateway (with 5% router fee)
+ *   - Ollama local models = $0
+ *
+ * Stdlib only. NO LLM calls.
+ *
+ * Created: sprint-1566 task `wallet_ledger_anthropic_calls` (F3) +
+ * `fix_cost_model_recorder` (F0e).
+ */
+export interface ModelPricing {
+    input_per_million: number;
+    output_per_million: number;
+}
+/** Pricing table. Keys are canonical model identifiers used by the orchestrator
+ *  and ClawRouter. Aliases (legacy names, short names) map to the canonical
+ *  via the resolveModel helper below. */
+export declare const LLM_COSTS: Record<string, ModelPricing>;
+/** Normalize a model name to the table key. Strips common prefixes (provider/)
+ *  if not in the table, lowercases for case-insensitive lookup of legacy names. */
+export declare function resolveModel(model: string): {
+    canonical: string;
+    pricing: ModelPricing;
+    known: boolean;
+};
+/** Compute USD cost for one LLM call. Returns 0 for unknown tokens (defensive). */
+export declare function computeCost(model: string, input_tokens: number, output_tokens: number): number;

package/dist/lib/llm-cost-table.js

@@ -0,0 +1,90 @@
+"use strict";
+/**
+ * llm-cost-table.ts — Per-model USD-per-million-tokens pricing + computeCost.
+ *
+ * Used by the orchestrator (after every callLLM) to compute the dollar cost
+ * of each LLM call from real input/output token counts, then write that to
+ * the wallet ledger so the anti-burn gates (sprint-runner's isOverDailyBudget
+ * + ceo-wallet's deductCost) actually have data to act on.
+ *
+ * Pricing as of 2026-05-20. Update when vendors change rates. Sources:
+ *   - Anthropic public pricing page
+ *   - MiniMax public pricing (M2.5)
+ *   - Google Gemini 2.5 Flash via OpenClaw gateway (with 5% router fee)
+ *   - Ollama local models = $0
+ *
+ * Stdlib only. NO LLM calls.
+ *
+ * Created: sprint-1566 task `wallet_ledger_anthropic_calls` (F3) +
+ * `fix_cost_model_recorder` (F0e).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_COSTS = void 0;
+exports.resolveModel = resolveModel;
+exports.computeCost = computeCost;
+/** Pricing table. Keys are canonical model identifiers used by the orchestrator
+ *  and ClawRouter. Aliases (legacy names, short names) map to the canonical
+ *  via the resolveModel helper below. */
+exports.LLM_COSTS = {
+    // Anthropic
+    'claude-sonnet-4-20250514': { input_per_million: 3.00, output_per_million: 15.00 },
+    'claude-haiku-4-5-20251001': { input_per_million: 0.80, output_per_million: 4.00 },
+    'claude-opus-4': { input_per_million: 15.00, output_per_million: 75.00 },
+    // MiniMax
+    'MiniMax-M2.5': { input_per_million: 0.50, output_per_million: 2.00 },
+    'minimax-m2.5': { input_per_million: 0.50, output_per_million: 2.00 },
+    // OpenAI (Codex review path)
+    'gpt-5-codex': { input_per_million: 5.00, output_per_million: 20.00 },
+    'codex': { input_per_million: 5.00, output_per_million: 20.00 },
+    // Google via OpenClaw gateway (+5% router fee already in the published rate)
+    'google/gemini-2.5-flash': { input_per_million: 0.35, output_per_million: 1.40 },
+    'gemini-2.5-flash': { input_per_million: 0.35, output_per_million: 1.40 },
+    // xAI Grok (X Premium subscription model — flat-rate, but per-token rate
+    // here approximates the marginal cost beyond subscription. Adjust if we
+    // ever pay metered.)
+    'grok-4': { input_per_million: 3.00, output_per_million: 15.00 },
+    // Ollama / local models — free
+    'qwen3:0.6b': { input_per_million: 0, output_per_million: 0 },
+    'qwen3:4b': { input_per_million: 0, output_per_million: 0 },
+    'qwen3:14b': { input_per_million: 0, output_per_million: 0 },
+    'qwen3:32b': { input_per_million: 0, output_per_million: 0 },
+    'deepseek-r1:14b': { input_per_million: 0, output_per_million: 0 },
+    'gemma4:26b': { input_per_million: 0, output_per_million: 0 },
+    // OpenClaw gateway pseudo-models (routed downstream — billed there too;
+    // here we mark them 0 so we don't double-count when the real model also
+    // gets recorded via the routeCall result.model field)
+    'openclaw/main': { input_per_million: 0, output_per_million: 0 },
+    'openclaw': { input_per_million: 0, output_per_million: 0 },
+    'openclaw/default': { input_per_million: 0, output_per_million: 0 },
+};
+/** Fallback used when an unknown model name shows up. Conservative — assumes
+ *  Sonnet-grade cost so we over-count rather than under-count. Logs a warning
+ *  via the recorder so we know to add the model to the table. */
+const UNKNOWN_FALLBACK = { input_per_million: 3.00, output_per_million: 15.00 };
+/** Normalize a model name to the table key. Strips common prefixes (provider/)
+ *  if not in the table, lowercases for case-insensitive lookup of legacy names. */
+function resolveModel(model) {
+    if (!model || model === 'unknown') {
+        return { canonical: 'unknown', pricing: UNKNOWN_FALLBACK, known: false };
+    }
+    if (exports.LLM_COSTS[model])
+        return { canonical: model, pricing: exports.LLM_COSTS[model], known: true };
+    // Try lowercase
+    const lower = model.toLowerCase();
+    if (exports.LLM_COSTS[lower])
+        return { canonical: lower, pricing: exports.LLM_COSTS[lower], known: true };
+    // Try without provider/ prefix
+    const noPrefix = model.includes('/') ? model.split('/').pop() : model;
+    if (exports.LLM_COSTS[noPrefix])
+        return { canonical: noPrefix, pricing: exports.LLM_COSTS[noPrefix], known: true };
+    return { canonical: model, pricing: UNKNOWN_FALLBACK, known: false };
+}
+/** Compute USD cost for one LLM call. Returns 0 for unknown tokens (defensive). */
+function computeCost(model, input_tokens, output_tokens) {
+    if (!input_tokens && !output_tokens)
+        return 0;
+    const { pricing } = resolveModel(model);
+    const inCost = (input_tokens || 0) * pricing.input_per_million / 1_000_000;
+    const outCost = (output_tokens || 0) * pricing.output_per_million / 1_000_000;
+    return inCost + outCost;
+}

package/dist/lib/local-model-router.d.ts

@@ -0,0 +1,27 @@
+/**
+ * local-model-router.ts — Decides whether a task runs locally (Ollama) or
+ * goes to the cloud (ClawRouter), and which local model to use.
+ */
+import { WalletState } from './wallet-state';
+export type LocalTier = 'nano' | 'local' | 'power' | 'heavy';
+export interface LocalRoute {
+    model: string;
+    tier: LocalTier;
+}
+interface Task {
+    task_target?: string;
+    task_type?: string;
+    title?: string;
+    priority?: string;
+}
+/**
+ * Decide whether this task should run locally.
+ * Priority: explicit task_target > wallet state > task complexity heuristic
+ */
+export declare function shouldRunLocally(task: Task, wallet: WalletState, sovereign?: boolean): boolean;
+/**
+ * Select the local Ollama model for a given task type.
+ * Falls back to qwen3:14b (the always-loaded workhorse) if unknown type.
+ */
+export declare function selectLocalModel(taskType: string): LocalRoute;
+export {};

package/dist/lib/local-model-router.js

@@ -0,0 +1,61 @@
+"use strict";
+/**
+ * local-model-router.ts — Decides whether a task runs locally (Ollama) or
+ * goes to the cloud (ClawRouter), and which local model to use.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shouldRunLocally = shouldRunLocally;
+exports.selectLocalModel = selectLocalModel;
+const LOCAL_MODEL_MAP = {
+    // Nano tier — sub-second, ~120 tok/s
+    classify: { model: 'qwen3:0.6b', tier: 'nano' },
+    format: { model: 'qwen3:0.6b', tier: 'nano' },
+    // Local tier — fast, ~60 tok/s
+    summarize: { model: 'qwen3:4b', tier: 'local' },
+    draft: { model: 'qwen3:4b', tier: 'local' },
+    'codebase-scan': { model: 'qwen3:4b', tier: 'local' },
+    // Power tier — workhorse, ~50 tok/s
+    code: { model: 'qwen3:14b', tier: 'power' },
+    content: { model: 'qwen3:14b', tier: 'power' },
+    data: { model: 'qwen3:14b', tier: 'power' },
+    lang: { model: 'qwen3:14b', tier: 'power' },
+    audit: { model: 'qwen3:14b', tier: 'power' },
+    util: { model: 'qwen3:14b', tier: 'power' },
+    'agent-framework': { model: 'qwen3:14b', tier: 'power' },
+    // Reasoning — deepseek-r1, ~40 tok/s
+    reason: { model: 'deepseek-r1:14b', tier: 'power' },
+    // Heavy tier — qwen3:32b, 20GB RAM, single-task only
+    'refactor-complex': { model: 'qwen3:32b', tier: 'heavy' },
+};
+/**
+ * Decide whether this task should run locally.
+ * Priority: explicit task_target > wallet state > task complexity heuristic
+ */
+function shouldRunLocally(task, wallet, sovereign = false) {
+    // Explicit override: sovereign mode or wallet frozen → everything local
+    if (sovereign || wallet.isFrozen)
+        return true;
+    // Explicit task_target: local → always local
+    if (task.task_target === 'local')
+        return true;
+    // Explicit cloud targets → never local (unless sovereign)
+    if (task.task_target === 'cloud-exec' || task.task_target === 'cloud-post')
+        return false;
+    // Wallet degraded (≥80%) → push non-critical tasks local
+    if (wallet.isDegraded) {
+        const taskType = (task.task_type || '').toLowerCase();
+        const nonCritical = ['util', 'content', 'data', 'summarize', 'draft', 'codebase-scan'];
+        if (nonCritical.includes(taskType))
+            return true;
+        if (task.priority !== 'critical' && task.priority !== 'high')
+            return true;
+    }
+    return false;
+}
+/**
+ * Select the local Ollama model for a given task type.
+ * Falls back to qwen3:14b (the always-loaded workhorse) if unknown type.
+ */
+function selectLocalModel(taskType) {
+    return LOCAL_MODEL_MAP[taskType] || LOCAL_MODEL_MAP['code'];
+}

package/dist/lib/mc-client.d.ts

@@ -0,0 +1,51 @@
+/**
+ * mc-client.ts — Mission Control API client for Invoica agents
+ *
+ * Provides lightweight connect/heartbeat/token-reporting for any Invoica agent
+ * to register itself with the Mission Control dashboard.
+ *
+ * API (from builderz-labs/mission-control):
+ *   POST   /api/connect                 → register, get connection_id + agent_id
+ *   POST   /api/agents/:id/heartbeat    → keep-alive (every 30s for long-running agents)
+ *   POST   /api/tokens                  → report token usage for cost tracking
+ *   DELETE /api/connect                 → deregister on shutdown
+ *
+ * Auth: Bearer token = MC_API_KEY env var
+ * Base URL: MC_BASE_URL env var (default http://localhost:3010)
+ *
+ * Fails silently if Mission Control is not running or MC_API_KEY is not set.
+ *
+ * Usage (long-running agent):
+ *   const mc = new MCClient('ceo-ai-bot', 'executive');
+ *   await mc.connect();
+ *   mc.startHeartbeatLoop(30_000);
+ *   process.on('SIGTERM', async () => { mc.stopHeartbeatLoop(); await mc.disconnect(); });
+ *
+ * Usage (cron agent):
+ *   const mc = new MCClient('memory-agent', 'observer');
+ *   await mc.connect();
+ *   // ... do work ...
+ *   await mc.reportTokens('claude-haiku-4-5', 800, 400);
+ *   await mc.disconnect();
+ */
+export declare class MCClient {
+    private readonly agentName;
+    private readonly agentRole;
+    private connectionId;
+    private agentId;
+    private heartbeatTimer;
+    private connected;
+    constructor(agentName: string, agentRole?: string);
+    connect(): Promise<boolean>;
+    heartbeat(tokenUsage?: {
+        model: string;
+        inputTokens: number;
+        outputTokens: number;
+    }): Promise<void>;
+    reportTokens(model: string, inputTokens: number, outputTokens: number, operation?: string): Promise<void>;
+    disconnect(): Promise<void>;
+    startHeartbeatLoop(intervalMs?: number): void;
+    stopHeartbeatLoop(): void;
+    runSession<T>(fn: (mc: MCClient) => Promise<T>): Promise<T>;
+}
+export declare function createMCClient(agentName: string, agentRole?: string): MCClient;

package/dist/lib/mc-client.js

@@ -0,0 +1,249 @@
+"use strict";
+/**
+ * mc-client.ts — Mission Control API client for Invoica agents
+ *
+ * Provides lightweight connect/heartbeat/token-reporting for any Invoica agent
+ * to register itself with the Mission Control dashboard.
+ *
+ * API (from builderz-labs/mission-control):
+ *   POST   /api/connect                 → register, get connection_id + agent_id
+ *   POST   /api/agents/:id/heartbeat    → keep-alive (every 30s for long-running agents)
+ *   POST   /api/tokens                  → report token usage for cost tracking
+ *   DELETE /api/connect                 → deregister on shutdown
+ *
+ * Auth: Bearer token = MC_API_KEY env var
+ * Base URL: MC_BASE_URL env var (default http://localhost:3010)
+ *
+ * Fails silently if Mission Control is not running or MC_API_KEY is not set.
+ *
+ * Usage (long-running agent):
+ *   const mc = new MCClient('ceo-ai-bot', 'executive');
+ *   await mc.connect();
+ *   mc.startHeartbeatLoop(30_000);
+ *   process.on('SIGTERM', async () => { mc.stopHeartbeatLoop(); await mc.disconnect(); });
+ *
+ * Usage (cron agent):
+ *   const mc = new MCClient('memory-agent', 'observer');
+ *   await mc.connect();
+ *   // ... do work ...
+ *   await mc.reportTokens('claude-haiku-4-5', 800, 400);
+ *   await mc.disconnect();
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCClient = void 0;
+exports.createMCClient = createMCClient;
+const http = __importStar(require("http"));
+const https = __importStar(require("https"));
+// ── Config ──────────────────────────────────────────────────────────────────
+const MC_BASE_URL = process.env.MC_BASE_URL || 'http://localhost:3010';
+const MC_API_KEY = process.env.MC_API_KEY || '';
+const TOOL_NAME = 'invoica-agent';
+const TOOL_VERSION = '1.0.0';
+// Mission Control model pricing keys for common Invoica models
+// (maps our internal names to MC's pricing table names)
+const MODEL_MAP = {
+    'claude-haiku-4-5': 'claude-haiku-4-5',
+    'claude-3-5-haiku-latest': 'anthropic/claude-3-5-haiku-latest',
+    'claude-sonnet-4-5': 'claude-sonnet-4',
+    'claude-3-5-sonnet-20241022': 'claude-sonnet-4',
+    'MiniMax-Text-01': 'minimax/minimax-m2.1',
+};
+// ── HTTP helper ──────────────────────────────────────────────────────────────
+function mcRequest(method, path, body, timeoutMs = 8_000) {
+    return new Promise((resolve) => {
+        if (!MC_API_KEY) {
+            resolve(null);
+            return;
+        }
+        const bodyStr = body ? JSON.stringify(body) : '';
+        let url;
+        try {
+            url = new URL(path, MC_BASE_URL);
+        }
+        catch {
+            resolve(null);
+            return;
+        }
+        const isHttps = url.protocol === 'https:';
+        const lib = isHttps ? https : http;
+        const defaultPort = isHttps ? 443 : 3010;
+        const options = {
+            hostname: url.hostname,
+            port: url.port ? parseInt(url.port, 10) : defaultPort,
+            path: url.pathname + url.search,
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                'Authorization': `Bearer ${MC_API_KEY}`,
+                ...(bodyStr ? { 'Content-Length': String(Buffer.byteLength(bodyStr)) } : {}),
+            },
+        };
+        const req = lib.request(options, (res) => {
+            let data = '';
+            res.on('data', (c) => (data += c));
+            res.on('end', () => {
+                try {
+                    resolve(JSON.parse(data));
+                }
+                catch {
+                    resolve({});
+                }
+            });
+        });
+        req.setTimeout(timeoutMs, () => { req.destroy(); resolve(null); });
+        req.on('error', () => resolve(null));
+        if (bodyStr)
+            req.write(bodyStr);
+        req.end();
+    });
+}
+// ── MCClient class ───────────────────────────────────────────────────────────
+class MCClient {
+    agentName;
+    agentRole;
+    connectionId = null;
+    agentId = null;
+    heartbeatTimer = null;
+    connected = false;
+    constructor(agentName, agentRole = 'agent') {
+        this.agentName = agentName;
+        this.agentRole = agentRole;
+    }
+    // ── Connect ───────────────────────────────────────────────────────────────
+    async connect() {
+        if (!MC_API_KEY)
+            return false;
+        try {
+            const res = await mcRequest('POST', '/api/connect', {
+                tool_name: TOOL_NAME,
+                tool_version: TOOL_VERSION,
+                agent_name: this.agentName,
+                agent_role: this.agentRole,
+            });
+            if (!res?.connection_id)
+                return false;
+            this.connectionId = res.connection_id;
+            this.agentId = Number(res.agent_id);
+            this.connected = true;
+            console.log(`[MCClient] ${this.agentName} connected to Mission Control (agent_id=${this.agentId})`);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    // ── Heartbeat ─────────────────────────────────────────────────────────────
+    async heartbeat(tokenUsage) {
+        if (!this.agentId || !this.connected)
+            return;
+        try {
+            const body = { connection_id: this.connectionId };
+            if (tokenUsage) {
+                body.token_usage = {
+                    model: MODEL_MAP[tokenUsage.model] || tokenUsage.model,
+                    inputTokens: tokenUsage.inputTokens,
+                    outputTokens: tokenUsage.outputTokens,
+                };
+            }
+            await mcRequest('POST', `/api/agents/${this.agentId}/heartbeat`, body);
+        }
+        catch { /* silent */ }
+    }
+    // ── Report token usage (standalone, without heartbeat) ────────────────────
+    async reportTokens(model, inputTokens, outputTokens, operation = 'agent_run') {
+        if (!MC_API_KEY)
+            return;
+        try {
+            await mcRequest('POST', '/api/tokens', {
+                model: MODEL_MAP[model] || model,
+                sessionId: `${this.agentName}:cli`,
+                inputTokens,
+                outputTokens,
+                operation,
+            });
+        }
+        catch { /* silent */ }
+    }
+    // ── Disconnect ────────────────────────────────────────────────────────────
+    async disconnect() {
+        if (!this.connectionId || !this.connected)
+            return;
+        try {
+            await mcRequest('DELETE', '/api/connect', { connection_id: this.connectionId });
+            console.log(`[MCClient] ${this.agentName} disconnected from Mission Control`);
+        }
+        catch { /* silent */ }
+        finally {
+            this.connected = false;
+            this.connectionId = null;
+            this.agentId = null;
+        }
+    }
+    // ── Heartbeat loop (for long-running agents) ──────────────────────────────
+    startHeartbeatLoop(intervalMs = 30_000) {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            this.heartbeat().catch(() => { });
+        }, intervalMs);
+        // Don't block process exit
+        if (typeof this.heartbeatTimer === 'object' && 'unref' in this.heartbeatTimer) {
+            this.heartbeatTimer.unref();
+        }
+    }
+    stopHeartbeatLoop() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+    }
+    // ── Convenience: full lifecycle for cron agents ───────────────────────────
+    // Connects, runs the provided function, then disconnects.
+    async runSession(fn) {
+        await this.connect();
+        try {
+            return await fn(this);
+        }
+        finally {
+            await this.disconnect();
+        }
+    }
+}
+exports.MCClient = MCClient;
+// ── Convenience singleton factory ─────────────────────────────────────────────
+function createMCClient(agentName, agentRole) {
+    return new MCClient(agentName, agentRole);
+}

package/dist/lib/model-router-contract.d.ts

@@ -0,0 +1,91 @@
+/**
+ * model-router-contract.ts — TICKET-215 Wave C: the engine's model-routing SEAM.
+ *
+ * This is the zero-dep interface that decouples the orchestrator from any
+ * concrete router. The orchestrator depends ONLY on this contract; the actual
+ * implementation is injected at startup (see model-router-registry.ts).
+ *
+ * WHY: ClawRouter v2 (the production router) imports `viem` for on-chain x402
+ * payments. We do NOT want `viem` in @kognai/orchestrator-core — that would make
+ * every adopter (e.g. Invoica, which never routes on-chain) carry web3. So the
+ * viem-backed router lives OUTSIDE core (Kognai injects it); products that don't
+ * route on-chain inject their own / use a local default. viem stays absent from
+ * core's dependency tree entirely.
+ *
+ * These request/response types are the canonical source of truth — clawrouter-v2
+ * imports them from here and re-exports for back-compat.
+ */
+export type TierClass = 'text' | 'creative';
+export type TextComplexity = 'nano' | 'local' | 'power' | 'exec' | 'apex';
+export type CreativeModality = 'image' | 'video' | 'speech' | 'music' | 'transcription' | 'visual_understanding';
+export type CreativeQuality = 'fast' | 'high' | 'emotional';
+export interface ClawRouterV2Request {
+    task_type: string;
+    tier_class: TierClass;
+    complexity?: TextComplexity;
+    modality?: CreativeModality;
+    quality?: CreativeQuality;
+    context_tokens: number;
+    constitutional_flag: boolean;
+    agent_id: string;
+    payload: {
+        system?: string;
+        prompt?: string;
+        messages?: Array<{
+            role: string;
+            content: string;
+        }>;
+        [key: string]: any;
+    };
+}
+export interface ClawRouterV2Response {
+    content: string;
+    model: string;
+    tier: string;
+    local: boolean;
+    cost_usd: number;
+    input_tokens: number;
+    output_tokens: number;
+    qcg_compressed: boolean;
+    tokens_saved_by_qcg: number;
+    agent_id: string;
+    task_type: string;
+    timestamp: string;
+}
+export interface CallLLMOptions {
+    systemPrompt?: string;
+    complexity?: TextComplexity;
+    constitutional?: boolean;
+    agentId?: string;
+    taskType?: string;
+    maxTokens?: number;
+}
+export interface CallLLMResult {
+    content: string;
+    model: string;
+    tier: string;
+    cost_usd: number;
+}
+export interface HealthCheckResult {
+    ollama: boolean;
+    gateway: boolean;
+    models: string[];
+}
+export interface DailyCostDigest {
+    total_usd: number;
+    by_tier: Record<string, number>;
+    by_agent: Record<string, number>;
+    tokens_saved_by_qcg: number;
+    call_count: number;
+}
+/**
+ * The single door every LLM call passes through (Execution Protocol §17).
+ * Implementations: Kognai's viem-backed ClawRouter v2 (injected), a future
+ * local-only default, or any product-specific router.
+ */
+export interface ModelRouter {
+    routeCall(req: ClawRouterV2Request): Promise<ClawRouterV2Response>;
+    callLLM(prompt: string, opts?: CallLLMOptions): Promise<CallLLMResult>;
+    healthCheck(): Promise<HealthCheckResult>;
+    getDailyCostDigest(): DailyCostDigest;
+}

package/dist/lib/model-router-contract.js

@@ -0,0 +1,19 @@
+"use strict";
+/**
+ * model-router-contract.ts — TICKET-215 Wave C: the engine's model-routing SEAM.
+ *
+ * This is the zero-dep interface that decouples the orchestrator from any
+ * concrete router. The orchestrator depends ONLY on this contract; the actual
+ * implementation is injected at startup (see model-router-registry.ts).
+ *
+ * WHY: ClawRouter v2 (the production router) imports `viem` for on-chain x402
+ * payments. We do NOT want `viem` in @kognai/orchestrator-core — that would make
+ * every adopter (e.g. Invoica, which never routes on-chain) carry web3. So the
+ * viem-backed router lives OUTSIDE core (Kognai injects it); products that don't
+ * route on-chain inject their own / use a local default. viem stays absent from
+ * core's dependency tree entirely.
+ *
+ * These request/response types are the canonical source of truth — clawrouter-v2
+ * imports them from here and re-exports for back-compat.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/lib/model-router-registry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * model-router-registry.ts — TICKET-215 Wave C: the injection point for the
+ * model-routing seam (see model-router-contract.ts).
+ *
+ * Products wire their router at startup:
+ *   - Kognai:  setModelRouter(<viem-backed ClawRouter v2 adapter>)
+ *   - others:  inject a local/product-specific ModelRouter, or leave the
+ *              fail-loud default in place until one is provided.
+ *
+ * The default is intentionally NOT a silent no-op: a routeCall with no router
+ * configured throws a clear, actionable error rather than returning empty
+ * completions. Replace with a real local-only default when one exists.
+ *
+ * Per-agent gating note: an injected router MAY consult the ACP capability
+ * registry (see ./acp) before performing a paid/on-chain call, so that only
+ * capability-bearing agents can spend — everyone else falls back to local.
+ */
+import type { ModelRouter } from './model-router-contract';
+/** Inject the concrete router. Call once at process startup, before routing. */
+export declare function setModelRouter(router: ModelRouter): void;
+/** Resolve the active router. The orchestrator routes every LLM call through this. */
+export declare function getModelRouter(): ModelRouter;
+/** True once a real router has been injected (i.e. not the fail-loud default). */
+export declare function isModelRouterConfigured(): boolean;