@desplega.ai/agent-swarm 1.121.0 → 1.122.0

package/src/tests/openrouter-base-url.test.ts

@@ -0,0 +1,256 @@
+/**
+ * OPENROUTER_BASE_URL gateway routing — unit tests.
+ *
+ * Covers the shared resolver (`src/utils/openrouter-base-url.ts`), the pi
+ * models.json override writer (`ensureOpenRouterModelsOverride`) including
+ * its composition through pi-coding-agent's ModelRuntime, and the opencode
+ * per-task config injection (`applyOpenRouterBaseUrlOverride`).
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ModelRuntime } from "@earendil-works/pi-coding-agent";
+import type { Config } from "@opencode-ai/sdk";
+import { applyOpenRouterBaseUrlOverride } from "../providers/opencode-adapter";
+import { ensureOpenRouterModelsOverride } from "../providers/pi-mono-adapter";
+import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../utils/openrouter-base-url";
+
+const GATEWAY = "https://control-plane.example/proxy/v1";
+
+describe("getOpenRouterBaseUrl", () => {
+  test("defaults to openrouter.ai when unset", () => {
+    expect(getOpenRouterBaseUrl({} as NodeJS.ProcessEnv)).toBe(DEFAULT_OPENROUTER_BASE_URL);
+  });
+
+  test("blank / whitespace-only values fall back to the default", () => {
+    expect(getOpenRouterBaseUrl({ OPENROUTER_BASE_URL: "" } as NodeJS.ProcessEnv)).toBe(
+      DEFAULT_OPENROUTER_BASE_URL,
+    );
+    expect(getOpenRouterBaseUrl({ OPENROUTER_BASE_URL: "   " } as NodeJS.ProcessEnv)).toBe(
+      DEFAULT_OPENROUTER_BASE_URL,
+    );
+  });
+
+  test("returns the override verbatim (trimmed)", () => {
+    expect(getOpenRouterBaseUrl({ OPENROUTER_BASE_URL: ` ${GATEWAY} ` } as NodeJS.ProcessEnv)).toBe(
+      GATEWAY,
+    );
+  });
+
+  test("strips trailing slashes so call sites can append paths", () => {
+    expect(getOpenRouterBaseUrl({ OPENROUTER_BASE_URL: `${GATEWAY}//` } as NodeJS.ProcessEnv)).toBe(
+      GATEWAY,
+    );
+  });
+});
+
+describe("ensureOpenRouterModelsOverride (pi)", () => {
+  let agentDir: string;
+
+  beforeAll(() => {
+    agentDir = mkdtempSync(join(tmpdir(), "pi-or-override-"));
+  });
+
+  afterAll(() => {
+    rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  test("no-op when OPENROUTER_BASE_URL is unset", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-noop-"));
+    try {
+      await ensureOpenRouterModelsOverride(dir, {});
+      expect(await Bun.file(join(dir, "models.json")).exists()).toBe(false);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("writes providers.openrouter.baseUrl when the env is set", async () => {
+    await ensureOpenRouterModelsOverride(agentDir, { OPENROUTER_BASE_URL: GATEWAY });
+    const written = JSON.parse(await Bun.file(join(agentDir, "models.json")).text());
+    expect(written).toEqual({ providers: { openrouter: { baseUrl: GATEWAY } } });
+  });
+
+  test("reverts a written override when the env returns to default (file we created is removed)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-revert-"));
+    try {
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      expect(await Bun.file(join(dir, "models.json")).exists()).toBe(true);
+      await ensureOpenRouterModelsOverride(dir, {});
+      // The override was ALL the file contained — both it and the marker go.
+      expect(await Bun.file(join(dir, "models.json")).exists()).toBe(false);
+      expect(await Bun.file(join(dir, ".agent-swarm-openrouter-override.json")).exists()).toBe(
+        false,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("revert restores a displaced user baseUrl and keeps sibling keys", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-restore-"));
+    try {
+      await Bun.write(
+        join(dir, "models.json"),
+        JSON.stringify({
+          providers: {
+            openrouter: { baseUrl: "https://user.example/v1", compat: { supportsTools: true } },
+            custom: { baseUrl: "https://custom.example/v1", api: "openai-completions" },
+          },
+        }),
+      );
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      // Re-run with the gateway still set — displaced value must survive.
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      await ensureOpenRouterModelsOverride(dir, {});
+      const restored = JSON.parse(await Bun.file(join(dir, "models.json")).text());
+      expect(restored.providers.openrouter).toEqual({
+        baseUrl: "https://user.example/v1",
+        compat: { supportsTools: true },
+      });
+      expect(restored.providers.custom).toEqual({
+        baseUrl: "https://custom.example/v1",
+        api: "openai-completions",
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("revert leaves a user-edited baseUrl alone (marker mismatch) and drops the marker", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-user-edit-"));
+    try {
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      // User hand-edits the file after we wrote it.
+      await Bun.write(
+        join(dir, "models.json"),
+        JSON.stringify({ providers: { openrouter: { baseUrl: "https://mine.example/v1" } } }),
+      );
+      await ensureOpenRouterModelsOverride(dir, {});
+      const kept = JSON.parse(await Bun.file(join(dir, "models.json")).text());
+      expect(kept.providers.openrouter.baseUrl).toBe("https://mine.example/v1");
+      expect(await Bun.file(join(dir, ".agent-swarm-openrouter-override.json")).exists()).toBe(
+        false,
+      );
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("default env never touches a hand-authored models.json (no marker)", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-hands-off-"));
+    try {
+      const userConfig = {
+        providers: { openrouter: { baseUrl: "https://mine.example/v1" } },
+      };
+      await Bun.write(join(dir, "models.json"), JSON.stringify(userConfig));
+      await ensureOpenRouterModelsOverride(dir, {});
+      expect(JSON.parse(await Bun.file(join(dir, "models.json")).text())).toEqual(userConfig);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("merge-preserves existing providers and openrouter keys", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-merge-"));
+    try {
+      await Bun.write(
+        join(dir, "models.json"),
+        JSON.stringify({
+          providers: {
+            openrouter: { baseUrl: "https://old.example/v1", compat: { supportsTools: true } },
+            custom: { baseUrl: "https://custom.example/v1", api: "openai-completions" },
+          },
+        }),
+      );
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      const written = JSON.parse(await Bun.file(join(dir, "models.json")).text());
+      expect(written.providers.openrouter.baseUrl).toBe(GATEWAY);
+      expect(written.providers.openrouter.compat).toEqual({ supportsTools: true });
+      expect(written.providers.custom).toEqual({
+        baseUrl: "https://custom.example/v1",
+        api: "openai-completions",
+      });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("overwrites a corrupt models.json with just the override", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-corrupt-"));
+    try {
+      await Bun.write(join(dir, "models.json"), "{not json");
+      await ensureOpenRouterModelsOverride(dir, { OPENROUTER_BASE_URL: GATEWAY });
+      const written = JSON.parse(await Bun.file(join(dir, "models.json")).text());
+      expect(written).toEqual({ providers: { openrouter: { baseUrl: GATEWAY } } });
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("ModelRuntime composes the override onto built-in OpenRouter models", async () => {
+    // The whole point of the lever: built-in model IDs resolved through the
+    // runtime's composed store carry the gateway baseUrl.
+    const runtime = await ModelRuntime.create({
+      authPath: join(agentDir, "auth.json"),
+      modelsPath: join(agentDir, "models.json"),
+    });
+    expect(runtime.getError()).toBeUndefined();
+    const model = runtime.getModel("openrouter", "anthropic/claude-sonnet-5");
+    expect(model?.baseUrl).toBe(GATEWAY);
+  });
+
+  test("ModelRuntime keeps the default baseUrl when no models.json exists", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "pi-or-default-"));
+    try {
+      const runtime = await ModelRuntime.create({
+        authPath: join(dir, "auth.json"),
+        modelsPath: join(dir, "models.json"),
+      });
+      const model = runtime.getModel("openrouter", "anthropic/claude-sonnet-5");
+      expect(model?.baseUrl).toBe(DEFAULT_OPENROUTER_BASE_URL);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});
+
+describe("applyOpenRouterBaseUrlOverride (opencode)", () => {
+  test("no-op when OPENROUTER_BASE_URL is unset", () => {
+    const config: Config = { model: "openrouter/google/gemini-3-flash-preview" };
+    applyOpenRouterBaseUrlOverride(config, {});
+    expect(config.provider).toBeUndefined();
+  });
+
+  test("sets provider.openrouter.options.baseURL when the env is set", () => {
+    const config: Config = { model: "openrouter/google/gemini-3-flash-preview" };
+    applyOpenRouterBaseUrlOverride(config, { OPENROUTER_BASE_URL: GATEWAY });
+    expect(config.provider?.openrouter?.options?.baseURL).toBe(GATEWAY);
+  });
+
+  test("preserves existing provider config (e.g. reasoning model options)", () => {
+    const config: Config = {
+      model: "openrouter/google/gemini-3-flash-preview",
+      provider: {
+        openrouter: {
+          models: {
+            "google/gemini-3-flash-preview": { options: { reasoning: { effort: "low" } } },
+          },
+          options: { apiKey: "sk-keep" },
+        },
+        anthropic: { options: { apiKey: "sk-ant" } },
+      },
+    };
+    applyOpenRouterBaseUrlOverride(config, { OPENROUTER_BASE_URL: GATEWAY });
+    expect(config.provider?.openrouter?.options).toEqual({
+      apiKey: "sk-keep",
+      baseURL: GATEWAY,
+    });
+    expect(config.provider?.openrouter?.models).toEqual({
+      "google/gemini-3-flash-preview": { options: { reasoning: { effort: "low" } } },
+    });
+    expect(config.provider?.anthropic).toEqual({ options: { apiKey: "sk-ant" } });
+  });
+});

package/src/tests/pi-mono-adapter.test.ts

@@ -81,6 +81,96 @@ describe("PiMonoAdapter.createSession — reasoning_effort", () => {
   });
 });
 
+// ─── OPENROUTER_BASE_URL gateway routing (session model composition) ─────────
+
+describe("PiMonoAdapter.createSession — OPENROUTER_BASE_URL gateway", () => {
+  const GATEWAY = "https://control-plane.example/proxy/v1";
+  const agentDir = `/tmp/pi-or-gateway-test-${Date.now()}`;
+  const origAgentDirEnv = process.env.PI_CODING_AGENT_DIR;
+
+  let createAgentSessionSpy: ReturnType<typeof spyOn>;
+  let capturedOptions: Record<string, unknown> | undefined;
+
+  beforeAll(() => {
+    mkdirSync(agentDir, { recursive: true });
+    // getAgentDir() reads process.env directly (config.env doesn't reach it).
+    process.env.PI_CODING_AGENT_DIR = agentDir;
+  });
+
+  afterAll(() => {
+    if (origAgentDirEnv === undefined) delete process.env.PI_CODING_AGENT_DIR;
+    else process.env.PI_CODING_AGENT_DIR = origAgentDirEnv;
+    rmSync(agentDir, { recursive: true, force: true });
+  });
+
+  afterEach(() => {
+    createAgentSessionSpy?.mockRestore();
+    capturedOptions = undefined;
+  });
+
+  function makeConfig(env: Record<string, string>): ProviderSessionConfig {
+    return {
+      prompt: "hello",
+      systemPrompt: "",
+      model: "openrouter/google/gemini-3-flash-preview",
+      role: "worker",
+      agentId: "test-agent",
+      taskId: "test-task",
+      apiUrl: "",
+      apiKey: "",
+      cwd: "/tmp",
+      logFile: `/tmp/pi-or-gateway-test-${Date.now()}-${Math.random().toString(36).slice(2)}.log`,
+      env: { OPENROUTER_API_KEY: "sk-or-test", ...env },
+    };
+  }
+
+  function spyOnCreateAgentSession() {
+    createAgentSessionSpy = spyOn(piCodingAgent, "createAgentSession").mockImplementation((async (
+      opts: Record<string, unknown>,
+    ) => {
+      capturedOptions = opts;
+      return {
+        session: {
+          sessionId: "fake-session",
+          isStreaming: false,
+          model: undefined,
+          subscribe: () => () => {},
+          dispose: () => {},
+        },
+      };
+    }) as typeof piCodingAgent.createAgentSession);
+  }
+
+  test("session model carries the gateway baseUrl when OPENROUTER_BASE_URL is set", async () => {
+    spyOnCreateAgentSession();
+    const adapter = new PiMonoAdapter();
+    await adapter.createSession(makeConfig({ OPENROUTER_BASE_URL: GATEWAY }));
+    const model = capturedOptions?.model as { baseUrl?: string; id?: string } | undefined;
+    expect(model?.id).toBe("google/gemini-3-flash-preview");
+    expect(model?.baseUrl).toBe(GATEWAY);
+    // The override was materialized for the runtime to load.
+    expect(existsSync(join(agentDir, "models.json"))).toBe(true);
+  });
+
+  test("session model keeps the default openrouter.ai baseUrl when env is unset", async () => {
+    // Fresh agent dir so the previous test's models.json doesn't leak in.
+    const cleanDir = `${agentDir}-clean`;
+    mkdirSync(cleanDir, { recursive: true });
+    process.env.PI_CODING_AGENT_DIR = cleanDir;
+    try {
+      spyOnCreateAgentSession();
+      const adapter = new PiMonoAdapter();
+      await adapter.createSession(makeConfig({}));
+      const model = capturedOptions?.model as { baseUrl?: string } | undefined;
+      expect(model?.baseUrl).toBe("https://openrouter.ai/api/v1");
+      expect(existsSync(join(cleanDir, "models.json"))).toBe(false);
+    } finally {
+      process.env.PI_CODING_AGENT_DIR = agentDir;
+      rmSync(cleanDir, { recursive: true, force: true });
+    }
+  });
+});
+
 describe("AGENTS.md symlink management", () => {
   const tmpDir = `/tmp/pi-mono-test-${Date.now()}`;
 

package/src/tools/memory-search.ts

@@ -93,7 +93,8 @@ export const registerMemorySearchTool = (server: McpServer) => {
         isLead,
         queryText: query,
       });
-      // 1-hop memory_link neighbor expansion (no-op unless MEMORY_GRAPH_EXPANSION=1).
+      // Default-on 1-hop memory_link neighbor expansion (disable with
+      // MEMORY_GRAPH_EXPANSION=0|false).
       const expanded = expandCandidatesWithGraph(candidates, requestInfo.agentId, {
         scope: scope as "agent" | "swarm" | "all",
         source,

package/src/utils/internal-ai/complete-structured.ts

@@ -20,6 +20,7 @@ import { complete } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModel as getModel } from "@earendil-works/pi-ai/providers/all";
 import type { TSchema } from "typebox";
 import { z } from "zod";
+import { DEFAULT_OPENROUTER_BASE_URL, getOpenRouterBaseUrl } from "../openrouter-base-url.js";
 import { type ResolvedCredential, resolveCredential } from "./credentials.js";
 import { parseModelStr } from "./models.js";
 
@@ -40,6 +41,14 @@ export interface CompleteStructuredOptions<TZod extends z.ZodTypeAny> {
    */
   apiUrl?: string;
   apiKey?: string;
