@desplega.ai/agent-swarm 1.74.1 → 1.74.3

package/openapi.json

@@ -2,7 +2,7 @@
   "openapi": "3.1.0",
   "info": {
     "title": "Agent Swarm API",
-    "version": "1.74.1",
+    "version": "1.74.3",
     "description": "Multi-agent orchestration API for Claude Code, Codex, and Gemini CLI. Enables task distribution, agent communication, and service discovery.\n\nMCP tools are documented separately in [MCP.md](./MCP.md)."
   },
   "servers": [
@@ -7343,6 +7343,33 @@
         }
       }
     },
+    "/api/trackers/jira/refresh": {
+      "post": {
+        "summary": "Force a Jira OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token via tracker-status / db-query and wants to recover without restarting the server or re-running 3LO.",
+        "tags": [
+          "Trackers"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Token refreshed; returns same shape as /status"
+          },
+          "409": {
+            "description": "Jira not connected (no refresh token stored)"
+          },
+          "500": {
+            "description": "Refresh failed (e.g. revoked grant, network error)"
+          },
+          "503": {
+            "description": "Jira integration not configured"
+          }
+        }
+      }
+    },
     "/api/trackers/jira/webhook/{token}": {
       "post": {
         "summary": "Receive Jira webhook events (URL-token authenticated). Phase 2 stub — Phase 3 fills in dispatch.",
@@ -7547,6 +7574,33 @@
         }
       }
     },
+    "/api/trackers/linear/refresh": {
+      "post": {
+        "summary": "Force a Linear OAuth token refresh and return the updated status payload. Useful when an agent observes an expired token and wants to recover without restarting the server or re-running OAuth.",
+        "tags": [
+          "Trackers"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Token refreshed; returns same shape as /status"
+          },
+          "409": {
+            "description": "Linear not connected (no refresh token stored)"
+          },
+          "500": {
+            "description": "Refresh failed"
+          },
+          "503": {
+            "description": "Linear integration not configured"
+          }
+        }
+      }
+    },
     "/api/trackers/linear/webhook": {
       "post": {
         "summary": "Handle Linear webhook events (signature-verified)",
@@ -7644,6 +7698,108 @@
         }
       }
     },
+    "/api/workflow-runs/{runId}/events": {
+      "post": {
+        "summary": "Fire a run-scoped event signal",
+        "description": "Emits an event onto the workflow event bus with `_runId` injected. Used by wait nodes in `event` mode with `scope: 'run'`. The body's `name` is the bus event name; `payload` is forwarded as-is plus `_runId`.",
+        "tags": [
+          "WorkflowEvents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string",
+              "format": "uuid"
+            },
+            "required": true,
+            "name": "runId",
+            "in": "path"
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "payload": {
+                    "type": "object",
+                    "additionalProperties": {}
+                  }
+                },
+                "required": [
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Event emitted"
+          },
+          "400": {
+            "description": "Validation error"
+          },
+          "404": {
+            "description": "Workflow run not found"
+          }
+        }
+      }
+    },
+    "/api/workflow-events": {
+      "post": {
+        "summary": "Fire a global workflow event signal",
+        "description": "Emits an event onto the workflow event bus. Wait-states with `scope: 'global'` may match. Run-scoped waits will NOT match this broadcast unless the payload carries a matching `workflowRunId`.",
+        "tags": [
+          "WorkflowEvents"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": {
+                "type": "object",
+                "properties": {
+                  "name": {
+                    "type": "string",
+                    "minLength": 1
+                  },
+                  "payload": {
+                    "type": "object",
+                    "additionalProperties": {}
+                  }
+                },
+                "required": [
+                  "name"
+                ]
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Event emitted"
+          },
+          "400": {
+            "description": "Validation error"
+          }
+        }
+      }
+    },
     "/api/workflows": {
       "get": {
         "summary": "List all workflows",
@@ -8651,6 +8807,14 @@
                       "continue"
                     ],
                     "description": "Update the definition-level onNodeFailure behavior"
+                  },
+                  "triggerSchema": {
+                    "type": [
+                      "object",
+                      "null"
+                    ],
+                    "additionalProperties": {},
+                    "description": "Optional JSON-Schema describing the expected trigger payload shape. Pass an object to set/replace; pass null to clear; omit to leave unchanged. Validator subset: type, required, properties, enum, const, items. Other JSON-Schema keywords are silently ignored."
                   }
                 }
               }
