@desplega.ai/agent-swarm 2.6.0 → 2.7.1

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/constants.ts

@@ -89,6 +89,36 @@ export function getAgentFsLiveUrl(): string {
   return (raw || DEFAULT_AGENT_FS_LIVE_URL).replace(/\/+$/, "");
 }
 
+/** Where people-facing agent-fs file links point: Comb in the dashboard, or the live app. */
+export type AgentFsLinkTarget = "dashboard" | "live";
+
+/**
+ * The operator's `AGENT_FS_LINK_TARGET` choice (trimmed, lowercased). Null when
+ * unset, blank, or invalid: every surface then keeps its automatic behavior.
+ */
+export function readAgentFsLinkTarget(): AgentFsLinkTarget | null {
+  const raw = process.env.AGENT_FS_LINK_TARGET?.trim().toLowerCase();
+  return raw === "dashboard" || raw === "live" ? raw : null;
+}
+
+/**
+ * The base URL (no trailing slash) that a people-facing file link starts with,
+ * per {@link readAgentFsLinkTarget}. `dashboard` uses `APP_URL` when one is
+ * configured (and, for attachments, Comb is on), else the live app. Null when
+ * no target is set: the caller keeps its current code path.
+ *
+ * The prompt surface skips the Comb check: workers do not get `COMB_ENABLED`,
+ * and an explicit `dashboard` is the operator's choice.
+ */
+export function resolveAgentFsLinkBase(surface: "prompt" | "attachment"): string | null {
+  const target = readAgentFsLinkTarget();
+  if (target === null) return null;
+  if (target === "dashboard" && getConfiguredAppUrls().length > 0) {
+    if (surface === "prompt" || isCombEnabled()) return getAppUrl();
+  }
+  return getAgentFsLiveUrl();
+}
+
 /**
  * Optional fallback agent-fs `org_id` for attachments that store only `path`.
  * Strictly opt-in — when neither env var is set, the renderer keeps the
@@ -166,6 +196,15 @@ export function isCombEnabled(): boolean {
   return isEnvFlagEnabled("COMB_ENABLED", false) && Boolean(apiUrl);
 }
 
+/**
+ * `AGENT_FS_PROXY`: the API serves agent-fs at `/agentfs/*` (plus the public
+ * `/share/*` and `/site/*` pages), and Comb uses `<public API URL>/agentfs`.
+ * Read per request, so a config upsert applies without a restart. Off by default.
+ */
+export function isAgentFsProxyEnabled(): boolean {
+  return isEnvFlagEnabled("AGENT_FS_PROXY", false);
+}
+
 /**
  * The dashboard (Comb) URL for an agent-fs file, same id and encoding rules as
  * {@link buildAgentFsLiveUrl}. Null unless Comb is on AND an explicit

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/utils/task-attachment-links.ts

@@ -1,5 +1,11 @@
 import type { TaskAttachment } from "../types";
-import { buildAgentFsLiveUrl, buildCombFileUrl, getAppUrl } from "./constants";
+import {
+  agentFsFileRoute,
+  buildAgentFsLiveUrl,
+  buildCombFileUrl,
+  getAppUrl,
+  resolveAgentFsLinkBase,
+} from "./constants";
 
 function shellQuote(value: string): string {
   return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -26,8 +32,9 @@ export function taskAttachmentFetchCommand(
 /**
  * The link a human (Slack, prompts, citations) sees for an attachment. An
  * agent-fs file links to the dashboard (Comb) when Comb is on and `APP_URL` is
- * set, else to the agent-fs live UI, else to the raw `agent-fs:<path>`.
- * `comb: false` skips the dashboard link.
+ * set, else to the agent-fs live UI, else to the raw `agent-fs:<path>`. An
+ * explicit `AGENT_FS_LINK_TARGET` picks the base instead (see
+ * `resolveAgentFsLinkBase`). `comb: false` always links to the live UI.
  */
 export function taskAttachmentDisplayUrl(
   attachment: TaskAttachment,
@@ -40,6 +47,11 @@ export function taskAttachmentDisplayUrl(
 
   if (attachment.providerId === "agent-fs" || attachment.kind === "agent-fs") {
     const file = { path: attachment.path, orgId: attachment.orgId, driveId: attachment.driveId };
+    const linkBase = opts.comb === false ? null : resolveAgentFsLinkBase("attachment");
+    if (linkBase !== null) {
+      const route = agentFsFileRoute(file);
+      return route ? `${linkBase}/file/~/${route}` : `agent-fs:${attachment.path ?? ""}`;
+    }
     const combUrl = opts.comb === false ? null : buildCombFileUrl(file);
     return combUrl ?? buildAgentFsLiveUrl(file) ?? `agent-fs:${attachment.path ?? ""}`;
   }

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) };
+}