@desplega.ai/agent-swarm 1.173.0 → 2.0.0

package/src/tools/create-page.ts

@@ -21,7 +21,8 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { authorizeAssetKeyWrite } from "@/be/asset-key-auth";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
-import { createPage, getPage, getPageBySlug, getPageVersions, updatePage } from "@/be/db";
+import { createPage, getPage, getPageBySlug, updatePage } from "@/be/db";
+import { getPageEditCounter } from "@/be/db/page-versions";
 import { snapshotPage } from "@/pages/version";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { AssetKeySchema, PageAuthModeSchema, PageContentTypeSchema } from "@/types";
@@ -45,17 +46,6 @@ function getAppBaseUrl(): string {
   return getAppUrl();
 }
 
-/**
- * Edit counter for a page — `MAX(page_versions.version) + 1`. Returned to
- * the agent as `version` so they have a monotonic "this page has been
- * edited N times" signal. Mirrors the value returned by
- * `PUT /api/pages/:id` (see src/http/pages.ts:pageEditCounter).
- */
-async function pageEditCounter(pageId: string): Promise<number> {
-  const versions = await getPageVersions(pageId);
-  return versions.length > 0 ? versions[0]!.version + 1 : 1;
-}
-
 export const registerCreatePageTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "create_page",
@@ -217,7 +207,7 @@ export const registerCreatePageTool = (server: McpServer) => {
 
       const apiUrl = `${getApiBaseUrl()}/p/${id}`;
       const appUrl = `${getAppBaseUrl()}/pages/${id}`;
-      const version = await pageEditCounter(id);
+      const version = await getPageEditCounter(id);
 
       return toolOk(`Page "${input.title}" saved (slug=${finalSlug}, version=${version}).`, {
         details: `API: ${apiUrl}\n  App: ${appUrl}`,

package/src/tools/model-catalog/index.ts

@@ -1,3 +1,4 @@
+import { openAICompatibleProviderIds } from "@desplega/model-catalog";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getAgentById } from "@/be/db";
@@ -86,7 +87,7 @@ export const registerModelCatalogOverlayUpsertTool = (server: McpServer) => {
           .string()
           .min(1)
           .describe(
-            "models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode.",
+            `models.dev provider id: anthropic, openai, openrouter, amazon-bedrock, opencode, ${openAICompatibleProviderIds().join(", ")}.`,
           ),
         modelId: z
           .string()

package/src/tools/register-chat-channel.ts

@@ -0,0 +1,139 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getWorkflow } from "@/be/db";
+import { CHAT_SDK_ADAPTER_NAMES } from "@/integrations/chat-sdk/config";
+import { errorMessage } from "@/integrations/chat-sdk/logger";
+import {
+  type ChatChannelMapping,
+  chatChannelKey,
+  deleteChatChannelMapping,
+  putChatChannelMapping,
+} from "@/integrations/chat-sdk/router";
+import { can } from "@/rbac";
+import {
+  createToolRegistrar,
+  type RequestInfo,
+  swarmToolOutputSchema,
+  toolErr,
+  toolOk,
+} from "@/tools/utils";
+
+async function canManageChatChannels(requestInfo: RequestInfo): Promise<boolean> {
+  const caller = requestInfo.agentId ? await getAgentById(requestInfo.agentId) : null;
+  return can({
+    principal: {
+      kind: "agent",
+      agentId: requestInfo.agentId ?? "",
+      isLead: caller?.isLead ?? false,
+    },
+    verb: "integration.chat.manage",
+    resource: { kind: "none" },
+    source: "mcp",
+  }).allow;
+}
+
+export const registerRegisterChatChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "register-chat-channel",
+    {
+      title: "Route a chat channel to an agent or workflow",
+      annotations: { idempotentHint: true },
+      description:
+        "Lead-only. Route every swarm-addressed message from one Chat SDK channel (a Telegram group, Slack channel, Discord channel or Teams chat) to a fixed agent or workflow instead of the lead. Give exactly one of agentId or workflowId. A swarm#<agentId> token in a message still wins over the mapping. Remove it with unregister-chat-channel.",
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        channelId: z
+          .string()
+          .min(1)
+          .describe("SDK channel id, such as telegram:-100123 or slack:C123 (prefix optional)."),
+        agentId: z.string().optional().describe("Agent that receives the channel's tasks."),
+        workflowId: z
+          .string()
+          .optional()
+          .describe("Workflow whose webhook trigger receives the channel's messages."),
+        name: z.string().max(200).optional().describe("Display name for the mapping."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        key: z.string().optional(),
+        mapping: z
+          .looseObject({
+            agentId: z.string().optional(),
+            workflowId: z.string().optional(),
+            name: z.string().optional(),
+            createdAt: z.string().optional(),
+          })
+          .optional(),
+      }),
+    },
+    async ({ adapter, channelId, agentId, workflowId, name }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      try {
+        if (!(await canManageChatChannels(requestInfo))) {
+          return toolErr("Permission denied. Only the lead can register a chat channel.", {
+            data,
+          });
+        }
+        if (Boolean(agentId) === Boolean(workflowId)) {
+          return toolErr("Give exactly one of agentId or workflowId.", { data });
+        }
+        if (agentId && !(await getAgentById(agentId))) {
+          return toolErr(`Agent ${agentId} not found.`, { data });
+        }
+        if (workflowId && !(await getWorkflow(workflowId))) {
+          return toolErr(`Workflow ${workflowId} not found.`, { data });
+        }
+        const mapping: ChatChannelMapping = {
+          ...(agentId ? { agentId } : {}),
+          ...(workflowId ? { workflowId } : {}),
+          ...(name ? { name } : {}),
+          createdAt: new Date().toISOString(),
+        };
+        const key = await putChatChannelMapping(adapter, channelId, mapping);
+        return toolOk(
+          `Registered chat channel ${key} -> ${workflowId ? `workflow ${workflowId}` : `agent ${agentId}`}.`,
+          { data: { ...data, key, mapping } },
+        );
+      } catch (error) {
+        return toolErr(errorMessage(error), { data });
+      }
+    },
+  );
+};
+
+export const registerUnregisterChatChannelTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "unregister-chat-channel",
+    {
+      title: "Remove a chat channel route",
+      annotations: { idempotentHint: true },
+      description:
+        "Lead-only. Remove the channel-to-agent or channel-to-workflow route that register-chat-channel stored. Messages from the channel go back to the default route (thread owner, then the lead).",
+      inputSchema: z.object({
+        adapter: z.enum(CHAT_SDK_ADAPTER_NAMES).describe("Chat SDK adapter name."),
+        channelId: z.string().min(1).describe("SDK channel id (prefix optional)."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        yourAgentId: z.string().optional(),
+        key: z.string().optional(),
+      }),
+    },
+    async ({ adapter, channelId }, requestInfo) => {
+      const data = { yourAgentId: requestInfo.agentId };
+      try {
+        if (!(await canManageChatChannels(requestInfo))) {
+          return toolErr("Permission denied. Only the lead can unregister a chat channel.", {
+            data,
+          });
+        }
+        const key = chatChannelKey(adapter, channelId);
+        const deleted = await deleteChatChannelMapping(adapter, channelId);
+        return deleted
+          ? toolOk(`Unregistered chat channel ${key}.`, { data: { ...data, key } })
+          : toolErr(`No mapping found for chat channel ${key}.`, { data: { ...data, key } });
+      } catch (error) {
+        return toolErr(errorMessage(error), { data });
+      }
+    },
+  );
+};

