@cohortapp/agent-sdk 2.3.0

package/lib/model-router/spawn.test.mjs

@@ -0,0 +1,425 @@
+/**
+ * lib/model-router/spawn.test.mjs — the router EXECUTION layer (session path).
+ *
+ * Drives spawnRouted over the REAL bundled catalog + a test policy, with an
+ * injected spawnImpl that returns SCRIPTED FailoverReasons (no real child
+ * process) and an in-memory breaker. Asserts the component-brief contract:
+ *   - picks the cheap candidate (first chain survivor);
+ *   - fails over on rate_limit to the next candidate AND opens a breaker;
+ *   - NEVER fails over on context_overflow;
+ *   - MAESTRO_ROUTER_FORCE_ANTHROPIC short-circuits to stock Anthropic;
+ *   - builds the correct argv (--model/--max-turns/--bare/--agents) and the
+ *     session-retarget child env (BASE_URL/AUTH_TOKEN/API_KEY="" for Kimi/DeepSeek),
+ *     with foreign credentials scrubbed (§7.3).
+ *
+ * House style: node:test, node:assert/strict, hermetic, no network.
+ */
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { spawnRouted, buildChildEnv, buildSpawnArgs, _internals } from "./spawn.mjs";
+import { loadCatalog, lookupModel } from "./catalog.mjs";
+import { DISPOSITION } from "./taxonomy.mjs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUNDLED_DIR = join(__dirname, "catalog");
+
+// ---------------------------------------------------------------------------
+// Hermetic harness
+// ---------------------------------------------------------------------------
+
+function fakeClock(start = 1_700_000_000_000) {
+  let t = start;
+  const now = () => t;
+  now.advance = (ms) => (t += ms);
+  return now;
+}
+
+function seededRng(seed = 0.42) {
+  let s = seed;
+  return () => {
+    s = (s * 9301 + 49297) % 233280;
+    return s / 233280;
+  };
+}
+
+function loadBundled(overrides = {}) {
+  const res = loadCatalog("/tmp/nope", { bundledDir: BUNDLED_DIR, ...overrides });
+  assert.ok(res.byRef.size > 0, "bundled catalog parsed");
+  return res;
+}
+
+/** In-memory breaker shaped the way failover.mjs drives (isOpen/open/close). */
+function memBreaker(now) {
+  const map = new Map();
+  const clock = typeof now === "function" ? now : () => now;
+  return {
+    map,
+    isOpen(key, at) {
+      const t = Number.isFinite(at) ? at : clock();
+      const s = map.get(key);
+      if (!s) return { open: false, until: 0, reason: null, strikes: 0 };
+      return { open: s.cooldownUntil > t, until: s.cooldownUntil, reason: s.reason, strikes: s.strikes };
+    },
+    open(key, reason, ms, at) {
+      const t = Number.isFinite(at) ? at : clock();
+      const prev = map.get(key) || { strikes: 0, cooldownUntil: 0 };
+      const strikes = prev.strikes + 1;
+      let cd = ms;
+      if (cd == null) {
+        const d = DISPOSITION[reason];
+        if (d && Array.isArray(d.stepped) && d.stepped.length) cd = d.stepped[Math.min(strikes - 1, d.stepped.length - 1)];
+        else if (d && d.cooldownMs === Infinity) cd = Infinity;
+        else cd = (d && d.cooldownMs) || 0;
+      }
+      const until = cd === Infinity ? Infinity : t + cd;
+      const next = { key, reason, strikes, cooldownUntil: Math.max(prev.cooldownUntil || 0, until), openedAt: t };
+      map.set(key, next);
+      return { ...next, cooldownUntil: next.cooldownUntil };
+    },
+    close(key) {
+      map.delete(key);
+    },
+  };
+}
+
+/**
+ * A v2 config whose cheap chain prefers a third-party session (Kimi) then falls
+ * back to the default Anthropic workhorse. public data_class so Kimi is gateable.
+ */
+function cheapSessionConfig() {
+  return {
+    schema_version: 2,
+    aliases: {
+      frontier: "anthropic/claude-opus-4-8",
+      default: "anthropic/claude-sonnet-4-6",
+      fast: "anthropic/claude-haiku-4-5",
+      cheapsession: "moonshot/kimi-k2.6",
+    },
+    defaults: { needs_tool_use_for_sessions: false, data_class: "public", cache_ttl: "1h" },
+    backends: {
+      anthropic: { allowed_data_classes: ["public", "internal", "sensitive"] },
+      moonshot: { allowed_data_classes: ["public"] },
+    },
+    routing_policy: [
+      { match: { task_class: "session.responder" }, harness: "session", chain: ["cheapsession", "default"], needs_tool_use: false },
+      { default: true, chain: ["default", "fast"] },
+    ],
+    fallback_to_anthropic: true,
+  };
+}
+
+const baseRequest = (over = {}) => ({
+  task_class: "session.responder",
+  source: "backlog",
+  data_class: "public",
+  priority: "normal",
+  ...over,
+});
+
+// ---------------------------------------------------------------------------
+// argv + env unit tests (pure)
+// ---------------------------------------------------------------------------
+
+test("buildSpawnArgs emits --print --bare --output-format json --model --max-turns", () => {
+  const args = buildSpawnArgs({ modelFlag: "claude-sonnet-4-6", maxTurns: 6, bare: true });
+  assert.deepEqual(args, [
+    "--print",
+    "--bare",
+    "--output-format",
+    "json",
+    "--model",
+    "claude-sonnet-4-6",
+    "--max-turns",
+    "6",
+  ]);
+});
+
+test("buildSpawnArgs includes --agents <json> and --effort when set; honors modelFlag override", () => {
+  const args = buildSpawnArgs(
+    { modelFlag: "claude-sonnet-4-6", maxTurns: 4, effort: "high", agentsJson: { explore: "haiku" }, bare: false },
+    { modelFlag: "kimi-k2.6" }
+  );
+  assert.ok(!args.includes("--bare"), "bare:false omits --bare");
+  assert.deepEqual(args.slice(args.indexOf("--model"), args.indexOf("--model") + 2), ["--model", "kimi-k2.6"]);
+  assert.ok(args.includes("--effort") && args[args.indexOf("--effort") + 1] === "high");
+  assert.ok(args.includes("--agents"));
+  assert.equal(args[args.indexOf("--agents") + 1], JSON.stringify({ explore: "haiku" }));
+});
+
+test("buildChildEnv scrubs all foreign credentials, injects only the retarget set (§7.3)", () => {
+  const base = {
+    PATH: "/usr/bin",
+    ANTHROPIC_API_KEY: "sk-anthropic-secret",
+    DEEPSEEK_API_KEY: "ds-secret",
+    OPENAI_API_KEY: "oai-secret",
+    SOME_AUTH_TOKEN: "tok",
+    HOME: "/home/x",
+  };
+  const retarget = {
+    ANTHROPIC_BASE_URL: "https://api.moonshot.ai/anthropic",
+    ANTHROPIC_AUTH_TOKEN: "moonshot-token",
+    ANTHROPIC_API_KEY: "",
+    ANTHROPIC_MODEL: "kimi-k2.6",
+  };
+  const env = buildChildEnv(base, retarget);
+  // Foreign credentials are gone.
+  assert.equal(env.DEEPSEEK_API_KEY, undefined);
+  assert.equal(env.OPENAI_API_KEY, undefined);
+  assert.equal(env.SOME_AUTH_TOKEN, undefined);
+  // Non-credential vars survive.
+  assert.equal(env.PATH, "/usr/bin");
+  assert.equal(env.HOME, "/home/x");
+  // The retarget set is injected verbatim, including empty-string API key.
+  assert.equal(env.ANTHROPIC_BASE_URL, "https://api.moonshot.ai/anthropic");
+  assert.equal(env.ANTHROPIC_AUTH_TOKEN, "moonshot-token");
+  assert.equal(env.ANTHROPIC_API_KEY, "");
+  assert.equal(env.ANTHROPIC_MODEL, "kimi-k2.6");
+});
+
+test("breakerKeysForRef splits provider + model", () => {
+  const k = _internals.breakerKeysForRef("moonshot/kimi-k2.6");
+  assert.equal(k.backendKey, "moonshot");
+  assert.equal(k.breakerKey, "moonshot:kimi-k2.6");
+});
+
+// ---------------------------------------------------------------------------
+// spawnRouted lanes
+// ---------------------------------------------------------------------------
+
+test("picks the cheap candidate (Kimi session) and builds the session-retarget env", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = { MOONSHOT_API_KEY: "moonshot-key", ANTHROPIC_API_KEY: "anthropic-key", DASHSCOPE_API_KEY: "x" };
+
+  let seenArgs = null;
+  let seenEnv = null;
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    rng: seededRng(),
+    breaker: memBreaker(now),
+    spawnImpl: (candidate, ctx) => {
+      seenArgs = ctx.args;
+      seenEnv = ctx.env;
+      return { ok: true, result: { ok: true } };
+    },
+  });
+
+  assert.equal(out.ok, true);
+  assert.equal(out.chosen.provider, "moonshot");
+  assert.equal(out.chosen.model, "kimi-k2.6");
+  // argv carries the cheap model flag + --bare + --output-format json.
+  assert.ok(seenArgs.includes("--model"));
+  assert.equal(seenArgs[seenArgs.indexOf("--model") + 1], "kimi-k2.6");
+  assert.ok(seenArgs.includes("--bare"));
+  assert.equal(seenArgs[seenArgs.indexOf("--output-format") + 1], "json");
+  // Session-retarget env present for Kimi: BASE_URL + AUTH_TOKEN + empty API key + MODEL.
+  assert.ok(/moonshot/i.test(seenEnv.ANTHROPIC_BASE_URL), "BASE_URL retargeted to moonshot");
+  assert.equal(seenEnv.ANTHROPIC_AUTH_TOKEN, "moonshot-key");
+  assert.equal(seenEnv.ANTHROPIC_API_KEY, "");
+  assert.equal(seenEnv.ANTHROPIC_MODEL, "kimi-k2.6");
+  // The anthropic key from the base env must NOT leak into the moonshot session.
+  assert.ok(seenEnv.ANTHROPIC_AUTH_TOKEN !== "anthropic-key");
+});
+
+test("fails over on rate_limit to the next candidate AND opens a backend:model breaker", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = { MOONSHOT_API_KEY: "moonshot-key", ANTHROPIC_API_KEY: "anthropic-key", DASHSCOPE_API_KEY: "x" };
+  const breaker = memBreaker(now);
+
+  const attempts = [];
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    rng: seededRng(),
+    breaker,
+    spawnImpl: (candidate) => {
+      attempts.push(candidate.ref);
+      if (candidate.ref === "moonshot/kimi-k2.6") return { ok: false, reason: "rate_limit" };
+      return { ok: true, result: { ok: true } };
+    },
+  });
+
+  assert.equal(out.ok, true, "second candidate succeeds");
+  assert.equal(out.chosen.provider, "anthropic", "failed over to anthropic default");
+  assert.deepEqual(attempts, ["moonshot/kimi-k2.6", "anthropic/claude-sonnet-4-6"]);
+  // The rate_limit disposition opens a backend:model breaker for kimi.
+  const kimi = breaker.isOpen("moonshot:kimi-k2.6", now());
+  assert.equal(kimi.open, true, "moonshot:kimi-k2.6 breaker opened");
+  assert.equal(kimi.reason, "rate_limit");
+  // tried[] records the rate_limit on the first candidate.
+  assert.equal(out.tried[0].ref, "moonshot/kimi-k2.6");
+  assert.equal(out.tried[0].reason, "rate_limit");
+});
+
+test("a subsequent spawn within cooldown SKIPS the open kimi breaker", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = { MOONSHOT_API_KEY: "moonshot-key", ANTHROPIC_API_KEY: "anthropic-key", DASHSCOPE_API_KEY: "x" };
+  const breaker = memBreaker(now);
+  // Pre-open the kimi breaker.
+  breaker.open("moonshot:kimi-k2.6", "rate_limit", null, now());
+
+  const attempts = [];
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    breaker,
+    spawnImpl: (candidate) => {
+      attempts.push(candidate.ref);
+      return { ok: true, result: { ok: true } };
+    },
+  });
+
+  assert.equal(out.ok, true);
+  // kimi was skipped (breaker open) — only anthropic was attempted.
+  assert.ok(!attempts.includes("moonshot/kimi-k2.6"), "open kimi breaker skipped");
+  assert.equal(out.chosen.provider, "anthropic");
+});
+
+test("NEVER fails over on context_overflow (terminates the walk)", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = { MOONSHOT_API_KEY: "moonshot-key", ANTHROPIC_API_KEY: "anthropic-key", DASHSCOPE_API_KEY: "x" };
+
+  const attempts = [];
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    breaker: memBreaker(now),
+    spawnImpl: (candidate) => {
+      attempts.push(candidate.ref);
+      return { ok: false, reason: "context_overflow" };
+    },
+  });
+
+  assert.equal(out.ok, false);
+  assert.equal(out.outcome.reason, "context_overflow");
+  // Only the first candidate was attempted; no failover to anthropic.
+  assert.deepEqual(attempts, ["moonshot/kimi-k2.6"]);
+});
+
+test("network never opens a breaker and never fails over (DEFER-style)", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = { MOONSHOT_API_KEY: "moonshot-key", ANTHROPIC_API_KEY: "anthropic-key", DASHSCOPE_API_KEY: "x" };
+  const breaker = memBreaker(now);
+
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    breaker,
+    spawnImpl: () => ({ ok: false, reason: "network" }),
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.outcome.reason, "network");
+  assert.equal(breaker.map.size, 0, "no breaker opened on network");
+});
+
+test("MAESTRO_ROUTER_FORCE_ANTHROPIC short-circuits to stock Anthropic (no retarget env)", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const env = {
+    MAESTRO_ROUTER_FORCE_ANTHROPIC: "1",
+    MOONSHOT_API_KEY: "moonshot-key",
+    ANTHROPIC_API_KEY: "anthropic-key",
+  };
+
+  let seenEnv = null;
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env,
+    now,
+    breaker: memBreaker(now),
+    spawnImpl: (candidate, ctx) => {
+      seenEnv = ctx.env;
+      return { ok: true, result: { ok: true } };
+    },
+  });
+
+  assert.equal(out.ok, true);
+  assert.equal(out.chosen.provider, "anthropic");
+  // No third-party retarget: stock Anthropic session has no ANTHROPIC_BASE_URL.
+  assert.equal(seenEnv.ANTHROPIC_BASE_URL, undefined);
+  // Foreign moonshot key is still scrubbed even on the anthropic path.
+  assert.equal(seenEnv.MOONSHOT_API_KEY, undefined);
+});
+
+test("no spawnImpl → surfaces no_spawn_impl, does not throw", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env: { MOONSHOT_API_KEY: "k", ANTHROPIC_API_KEY: "a" },
+    now,
+    breaker: memBreaker(now),
+  });
+  assert.equal(out.ok, false);
+  assert.equal(out.outcome.reason, "unknown");
+  assert.equal(out.tried[0].reason, "no_spawn_impl");
+});
+
+test("a spawnImpl that throws is caught and classified unknown (never propagates)", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const out = await spawnRouted(baseRequest(), {
+    config: cheapSessionConfig(),
+    catalog,
+    env: { MOONSHOT_API_KEY: "k", ANTHROPIC_API_KEY: "a", DASHSCOPE_API_KEY: "x" },
+    now,
+    breaker: memBreaker(now),
+    // throw once on kimi, succeed on anthropic (unknown fails over).
+    spawnImpl: (candidate) => {
+      if (candidate.ref === "moonshot/kimi-k2.6") throw new Error("boom");
+      return { ok: true, result: { ok: true } };
+    },
+  });
+  assert.equal(out.ok, true);
+  assert.equal(out.chosen.provider, "anthropic");
+  assert.ok(out.tried.some((t) => t.reason === "unknown"));
+});
+
+test("DeepSeek session retarget env is built when DeepSeek is the cheap candidate", async () => {
+  const now = fakeClock();
+  const catalog = loadBundled();
+  const config = cheapSessionConfig();
+  config.aliases.cheapsession = "deepseek/deepseek-v4-flash";
+  config.backends.deepseek = { allowed_data_classes: ["public"] };
+
+  let seenEnv = null;
+  const out = await spawnRouted(baseRequest(), {
+    config,
+    catalog,
+    env: { DEEPSEEK_API_KEY: "ds-key", ANTHROPIC_API_KEY: "a", MOONSHOT_API_KEY: "m" },
+    now,
+    breaker: memBreaker(now),
+    spawnImpl: (candidate, ctx) => {
+      seenEnv = ctx.env;
+      return { ok: true, result: { ok: true } };
+    },
+  });
+  assert.equal(out.ok, true);
+  assert.equal(out.chosen.provider, "deepseek");
+  assert.ok(/deepseek/i.test(seenEnv.ANTHROPIC_BASE_URL), "BASE_URL retargeted to deepseek");
+  assert.equal(seenEnv.ANTHROPIC_AUTH_TOKEN, "ds-key");
+  assert.equal(seenEnv.ANTHROPIC_API_KEY, "");
+  // Foreign keys scrubbed.
+  assert.equal(seenEnv.MOONSHOT_API_KEY, undefined);
+});