@desplega.ai/agent-swarm 1.121.0 → 1.122.0

package/src/providers/pi-mono-adapter.ts

@@ -28,6 +28,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { type TSchema, Type } from "typebox";
 import { classifyAwsSdkError } from "../utils/aws-error-classifier";
+import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { readPkgVersion } from "./harness-version";
 import { createSwarmHooksExtension } from "./pi-mono-extension";
@@ -356,6 +357,172 @@ export async function createPiRuntimeAuth(
   return modelRuntime;
 }
 
+/**
+ * Sidecar marker recording the gateway `baseUrl` WE wrote into models.json
+ * (and any user value we displaced). Lets `ensureOpenRouterModelsOverride`
+ * revert precisely when the env returns to default, without ever touching a
+ * hand-authored override it didn't create. Lives next to models.json; NOT
+ * part of pi's config surface.
+ */
+const OPENROUTER_OVERRIDE_MARKER = ".agent-swarm-openrouter-override.json";
+
+interface OpenRouterOverrideMarker {
+  baseUrl: string;
+  /** User-authored baseUrl we displaced, restored on revert. */
+  previous?: string;
+}
+
+async function readJsonFile(path: string): Promise<Record<string, unknown> | undefined> {
+  try {
+    const file = Bun.file(path);
+    if (!(await file.exists())) return undefined;
+    const parsed: unknown = JSON.parse(await file.text());
+    return typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Materialize (or revert) the OpenRouter gateway override in
+ * `<agentDir>/models.json` so pi-coding-agent's `ModelRuntime` (which loads
+ * that file at create time) composes every built-in OpenRouter model with
+ * the gateway `baseUrl` — see `src/utils/openrouter-base-url.ts` for the
+ * env contract.
+ *
+ * Gateway set (non-default): merge-preserving write — existing provider
+ * entries and other openrouter keys are kept, only
+ * `providers.openrouter.baseUrl` is set; a displaced user value is recorded
+ * in a sidecar marker. A corrupt existing file is overwritten with just the
+ * override — for gateway deployments, guaranteed rerouting wins over
+ * preserving unparseable config.
+ *
+ * Gateway unset/default: reverts a PREVIOUSLY WRITTEN override (marker
+ * present and models.json still carries the marker's value) — restoring the
+ * displaced user baseUrl or deleting the key, dropping now-empty objects,
+ * and removing models.json entirely if the override was all it contained.
+ * The env value in a shared worker isn't per-task in practice, but reverts
+ * make rollback = "unset the env" and keep repo-scoped/self-hosted setups
+ * from inheriting a stale gateway (PR #1010 review). Without a marker the
+ * function never touches models.json, so hand-authored overrides survive.
+ */
+export async function ensureOpenRouterModelsOverride(
+  agentDir: string,
+  env: Record<string, string | undefined> = process.env,
+): Promise<void> {
+  const baseUrl = getOpenRouterBaseUrl(env as NodeJS.ProcessEnv);
+  const modelsPath = join(agentDir, "models.json");
+  const markerPath = join(agentDir, OPENROUTER_OVERRIDE_MARKER);
+
+  if (baseUrl === DEFAULT_OPENROUTER_BASE_URL) {
+    await revertOpenRouterModelsOverride(modelsPath, markerPath);
+    return;
+  }
+
+  let existing: Record<string, unknown> = {};
+  try {
+    const file = Bun.file(modelsPath);
+    if (await file.exists()) {
+      existing = JSON.parse(await file.text()) as Record<string, unknown>;
+    }
+  } catch (err) {
+    console.warn(
+      `[pi-mono] ${modelsPath} is unreadable/invalid (${err instanceof Error ? err.message : err}); rewriting with the OpenRouter gateway override`,
+    );
+    existing = {};
+  }
+
+  const providers =
+    typeof existing.providers === "object" && existing.providers !== null
+      ? (existing.providers as Record<string, unknown>)
+      : {};
+  const openrouter =
+    typeof providers.openrouter === "object" && providers.openrouter !== null
+      ? (providers.openrouter as Record<string, unknown>)
+      : {};
+
+  // Record what we displace, once — re-runs with the marker already present
+  // keep the ORIGINAL displaced value (the current baseUrl is then ours).
+  const priorMarker = (await readJsonFile(markerPath)) as OpenRouterOverrideMarker | undefined;
+  const currentBaseUrl = typeof openrouter.baseUrl === "string" ? openrouter.baseUrl : undefined;
+  const previous = priorMarker
+    ? priorMarker.previous
+    : currentBaseUrl !== baseUrl
+      ? currentBaseUrl
+      : undefined;
+
+  const next = {
+    ...existing,
+    providers: {
+      ...providers,
+      openrouter: { ...openrouter, baseUrl },
+    },
+  };
+  await Bun.write(modelsPath, `${JSON.stringify(next, null, 2)}\n`);
+  const marker: OpenRouterOverrideMarker = {
+    baseUrl,
+    ...(previous !== undefined ? { previous } : {}),
+  };
+  await Bun.write(markerPath, `${JSON.stringify(marker, null, 2)}\n`);
+}
+
+/**
+ * Undo a marker-recorded gateway override. Only acts when the marker exists
+ * AND models.json's `providers.openrouter.baseUrl` still equals the value
+ * the marker says we wrote — anything else means the user edited the file
+ * since, and we leave it alone (the stale marker is dropped either way).
+ */
+async function revertOpenRouterModelsOverride(
+  modelsPath: string,
+  markerPath: string,
+): Promise<void> {
+  const marker = (await readJsonFile(markerPath)) as OpenRouterOverrideMarker | undefined;
+  if (!marker) return;
+  const removeMarker = () => Bun.file(markerPath).delete();
+
+  const existing = await readJsonFile(modelsPath);
+  if (!existing) {
+    await removeMarker();
+    return;
+  }
+  const providers =
+    typeof existing.providers === "object" && existing.providers !== null
+      ? { ...(existing.providers as Record<string, unknown>) }
+      : undefined;
+  const openrouter =
+    providers && typeof providers.openrouter === "object" && providers.openrouter !== null
+      ? { ...(providers.openrouter as Record<string, unknown>) }
+      : undefined;
+  if (!providers || !openrouter || openrouter.baseUrl !== marker.baseUrl) {
+    await removeMarker();
+    return;
+  }
+
+  if (marker.previous !== undefined) {
+    openrouter.baseUrl = marker.previous;
+  } else {
+    delete openrouter.baseUrl;
+  }
+  if (Object.keys(openrouter).length === 0) {
+    delete providers.openrouter;
+  } else {
+    providers.openrouter = openrouter;
+  }
+  const next: Record<string, unknown> = { ...existing, providers };
+  if (Object.keys(providers).length === 0) {
+    delete next.providers;
+  }
+
+  if (Object.keys(next).length === 0) {
+    await Bun.file(modelsPath).delete();
+  } else {
+    await Bun.write(modelsPath, `${JSON.stringify(next, null, 2)}\n`);
+  }
+  await removeMarker();
+}
+
 /**
  * Resolve a model string to a pi-ai Model object.
  *
@@ -960,8 +1127,18 @@ export class PiMonoAdapter implements ProviderAdapter {
     const sessionEnv = config.env ?? process.env;
 
     // 3. Resolve model
-    const model = resolveModel(config.model, sessionEnv);
+    // Write the gateway override BEFORE ModelRuntime.create — the runtime
+    // loads `<agentDir>/models.json` exactly once at creation.
+    await ensureOpenRouterModelsOverride(getAgentDir(), sessionEnv);
+    const builtinModel = resolveModel(config.model, sessionEnv);
     const modelRuntime = await createPiRuntimeAuth(sessionEnv);
+    // models.json overrides (e.g. the OpenRouter gateway baseUrl) only apply
+    // to models resolved through the runtime's composed store; the builtin
+    // catalog object from `resolveModel` carries the hardcoded upstream URL
+    // and would be used verbatim by the session.
+    const model = builtinModel
+      ? (modelRuntime.getModel(builtinModel.provider, builtinModel.id) ?? builtinModel)
+      : builtinModel;
 
     // 4. Create swarm hooks extension
     const swarmExtension = createSwarmHooksExtension({
@@ -970,6 +1147,7 @@ export class PiMonoAdapter implements ProviderAdapter {
       agentId: config.agentId,
       taskId: config.taskId,
       isLead: config.role === "lead",
+      env: sessionEnv,
     });
 
     // 5. Create resource loader with system prompt + extension

package/src/providers/pi-mono-extension.ts

@@ -17,6 +17,12 @@ export interface SwarmHooksConfig {
   agentId: string;
   taskId: string;
   isLead: boolean;
+  /**
+   * Per-task resolved env (`ProviderSessionConfig.env`). Forwarded to the
+   * session-summary path so swarm_config overlays (rotated credentials,
+   * `OPENROUTER_BASE_URL`) apply — they never reach `process.env`.
+   */
+  env?: Record<string, string | undefined>;
 }
 
 /** Standard headers for swarm API requests */
@@ -368,6 +374,9 @@ export async function summarizeSessionForPi(
       },
       apiUrl: config.apiUrl,
       apiKey: config.apiKey,
+      // Per-task resolved env — swarm_config overlays (e.g.
+      // OPENROUTER_BASE_URL) never reach process.env.
+      env: config.env,
     });
     // null = no auth resolved or wrapper exhausted retries (already logged inside)
     if (!result) return;

