@desplega.ai/agent-swarm 1.80.0 → 1.80.1

package/src/be/scripts/typecheck.ts

@@ -0,0 +1,193 @@
+import ts from "typescript";
+
+export type ScriptTypecheckResult = { ok: true } | { ok: false; diagnostics: string[] };
+
+export const SCRIPT_SDK_TYPES = `
+export type JsonValue = null | boolean | number | string | JsonValue[] | { [key: string]: JsonValue };
+export type ScriptScope = "agent" | "global";
+export type ScriptFsMode = "none" | "workspace-rw";
+
+export interface Redacted<T> {
+  readonly __redactedBrand?: T;
+  toString(): "<redacted>";
+  toJSON(): "<redacted>";
+}
+
+export interface RedactedStatic {
+  value<T>(self: Redacted<T>): T;
+  meta<T>(self: Redacted<T>): { type: "system" | "user"; isSecret: boolean };
+  isSecret<T>(self: Redacted<T>): boolean;
+}
+
+export interface SwarmConfig {
+  apiKey: Redacted<string>;
+  agentId: Redacted<string>;
+  mcpBaseUrl: Redacted<string>;
+  get<T = string>(key: string): Redacted<T> | undefined;
+}
+
+export interface SwarmSdk {
+  memory_search(args: { query: string; scope?: "all" | "agent" | "swarm"; limit?: number; source?: string }): Promise<unknown>;
+  memory_get(args: { memoryId: string }): Promise<unknown>;
+  memory_rate(args: { id: string; useful: boolean; note?: string }): Promise<unknown>;
+  task_list(args?: Record<string, unknown>): Promise<unknown>;
+  task_get(args: { taskId: string }): Promise<unknown>;
+  task_storeProgress(args: Record<string, unknown>): Promise<unknown>;
+  kv_get(args: { key: string; namespace?: string }): Promise<unknown>;
+  kv_set(args: { key: string; value: unknown; namespace?: string; ttlSeconds?: number; valueType?: "string" | "json" | "integer" }): Promise<unknown>;
+  kv_del(args: { key: string; namespace?: string }): Promise<unknown>;
+  kv_incr(args: { key: string; by?: number; namespace?: string }): Promise<unknown>;
+  kv_list(args?: { prefix?: string; namespace?: string; limit?: number }): Promise<unknown>;
+  repo_list(args?: Record<string, unknown>): Promise<unknown>;
+  schedule_list(args?: Record<string, unknown>): Promise<unknown>;
+  script_search(args: { query?: string; scope?: ScriptScope; limit?: number }): Promise<unknown>;
+  script_run(args: { name?: string; source?: string; args?: unknown; intent?: string; scope?: ScriptScope; fsMode?: ScriptFsMode }): Promise<unknown>;
+}
+
+export interface ScriptStdlib {
+  fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+  fetchJson(input: string | URL | Request, init?: RequestInit): Promise<unknown>;
+  grep(pattern: string, files?: string | string[]): Promise<string>;
+  glob(pattern: string): Promise<string[]>;
+  table(rows: Array<Record<string, unknown>>): string;
+  Redacted: RedactedStatic;
+}
+
+export interface ScriptLogger extends Console {}
+
+export interface ScriptContext {
+  swarm: SwarmSdk & { config: SwarmConfig };
+  stdlib: ScriptStdlib;
+  logger: ScriptLogger;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: scripts may narrow their args type at the entrypoint.
+export type ScriptMain = (args: any, ctx: ScriptContext) => unknown | Promise<unknown>;
+`;
+
+export const SCRIPT_STDLIB_TYPES = `
+declare module "stdlib" {
+  export interface Redacted<T> {
+    readonly __redactedBrand?: T;
+    toString(): "<redacted>";
+    toJSON(): "<redacted>";
+  }
+  export const Redacted: {
+    value<T>(self: Redacted<T>): T;
+    meta<T>(self: Redacted<T>): { type: "system" | "user"; isSecret: boolean };
+    isSecret<T>(self: Redacted<T>): boolean;
+  };
+  export function fetch(input: string | URL | Request, init?: RequestInit): Promise<Response>;
+  export function fetchJson(input: string | URL | Request, init?: RequestInit): Promise<unknown>;
+  export function grep(pattern: string, files?: string | string[]): Promise<string>;
+  export function glob(pattern: string): Promise<string[]>;
+  export function table(rows: Array<Record<string, unknown>>): string;
+}
+
+declare module "swarm-sdk" {
+${SCRIPT_SDK_TYPES.replace(/^/gm, "  ")}
+}
+`;
+
+const USER_FILE = "/virtual/user-script.ts";
+const CHECK_FILE = "/virtual/check.ts";
+const SDK_FILE = "/virtual/swarm-sdk.d.ts";
+const STDLIB_FILE = "/virtual/stdlib.d.ts";
+
+function createCompilerHost(
+  files: Map<string, string>,
+  options: ts.CompilerOptions,
+): ts.CompilerHost {
+  const host = ts.createCompilerHost(options, true);
+  const originalGetSourceFile = host.getSourceFile.bind(host);
+
+  host.getSourceFile = (fileName, languageVersion, onError, shouldCreateNewSourceFile) => {
+    const normalized = fileName.replace(/\\/g, "/");
+    const source = files.get(normalized);
+    if (source !== undefined) {
+      return ts.createSourceFile(normalized, source, languageVersion, true, ts.ScriptKind.TS);
+    }
+    return originalGetSourceFile(fileName, languageVersion, onError, shouldCreateNewSourceFile);
+  };
+
+  host.fileExists = (fileName) => {
+    const normalized = fileName.replace(/\\/g, "/");
+    return files.has(normalized) || ts.sys.fileExists(fileName);
+  };
+
+  host.readFile = (fileName) => {
+    const normalized = fileName.replace(/\\/g, "/");
+    return files.get(normalized) ?? ts.sys.readFile(fileName);
+  };
+
+  host.resolveModuleNames = (moduleNames, containingFile) =>
+    moduleNames.map((moduleName) => {
+      if (moduleName === "./user-script") {
+        return { resolvedFileName: USER_FILE, extension: ts.Extension.Ts };
+      }
+      if (moduleName === "swarm-sdk") {
+        return { resolvedFileName: SDK_FILE, extension: ts.Extension.Dts };
+      }
+      if (moduleName === "stdlib") {
+        return { resolvedFileName: STDLIB_FILE, extension: ts.Extension.Dts };
+      }
+      return ts.resolveModuleName(moduleName, containingFile, options, host).resolvedModule;
+    });
+
+  // In compiled binary mode, TypeScript's lib .d.ts files live alongside
+  // typescript.js in /$bunfs/ — but .d.ts files are not embedded in the binary.
+  // Redirect lib lookups to TS_LIB_DIR where the Dockerfile copies real copies.
+  const tsLibDir = process.env.TS_LIB_DIR;
+  if (tsLibDir) {
+    host.getDefaultLibLocation = () => tsLibDir;
+  }
+
+  return host;
+}
+
+export function typecheckScript(source: string): ScriptTypecheckResult {
+  const options: ts.CompilerOptions = {
+    allowImportingTsExtensions: true,
+    module: ts.ModuleKind.ESNext,
+    moduleResolution: ts.ModuleResolutionKind.Bundler,
+    noEmit: true,
+    skipLibCheck: true,
+    strict: true,
+    target: ts.ScriptTarget.ES2022,
+    types: [],
+  };
+
+  const files = new Map<string, string>([
+    [USER_FILE, source],
+    [SDK_FILE, SCRIPT_SDK_TYPES],
+    [STDLIB_FILE, SCRIPT_STDLIB_TYPES],
+    [
+      CHECK_FILE,
+      `import run from "./user-script";
+import type { ScriptMain } from "swarm-sdk";
+const _scriptMain: ScriptMain = run;
+void _scriptMain;
+`,
+    ],
+  ]);
+
+  const host = createCompilerHost(files, options);
+  const program = ts.createProgram([USER_FILE, CHECK_FILE, SDK_FILE, STDLIB_FILE], options, host);
+  const diagnostics = [
+    ...program.getSyntacticDiagnostics(),
+    ...program.getSemanticDiagnostics(),
+  ].filter((diagnostic) => {
+    const fileName = diagnostic.file?.fileName.replace(/\\/g, "/");
+    return fileName === USER_FILE || fileName === CHECK_FILE;
+  });
+
+  if (diagnostics.length === 0) return { ok: true };
+
+  const formatted = ts.formatDiagnosticsWithColorAndContext(diagnostics, {
+    getCanonicalFileName: (fileName) => fileName,
+    getCurrentDirectory: () => "/virtual",
+    getNewLine: () => "\n",
+  });
+
+  return { ok: false, diagnostics: formatted.split("\n\n").filter(Boolean) };
+}

