@desplega.ai/agent-swarm 1.92.2 → 1.94.0

package/src/utils/credentials.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "bun:test";
 import {
   CREDENTIAL_POOL_VARS,
+  getModelAwareCredentialVars,
   resolveCredentialPools,
   selectRandomCredential,
   validateClaudeCredentials,
@@ -154,3 +155,70 @@ describe("CREDENTIAL_POOL_VARS", () => {
     expect(CREDENTIAL_POOL_VARS).toContain("ANTHROPIC_API_KEY");
   });
 });
+
+describe("getModelAwareCredentialVars", () => {
+  it("excludes OPENAI_API_KEY for opencode with OpenRouter model (slash in name)", () => {
+    const vars = getModelAwareCredentialVars("opencode", "google/gemini-3-flash-preview");
+    expect(vars).toContain("OPENROUTER_API_KEY");
+    expect(vars).toContain("ANTHROPIC_API_KEY");
+    expect(vars).not.toContain("OPENAI_API_KEY");
+  });
+
+  it("keeps OPENAI_API_KEY for opencode with direct OpenAI model (no slash)", () => {
+    const vars = getModelAwareCredentialVars("opencode", "gpt-4o");
+    expect(vars).toContain("OPENROUTER_API_KEY");
+    expect(vars).toContain("ANTHROPIC_API_KEY");
+    expect(vars).toContain("OPENAI_API_KEY");
+  });
+
+  it("keeps OPENAI_API_KEY for opencode when model is empty", () => {
+    const vars = getModelAwareCredentialVars("opencode", "");
+    expect(vars).toContain("OPENAI_API_KEY");
+  });
+
+  it("keeps OPENAI_API_KEY for opencode when model is undefined", () => {
+    const vars = getModelAwareCredentialVars("opencode");
+    expect(vars).toContain("OPENAI_API_KEY");
+  });
+
+  it("excludes OPENAI_API_KEY for pi with OpenRouter model (slash in name)", () => {
+    const vars = getModelAwareCredentialVars("pi", "anthropic/claude-sonnet-4-20250514");
+    expect(vars).toContain("OPENROUTER_API_KEY");
+    expect(vars).toContain("ANTHROPIC_API_KEY");
+    expect(vars).not.toContain("OPENAI_API_KEY");
+  });
+
+  it("keeps OPENAI_API_KEY for pi with direct model (no slash)", () => {
+    const vars = getModelAwareCredentialVars("pi", "gpt-4o");
+    expect(vars).toContain("OPENROUTER_API_KEY");
+    expect(vars).toContain("ANTHROPIC_API_KEY");
+    expect(vars).toContain("OPENAI_API_KEY");
+  });
+
+  it("keeps OPENAI_API_KEY for pi when model is undefined", () => {
+    const vars = getModelAwareCredentialVars("pi");
+    expect(vars).toContain("OPENAI_API_KEY");
+  });
+
+  it("returns static list for non-slash providers regardless of model", () => {
+    const vars = getModelAwareCredentialVars("claude", "google/gemini-3-flash-preview");
+    expect(vars).toContain("CLAUDE_CODE_OAUTH_TOKEN");
+    expect(vars).toContain("ANTHROPIC_API_KEY");
+    expect(vars).not.toContain("OPENAI_API_KEY");
+  });
+
+  it("falls back to all pool vars for unknown provider", () => {
+    const vars = getModelAwareCredentialVars("unknown-provider", "some-model");
+    expect(vars).toEqual(CREDENTIAL_POOL_VARS);
+  });
+
+  it("handles OpenRouter-prefixed models", () => {
+    const vars = getModelAwareCredentialVars("opencode", "openrouter/openai/gpt-4o");
+    expect(vars).not.toContain("OPENAI_API_KEY");
+  });
+
+  it("handles Anthropic-prefixed models via OpenRouter", () => {
+    const vars = getModelAwareCredentialVars("opencode", "anthropic/claude-sonnet-4-20250514");
+    expect(vars).not.toContain("OPENAI_API_KEY");
+  });
+});