package/src/tests/agent-avatar-resolution.test.ts

@@ -3,7 +3,10 @@ import { getAgentColorToken, resolveAgentColor } from "../../apps/ui/src/lib/age
 import {
   AVATAR_ICON_CATALOG,
   getAgentIcon,
+  MAX_AVATAR_ICON_SEARCH_RESULTS,
   resolveAgentIcon,
+  searchAvatarIcons,
+  WORKER_ICONS,
 } from "../../apps/ui/src/lib/agent-icon";
 
 /**
@@ -15,6 +18,40 @@ import {
  */
 describe("agent avatar resolution", () => {
   describe("getAgentIcon (deterministic fallback)", () => {
+    test("keeps the 30-entry worker pool and its established order", () => {
+      expect(WORKER_ICONS).toEqual([
+        AVATAR_ICON_CATALOG.bot,
+        AVATAR_ICON_CATALOG.cat,
+        AVATAR_ICON_CATALOG.dog,
+        AVATAR_ICON_CATALOG.bird,
+        AVATAR_ICON_CATALOG.fish,
+        AVATAR_ICON_CATALOG.bug,
+        AVATAR_ICON_CATALOG.snail,
+        AVATAR_ICON_CATALOG.turtle,
+        AVATAR_ICON_CATALOG.squirrel,
+        AVATAR_ICON_CATALOG.cherry,
+        AVATAR_ICON_CATALOG.apple,
+        AVATAR_ICON_CATALOG.carrot,
+        AVATAR_ICON_CATALOG.leaf,
+        AVATAR_ICON_CATALOG.sprout,
+        AVATAR_ICON_CATALOG["tree-deciduous"],
+        AVATAR_ICON_CATALOG.flower,
+        AVATAR_ICON_CATALOG.mountain,
+        AVATAR_ICON_CATALOG.sun,
+        AVATAR_ICON_CATALOG.moon,
+        AVATAR_ICON_CATALOG.cloud,
+        AVATAR_ICON_CATALOG.snowflake,
+        AVATAR_ICON_CATALOG.sparkles,
+        AVATAR_ICON_CATALOG.star,
+        AVATAR_ICON_CATALOG.rocket,
+        AVATAR_ICON_CATALOG.plane,
+        AVATAR_ICON_CATALOG.anchor,
+        AVATAR_ICON_CATALOG.compass,
+        AVATAR_ICON_CATALOG.telescope,
+        AVATAR_ICON_CATALOG.atom,
+        AVATAR_ICON_CATALOG.crown,
+      ]);
+    });
     test("lead always resolves to Crown, regardless of id", () => {
       expect(getAgentIcon({ agentId: "any-id", isLead: true })).toBe(AVATAR_ICON_CATALOG.crown);
       expect(getAgentIcon({ role: "lead", agentId: "any-id" })).toBe(AVATAR_ICON_CATALOG.crown);
@@ -29,6 +66,11 @@ describe("agent avatar resolution", () => {
       expect(first).toBe(second);
     });
 
+    test("keeps fixed seeds on their established fallback icons", () => {
+      expect(getAgentIcon({ agentId: "fixed-seed-alpha" })).toBe(AVATAR_ICON_CATALOG.snail);
+      expect(getAgentIcon({ agentId: "fixed-seed-beta" })).toBe(AVATAR_ICON_CATALOG.moon);
+    });
+
     test("different agentIds can resolve to different icons", () => {
       // Not a strict guarantee for every pair (hash collisions are possible),
       // but across a spread of ids we should see more than one icon.
@@ -44,6 +86,134 @@ describe("agent avatar resolution", () => {
     });
   });
 
+  describe("avatar icon picker search", () => {
+    test("returns the exact familiar shortlist for an empty query, not just its length", () => {
+      // Explicit contents (not just `.toHaveLength(64)`) so this can't silently
+      // drift to a different 64 if AVATAR_ICON_CATALOG is ever reordered.
+      const results = searchAvatarIcons("");
+      expect(results.iconResults).toEqual([
+        "bot",
+        "cat",
+        "dog",
+        "bird",
+        "fish",
+        "bug",
+        "snail",
+        "turtle",
+        "squirrel",
+        "rabbit",
+        "cherry",
+        "apple",
+        "carrot",
+        "leaf",
+        "sprout",
+        "tree-deciduous",
+        "flower",
+        "mountain",
+        "sun",
+        "moon",
+        "cloud",
+        "snowflake",
+        "sparkles",
+        "star",
+        "rocket",
+        "plane",
+        "anchor",
+        "compass",
+        "telescope",
+        "atom",
+        "crown",
+        "award",
+        "book",
+        "box",
+        "briefcase",
+        "camera",
+        "coffee",
+        "diamond",
+        "droplet",
+        "feather",
+        "flag",
+        "flame",
+        "gem",
+        "ghost",
+        "gift",
+        "globe",
+        "heart",
+        "key",
+        "lock",
+        "map",
+        "music",
+        "package",
+        "palette",
+        "pizza",
+        "puzzle",
+        "shield",
+        "skull",
+        "sword",
+        "target",
+        "trophy",
+        "umbrella",
+        "wand",
+        "zap",
+        "wrench",
+      ]);
+      expect(results.totalMatches).toBe(64);
+    });
+
+    test("normalizes case, spaces, and hyphens", () => {
+      expect(searchAvatarIcons("TREE DECIDUOUS").iconResults).toContain("tree-deciduous");
+      expect(searchAvatarIcons("tree-deciduous").iconResults).toContain("tree-deciduous");
+    });
+
+    test("returns no choices for an unmatched query", () => {
+      expect(searchAvatarIcons("not-an-icon-at-all")).toEqual({ iconResults: [], totalMatches: 0 });
+    });
+
+    test("caps broad searches at 100 choices while retaining the match total", () => {
+      const results = searchAvatarIcons("a");
+      expect(results.totalMatches).toBeGreaterThan(MAX_AVATAR_ICON_SEARCH_RESULTS);
+      expect(results.iconResults).toHaveLength(MAX_AVATAR_ICON_SEARCH_RESULTS);
+    });
+
+    test("the catalog has no duplicate-glyph deprecated-alias pairs", () => {
+      // Every icon component in the catalog should be unique — a deprecated
+      // lucide alias re-exports the SAME component as its canonical name, so
+      // two catalog keys pointing at the same component is exactly that bug.
+      const seen = new Map<unknown, string>();
+      const dupes: Array<{ key: string; dupOf: string }> = [];
+      for (const [key, icon] of Object.entries(AVATAR_ICON_CATALOG)) {
+        const existing = seen.get(icon);
+        if (existing) dupes.push({ key, dupOf: existing });
+        else seen.set(icon, key);
+      }
+      expect(dupes).toEqual([]);
+    });
+
+    test("covers previously-unreachable d-z avatar-worthy searches", () => {
+      // Round-3 fix: the catalog used to be an alphabetical head-slice
+      // (a/b/c only), so none of these ever returned a result.
+      for (const query of [
+        "wrench",
+        "gamepad",
+        "sword",
+        "rocket",
+        "crown",
+        "heart",
+        "star",
+        "zap",
+      ]) {
+        expect(searchAvatarIcons(query).totalMatches).toBeGreaterThan(0);
+      }
+      for (const query of ["ghost", "cat", "dog", "pizza", "music"]) {
+        expect(searchAvatarIcons(query).totalMatches).toBeGreaterThan(0);
+      }
+      // Spot-check letters that were entirely absent before this round.
+      for (const query of ["guitar", "octagon", "volleyball", "wheat"]) {
+        expect(searchAvatarIcons(query).totalMatches).toBeGreaterThan(0);
+      }
+    });
+  });
+
   describe("resolveAgentIcon (custom avatar overrides deterministic fallback)", () => {
     test("a known catalog icon wins over the deterministic fallback", () => {
       const avatar = { type: "lucide" as const, icon: "trophy" };

package/src/tests/memory-feature-flags.test.ts

@@ -0,0 +1,45 @@
+import { afterAll, describe, expect, test } from "bun:test";
+import { isGraphExpansionEnabled, isHybridSearchEnabled } from "../be/memory/constants";
+
+const previousHybrid = process.env.MEMORY_HYBRID_SEARCH;
+const previousGraph = process.env.MEMORY_GRAPH_EXPANSION;
+
+afterAll(() => {
+  if (previousHybrid === undefined) delete process.env.MEMORY_HYBRID_SEARCH;
+  else process.env.MEMORY_HYBRID_SEARCH = previousHybrid;
+
+  if (previousGraph === undefined) delete process.env.MEMORY_GRAPH_EXPANSION;
+  else process.env.MEMORY_GRAPH_EXPANSION = previousGraph;
+});
+
+describe("memory retrieval feature flags", () => {
+  test("hybrid search defaults on and keeps explicit enable/disable overrides", () => {
+    delete process.env.MEMORY_HYBRID_SEARCH;
+    expect(isHybridSearchEnabled()).toBe(true);
+
+    for (const enabled of ["", " ", "\t", "1", "true", "TRUE"]) {
+      process.env.MEMORY_HYBRID_SEARCH = enabled;
+      expect(isHybridSearchEnabled()).toBe(true);
+    }
+
+    for (const disabled of ["0", "false", "FALSE", " 0 ", " false "]) {
+      process.env.MEMORY_HYBRID_SEARCH = disabled;
+      expect(isHybridSearchEnabled()).toBe(false);
+    }
+  });
+
+  test("graph expansion defaults on and keeps explicit enable/disable overrides", () => {
+    delete process.env.MEMORY_GRAPH_EXPANSION;
+    expect(isGraphExpansionEnabled()).toBe(true);
+
+    for (const enabled of ["", " ", "\t", "1", "true", "TRUE"]) {
+      process.env.MEMORY_GRAPH_EXPANSION = enabled;
+      expect(isGraphExpansionEnabled()).toBe(true);
+    }
+
+    for (const disabled of ["0", "false", "FALSE", " 0 ", " false "]) {
+      process.env.MEMORY_GRAPH_EXPANSION = disabled;
+      expect(isGraphExpansionEnabled()).toBe(false);
+    }
+  });
+});

package/src/tests/memory-rater-llm-summarizer.test.ts

@@ -139,6 +139,30 @@ describe("runMemoryRater — request shape", () => {
     expect(body.response_format.json_schema.schema).toEqual(MEMORY_RATER_JSON_SCHEMA);
   });
 
+  test("OPENROUTER_BASE_URL reroutes the chat-completions call through the gateway", async () => {
+    const origBaseUrl = process.env.OPENROUTER_BASE_URL;
+    process.env.OPENROUTER_BASE_URL = "https://control-plane.example/proxy/v1/";
+    try {
+      let capturedUrl: string | URL | Request | undefined;
+      const fakeFetch: typeof fetch = async (url) => {
+        capturedUrl = url;
+        return makeOpenRouterResponse(JSON.stringify({ summary: "ok", ratings: [] }));
+      };
+
+      const result = await runMemoryRater({
+        prompt: "test prompt",
+        apiKey: "test-api-key-123",
+        fetchImpl: fakeFetch,
+      });
+
+      expect(result.ok).toBe(true);
+      expect(String(capturedUrl)).toBe("https://control-plane.example/proxy/v1/chat/completions");
+    } finally {
+      if (origBaseUrl === undefined) delete process.env.OPENROUTER_BASE_URL;
+      else process.env.OPENROUTER_BASE_URL = origBaseUrl;
+    }
+  });
+
   test("MEMORY_RATER_JSON_SCHEMA reflects SummaryWithRatingsSchema (key shape only)", () => {
     // Don't assert exact JSON Schema bytes — Zod's emitter can change with
     // version bumps. Lock down the contract that matters for the OpenRouter

package/src/tests/opencode-plugin.test.ts

@@ -21,6 +21,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import type { Message, Part } from "@opencode-ai/sdk";
 import {
   flattenOpencodeTranscript,
+  runSummaryLlm,
   type SummarizeSessionForOpencodeDeps,
   type SwarmConfig,
   summarizeSessionForOpencode,
@@ -494,3 +495,45 @@ describe("summarizeSessionForOpencode", () => {
     expect(postRatingsArgs!.taskId).toBe("task-oc-1");
   });
 });
+
+// ── OPENROUTER_BASE_URL gateway routing (vendored resolver in summarize.ts) ──
+
+describe("runSummaryLlm — OPENROUTER_BASE_URL gateway", () => {
+  const summaryBody = {
+    choices: [{ message: { content: JSON.stringify({ summary: "ok", ratings: [] }) } }],
+  };
+  const openrouterCred = {
+    kind: "openrouter" as const,
+    apiKey: "sk-or-test",
+    modelDefault: "openrouter/google/gemini-3-flash-preview",
+  };
+
+  afterEach(() => {
+    delete process.env.OPENROUTER_BASE_URL;
+  });
+
+  test("defaults to openrouter.ai when the env is unset", async () => {
+    fetchHandler = async () => ({
+      ok: true,
+      status: 200,
+      text: async () => "",
+      json: async () => summaryBody,
+    });
+    const result = await runSummaryLlm(openrouterCred, "sys", "user");
+    expect(result).not.toBeNull();
+    expect(fetchCalls[0]?.url).toBe("https://openrouter.ai/api/v1/chat/completions");
+  });
+
+  test("reroutes through the gateway when OPENROUTER_BASE_URL is set", async () => {
+    process.env.OPENROUTER_BASE_URL = "https://control-plane.example/proxy/v1/";
+    fetchHandler = async () => ({
+      ok: true,
+      status: 200,
+      text: async () => "",
+      json: async () => summaryBody,
+    });
+    const result = await runSummaryLlm(openrouterCred, "sys", "user");
+    expect(result).not.toBeNull();
+    expect(fetchCalls[0]?.url).toBe("https://control-plane.example/proxy/v1/chat/completions");
+  });
+});