@desplega.ai/agent-swarm 2.7.4 → 2.7.5

package/src/tests/workflow-script-principal.test.ts

@@ -13,14 +13,19 @@ import {
   createAgent,
   createScheduledTask,
   createWorkflow,
+  createWorkflowRun,
   getDbClient,
+  getScheduledTaskByName,
+  getWorkflowRun,
   initDb,
   listWorkflows,
+  updateWorkflow,
 } from "../be/db";
 import { upsertScriptByName } from "../be/scripts/db";
 import { setScriptEmbeddingProviderForTests } from "../be/scripts/embeddings";
 import * as runCredential from "../be/scripts/run-credential";
 import { runSeeder } from "../be/seed";
+import { createSchedulesSeeder } from "../be/seed/schedules-seeder";
 import { createWorkflowsSeeder } from "../be/seed/workflows-seeder";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { handleWorkflows } from "../http/workflows";
@@ -34,6 +39,7 @@ import {
   workflowEventBus,
 } from "../workflows";
 import { handleEventTrigger } from "../workflows/triggers";
+import { snapshotAndUpdateWorkflow } from "../workflows/version";
 import { listenOnFreePort } from "./test-net";
 
 // A creator-less workflow (the seeded `dreaming`) runs its `swarm-script` nodes as
@@ -160,9 +166,31 @@ afterAll(async () => {
   await removeDbFiles();
 });
 
