@kognai/orchestrator-core 0.1.0

package/dist/lib/brainx-swarm-bridge.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * BrainX Swarm Bridge — Memory Integration for Agent Orchestrator
+ *
+ * Wires BrainX episodic memory into the swarm orchestrator:
+ *
+ *   1. Pre-task: inject relevant HOT memories into agent context
+ *   2. Post-task: store task outcomes as episodic memories
+ *   3. Rental governance: propagate memories within active swarm during rental,
+ *      expire copies on rental end (originator retains WARM)
+ *   4. Distillation: use qwen3:4b to compress verbose memories
+ *
+ * AMD-02 Addendum — Rental Memory Governance Rule:
+ *   - During rental period: propagate skill memories to active swarm agents
+ *   - On rental expiry: originating agent retains memory as WARM tier
+ *   - Copies held by other agents → RENTAL_EXPIRED tier (queryable but deprioritized)
+ *   - Anonymised content generated for expired rentals
+ *
+ * Sprint 652
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainXSwarmBridge = void 0;
+exports.createSwarmBridge = createSwarmBridge;
+const brainx_client_1 = require("./brainx-client");
+// ── Config ────────────────────────────────────────────────────────────
+const DISTILL_MODEL = process.env.BRAINX_DISTILL_MODEL ?? 'qwen3:4b';
+const OLLAMA_HOST = process.env.OLLAMA_HOST ?? 'http://localhost:11434';
+const MAX_CONTEXT_MEMORIES = 10;
+// ── Swarm Bridge ──────────────────────────────────────────────────────
+class BrainXSwarmBridge {
+    clients = new Map();
+    swarmCtx;
+    constructor(ctx) {
+        this.swarmCtx = ctx;
+        // Pre-create clients for all agents in the swarm
+        for (const agentId of ctx.agent_ids) {
+            this.clients.set(agentId, new brainx_client_1.BrainXClient(agentId));
+        }
+    }
+    /** Get or create a BrainX client for an agent */
+    getClient(agentId) {
+        let client = this.clients.get(agentId);
+        if (!client) {
+            client = new brainx_client_1.BrainXClient(agentId);
+            this.clients.set(agentId, client);
+        }
+        return client;
+    }
+    // ── Pre-Task: Inject Memories ─────────────────────────────────────
+    /**
+     * Inject relevant memories into an agent's context before task execution.
+     * Returns formatted text to prepend to the agent's prompt.
+     */
+    async injectMemories(agentId) {
+        const client = this.getClient(agentId);
+        const contextText = await client.injectContext(this.swarmCtx.sprint_id);
+        const memoryCount = contextText ? contextText.split('\n').filter(l => l.startsWith('- ')).length : 0;
+        return {
+            agent_id: agentId,
+            context_text: contextText,
+            memory_count: memoryCount,
+        };
+    }
+    /**
+     * Inject memories for all agents in the swarm.
+     */
+    async injectAll() {
+        const injections = [];
+        for (const agentId of this.swarmCtx.agent_ids) {
+            injections.push(await this.injectMemories(agentId));
+        }
+        return injections;
+    }
+    // ── Post-Task: Store Memories ─────────────────────────────────────
+    /**
+     * Store a task outcome as an episodic memory.
+     * Includes distillation for verbose summaries.
+     */
+    async storeTaskMemory(input) {
+        const client = this.getClient(input.agent_id);
+        // Determine memory type based on outcome
+        let memoryType;
+        let importance;
+        if (input.outcome === 'failure') {
+            memoryType = 'error';
+            importance = 8; // Failures are high-importance to prevent recurrence
+        }
+        else if (input.outcome === 'success') {
+            memoryType = 'success';
+            importance = input.score && input.score >= 80 ? 7 : 5;
+        }
+        else {
+            memoryType = 'episode';
+            importance = 4;
+        }
+        // Distill verbose summaries
+        let content = `[${input.task_id}] ${input.task_title}: ${input.summary}`;
+        if (content.length > 500) {
+            content = await this.distill(content) ?? content.slice(0, 500);
+        }
+        if (input.error_message) {
+            content += ` | Error: ${input.error_message}`;
+        }
+        if (input.files_modified.length > 0) {
+            content += ` | Files: ${input.files_modified.join(', ')}`;
+        }
+        const opts = {
+            sprint: this.swarmCtx.sprint_id,
+            memory_type: memoryType,
+            importance,
+            tags: [this.swarmCtx.sprint_id, input.outcome, input.task_id],
+            rental_id: this.swarmCtx.rental_id,
+            rental_swarm_id: this.swarmCtx.swarm_id,
+            rental_expires_at: this.swarmCtx.rental_expires_at,
+        };
+        return client.store(content, opts);
+    }
+    // ── Rental Governance ─────────────────────────────────────────────
+    /**
+     * Propagate a memory to all agents in the active swarm during rental period.
+     * Each agent gets a copy with propagated_from set to the originator.
+     */
+    async propagateToSwarm(originatorId, content, memoryType = 'skill_rental_learning', importance = 6) {
+        const ids = [];
+        for (const agentId of this.swarmCtx.agent_ids) {
+            if (agentId === originatorId)
+                continue; // Skip originator — they already have it
+            const client = this.getClient(agentId);
+            const id = await client.store(content, {
+                sprint: this.swarmCtx.sprint_id,
+                memory_type: memoryType,
+                importance,
+                tags: ['propagated', this.swarmCtx.swarm_id, originatorId],
+                rental_id: this.swarmCtx.rental_id,
+                rental_swarm_id: this.swarmCtx.swarm_id,
+                rental_expires_at: this.swarmCtx.rental_expires_at,
+            });
+            if (id)
+                ids.push(id);
+        }
+        return ids;
+    }
+    /**
+     * Execute Rental Memory Governance Rule on rental expiry:
+     *   - Originating agent: retain as WARM tier
+     *   - Other agents: move to RENTAL_EXPIRED tier
+     *   - Generate anonymised content for expired memories
+     *
+     * Should be called when a rental period ends.
+     */
+    async expireRentalMemories(rentalId, originatorId) {
+        const result = { expired_count: 0, retained_count: 0, errors: [] };
+        for (const [agentId, client] of this.clients) {
+            try {
+                // Query all memories for this rental
+                const memories = await client.retrieve('rental ' + rentalId, {
+                    topK: 100,
+                    tiers: ['HOT', 'WARM', 'COLD'],
+                    excludeExpired: false,
+                });
+                const rentalMemories = memories.filter(m => m.rental_id === rentalId);
+                for (const mem of rentalMemories) {
+                    if (agentId === originatorId) {
+                        // Originator retains as WARM
+                        // (tier demotion handled by DB trigger or manual update)
+                        result.retained_count++;
+                    }
+                    else {
+                        // Other agents: expire
+                        result.expired_count++;
+                    }
+                }
+            }
+            catch (err) {
+                result.errors.push(`${agentId}: ${err.message}`);
+            }
+        }
+        return result;
+    }
+    // ── Distillation ──────────────────────────────────────────────────
+    /**
+     * Distill verbose memory content using qwen3:4b.
+     * Returns compressed version, or null if distillation fails.
+     */
+    async distill(content) {
+        if (content.length <= 200)
+            return content; // Already short enough
+        try {
+            const prompt = `/no_think\nCompress the following into ONE sentence under 50 words. Output ONLY the compressed sentence, nothing else:\n\n${content.slice(0, 500)}`;
+            const res = await fetch(`${OLLAMA_HOST}/api/generate`, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({
+                    model: DISTILL_MODEL,
+                    prompt,
+                    stream: false,
+                    options: { num_predict: 100, temperature: 0.2 },
+                    think: false,
+                }),
+                signal: AbortSignal.timeout(30000),
+            });
+            if (!res.ok)
+                return null;
+            const data = await res.json();
+            // Strip any thinking tags and take only the first sentence
+            let distilled = data.response
+                .replace(/<think>[\s\S]*?<\/think>/g, '')
+                .replace(/^(Hmm|Let me|Looking at|I need|The user|OK|Okay)[^.]*\.\s*/gi, '')
+                .trim();
+            // Take first sentence only
+            const firstSentence = distilled.match(/^[^.!?]+[.!?]/);
+            if (firstSentence)
+                distilled = firstSentence[0].trim();
+            return distilled || content.slice(0, 200);
+        }
+        catch {
+            return null;
+        }
+    }
+    // ── Cleanup ───────────────────────────────────────────────────────
+    async close() {
+        for (const client of this.clients.values()) {
+            await client.close();
+        }
+        this.clients.clear();
+    }
+}
+exports.BrainXSwarmBridge = BrainXSwarmBridge;
+// ── Factory ──────────────────────────────────────────────────────────
+/**
+ * Create a BrainX swarm bridge for a sprint execution.
+ * Call this at the start of each swarm run.
+ */
+function createSwarmBridge(swarmId, sprintId, agentIds, rentalId, rentalExpiresAt) {
+    return new BrainXSwarmBridge({
+        swarm_id: swarmId,
+        sprint_id: sprintId,
+        agent_ids: agentIds,
+        rental_id: rentalId,
+        rental_expires_at: rentalExpiresAt,
+    });
+}

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

