@desplega.ai/agent-swarm 1.61.0 → 1.63.0

package/README.md

@@ -49,7 +49,7 @@ Agent Swarm lets you run a team of AI coding agents that coordinate autonomously
 - **Templates registry** — Pre-built agent templates (9 official: lead, coder, researcher, reviewer, tester, FDE, content-writer, content-reviewer, content-strategist) with a gallery UI and docker-compose builder
 - **GitLab integration** — Full GitLab webhook support alongside GitHub via provider adapter pattern
 - **Working directory support** — Tasks can specify a custom starting directory for agents via the `dir` parameter
-- **Multi-provider** — Run agents with Claude Code or pi-mono (`HARNESS_PROVIDER=claude|pi`)
+- **Multi-provider** — Run agents with Claude Code, pi-mono, or OpenAI Codex (`HARNESS_PROVIDER=claude|pi|codex`)
 - **Agent-fs integration** — Persistent, searchable filesystem shared across the swarm with auto-registration on first boot
 - **Debug dashboard** — SQL query interface with Monaco editor and AG Grid results for database inspection
 - **Workflow engine** — DAG-based workflow automation with executor registry, checkpoint durability, webhook/schedule/manual triggers, per-step retry, structured I/O schemas, fan-out/convergence, configurable failure handling, and version history

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.61.0",
+    "version": "1.63.0",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -1677,6 +1677,71 @@
         }
       }
     },
