@desplega.ai/agent-swarm 1.62.0 → 1.63.1

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.62.0",
+    "version": "1.63.1",
     "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.62.0",
+  "version": "1.63.1",
   "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/cli.tsx

@@ -255,6 +255,21 @@ const COMMAND_HELP: Record<
     options: "  -h, --help             Show this help",
     examples: [`  ${binName} artifact serve`, `  ${binName} artifact help`].join("\n"),
   },
+  "codex-login": {
+    usage: `${binName} codex-login [options]`,
+    description:
+      "Authenticate Codex via ChatGPT OAuth (browser or manual paste).\nPrompts interactively for the target API URL and a best-effort masked API key, then stores credentials in the swarm API config store for deployed workers.",
+    options: [
+      "  --api-url <url>    Swarm API URL (default: MCP_BASE_URL or http://localhost:3013)",
+      "  --api-key <key>    Swarm API key (default: API_KEY or 123123)",
+      "  -h, --help         Show this help",
+    ].join("\n"),
+    examples: [
+      `  ${binName} codex-login`,
+      `  ${binName} codex-login --api-url https://swarm.example.com`,
+      `  ${binName} codex-login --api-url https://swarm.example.com --api-key <api-key>`,
+    ].join("\n"),
+  },
 };
 
 function printHelp(command?: string) {
@@ -283,6 +298,7 @@ function printHelp(command?: string) {
     ["hook", "Handle Claude Code hook events (stdin)"],
     ["artifact", "Manage agent artifacts"],
     ["docs", "Open documentation (--open to launch in browser)"],
+    ["codex-login", "Authenticate Codex via ChatGPT OAuth"],
     ["version", "Show version number"],
     ["help", "Show this help message"],
   ];
@@ -535,6 +551,10 @@ if (args.showHelp || args.command === "help" || args.command === undefined) {
     port: args.port,
     key: args.key,
   });
+} else if (args.command === "codex-login") {
+  const { runCodexLogin } = await import("./commands/codex-login");
+  const codexLoginArgs = process.argv.slice(process.argv.indexOf("codex-login") + 1);
+  await runCodexLogin(codexLoginArgs);
 } else {
   render(<App args={args} />);
 }

package/src/commands/codex-login.ts