package/src/tools/send-task.ts

@@ -378,6 +378,30 @@ export async function sendTaskHandler(
   const effectiveParentTask = effectiveParentTaskId
     ? await getTaskById(effectiveParentTaskId)
     : null;
+  // The child inherits the parent's contextKey (its Slack or chat thread) and requester, and
+  // thread-scoped tools trust that binding. An agent can only build on a parent it owns or
+  // created; otherwise a worker could mint access to a foreign thread.
+  if (ctx.kind === "owner" && creatorAgentId && effectiveParentTask) {
+    const caller = await getAgentById(creatorAgentId);
+    const decision = can({
+      principal: { kind: "agent", agentId: creatorAgentId, isLead: caller?.isLead ?? false },
+      verb: "task.parent.attach",
+      resource: {
+        kind: "task",
+        taskId: effectiveParentTask.id,
+        requestedByUserId: effectiveParentTask.requestedByUserId,
+        creatorAgentId: effectiveParentTask.creatorAgentId,
+        agentId: effectiveParentTask.agentId,
+      },
+      source: "mcp",
+    });
+    if (!decision.allow) {
+      return toolErr(
+        `You don't have context for parent task ${effectiveParentTask.id}. Only its assignee, its creator, or a lead can create a child task under it.`,
+        { data: { yourAgentId: creatorAgentId } },
+      );
+    }
+  }
   if (effectiveParentTask?.routingAffinityInvalid) {
     return toolErr("Cannot continue a task with an invalid routing affinity.", {
       data: { yourAgentId: creatorAgentId },

package/src/tools/skills/skill-get.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getSkillById, getSkillByName } from "@/be/db";
+import { resolveSwarmSkillByName } from "@/be/db/skill-name-resolution";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerSkillGetTool = (server: McpServer) => {
@@ -10,7 +11,7 @@ export const registerSkillGetTool = (server: McpServer) => {
       title: "Get Skill",
       annotations: { destructiveHint: false },
       description:
-        "Get full skill content by ID or name. Name resolution checks agent scope first, then swarm, then global.",
+        "Get full skill content by ID or name. Name resolution checks agent scope first, then swarm, then global. In swarm scope the ownerless skill wins, then your own, then the only agent-owned one; when several other agents own that name, it errors with their IDs: pass skillId instead.",
       inputSchema: z.object({
         skillId: z.string().optional().describe("Skill ID"),
         name: z.string().optional().describe("Skill name (resolved with precedence)"),
@@ -29,15 +30,22 @@ export const registerSkillGetTool = (server: McpServer) => {
 
       if (args.skillId) {
         skill = await getSkillById(args.skillId);
-      } else if (args.name && requestInfo.agentId) {
-        // Precedence: agent (personal) → swarm → global
-        skill =
-          (await getSkillByName(args.name, "agent", requestInfo.agentId)) ||
-          (await getSkillByName(args.name, "swarm")) ||
-          (await getSkillByName(args.name, "global"));
       } else if (args.name) {
-        skill =
-          (await getSkillByName(args.name, "swarm")) || (await getSkillByName(args.name, "global"));
+        // Precedence: agent (personal) → swarm → global
+        if (requestInfo.agentId) {
+          skill = await getSkillByName(args.name, "agent", requestInfo.agentId);
+        }
+        if (!skill) {
+          const swarm = await resolveSwarmSkillByName(args.name, requestInfo.agentId);
+          if (swarm.kind === "ambiguous") {
+            return toolErr(
+              `Skill name "${args.name}" matches ${swarm.skillIds.length} swarm skills owned by other agents: ${swarm.skillIds.join(", ")}. Call skill-get with skillId instead.`,
+              { data: { yourAgentId: requestInfo.agentId } },
+            );
+          }
+          if (swarm.kind === "found") skill = await getSkillById(swarm.skillId);
+        }
+        if (!skill) skill = await getSkillByName(args.name, "global");
       }
 
       if (!skill) {

package/src/tools/swarm-config/get-config.ts

@@ -19,6 +19,7 @@ const configEntryShape = z.looseObject({
   createdAt: z.string().optional(),
   lastUpdatedAt: z.string().optional(),
   encrypted: z.boolean().optional(),
+  exportToEnv: z.boolean().optional(),
 });
 
 export const registerGetConfigTool = (server: McpServer) => {
@@ -110,7 +111,7 @@ export const registerGetConfigTool = (server: McpServer) => {
             : result
                 .map(
                   (c) =>
-                    `- ${c.key}=${c.isSecret && !effectiveIncludeSecrets ? "********" : c.value} (scope: ${c.scope}${c.scopeId ? `, scopeId: ${c.scopeId}` : ""})`,
+                    `- ${c.key}=${c.isSecret && !effectiveIncludeSecrets ? "********" : c.value} (scope: ${c.scope}${c.scopeId ? `, scopeId: ${c.scopeId}` : ""}${c.exportToEnv ? "" : ", not in agent env"})`,
                 )
                 .join("\n");
 

package/src/tools/swarm-config/list-config.ts

@@ -19,6 +19,7 @@ const configEntryShape = z.looseObject({
   createdAt: z.string().optional(),
   lastUpdatedAt: z.string().optional(),
   encrypted: z.boolean().optional(),
+  exportToEnv: z.boolean().optional(),
 });
 
 export const registerListConfigTool = (server: McpServer) => {
@@ -102,7 +103,7 @@ export const registerListConfigTool = (server: McpServer) => {
             : result
                 .map(
                   (c) =>
-                    `- [${c.scope}${c.scopeId ? `:${c.scopeId}` : ""}] ${c.key}=${c.isSecret && !effectiveIncludeSecrets ? "********" : c.value}${c.description ? ` — ${c.description}` : ""}`,
+                    `- [${c.scope}${c.scopeId ? `:${c.scopeId}` : ""}] ${c.key}=${c.isSecret && !effectiveIncludeSecrets ? "********" : c.value}${c.exportToEnv ? "" : " [not in agent env]"}${c.description ? ` — ${c.description}` : ""}`,
                 )
                 .join("\n");
 

package/src/tools/swarm-config/set-config.ts

@@ -8,6 +8,7 @@ import {
   isReservedConfigKey,
   reservedKeyError,
   validateConfigValue,
+  validateExportToEnv,
 } from "@/be/swarm-config-guard";
 import { scheduleIntegrationsReload } from "@/http/core";
 import { can } from "@/rbac";
@@ -26,6 +27,7 @@ const configEntryShape = z.looseObject({
   createdAt: z.string().optional(),
   lastUpdatedAt: z.string().optional(),
   encrypted: z.boolean().optional(),
+  exportToEnv: z.boolean().optional(),
 });
 
 export const registerSetConfigTool = (server: McpServer) => {
@@ -34,7 +36,7 @@ export const registerSetConfigTool = (server: McpServer) => {
     {
       title: "Set Config",
       description:
-        "Set or update a swarm configuration value. Upserts by (scope, scopeId, key). Use scope='global' for server-wide settings, 'agent' for agent-specific, or 'repo' for repo-specific. Set isSecret=true to mask the value in API responses.",
+        "Set or update a swarm configuration value. Upserts by (scope, scopeId, key). Use scope='global' for server-wide settings, 'agent' for agent-specific, or 'repo' for repo-specific. Set isSecret=true to mask the value in API responses. Set exportToEnv=false to keep the row out of agent process env (agents then reach it through a connection or script credential binding).",
       annotations: { idempotentHint: true },
 
       inputSchema: z.object({
@@ -63,13 +65,22 @@ export const registerSetConfigTool = (server: McpServer) => {
           .string()
           .optional()
           .describe("Optional human-readable description of this config entry."),
+        exportToEnv: z
+          .boolean()
+          .optional()
+          .describe(
+            "Export this row into agent process env (default true on create, false for a few server-side secrets; omitted on update keeps the stored flag). Rejected as true for keys only the API server reads.",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
         config: configEntryShape.optional(),
       }),
     },
-    async ({ scope, scopeId, key, value, isSecret, envPath, description }, requestInfo) => {
+    async (
+      { scope, scopeId, key, value, isSecret, envPath, description, exportToEnv },
+      requestInfo,
+    ) => {
       if (!requestInfo.agentId) {
         return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
       }
@@ -114,7 +125,8 @@ export const registerSetConfigTool = (server: McpServer) => {
           });
         }
 
-        const validationError = validateConfigValue(key, value);
+        const validationError =
+          validateConfigValue(key, value) ?? validateExportToEnv(key, exportToEnv);
         if (validationError) {
           return toolErr(validationError, { data: { yourAgentId: requestInfo.agentId } });
         }
@@ -127,6 +139,7 @@ export const registerSetConfigTool = (server: McpServer) => {
           isSecret,
           envPath,
           description,
+          exportToEnv,
         });
 
         if (scope === "global") {

package/src/tools/tool-config.ts

@@ -72,12 +72,6 @@ export const DEFERRED_TOOLS = new Set([
   "retry-workflow-run",
   "cancel-workflow-run",
 
-  // Services (4)
-  "register-service",
-  "unregister-service",
-  "list-services",
-  "update-service-status",
-
   // Config (7)
   "set-config",
   "list-config",
@@ -127,6 +121,14 @@ export const DEFERRED_TOOLS = new Set([
   "send-whatsapp-message",
   "reply-whatsapp-message",
 
+  // Chat SDK (6)
+  "chat-reply",
+  "chat-post",
+  "chat-open-dm",
+  "chat-read-thread",
+  "register-chat-channel",
+  "unregister-chat-channel",
+
   // Tracker (7)
   "tracker-status",
   "get-oauth-access-token",

package/src/types.ts

@@ -391,6 +391,7 @@ export const AgentTaskSourceSchema = z.enum([
   "linear",
   "jira",
   "comb",
+  "chat",
 ]);
 export type AgentTaskSource = z.infer<typeof AgentTaskSourceSchema>;
 
@@ -446,7 +447,7 @@ export const SteeringStatusSchema = z.enum([
 ]);
 export type SteeringStatus = z.infer<typeof SteeringStatusSchema>;
 
-export const SteeringSourceSchema = z.enum(["ui", "mcp", "script", "slack", "api"]);
+export const SteeringSourceSchema = z.enum(["ui", "mcp", "script", "slack", "api", "chat"]);
 export type SteeringSource = z.infer<typeof SteeringSourceSchema>;
 
 export const SteeringMessageSchema = z
@@ -681,6 +682,10 @@ export const AgentTaskSchema = z
     resolvedModel: z.string().optional(),
     modelSource: z.string().optional(),
     modelAlias: z.string().optional(),
+    // The effort the session ran at (task effort, else the agent's
+    // REASONING_EFFORT_OVERRIDE, dropped when the harness/model cannot take
+    // it). Reported at session start; unset when the harness default applied.
+    resolvedEffort: ReasoningEffortSchema.optional(),
 
     // Schedule linking (optional — set when task was created by a schedule).
     // z.string(): also reachable verbatim from the create-task query param.
@@ -1458,7 +1463,7 @@ export type ChannelType = z.infer<typeof ChannelTypeSchema>;
 export type Channel = z.infer<typeof ChannelSchema>;
 export type ChannelMessage = z.infer<typeof ChannelMessageSchema>;
 
-// Service Types (for PM2/background services)
+// Service Types (removed PM2 service registry; kept with the services table)
 export const ServiceStatusSchema = z.enum(["starting", "healthy", "unhealthy", "stopped"]);
 
 export const ServiceSchema = z
@@ -1834,6 +1839,10 @@ export const SwarmConfigSchema = z
     // auto-encrypted during initDb; if that fails, boot aborts before normal API
     // reads occur.
     encrypted: z.boolean(),
+    // Whether workers export this row into agent process env. False keeps it
+    // server-side (connections, script credential bindings). Always false for
+    // keys only the API server reads (src/utils/config-env-export.ts).
+    exportToEnv: z.boolean(),
   })
   .openapi("SwarmConfig");
 
@@ -2625,6 +2634,7 @@ export type AgentTaskSummary = Pick<
   | "modelSource"
   | "modelAlias"
   | "effort"
+  | "resolvedEffort"
   | "provider"
   | "requestedByUserId"
   | "progress"

package/src/utils/config-env-export.ts

@@ -0,0 +1,74 @@
+/**
+ * Whether a swarm_config row reaches an agent's process environment.
+ *
+ * Each row carries an `exportToEnv` flag (migration 215). Workers export a row
+ * into the harness env, and so into `env`, `printenv` and `/proc/<pid>/environ`
+ * of every agent shell, only when the flag is true. Rows with the flag off stay
+ * server-side: agents use them through a connection or a script credential
+ * binding instead.
+ *
+ * Keys below are read only by the API server (integration signing secrets, app
+ * private keys, OAuth client secrets, the API's own agent-fs key). They can
+ * never be exported: the config API rejects `exportToEnv: true` for them and
+ * every reader treats a stored true as false.
+ */
+export const ENV_EXPORT_RESTRICTED_KEYS: ReadonlySet<string> = new Set([
+  "SLACK_APP_TOKEN",
+  "SLACK_SIGNING_SECRET",
+  "GITHUB_APP_PRIVATE_KEY",
+  "GITHUB_WEBHOOK_SECRET",
+  "GITLAB_WEBHOOK_SECRET",
+  "LINEAR_CLIENT_SECRET",
+  "LINEAR_SIGNING_SECRET",
+  "JIRA_CLIENT_SECRET",
+  "JIRA_WEBHOOK_TOKEN",
+  "AZURE_DEVOPS_WEBHOOK_SECRET",
+  "AGENTMAIL_WEBHOOK_SECRET",
+  "API_AGENT_FS_API_KEY",
+]);
+
+/**
+ * Server-side secrets an operator may still export per row. A new row for one
+ * of these keys starts with the flag off unless the caller sends
+ * `exportToEnv: true`. Migration 215 applies the same default to rows that
+ * already existed.
+ */
+export const ENV_EXPORT_DEFAULT_OFF_KEYS: ReadonlySet<string> = new Set([
+  "KAPSO_WEBHOOK_HMAC_SECRET",
+  "SENTRY_TEST_APP_WEBHOOK_SECRET",
+  "TELEMETRY_CH_AUTH",
+  "HACK_AGENT_FS_ADMIN_KEY",
+  "X_CLIENT_SECRET",
+]);
+
+/** Script connection secrets (`connection.<slug>.secret`) are brokered server-side. */
+const CONNECTION_SECRET_KEY = /^connection\..+\.secret$/;
+
+/**
+ * Key prefixes whose rows start with the flag off: the API server reads them
+ * (Chat SDK bot tokens and adapter JSON), agents never need them in a shell.
+ */
+const ENV_EXPORT_DEFAULT_OFF_PREFIXES = ["CHAT_SDK_"];
+
+export function isEnvExportRestrictedKey(key: string): boolean {
+  return ENV_EXPORT_RESTRICTED_KEYS.has(key.toUpperCase()) || CONNECTION_SECRET_KEY.test(key);
+}
+
+/** The flag a new row gets when the caller does not send one. */
+export function defaultExportToEnv(key: string): boolean {
+  const upper = key.toUpperCase();
+  return (
+    !isEnvExportRestrictedKey(key) &&
+    !ENV_EXPORT_DEFAULT_OFF_KEYS.has(upper) &&
+    !ENV_EXPORT_DEFAULT_OFF_PREFIXES.some((prefix) => upper.startsWith(prefix))
+  );
+}
+
+export function envExportRestrictedError(key: string): string {
+  return `Key '${key}' is read only by the API server and can never be exported to agent env; store it with exportToEnv: false.`;
+}
+
+/** The flag readers act on: a stored true never wins for a restricted key. */
+export function effectiveExportToEnv(key: string, stored: boolean): boolean {
+  return stored && !isEnvExportRestrictedKey(key);
+}

package/src/utils/credentials.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, it } from "bun:test";
+import { OPENAI_COMPATIBLE_PROVIDERS } from "@desplega/model-catalog";
 import {
   CREDENTIAL_POOL_VARS,
+  deriveProviderFromKeyType,
   getModelAwareCredentialVars,
   resolveCredentialPools,
   selectRandomCredential,
@@ -123,6 +125,35 @@ describe("resolveCredentialPools", () => {
     expect(["example-oauth1", "example-oauth2"]).toContain(env.CLAUDE_CODE_OAUTH_TOKEN!);
     expect(["example-apikey1", "example-apikey2"]).toContain(env.ANTHROPIC_API_KEY!);
   });
+
+  it("pools NAN_API_KEY alone for an opencode nan/* model", async () => {
+    const env: Record<string, string | undefined> = {
+      NAN_API_KEY: "example-nan-a,example-nan-b,example-nan-c",
+      OPENROUTER_API_KEY: "example-or-a,example-or-b",
+    };
+    const selections = await resolveCredentialPools(env, {
+      provider: "opencode",
+      model: "nan/glm5.3-flash",
+    });
+    expect(["example-nan-a", "example-nan-b", "example-nan-c"]).toContain(env.NAN_API_KEY!);
+    expect(selections).toHaveLength(1);
+    expect(selections[0]?.keyType).toBe("NAN_API_KEY");
+    expect(selections[0]?.total).toBe(3);
+    // OpenRouter is not relevant to a nan/* model and stays untouched.
+    expect(env.OPENROUTER_API_KEY).toBe("example-or-a,example-or-b");
+  });
+
+  it("pools HELMCODE_API_KEY alone for a pi helmcode/* model", async () => {
+    const env: Record<string, string | undefined> = {
+      HELMCODE_API_KEY: "example-helm-a,example-helm-b",
+    };
+    const selections = await resolveCredentialPools(env, {
+      provider: "pi",
+      model: "helmcode/glm5.3",
+    });
+    expect(["example-helm-a", "example-helm-b"]).toContain(env.HELMCODE_API_KEY!);
+    expect(selections.map((s) => s.keyType)).toEqual(["HELMCODE_API_KEY"]);
+  });
 });
 
 describe("validateClaudeCredentials", () => {
@@ -198,6 +229,23 @@ describe("CREDENTIAL_POOL_VARS", () => {
   it("contains expected env var names", () => {
     expect(CREDENTIAL_POOL_VARS).toContain("CLAUDE_CODE_OAUTH_TOKEN");
     expect(CREDENTIAL_POOL_VARS).toContain("ANTHROPIC_API_KEY");
+    expect(CREDENTIAL_POOL_VARS).toContain("NAN_API_KEY");
+    expect(CREDENTIAL_POOL_VARS).toContain("HELMCODE_API_KEY");
+  });
+
+  it("pools only the canonical NaN var; the alias is normalized by the runner", () => {
+    expect(OPENAI_COMPATIBLE_PROVIDERS.nan.aliasEnvVars).toEqual(["HELMCODE_API_NAN"]);
+    expect(CREDENTIAL_POOL_VARS as readonly string[]).not.toContain("HELMCODE_API_NAN");
+  });
+});
+
+describe("deriveProviderFromKeyType", () => {
+  it("tags NaN and Helmcode keys as pi, like OpenRouter", () => {
+    for (const keyType of ["NAN_API_KEY", "HELMCODE_API_NAN", "HELMCODE_API_KEY"]) {
+      expect(deriveProviderFromKeyType(keyType)).toBe("pi");
+    }
+    expect(deriveProviderFromKeyType("OPENROUTER_API_KEY")).toBe("pi");
+    expect(deriveProviderFromKeyType("SOMETHING_ELSE")).toBe("claude");
   });
 });
 
@@ -266,4 +314,48 @@ describe("getModelAwareCredentialVars", () => {
     const vars = getModelAwareCredentialVars("opencode", "anthropic/claude-sonnet-4-20250514");
     expect(vars).not.toContain("OPENAI_API_KEY");
   });
+
+  it("routes nan/* and helmcode/* to their own key on pi and opencode", () => {
+    for (const provider of ["pi", "opencode"]) {
+      expect(getModelAwareCredentialVars(provider, "nan/glm5.3-flash")).toEqual(["NAN_API_KEY"]);
+      expect(getModelAwareCredentialVars(provider, "helmcode/glm5.3")).toEqual([
+        "HELMCODE_API_KEY",
+      ]);
+      // Only the exact prefix routes: a look-alike is any other provider/model.
+      const other = getModelAwareCredentialVars(provider, "other/x");
+      expect(getModelAwareCredentialVars(provider, "helmcodex/x")).toEqual(other);
+      expect(getModelAwareCredentialVars(provider, "nanx/y")).toEqual(other);
+      expect(other).not.toContain("NAN_API_KEY");
+      expect(other).not.toContain("HELMCODE_API_KEY");
+    }
+  });
+
+  it("keeps OpenRouter and bare-id routing byte-identical", () => {
+    for (const provider of ["pi", "opencode"]) {
+      expect(
+        getModelAwareCredentialVars(provider, "openrouter/deepseek/deepseek-v4-flash"),
+      ).toEqual(["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY"]);
+      expect(getModelAwareCredentialVars(provider, "openai/gpt-5")).toEqual([
+        "OPENROUTER_API_KEY",
+        "ANTHROPIC_API_KEY",
+      ]);
+      expect(getModelAwareCredentialVars(provider, "gpt-4o")).toEqual([
+        "OPENROUTER_API_KEY",
+        "ANTHROPIC_API_KEY",
+        "OPENAI_API_KEY",
+      ]);
+      // A NaN model routed through OpenRouter is still an OpenRouter model.
+      expect(getModelAwareCredentialVars(provider, "openrouter/nan/glm5.3")).toEqual([
+        "OPENROUTER_API_KEY",
+        "ANTHROPIC_API_KEY",
+      ]);
+    }
+  });
+
+  it("does not apply the nan/helmcode prefix routing to other harnesses", () => {
+    expect(getModelAwareCredentialVars("claude", "nan/glm5.3")).toEqual([
+      "CLAUDE_CODE_OAUTH_TOKEN",
+      "ANTHROPIC_API_KEY",
+    ]);
+  });
 });