package/src/utils/credentials.ts

@@ -23,13 +23,47 @@ export const CREDENTIAL_POOL_VARS = [
  */
 export const PROVIDER_CREDENTIAL_VARS: Record<string, readonly string[]> = {
   claude: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
-  // pi-mono accepts either router or anthropic keys
-  pi: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY"],
+  pi: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
   codex: ["OPENAI_API_KEY", "CODEX_OAUTH"],
   devin: ["DEVIN_API_KEY"],
   opencode: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
 };
 
+/**
+ * Providers where models use `provider_id/model_id` format — a slash in the
+ * model string means the model is routed through an upstream provider (e.g.
+ * OpenRouter) and OPENAI_API_KEY must not be selected (it would auth against
+ * the wrong endpoint). Without a slash the model targets a direct API (e.g.
+ * OpenAI) and OPENAI_API_KEY is valid.
+ *
+ * Both opencode and pi follow this convention:
+ * - opencode: https://opencode.ai/docs/models/
+ * - pi: https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/models.md
+ */
+const SLASH_MODEL_PROVIDERS = new Set(["opencode", "pi"]);
+
+/**
+ * Given a provider and model string, return the credential vars that are
+ * actually relevant. This implements the harness × model matrix constraint:
+ *
+ * - (opencode | pi) + model with "/" (e.g. "google/gemini-3-flash-preview",
+ *   "openrouter/openai/gpt-4o"): the model is routed through OpenRouter →
+ *   OPENAI_API_KEY must not be selected.
+ * - (opencode | pi) + model without "/" (e.g. "gpt-4o", "o3-mini") or empty:
+ *   the model targets a direct API → keep all creds including OPENAI_API_KEY.
+ *
+ * All other providers return their static list unchanged.
+ */
+export function getModelAwareCredentialVars(provider: string, model?: string): readonly string[] {
+  const base = PROVIDER_CREDENTIAL_VARS[provider];
+  if (!base) return CREDENTIAL_POOL_VARS;
+  if (!SLASH_MODEL_PROVIDERS.has(provider) || !model) return base;
+  if (model.includes("/")) {
+    return base.filter((v) => v !== "OPENAI_API_KEY");
+  }
+  return base;
+}
+
 /**
  * Derive a canonical harness provider from a credential env var name. Used
  * by the api_key_status table's `provider` column so the dashboard can
@@ -64,6 +98,8 @@ export interface CredentialSelection {
   keySuffix: string;
   /** Which credential pool env var this selection came from */
   keyType: string;
+  /** True when all indices for this keyType were rate-limited (best-effort pick) */
+  isRateLimitFallback: boolean;
 }
 
 /**
@@ -82,10 +118,19 @@ export function selectCredential(
     .filter(Boolean);
   if (credentials.length <= 1) {
     const selected = value.trim();
-    return { selected, index: 0, total: 1, keySuffix: selected.slice(-5), keyType };
+    const isRateLimitFallback = availableIndices !== undefined && availableIndices.length === 0;
+    return {
+      selected,
+      index: 0,
+      total: 1,
+      keySuffix: selected.slice(-5),
+      keyType,
+      isRateLimitFallback,
+    };
   }
 
   let index: number;
+  let isRateLimitFallback = false;
   if (availableIndices && availableIndices.length > 0) {
     // Pick randomly from available (non-rate-limited) indices
     const validIndices = availableIndices.filter((i) => i >= 0 && i < credentials.length);
@@ -94,17 +139,26 @@ export function selectCredential(
     } else {
       // All available indices out of range — fall back to random from all
       index = Math.floor(Math.random() * credentials.length);
+      isRateLimitFallback = true;
     }
   } else if (availableIndices && availableIndices.length === 0) {
     // All keys are rate-limited — pick randomly anyway (best effort)
     index = Math.floor(Math.random() * credentials.length);
+    isRateLimitFallback = true;
   } else {
     // No availability info — pure random (backward compatible)
     index = Math.floor(Math.random() * credentials.length);
   }
 
   const selected = credentials[index]!;
-  return { selected, index, total: credentials.length, keySuffix: selected.slice(-5), keyType };
+  return {
+    selected,
+    index,
+    total: credentials.length,
+    keySuffix: selected.slice(-5),
+    keyType,
+    isRateLimitFallback,
+  };
 }
 
 /**
@@ -208,10 +262,17 @@ export async function resolveCredentialPools(
      * container env. Defaults to ALL pool vars for backwards compatibility.
      */
     provider?: string;