@@ -8917,6 +9081,40 @@
         }
       }
     },
+    "/api/workflows/{id}/trigger/validate": {
+      "post": {
+        "summary": "Validate a payload against the workflow's triggerSchema (no run)",
+        "tags": [
+          "Workflows"
+        ],
+        "security": [
+          {
+            "bearerAuth": []
+          }
+        ],
+        "parameters": [
+          {
+            "schema": {
+              "type": "string"
+            },
+            "required": true,
+            "name": "id",
+            "in": "path"
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Payload matches the workflow's triggerSchema (or workflow has none)"
+          },
+          "400": {
+            "description": "Payload failed validation; body matches the TriggerSchemaError contract"
+          },
+          "404": {
+            "description": "Workflow not found"
+          }
+        }
+      }
+    },
     "/api/workflows/{id}/runs": {
       "get": {
         "summary": "List runs for a workflow",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@desplega.ai/agent-swarm",
-  "version": "1.74.1",
+  "version": "1.74.3",
   "description": "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants",
   "license": "MIT",
   "author": "desplega.sh <contact@desplega.sh>",

package/src/be/db.ts

@@ -58,6 +58,9 @@ import type {
   User,
   VersionableField,
   VersionMeta,
+  WaitMode,
+  WaitStateRow,
+  WaitStateStatus,
   Workflow,
   WorkflowDefinition,
   WorkflowRun,
@@ -6781,6 +6784,281 @@ export function getExpiredPendingApprovals(): ApprovalRequest[] {
   return rows.map(rowToApprovalRequest);
 }
 
+// ============================================================================
+// Wait States (workflow `wait` node side table)
+// ============================================================================
+//
+// Mirrors approval-request helpers above. Time-mode rows carry `wakeUpAt`;
+// event-mode rows carry `eventName` + optional `eventFilter` (object or
+// arrow-fn body string) and optional `expiresAt`. `resolveWaitState` is the
+// race-safe transition gate — concurrent callers (poller + bus listener)
+// rely on `WHERE status='pending'` so only the first one wins.
+
+interface WaitStateRowDb {
+  id: string;
+  workflowRunId: string;
+  workflowRunStepId: string;
+  mode: string;
+  wakeUpAt: string | null;
+  eventName: string | null;
+  eventFilter: string | null;
+  expiresAt: string | null;
+  status: string;
+  firedPayload: string | null;
+  resolvedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
+  eventScope: string;
+}
+
+function rowToWaitState(row: WaitStateRowDb): WaitStateRow {
+  let parsedFilter: WaitStateRow["eventFilter"] = null;
+  if (row.eventFilter !== null) {
+    // eventFilter is stored as JSON: either an object or a JSON-encoded string.
+    try {
+      const decoded = JSON.parse(row.eventFilter);
+      // Accept both shapes — string filter (arrow-fn body) or object filter.
+      if (typeof decoded === "string" || (typeof decoded === "object" && decoded !== null)) {
+        parsedFilter = decoded as WaitStateRow["eventFilter"];
+      }
+    } catch {
+      parsedFilter = null;
+    }
+  }
+  return {
+    id: row.id,
+    workflowRunId: row.workflowRunId,
+    workflowRunStepId: row.workflowRunStepId,
+    mode: row.mode as WaitMode,
+    wakeUpAt: normalizeDate(row.wakeUpAt),
+    eventName: row.eventName,
+    eventFilter: parsedFilter,
+    expiresAt: normalizeDate(row.expiresAt),
+    status: row.status as WaitStateStatus,
+    firedPayload: row.firedPayload ? JSON.parse(row.firedPayload) : null,
+    resolvedAt: normalizeDate(row.resolvedAt),
+    createdAt: normalizeDateRequired(row.createdAt),
+    updatedAt: normalizeDateRequired(row.updatedAt),
+    eventScope: (row.eventScope as "run" | "global") ?? "run",
+  };
+}
+
+export interface CreateWaitStateInput {
+  id: string;
+  workflowRunId: string;
+  workflowRunStepId: string;
+  mode: WaitMode;
+  wakeUpAt?: string | null;
+  eventName?: string | null;
+  eventFilter?: Record<string, unknown> | string | null;
+  expiresAt?: string | null;
+  scope?: "run" | "global";
+}
+
+export function createWaitState(input: CreateWaitStateInput): WaitStateRow {
+  const now = new Date().toISOString();
+  const row = getDb()
+    .prepare<
+      WaitStateRowDb,
+      [
+        string,
+        string,
+        string,
+        string,
+        string | null,
+        string | null,
+        string | null,
+        string | null,
+        string,
+        string,
+        string,
+      ]
+    >(
+      `INSERT INTO wait_states
+         (id, workflowRunId, workflowRunStepId, mode, wakeUpAt, eventName, eventFilter, expiresAt, eventScope, createdAt, updatedAt)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+       RETURNING *`,
+    )
+    .get(
+      input.id,
+      input.workflowRunId,
+      input.workflowRunStepId,
+      input.mode,
+      input.wakeUpAt ?? null,
+      input.eventName ?? null,
+      input.eventFilter !== undefined && input.eventFilter !== null
+        ? JSON.stringify(input.eventFilter)
+        : null,
+      input.expiresAt ?? null,
+      input.scope ?? "run",
+      now,
+      now,
+    );
+  return rowToWaitState(row!);
+}
+
+export function getWaitStateById(id: string): WaitStateRow | null {
+  const row = getDb()
+    .prepare<WaitStateRowDb, [string]>("SELECT * FROM wait_states WHERE id = ?")
+    .get(id);
+  return row ? rowToWaitState(row) : null;
+}
+
+/**
+ * Idempotency lookup — mirrors `getApprovalRequestByStepId`. A re-execution of
+ * the same wait node finds its existing row instead of inserting a duplicate.
+ */
+export function getWaitStateByStepId(stepId: string): WaitStateRow | null {
+  const row = getDb()
+    .prepare<WaitStateRowDb, [string]>("SELECT * FROM wait_states WHERE workflowRunStepId = ?")
+    .get(stepId);
+  return row ? rowToWaitState(row) : null;
+}
+
+/**
+ * Scan for waits the poller should resume now:
+ *   - mode='time' with `wakeUpAt <= now`, OR
+ *   - mode='event' with non-null `expiresAt <= now` (timeout branch).
+ */
+export function getDueWaitStates(): WaitStateRow[] {
+  const rows = getDb()
+    .prepare<WaitStateRowDb, []>(
+      `SELECT * FROM wait_states
+       WHERE status = 'pending'
+         AND (
+           (mode = 'time' AND wakeUpAt IS NOT NULL
+              AND wakeUpAt <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+           OR
+           (mode = 'event' AND expiresAt IS NOT NULL
+              AND expiresAt <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+         )`,
+    )
+    .all();
+  return rows.map(rowToWaitState);
+}
+
+/**
+ * Distinct `eventName` values across pending event-mode waits. Used at boot
+ * by the wait-bus subscription system to register one listener per event name.
+ */
+export function getPendingEventWaitNames(): string[] {
+  const rows = getDb()
+    .prepare<{ eventName: string }, []>(
+      `SELECT DISTINCT eventName FROM wait_states
+       WHERE status = 'pending' AND eventName IS NOT NULL`,
+    )
+    .all();
+  return rows.map((r) => r.eventName);
+}
+
+/**
+ * Find pending event-mode waits matching `eventName`. Optional `runId` narrows
+ * to a single run for run-scoped signals. The Phase 3 listener applies the
+ * declarative/JS filter on top of this; the DB query is the cheap pre-filter.
+ */
+export function getPendingWaitsByEvent(eventName: string, runId?: string): WaitStateRow[] {
+  if (runId !== undefined) {
+    const rows = getDb()
+      .prepare<WaitStateRowDb, [string, string]>(
+        `SELECT * FROM wait_states
+         WHERE status = 'pending' AND mode = 'event' AND eventName = ? AND workflowRunId = ?`,
+      )
+      .all(eventName, runId);
+    return rows.map(rowToWaitState);
+  }
+  const rows = getDb()
+    .prepare<WaitStateRowDb, [string]>(
+      `SELECT * FROM wait_states
+       WHERE status = 'pending' AND mode = 'event' AND eventName = ?`,
+    )
+    .all(eventName);
+  return rows.map(rowToWaitState);
+}
+
+/**
+ * Atomic state transition: pending → fired|timeout. Returns `{updated: true}`
+ * iff the caller won the race (UPDATE matched a pending row). Concurrent
+ * callers see `{updated: false}` and should bail without further side effects.
+ */
+export function resolveWaitState(
+  id: string,
+  data: { status: Exclude<WaitStateStatus, "pending">; firedPayload?: unknown },
+): { updated: boolean; row: WaitStateRow | null } {
+  const now = new Date().toISOString();
+  const row = getDb()
+    .prepare<WaitStateRowDb, [string, string | null, string, string, string]>(
+      `UPDATE wait_states
+       SET status = ?, firedPayload = ?, resolvedAt = ?, updatedAt = ?
+       WHERE id = ? AND status = 'pending'
+       RETURNING *`,
+    )
+    .get(
+      data.status,
+      data.firedPayload !== undefined ? JSON.stringify(data.firedPayload) : null,
+      now,
+      now,
+      id,
+    );
+  return { updated: row !== null, row: row ? rowToWaitState(row) : null };
+}
+
+export interface StuckWaitRun {
+  runId: string;
+  stepId: string;
+  nodeId: string;
+  workflowId: string;
+  waitId: string;
+  waitMode: string;
+  waitStatus: string;
+  wakeUpAt: string | null;
+  expiresAt: string | null;
+  firedPayload: string | null;
+}
+
+/**
+ * Recovery scan: workflow runs in `waiting` whose wait_state is either
+ *   (a) already non-pending — signal arrived / timeout fired while down and
+ *       the in-memory bus event was lost, OR
+ *   (b) still pending but overdue (`wakeUpAt`/`expiresAt` already past).
+ *
+ * Case (b) overlaps with the wait-poller's first tick after boot, but explicit
+ * recovery avoids the up-to-5s startup latency window for stuck runs.
+ */
+export function getStuckWaitRuns(): StuckWaitRun[] {
+  return getDb()
+    .prepare<StuckWaitRun, []>(
+      `SELECT
+        wr.id as runId,
+        wrs.id as stepId,
+        wrs.nodeId,
+        wr.workflowId,
+        ws.id as waitId,
+        ws.mode as waitMode,
+        ws.status as waitStatus,
+        ws.wakeUpAt as wakeUpAt,
+        ws.expiresAt as expiresAt,
+        ws.firedPayload as firedPayload
+      FROM workflow_runs wr
+      JOIN workflow_run_steps wrs ON wrs.runId = wr.id AND wrs.status = 'waiting' AND wrs.nodeType = 'wait'
+      JOIN wait_states ws ON ws.workflowRunStepId = wrs.id
+      WHERE wr.status = 'waiting'
+        AND (
+          ws.status IN ('fired', 'timeout')
+          OR (
+            ws.status = 'pending'
+            AND (
+              (ws.wakeUpAt IS NOT NULL
+                AND ws.wakeUpAt <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+              OR
+              (ws.expiresAt IS NOT NULL
+                AND ws.expiresAt <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+            )
+          )
+        )`,
+    )
+    .all();
+}
+
 // ============================================================================
 // Skills
 // ============================================================================

package/src/be/migrations/049_wait_states.sql

@@ -0,0 +1,30 @@
+-- 049_wait_states.sql
+-- Wait Node side table for the workflow engine
+--
+-- Mirrors the approval_requests precedent (020_approval_requests.sql) for the
+-- async-pause-and-resume pattern. A `wait` workflow node pauses execution
+-- either for a fixed duration (mode='time', wakeUpAt) or until an external
+-- event arrives (mode='event', eventName + eventFilter, optional expiresAt).
+
+CREATE TABLE IF NOT EXISTS wait_states (
+  id TEXT PRIMARY KEY,
+  workflowRunId TEXT NOT NULL,
+  workflowRunStepId TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK (mode IN ('time', 'event')),
+  wakeUpAt DATETIME,                       -- mode='time'; NULL for event mode
+  eventName TEXT,                          -- mode='event'
+  eventFilter JSONB,                       -- mode='event'; flat key/val match or arrow-fn body
+  expiresAt DATETIME,                      -- mode='event' optional timeout
+  status TEXT NOT NULL DEFAULT 'pending'
+    CHECK (status IN ('pending', 'fired', 'timeout')),
+  firedPayload JSONB,                      -- payload that satisfied an event wait
+  resolvedAt DATETIME,
+  createdAt DATETIME DEFAULT CURRENT_TIMESTAMP,
+  updatedAt DATETIME DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_wait_states_step ON wait_states(workflowRunStepId);
+CREATE INDEX IF NOT EXISTS idx_wait_states_run ON wait_states(workflowRunId);
+CREATE INDEX IF NOT EXISTS idx_wait_states_wake ON wait_states(wakeUpAt) WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS idx_wait_states_expire ON wait_states(expiresAt) WHERE status = 'pending';
+CREATE INDEX IF NOT EXISTS idx_wait_states_event ON wait_states(eventName) WHERE status = 'pending';

package/src/be/migrations/050_wait_states_scope.sql

@@ -0,0 +1,19 @@
+-- 050_wait_states_scope.sql
+-- Add `scope` column to wait_states (Phase 3 of the wait-node plan).
+--
+-- The bus listener needs to know whether to enforce a run-id match between
+-- the incoming payload (`_runId` or `workflowRunId`) and the wait_state's
+-- `workflowRunId`. Storing it in a dedicated column keeps the matcher
+-- O(1)-fast (no JSON.parse on every event) and surfaces it in DB queries.
+--
+-- - 'run'    (default): listener enforces payload._runId === waitState.workflowRunId
+--                       (or payload.workflowRunId for built-in events from src/be/db.ts)
+-- - 'global':           listener skips the run-id check; any payload satisfying
+--                       the filter resolves the wait
+--
+-- Existing rows (all from Phase 2 — time mode only) get the default 'run'
+-- which is harmless because time-mode rows never go through the bus listener.
+
+ALTER TABLE wait_states
+  ADD COLUMN eventScope TEXT NOT NULL DEFAULT 'run'
+    CHECK (eventScope IN ('run', 'global'));

package/src/http/index.ts

@@ -46,6 +46,7 @@ import { handleTasks } from "./tasks";
 import { handleTrackers } from "./trackers";
 import { getPathSegments, parseQueryParams, setCorsHeaders } from "./utils";
 import { handleWebhooks } from "./webhooks";
+import { handleWorkflowEvents } from "./workflow-events";
 import { handleWorkflows } from "./workflows";
 
 // Last-line-of-defense: never let a single bad request (e.g. a SQLITE_BUSY
@@ -129,6 +130,7 @@ const httpServer = createHttpServer(async (req, res) => {
     () => handlePricing(req, res, pathSegments, queryParams, myAgentId),
     () => handleSchedules(req, res, pathSegments, queryParams, myAgentId),
     () => handleWorkflows(req, res, pathSegments, queryParams, myAgentId),
+    () => handleWorkflowEvents(req, res, pathSegments, queryParams),
     () => handleApprovalRequests(req, res, pathSegments, queryParams),
     () => handleConfig(req, res, pathSegments, queryParams),
     () => handleIntegrations(req, res, pathSegments),