-beforeEach(() => {
-  // Dreaming has no cooldown, so earlier runs (parked on an agent-task) do not
-  // block the next trigger.
+/** Put the seeded dreaming row back after a test edits it. */
+async function restoreDreaming(): Promise<void> {
+  await updateWorkflow(dreaming.id, {
+    description: dreaming.description,
+    definition: dreaming.definition,
+    input: dreaming.input,
+    cooldown: dreaming.cooldown,
+    enabled: dreaming.enabled,
+  });
+}
+
+/** Move every dreaming run start out of its 20-hour cooldown window. */
+async function ageDreamingRuns(): Promise<void> {
+  await getDbClient().run(
+    `UPDATE workflow_runs SET startedAt = '2000-01-01T00:00:00.000Z',
+       finishedAt = CASE WHEN finishedAt IS NULL THEN NULL ELSE '2000-01-01T00:00:00.000Z' END
+     WHERE workflowId = ?`,
+    [dreaming.id],
+  );
+}
+
+beforeEach(async () => {
+  // Dreaming has a 20-hour cooldown. Age earlier runs (parked on an agent-task)
+  // so they do not block the next trigger.
+  await ageDreamingRuns();
   calls = [];
   scriptResult = QUIET_GATHER;
 });
@@ -241,6 +269,179 @@ describe("swarm-script principal for a creator-less workflow", () => {
     expect(gatherPrincipals()).toEqual([leadId]);
   });
 
+  test("a creator-less schedule runs as the lead, resolved at fire time", async () => {
+    const schedule = await createScheduledTask({
+      name: `principal-seeded-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+      targetAgentId: workerId,
+    });
+    expect(schedule.createdByAgentId).toBeUndefined();
+    await dispatchScheduleTarget(schedule);
+    expect(gatherPrincipals()).toEqual([leadId]);
+  });
+
+  test("a creator-less schedule fails its fire when the swarm has no lead", async () => {
+    const schedule = await createScheduledTask({
+      name: `principal-leadless-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+    });
+    await getDbClient().run("UPDATE agents SET isLead = 0 WHERE id = ?", [leadId]);
+    try {
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow(
+        "has no creator and the swarm has no lead",
+      );
+    } finally {
+      await getDbClient().run("UPDATE agents SET isLead = 1 WHERE id = ?", [leadId]);
+    }
+    expect(calls).toEqual([]);
+    const runs = await getDbClient().query<{ id: string }>(
+      "SELECT id FROM workflow_runs WHERE workflowId = ? AND startedAt > '2001-01-01'",
+      [dreaming.id],
+    );
+    expect(runs).toEqual([]);
+  });
+
+  test("a creator-less schedule keeps the lead after the documented input setup and enable", async () => {
+    // The guide's setup: update-workflow with every input key, then turn it on.
+    // Both snapshot the seeded state first, as the tool and REST paths do.
+    await snapshotAndUpdateWorkflow(
+      dreaming.id,
+      { input: { ...dreaming.input, leadAgentId: leadId, slackChannel: "C123" } },
+      { changedByAgentId: workerId },
+    );
+    await snapshotAndUpdateWorkflow(dreaming.id, { enabled: false });
+    await snapshotAndUpdateWorkflow(dreaming.id, {
+      enabled: true,
+      description: "tuned by the operator",
+      cooldown: { hours: 22, from: "start" },
+    });
+    const schedule = await createScheduledTask({
+      name: `principal-tuned-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+    });
+    try {
+      await dispatchScheduleTarget(schedule);
+      expect(gatherPrincipals()).toEqual([leadId]);
+      expect(calls[0]?.args.leadAgentId).toBe(leadId);
+    } finally {
+      await restoreDreaming();
+    }
+  });
+
+  test("a creator-less schedule refuses the lead once a worker edits the seeded nodes", async () => {
+    const schedule = await createScheduledTask({
+      name: `principal-edited-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+    });
+    const [gather, ...rest] = dreaming.definition.nodes;
+    await snapshotAndUpdateWorkflow(
+      dreaming.id,
+      {
+        input: { ...dreaming.input, leadAgentId: leadId },
+        definition: {
+          ...dreaming.definition,
+          nodes: [{ ...gather!, config: { ...gather!.config, scriptName: "evil" } }, ...rest],
+        },
+      },
+      { changedByAgentId: workerId },
+    );
+    try {
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow(
+        'the nodes or params of seeded workflow "dreaming" were edited',
+      );
+    } finally {
+      await restoreDreaming();
+    }
+    expect(calls).toEqual([]);
+  });
+
+  test("a creator-less schedule refuses the lead for an edit with no seeded snapshot", async () => {
+    const schedule = await createScheduledTask({
+      name: `principal-unsnapshotted-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+    });
+    // Delete the history so no snapshot proves the seeded state.
+    await getDbClient().run("DELETE FROM workflow_versions WHERE workflowId = ?", [dreaming.id]);
+    await updateWorkflow(dreaming.id, { description: "edited without a snapshot" });
+    try {
+      await expect(dispatchScheduleTarget(schedule)).rejects.toThrow("were edited");
+    } finally {
+      await restoreDreaming();
+    }
+    expect(calls).toEqual([]);
+  });
+
+  test("a long successful night does not make the next nightly fire skip", async () => {
+    const schedule = await createScheduledTask({
+      name: `principal-long-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: dreaming.id,
+    });
+    // Last night started 24h ago and finished 1h ago.
+    const runId = crypto.randomUUID();
+    await createWorkflowRun({ id: runId, workflowId: dreaming.id });
+    await getDbClient().run(
+      "UPDATE workflow_runs SET status = 'completed', startedAt = ?, finishedAt = ? WHERE id = ?",
+      [
+        new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(),
+        new Date(Date.now() - 60 * 60 * 1000).toISOString(),
+        runId,
+      ],
+    );
+    const fired = await dispatchScheduleTarget(schedule);
+    const run = await getWorkflowRun(fired.workflowRunIds![0]!);
+    expect(run?.status).not.toBe("skipped");
+    expect(gatherPrincipals()).toEqual([leadId]);
+  });
+
+  test("control: a creator-less workflow the seeder never wrote keeps running agentless", async () => {
+    const copy = await createWorkflow({
+      name: `principal-unseeded-${crypto.randomUUID()}`,
+      definition: dreaming.definition,
+    });
+    const schedule = await createScheduledTask({
+      name: `principal-unseeded-${crypto.randomUUID().slice(0, 8)}`,
+      cronExpression: "0 0 1 1 *",
+      targetType: "workflow",
+      workflowId: copy.id,
+    });
+    await dispatchScheduleTarget(schedule);
+    expect(gatherPrincipals()).toEqual(["workflow"]);
+  });
+
+  test("end to end: the seeded dreaming-daily schedule fires dreaming as the lead, once a day", async () => {
+    const seeded = await runSeeder(createSchedulesSeeder(), { quiet: true });
+    expect(seeded.failed).toEqual([]);
+    const schedule = await getScheduledTaskByName("dreaming-daily");
+    expect(schedule).toMatchObject({ targetType: "workflow", workflowId: dreaming.id });
+    expect(schedule?.taskTemplate).toBeUndefined();
+    expect(schedule?.createdByAgentId).toBeUndefined();
+
+    const first = await dispatchScheduleTarget(schedule!);
+    expect(first.task).toBeUndefined();
+    expect(first.workflowRunIds).toHaveLength(1);
+    expect(gatherPrincipals()).toEqual([leadId]);
+    const run = await getWorkflowRun(first.workflowRunIds![0]!);
+    expect(run?.triggerData).toMatchObject({ scheduleName: "dreaming-daily" });
+
+    // The cooldown replaces the old task prompt's 20-hour double-run guard.
+    const second = await dispatchScheduleTarget(schedule!);
+    const skipped = await getWorkflowRun(second.workflowRunIds![0]!);
+    expect(skipped).toMatchObject({ status: "skipped", error: "cooldown" });
+    expect(gatherPrincipals()).toEqual([leadId]);
+  });
+
   test("control: a workflow with a creator still runs as its creator", async () => {
     const owned = await createWorkflow({
       name: `principal-owned-${crypto.randomUUID()}`,
@@ -251,10 +452,9 @@ describe("swarm-script principal for a creator-less workflow", () => {
     expect(gatherPrincipals()).toEqual([leadId]);
   });
 
-  test("control: the seeded schedule's fire (a worker triggers with no data) runs the *-lead nodes on the lead", async () => {
-    // dreaming-daily makes a pool task; the worker that claims it calls
-    // trigger-workflow with no triggerData. Scripts run as that worker, while
-    // synthesize and apply-lead target gather's leadAgentId.
+  test("control: a worker's manual trigger with no data runs the *-lead nodes on the lead", async () => {
+    // A worker that calls trigger-workflow with no triggerData. Scripts run as
+    // that worker, while synthesize and apply-lead target gather's leadAgentId.
     scriptResult = {
       ok: true,
       agents: [{ id: workerId, name: "principal-worker" }],

package/src/tools/slack-leave-thread.ts

@@ -0,0 +1,104 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById, getTaskById } from "@/be/db";
+import { can } from "@/rbac";
+import {
+  isSlackLeaveThreadDisabled,
+  leaveSlackThread,
+  SLACK_LEAVE_THREAD_DISABLE,
+} from "@/slack/left-threads";
+import { parseSlackTs } from "@/slack/message-text";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+
+export const registerSlackLeaveThreadTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "slack-leave-thread",
+    {
+      title: "Leave a Slack thread",
+      description:
+        "Stop following a Slack thread until someone @mentions the bot there again. Messages in the thread that do not @mention the bot are then ignored, with no task and no reply. Posts nothing to Slack. Pass taskId for the thread of your Slack-originated task, or (lead only) channelId and threadTs.",
+      annotations: { openWorldHint: true, idempotentHint: true },
+
+      inputSchema: z.object({
+        taskId: z.uuid().optional().describe("A task whose Slack thread to leave."),
+        channelId: z.string().min(1).optional().describe("The Slack channel ID of the thread."),
+        threadTs: z
+          .string()
+          .min(1)
+          .optional()
+          .describe("Timestamp of the thread root (dotted, 'p' deep-link, or full permalink URL)."),
+      }),
+      outputSchema: swarmToolOutputSchema({
+        channelId: z.string().optional(),
+        threadTs: z.string().optional(),
+      }),
+    },
+    async ({ taskId, channelId, threadTs }, requestInfo, _meta) => {
+      // Sessions created before the flag was set still list the tool.
+      if (isSlackLeaveThreadDisabled()) {
+        return toolErr(`slack-leave-thread is disabled by ${SLACK_LEAVE_THREAD_DISABLE}.`);
+      }
+
+      if (!requestInfo.agentId) {
+        return toolErr("Agent ID not found.");
+      }
+
+      const agent = await getAgentById(requestInfo.agentId);
+      if (!agent) {
+        return toolErr("Agent not found.");
+      }
+
+      // Any thread is open to leads, like slack-post. Task Slack context and
+      // source can be set by any agent (send-task, POST /api/tasks), so a non-lead
+      // may only leave the thread of a task assigned to it that Slack ingress
+      // created: only the Slack handlers write slackTriggerMessageTs.
+      const mayLeaveAnyThread = can({
+        principal: { kind: "agent", agentId: agent.id, isLead: agent.isLead },
+        verb: "integration.slack.post",
+        resource: { kind: "none" },
+        source: "mcp",
+      }).allow;
+
+      let slackChannelId: string | undefined;
+      let slackThreadTs: string | undefined;
+
+      if (taskId) {
+        if (channelId || threadTs) {
+          return toolErr("Provide either taskId or channelId and threadTs, not both.");
+        }
+        const task = await getTaskById(taskId);
+        if (!task) {
+          return toolErr("Task not found.");
+        }
+        if (
+          !mayLeaveAnyThread &&
+          (task.agentId !== agent.id || task.source !== "slack" || !task.slackTriggerMessageTs)
+        ) {
+          return toolErr(
+            "Only a lead or the agent assigned a Slack-originated task can leave its thread.",
+          );
+        }
+        slackChannelId = task.slackChannelId;
+        slackThreadTs = task.slackThreadTs;
+      } else if (channelId && threadTs) {
+        if (!mayLeaveAnyThread) {
+          return toolErr("Leaving a thread by channelId and threadTs requires lead privileges.");
+        }
+        slackChannelId = channelId;
+        slackThreadTs = parseSlackTs(threadTs);
+      } else {
+        return toolErr("Must provide taskId, or both channelId and threadTs.");
+      }
+
+      if (!slackChannelId || !slackThreadTs) {
+        return toolErr("No Slack thread context available.");
+      }
+
+      await leaveSlackThread(slackChannelId, slackThreadTs, agent.id);
+      return toolOk(
+        `Left Slack thread ${slackChannelId}/${slackThreadTs}. Messages there are ignored until someone @mentions the bot.`,
+        { data: { channelId: slackChannelId, threadTs: slackThreadTs } },
+      );
+    },
+  );
+};

package/src/tools/steer-task.ts

@@ -99,7 +99,8 @@ export async function steerTaskHandler(
       message,
       mode,
       onUnsupported,
-      source: "mcp",
+      source:
+        ctx.kind === "owner" && ctx.requestInfo?.callOrigin === "script-sdk" ? "script" : "mcp",
       createdByKind: ctx.kind === "owner" ? "agent" : "user",
       createdByAgentId: ctx.kind === "owner" ? ctx.agentId : undefined,
       createdByUserId: ctx.kind === "user" ? ctx.userId : undefined,
@@ -126,7 +127,7 @@ export const registerSteerTaskTool = (server: McpServer) => {
     {
       title: "Steer Task",
       description:
-        'Send a message to a task that is already running. `mode:"steer"` is honored on pi, claude-managed, codex and cursor; claude, devin, opencode and amp support queue only (amp delivery lands at the next tool result). Pass `onUnsupported:"fail"` to get an error instead of a downgrade.',
+        'Send a message to a task that is already running. `mode:"steer"` is honored on pi, claude-managed, codex, cursor and fx (fx supports steer only); claude, devin, opencode and amp support queue only (amp delivery lands at the next tool result). Pass `onUnsupported:"fail"` to get an error instead of a downgrade.',
       annotations: { destructiveHint: true },
       inputSchema: steerTaskInputSchema,
       outputSchema: steerTaskOutputSchema,

package/src/tools/tool-config.ts

@@ -96,7 +96,7 @@ export const DEFERRED_TOOLS = new Set([
   "read-messages",
   "post-message",
 
-  // Slack (12): task-context gated; keep out of CORE_TOOLS
+  // Slack (13): task-context gated; keep out of CORE_TOOLS
   "slack-reply",
   "slack-read",
   "slack-upload-file",
@@ -109,6 +109,7 @@ export const DEFERRED_TOOLS = new Set([
   "slack-archive-channel",
   "slack-delete",
   "slack-update",
+  "slack-leave-thread",
 
   // Channel management (2)
   "create-channel",

package/src/types.ts

@@ -185,6 +185,14 @@ export const DEFAULT_MODEL_TIER_MAP: Record<ProviderName, Record<ModelTier, stri
     smart: "grok-4.6",
     ultra: "grok-4.7",
   },
+  // fx runs these on its `openrouter` custom connection (OPENROUTER_API_KEY),
+  // pi's tested OpenRouter set; each ran under fx 0.0.15 (2026-10-29 probe).
+  fx: {
+    smol: "openrouter/deepseek/deepseek-v4.1-flash",
+    regular: "openrouter/deepseek/deepseek-v4.1-flash",
+    smart: "openrouter/deepseek/deepseek-v4-pro-0813",
+    ultra: "openrouter/anthropic/claude-opus-5.5",
+  },
   // ACP has no portable tier-to-model mapping. Operators may set an explicit
   // MODEL_OVERRIDE, which the adapter applies through an advertised `model`
   // config option with a target-specific startup fallback.
@@ -436,6 +444,7 @@ export const ProviderNameSchema = z.enum([
   "amp",
   "cursor",
   "grok",
+  "fx",
 ]);
 export type ProviderName = z.infer<typeof ProviderNameSchema>;
 
@@ -596,6 +605,10 @@ export const PROVIDER_STEER_CAPABILITIES: Record<ProviderName, SteerMode[]> = {
   // Grok runs on the ACP client: one `session/prompt` turn, interrupted only
   // by `session/cancel`. No Grok surface (ACP or headless) exposes a steer.
   grok: [],
+  // `fx acp` steers natively: a `session/prompt` with `_meta.fx.steer` during a
+  // running turn lands at the next tool boundary without cancelling it (fx
+  // 0.0.15 probe, 2026-10-29). Queue is not measured, so it is not advertised.
+  fx: ["steer"],
 };
 
 export type DevinProviderMeta = {
@@ -619,6 +632,7 @@ export type ProviderMetaMap = {
   amp: NoProviderMeta;
   cursor: NoProviderMeta;
   grok: NoProviderMeta;
+  fx: NoProviderMeta;
 };
 
 export const FollowUpConfigSchema = z
@@ -2606,6 +2620,10 @@ export const CooldownConfigSchema = z
     hours: z.number().min(0).optional(),
     minutes: z.number().min(0).optional(),
     seconds: z.number().min(0).optional(),
+    // "finish" (default): also wait out the window after the last successful
+    // run finished. "start": count only from run starts, so a long run never
+    // pushes the next fixed-time trigger out.
+    from: z.enum(["finish", "start"]).optional(),
   })
   .refine((v) => v.hours !== undefined || v.minutes !== undefined || v.seconds !== undefined, {
     message: "At least one of hours, minutes, or seconds is required",
@@ -3838,6 +3856,7 @@ export const PricingProviderSchema = z.enum([
   "amp",
   "cursor",
   "grok",
+  "fx",
 ]);
 export type PricingProvider = z.infer<typeof PricingProviderSchema>;
 

package/src/utils/codex-auth-failure.ts

@@ -32,3 +32,33 @@ export function isCodexAuthFailureReason(failureReason: string | undefined | nul
   const lower = failureReason.toLowerCase();
   return !TRANSIENT_AUTH_ERROR_MARKERS.some((m) => lower.includes(m));
 }
+
+/**
+ * Turn-level texts of a rejected ChatGPT/Codex credential: a bad API key, or
+ * a pool login revoked while its access token is unexpired. That death mode
+ * never enters `getValidCodexOAuth` (the token looks fresh), so this error is
+ * its only artifact. The adapters tag a match `[auth-error]`.
+ */
+const REJECTED_ACCESS_PATTERNS = [
+  "unauthorized",
+  "http 401",
+  " 401 ",
+  "invalid api key",
+  "invalid_api_key",
+  "missing api key",
+  "no api key",
+  "authentication failed",
+  "failed to refresh token",
+  "invalid 'refresh_token'",
+  // ChatGPT backend 401 bodies (pi on the subscription surfaces them as-is).
+  "token_invalidated",
+  "authentication token has been invalidated",
+  "authentication token is expired",
+  "refresh token was revoked",
+  "could not parse your authentication token",
+];
+
+export function isCodexRejectedAccessError(text: string): boolean {
+  const lower = text.toLowerCase();
+  return REJECTED_ACCESS_PATTERNS.some((p) => lower.includes(p));
+}

package/src/utils/context-window.ts

@@ -20,7 +20,7 @@
  *     deprecated; new code should use `computeContextUsedUnified`.
  */
 
-import { buildClaudeShortnameMap } from "@desplega/model-catalog";
+import { buildClaudeShortnameMap, chatgptSubscriptionModelId } from "@desplega/model-catalog";
 import { runtimeCatalogModel, runtimeCatalogSection } from "./runtime-model-catalog";
 
 /**
@@ -73,6 +73,9 @@ export function getContextWindowSize(model: string): number {
 /** {@link getContextWindowSize} without the fallback: undefined when the catalog has no window. */
 export function getKnownContextWindowSize(model: string | undefined): number | undefined {
   if (!model) return undefined;
+  // `openai-codex/<id>` (pi on the ChatGPT subscription) is the OpenAI `<id>`.
+  const subscriptionId = chatgptSubscriptionModelId(model);
+  if (subscriptionId) return catalogContext("openai", subscriptionId);
   const slash = model.indexOf("/");
   if (slash > 0) {
     const scoped = catalogContext(model.slice(0, slash), model.slice(slash + 1));

package/src/utils/credentials.ts

@@ -1,5 +1,6 @@
 import { existsSync } from "node:fs";
 import {
+  fxModelRoute,
   openAICompatibleProviders,
   providerForKeyVar,
   providerForModel,
@@ -61,6 +62,7 @@ export const PROVIDER_CREDENTIAL_VARS: Record<string, readonly string[]> = {
   amp: ["AMP_API_KEY"],
   cursor: ["CURSOR_API_KEY"],
   grok: ["XAI_API_KEY", "OPENROUTER_API_KEY"],
+  fx: ["OPENROUTER_API_KEY", "OPENAI_API_KEY", "AI_GATEWAY_API_KEY"],
   opencode: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY"],
 };
 
@@ -100,6 +102,11 @@ export function getModelAwareCredentialVars(provider: string, model?: string): r
   if (provider === "grok" && model) {
     return model.startsWith("openrouter/") ? ["OPENROUTER_API_KEY"] : ["XAI_API_KEY"];
   }
+  // fx routes by namespace (`src/utils/fx-models.ts`); each route reads one key.
+  if (provider === "fx" && model) {
+    const route = fxModelRoute(model);
+    return "error" in route ? base : [route.keyVar];
+  }
   if (!SLASH_MODEL_PROVIDERS.has(provider) || !model) return base;
   // OpenAI-compatible registry providers own their key: `nan/<id>` and
   // `helmcode/<id>` never pool an OpenRouter or Anthropic key.

package/src/utils/fx-models.ts

@@ -0,0 +1,43 @@
+/**
+ * Model routing for the `fx` harness. Pure, so the API server can validate a
+ * model and the worker can route it without importing the adapter.
+ *
+ * | Swarm model string           | fx provider (`FX_PROVIDER`)       | `fx acp --model` | Key                  |
+ * |------------------------------|-----------------------------------|------------------|----------------------|
+ * | `openrouter/<vendor>/<id>`   | `openrouter` (custom connection)  | `<vendor>/<id>`  | `OPENROUTER_API_KEY` |
+ * | `vercel/<vendor>/<id>`       | `gateway` (built in)              | `<vendor>/<id>`  | `AI_GATEWAY_API_KEY` |
+ * | bare `<id>` (no slash)       | `openai` (custom connection)      | `<id>`           | `OPENAI_API_KEY`     |
+ *
+ * Anything else (`nan/…`, `helmcode/…`, `anthropic/…`) is rejected with a reason.
+ */
+import { type FxRoute, fxModelRoute } from "@desplega/model-catalog";
+import { DEFAULT_MODEL_TIER_MAP } from "../types";
+
+export type { FxRoute };
+
+/** An fx route plus the swarm model string it came from. */
+export type ResolvedFxRoute = FxRoute & { model: string };
+
+/** Every key an fx route can read, in route-table order. */
+export const FX_ROUTE_KEY_VARS = [
+  "OPENROUTER_API_KEY",
+  "OPENAI_API_KEY",
+  "AI_GATEWAY_API_KEY",
+] as const;
+
+/**
+ * The fx route for a swarm model string, or the reason it has none. An empty
+ * model means the regular tier default.
+ */
+export function resolveFxRoute(model: string | undefined): ResolvedFxRoute | { error: string } {
+  const value = model?.trim() || DEFAULT_MODEL_TIER_MAP.fx.regular;
+  const route = fxModelRoute(value);
+  return "error" in route ? route : { ...route, model: value };
+}
+
+/** {@link resolveFxRoute}, throwing the rejection reason. */
+export function requireFxRoute(model: string | undefined): ResolvedFxRoute {
+  const route = resolveFxRoute(model);
+  if ("error" in route) throw new Error(route.error);
+  return route;
+}

package/src/workflows/cooldown.ts

@@ -15,7 +15,8 @@ function cooldownToMs(cooldown: CooldownConfig): number {
 /**
  * Check if a workflow should be skipped due to cooldown.
  * Returns true if:
- * - the last successful run finished within the cooldown window, OR
+ * - the last successful run finished within the cooldown window (skipped for
+ *   `from: "start"`), OR
  * - any run (including failed ones) started within the cooldown window.
  *
  * The second condition prevents runaway re-triggering when all runs fail
@@ -30,7 +31,7 @@ export async function shouldSkipCooldown(
   const now = Date.now();
 
   // Skip if last successful run finished within the cooldown window
-  const lastSuccess = await getLastSuccessfulRun(workflowId);
+  const lastSuccess = cooldown.from === "start" ? null : await getLastSuccessfulRun(workflowId);
   if (lastSuccess?.finishedAt) {
     const lastFinished = new Date(lastSuccess.finishedAt).getTime();
     if (now - lastFinished < cooldownMs) return true;

package/src/workflows/engine.ts

@@ -192,7 +192,7 @@ export async function startWorkflowExecution(
   const newRunId = crypto.randomUUID();
   const release = holdWorkflowRun(newRunId);
   try {
-    const { runId, created, preflightAlert } = await createRunWithInitialState(
+    const { runId, created, preflightAlert, status } = await createRunWithInitialState(
       workflow,
       triggerData,
       options,
@@ -204,7 +204,7 @@ export async function startWorkflowExecution(
       if (preflightAlert) await notifyAutomationPreflightFailure(preflight);
       return runId;
     }
-    if (initial.status === "skipped") return runId;
+    if (status === "skipped") return runId;
     telemetry.workflow("started", {
       workflowId: workflow.id,
       nodeCount: workflow.definition.nodes.length,
@@ -317,7 +317,12 @@ async function createRunWithInitialState(
   options: WorkflowExecutionOptions,
   initial: InitialRunState,
   runId: string,
-): Promise<{ runId: string; created: boolean; preflightAlert?: boolean }> {
+): Promise<{
+  runId: string;
+  created: boolean;
+  preflightAlert?: boolean;
+  status?: InitialRunState["status"];
+}> {
   return getDbClient().transaction(async () => {
     const { parentStepId } = options;
     const attempt = options.parentStepAttempt ?? 0;
@@ -328,6 +333,16 @@ async function createRunWithInitialState(
       const existingId = await getChildWorkflowRunId(parentStepId, attempt);
       if (existingId) return { runId: existingId, created: false };
     }
+    // The cooldown check before this transaction is only a fast path: two
+    // triggers can both pass it before either run exists. The write lock is
+    // held from BEGIN, across processes too, so this recheck sees every run
+    // committed before it and the losing trigger records a skipped run.
+    const state: InitialRunState =
+      !initial.status &&
+      workflow.cooldown &&
+      (await shouldSkipCooldown(workflow.id, workflow.cooldown))
+        ? { status: "skipped", error: "cooldown", finishedAt: new Date().toISOString() }
+        : initial;
     await createWorkflowRun({
       id: runId,
       workflowId: workflow.id,
@@ -340,16 +355,16 @@ async function createRunWithInitialState(
     });
     await updateWorkflowRun(
       runId,
-      initial.status
-        ? { status: initial.status, error: initial.error, finishedAt: initial.finishedAt }
-        : { context: initial.context },
+      state.status
+        ? { status: state.status, error: state.error, finishedAt: state.finishedAt }
+        : { context: state.context },
     );
     const preflightAlert =
-      initial.status === "failed" && initial.preflight
+      state.status === "failed" && state.preflight
         ? await isFirstWorkflowPreflightFailureToday(workflow.id, runId)
         : undefined;
-    await options.accept?.({ runId, skipped: initial.status === "skipped" });
-    return { runId, created: true, preflightAlert };
+    await options.accept?.({ runId, skipped: state.status === "skipped" });
+    return { runId, created: true, preflightAlert, status: state.status };
   });
 }