@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/be/db/session-tree.ts

@@ -16,8 +16,13 @@ export type SessionReadState = "unread" | "read" | "later" | "done";
 export interface SessionFilters {
   /** Restrict roots to these task sources. */
   source?: string[];
-  /** Leave out roots of these task sources (the sessions v2 source filter). */
+  /** Leave out roots of these task sources (the older sessions v2 source filter). */
   hideSource?: string[];
+  /**
+   * Keep only roots of these task sources (the sessions v2 source filter).
+   * Unlike `source`, an empty list matches no root.
+   */
+  showSource?: string[];
   /** Match root task text or title with a case-insensitive substring. */
   q?: string;
   /** Match the root requester, excluding NULL requester rows. */
@@ -50,13 +55,17 @@ export interface SessionFilters {
 
 type SqlFragment = { sql: string; params: (string | number | null)[] };
 
-/** Shared read-state rule with bound ISO timestamps for the list and tree. */
+/**
+ * Shared read-state rule with bound ISO timestamps for the list and tree.
+ * Done holds through agent activity (progress, status changes, child tasks):
+ * only `a.reopensDone`, counted in `sessionSummaryQuery`, brings it back.
+ */
 function sessionReadStateSql(now = new Date().toISOString()): SqlFragment {
   return {
     sql: `CASE
       WHEN s.id IS NULL THEN CASE WHEN a.lastActivityAt > ? THEN 'unread' ELSE 'read' END
       WHEN s.status = 'dismissed' THEN 'done'
-      WHEN s.status = 'done' THEN CASE WHEN a.lastActivityAt > s.lastUpdatedAt THEN 'unread' ELSE 'done' END
+      WHEN s.status = 'done' THEN CASE WHEN a.reopensDone > 0 THEN 'unread' ELSE 'done' END
       WHEN s.status = 'snoozed' THEN CASE WHEN s.snoozeUntil > ? THEN 'later' ELSE 'unread' END
       WHEN a.lastActivityAt > COALESCE(s.lastReadAt, s.lastUpdatedAt) THEN 'unread'
       ELSE 'read'
@@ -100,6 +109,14 @@ export function sessionRootFilter(opts: SessionFilters = {}): SqlFragment {
   const hidden = opts.hideSource?.filter(Boolean) ?? [];
   if (hidden.length)
     add({ sql: `r.source NOT IN (${hidden.map(() => "?").join(",")})`, params: hidden });
+  if (opts.showSource) {
+    const shown = opts.showSource.filter(Boolean);
+    add(
+      shown.length
+        ? { sql: `r.source IN (${shown.map(() => "?").join(",")})`, params: shown }
+        : { sql: "0", params: [] },
+    );
+  }
   if (opts.q?.trim()) {
     const like = `%${opts.q.trim().toLowerCase()}%`;
     add({
@@ -152,6 +169,35 @@ function hasSessionChainFilter(opts: SessionFilters): boolean {
 
 const runningSql = `latestStatus NOT IN (${TERMINAL_TASK_STATUSES.map((s) => `'${s}'`).join(",")})`;
 
+/**
+ * Sources of tasks that agents and the server create: delegation and scripts
+ * (`mcp`), follow-ups (`system`), deferred wake-ups (`schedule`) and workflow
+ * steps. Agents also set `requestedByUserId` explicitly on these, so a requester
+ * alone does not mark a human message.
+ */
+const AGENT_TASK_SOURCES = ["mcp", "system", "schedule", "workflow"] as const;
+
+/**
+ * Per chain row, over `chain` and the viewer's Done row `d`: whether the row
+ * needs the user since they marked the session Done. That is a human message
+ * (a task attributed to a person directly, not copied from its parent, from a
+ * human channel), a person's steering message on a chain task (steer or
+ * queue, not cancelled), or a pending approval, created after the Done mark.
+ * Steering `created_at` and the Done mark's `lastUpdatedAt` are both written
+ * as `%Y-%m-%dT%H:%M:%fZ`, so they compare as text.
+ */
+const reopensDoneSql = `(d.id IS NOT NULL AND (
+        (chain.createdAt > d.lastUpdatedAt
+          AND chain.requestedByUserId IS NOT NULL
+          AND chain.requestedByUserIdInherited = 0
+          AND COALESCE(chain.source, '') NOT IN (${AGENT_TASK_SOURCES.map((s) => `'${s}'`).join(",")}))
+        OR EXISTS (SELECT 1 FROM task_steering_messages sm
+          WHERE sm.task_id = chain.id AND sm.created_by_kind = 'user'
+            AND sm.status != 'cancelled' AND sm.created_at > d.lastUpdatedAt)
+        OR EXISTS (SELECT 1 FROM approval_requests ar
+          WHERE ar.sourceTaskId = chain.id AND ar.status = 'pending' AND ar.createdAt > d.lastUpdatedAt)
+      ))`;
+
 /**
  * A session starts at a parentTaskId IS NULL root. One recursive CTE computes
  * chain-wide latest activity for list ordering. Root filters precede recursion.
@@ -162,7 +208,7 @@ export function sessionSummaryQuery(opts: SessionFilters = {}): SqlFragment {
   const read = opts.viewer?.userId ? sessionReadStateSql(opts.now) : { sql: "NULL", params: [] };
   const params = [...root.params];
   if (opts.withUserId) params.push(opts.withUserId);
-  params.push(...read.params, opts.viewer?.userId ?? null);
+  params.push(opts.viewer?.userId ?? null, ...read.params, opts.viewer?.userId ?? null);
   const filters: string[] = [];
   if (opts.triage === "unread") filters.push("readState = 'unread'");
   else if (opts.triage === "later" || opts.triage === "done") {
@@ -182,19 +228,27 @@ export function sessionSummaryQuery(opts: SessionFilters = {}): SqlFragment {
   return {
     // SQLite takes the bare status from the row with MAX(lastUpdatedAt).
     // Keep this as the only MIN/MAX aggregate so status follows activity.
-    sql: `WITH RECURSIVE chain(root_id, id, lastUpdatedAt, status, requestedByUserId) AS (
-      SELECT r.id, r.id, r.lastUpdatedAt, r.status, r.requestedByUserId
+    // `d` is the viewer's Done row, so `reopensDone` can compare chain rows
+    // against the Done mark (SUM keeps MAX the only MIN/MAX aggregate).
+    sql: `WITH RECURSIVE chain(root_id, id, lastUpdatedAt, status, requestedByUserId,
+        createdAt, source, requestedByUserIdInherited) AS (
+      SELECT r.id, r.id, r.lastUpdatedAt, r.status, r.requestedByUserId,
+        r.createdAt, r.source, r.requestedByUserIdInherited
       FROM agent_tasks r WHERE ${root.sql}
       UNION ALL
-      SELECT c.root_id, t.id, t.lastUpdatedAt, t.status, t.requestedByUserId
+      SELECT c.root_id, t.id, t.lastUpdatedAt, t.status, t.requestedByUserId,
+        t.createdAt, t.source, t.requestedByUserIdInherited
       FROM chain c JOIN agent_tasks t ON t.parentTaskId = c.id
     ), agg AS (
-      SELECT root_id, COUNT(*) AS chainCount,
-        status AS latestStatus, MAX(lastUpdatedAt) AS lastActivityAt,
-        ${opts.withUserId ? "SUM(requestedByUserId = ?) AS withUser," : ""}
+      SELECT chain.root_id, COUNT(*) AS chainCount,
+        chain.status AS latestStatus, MAX(chain.lastUpdatedAt) AS lastActivityAt,
+        ${opts.withUserId ? "SUM(chain.requestedByUserId = ?) AS withUser," : ""}
         SUM(EXISTS (SELECT 1 FROM approval_requests ar
-          WHERE ar.sourceTaskId = chain.id AND ar.status = 'pending')) AS pendingApproval
-      FROM chain GROUP BY root_id
+          WHERE ar.sourceTaskId = chain.id AND ar.status = 'pending')) AS pendingApproval,
+        SUM(${reopensDoneSql}) AS reopensDone
+      FROM chain LEFT JOIN inbox_item_state d
+        ON d.userId = ? AND d.itemType = 'to_read' AND d.itemId = chain.root_id AND d.status = 'done'
+      GROUP BY chain.root_id
     ), state AS (
       SELECT a.*, ${read.sql} AS readState, s.snoozeUntil
       FROM agg a LEFT JOIN inbox_item_state s
@@ -341,7 +395,7 @@ export interface SessionTree {
 export async function getSessionTree(
   actor: { kind: "bypass" } | { kind: "user"; userId: string | null },
   now?: string,
-  opts: { mine?: boolean; hideSource?: string[] } = {},
+  opts: { mine?: boolean; hideSource?: string[]; showSource?: string[] } = {},
 ): Promise<SessionTree> {
   // No source filter in SQL: the source counts must include hidden sources,
   // so the filter menu can offer them back. The loop skips them instead.
@@ -373,6 +427,7 @@ export async function getSessionTree(
     sources: [],
   };
   const hidden = new Set(opts.hideSource);
+  const shown = opts.showSource ? new Set(opts.showSource) : null;
   const sources = new Map<string, number>();
   const groups = new Map<string, SessionTreeGroup>();
   const add = (section: SessionSectionCounts, row: (typeof rows)[number]) => {
@@ -383,7 +438,7 @@ export async function getSessionTree(
   };
   for (const row of rows) {
     sources.set(row.source, (sources.get(row.source) ?? 0) + 1);
-    if (hidden.has(row.source)) continue;
+    if (hidden.has(row.source) || (shown && !shown.has(row.source))) continue;
     const key = sessionGroupKey(row.key);
     const noGroup =
       key === "shared/" || (actor.kind === "user" && key === `personal/${actor.userId}/`);
@@ -425,7 +480,10 @@ const UNREAD_CURSOR = "1970-01-01T00:00:00.000Z";
  */
 export async function triageSessionList(
   userId: string,
-  filters: Pick<SessionFilters, "triage" | "noGroup" | "groupKey" | "mine" | "hideSource" | "now">,
+  filters: Pick<
+    SessionFilters,
+    "triage" | "noGroup" | "groupKey" | "mine" | "hideSource" | "showSource" | "now"
+  >,
   action: SessionListTriage,
 ): Promise<number> {
   const now = filters.now ?? new Date().toISOString();

package/src/be/db/skill-search.ts

@@ -0,0 +1,87 @@
+import { getDbClient } from "./runtime";
+
+// bm25() takes one weight per FTS column, in declaration order.
+// skills_fts (migration 239): skill_id (UNINDEXED), name, description, content.
+// skills_meta_fts (migration 241): skill_id (UNINDEXED), name, description.
+const SKILLS_FTS_BM25 = "bm25(skills_fts, 0.0, 3.0, 2.0, 1.0)";
+const SKILLS_META_FTS_BM25 = "bm25(skills_meta_fts, 0.0, 3.0, 2.0)";
+
+// FTS5 bm25 normalizes by the length of the whole row, so in skills_fts a
+// long SKILL.md body buries a name or description hit. skills_meta_fts holds
+// only those short fields; its score is added at this multiple. On the live
+// catalog, multiples from 2 to 10 rank the same; 3 is mid-range.
+const META_SCORE_MULTIPLE = 3;
+
+// English function words that agents put in natural-language queries. Each
+// one matches most of the catalog ("a" matched 189 of 189 skills) and only
+// adds noise to the ranking.
+const STOPWORDS = new Set(
+  (
+    "a an and are as at be but by can do does for from get got have how i if in into is it its " +
+    "me my need of on or our should so that the their them then there these this to use using " +
+    "want was we what when where which who why will with would you your"
+  ).split(" "),
+);
+
+/**
+ * Build a skills_fts MATCH expression from free text. Every term is quoted as
+ * an FTS5 string, so user text cannot inject operators (NEAR, AND, -, *, ^,
+ * column filters). Stopwords are dropped and the remaining terms are OR-ed:
+ * ranked recall, ordered by bm25. Returns null when no term is left, so the
+ * caller falls back to the substring match.
+ */
+export function buildSkillsFtsMatch(query: string): string | null {
+  const terms = query
+    .split(/[^\p{L}\p{N}_-]+/u)
+    .filter((term) => /[\p{L}\p{N}]/u.test(term) && !STOPWORDS.has(term.toLowerCase()))
+    .slice(0, 12);
+  if (terms.length === 0) return null;
+  return terms.map((term) => `"${term.replaceAll('"', '""')}"`).join(" OR ");
+}
+
+/**
+ * Enabled skills ranked by BM25: the skills_fts score (name 3, description 2,
+ * content 1) plus META_SCORE_MULTIPLE times the skills_meta_fts score (name 3,
+ * description 2). A skill whose name equals the whole query (case-insensitive)
+ * ranks first. Returns [] when the query has no indexable terms or the
+ * backend cannot run the FTS query, so the caller can fall back.
+ *
+ * `columns` is a select list over `skills`; it must not name a bare
+ * `skill_id` or `score`, which the joined `hits` and `meta` CTEs also expose.
+ */
+export async function searchSkillRowsRanked<T>(
+  query: string,
+  limit: number,
+  columns: string,
+): Promise<T[]> {
+  const match = buildSkillsFtsMatch(query);
+  if (!match) return [];
+  const exactName = query.trim();
+  try {
+    return await getDbClient().query<T>(
+      `WITH hits AS (
+         SELECT skill_id, ${SKILLS_FTS_BM25} AS score FROM skills_fts WHERE skills_fts MATCH ?
+       ),
+       meta AS (
+         SELECT skill_id, ${SKILLS_META_FTS_BM25} AS score
+         FROM skills_meta_fts WHERE skills_meta_fts MATCH ?
+       )
+       SELECT ${columns} FROM skills
+       LEFT JOIN hits ON hits.skill_id = skills.id
+       LEFT JOIN meta ON meta.skill_id = skills.id
+       WHERE skills.isEnabled = 1
+         AND (hits.skill_id IS NOT NULL OR lower(skills.name) = lower(?))
+       ORDER BY lower(skills.name) = lower(?) DESC,
+         COALESCE(hits.score, 0) + ${META_SCORE_MULTIPLE} * COALESCE(meta.score, 0) ASC,
+         skills.name ASC
+       LIMIT ?`,
+      [match, match, exactName, exactName, limit],
+    );
+  } catch (err) {
+    console.warn(
+      "[skills-fts] ranked query failed, using substring match:",
+      (err as Error).message,
+    );
+    return [];
+  }
+}

package/src/be/db/tasks/read.ts

@@ -196,12 +196,39 @@ type AgentTaskTimelineRow = Pick<
  * past it).
  */
 const TASK_PREVIEW_BYTES = 4 * (TASK_PREVIEW_LENGTH + 1);
-const TASK_PREVIEW_SQL = `substr(CAST(agent_tasks.task AS BLOB), 1, ${TASK_PREVIEW_BYTES}) AS task`;
+/**
+ * A leading `<sibling_tasks_in_progress>` block (`src/tasks/sibling-block.ts`)
+ * is generated context that can fill the whole preview, so the list row never
+ * reaches the ask. The preview starts after the block and the `\n\n`
+ * `prependSiblingBlock` puts after it. A block with no closing tag stays.
+ */
+const SIBLING_OPEN = "<sibling_tasks_in_progress>";
+const SIBLING_CLOSE = "</sibling_tasks_in_progress>";
+const TASK_BLOB = "CAST(agent_tasks.task AS BLOB)";
+const SIBLING_CLOSE_AT = `instr(${TASK_BLOB}, CAST('${SIBLING_CLOSE}' AS BLOB))`;
+const SIBLING_END = `(${SIBLING_CLOSE_AT} + ${SIBLING_CLOSE.length})`;
+const TASK_PREVIEW_START = `CASE
+    WHEN substr(${TASK_BLOB}, 1, ${SIBLING_OPEN.length}) = CAST('${SIBLING_OPEN}' AS BLOB)
+      AND ${SIBLING_CLOSE_AT} > 0
+    THEN ${SIBLING_END} + (substr(${TASK_BLOB}, ${SIBLING_END}, 2) = x'0a0a') * 2
+    ELSE 1 END`;
+const TASK_PREVIEW_SQL = `substr(${TASK_BLOB}, ${TASK_PREVIEW_START}, ${TASK_PREVIEW_BYTES}) AS task`;
 // ignoreBOM keeps a leading U+FEFF, which the full-text preview keeps too.
 const taskPreviewDecoder = new TextDecoder("utf-8", { ignoreBOM: true });
 
+/** What `TASK_PREVIEW_START` does in SQL, for a full-text row. */
+function skipSiblingBlock(text: string): string {
+  if (!text.startsWith(SIBLING_OPEN)) return text;
+  const close = text.indexOf(SIBLING_CLOSE);
+  if (close === -1) return text;
+  const end = close + SIBLING_CLOSE.length;
+  return text.slice(text.startsWith("\n\n", end) ? end + 2 : end);
+}
+
 function taskPreview(task: TaskPreviewSource["task"]): string {
-  const text = task instanceof Uint8Array ? taskPreviewDecoder.decode(task) : task;
+  // Bytes come from `TASK_PREVIEW_SQL`, which already skipped the block.
+  const text =
+    task instanceof Uint8Array ? taskPreviewDecoder.decode(task) : skipSiblingBlock(task ?? "");
   return dependencies.previewText(text, TASK_PREVIEW_LENGTH);
 }
 

package/src/be/db/tasks/write.ts

@@ -657,7 +657,15 @@ export async function overwriteTerminalTaskResultText(
   return row ? rowToAgentTask(row) : task;
 }
 
-export async function cancelTask(id: string, reason?: string): Promise<AgentTask | null> {
+/**
+ * `cascadeDependents: false` skips the dependents sweep for a caller that
+ * already knows no task depends on this one (a bulk cancel looks once).
+ */
+export async function cancelTask(
+  id: string,
+  reason?: string,
+  options: { cascadeDependents?: boolean } = {},
+): Promise<AgentTask | null> {
   const oldTask = await getTaskById(id);
   if (!oldTask) return null;
 
@@ -736,10 +744,12 @@ export async function cancelTask(id: string, reason?: string): Promise<AgentTask
       );
     }
 
-    try {
-      await dependencies.cascadeFailDependents(id, "cancelled");
-    } catch (err) {
-      console.error("[cancelTask] cascade-fail dependents error:", err);
+    if (options.cascadeDependents !== false) {
+      try {
+        await dependencies.cascadeFailDependents(id, "cancelled");
+      } catch (err) {
+        console.error("[cancelTask] cascade-fail dependents error:", err);
+      }
     }
   }
 

package/src/be/db/workflow-idempotency.ts

@@ -0,0 +1,183 @@
+import { getCurrentRequestUserId } from "../../utils/request-auth-context";
+import { openSealedJson, sealJson } from "../sealed-json";
+import { getDbClient } from "./runtime";
+
+/**
+ * Server-side `Idempotency-Key` records for workflow create and trigger.
+ *
+ * A record is written in the transaction that accepts the operation (the
+ * workflow insert, or the run insert with its initial state), so it exists if
+ * and only if the operation committed. Readers look it up before re-running
+ * any check that can change between attempts (enabled, cooldown, readiness,
+ * trigger schema) and replay the stored response instead.
+ */
+
+export type WorkflowIdempotencyOperation = "workflow.create" | "workflow.trigger";
+
+/** Who may replay a record: one caller, one operation, one target, one key. */
+export interface WorkflowIdempotencyScope {
+  /** Stable caller identity, e.g. `user:<id>`; never a credential value. */
+  principal: string;
+  operation: WorkflowIdempotencyOperation;
+  /** The triggered workflow id; empty for create. */
+  targetId: string;
+  /** The client's `Idempotency-Key` value. Stored only as a hash. */
+  key: string;
+}
+
+/** A claim for one request: its scope plus the fingerprint of what it asked for. */
+export interface WorkflowIdempotencyClaim extends WorkflowIdempotencyScope {
+  fingerprint: string;
+}
+
+export interface AcceptedWorkflowOperation {
+  fingerprint: string;
+  status: number;
+  /** The original response body; null once the workflow it names was deleted. */
+  body: unknown;
+  resourceDeletedAt: string | null;
+}
+
+/**
+ * The key was accepted for another request while this one was getting ready.
+ * Thrown inside the accepting transaction, so this request commits nothing;
+ * the caller looks the record up again and answers from it.
+ */
+export class IdempotencyKeyTakenError extends Error {
+  constructor() {
+    super("Idempotency-Key was accepted by a concurrent request");
+    this.name = "IdempotencyKeyTakenError";
+  }
+}
+
+type AcceptedRow = {
+  requestFingerprint: string;
+  responseStatus: number;
+  responseBody: string | null;
+  resourceDeletedAt: string | null;
+};
+
+function sha256(text: string): string {
+  const hasher = new Bun.CryptoHasher("sha256");
+  hasher.update(text);
+  return hasher.digest("hex");
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (!value || typeof value !== "object") return value;
+  // Code-unit order, not localeCompare: the fingerprint must not depend on the
+  // server's locale.
+  return Object.fromEntries(
+    Object.entries(value as Record<string, unknown>)
+      .filter(([, nested]) => nested !== undefined)
+      .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+      .map(([key, nested]) => [key, sortKeys(nested)]),
+  );
+}
+
+/**
+ * Fingerprint of an accepted request body. Object key order does not matter,
+ * array order does, and every value counts as sent (nothing is redacted first,
+ * so two requests that differ only in a secret never match). Only the hash is
+ * stored.
+ */
+export function workflowRequestFingerprint(
+  operation: WorkflowIdempotencyOperation,
+  body: unknown,
+): string {
+  return sha256(`${operation}\n${JSON.stringify(sortKeys(body ?? null))}`);
+}
+
+const SCOPE_WHERE = "principal = ? AND operation = ? AND targetId = ? AND keyHash = ?";
+
+function scopeParams(scope: WorkflowIdempotencyScope): string[] {
+  return [scope.principal, scope.operation, scope.targetId, sha256(scope.key)];
+}
+
+export async function findAcceptedWorkflowOperation(
+  scope: WorkflowIdempotencyScope,
+): Promise<AcceptedWorkflowOperation | null> {
+  const row = await getDbClient().get<AcceptedRow>(
+    `SELECT requestFingerprint, responseStatus, responseBody, resourceDeletedAt
+       FROM workflow_idempotency_keys WHERE ${SCOPE_WHERE}`,
+    scopeParams(scope),
+  );
+  if (!row) return null;
+  return {
+    fingerprint: row.requestFingerprint,
+    status: row.responseStatus,
+    body: row.responseBody === null ? null : openSealedJson(row.responseBody),
+    resourceDeletedAt: row.resourceDeletedAt,
+  };
+}
+
+/**
+ * Throw `IdempotencyKeyTakenError` when the scope already has a record. Inside
+ * the accepting transaction, call it before writing a resource whose insert
+ * could collide with the concurrent winner's (a unique workflow name), so the
+ * loser replays instead of failing on that constraint.
+ */
+export async function assertWorkflowIdempotencyKeyUnused(
+  scope: WorkflowIdempotencyScope,
+): Promise<void> {
+  const taken = await getDbClient().get(
+    `SELECT 1 FROM workflow_idempotency_keys WHERE ${SCOPE_WHERE}`,
+    scopeParams(scope),
+  );
+  if (taken) throw new IdempotencyKeyTakenError();
+}
+
+/**
+ * Record the accepted operation. Call it inside the transaction that creates
+ * the resource: a rollback drops both. Throws `IdempotencyKeyTakenError` when
+ * the scope already has a record (a concurrent request committed first); the
+ * unique index backs this across processes.
+ */
+export async function recordAcceptedWorkflowOperation(
+  claim: WorkflowIdempotencyClaim,
+  accepted: { workflowId: string; runId?: string; status: number; body: unknown },
+): Promise<void> {
+  await assertWorkflowIdempotencyKeyUnused(claim);
+  const actor = getCurrentRequestUserId() ?? null;
+  try {
+    await getDbClient().run(
+      `INSERT INTO workflow_idempotency_keys
+         (id, principal, operation, targetId, keyHash, requestFingerprint, workflowId, runId,
+          responseStatus, responseBody, createdAt, created_by, updated_by)
+       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      [
+        crypto.randomUUID(),
+        ...scopeParams(claim),
+        claim.fingerprint,
+        accepted.workflowId,
+        accepted.runId ?? null,
+        accepted.status,
+        sealJson(accepted.body),
+        new Date().toISOString(),
+        actor,
+        actor,
+      ],
+    );
+  } catch (err) {
+    if (err instanceof Error && err.message.includes("UNIQUE constraint failed")) {
+      throw new IdempotencyKeyTakenError();
+    }
+    throw err;
+  }
+}
+
+/**
+ * Turn every record naming `workflowId` into a tombstone: the stored response
+ * (which may carry the deleted workflow's definition) is cleared and the key
+ * stays taken, so a retry is told the resource is gone instead of creating or
+ * triggering anything again. Runs in the delete's transaction.
+ */
+export async function tombstoneWorkflowIdempotencyKeys(workflowId: string): Promise<void> {
+  await getDbClient().run(
+    `UPDATE workflow_idempotency_keys
+        SET responseBody = NULL, resourceDeletedAt = ?, updated_by = ?
+      WHERE workflowId = ? AND resourceDeletedAt IS NULL`,
+    [new Date().toISOString(), getCurrentRequestUserId() ?? null, workflowId],
+  );
+}