@@ -0,0 +1,263 @@
+/**
+ * `agent-swarm codex-login` — authenticate Codex via ChatGPT OAuth.
+ *
+ * Runs the OAuth PKCE flow (browser redirect to localhost:1455, manual paste
+ * fallback), extracts chatgpt_account_id from the JWT, and stores the
+ * credentials in the swarm API config store at global scope.
+ *
+ * This is a non-UI command (plain stdout, no Ink) — it exits immediately
+ * after completing or failing the OAuth flow.
+ */
+
+import { exec } from "node:child_process";
+import { emitKeypressEvents } from "node:readline";
+
+import { loginCodexOAuth } from "../providers/codex-oauth/flow.js";
+import { storeCodexOAuth } from "../providers/codex-oauth/storage.js";
+
+type PromptTextFn = (label: string, defaultValue: string) => Promise<string>;
+type PromptSecretFn = (label: string, defaultValue: string, helpText?: string) => Promise<string>;
+
+type ResolveCodexLoginConfigDeps = {
+  env?: Record<string, string | undefined>;
+  isInteractive?: boolean;
+  promptText?: PromptTextFn;
+  promptSecret?: PromptSecretFn;
+};
+
+type RunCodexLoginDeps = {
+  resolveConfig?: typeof resolveCodexLoginConfig;
+  login?: typeof loginCodexOAuth;
+  store?: typeof storeCodexOAuth;
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+  exit?: (code: number) => void;
+};
+
+type ParsedCodexLoginArgs = {
+  apiUrl?: string;
+  apiKey?: string;
+  showHelp: boolean;
+};
+
+function parseCodexLoginArgs(args: string[]): ParsedCodexLoginArgs {
+  const parsed: ParsedCodexLoginArgs = { showHelp: false };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--api-url" && args[i + 1]) {
+      parsed.apiUrl = args[++i]!;
+    } else if (arg === "--api-key" && args[i + 1]) {
+      parsed.apiKey = args[++i]!;
+    } else if (arg === "--help" || arg === "-h") {
+      parsed.showHelp = true;
+    }
+  }
+
+  return parsed;
+}
+
+async function promptTextInput(label: string, defaultValue: string): Promise<string> {
+  const { createInterface } = await import("node:readline");
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  return new Promise<string>((resolve) => {
+    const suffix = defaultValue ? ` [${defaultValue}]` : "";
+    rl.question(`${label}${suffix}: `, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function promptHiddenInput(
+  label: string,
+  _defaultValue: string,
+  helpText?: string,
+): Promise<string> {
+  const stdin = process.stdin;
+  const stdout = process.stdout;
+
+  if (!stdin.isTTY || !stdout.isTTY || typeof stdin.setRawMode !== "function") {
+    return promptTextInput(label, "");
+  }
+
+  if (helpText) {
+    stdout.write(`${helpText}\n`);
+  }
+  stdout.write(`${label}: `);
+
+  emitKeypressEvents(stdin);
+  const wasRaw = stdin.isRaw;
+  stdin.setRawMode(true);
+  stdin.resume();
+
+  return new Promise<string>((resolve, reject) => {
+    let value = "";
+
+    const cleanup = () => {
+      stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+      stdin.removeListener("keypress", onKeypress);
+      stdout.write("\n");
+    };
+
+    const onKeypress = (str: string, key: { name?: string; ctrl?: boolean; meta?: boolean }) => {
+      if (key.ctrl && key.name === "c") {
+        cleanup();
+        reject(new Error("Aborted"));
+        return;
+      }
+
+      if (key.name === "return" || key.name === "enter") {
+        cleanup();
+        resolve(value.trim());
+        return;
+      }
+
+      if (key.name === "backspace") {
+        if (value.length > 0) {
+          value = value.slice(0, -1);
+          stdout.write("\b \b");
+        }
+        return;
+      }
+
+      if (!key.ctrl && !key.meta && str) {
+        value += str;
+        stdout.write("*");
+      }
+    };
+
+    stdin.on("keypress", onKeypress);
+  });
+}
+
+export async function resolveCodexLoginConfig(
+  args: string[],
+  deps: ResolveCodexLoginConfigDeps = {},
+): Promise<{ apiUrl: string; apiKey: string }> {
+  const env = deps.env ?? process.env;
+  const parsed = parseCodexLoginArgs(args);
+  const promptText = deps.promptText ?? promptTextInput;
+  const promptSecret = deps.promptSecret ?? promptHiddenInput;
+  const isInteractive = deps.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const defaultApiUrl = env.MCP_BASE_URL || "http://localhost:3013";
+  const defaultApiKey = env.API_KEY || "123123";
+
+  let apiUrl = parsed.apiUrl ?? defaultApiUrl;
+  let apiKey = parsed.apiKey ?? defaultApiKey;
+
+  if (!parsed.apiUrl && isInteractive) {
+    apiUrl = (await promptText("Swarm API URL", defaultApiUrl)).trim() || defaultApiUrl;
+  }
+
+  if (!parsed.apiKey && isInteractive) {
+    const apiKeyHelp = env.API_KEY
+      ? "Press Enter to use API_KEY from the environment"
+      : "Press Enter to use the default local API key";
+    apiKey =
+      (await promptSecret("Swarm API key", defaultApiKey, apiKeyHelp)).trim() || defaultApiKey;
+  }
+
+  return { apiUrl, apiKey };
+}
+
+function printHelp() {
+  console.log(`
+agent-swarm codex-login — Authenticate Codex via ChatGPT OAuth
+
+Usage:
+  agent-swarm codex-login [options]
+
+Options:
+  --api-url <url>    Swarm API URL (default: MCP_BASE_URL or http://localhost:3013)
+  --api-key <key>    Swarm API key (default: API_KEY or 123123)
+  -h, --help         Show this help
+
+Without flags, the command prompts interactively for the target API URL and
+for the swarm API key using masked input when the terminal supports it.
+
+This command runs the OpenAI Codex OAuth PKCE flow:
+  1. Opens a browser to ChatGPT login
+  2. Receives the authorization code via localhost:1455 callback
+  3. Exchanges the code for access/refresh tokens
+  4. Stores credentials in the swarm API config store
+
+Deployed Codex workers automatically restore these credentials at boot.
+`);
+}
+
+export async function runCodexLogin(args: string[], deps: RunCodexLoginDeps = {}): Promise<void> {
+  const resolveConfig = deps.resolveConfig ?? resolveCodexLoginConfig;
+  const login = deps.login ?? loginCodexOAuth;
+  const store = deps.store ?? storeCodexOAuth;
+  const log = deps.log ?? console.log;
+  const error = deps.error ?? console.error;
+  const exit = deps.exit ?? ((code: number) => process.exit(code));
+
+  if (parseCodexLoginArgs(args).showHelp) {
+    printHelp();
+    return;
+  }
+
+  let browserOpened = false;
+
+  try {
+    const { apiUrl, apiKey } = await resolveConfig(args);
+
+    log("Starting Codex ChatGPT OAuth login...\n");
+    log(`Target swarm API: ${apiUrl}\n`);
+
+    const creds = await login({
+      onAuth: ({ url, instructions }) => {
+        log(`Open this URL in your browser:\n\n  ${url}\n`);
+        if (instructions) {
+          log(instructions);
+        }
+        // Try to open the browser (fire-and-forget, non-fatal)
+        if (!browserOpened) {
+          browserOpened = true;
+          const cmd =
+            process.platform === "darwin"
+              ? "open"
+              : process.platform === "win32"
+                ? "start"
+                : "xdg-open";
+          exec(`${cmd} "${url}"`, (err) => {
+            if (err) {
+              log("(Could not open browser automatically)\n");
+            }
+          });
+        }
+      },
+      onPrompt: async ({ message }) => {
+        return promptTextInput(message, "");
+      },
+      onProgress: (message) => {
+        log(message);
+      },
+      onManualCodeInput: async () => {
+        return promptTextInput("Or paste the authorization code here", "");
+      },
+    });
+
+    log("\nOAuth flow completed successfully!");
+    log(`  Account ID: ${creds.accountId}`);
+    log(`  Expires: ${new Date(creds.expires).toISOString()}`);
+
+    // Store credentials in the swarm API config store
+    log("\nStoring credentials in swarm API config store...");
+    await store(apiUrl, apiKey, creds);
+    log("Credentials stored successfully!");
+
+    log("\nDeployed Codex workers will automatically restore these credentials at boot.");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    error(`\nError: ${message}`);
+    exit(1);
+  }
+}

package/src/commands/runner.ts

@@ -10,6 +10,7 @@ import {
   generateDefaultToolsMd,
 } from "../prompts/defaults.ts";
 import { configureHttpResolver, resolveTemplateAsync } from "../prompts/resolver.ts";
+import { authJsonToCredentialSelection } from "../providers/codex-oauth/auth-json.js";
 import {
   type CostData,
   createProviderAdapter,
@@ -17,6 +18,7 @@ import {
   type ProviderSession,
   type ProviderSessionConfig,
 } from "../providers/index.ts";
+import { initTelemetry, telemetry } from "../telemetry.ts";
 import type { RepoGuidelines } from "../types.ts";
 import { getContextWindowSize } from "../utils/context-window.ts";
 import { type CredentialSelection, resolveCredentialPools } from "../utils/credentials.ts";
@@ -232,7 +234,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 };
 }
@@ -626,6 +636,33 @@ async function reportKeyUsage(
   }
 }
 
+async function resolveCodexOAuthCredentialInfo(): Promise<CredentialSelection | null> {
+  try {
+    const home = process.env.HOME;
+    if (!home) return null;
+
+    const authFile = Bun.file(`${home}/.codex/auth.json`);
+    if (!(await authFile.exists())) {
+      return null;
+    }
+
+    const auth = JSON.parse(await authFile.text()) as {
+      auth_mode?: string;
+      tokens?: { account_id?: string };
+    };
+
+    if (auth.auth_mode !== "chatgpt" || !auth.tokens?.account_id) {
+      return null;
+    }
+
+    return authJsonToCredentialSelection(
+      auth as Parameters<typeof authJsonToCredentialSelection>[0],
+    );
+  } catch {
+    return null;
+  }
+}
+
 /** Report a rate-limited key to the API (fire-and-forget) */
 async function reportKeyRateLimit(
   apiUrl: string,
@@ -840,6 +877,7 @@ function setupShutdownHandlers(
     }
 
     if (apiConfig) {
+      telemetry.session("ended", { agentId: apiConfig.agentId });
       await closeAgent(apiConfig, role);
     }
     await savePm2State(role);
@@ -1559,6 +1597,20 @@ async function spawnProviderProcess(
 
   const session = await adapter.createSession(config);
 
+  let oauthSelection: CredentialSelection | undefined;
+  if (adapter.name === "codex" && credentialSelections.length === 0) {
+    oauthSelection = (await resolveCodexOAuthCredentialInfo()) ?? undefined;
+    if (oauthSelection && realTaskId) {
+      reportKeyUsage(
+        opts.apiUrl,
+        opts.apiKey,
+        oauthSelection.keyType,
+        oauthSelection,
+        realTaskId,
+      ).catch(() => {});
+    }
+  }
+
   // Set up log streaming
   const logBuffer: LogBuffer = { lines: [], lastFlush: Date.now(), partialLine: "" };
   const shouldStream = opts.apiUrl && opts.runnerSessionId && opts.iteration;
@@ -1866,7 +1918,7 @@ async function spawnProviderProcess(
   });
 
   // Build credential info for rate limit tracking
-  const primarySelection = credentialSelections[0];
+  const primarySelection = credentialSelections[0] ?? oauthSelection;
   const credentialInfo = primarySelection
     ? {
         keyType: primarySelection.keyType,
@@ -2000,7 +2052,7 @@ async function checkCompletedProcesses(
         console.log(`[${role}] Detected error for task ${taskId.slice(0, 8)}: ${failureReason}`);
 
         // If rate-limited and we know which key was used, report it
-        if (credentialInfo && /rate.?limit/i.test(failureReason)) {
+        if (credentialInfo && /rate.?limit|hit your limit/i.test(failureReason)) {
           // Try to extract reset time from the error message (e.g. "resets 3pm (UTC)")
           const parsedResetTime = parseRateLimitResetTime(failureReason);
           const defaultCooldownMs = 5 * 60 * 1000;
@@ -2154,6 +2206,46 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
     configureHttpResolver(apiUrl, process.env.API_KEY);
   }
 
+  // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false)
+  // Workers use HTTP-based config access (cannot import DB directly)
+  {
+    const telemetryApiKey = process.env.API_KEY;
+    await initTelemetry(
+      "worker",
+      async (key) => {
+        if (!telemetryApiKey) return undefined;
+        try {
+          const resp = await fetch(`${apiUrl}/api/config?scope=global&includeSecrets=true`, {
+            headers: { Authorization: `Bearer ${telemetryApiKey}` },
+            signal: AbortSignal.timeout(5_000),
+          });
+          if (!resp.ok) return undefined;
+          const data = (await resp.json()) as { configs: { key: string; value: string }[] };
+          return data.configs.find((c) => c.key === key)?.value;
+        } catch {
+          return undefined;
+        }
+      },
+      async (key, value) => {
+        if (!telemetryApiKey) return;
+        try {
+          await fetch(`${apiUrl}/api/config`, {
+            method: "PUT",
+            headers: {
+              Authorization: `Bearer ${telemetryApiKey}`,
+              "Content-Type": "application/json",
+            },
+            body: JSON.stringify({ scope: "global", key, value }),
+            signal: AbortSignal.timeout(5_000),
+          });
+        } catch {
+          // Silently ignore — telemetry is best-effort
+        }
+      },
+    );
+  }
+  telemetry.session("started", { agentId });
+
   let capabilities = config.capabilities;
 
   // Agent identity fields — populated after registration by fetching full profile