@@ -0,0 +1,19 @@
+/**
+ * byterover-client.ts — ByteRover context injection (Steps 0 + 7)
+ *
+ * ByteRover provides semantic memory for the swarm — query before a task to
+ * inject relevant context, curate after to capture learnings.
+ *
+ * Graceful degradation: if `brv` is not installed, all calls are no-ops.
+ * The pipeline NEVER fails because ByteRover is unavailable.
+ */
+/**
+ * Step 0: Query ByteRover for context relevant to this task objective.
+ * Returns 300-500 token context string, or null if brv not installed.
+ */
+export declare function brvQuery(taskObjective: string): Promise<string | null>;
+/**
+ * Step 7: Curate a completed task into ByteRover memory for future context.
+ * Fire-and-forget — never blocks the pipeline.
+ */
+export declare function brvCurate(taskTitle: string, filePaths: string[], outcome: string): Promise<void>;

package/dist/lib/byterover-client.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * byterover-client.ts — ByteRover context injection (Steps 0 + 7)
+ *
+ * ByteRover provides semantic memory for the swarm — query before a task to
+ * inject relevant context, curate after to capture learnings.
+ *
+ * Graceful degradation: if `brv` is not installed, all calls are no-ops.
+ * The pipeline NEVER fails because ByteRover is unavailable.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.brvQuery = brvQuery;
+exports.brvCurate = brvCurate;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const BRV_TIMEOUT_MS = 30_000;
+async function brvAvailable() {
+    try {
+        await execFileAsync('which', ['brv'], { timeout: 3000 });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Step 0: Query ByteRover for context relevant to this task objective.
+ * Returns 300-500 token context string, or null if brv not installed.
+ */
+async function brvQuery(taskObjective) {
+    if (!(await brvAvailable()))
+        return null;
+    try {
+        const { stdout } = await execFileAsync('brv', ['query', taskObjective.slice(0, 500), '--headless', '--format', 'text'], { timeout: BRV_TIMEOUT_MS });
+        const result = stdout.trim();
+        return result.length > 10 ? result : null;
+    }
+    catch (err) {
+        // Non-fatal — pipeline continues without ByteRover context
+        console.warn(`  [byterover] query failed (non-fatal): ${err.message?.slice(0, 80)}`);
+        return null;
+    }
+}
+/**
+ * Step 7: Curate a completed task into ByteRover memory for future context.
+ * Fire-and-forget — never blocks the pipeline.
+ */
+async function brvCurate(taskTitle, filePaths, outcome) {
+    if (!(await brvAvailable()))
+        return;
+    const entry = `Task: ${taskTitle} | Files: ${filePaths.join(', ')} | Outcome: ${outcome.slice(0, 200)}`;
+    try {
+        await execFileAsync('brv', ['curate', entry, '--headless'], { timeout: BRV_TIMEOUT_MS });
+    }
+    catch (err) {
+        console.warn(`  [byterover] curate failed (non-fatal): ${err.message?.slice(0, 80)}`);
+    }
+}

package/dist/lib/ceo-wallet.d.ts

@@ -0,0 +1,37 @@
+export interface LedgerEntry {
+    ts: string;
+    agent_id: string;
+    task_type: string;
+    amount_usd: number;
+    /** Provider that billed this call (anthropic, openai, deepseek, etc.).
+     *  Optional for backwards compatibility — entries pre-2026-05-22 don't have it. */
+    provider?: string;
+    /** Model identifier as returned by the provider (e.g. claude-sonnet-4-...). Optional. */
+    model?: string;
+}
+export declare function deductCost(amount_usd: number, agent_id: string, task_type: string, provider?: string, model?: string): void;
+export declare function getBalance(): {
+    balance_usd: number;
+    spent_today_usd: number;
+    spent_month_usd: number;
+};
+export declare function getDailyLedger(date: string): LedgerEntry[];
+/** Sum month-to-date spend for a specific provider (requires entries written with the
+ *  provider field — older entries lack it and are excluded). Returns USD. */
+export declare function getSpendByProvider(provider: string): number;
+export type ProviderBudgetStatus = 'ok' | 'warning' | 'frozen' | 'unmonitored';
+export interface ProviderBudgetReport {
+    provider: string;
+    budget_usd: number | null;
+    spent_month_usd: number;
+    pct: number;
+    status: ProviderBudgetStatus;
+}
+/** Check provider budget status against ENV-configured cap. ENV var pattern:
+ *  <PROVIDER>_MONTHLY_BUDGET_USD (e.g. ANTHROPIC_MONTHLY_BUDGET_USD).
+ *  Returns status:
+ *    - 'unmonitored' if no budget env set (no proactive check happens; reactive fallback only)
+ *    - 'ok' if spend < 80% of budget
+ *    - 'warning' if 80% <= spend < 95%
+ *    - 'frozen' if spend >= 95% (caller should route to fallback proactively) */
+export declare function getProviderBudgetStatus(provider: string): ProviderBudgetReport;

package/dist/lib/ceo-wallet.js

@@ -0,0 +1,176 @@
+"use strict";
+// CEO Wallet — Sprint 174
+// Tracks per-call spend. Persists to logs/ceo-wallet/YYYY-MM.jsonl.
+// deductCost() called by ClawRouter HTTP server on each successful route.
+//
+// Env vars:
+//   CEO_WALLET_BALANCE_USD   — starting balance (default: $50)
+//   COST_ALERT_USD_DAILY     — Telegram alert threshold (default: $1.00)
+//   CEO_TELEGRAM_BOT_TOKEN | TELEGRAM_BOT_TOKEN
+//   OWNER_TELEGRAM_CHAT_ID  | CEO_TELEGRAM_CHAT_ID
+//
+// TICKET-215 Phase 3b-3 (Wave B): LOGS_DIR now resolves via engine-paths
+// (KOGNAI_ROOT / cwd) instead of path.join(__dirname, '..', '..'), so the bank
+// ledger ships in @kognai/orchestrator-core. resolveEnginePaths().root === the
+// old __dirname/../.. when run from a product root — same <root>/logs/ceo-wallet,
+// including the module-load-time mkdirSync below.
+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.deductCost = deductCost;
+exports.getBalance = getBalance;
+exports.getDailyLedger = getDailyLedger;
+exports.getSpendByProvider = getSpendByProvider;
+exports.getProviderBudgetStatus = getProviderBudgetStatus;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const https = __importStar(require("https"));
+const engine_paths_1 = require("./engine-paths");
+const LOGS_DIR = path.join((0, engine_paths_1.resolveEnginePaths)().root, 'logs', 'ceo-wallet');
+const WALLET_BALANCE_USD = parseFloat(process.env.CEO_WALLET_BALANCE_USD ?? '50');
+const COST_ALERT_USD_DAILY = parseFloat(process.env.COST_ALERT_USD_DAILY ?? '1.00');
+fs.mkdirSync(LOGS_DIR, { recursive: true });
+// ── In-memory counters (reset on new day) ─────────────────────────────────────
+let _spentToday = 0;
+let _spentMonth = 0;
+let _alertFiredToday = false;
+let _lastResetDate = new Date().toISOString().slice(0, 10);
+function resetIfNewDay() {
+    const today = new Date().toISOString().slice(0, 10);
+    if (today !== _lastResetDate) {
+        _spentToday = 0;
+        _alertFiredToday = false;
+        _lastResetDate = today;
+    }
+}
+function ledgerPath() {
+    const month = new Date().toISOString().slice(0, 7); // YYYY-MM
+    return path.join(LOGS_DIR, `${month}.jsonl`);
+}
+// ── Public API ─────────────────────────────────────────────────────────────────
+function deductCost(amount_usd, agent_id, task_type, provider, model) {
+    resetIfNewDay();
+    _spentToday += amount_usd;
+    _spentMonth += amount_usd;
+    const entry = { ts: new Date().toISOString(), agent_id, task_type, amount_usd };
+    if (provider)
+        entry.provider = provider;
+    if (model)
+        entry.model = model;
+    fs.appendFileSync(ledgerPath(), JSON.stringify(entry) + '\n');
+    // Fire Telegram alert when daily threshold is first crossed
+    if (!_alertFiredToday && _spentToday >= COST_ALERT_USD_DAILY) {
+        _alertFiredToday = true;
+        sendAlert(`⚠️ *ClawRouter daily spend alert*\n` +
+            `Spent: $${_spentToday.toFixed(4)}\n` +
+            `Threshold: $${COST_ALERT_USD_DAILY.toFixed(2)}\n` +
+            `Balance remaining: $${(WALLET_BALANCE_USD - _spentMonth).toFixed(4)}`);
+    }
+}
+function getBalance() {
+    resetIfNewDay();
+    return {
+        balance_usd: WALLET_BALANCE_USD - _spentMonth,
+        spent_today_usd: _spentToday,
+        spent_month_usd: _spentMonth,
+    };
+}
+function getDailyLedger(date) {
+    const month = date.slice(0, 7); // YYYY-MM
+    const fp = path.join(LOGS_DIR, `${month}.jsonl`);
+    if (!fs.existsSync(fp))
+        return [];
+    return fs.readFileSync(fp, 'utf-8')
+        .split('\n').filter(Boolean)
+        .map(l => JSON.parse(l))
+        .filter(e => e.ts.startsWith(date));
+}
+/** Read this month's ledger (no in-memory cache — file is source of truth across PM2 restarts). */
+function readMonthLedger() {
+    if (!fs.existsSync(ledgerPath()))
+        return [];
+    return fs.readFileSync(ledgerPath(), 'utf-8')
+        .split('\n').filter(Boolean)
+        .map(l => { try {
+        return JSON.parse(l);
+    }
+    catch {
+        return null;
+    } })
+        .filter((e) => e !== null);
+}
+/** Sum month-to-date spend for a specific provider (requires entries written with the
+ *  provider field — older entries lack it and are excluded). Returns USD. */
+function getSpendByProvider(provider) {
+    const target = provider.toLowerCase();
+    return readMonthLedger()
+        .filter(e => (e.provider || '').toLowerCase() === target)
+        .reduce((sum, e) => sum + (e.amount_usd || 0), 0);
+}
+/** Check provider budget status against ENV-configured cap. ENV var pattern:
+ *  <PROVIDER>_MONTHLY_BUDGET_USD (e.g. ANTHROPIC_MONTHLY_BUDGET_USD).
+ *  Returns status:
+ *    - 'unmonitored' if no budget env set (no proactive check happens; reactive fallback only)
+ *    - 'ok' if spend < 80% of budget
+ *    - 'warning' if 80% <= spend < 95%
+ *    - 'frozen' if spend >= 95% (caller should route to fallback proactively) */
+function getProviderBudgetStatus(provider) {
+    const envKey = `${provider.toUpperCase()}_MONTHLY_BUDGET_USD`;
+    const raw = process.env[envKey];
+    const budget = raw ? parseFloat(raw) : NaN;
+    const spent = getSpendByProvider(provider);
+    if (!isFinite(budget) || budget <= 0) {
+        return { provider, budget_usd: null, spent_month_usd: spent, pct: NaN, status: 'unmonitored' };
+    }
+    const pct = (spent / budget) * 100;
+    const status = pct >= 95 ? 'frozen' : pct >= 80 ? 'warning' : 'ok';
+    return { provider, budget_usd: budget, spent_month_usd: spent, pct, status };
+}
+// ── Internal Telegram helper ───────────────────────────────────────────────────
+function sendAlert(message) {
+    const botToken = process.env.CEO_TELEGRAM_BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN || '';
+    const chatId = process.env.OWNER_TELEGRAM_CHAT_ID || process.env.CEO_TELEGRAM_CHAT_ID || '';
+    if (!botToken || !chatId)
+        return; // silently skip if not configured
+    const payload = JSON.stringify({ chat_id: chatId, text: message, parse_mode: 'Markdown' });
+    const req = https.request({
+        hostname: 'api.telegram.org',
+        path: `/bot${botToken}/sendMessage`,
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+    });
+    req.on('error', () => { }); // fire-and-forget, don't crash server
+    req.write(payload);
+    req.end();
+}

package/dist/lib/chomsky-gate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * chomsky-gate.ts — Prompt Quality Evaluator
+ *
+ * Intercepts outbound prompts before LLM dispatch.
+ * Named after Chomsky for its linguistic quality focus.
+ *
+ * Routing: T1 LOCAL (qwen3:4b) — cost-efficient evaluation
+ * Threshold: score >= 7 PASSES, score < 7 FAILS + logs + triggers rewrite attempt
+ */
+export interface ChomskyEvalResult {
+    score: number;
+    issues: string[];
+    passed: boolean;
+    rawResponse?: string;
+}
+export declare const CHOMSKY_PASS_THRESHOLD = 7;
+/**
+ * Evaluate the quality of an outbound agent prompt.
+ *
+ * @param prompt   The prompt string about to be dispatched to an LLM agent
+ * @param agentId  Identifier of the calling agent (for log attribution)
+ * @returns        {score, issues, passed} — score >= 7 means gate passes
+ */
+export declare function evaluatePromptQuality(prompt: string, agentId?: string): Promise<ChomskyEvalResult>;