+    "/api/keys/name": {
+      "patch": {
+        "summary": "Set or clear the human-friendly label on a pooled credential",
+        "tags": [
+          "API Keys"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "keyType": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "keySuffix": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 10
+                  },
+                  "name": {
+                    "type": [
+                      "string",
+                      "null"
+                    ],
+                    "maxLength": 60
+                  },
+                  "scope": {
+                    "type": "string"
+                  },
+                  "scopeId": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "keyType",
+                  "keySuffix",
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Name updated"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "401": {
+            "description": "Unauthorized"
+          },
+          "404": {
+            "description": "Key not found"
+          }
+        }
+      }
+    },
     "/api/events": {
       "post": {
         "summary": "Store a single event",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",
@@ -105,6 +105,7 @@
     "@mariozechner/pi-ai": "^0.57.1",
     "@mariozechner/pi-coding-agent": "^0.57.1",
     "@modelcontextprotocol/sdk": "^1.25.1",
+    "@openai/codex-sdk": "^0.118.0",
     "@openfort/openfort-node": "^0.9.1",
     "@slack/bolt": "^4.6.0",
     "@types/react": "^19.2.7",

package/src/be/db.ts

@@ -58,6 +58,7 @@ import type {
   WorkflowSnapshot,
   WorkflowVersion,
 } from "../types";
+import { deriveProviderFromKeyType } from "../utils/credentials";
 import { normalizeDate, normalizeDateRequired } from "./date-utils";
 import { runMigrations } from "./migrations/runner";
 import { seedDefaultTemplates } from "./seed";
@@ -7576,6 +7577,10 @@ export interface ApiKeyStatus {
   lastRateLimitAt: string | null;
   totalUsageCount: number;
   rateLimitCount: number;
+  /** Optional human-friendly label set from the dashboard. */
+  name: string | null;
+  /** Auto-derived harness provider (claude/pi/codex) — see deriveProviderFromKeyType. */
+  provider: string;
   createdAt: string;
   updatedAt: string;
 }
@@ -7634,17 +7639,21 @@ export function recordKeyUsage(
   const db = getDb();
   const effectiveScopeId = scopeId ?? "";
 
-  // Upsert key status record
+  // Upsert key status record. Sets `provider` on insert (auto-derived from
+  // keyType — see deriveProviderFromKeyType in src/utils/credentials.ts).
+  // The `name` column is left null on insert and only set via the
+  // setApiKeyName API endpoint when the user manually labels the key.
+  const provider = deriveProviderFromKeyType(keyType);
   db.prepare(
-    `INSERT INTO api_key_status (keyType, keySuffix, keyIndex, scope, scopeId, lastUsedAt, totalUsageCount, updatedAt)
-     VALUES (?, ?, ?, ?, ?, ?, 1, ?)
+    `INSERT INTO api_key_status (keyType, keySuffix, keyIndex, scope, scopeId, lastUsedAt, totalUsageCount, provider, updatedAt)
+     VALUES (?, ?, ?, ?, ?, ?, 1, ?, ?)
      ON CONFLICT(keyType, keySuffix, scope, scopeId)
      DO UPDATE SET
        lastUsedAt = excluded.lastUsedAt,
        totalUsageCount = totalUsageCount + 1,
        keyIndex = excluded.keyIndex,
        updatedAt = excluded.updatedAt`,
-  ).run(keyType, keySuffix, keyIndex, scope, effectiveScopeId, now, now);
+  ).run(keyType, keySuffix, keyIndex, scope, effectiveScopeId, now, provider, now);
 
   // Record which key was used on the task
   if (taskId) {
@@ -7667,10 +7676,11 @@ export function markKeyRateLimited(
 ): void {
   const now = new Date().toISOString();
   const effectiveScopeId = scopeId ?? "";
+  const provider = deriveProviderFromKeyType(keyType);
   getDb()
     .prepare(
-      `INSERT INTO api_key_status (keyType, keySuffix, keyIndex, scope, scopeId, status, rateLimitedUntil, lastRateLimitAt, rateLimitCount, updatedAt)
-       VALUES (?, ?, ?, ?, ?, 'rate_limited', ?, ?, 1, ?)
+      `INSERT INTO api_key_status (keyType, keySuffix, keyIndex, scope, scopeId, status, rateLimitedUntil, lastRateLimitAt, rateLimitCount, provider, updatedAt)
+       VALUES (?, ?, ?, ?, ?, 'rate_limited', ?, ?, 1, ?, ?)
        ON CONFLICT(keyType, keySuffix, scope, scopeId)
        DO UPDATE SET
          status = 'rate_limited',
@@ -7680,7 +7690,39 @@ export function markKeyRateLimited(
          keyIndex = excluded.keyIndex,
          updatedAt = excluded.updatedAt`,
     )
-    .run(keyType, keySuffix, keyIndex, scope, effectiveScopeId, rateLimitedUntil, now, now);
+    .run(
+      keyType,
+      keySuffix,
+      keyIndex,
+      scope,
+      effectiveScopeId,
+      rateLimitedUntil,
+      now,
+      provider,
+      now,
+    );
+}
+
+/**
+ * Set or clear the human-friendly `name` label on a pooled credential.
+ * Identified by the natural key (keyType + keySuffix + scope + scopeId).
+ * Returns true if a row was updated, false if no matching key exists.
+ */
+export function setApiKeyName(
+  keyType: string,
+  keySuffix: string,
+  name: string | null,
+  scope = "global",
+  scopeId: string | null = null,
+): boolean {
+  const result = getDb()
+    .prepare(
+      `UPDATE api_key_status
+       SET name = ?, updatedAt = ?
+       WHERE keyType = ? AND keySuffix = ? AND scope = ? AND scopeId = ?`,
+    )
+    .run(name, new Date().toISOString(), keyType, keySuffix, scope, scopeId ?? "");
+  return result.changes > 0;
 }
 
 /**

package/src/be/migrations/035_api_key_name_provider.sql

@@ -0,0 +1,22 @@
+-- Add user-facing `name` (manually settable from the dashboard) and
+-- automatic `provider` (claude/pi/codex, derived from keyType) columns to
+-- api_key_status. This lets users label their pooled credentials and lets
+-- the dashboard / runner group keys by harness without re-deriving the
+-- mapping at every read site.
+
+ALTER TABLE api_key_status ADD COLUMN name TEXT;
+ALTER TABLE api_key_status ADD COLUMN provider TEXT NOT NULL DEFAULT 'claude';
+
+-- Backfill provider for existing rows based on the keyType, mirroring the
+-- PROVIDER_CREDENTIAL_VARS mapping in src/utils/credentials.ts. ANTHROPIC_API_KEY
+-- is shared between claude and pi-mono — we default it to claude (the primary
+-- consumer) since the runner sets the provider on every subsequent usage.
+UPDATE api_key_status SET provider = 'claude'
+  WHERE keyType IN ('CLAUDE_CODE_OAUTH_TOKEN', 'ANTHROPIC_API_KEY');
+UPDATE api_key_status SET provider = 'pi'
+  WHERE keyType = 'OPENROUTER_API_KEY';
+UPDATE api_key_status SET provider = 'codex'
+  WHERE keyType = 'OPENAI_API_KEY';
+
+CREATE INDEX IF NOT EXISTS idx_api_key_status_provider
+  ON api_key_status(provider);

package/src/commands/runner.ts

@@ -232,7 +232,15 @@ async function fetchResolvedEnv(
     }
   }
 
-  const credentialSelections = await resolveCredentialPools(env, { apiUrl, apiKey });
+  const credentialSelections = await resolveCredentialPools(env, {
+    apiUrl,
+    apiKey,
+    // Provider-aware selection: codex tasks should not get a
+    // CLAUDE_CODE_OAUTH_TOKEN stamped on their task record (and vice
+    // versa) just because both env vars happen to be set in the worker
+    // container. See `PROVIDER_CREDENTIAL_VARS` in src/utils/credentials.ts.
+    provider: process.env.HARNESS_PROVIDER,
+  });
 
   return { env, credentialSelections };
 }

package/src/http/api-keys.ts

@@ -6,6 +6,7 @@ import {
   getKeyStatuses,
   markKeyRateLimited,
   recordKeyUsage,
+  setApiKeyName,
 } from "../be/db";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
@@ -110,6 +111,29 @@ const getCosts = route({
   auth: { apiKey: true },
 });
 
+const setKeyName = route({
+  method: "patch",
+  path: "/api/keys/name",
+  pattern: ["api", "keys", "name"],
+  summary: "Set or clear the human-friendly label on a pooled credential",
+  tags: ["API Keys"],
+  body: z.object({
+    keyType: z.string().min(1),
+    keySuffix: z.string().min(1).max(10),
+    /** Pass null or empty string to clear the existing label. */
+    name: z.string().max(60).nullable(),
+    scope: z.string().optional(),
+    scopeId: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Name updated" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+    404: { description: "Key not found" },
+  },
+  auth: { apiKey: true },
+});
+
 // ─── Handler ─────────────────────────────────────────────────────────────────
 
 export async function handleApiKeys(
@@ -196,5 +220,27 @@ export async function handleApiKeys(
     return true;
   }
 
+  // PATCH /api/keys/name
+  if (setKeyName.match(req.method, pathSegments)) {
+    const parsed = await setKeyName.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const { keyType, keySuffix, name, scope, scopeId } = parsed.body;
+    try {
+      // Empty string is treated as "clear the label" so the dashboard's
+      // contenteditable can submit "" without sending an explicit null.
+      const value = name === "" ? null : name;
+      const updated = setApiKeyName(keyType, keySuffix, value, scope, scopeId ?? null);
+      if (!updated) {
+        jsonError(res, `No key matching ${keyType} ...${keySuffix}`, 404);
+        return true;
+      }
+      json(res, { success: true, keyType, keySuffix, name: value });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to set key name", 500);
+    }
+    return true;
+  }
+
   return false;
 }

