@desplega.ai/agent-swarm 2.6.0 → 2.7.0

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/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

@@ -2282,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 ---
 
@@ -3203,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(),
@@ -3219,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/credentials.ts

@@ -406,10 +406,13 @@ 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) {

package/src/workflows/engine.ts

@@ -51,7 +51,7 @@ import { FOREACH_TERMINAL_STEP_STATUSES, resolveForeachParent } from "./foreach-
 import { getSecretInputKeys, redactSecretsForStorage, resolveInputs } from "./input";
 import { validateJsonSchema } from "./json-schema-validator";
 import { getMaxWorkflowStepsPerRun } from "./limits";
-import { resolveNodeTimeoutMs } from "./node-timeout";
+import { resolveNodeTimeoutMs, startStepDeadline } from "./node-timeout";
 import { findWorkflowReadinessProblems, formatReadinessRunError } from "./readiness";
 import { deepInterpolate } from "./template";
 import { runStepValidation, type ValidationRunResult } from "./validation";
@@ -78,6 +78,13 @@ export interface WorkflowExecutionOptions {
    * HTTP trigger records its `Idempotency-Key` here.
    */
   accept?: (run: { runId: string; skipped: boolean }) => Promise<void>;
+  /**
+   * Return once the run is committed and walk it in the background, as a
+   * child run does. By default a top-level start resolves only after the
+   * walk reaches its end or its first async step, so a caller that only
+   * needs the run id waits for every instant step before it.
+   */
+  detach?: boolean;
 }
 
 /**
@@ -209,9 +216,12 @@ export async function startWorkflowExecution(
       options,
     );
     // A child run walks on its own, outside the parent executor's timeout. Its
-    // terminal status wakes the parent step (`resumeFromChildRun`).
-    if (options.parentStepId) {
-      walk.catch((err) => console.error(`[workflows] Child workflow run ${runId} failed:`, err));
+    // terminal status wakes the parent step (`resumeFromChildRun`). A detached
+    // top-level run walks the same way; the walk holds the run before its
+    // first await, so releasing the start hold below leaves no gap.
+    if (options.parentStepId || options.detach) {
+      const kind = options.parentStepId ? "Child" : "Detached";
+      walk.catch((err) => console.error(`[workflows] ${kind} workflow run ${runId} failed:`, err));
       return runId;
     }
     await walk;
@@ -1045,7 +1055,7 @@ async function runClaimedStep(
     inputCtx: interpolationCtx,
   };
 
-  const timeoutMs = resolveNodeTimeoutMs(node);
+  const deadline = startStepDeadline(resolveNodeTimeoutMs(node));
 
   let result: Awaited<ReturnType<typeof executor.run>>;
   try {
@@ -1053,10 +1063,10 @@ async function runClaimedStep(
       executor.run({
         config: interpolatedConfig,
         context: executionCtx,
-        meta,
+        meta: { ...meta, signal: deadline.signal },
       }),
-      timeoutPromise(timeoutMs),
-    ]);
+      deadline.expired,
+    ]).finally(deadline.clear);
   } catch (err) {
     const errorMsg = err instanceof Error ? err.message : String(err);
 
@@ -1459,11 +1469,3 @@ export function scriptBodyInterpolationError(nodeId: string, tokens: string[]):
     "Pass dynamic trigger or upstream values through config.args and read them from argv."
   );
 }
-
-// ─── Helpers ───────────────────────────────────────────────
-
-function timeoutPromise(ms: number): Promise<never> {
-  return new Promise((_, reject) => {
-    setTimeout(() => reject(new Error(`Step timed out after ${ms}ms`)), ms);
-  });
-}

package/src/workflows/executors/swarm-script.ts

@@ -123,6 +123,7 @@ export class SwarmScriptExecutor extends BaseExecutor<
       source: resolved.source,
       args: config.args,
       fsMode: "none",
+      executor: resolved.script.executor,
       agentId: agentId ?? "workflow",
       mcpBaseUrl: getMcpBaseUrl(),
       egressSecrets: credentials.egressSecrets,
@@ -132,6 +133,10 @@ export class SwarmScriptExecutor extends BaseExecutor<
       apiConnections: getScriptApiConnectionDescriptors({ agentId: agentId ?? undefined }),
       mcpConnections: getScriptMcpConnectionDescriptors({ agentId: agentId ?? undefined }),
       timeoutMs: config.timeoutMs,
+      // The step watchdog aborts this when the node budget runs out, which
+      // kills the script process: a step reported as timed out must not go
+      // on to perform the script's side effects.
+      signal: meta.signal,
     });
     if (output.exitCode === 0 && !output.error && !output.runtimeError) {
       await touchScratchScriptLastUsed(resolved.script.id);

package/src/workflows/foreach-driver.ts

@@ -47,7 +47,7 @@ import {
   settleForeachChild,
 } from "./foreach-join";
 import { getSecretInputKeys } from "./input";
-import { resolveNodeTimeoutMs } from "./node-timeout";
+import { resolveNodeTimeoutMs, startStepDeadline } from "./node-timeout";
 import { rebuildNodeExecutionInput } from "./step-input";
 
 export { FOREACH_ITEMS_WAIT_FOR };
@@ -480,27 +480,21 @@ async function startChild(input: {
   }
 
   const executor = registry.get(bodyType);
-  const timeoutMs = resolveNodeTimeoutMs({ type: bodyType, config });
-  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = startStepDeadline(resolveNodeTimeoutMs({ type: bodyType, config }));
   let result: Awaited<ReturnType<typeof executor.run>>;
   try {
     result = await Promise.race([
       executor.run({
         config,
         context: { ...ctx, ...bodyCtx },
-        meta: { ...meta, stepId: child.id, nodeId: child.nodeId },
-      }),
-      new Promise<never>((_, reject) => {
-        timer = setTimeout(
-          () => reject(new Error(`Step timed out after ${timeoutMs}ms`)),
-          timeoutMs,
-        );
+        meta: { ...meta, stepId: child.id, nodeId: child.nodeId, signal: deadline.signal },
       }),
+      deadline.expired,
     ]);
   } catch (err) {
     return { status: "failed", error: err instanceof Error ? err.message : String(err) };
   } finally {
-    if (timer) clearTimeout(timer);
+    deadline.clear();
   }
 
   if (result.status === "failed") {

package/src/workflows/node-timeout.ts

@@ -19,3 +19,33 @@ export function resolveNodeTimeoutMs(node: Pick<WorkflowNode, "type" | "config">
   if (node.type === "script" && typeof config.timeout === "number") return config.timeout;
   return DEFAULT_NODE_TIMEOUT_MS;
 }
+
+export interface StepDeadline {
+  /** Aborted when the budget runs out. The executor gets it as `meta.signal`. */
+  signal: AbortSignal;
+  /** Rejects with "Step timed out after <ms>ms" when the budget runs out. */
+  expired: Promise<never>;
+  /** Stop the timer once the executor call settled. */
+  clear: () => void;
+}
+
+/**
+ * The watchdog for one executor call. Racing `expired` alone settles the step
+ * but leaves the executor running, so a step reported as timed out could still
+ * perform its side effects. On expiry the deadline also aborts `signal`, so an
+ * executor that forwards it (swarm-script kills its script process) stops.
+ */
+export function startStepDeadline(timeoutMs: number): StepDeadline {
+  const controller = new AbortController();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => {
+      const error = new Error(`Step timed out after ${timeoutMs}ms`);
+      // Reject first so the race settles on the timeout, not on the
+      // executor's "killed" result that the abort produces.
+      reject(error);
+      controller.abort(error);
+    }, timeoutMs);
+  });
+  return { signal: controller.signal, expired, clear: () => clearTimeout(timer) };
+}