+    /**
+     * Optional model string (e.g. "google/gemini-3-flash-preview", "gpt-4o").
+     * Used together with `provider` to apply the harness × model matrix:
+     * an OpenRouter-routed model (contains "/") on the opencode harness must
+     * not select OPENAI_API_KEY, while a direct OpenAI model may.
+     */
+    model?: string;
   },
 ): Promise<CredentialSelection[]> {
   const providerVars = opts?.provider
-    ? (PROVIDER_CREDENTIAL_VARS[opts.provider] ?? CREDENTIAL_POOL_VARS)
+    ? getModelAwareCredentialVars(opts.provider, opts.model)
     : CREDENTIAL_POOL_VARS;
 
   const availableIndicesMap =

package/src/utils/pretty-print.ts

@@ -87,6 +87,17 @@ export function prettyPrintLine(line: string, role: string): void {
     const prefix = `${c.dim}[${role}]${c.reset}`;
 
     switch (type) {
+      case "session_init": {
+        const provider = json.provider as string;
+        const variant = json.harnessVariant as string;
+        const meta = json.harnessVariantMeta as Record<string, unknown> | undefined;
+        const version = meta?.version ?? "";
+        console.log(
+          `${prefix} ${c.cyan}●${c.reset} ${c.bold}Session started${c.reset} ${c.dim}(${provider}${variant ? ` ${variant}` : ""}${version ? ` v${version}` : ""})${c.reset}`,
+        );
+        break;
+      }
+
       case "system": {
         const subtype = json.subtype as string;
         if (subtype === "init") {
@@ -190,20 +201,24 @@ export function prettyPrintLine(line: string, role: string): void {
       }
 
       case "result": {
-        const subtype = json.subtype as string;
-        const isError = json.is_error as boolean;
-        const duration = json.duration_ms as number;
-        const cost = json.total_cost_usd as number;
-        const numTurns = json.num_turns as number;
-        const result = json.result as string;
+        // Claude CLI emits flat fields (subtype, num_turns, duration_ms, total_cost_usd).
+        // Non-Claude adapters (opencode, pi) emit a nested `cost` object with
+        // CostData fields. Handle both formats gracefully.
+        const costObj = json.cost as Record<string, unknown> | undefined;
+        const subtype = (json.subtype as string) ?? (json.isError ? "error" : "success");
+        const isError = (json.is_error as boolean) ?? (json.isError as boolean) ?? false;
+        const duration = (json.duration_ms as number) ?? (costObj?.durationMs as number);
+        const costUsd = (json.total_cost_usd as number) ?? (costObj?.totalCostUsd as number);
+        const numTurns = (json.num_turns as number) ?? (costObj?.numTurns as number | null);
+        const result = (json.result as string) ?? (json.output as string);
 
         const icon = isError ? `${c.red}✗${c.reset}` : `${c.green}✓${c.reset}`;
         const durationStr = duration ? `${(duration / 1000).toFixed(1)}s` : "";
-        const costStr = cost ? `$${cost.toFixed(4)}` : "";
+        const costStr = costUsd ? `$${costUsd.toFixed(4)}` : "";
+        const turnsStr = numTurns != null ? `${numTurns} turns` : "";
 
-        console.log(
-          `${prefix} ${icon} ${c.bold}Done${c.reset} ${c.dim}(${subtype}, ${numTurns} turns, ${durationStr}, ${costStr})${c.reset}`,
-        );
+        const details = [subtype, turnsStr, durationStr, costStr].filter(Boolean).join(", ");
+        console.log(`${prefix} ${icon} ${c.bold}Done${c.reset} ${c.dim}(${details})${c.reset}`);
 
         if (result) {
           const lines = result.split("\n").filter((l) => l.trim());

package/src/utils/skill-fs-writer.ts

@@ -0,0 +1,220 @@
+/**
+ * Pure, DB-free filesystem writer for agent skills.
+ *
+ * Worker-safe: imports only node:fs / node:os / node:path — no be/db, no bun:sqlite.
+ *
+ * Shared by:
+ *   - API-side: syncSkillsToFilesystem (src/be/skill-sync.ts) which fetches
+ *     SkillFsEntry data from the DB then delegates here.
+ *   - Worker-side: refreshSkillsIfChanged (src/utils/skills-refresh.ts) which
+ *     fetches SkillFsEntry data over HTTP then calls writeSkillsToFilesystem
+ *     with the worker's own homedir(), writing SKILL.md files to the correct
+ *     machine instead of the API box.
+ */
+
+import type { Dirent } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+export interface SkillSyncResult {
+  synced: number;
+  removed: number;
+  errors: string[];
+}
+
+export interface SkillFsEntry {
+  id: string;
+  name: string;
+  content: string | null;
+  isComplex: boolean;
+  isEnabled: boolean;
+  isActive: boolean;
+  files: { path: string; content: string; isBinary: boolean }[];
+}
+
+/**
+ * Marker file written into every swarm-managed skill directory. Cleanup
+ * only ever removes directories that contain this marker, so unrelated
+ * personal skills the user installed via the harness's own tooling (e.g.
+ * `codex skills add ...` writing into `~/.codex/skills/<name>/`) are left
+ * untouched even when the API server shares a HOME with the worker (local
+ * dev). See `~/.codex/skills` blast-radius note in PR #555.
+ */
+export const SWARM_MARKER_FILE = ".swarm-managed";
+
+function reconcileManagedSkillFiles(skillDir: string, currentRelativeFiles: Set<string>): number {
+  if (!existsSync(join(skillDir, SWARM_MARKER_FILE))) return 0;
+
+  let removed = 0;
+
+  const walk = (dir: string, relativeDir = ""): boolean => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return false;
+    }
+
+    let hasEntries = false;
+    for (const entry of entries) {
+      const relativePath = relativeDir ? `${relativeDir}/${entry.name}` : entry.name;
+      const fullPath = join(dir, entry.name);
+
+      if (entry.isDirectory()) {
+        const childHasEntries = walk(fullPath, relativePath);
+        if (!childHasEntries) {
+          try {
+            rmSync(fullPath, { recursive: true, force: true });
+          } catch {
+            hasEntries = true;
+          }
+        } else {
+          hasEntries = true;
+        }
+        continue;
+      }
+
+      if (
+        relativePath === "SKILL.md" ||
+        relativePath === SWARM_MARKER_FILE ||
+        currentRelativeFiles.has(relativePath)
+      ) {
+        hasEntries = true;
+        continue;
+      }
+
+      try {
+        rmSync(fullPath, { force: true });
+        removed++;
+      } catch {
+        hasEntries = true;
+      }
+    }
+
+    return hasEntries;
+  };
+
+  walk(skillDir);
+  return removed;
+}
+
+/**
+ * Write skill entries to the filesystem under the given home directory.
+ *
+ * For simple skills (non-complex): writes SKILL.md only.
+ * For DB-backed complex skills: writes SKILL.md plus bundled files.
+ * Skips legacy complex skills with no files (handled by npx in entrypoint).
+ * Binary files are skipped.
+ * Stale swarm-managed skill directories are cleaned up.
+ */
+export function writeSkillsToFilesystem(
+  entries: SkillFsEntry[],
+  harnessType: "claude" | "pi" | "codex" | "all" = "all",
+  home: string,
+): SkillSyncResult {
+  const errors: string[] = [];
+  let synced = 0;
+  let removed = 0;
+
+  // Directories to write to
+  const skillDirs: string[] = [];
+  if (harnessType === "claude" || harnessType === "all") {
+    skillDirs.push(join(home, ".claude", "skills"));
+  }
+  if (harnessType === "pi" || harnessType === "all") {
+    skillDirs.push(join(home, ".pi", "agent", "skills"));
+  }
+  if (harnessType === "codex" || harnessType === "all") {
+    skillDirs.push(join(home, ".codex", "skills"));
+  }
+
+  // Ensure base dirs exist
+  for (const dir of skillDirs) {
+    mkdirSync(dir, { recursive: true });
+  }
+
+  // Track which skill names we write (for cleanup)
+  const writtenNames = new Set<string>();
+
+  for (const skill of entries) {
+    if (!skill.isActive || !skill.isEnabled) continue;
+    if (skill.isComplex && skill.files.length === 0) continue; // Legacy complex skills handled by npx
+    if (!skill.content) continue;
+
+    // Sanitize skill name to prevent path traversal (strip /, .., and non-safe chars)
+    const safeName = skill.name.replace(/[^a-zA-Z0-9_-]/g, "_");
+    if (!safeName) continue;
+
+    writtenNames.add(safeName);
+    const currentBundledFilePaths = new Set(
+      skill.files.filter((file) => !file.isBinary).map((file) => file.path),
+    );
+
+    for (const baseDir of skillDirs) {
+      const skillDir = join(baseDir, safeName);
+      const skillFile = join(skillDir, "SKILL.md");
+      const markerFile = join(skillDir, SWARM_MARKER_FILE);
+
+      try {
+        mkdirSync(skillDir, { recursive: true });
+        removed += reconcileManagedSkillFiles(skillDir, currentBundledFilePaths);
+        writeFileSync(skillFile, skill.content, "utf-8");
+        writeFileSync(markerFile, "", "utf-8");
+        synced++;
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : "Unknown error";
+        errors.push(`${skill.name} -> ${skillDir}: ${msg}`);
+        console.error(
+          `[skill-fs-writer] Failed to write SKILL.md for ${skill.name} to ${skillDir}: ${msg}`,
+        );
+      }
+
+      for (const file of skill.files) {
+        if (file.isBinary) {
+          console.log(`[skill-fs-writer] Skipping binary skill file ${skill.name}/${file.path}`);
+          continue;
+        }
+
+        const targetPath = join(skillDir, file.path);
+        try {
+          mkdirSync(dirname(targetPath), { recursive: true });
+          writeFileSync(targetPath, file.content, "utf-8");
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : "Unknown error";
+          errors.push(`${skill.name}/${file.path} -> ${targetPath}: ${msg}`);
+          console.error(
+            `[skill-fs-writer] Failed to write bundled file ${skill.name}/${file.path} to ${targetPath}: ${msg}`,
+          );
+        }
+      }
+    }
+  }
+
+  // Cleanup: only remove directories WE previously created (marker file
+  // present). Leaves user-installed personal skills alone — important on
+  // local dev where ~/.codex/skills holds skills the user installed
+  // outside the swarm.
+  for (const baseDir of skillDirs) {
+    if (!existsSync(baseDir)) continue;
+
+    try {
+      const existing = readdirSync(baseDir, { withFileTypes: true });
+      for (const entry of existing) {
+        if (!entry.isDirectory()) continue;
+        if (writtenNames.has(entry.name)) continue;
+        const skillDir = join(baseDir, entry.name);
+        if (!existsSync(join(skillDir, SWARM_MARKER_FILE))) continue;
+        try {
+          rmSync(skillDir, { recursive: true, force: true });
+          removed++;
+        } catch {
+          // Non-fatal — skip cleanup errors
+        }
+      }
+    } catch {
+      // Non-fatal — skip if we can't read the directory
+    }
+  }
+
+  return { synced, removed, errors };
+}