package/src/http/index.ts

@@ -154,6 +154,12 @@ async function shutdown() {
   // Stop Slack bot
   await stopSlackApp();
 
+  // Stop OAuth keepalive
+  if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
+    const { stopOAuthKeepalive } = await import("../oauth/keepalive");
+    stopOAuthKeepalive();
+  }
+
   // Close all active transports (SSE connections, etc.)
   for (const [id, transport] of Object.entries(transports)) {
     console.log(`[HTTP] Closing transport ${id}`);
@@ -242,6 +248,12 @@ httpServer
       const heartbeatMs = Number(process.env.HEARTBEAT_INTERVAL_MS) || 90000;
       startHeartbeat(heartbeatMs);
     }
+
+    // Start OAuth token keepalive (proactive refresh to prevent expiry)
+    if (process.env.OAUTH_KEEPALIVE_DISABLE !== "true") {
+      const { startOAuthKeepalive } = await import("../oauth/keepalive");
+      startOAuthKeepalive();
+    }
   })
   .on("error", (err) => {
     console.error("HTTP Server Error:", err);

package/src/http/mcp-servers.ts

@@ -174,14 +174,25 @@ export async function handleMcpServers(
         const resolvedEnv: Record<string, string> = {};
         const resolvedHeaders: Record<string, string> = {};
 
-        // Resolve env config keys (JSON object: {"ENV_VAR": "config-key-name"})
+        // Resolve env config keys
+        // Supports both array format ["KEY_A", "KEY_B"] (key = config key = element)
+        // and object format {"ENV_VAR": "config-key-name"}
         if (server.envConfigKeys) {
           try {
-            const mapping = JSON.parse(server.envConfigKeys) as Record<string, string>;
-            for (const [envVar, configKey] of Object.entries(mapping)) {
-              const value = configMap.get(configKey);
-              if (value !== undefined) {
-                resolvedEnv[envVar] = value;
+            const parsed = JSON.parse(server.envConfigKeys);
+            if (Array.isArray(parsed)) {
+              for (const key of parsed) {
+                const value = configMap.get(key);
+                if (value !== undefined) {
+                  resolvedEnv[key] = value;
+                }
+              }
+            } else {
+              for (const [envVar, configKey] of Object.entries(parsed as Record<string, string>)) {
+                const value = configMap.get(configKey);
+                if (value !== undefined) {
+                  resolvedEnv[envVar] = value;
+                }
               }
             }
           } catch {
@@ -189,14 +200,26 @@ export async function handleMcpServers(
           }
         }
 
-        // Resolve header config keys (JSON object: {"Header-Name": "config-key-name"})
+        // Resolve header config keys
+        // Supports both array format ["Header-A", "Header-B"] and object format {"Header-Name": "config-key-name"}
         if (server.headerConfigKeys) {
           try {
-            const mapping = JSON.parse(server.headerConfigKeys) as Record<string, string>;
-            for (const [headerName, configKey] of Object.entries(mapping)) {
-              const value = configMap.get(configKey);
-              if (value !== undefined) {
-                resolvedHeaders[headerName] = value;
+            const parsed = JSON.parse(server.headerConfigKeys);
+            if (Array.isArray(parsed)) {
+              for (const key of parsed) {
+                const value = configMap.get(key);
+                if (value !== undefined) {
+                  resolvedHeaders[key] = value;
+                }
+              }
+            } else {
+              for (const [headerName, configKey] of Object.entries(
+                parsed as Record<string, string>,
+              )) {
+                const value = configMap.get(configKey);
+                if (value !== undefined) {
+                  resolvedHeaders[headerName] = value;
+                }
               }
             }
           } catch {

package/src/oauth/ensure-token.ts

@@ -25,9 +25,13 @@ function getOAuthConfig(provider: string): OAuthProviderConfig | null {
  * Ensure a valid OAuth token exists for the given provider.
  * If the token is expiring soon, attempt to refresh it.
  * Call this before any API interaction with an OAuth-protected service.
+ *
+ * @param bufferMs - How far ahead to check for expiry. Default 5 min (reactive use).
+ *                   Keepalive callers should pass a larger value (e.g. 13h) to force
+ *                   a proactive refresh well before the token actually expires.
  */
-export async function ensureToken(provider: string): Promise<void> {
-  if (!isTokenExpiringSoon(provider)) return;
+export async function ensureToken(provider: string, bufferMs?: number): Promise<void> {
+  if (!isTokenExpiringSoon(provider, bufferMs)) return;
 
   const config = getOAuthConfig(provider);
   const tokens = getOAuthTokens(provider);

package/src/oauth/keepalive.ts

@@ -0,0 +1,76 @@
+import { ensureToken } from "./ensure-token";
+
+const TWELVE_HOURS_MS = 12 * 60 * 60 * 1000;
+const THIRTEEN_HOURS_MS = 13 * 60 * 60 * 1000;
+const SLACK_ALERTS_CHANNEL = process.env.SLACK_ALERTS_CHANNEL || "C08JCRURPBV";
+
+let keepaliveInterval: ReturnType<typeof setInterval> | null = null;
+
+/**
+ * Proactively refresh OAuth tokens on a schedule to prevent expiry.
+ * If refresh fails, posts a Slack notification so someone can re-auth manually.
+ */
+async function runKeepalive(): Promise<void> {
+  console.log("[OAuth Keepalive] Running scheduled token refresh for linear...");
+  try {
+    await ensureToken("linear", THIRTEEN_HOURS_MS);
+    console.log("[OAuth Keepalive] linear token check completed successfully");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`[OAuth Keepalive] Failed to refresh linear token: ${message}`);
+    await notifySlack(
+      `⚠️ *OAuth Keepalive Failed*\nProvider: \`linear\`\nError: ${message}\n\nManual re-authorization may be required.`,
+    );
+  }
+}
+
+async function notifySlack(text: string): Promise<void> {
+  try {
+    const { getSlackApp } = await import("../slack/app");
+    const app = getSlackApp();
+    if (!app) {
+      console.warn("[OAuth Keepalive] Slack not available, cannot send notification");
+      return;
+    }
+    await app.client.chat.postMessage({
+      channel: SLACK_ALERTS_CHANNEL,
+      text,
+    });
+    console.log("[OAuth Keepalive] Slack notification sent");
+  } catch (slackErr) {
+    console.error(
+      "[OAuth Keepalive] Failed to send Slack notification:",
+      slackErr instanceof Error ? slackErr.message : slackErr,
+    );
+  }
+}
+
+/**
+ * Start the OAuth keepalive timer. Runs immediately then every 12 hours.
+ */
+export function startOAuthKeepalive(): void {
+  if (keepaliveInterval) {
+    console.log("[OAuth Keepalive] Already running, skipping");
+    return;
+  }
+
+  console.log("[OAuth Keepalive] Starting (12h interval)");
+
+  // Run once after a short delay (let server finish startup)
+  setTimeout(() => runKeepalive(), 10_000);
+
+  keepaliveInterval = setInterval(() => {
+    runKeepalive();
+  }, TWELVE_HOURS_MS);
+}
+
+/**
+ * Stop the OAuth keepalive timer.
+ */
+export function stopOAuthKeepalive(): void {
+  if (keepaliveInterval) {
+    clearInterval(keepaliveInterval);
+    keepaliveInterval = null;
+    console.log("[OAuth Keepalive] Stopped");
+  }
+}