akemon 0.2.24 → 0.2.26

package/dist/context.js

@@ -41,12 +41,14 @@ function parseConversation(content) {
     if (recentMatch) {
         const lines = recentMatch[1].split("\n");
         for (const line of lines) {
-            const m = line.match(/^\[(.+?)\] (User|Agent): (.*)$/);
+            // Format: [ts] [kind] Role: text  OR (legacy)  [ts] Role: text
+            const m = line.match(/^\[(.+?)\] (?:\[(order)\] )?(User|Agent): (.*)$/);
             if (m) {
                 rounds.push({
                     ts: m[1],
-                    role: m[2].toLowerCase(),
-                    content: m[3],
+                    kind: m[2] ?? "chat",
+                    role: m[3].toLowerCase(),
+                    content: m[4],
                 });
             }
             else if (rounds.length > 0 && line !== "") {
@@ -67,8 +69,10 @@ export async function loadConversation(workdir, agentName, convId) {
         return { summary: "", rounds: [] };
     }
 }
-/** Append a single message to a conversation file. Creates file if needed. */
-export async function appendMessage(workdir, agentName, convId, role, message) {
+/** Append a single message to a conversation file. Creates file if needed.
+ *  kind="order" writes an explicit [order] tag so the UI can filter/style it.
+ *  kind="chat" (default) omits the tag for backward-compatibility with old files. */
+export async function appendMessage(workdir, agentName, convId, role, message, kind = "chat") {
     const dir = conversationsDir(workdir, agentName);
     await mkdir(dir, { recursive: true });
     const p = conversationPath(workdir, agentName, convId);
@@ -81,7 +85,8 @@ export async function appendMessage(workdir, agentName, convId, role, message) {
         content = "## Summary\n\n\n## Recent\n";
     }
     const ts = localNow();
-    content = content.trimEnd() + "\n" + `[${ts}] ${role}: ${message}` + "\n";
+    const kindTag = kind === "order" ? "[order] " : "";
+    content = content.trimEnd() + "\n" + `[${ts}] ${kindTag}${role}: ${message}` + "\n";
     await writeFile(p, content);
 }
 /** Append a user+agent round to a conversation file. Creates file if needed. */

package/dist/context.test.js

@@ -0,0 +1,90 @@
+import assert from "node:assert/strict";
+import { describe, it, before, after } from "node:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+// We import the functions we need to test. appendMessage and loadConversation
+// need a workdir on disk; parseConversation is internal — tested via loadConversation.
+import { appendMessage, loadConversation } from "./context.js";
+const agentName = "test-agent";
+// ---------------------------------------------------------------------------
+// appendMessage + loadConversation round-trip
+// ---------------------------------------------------------------------------
+describe("appendMessage / loadConversation", () => {
+    let workdir = "";
+    before(async () => {
+        workdir = await mkdtemp(join(tmpdir(), "ctx-test-"));
+    });
+    after(async () => {
+        await rm(workdir, { recursive: true, force: true });
+    });
+    it("writes a chat message and reads it back with kind='chat'", async () => {
+        const convId = "test-chat";
+        await appendMessage(workdir, agentName, convId, "User", "hello", "chat");
+        const conv = await loadConversation(workdir, agentName, convId);
+        assert.equal(conv.rounds.length, 1);
+        assert.equal(conv.rounds[0].role, "user");
+        assert.equal(conv.rounds[0].content, "hello");
+        assert.equal(conv.rounds[0].kind, "chat");
+    });
+    it("writes an order message with [order] tag and reads kind='order'", async () => {
+        const convId = "test-order";
+        await appendMessage(workdir, agentName, convId, "User", "order request", "order");
+        await appendMessage(workdir, agentName, convId, "Agent", "order delivered", "order");
+        const conv = await loadConversation(workdir, agentName, convId);
+        assert.equal(conv.rounds.length, 2);
+        assert.equal(conv.rounds[0].kind, "order");
+        assert.equal(conv.rounds[0].role, "user");
+        assert.equal(conv.rounds[1].kind, "order");
+        assert.equal(conv.rounds[1].role, "agent");
+    });
+    it("defaults to kind='chat' when kind arg is omitted", async () => {
+        const convId = "test-default-kind";
+        await appendMessage(workdir, agentName, convId, "Agent", "hi there");
+        const conv = await loadConversation(workdir, agentName, convId);
+        assert.equal(conv.rounds[0].kind, "chat");
+    });
+    it("parses mixed chat + order rounds correctly", async () => {
+        const convId = "test-mixed";
+        await appendMessage(workdir, agentName, convId, "User", "chat message", "chat");
+        await appendMessage(workdir, agentName, convId, "User", "order task", "order");
+        await appendMessage(workdir, agentName, convId, "Agent", "chat reply", "chat");
+        await appendMessage(workdir, agentName, convId, "Agent", "order result", "order");
+        const conv = await loadConversation(workdir, agentName, convId);
+        assert.equal(conv.rounds.length, 4);
+        assert.equal(conv.rounds[0].kind, "chat");
+        assert.equal(conv.rounds[1].kind, "order");
+        assert.equal(conv.rounds[2].kind, "chat");
+        assert.equal(conv.rounds[3].kind, "order");
+    });
+    it("parses legacy file (no [kind] tag) as kind='chat' for backward-compat", async () => {
+        const convId = "test-legacy";
+        // Write a legacy-style file manually (no [order] tag)
+        const { mkdir, writeFile } = await import("node:fs/promises");
+        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
+        await mkdir(dir, { recursive: true });
+        const legacyContent = "## Summary\n\n\n## Recent\n[2026-04-23 10:00] User: old message\n[2026-04-23 10:01] Agent: old reply\n";
+        await writeFile(join(dir, `${convId}.md`), legacyContent);
+        const conv = await loadConversation(workdir, agentName, convId);
+        assert.equal(conv.rounds.length, 2);
+        assert.equal(conv.rounds[0].kind, "chat");
+        assert.equal(conv.rounds[1].kind, "chat");
+    });
+    it("[order] tag appears in the raw file content", async () => {
+        const convId = "test-tag-on-disk";
+        await appendMessage(workdir, agentName, convId, "User", "buy something", "order");
+        const { readFile: rf } = await import("node:fs/promises");
+        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
+        const raw = await rf(join(dir, `${convId}.md`), "utf-8");
+        assert.ok(raw.includes("[order] User: buy something"), `raw file should contain [order] tag: ${raw}`);
+    });
+    it("chat message does NOT have [order] tag in raw file", async () => {
+        const convId = "test-no-tag-on-disk";
+        await appendMessage(workdir, agentName, convId, "User", "just chatting", "chat");
+        const { readFile: rf } = await import("node:fs/promises");
+        const dir = join(workdir, ".akemon", "agents", agentName, "conversations");
+        const raw = await rf(join(dir, `${convId}.md`), "utf-8");
+        assert.ok(!raw.includes("[order]"), `chat line should NOT contain [order] tag: ${raw}`);
+        assert.ok(raw.includes("User: just chatting"));
+    });
+});

package/dist/engine-peripheral.js

@@ -13,6 +13,9 @@ import { readFile, writeFile, mkdir } from "fs/promises";
 import { join, dirname, isAbsolute } from "path";
 import { callAgent } from "./relay-client.js";
 import { SIG, sig } from "./types.js";
+import { updateMetrics, pushExecMs } from "./metrics.js";
+import { sendFailureEvent } from "./relay-client.js";
+import { resolveEngineConfig, } from "./engine-routing.js";
 export const LLM_ENGINES = new Set(["claude", "codex", "opencode", "gemini", "raw"]);
 // ---------------------------------------------------------------------------
 // EnginePeripheral
@@ -26,6 +29,27 @@ export class EnginePeripheral {
     bus = null;
     /** Last execution trace (for error reporting) */
     lastTrace = [];
+    /** Active CLI child processes — tracked so SIGTERM handler can kill them. */
+    activeChildren = new Set();
+    /**
+     * Send SIGKILL to all active child process groups. Called during daemon shutdown.
+     *
+     * NOTE: sends SIGKILL directly (no SIGTERM grace) — safe for stateless
+     * request/response CLIs. Must change to SIGTERM+3s+SIGKILL when Batch 5.1
+     * persistent-session mode lands (sessions need graceful teardown).
+     */
+    killAllChildren() {
+        for (const child of this.activeChildren) {
+            if (!child.pid)
+                continue;
+            console.log(`[engine] shutdown: killing pgid=-${child.pid}`);
+            try {
+                process.kill(-child.pid, "SIGKILL");
+            }
+            catch { }
+        }
+        this.activeChildren.clear();
+    }
     constructor(config) {
         this.config = config;
         this.id = `engine:${config.engine}`;
@@ -69,22 +93,32 @@ export class EnginePeripheral {
     // ---------------------------------------------------------------------------
     // Unified engine runner
     // ---------------------------------------------------------------------------
-    async runEngine(task, allowAll, extraAllowedTools, signal) {
-        const { engine, model, workdir } = this.config;
-        if (engine === "raw") {
-            return this.runRawEngine(task);
+    async runEngine(task, allowAll, extraAllowedTools, signal, origin, routing) {
+        const entry = resolveEngineConfig(routing, origin);
+        const cfg = entry ? applyRoutingEntry(this.config, entry) : this.config;
+        if (origin && entry) {
+            console.log(`[engine] using ${cfg.engine}${cfg.model ? `/${cfg.model}` : ""} (origin=${origin})`);
+        }
+        const t0 = Date.now();
+        try {
+            if (cfg.engine === "raw") {
+                return await this.runRawEngine(task, cfg);
+            }
+            const cmd = buildEngineCommand(cfg.engine, cfg.model, allowAll ?? cfg.allowAll, extraAllowedTools);
+            return await runCommand(cmd.cmd, cmd.args, task, cfg.workdir, cmd.stdinMode, signal, this.activeChildren);
+        }
+        finally {
+            pushExecMs(Date.now() - t0);
         }
-        const cmd = buildEngineCommand(engine, model, allowAll ?? this.config.allowAll, extraAllowedTools);
-        return runCommand(cmd.cmd, cmd.args, task, workdir, cmd.stdinMode, signal);
     }
     // ---------------------------------------------------------------------------
     // Raw engine: OpenAI-compatible API with tool call loop
     // ---------------------------------------------------------------------------
-    async runRawEngine(task) {
-        const apiUrl = (this.config.rawApiUrl || "http://localhost:11434/v1") + "/chat/completions";
-        const modelName = this.config.model || "gemma4:4b";
-        const maxRounds = this.config.rawMaxRounds || 20;
-        const apiKey = this.config.rawApiKey || "";
+    async runRawEngine(task, cfg = this.config) {
+        const apiUrl = (cfg.rawApiUrl || "http://localhost:11434/v1") + "/chat/completions";
+        const modelName = cfg.model || "gemma4:4b";
+        const maxRounds = cfg.rawMaxRounds || 20;
+        const apiKey = cfg.rawApiKey || "";
         console.log(`[raw] Task:\n${task}`);
         const trace = [];
         this.lastTrace = trace;
@@ -332,6 +366,28 @@ export const RAW_TOOLS = [
 // ---------------------------------------------------------------------------
 // CLI engine helpers (shared, non-class)
 // ---------------------------------------------------------------------------
+/**
+ * Build a local EngineConfig copy that merges in a routing entry's overrides.
+ * Resolves rawApiKeyEnv → rawApiKey from environment at call time.
+ * Never mutates the base config.
+ */
+function applyRoutingEntry(base, entry) {
+    const override = { engine: entry.engine };
+    if (entry.model !== undefined)
+        override.model = entry.model ?? undefined;
+    if (entry.rawApiUrl !== undefined)
+        override.rawApiUrl = entry.rawApiUrl;
+    if (entry.rawMaxRounds !== undefined)
+        override.rawMaxRounds = entry.rawMaxRounds;
+    if (entry.allowAll !== undefined)
+        override.allowAll = entry.allowAll;
+    // rawApiKeyEnv takes precedence over rawApiKey (env vars preferred for secrets)
+    if (entry.rawApiKeyEnv)
+        override.rawApiKey = process.env[entry.rawApiKeyEnv] ?? "";
+    else if (entry.rawApiKey !== undefined)
+        override.rawApiKey = entry.rawApiKey;
+    return { ...base, ...override };
+}
 function buildEngineCommand(engine, model, allowAll, extraAllowedTools) {
     switch (engine) {
         case "claude": {
@@ -364,7 +420,7 @@ function buildEngineCommand(engine, model, allowAll, extraAllowedTools) {
             return { cmd: engine, args: [], stdinMode: true };
     }
 }
-function runCommand(cmd, args, task, cwd, stdinMode = true, signal) {
+function runCommand(cmd, args, task, cwd, stdinMode = true, signal, activeChildren) {
     return new Promise((resolve, reject) => {
         const { CLAUDECODE, ...cleanEnv } = process.env;
         const finalArgs = stdinMode ? args : [...args, task];
@@ -373,23 +429,32 @@ function runCommand(cmd, args, task, cwd, stdinMode = true, signal) {
             cwd,
             env: cleanEnv,
             stdio: [stdinMode ? "pipe" : "ignore", "pipe", "pipe"],
+            detached: true, // child becomes process-group leader; enables pgid kill
         });
-        // Abort → SIGTERM, then SIGKILL after a grace period so a hung engine can't
-        // hold the slot past the caller's deadline.
+        if (activeChildren) {
+            activeChildren.add(child);
+            updateMetrics({ engine_children_active: activeChildren.size });
+        }
+        // Abort → SIGTERM to process group, then SIGKILL after grace period.
+        // Using -pid (negative) sends the signal to the entire process group,
+        // so any sub-forks spawned by the CLI are also terminated.
         let aborted = false;
         const onAbort = () => {
-            if (aborted)
+            if (aborted || !child.pid)
                 return;
             aborted = true;
-            console.log(`[${cmd}] aborted, killing pid=${child.pid}`);
+            console.log(`[${cmd}] aborted, killing pgid=-${child.pid}`);
+            sendFailureEvent("engine_abort", cmd, "engine subprocess aborted via signal");
             try {
-                child.kill("SIGTERM");
+                process.kill(-child.pid, "SIGTERM");
             }
             catch { }
-            setTimeout(() => { try {
-                child.kill("SIGKILL");
-            }
-            catch { } }, 3000).unref();
+            setTimeout(() => {
+                try {
+                    process.kill(-child.pid, "SIGKILL");
+                }
+                catch { }
+            }, 3000).unref();
         };
         if (signal) {
             if (signal.aborted)
@@ -412,6 +477,11 @@ function runCommand(cmd, args, task, cwd, stdinMode = true, signal) {
         });
         child.on("close", (code, killSignal) => {
             signal?.removeEventListener("abort", onAbort);
+            if (activeChildren) {
+                activeChildren.delete(child);
+                updateMetrics({ engine_children_active: activeChildren.size });
+            }
+            child.unref();
             console.log(`[${cmd}] exit=${code}${killSignal ? ` signal=${killSignal}` : ""} stdout=${stdout.length}b stderr=${stderr.length}b`);
             if (stderr)
                 console.log(`[${cmd}] stderr:\n${stderr}`);
@@ -431,6 +501,11 @@ function runCommand(cmd, args, task, cwd, stdinMode = true, signal) {
         });
         child.on("error", (err) => {
             signal?.removeEventListener("abort", onAbort);
+            if (activeChildren) {
+                activeChildren.delete(child);
+                updateMetrics({ engine_children_active: activeChildren.size });
+            }
+            child.unref();
             reject(err);
         });
     });

package/dist/engine-queue.js

@@ -19,11 +19,55 @@
  *   - low    — background enrichment (platform tasks, script activities,
  *              long-term, identity compression)
  */
+import { updateMetrics } from "./metrics.js";
 const PRIORITY_RANK = { high: 3, normal: 2, low: 1 };
+/** Max simultaneous user_manual tasks allowed to hold or wait for a slot.
+ *  Prevents more than this many claude CLI processes from queuing up. */
+const DEFAULT_MAX_USER_MANUAL = 2;
 export class EngineQueue {
     busy = false;
     busySince = 0;
     waiters = [];
+    // User-manual concurrency gate
+    maxUserManualSlots;
+    userManualActive = 0;
+    userManualQueue = [];
+    constructor(maxUserManualSlots = DEFAULT_MAX_USER_MANUAL) {
+        this.maxUserManualSlots = maxUserManualSlots;
+    }
+    /** Acquire a user_manual slot before joining the engine queue.
+     *  Callers MUST call releaseUserManualSlot() in a finally block. */
+    acquireUserManualSlot(deadlineMs) {
+        if (this.userManualActive < this.maxUserManualSlots) {
+            this.userManualActive++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve, reject) => {
+            let timerRef;
+            const entry = {
+                resolve: () => { clearTimeout(timerRef); resolve(); },
+                reject: (err) => { clearTimeout(timerRef); reject(err); },
+            };
+            timerRef = setTimeout(() => {
+                const idx = this.userManualQueue.indexOf(entry);
+                if (idx >= 0)
+                    this.userManualQueue.splice(idx, 1);
+                entry.reject(new Error("User manual slot timeout"));
+            }, deadlineMs);
+            this.userManualQueue.push(entry);
+        });
+    }
+    /** Release a user_manual slot and wake the next waiter. */
+    releaseUserManualSlot() {
+        const next = this.userManualQueue.shift();
+        if (next) {
+            // Transfer slot to the next waiter (active count unchanged)
+            next.resolve();
+        }
+        else {
+            this.userManualActive = Math.max(0, this.userManualActive - 1);
+        }
+    }
     /** Wait up to `deadlineMs` for the slot, then take it. */
     acquire(priority, deadlineMs) {
         if (!this.busy) {
@@ -39,12 +83,15 @@ export class EngineQueue {
                 reject,
                 timer: setTimeout(() => {
                     const idx = this.waiters.indexOf(waiter);
-                    if (idx >= 0)
+                    if (idx >= 0) {
                         this.waiters.splice(idx, 1);
+                        updateMetrics({ engine_queue_depth: this.waiters.length });
+                    }
                     reject(new Error(`Engine busy timeout (${Math.round(deadlineMs / 60000)} min)`));
                 }, deadlineMs),
             };
             this.waiters.push(waiter);
+            updateMetrics({ engine_queue_depth: this.waiters.length });
         });
     }
     /** Release the slot and hand it to the best waiter, if any. */
@@ -58,6 +105,7 @@ export class EngineQueue {
         this.waiters.splice(this.waiters.indexOf(next), 1);
         clearTimeout(next.timer);
         this.busySince = Date.now();
+        updateMetrics({ engine_queue_depth: this.waiters.length });
         next.resolve();
     }
     /** Take the slot synchronously (used by MCP fast-path when !isBusy). */

package/dist/engine-queue.test.js

@@ -0,0 +1,99 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { EngineQueue } from "./engine-queue.js";
+// Helpers
+const tick = () => new Promise((r) => setImmediate(r));
+async function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+describe("EngineQueue", () => {
+    it("free slot: acquire resolves immediately and isBusy becomes true", async () => {
+        const q = new EngineQueue();
+        assert.equal(q.isBusy(), false);
+        await q.acquire("high", 1000);
+        assert.equal(q.isBusy(), true);
+        q.release();
+        assert.equal(q.isBusy(), false);
+    });
+    it("tryAcquire: succeeds when free, returns false when busy", () => {
+        const q = new EngineQueue();
+        assert.equal(q.tryAcquire(), true);
+        assert.equal(q.isBusy(), true);
+        assert.equal(q.tryAcquire(), false);
+        q.release();
+    });
+    it("priority ordering: high waiter beats normal when slot is released", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000); // take the slot
+        const order = [];
+        const p1 = q.acquire("normal", 2000).then(() => { order.push("normal"); q.release(); });
+        await tick();
+        const p2 = q.acquire("high", 2000).then(() => { order.push("high"); q.release(); });
+        await tick();
+        assert.equal(q.queueDepth(), 2);
+        q.release(); // hand off to highest-priority waiter
+        await Promise.all([p1, p2]);
+        assert.deepEqual(order, ["high", "normal"]);
+    });
+    it("FIFO within same priority: earlier enqueuer wins", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000);
+        const order = [];
+        const p1 = q.acquire("normal", 2000).then(() => { order.push("first"); q.release(); });
+        await sleep(5); // ensure different enqueuedAt timestamps
+        const p2 = q.acquire("normal", 2000).then(() => { order.push("second"); q.release(); });
+        await tick();
+        q.release();
+        await Promise.all([p1, p2]);
+        assert.deepEqual(order, ["first", "second"]);
+    });
+    it("deadline timeout: waiter is removed and rejects with busy-timeout error", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000); // hold the slot
+        let caught = null;
+        const p = q.acquire("low", 30).catch((e) => { caught = e; });
+        await sleep(60); // let the 30ms deadline fire
+        assert.equal(q.queueDepth(), 0, "waiter must be removed after timeout");
+        await p;
+        assert.ok(caught !== null && typeof caught === "object", "should have rejected with an Error");
+        const msg = caught.message;
+        assert.ok(msg.includes("Engine busy timeout"), msg);
+        q.release();
+    });
+    it("release with no waiters makes slot free", () => {
+        const q = new EngineQueue();
+        assert.equal(q.tryAcquire(), true);
+        q.release();
+        assert.equal(q.isBusy(), false);
+        assert.equal(q.heldMs(), 0);
+    });
+    it("queueDepth tracks waiters correctly", async () => {
+        const q = new EngineQueue();
+        await q.acquire("high", 1000);
+        assert.equal(q.queueDepth(), 0);
+        const p1 = q.acquire("normal", 2000);
+        await tick();
+        assert.equal(q.queueDepth(), 1);
+        const p2 = q.acquire("low", 2000);
+        await tick();
+        assert.equal(q.queueDepth(), 2);
+        q.release(); // hand to normal (higher priority)
+        await tick();
+        assert.equal(q.queueDepth(), 1);
+        const holder = await p1; // p1 resolved — release it
+        void holder; // suppress unused warning
+        q.release();
+        await p2;
+        q.release();
+        assert.equal(q.queueDepth(), 0);
+    });
+    it("heldMs: returns 0 when free, positive when busy", async () => {
+        const q = new EngineQueue();
+        assert.equal(q.heldMs(), 0);
+        await q.acquire("high", 1000);
+        await sleep(10);
+        assert.ok(q.heldMs() >= 10, `heldMs should be >= 10, got ${q.heldMs()}`);
+        q.release();
+        assert.equal(q.heldMs(), 0);
+    });
+});

package/dist/engine-routing.js

@@ -0,0 +1,52 @@
+/**
+ * engine-routing.ts — pure helpers for origin-based engine selection.
+ *
+ * Three exported pure functions (each independently unit-tested):
+ *   resolveEngineConfig  — picks which engine/model to use for a given origin
+ *   deriveChildOrigin    — returns the origin a child/sub-task should carry
+ *   downgradeForRetry    — downgrades any origin to "retry" when a task retries
+ */
+/**
+ * Resolve which engine routing entry to use for a given origin.
+ *
+ * Lookup order:
+ *   1. routing[origin]   (exact match)
+ *   2. routing.default   (fallback)
+ *   3. null              (no routing configured → caller uses base engine config)
+ *
+ * Backward-compatible: if routing is undefined/null, returns null, meaning the
+ * caller should use whatever engine is already in the base EngineConfig.
+ */
+export function resolveEngineConfig(routing, origin) {
+    if (!routing)
+        return null;
+    if (origin) {
+        const exact = routing[origin];
+        if (exact)
+            return exact;
+    }
+    return routing.default ?? null;
+}
+/**
+ * Derive the origin that a child task should carry.
+ *
+ * "Human contamination" rule: human intent does NOT cross agent boundaries.
+ * Regardless of what the parent's origin is, any task spawned for/from another
+ * agent is always "platform" on the receiving side.
+ *
+ * Example: user_manual order → agent A calls agent B via MCP →
+ *          agent B's resulting order has origin "platform", not "user_manual".
+ */
+export function deriveChildOrigin(_parentOrigin) {
+    return "platform";
+}
+/**
+ * Downgrade the origin when a task enters the retry path.
+ *
+ * Retries must not consume the subscription CLI budget even if the original
+ * task was user_manual. Downgrading to "retry" lets the routing table send
+ * them to a cheaper API engine.
+ */
+export function downgradeForRetry(_origin) {
+    return "retry";
+}

package/dist/engine-routing.test.js

@@ -0,0 +1,122 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveEngineConfig, deriveChildOrigin, downgradeForRetry, } from "./engine-routing.js";
+// ---------------------------------------------------------------------------
+// resolveEngineConfig
+// ---------------------------------------------------------------------------
+describe("resolveEngineConfig", () => {
+    const claudeEntry = { engine: "claude", model: "claude-opus-4-5" };
+    const rawEntry = { engine: "raw", rawApiUrl: "https://api.deepseek.com/v1", model: "deepseek-chat", rawApiKeyEnv: "DEEPSEEK_API_KEY" };
+    const defaultEntry = { engine: "raw", rawApiUrl: "https://api.anthropic.com/v1", model: "claude-haiku-4-5", rawApiKeyEnv: "ANTHROPIC_API_KEY" };
+    it("returns exact origin entry when routing has that origin", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            platform: rawEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "user_manual");
+        assert.deepEqual(result, claudeEntry);
+    });
+    it("returns platform entry for platform origin", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            platform: rawEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "platform");
+        assert.deepEqual(result, rawEntry);
+    });
+    it("falls back to default when origin not in routing", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            default: defaultEntry,
+        };
+        // self_cycle not in routing → fallback to default
+        const result = resolveEngineConfig(routing, "self_cycle");
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("falls back to default when origin is undefined", () => {
+        const routing = { default: defaultEntry };
+        const result = resolveEngineConfig(routing, undefined);
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("returns null when routing is undefined (backward-compat: use base config)", () => {
+        const result = resolveEngineConfig(undefined, "user_manual");
+        assert.equal(result, null);
+    });
+    it("returns null when routing is null", () => {
+        const result = resolveEngineConfig(null, "user_manual");
+        assert.equal(result, null);
+    });
+    it("returns null when routing has no matching entry and no default", () => {
+        const routing = { user_manual: claudeEntry };
+        // self_cycle not in routing, no default
+        const result = resolveEngineConfig(routing, "self_cycle");
+        assert.equal(result, null);
+    });
+    it("returns null when routing is empty object and origin is undefined", () => {
+        const result = resolveEngineConfig({}, undefined);
+        assert.equal(result, null);
+    });
+    it("retry origin resolves to its own routing entry when configured", () => {
+        const retryEntry = { engine: "raw", rawApiUrl: "https://api.deepseek.com/v1", model: "deepseek-chat" };
+        const routing = {
+            user_manual: claudeEntry,
+            retry: retryEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "retry");
+        assert.deepEqual(result, retryEntry);
+    });
+    it("retry origin falls back to default when no retry entry configured", () => {
+        const routing = {
+            user_manual: claudeEntry,
+            default: defaultEntry,
+        };
+        const result = resolveEngineConfig(routing, "retry");
+        assert.deepEqual(result, defaultEntry);
+    });
+    it("reflection origin resolves correctly", () => {
+        const reflEntry = { engine: "raw", model: "gemma3:4b" };
+        const routing = { reflection: reflEntry, default: defaultEntry };
+        const result = resolveEngineConfig(routing, "reflection");
+        assert.deepEqual(result, reflEntry);
+    });
+});
+// ---------------------------------------------------------------------------
+// downgradeForRetry
+// ---------------------------------------------------------------------------
+describe("downgradeForRetry", () => {
+    const origins = ["user_manual", "self_cycle", "platform", "retry", "reflection"];
+    it("always returns 'retry' regardless of input", () => {
+        for (const origin of origins) {
+            assert.equal(downgradeForRetry(origin), "retry", `downgradeForRetry(${origin}) should be 'retry'`);
+        }
+    });
+    it("user_manual + isRetry=true → 'retry' (not user_manual)", () => {
+        // This is the spec's explicit test case for the downgrade rule
+        const original = "user_manual";
+        const downgraded = downgradeForRetry(original);
+        assert.equal(downgraded, "retry");
+        assert.notEqual(downgraded, "user_manual");
+    });
+});
+// ---------------------------------------------------------------------------
+// deriveChildOrigin
+// ---------------------------------------------------------------------------
+describe("deriveChildOrigin", () => {
+    const origins = ["user_manual", "self_cycle", "platform", "retry", "reflection"];
+    it("always returns 'platform' regardless of parent", () => {
+        for (const origin of origins) {
+            assert.equal(deriveChildOrigin(origin), "platform", `deriveChildOrigin(${origin}) should be 'platform'`);
+        }
+    });
+    it("user_manual parent does NOT propagate to child (anti-contamination rule)", () => {
+        const child = deriveChildOrigin("user_manual");
+        assert.equal(child, "platform");
+        assert.notEqual(child, "user_manual");
+    });
+    it("self_cycle parent → child is platform, not self_cycle", () => {
+        assert.equal(deriveChildOrigin("self_cycle"), "platform");
+    });
+});