@desplega.ai/agent-swarm 2.5.4 → 2.7.0

package/src/tools/get-tasks.ts

@@ -50,6 +50,11 @@ export const getTasksInputSchema = z.object({
     .uuid()
     .optional()
     .describe("Filter by schedule ID to find tasks created by a specific schedule."),
+  workflowRunId: z
+    .string()
+    .uuid()
+    .optional()
+    .describe("Filter by workflow run ID to find the tasks of a single run."),
   key: AssetKeySchema.optional().describe("Filter by exact logical namespace."),
   keyPrefix: AssetKeySchema.optional().describe("Filter by namespace subtree."),
   includeHeartbeat: z
@@ -130,6 +135,7 @@ export async function getTasksHandler(
     tags,
     search,
     scheduleId,
+    workflowRunId,
     key,
     keyPrefix,
     includeHeartbeat,
@@ -151,6 +157,7 @@ export async function getTasksHandler(
     tags,
     search,
     scheduleId,
+    workflowRunId,
     key,
     keyPrefix,
     includeHeartbeat,
@@ -192,6 +199,7 @@ export async function getTasksHandler(
   if (tags?.length) filters.push(`tags=[${tags.join(", ")}]`);
   if (search) filters.push(`search='${search}'`);
   if (scheduleId) filters.push(`scheduleId='${scheduleId}'`);
+  if (workflowRunId) filters.push(`workflowRunId='${workflowRunId}'`);
   if (key) filters.push(`key='${key}'`);
   if (keyPrefix) filters.push(`keyPrefix='${keyPrefix}'`);
 

package/src/tools/kv/kv-read-auth.ts

@@ -1,13 +1,15 @@
 import { mcpOverflowAuthError } from "@/kv-overflow";
+import { privateNamespaceError } from "@/kv-reserved-namespaces";
 
 /**
  * Ordinary KV namespaces intentionally remain readable across agents. MCP
  * overflow is different: it contains tool-result business data and is private
- * to the authenticated agent whose finalizer created the spill.
+ * to the authenticated agent whose finalizer created the spill. Private
+ * reserved families (`session-labels`) are not readable here at all.
  */
 export function kvReadAuthError(
   namespace: string,
   info: { agentId: string | undefined },
 ): string | null {
-  return mcpOverflowAuthError(namespace, info.agentId);
+  return privateNamespaceError(namespace) ?? mcpOverflowAuthError(namespace, info.agentId);
 }

package/src/tools/script-common.ts

@@ -16,6 +16,7 @@ export const SCRIPT_TRANSPORT_ERROR =
 export const scriptNameSchema = z.string().min(1).max(200);
 export const scriptScopeSchema = z.enum(["agent", "global"]);
 export const scriptFsModeSchema = z.enum(["none", "workspace-rw"]);
+export const scriptExecutorSchema = z.enum(["native", "quickjs"]);
 
 export const scriptToolOutputSchema = swarmToolOutputSchema({
   status: z.number().optional(),

package/src/tools/script-run.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -66,6 +67,12 @@ export const registerScriptRunTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional executor override ("native" or "quickjs"). When omitted, named scripts use their saved executor or SCRIPT_EXECUTOR.',
+          ),
         idempotencyKey: z
           .string()
           .max(200)

package/src/tools/script-upsert.ts

@@ -3,6 +3,7 @@ import * as z from "zod";
 import { createToolRegistrar } from "@/tools/utils";
 import {
   proxyScriptsApi,
+  scriptExecutorSchema,
   scriptFsModeSchema,
   scriptNameSchema,
   scriptScopeSchema,
@@ -33,6 +34,12 @@ export const registerScriptUpsertTool = (server: McpServer) => {
         fsMode: scriptFsModeSchema
           .default("none")
           .describe("Filesystem mode. v1 supports none only."),
+        executor: scriptExecutorSchema
+          .nullable()
+          .optional()
+          .describe(
+            'Optional per-script executor override ("native" or "quickjs"). Null or omitted inherits SCRIPT_EXECUTOR.',
+          ),
       }),
       outputSchema: scriptToolOutputSchema,
     },

package/src/tools/store-progress.ts

@@ -13,6 +13,11 @@ import {
   updateAgentStatusFromCapacity,
   updateTaskProgress,
 } from "@/be/db";
+import {
+  LEARNING_MAX_TAGS,
+  storeTaskLearning,
+  type TaskLearningResult,
+} from "@/be/memory/task-learning";
 import {
   CitationInputSchema,
   getTaskCitations,
@@ -114,8 +119,26 @@ export const storeProgressOutputSchema = swarmToolOutputSchema({
     .describe(
       "Present only when this progress text reads as blocked-waiting: milliseconds since the task's prior update. Drives the store-progress nudge toward defer-task.",
     ),
+  learning: z
+    .looseObject({
+      status: z.string().optional(),
+      key: z.string().optional(),
+      memoryId: z.string().optional(),
+      workstream: z.string().optional(),
+      error: z.string().optional(),
+    })
+    .optional()
+    .describe(
+      "Present when the call carried a learning: stored, replayed (same text already stored for this task), or failed with error.",
+    ),
 });
 
+function learningSentence(result: TaskLearningResult): string {
+  if (result.status === "stored") return `Learning stored at ${result.key}.`;
+  if (result.status === "replayed") return `Learning already stored at ${result.key}; skipped.`;
+  return `Learning not stored: ${result.error}.`;
+}
+
 export const registerStoreProgressTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "store-progress",
@@ -165,6 +188,19 @@ export const registerStoreProgressTool = (server: McpServer) => {
           .describe(
             'Claim sources, upserted by index across calls. Use only for factual claims the reader cannot already see in the thread or task tree, 1-2 sources; none on delegation, routing, acks, or status replies. Reference each one in output with [citation:N], or set general: true for a source that backs the whole answer (it renders under "General sources"). ref per kind: task = task UUID; memory = memory UUID (optional quote must appear verbatim in it); github = owner/repo#N, owner/repo@<sha>, or a github.com pull, issues, or commit URL; slack = permalink or channel/ts; agent-fs = file path; page = page id; script-run = script run id; url = http(s) URL. The first completing call is refused, and the task stays in progress, if a marker has no entry, a citation fails validation, or a non-general citation is unreferenced; the response lists each problem. After one refusal, completion proceeds and those markers and sources are dropped from rendered output. At most 50 citations per call/task, refs up to 2048 characters, labels up to 200. Invalid or oversized batches are ignored; existing indices can still be updated at capacity.',
           ),
+        learning: z
+          .union([
+            z.string(),
+            z.object({
+              text: z.string(),
+              workstream: z.string().optional(),
+              tags: z.array(z.string()).optional(),
+            }),
+          ])
+          .optional()
+          .describe(
+            `A lesson to keep. Add one only when it would change how the next agent works: a gotcha, a dead end, a pattern that worked. Not a progress line. Stored as a swarm memory at /learnings/<workstream>/<slug>, tagged "learning" and tied to this task. The first line of text is the title. At most ~500 tokens and ${LEARNING_MAX_TAGS} kebab tags. workstream defaults to the task's repo name, else "general". Send it on or before the completing call: a call on a finished task stores nothing. A failed learning write is reported in the result and never blocks the progress update.`,
+          ),
         persistMemory: z
           .boolean()
           .optional()
@@ -193,6 +229,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         failureReason,
         attachments,
         citations,
+        learning,
         persistMemory,
         force,
       },
@@ -332,6 +369,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         }
       }
 
+      let learningWrite: Promise<TaskLearningResult> | undefined;
       const result = await getDbClient().transaction(async () => {
         const agent = await getAgentById(requestInfo.agentId ?? "");
 
@@ -435,6 +473,29 @@ export const registerStoreProgressTool = (server: McpServer) => {
           await upsertTaskCitations(taskId, citations);
         }
 
+        // A finished task takes no new writes, learnings included.
+        if (learning && isTerminal) {
+          learningWrite = Promise.resolve({
+            status: "failed",
+            error: "the task is already finished; use memory-store",
+          });
+        } else if (learning) {
+          // Post-commit, so a rolled-back progress write never leaves a learning
+          // behind, and a failed learning write never rolls back the progress.
+          learningWrite = new Promise((resolve) => {
+            getDbClient().afterCommit(() =>
+              storeTaskLearning({
+                agentId: agent.id,
+                isLead: agent.isLead === true,
+                task: existingTask,
+                learning,
+              }).then(resolve, (err) =>
+                resolve({ status: "failed", error: scrubSecrets(String(err)) }),
+              ),
+            );
+          });
+        }
+
         // Idempotency guard: short-circuit terminal-status writes (completed/failed)
         // BEFORE any side-effects fire (event emission, memory write, follow-up task,
         // business-use ensure). Without this, a multi-session race causes duplicate
@@ -627,7 +688,11 @@ export const registerStoreProgressTool = (server: McpServer) => {
         });
       }
 
-      const { success, message } = result;
+      const learningResult = await learningWrite;
+      const { success } = result;
+      const message = learningResult
+        ? `${result.message} ${learningSentence(learningResult)}`
+        : result.message;
       const task = result.task
         ? {
             id: result.task.id,
@@ -646,6 +711,7 @@ export const registerStoreProgressTool = (server: McpServer) => {
         typeof result.blockedWaitingElapsedMs === "number"
           ? { blockedWaitingElapsedMs: result.blockedWaitingElapsedMs }
           : {}),
+        ...(learningResult ? { learning: learningResult } : {}),
       };
       const warnings =
         success && status === "completed"

package/src/tools/task-action.ts

@@ -68,7 +68,7 @@ export const taskActionInputSchema = z.object({
   // For 'create' action:
   task: z.string().min(1).optional().describe("Task description (required for 'create')."),
   key: AssetKeySchema.optional().describe(
-    "Logical namespace for a created task. Defaults to a shared/task:<id>/ resource key.",
+    "Logical namespace for a created task. Default: the Slack or chat source key of the task (for example shared/slack/<channel>/thread:<ts>/), else shared/task:<id>/.",
   ),
   taskType: z.string().max(50).optional().describe("Task type (e.g., 'bug', 'feature')."),
   tags: z

package/src/tools/workflows/get-workflow-run.ts

@@ -1,6 +1,7 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { getWorkflowRun, getWorkflowRunStepsByRunId } from "@/be/db";
+import { getWorkflowRunStepsSlimByRunId, getWorkflowRunSummary } from "@/be/db/workflow-runs";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 const STEP_VALUE_CAP = 400;
@@ -15,7 +16,7 @@ function stepValuePreview(value: unknown): string | undefined {
 }
 
 function renderSteps(
-  steps: Awaited<ReturnType<typeof getWorkflowRunStepsByRunId>>,
+  steps: Awaited<ReturnType<typeof getWorkflowRunStepsSlimByRunId>>,
 ): string | undefined {
   if (steps.length === 0) return undefined;
   return steps
@@ -46,20 +47,29 @@ export const registerGetWorkflowRunTool = (server: McpServer) => {
       description: "Get details of a workflow run by ID, including all steps and their statuses.",
       inputSchema: z.object({
         id: z.string().uuid().describe("Workflow run ID"),
+        fields: z
+          .enum(["full", "slim"])
+          .optional()
+          .describe(
+            "`slim` omits run.context and each step's input (a context snapshot per step, large in runs with loops). Outputs, errors and retry fields stay. Default: full.",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         run: z.unknown().optional(),
         steps: z.array(z.unknown()).optional(),
       }),
     },
-    async ({ id }) => {
+    async ({ id, fields }) => {
       try {
         // Display view: the scrubbed context and step outputs, never replay state.
-        const run = await getWorkflowRun(id, "display");
+        const slim = fields === "slim";
+        const run = slim ? await getWorkflowRunSummary(id) : await getWorkflowRun(id, "display");
         if (!run) {
           return toolErr(`Workflow run not found: ${id}`, { data: { steps: [] } });
         }
-        const steps = await getWorkflowRunStepsByRunId(id, "display");
+        const steps = slim
+          ? await getWorkflowRunStepsSlimByRunId(id)
+          : await getWorkflowRunStepsByRunId(id, "display");
         return toolOk(`Run ${id} status: ${run.status}.`, {
           details: renderSteps(steps),
           data: { run, steps },

package/src/tools/workflows/trigger-workflow.ts

@@ -2,10 +2,42 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { resolveTaskAuditUserId } from "@/be/audit-user";
 import { getWorkflow, getWorkflowRun } from "@/be/db";
+import {
+  findAcceptedWorkflowOperation,
+  IdempotencyKeyTakenError,
+  recordAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+  workflowRequestFingerprint,
+} from "@/be/db/workflow-idempotency";
+import { IDEMPOTENCY_KEY_PATTERN } from "@/http/idempotency-key";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import { getExecutorRegistry, startWorkflowExecution } from "@/workflows";
 import { TriggerSchemaError } from "@/workflows/engine";
 
+/**
+ * Answer from the run already accepted under this key, or null when there is
+ * none. Same record and rules as the HTTP trigger's `Idempotency-Key`.
+ */
+async function replayAcceptedTrigger(claim: WorkflowIdempotencyClaim) {
+  const accepted = await findAcceptedWorkflowOperation(claim);
+  if (!accepted) return null;
+  if (accepted.fingerprint !== claim.fingerprint) {
+    return toolErr("idempotencyKey was already used to trigger this workflow with other data.", {
+      data: { idempotencyConflict: true },
+    });
+  }
+  if (accepted.resourceDeletedAt !== null) {
+    return toolErr(
+      "The workflow this idempotencyKey triggered was deleted; send a new key to start over.",
+    );
+  }
+  const { runId, skipped } = accepted.body as { runId: string; skipped: boolean };
+  return toolOk("Run already accepted under this idempotencyKey; nothing new was started.", {
+    details: `Replayed the run accepted under this idempotencyKey — run ID: ${runId}.`,
+    data: { runId, skipped, replayed: true },
+  });
+}
+
 export const registerTriggerWorkflowTool = (server: McpServer) => {
   createToolRegistrar(server)(
     "trigger-workflow",
@@ -21,16 +53,55 @@ export const registerTriggerWorkflowTool = (server: McpServer) => {
           .record(z.string(), z.unknown())
           .optional()
           .describe("Optional data to pass as trigger context to the workflow"),
+        wait: z
+          .boolean()
+          .optional()
+          .describe(
+            "Default true: return after the run's instant steps ran, when it finishes or parks at its first async step. " +
+              "false: return as soon as the run is created and walk it in the background. Use false from a script or step that only needs the runId.",
+          ),
+        idempotencyKey: z
+          .string()
+          .regex(IDEMPOTENCY_KEY_PATTERN)
+          .optional()
+          .describe(
+            "Optional, 1-255 visible ASCII characters, scoped to the calling agent and this workflow. " +
+              "The first trigger accepted under a key starts one run; the key is recorded in the run's own transaction and never expires. " +
+              "A retry with the same key and triggerData starts nothing and returns that run (replayed: true), even if the earlier call was killed before it saw the answer. " +
+              "The same key with other triggerData is an error with idempotencyConflict: true.",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         runId: z.string().optional(),
         skipped: z.boolean().optional(),
+        replayed: z.boolean().optional(),
+        idempotencyConflict: z.boolean().optional(),
         validationErrors: z.array(z.string()).optional(),
         triggerSchema: z.record(z.string(), z.unknown()).optional(),
       }),
     },
-    async ({ id, triggerData }, requestInfo) => {
+    async ({ id, triggerData, wait, idempotencyKey }, requestInfo) => {
       try {
+        if (idempotencyKey !== undefined && !requestInfo.agentId) {
+          return toolErr("idempotencyKey needs an identified caller (X-Agent-ID).");
+        }
+        const claim: WorkflowIdempotencyClaim | undefined =
+          idempotencyKey === undefined
+            ? undefined
+            : {
+                principal: `agent:${requestInfo.agentId}`,
+                key: idempotencyKey,
+                operation: "workflow.trigger",
+                targetId: id,
+                fingerprint: workflowRequestFingerprint("workflow.trigger", triggerData ?? {}),
+              };
+        if (claim) {
+          // Before the enabled, cooldown and trigger-schema checks: an
+          // accepted trigger replays even after the workflow changed.
+          const replayed = await replayAcceptedTrigger(claim);
+          if (replayed) return replayed;
+        }
+
         const workflow = await getWorkflow(id);
         if (!workflow) {
           return toolErr(`Workflow not found: ${id}`);
@@ -38,21 +109,44 @@ export const registerTriggerWorkflowTool = (server: McpServer) => {
         if (!workflow.enabled) {
           return toolErr(`Workflow "${workflow.name}" is disabled.`);
         }
-        const runId = await startWorkflowExecution(
-          workflow,
-          triggerData ?? {},
-          getExecutorRegistry(),
-          {
+        let accepted: { runId: string; skipped: boolean } | undefined;
+        let runId: string;
+        try {
+          runId = await startWorkflowExecution(workflow, triggerData ?? {}, getExecutorRegistry(), {
             triggerType: "manual",
             requestedByUserId:
               (await resolveTaskAuditUserId(requestInfo.sourceTaskId, requestInfo.agentId)) ??
               undefined,
-          },
-        );
+            detach: wait === false,
+            // Recorded in the run's own transaction: the key exists if and
+            // only if the run committed.
+            accept: claim
+              ? async (run) => {
+                  const response = { runId: run.runId, skipped: run.skipped };
+                  await recordAcceptedWorkflowOperation(claim, {
+                    workflowId: workflow.id,
+                    runId: run.runId,
+                    status: 201,
+                    body: response,
+                  });
+                  accepted = response;
+                }
+              : undefined,
+          });
+        } catch (err) {
+          // A concurrent call with this key committed its run first; this one
+          // created none.
+          if (claim && err instanceof IdempotencyKeyTakenError) {
+            const replayed = await replayAcceptedTrigger(claim);
+            if (replayed) return replayed;
+          }
+          throw err;
+        }
 
         // Check if the run was skipped due to cooldown
-        const run = await getWorkflowRun(runId);
-        const skipped = run?.status === "skipped";
+        const skipped = accepted
+          ? accepted.skipped
+          : (await getWorkflowRun(runId))?.status === "skipped";
 
         if (skipped) {
           return toolOk(`Workflow "${workflow.name}" skipped (cooldown).`, {

package/src/types.ts

@@ -1341,12 +1341,27 @@ export const AgentSchema = z
 //
 // The cache-hit post-task path does NOT produce a new report; the row's
 // `reportedAt` deliberately stays at the last actual check.
+/** One pool member's live test. `suffix` is its last 5 chars, as in `api_key_status`. */
+export const AgentCredStatusKeyResultSchema = z
+  .object({
+    keyType: z.string(),
+    index: z.number(),
+    suffix: z.string(),
+    ok: z.boolean(),
+    error: z.string().optional(),
+    httpStatus: z.number().optional(),
+    latency_ms: z.number(),
+  })
+  .openapi("AgentCredStatusKeyResult");
+
 export const AgentCredStatusLiveTestSchema = z
   .object({
     ok: z.boolean(),
     error: z.string().nullable().default(null),
     latency_ms: z.number(),
     testedAt: z.number(), // unix ms
+    warning: z.string().optional(),
+    keys: z.array(AgentCredStatusKeyResultSchema).optional(),
   })
   .openapi("AgentCredStatusLiveTest");
 export type AgentCredStatusLiveTest = z.infer<typeof AgentCredStatusLiveTestSchema>;
@@ -2267,7 +2282,14 @@ export const ExecutorMetaSchema = z
     inputCtx: z.record(z.string(), z.unknown()).optional(),
   })
   .openapi("ExecutorMeta");
-export type ExecutorMeta = z.infer<typeof ExecutorMetaSchema>;
+export type ExecutorMeta = z.infer<typeof ExecutorMetaSchema> & {
+  /**
+   * Aborted when the step's watchdog budget runs out (`startStepDeadline`).
+   * Runtime-only, never serialized. An executor with a long or one-shot side
+   * effect should forward it so a timed-out step stops instead of finishing.
+   */
+  signal?: AbortSignal;
+};
 
 // --- Validation ---
 
@@ -3090,6 +3112,15 @@ export const WorkflowRunStepSchema = z
   .openapi("WorkflowRunStep");
 export type WorkflowRunStep = z.infer<typeof WorkflowRunStepSchema>;
 
+/**
+ * Step of `GET /api/workflow-runs/{id}?fields=slim`: no `input`, the context
+ * snapshot taken when the step started. Loops repeat it once per iteration.
+ */
+export const WorkflowRunStepSlimSchema = WorkflowRunStepSchema.omit({ input: true }).openapi(
+  "WorkflowRunStepSlim",
+);
+export type WorkflowRunStepSlim = z.infer<typeof WorkflowRunStepSlimSchema>;
+
 // --- Wait State (workflow `wait` node side table) ---
 
 export const WaitModeSchema = z.enum(["time", "event"]);
@@ -3179,6 +3210,9 @@ export type ScriptScope = z.infer<typeof ScriptScopeSchema>;
 export const ScriptFsModeSchema = z.enum(["none", "workspace-rw"]);
 export type ScriptFsMode = z.infer<typeof ScriptFsModeSchema>;
 
+export const ScriptExecutorNameSchema = z.enum(["native", "quickjs"]);
+export type ScriptExecutorName = z.infer<typeof ScriptExecutorNameSchema>;
+
 export const ScriptRecordSchema = z
   .object({
     id: z.string(),
@@ -3195,6 +3229,7 @@ export const ScriptRecordSchema = z
     isScratch: z.boolean(),
     typeChecked: z.boolean(),
     fsMode: ScriptFsModeSchema,
+    executor: ScriptExecutorNameSchema.nullable().default(null),
     createdByAgentId: z.string().nullable(),
     createdAt: z.string(),
     updatedAt: z.string(),

package/src/utils/company-profile.ts

@@ -1,6 +1,19 @@
+import type { EventContext } from "../telemetry-contract";
+
 export const COMPANY_TEAM_SIZES = ["1", "2-10", "11-50", "51+"] as const;
 
-export const COMPANY_USE_CASES = ["features", "bugs", "review", "ops", "docs", "data"] as const;
+export const COMPANY_USE_CASES = [
+  "features",
+  "bugs",
+  "review",
+  "ops",
+  "docs",
+  "data",
+  "content",
+  "research",
+  "seo",
+  "admin",
+] as const;
 
 export const COMPANY_ACQUISITION_SOURCES = [
   "search",
@@ -19,6 +32,43 @@ export const USER_FUNCTIONS = [
   "eng_lead",
   "founder",
   "product",
+  "marketing",
+  "sales",
+  "research",
   "ops",
   "other",
 ] as const;
+
+// The values the vendored telemetry catalog (`src/telemetry-contract`) lists.
+// The proxy rejects a whole event, feedback submission or benchmark request
+// for one value it does not list. So a newer value stays out of telemetry, as
+// if unset, until the proxy catalog adds it and `sync:telemetry-contract` runs.
+const REPORTED_USE_CASES = [
+  "features",
+  "bugs",
+  "review",
+  "ops",
+  "docs",
+  "data",
+] as const satisfies readonly NonNullable<EventContext["use_case"]>[];
+
+const REPORTED_USER_FUNCTIONS = [
+  "engineer",
+  "eng_lead",
+  "founder",
+  "product",
+  "ops",
+  "other",
+] as const satisfies readonly NonNullable<EventContext["user_function"]>[];
+
+/** `value` when telemetry may report it as a use case, else undefined. */
+export function reportedUseCase(value: unknown): (typeof REPORTED_USE_CASES)[number] | undefined {
+  return REPORTED_USE_CASES.find((reported) => reported === value);
+}
+
+/** `value` when telemetry may report it as a job function, else undefined. */
+export function reportedUserFunction(
+  value: unknown,
+): (typeof REPORTED_USER_FUNCTIONS)[number] | undefined {
+  return REPORTED_USER_FUNCTIONS.find((reported) => reported === value);
+}

package/src/utils/credentials.ts

@@ -380,6 +380,7 @@ export function validateOpencodeCredentials(
 /** Per-pool availability, including the model-scoped block breakdown when a model was requested. */
 export interface AvailabilityInfo {
   availableIndices: number[];
+  rejectedIndices?: number[];
   modelBlockedIndices?: number[];
   earliestModelResetAt?: string | null;
   /** Indices excluded because the key's subscription plan cannot run the model. */
@@ -405,28 +406,33 @@ async function fetchAvailableIndices(
   for (const envVar of poolVars) {
     const val = env[envVar];
     if (val) {
-      const totalKeys = val.includes(",") ? val.split(",").filter((s) => s.trim()).length : 1;
+      // Status is matched by key suffix, so a key at the same index in another
+      // agent's or repo's pool never blocks one of ours (issue #2425).
+      const keySuffixes = splitCredentialPool(val).map((key) => key.slice(-5));
+      const totalKeys = keySuffixes.length;
       try {
         const resp = await fetch(
-          `${apiUrl}/api/keys/available?keyType=${encodeURIComponent(envVar)}&totalKeys=${totalKeys}${modelParam}`,
+          `${apiUrl}/api/keys/available?keyType=${encodeURIComponent(envVar)}&totalKeys=${totalKeys}${modelParam}&keySuffixes=${encodeURIComponent(keySuffixes.join(","))}`,
           { headers: { Authorization: `Bearer ${apiKey}` } },
         );
         if (resp.ok) {
           const data = (await resp.json()) as {
             availableIndices: number[];
+            rejectedIndices?: number[];
             modelBlockedIndices?: number[];
             earliestModelResetAt?: string | null;
             seatBlockedIndices?: number[];
           };
           availableIndicesMap[envVar] = {
             availableIndices: data.availableIndices,
+            rejectedIndices: data.rejectedIndices,
             modelBlockedIndices: data.modelBlockedIndices,
             earliestModelResetAt: data.earliestModelResetAt,
             seatBlockedIndices: data.seatBlockedIndices,
           };
           if (data.availableIndices.length < totalKeys) {
             console.log(
-              `[credentials] ${envVar}: ${data.availableIndices.length}/${totalKeys} keys available (${totalKeys - data.availableIndices.length} rate-limited)`,
+              `[credentials] ${envVar}: ${data.availableIndices.length}/${totalKeys} keys available (${totalKeys - data.availableIndices.length} unavailable)`,
             );
           }
         }
@@ -558,7 +564,7 @@ export async function resolveCredentialPools(
       env[envVar] = result.selected;
       const availInfo = available ? ` (${available.length} available of ${result.total})` : "";
       console.log(
-        `[credentials] Selected ${envVar} credential ${result.index + 1}/${result.total}${availInfo} [...${result.keySuffix}]`,
+        `[credentials] Selected ${envVar} credential ${result.index + 1}/${result.total}${availInfo} [...${result.keySuffix}]${info?.rejectedIndices?.length ? ` (${info.rejectedIndices.length} rejected)` : ""}`,
       );
       selections.push({
         ...result,

package/src/utils/internal-ai/complete-structured.ts

@@ -20,6 +20,7 @@ import { complete } from "@earendil-works/pi-ai/compat";
 import { getBuiltinModel as getModel } from "@earendil-works/pi-ai/providers/all";
 import type { TSchema } from "typebox";
 import { z } from "zod";
+import { selectCredential } from "../credentials.js";
 import {
   DEFAULT_OPENROUTER_BASE_URL,
   getOpenRouterAttributionHeaders,
@@ -134,6 +135,10 @@ export async function defaultSpawnClaudeCli(
   if (!env.CLAUDE_CODE_OAUTH_TOKEN && env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN) {
     env.CLAUDE_CODE_OAUTH_TOKEN = env.AGENT_SWARM_CLAUDE_OAUTH_TOKEN;
   }
+  // API calls and restarted workers can inherit raw pools.
+  for (const keyVar of ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"]) {
+    if (env[keyVar]) env[keyVar] = selectCredential(env[keyVar], undefined, keyVar).selected;
+  }
   // Recursion guard: this shellout is itself a full claude session — on exit it
   // fires the same global Stop hook, whose session-summary path would spawn
   // another `claude -p`, recursively (each level holds a ~0.5-1GB node process;