package/src/cli.tsx

@@ -9,6 +9,7 @@ import { runLead } from "./commands/lead.ts";
 import { Onboard } from "./commands/onboard.tsx";
 import { Setup as Connect } from "./commands/setup.tsx";
 import { runWorker } from "./commands/worker.ts";
+import { getApiKey, setApiKey } from "./utils/api-key.ts";
 
 // Get CLI name from bin field (assumes single key)
 const binName = Object.keys(pkg.bin)[0];
@@ -43,7 +44,7 @@ interface ParsedArgs {
 function parseArgs(args: string[]): ParsedArgs {
   const command = args[0] && !args[0].startsWith("-") ? args[0] : undefined;
   let port = process.env.PORT || "3013";
-  let key = process.env.API_KEY || "";
+  let key = getApiKey();
   let msg = "";
   let headless = false;
   let dryRun = false;
@@ -151,7 +152,7 @@ const COMMAND_HELP: Record<
   connect: {
     usage: `${binName} connect [options]`,
     description:
-      "Connect this project to an existing swarm.\nCreates .mcp.json and .claude/settings.local.json with server URL and API key.\nAuto-reads API_KEY from .env if present.",
+      "Connect this project to an existing swarm.\nCreates .mcp.json and .claude/settings.local.json with server URL and API key.\nAuto-reads AGENT_SWARM_API_KEY (or legacy API_KEY) from .env if present.",
     options: [
       "  --dry-run              Show what would be changed without writing",
       "  --restore              Restore files from .bak backups",
@@ -248,13 +249,19 @@ const COMMAND_HELP: Record<
     options: "  -h, --help             Show this help",
     examples: [`  ${binName} artifact serve`, `  ${binName} artifact help`].join("\n"),
   },
+  scripts: {
+    usage: `${binName} scripts reembed`,
+    description: "Maintenance commands for reusable swarm scripts.",
+    options: "  -h, --help             Show this help",
+    examples: `  ${binName} scripts reembed`,
+  },
   "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)",
+      "  --api-key <key>    Swarm API key (default: AGENT_SWARM_API_KEY or API_KEY, falling back to 123123)",
       "  -h, --help         Show this help",
     ].join("\n"),
     examples: [
@@ -269,7 +276,7 @@ const COMMAND_HELP: Record<
       "Bootstrap Anthropic Managed Agents for the swarm: create the cloud environment, upload plugin/commands/*.md skills, create the managed agent, and persist the resulting IDs to swarm_config so deployed workers restore them at boot. Prompts interactively for ANTHROPIC_API_KEY when not set in env. Idempotent — re-run with --force to recreate.",
     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)",
+      "  --api-key <key>    Swarm API key (default: AGENT_SWARM_API_KEY or API_KEY, falling back to 123123)",
       "  --force            Recreate Anthropic-side resources even if already configured",
       "  -h, --help         Show this help",
     ].join("\n"),
@@ -306,6 +313,7 @@ function printHelp(command?: string) {
     ["claude", "Run Claude CLI"],
     ["hook", "Handle Claude Code hook events (stdin)"],
     ["artifact", "Manage agent artifacts"],
+    ["scripts", "Reusable scripts maintenance"],
     ["docs", "Open documentation (--open to launch in browser)"],
     ["codex-login", "Authenticate Codex via ChatGPT OAuth"],
     ["claude-managed-setup", "Bootstrap Anthropic Managed Agents (agent + env + skills)"],
@@ -324,7 +332,7 @@ function McpServer({ port, apiKey, dbPath }: { port: string; apiKey: string; dbP
 
   useEffect(() => {
     process.env.PORT = port;
-    process.env.API_KEY = apiKey;
+    setApiKey(apiKey);
     if (dbPath) {
       process.env.DATABASE_PATH = dbPath;
     }
@@ -547,6 +555,15 @@ if (args.showHelp || args.command === "help" || args.command === undefined) {
     port: args.port,
     key: args.key,
   });
+} else if (args.command === "scripts") {
+  const scriptsArgs = process.argv.slice(process.argv.indexOf("scripts") + 1);
+  if (args.showHelp || scriptsArgs[0] !== "reembed") {
+    printHelp("scripts");
+    process.exit(scriptsArgs[0] === "reembed" || args.showHelp ? 0 : 1);
+  }
+  const { runScriptsMaintenanceCommand } = await import("./be/scripts/maintenance");
+  await runScriptsMaintenanceCommand(scriptsArgs);
+  console.log("Scripts re-embedded.");
 } else if (args.command === "codex-login") {
   const { runCodexLogin } = await import("./commands/codex-login");
   const codexLoginArgs = process.argv.slice(process.argv.indexOf("codex-login") + 1);

package/src/commands/artifact.ts

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { createArtifactServer } from "../artifact-sdk";
+import { getApiKey } from "../utils/api-key";
 
 interface ArtifactArgs {
   additionalArgs: string[];
@@ -137,7 +138,7 @@ async function artifactServe(args: ArtifactArgs) {
 }
 
 async function artifactList() {
-  const apiKey = process.env.API_KEY || "";
+  const apiKey = getApiKey();
   const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
   const agentId = process.env.AGENT_ID || "";
 
@@ -195,7 +196,7 @@ async function artifactStop(args: ArtifactArgs) {
     process.exit(1);
   }
 
-  const apiKey = process.env.API_KEY || "";
+  const apiKey = getApiKey();
   const mcpBaseUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
   const agentId = process.env.AGENT_ID || "";
 

package/src/commands/claude-managed-setup.ts

@@ -33,6 +33,7 @@ import type { BetaEnvironment } from "@anthropic-ai/sdk/resources/beta/environme
 import type { SkillCreateResponse } from "@anthropic-ai/sdk/resources/beta/skills";
 import { toFile } from "@anthropic-ai/sdk/uploads";
 
+import { getApiKey } from "../utils/api-key";
 import { promptHiddenInput } from "./codex-login.js";
 
 // ─── Types ───────────────────────────────────────────────────────────────────
@@ -397,7 +398,7 @@ export async function resolveClaudeManagedSetupConfig(
   const isInteractive = deps.isInteractive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
 
   const apiUrl = parsed.apiUrl ?? env.MCP_BASE_URL ?? "http://localhost:3013";
-  const apiKey = parsed.apiKey ?? env.API_KEY ?? "123123";
+  const apiKey = parsed.apiKey ?? (getApiKey(env) || "123123");
 
   let anthropicApiKey = env.ANTHROPIC_API_KEY ?? "";
   if (!anthropicApiKey && isInteractive) {

package/src/commands/codex-login.ts

@@ -14,6 +14,7 @@ import { emitKeypressEvents } from "node:readline";
 
 import { loginCodexOAuth } from "../providers/codex-oauth/flow.js";
 import { storeCodexOAuth } from "../providers/codex-oauth/storage.js";
+import { getApiKey } from "../utils/api-key";
 
 type PromptTextFn = (label: string, defaultValue: string) => Promise<string>;
 type PromptSecretFn = (label: string, defaultValue: string, helpText?: string) => Promise<string>;
@@ -146,7 +147,8 @@ export async function resolveCodexLoginConfig(
   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";
+  const envApiKey = getApiKey(env);
+  const defaultApiKey = envApiKey || "123123";
 
   let apiUrl = parsed.apiUrl ?? defaultApiUrl;
   let apiKey = parsed.apiKey ?? defaultApiKey;
@@ -156,8 +158,8 @@ export async function resolveCodexLoginConfig(
   }
 
   if (!parsed.apiKey && isInteractive) {
-    const apiKeyHelp = env.API_KEY
-      ? "Press Enter to use API_KEY from the environment"
+    const apiKeyHelp = envApiKey
+      ? "Press Enter to use AGENT_SWARM_API_KEY/API_KEY from the environment"
       : "Press Enter to use the default local API key";
     apiKey =
       (await promptSecret("Swarm API key", defaultApiKey, apiKeyHelp)).trim() || defaultApiKey;

package/src/commands/onboard.tsx

@@ -3,6 +3,7 @@ import { Select } from "@inkjs/ui";
 import { Box, Text, useApp, useInput } from "ink";
 import { useCallback, useEffect, useRef, useState } from "react";
 import pkg from "../../package.json";
+import { getApiKey } from "../utils/api-key.ts";
 import { getAgentSummary, getPresetById, PRESETS } from "./onboard/presets.ts";
 import { CoreCredentialsStep } from "./onboard/steps/core-credentials.tsx";
 import { CustomTemplatesStep } from "./onboard/steps/custom-templates.tsx";
@@ -140,7 +141,7 @@ export function Onboard({ dryRun = false, yes = false, preset }: OnboardProps) {
     }
 
     const credentialType = anthropicKey ? "api_key" : "oauth";
-    const apiKey = process.env.API_KEY || crypto.randomBytes(16).toString("hex");
+    const apiKey = getApiKey() || crypto.randomBytes(16).toString("hex");
 
     const agentIds: Record<string, string> = {};
     for (const svc of selectedPreset.services) {

package/src/commands/runner.ts

@@ -6,6 +6,7 @@ import {
   type Attributes,
   initOtel,
   injectTraceContext,
+  isPollTracingEnabled,
   type SwarmSpan,
   startSpan,
   withSpan,
@@ -31,6 +32,7 @@ import {
 } from "../providers/index.ts";
 import { initTelemetry, telemetry } from "../telemetry.ts";
 import type { ProviderName, RepoGuidelines } from "../types.ts";
+import { getApiKey } from "../utils/api-key.ts";
 import { computeBudgetBackoffMs } from "../utils/budget-backoff.ts";
 import { getContextWindowSize } from "../utils/context-window.ts";
 import { type CredentialSelection, resolveCredentialPools } from "../utils/credentials.ts";
@@ -412,6 +414,12 @@ const SWARM_TOOL_LABELS: Record<string, string | null> = {
   "list-services": "🔌 Listing services",
   "unregister-service": "🔌 Unregistering service",
   "update-service-status": "🔌 Updating service status",
+  // Reusable scripts
+  "script-search": "📜 Searching scripts",
+  "script-run": "📜 Running script",
+  "script-upsert": "📜 Saving script",
+  "script-delete": "📜 Deleting script",
+  "script-query-types": "📜 Reading script types",
 };
 
 /** Convert kebab-case to sentence case: "get-task-details" → "Get task details" */
@@ -487,13 +495,11 @@ export function toolCallToProgress(toolName: string, args: unknown): string | nu
       }
 
       // Pi-mono exposes tools from the built-in swarm MCP endpoint as bare
-      // names ("store-progress", "send-task", ...), not as mcp__ names.
+      // names ("store-progress", "send-task", "script-run", ...), not as mcp__ names.
       // Treat those names as agent-swarm tools so activity stays readable.
-      if (toolName.includes("-")) {
-        const label = SWARM_TOOL_LABELS[toolName];
-        if (label === null) return null;
-        if (label) return label;
-      }
+      const label = SWARM_TOOL_LABELS[toolName];
+      if (label === null) return null;
+      if (label) return label;
 
       return `🔧 ${toolName}`;
     }
@@ -1513,6 +1519,9 @@ async function registerAgent(opts: {
 
 /** Poll for triggers via HTTP API */
 async function pollForTrigger(opts: PollOptions): Promise<Trigger | null> {
+  if (!isPollTracingEnabled()) {
+    return pollForTriggerOnce(opts);
+  }
   return withSpan(
     "worker.poll",
     async (span) => {
@@ -1917,6 +1926,47 @@ function providerEventAttributes(event: ProviderEvent): Attributes {
   }
 }
 
+/**
+ * Entry shape for the `activeToolSpans` map maintained by `runWithSession`.
+ * Exported for unit tests that exercise `implicitCloseActiveToolSpans`.
+ */
+export type ActiveToolSpanEntry = {
+  span: SwarmSpan;
+  startedAt: number;
+};
+
+/**
+ * Closes any still-open tool spans (both `worker.tool` and `worker.mcp.tool`)
+ * in `activeToolSpans` at the assistant-message boundary, tagging them with
+ * `agentswarm.tool.implicit_close=true` and removing them from the map.
+ *
+ * The Claude SDK adapter doesn't emit per-tool completion events for any
+ * tool kind, MCP or harness-side — so the assistant-message boundary serves
+ * as an implicit `tool_end` for everything. Spans closed here are still
+ * successful (code 1, OK); the boundary is just a signal that the prior
+ * tool turn is done.
+ *
+ * Returns the number of spans closed (handy for tests / metrics).
+ */
+export function implicitCloseActiveToolSpans(
+  activeToolSpans: Map<string, ActiveToolSpanEntry>,
+  now: number = Date.now(),
+): number {
+  let closed = 0;
+  for (const [toolCallId, active] of activeToolSpans) {
+    active.span.setAttributes({
+      "agentswarm.tool.duration_ms": now - active.startedAt,
+      "agentswarm.tool.implicit_close": true,
+      "agentswarm.tool.call_id": toolCallId,
+    });
+    active.span.setStatus({ code: 1 });
+    active.span.end();
+    activeToolSpans.delete(toolCallId);
+    closed++;
+  }
+  return closed;
+}
+
 async function spawnProviderProcess(
   adapter: ReturnType<typeof createProviderAdapter>,
   opts: {
@@ -2155,6 +2205,18 @@ async function spawnProviderProcess(
             sessionId: event.sessionId,
           });
           break;
+        case "message": {
+          // Assistant-message boundary acts as an implicit tool_end for ALL
+          // still-open tool spans (both `worker.tool` and `worker.mcp.tool`).
+          // The Claude SDK adapter doesn't emit per-tool completion events for
+          // any tool kind, so without this their spans would only close at
+          // session shutdown via `closeActiveToolSpans` and report wall-clock
+          // duration from tool_start to session end.
+          if (event.role === "assistant") {
+            implicitCloseActiveToolSpans(activeToolSpans);
+          }
+          break;
+        }
         case "tool_start": {
           const tool = classifyTool(event.toolName, event.args);
           const toolSpan = startSpan(tool.kind === "mcp" ? "worker.mcp.tool" : "worker.tool", {
@@ -2772,7 +2834,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
 
   const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
   const swarmUrl = process.env.SWARM_URL || "localhost";
-  const apiKey = process.env.API_KEY || "";
+  const apiKey = getApiKey();
 
   // Resolve the boot harness provider from swarm_config (repo > agent > global,
   // overlaid on top of `process.env`). This is what selects the adapter for
@@ -2798,8 +2860,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   let adapter = createProviderAdapter(bootProvider);
 
   // Configure HTTP-based template resolution (workers resolve via API, not local DB)
-  if (process.env.API_KEY) {
-    configureHttpResolver(apiUrl, process.env.API_KEY);
+  if (apiKey) {
+    configureHttpResolver(apiUrl, apiKey);
   }
 
   // Initialize anonymized telemetry (opt-out via ANONYMIZED_TELEMETRY=false).
@@ -2810,7 +2872,7 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
   // skips telemetry instead of minting a fresh `install_<hex>` ID per
   // restart, which floods prod metrics with phantom installs.
   {
-    const telemetryApiKey = process.env.API_KEY;
+    const telemetryApiKey = apiKey || undefined;
     await initTelemetry(
       "worker",
       async (key) => {

package/src/commands/setup.tsx

@@ -2,6 +2,7 @@
 import { Spinner, TextInput } from "@inkjs/ui";
 import { Box, Text, useApp } from "ink";
 import { useCallback, useEffect, useRef, useState } from "react";
+import { getApiKey } from "../utils/api-key.ts";
 import {
   createDefaultMcpJson,
   createDefaultSettingsLocal,
@@ -47,7 +48,7 @@ export function Setup({ dryRun = false, restore = false, yes = false }: SetupPro
   const { exit } = useApp();
   const [state, setState] = useState<SetupState>({
     step: restore ? "restoring" : "check_dirs",
-    token: yes ? process.env.API_KEY || "" : "",
+    token: yes ? getApiKey() : "",
     agentId: yes ? process.env.AGENT_ID || "" : "",
     existingToken: "",
     existingAgentId: "",
@@ -258,14 +259,15 @@ export function Setup({ dryRun = false, restore = false, yes = false }: SetupPro
 
       // In non-interactive mode (yes=true), skip prompts and go directly to updating
       if (yes) {
-        const token = process.env.API_KEY;
+        const token = getApiKey();
         const agentId = process.env.AGENT_ID;
 
         if (!token) {
           setState((s) => ({
             ...s,
             step: "error",
-            error: "API_KEY environment variable is required in non-interactive mode (-y/--yes)",
+            error:
+              "AGENT_SWARM_API_KEY (or legacy API_KEY) environment variable is required in non-interactive mode (-y/--yes)",
           }));
           return;
         }

package/src/hooks/hook.ts

@@ -10,6 +10,7 @@ import {
   type RetrievalRow,
 } from "../be/memory/raters/llm";
 import type { Agent } from "../types";
+import { getApiKey } from "../utils/api-key";
 import { summarizeSession as runSummarize } from "../utils/internal-ai";
 import { checkToolLoop, clearToolHistory } from "./tool-loop-detection";
 
@@ -150,7 +151,7 @@ async function fetchTaskDetails(
   taskId: string,
 ): Promise<{ id: string; task: string; progress?: string } | null> {
   const apiUrl = process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
-  const apiKey = process.env.API_KEY || "";
+  const apiKey = getApiKey();
   const headers: Record<string, string> = {};
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
 
@@ -301,7 +302,7 @@ export async function runStopHookSessionSummary(
     const { taskContext, taskId } = await resolveStopHookTaskContext(env);
 
     const apiUrl = env.MCP_BASE_URL || `http://localhost:${env.PORT || "3013"}`;
-    const apiKey = env.API_KEY || "";
+    const apiKey = getApiKey(env);
 
     // Memory-rater v1.5 step-4: piggyback per-memory ratings on the
     // existing summary call when MEMORY_RATERS includes `llm`.
@@ -1152,7 +1153,7 @@ ${hasAgentIdHeader() ? `You have a pre-defined agent ID via header: ${mcpConfig?
           try {
             const apiUrl =
               process.env.MCP_BASE_URL || `http://localhost:${process.env.PORT || "3013"}`;
-            const apiKey = process.env.API_KEY || "";
+            const apiKey = getApiKey();
             const fileContent = await Bun.file(editedPath).text();
             const isShared = editedPath.startsWith("/workspace/shared/");
             const fileName = editedPath.split("/").pop() ?? "unnamed";