+  /**
+   * Per-task resolved environment (`ProviderSessionConfig.env` /
+   * `fetchResolvedEnv` output). Used for credential lookup AND the
+   * `OPENROUTER_BASE_URL` gateway override — swarm_config-sourced values
+   * never reach `process.env`, so callers with a session env must pass it.
+   * Defaults to `process.env`.
+   */
+  env?: Record<string, string | undefined>;
   /** Default: 3. */
   retries?: number;
   signal?: AbortSignal;
@@ -186,7 +195,7 @@ export async function completeStructured<TZod extends z.ZodTypeAny>(
   } else {
     const resolver = opts._resolveCredential ?? resolveCredential;
     cred = await resolver({
-      env: process.env,
+      env: (opts.env ?? process.env) as NodeJS.ProcessEnv,
       apiUrl: opts.apiUrl,
       apiKey: opts.apiKey,
       callerTag: opts.callerTag,
@@ -259,6 +268,15 @@ export async function completeStructured<TZod extends z.ZodTypeAny>(
     return null;
   }
 
+  // The builtin catalog hardcodes openrouter.ai; OPENROUTER_BASE_URL reroutes
+  // through a gateway (pi-ai's stream path uses `model.baseUrl` verbatim).
+  // Resolved from the caller's session env when provided — swarm_config
+  // overlays don't reach `process.env`.
+  const openRouterBaseUrl = getOpenRouterBaseUrl((opts.env ?? process.env) as NodeJS.ProcessEnv);
+  if (provider === "openrouter" && openRouterBaseUrl !== DEFAULT_OPENROUTER_BASE_URL) {
+    model = { ...model, baseUrl: openRouterBaseUrl };
+  }
+
   const completeFn = opts._complete ?? complete;
   let userPrompt = opts.userPrompt;
   let lastErr: unknown = null;

package/src/utils/internal-ai/summarize-session.ts

@@ -35,6 +35,12 @@ export interface SummarizeSessionOptions {
   /** Passed through to `completeStructured` for codex-OAuth probing. */
   apiUrl: string;
   apiKey: string;
+  /**
+   * Per-task resolved env — forwarded to `completeStructured` so credential
+   * lookup and the `OPENROUTER_BASE_URL` gateway override see swarm_config
+   * overlays that never reach `process.env`.
+   */
+  env?: Record<string, string | undefined>;
   signal?: AbortSignal;
   /**
    * Bypass `resolveCredential` entirely — opencode auth path (and tests) pass
@@ -94,6 +100,7 @@ export async function summarizeSession(
     callerTag: `session-summary:${opts.harness}`,
     apiUrl: opts.apiUrl,
     apiKey: opts.apiKey,
+    env: opts.env,
     signal: opts.signal,
     retries: 3,
     ...(opts._credentialOverride ? { _credentialOverride: opts._credentialOverride } : {}),

package/src/utils/openrouter-base-url.ts

@@ -0,0 +1,28 @@
+/**
+ * OpenRouter base-URL resolution.
+ *
+ * `OPENROUTER_BASE_URL` lets a deployment route all OpenRouter traffic
+ * through an OpenAI-compatible gateway (e.g. the cloud control plane's
+ * `/proxy/v1` endpoint) instead of `openrouter.ai` directly, so the raw
+ * OpenRouter key never has to live on the box. When the env var is unset
+ * the default OpenRouter URL is used and behavior is unchanged.
+ *
+ * Worker-safe: pure env read, no `src/be/db` / `bun:sqlite` imports.
+ * The opencode summarize plugin (`plugin/opencode-plugins/lib/summarize.ts`)
+ * vendors this logic — keep the two in sync.
+ */
+
+export const DEFAULT_OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+
+/**
+ * Resolve the OpenRouter base URL (no trailing slash). Reads
+ * `OPENROUTER_BASE_URL` from `env`; blank values fall back to the default.
+ * Call sites append paths like `/chat/completions` or `/models`.
+ */
+export function getOpenRouterBaseUrl(env: NodeJS.ProcessEnv = process.env): string {
+  const raw = env.OPENROUTER_BASE_URL;
+  if (typeof raw === "string" && raw.trim().length > 0) {
+    return raw.trim().replace(/\/+$/, "");
+  }
+  return DEFAULT_OPENROUTER_BASE_URL;
+}

package/src/workflows/executors/raw-llm.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
+import { getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
 import { BaseExecutor, type ExecutorResult } from "./base";
 
 // ─── Schemas ────────────────────────────────────────────────
@@ -27,7 +28,7 @@ export async function executeRawLlm(
   try {
     const { createOpenAI } = await import("@ai-sdk/openai");
     const openrouter = createOpenAI({
-      baseURL: "https://openrouter.ai/api/v1",
+      baseURL: getOpenRouterBaseUrl(),
       apiKey: process.env.OPENROUTER_API_KEY,
     });
     const model = openrouter(modelName);

package/src/workflows/executors/validate.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import type { ExecutorMeta } from "../../types";
+import { getOpenRouterBaseUrl } from "../../utils/openrouter-base-url";
 import { BaseExecutor, type ExecutorResult } from "./base";
 
 // ─── Schemas ────────────────────────────────────────────────
@@ -115,7 +116,7 @@ export class ValidateExecutor extends BaseExecutor<
       const { generateObject, jsonSchema } = await import("ai");
 
       const openrouter = createOpenAI({
-        baseURL: "https://openrouter.ai/api/v1",
+        baseURL: getOpenRouterBaseUrl(),
         apiKey: process.env.OPENROUTER_API_KEY,
       });