@kognai/clawrouter-x402 0.1.0

package/dist/orchestrator-core/src/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/orchestrator-core/src/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/orchestrator-core/src/lib/wallet-state.d.ts

@@ -0,0 +1,26 @@
+/**
+ * wallet-state.ts — CFO budget tracking for ClawRouter spend
+ *
+ * Accumulates spend from ClawRouter X-Payment-Amount headers.
+ * Enforces degraded (≥80%) and frozen (≥95%) modes to protect the wallet.
+ * Persists to logs/wallet/state.json across sprint runs.
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): KOGNAI_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of `resolve(__dirname, '../..')`, so the bank
+ * state layer is location-independent and ships in @kognai/orchestrator-core.
+ * When run from a product repo root, resolveEnginePaths().root === the old
+ * __dirname/../.. — same <root>/logs/wallet/state.json, no behavior change.
+ */
+export interface WalletState {
+    monthlyBudget: number;
+    spentThisMonth: number;
+    callCount: number;
+    remaining: number;
+    burnPct: number;
+    isDegraded: boolean;
+    isFrozen: boolean;
+}
+export declare function getWalletState(): WalletState;
+export declare function recordSpend(costUsdc: number): void;
+export declare function resetWallet(): void;
+export declare function logWalletStatus(): void;

package/dist/orchestrator-core/src/lib/wallet-state.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * wallet-state.ts — CFO budget tracking for ClawRouter spend
+ *
+ * Accumulates spend from ClawRouter X-Payment-Amount headers.
+ * Enforces degraded (≥80%) and frozen (≥95%) modes to protect the wallet.
+ * Persists to logs/wallet/state.json across sprint runs.
+ *
+ * TICKET-215 Phase 3b-3 (Wave B): KOGNAI_ROOT now resolves via engine-paths
+ * (KOGNAI_ROOT / cwd) instead of `resolve(__dirname, '../..')`, so the bank
+ * state layer is location-independent and ships in @kognai/orchestrator-core.
+ * When run from a product repo root, resolveEnginePaths().root === the old
+ * __dirname/../.. — same <root>/logs/wallet/state.json, no behavior change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getWalletState = getWalletState;
+exports.recordSpend = recordSpend;
+exports.resetWallet = resetWallet;
+exports.logWalletStatus = logWalletStatus;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const engine_paths_1 = require("./engine-paths");
+const KOGNAI_ROOT = (0, engine_paths_1.resolveEnginePaths)().root;
+const STATE_FILE = (0, path_1.resolve)(KOGNAI_ROOT, 'logs/wallet/state.json');
+const DEFAULT_BUDGET = parseFloat(process.env.CEO_WALLET_BUDGET_USDC || '25'); // $25/month default
+function loadState() {
+    if ((0, fs_1.existsSync)(STATE_FILE)) {
+        try {
+            const raw = JSON.parse((0, fs_1.readFileSync)(STATE_FILE, 'utf8'));
+            // Auto-reset on new month
+            const lastReset = new Date(raw.lastReset);
+            const now = new Date();
+            if (lastReset.getMonth() !== now.getMonth() || lastReset.getFullYear() !== now.getFullYear()) {
+                return freshState();
+            }
+            return raw;
+        }
+        catch { /* fall through */ }
+    }
+    return freshState();
+}
+function freshState() {
+    return {
+        monthlyBudget: DEFAULT_BUDGET,
+        spentThisMonth: 0,
+        callCount: 0,
+        lastReset: new Date().toISOString(),
+    };
+}
+function saveState(data) {
+    try {
+        (0, fs_1.mkdirSync)((0, path_1.resolve)(KOGNAI_ROOT, 'logs/wallet'), { recursive: true });
+        (0, fs_1.writeFileSync)(STATE_FILE, JSON.stringify(data, null, 2), 'utf8');
+    }
+    catch { /* non-fatal */ }
+}
+// Singleton
+let _state = loadState();
+function getWalletState() {
+    const remaining = Math.max(0, _state.monthlyBudget - _state.spentThisMonth);
+    const burnPct = (_state.spentThisMonth / _state.monthlyBudget) * 100;
+    return {
+        monthlyBudget: _state.monthlyBudget,
+        spentThisMonth: _state.spentThisMonth,
+        callCount: _state.callCount,
+        remaining,
+        burnPct,
+        isDegraded: burnPct >= 80,
+        isFrozen: burnPct >= 95,
+    };
+}
+function recordSpend(costUsdc) {
+    _state.spentThisMonth += costUsdc;
+    _state.callCount += 1;
+    saveState(_state);
+}
+function resetWallet() {
+    _state = freshState();
+    saveState(_state);
+}
+function logWalletStatus() {
+    const s = getWalletState();
+    const status = s.isFrozen ? '🔴 FROZEN' : s.isDegraded ? '🟡 DEGRADED' : '🟢 OK';
+    console.log(`  💳 Wallet ${status}: $${s.spentThisMonth.toFixed(4)}/$${s.monthlyBudget} (${s.burnPct.toFixed(1)}%)`);
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@kognai/clawrouter-x402",
+  "version": "0.1.0",
+  "private": false,
+  "description": "ClawRouter v2 — Kognai's viem-backed x402 ModelRouter implementation. Injected into @kognai/orchestrator-core's router seam at startup, so core never depends on viem; products that don't route on-chain simply don't install this package.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "keywords": [
+    "kognai",
+    "clawrouter",
+    "x402",
+    "model-router",
+    "viem",
+    "base"
+  ],
+  "license": "UNLICENSED",
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "viem": "^2.47.0"
+  },
+  "peerDependencies": {
+    "@kognai/orchestrator-core": "*"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}