@desplega.ai/agent-swarm 1.157.0 → 1.158.0

package/src/tests/workflow-tla-races.test.ts

@@ -0,0 +1,389 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { z } from "zod";
+import * as db from "../be/db";
+import {
+  closeDb,
+  createWorkflow,
+  createWorkflowRun,
+  deleteWorkflow,
+  getWorkflowRun,
+  getWorkflowRunStepsByRunId,
+  initDb,
+} from "../be/db";
+import type { WorkflowDefinition, WorkflowRunStep } from "../types";
+import { walkGraph } from "../workflows/engine";
+import { workflowEventBus } from "../workflows/event-bus";
+import {
+  BaseExecutor,
+  type ExecutorDependencies,
+  type ExecutorResult,
+} from "../workflows/executors/base";
+import { ExecutorRegistry } from "../workflows/executors/registry";
+import { recoverIncompleteRuns } from "../workflows/recovery";
+import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
+import { startRetryPoller, stopRetryPoller } from "../workflows/retry-poller";
+import {
+  completeTaskStepAndResolveSuccessors,
+  failStepAndRunIfWaiting,
+} from "../workflows/task-step-routing";
+import { interpolate } from "../workflows/template";
+
+// Counterexamples from the TLA+ model in specs/tla/workflows/. Each test calls
+// the production functions in the order of the TLC trace named in its title
+// (specs/tla/workflows/FINDINGS.md), against a temp SQLite DB. A barrier
+// executor holds a node "in flight" so a trace step that interleaves with a
+// running executor can be replayed deterministically.
+
+const TEST_DB_PATH = `./test-workflow-tla-races-${crypto.randomUUID()}.sqlite`;
+
+type Behavior =
+  | "ok"
+  | "fail"
+  | "async"
+  | { hold: Promise<void>; entered: () => void; async?: boolean };
+
+/** Scripted executor: each call for a node consumes the next behavior. */
+const plans = new Map<string, Behavior[]>();
+const calls: string[] = [];
+
+class ScriptedExecutor extends BaseExecutor<
+  typeof ScriptedExecutor.schema,
+  typeof ScriptedExecutor.outSchema
+> {
+  static readonly schema = z.object({});
+  static readonly outSchema = z.object({ node: z.string() });
+
+  readonly type = "scripted";
+  readonly mode = "instant" as const;
+  readonly configSchema = ScriptedExecutor.schema;
+  readonly outputSchema = ScriptedExecutor.outSchema;
+
+  protected async execute(
+    _config: z.infer<typeof ScriptedExecutor.schema>,
+    _context: Readonly<Record<string, unknown>>,
+    meta: { nodeId: string },
+  ): Promise<ExecutorResult<z.infer<typeof ScriptedExecutor.outSchema>>> {
+    calls.push(meta.nodeId);
+    let behavior = plans.get(meta.nodeId)?.shift() ?? "ok";
+    if (behavior === "fail") return { status: "failed", error: `${meta.nodeId} failed` };
+    if (typeof behavior === "object" && behavior.async) {
+      behavior.entered();
+      await behavior.hold;
+      behavior = "async";
+    }
+    if (behavior === "async") {
+      return {
+        status: "success",
+        async: true,
+        waitFor: "task.completed",
+        correlationId: crypto.randomUUID(),
+      } as ExecutorResult<z.infer<typeof ScriptedExecutor.outSchema>>;
+    }
+    if (typeof behavior === "object") {
+      behavior.entered();
+      await behavior.hold;
+    }
+    return { status: "success", output: { node: meta.nodeId } };
+  }
+}
+
+const deps: ExecutorDependencies = {
+  db: db as typeof import("../be/db"),
+  eventBus: workflowEventBus,
+  interpolate: (template, ctx) => interpolate(template, ctx).result,
+};
+const registry = new ExecutorRegistry();
+registry.register(new ScriptedExecutor(deps));
+
+const retry = { strategy: "static" as const, maxRetries: 1, baseDelayMs: 1, maxDelayMs: 1 };
+
+/** T fans out to A and B; with `converge`, both join on M. */
+function fanOut(converge: boolean): WorkflowDefinition {
+  return {
+    nodes: [
+      { id: "T", type: "scripted", config: {}, next: ["A", "B"] },
+      { id: "A", type: "scripted", config: {}, retry, ...(converge ? { next: "M" } : {}) },
+      { id: "B", type: "scripted", config: {}, retry, ...(converge ? { next: "M" } : {}) },
+      ...(converge ? [{ id: "M", type: "scripted", config: {} }] : []),
+    ],
+  };
+}
+
+const workflowIds: string[] = [];
+
+async function newRun(def: WorkflowDefinition) {
+  const workflow = await createWorkflow({
+    name: `tla-race-${crypto.randomUUID()}`,
+    definition: def,
+  });
+  workflowIds.push(workflow.id);
+  const runId = crypto.randomUUID();
+  await createWorkflowRun({ id: runId, workflowId: workflow.id, triggerType: "manual" });
+  const ctx: Record<string, unknown> = {};
+  const walk = (nodeIds: string[]) =>
+    walkGraph(
+      def,
+      runId,
+      ctx,
+      def.nodes.filter((n) => nodeIds.includes(n.id)),
+      registry,
+      workflow.id,
+    );
+  return { runId, ctx, walk };
+}
+
+/** Holds the executor until released; with `async`, it then dispatches a task. */
+function barrier(async = false) {
+  const entered = Promise.withResolvers<void>();
+  const release = Promise.withResolvers<void>();
+  const behavior: Behavior = { hold: release.promise, entered: entered.resolve, async };
+  return { behavior, entered: entered.promise, release: release.resolve };
+}
+
+async function stepsOf(runId: string, nodeId: string): Promise<WorkflowRunStep[]> {
+  return (await getWorkflowRunStepsByRunId(runId)).filter((s) => s.nodeId === nodeId);
+}
+
+async function untilStatus(runId: string, nodeId: string, status: string) {
+  for (let i = 0; i < 200; i++) {
+    const [step] = await stepsOf(runId, nodeId);
+    if (step?.status === status) return step;
+    await sleep(2);
+  }
+  throw new Error(`${nodeId} never reached ${status}`);
+}
+
+const callsOf = (nodeId: string) => calls.filter((n) => n === nodeId).length;
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+async function runPollerOnce() {
+  startRetryPoller(registry, 1);
+  try {
+    await sleep(60);
+  } finally {
+    stopRetryPoller();
+  }
+}
+
+beforeAll(() => initDb(TEST_DB_PATH));
+
+afterAll(async () => {
+  stopRetryPoller();
+  for (const id of workflowIds) await deleteWorkflow(id).catch(() => {});
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) await unlink(TEST_DB_PATH + suffix).catch(() => {});
+});
+
+describe("TLA+ workflow counterexamples", () => {
+  test("CX1: the retry poller does not re-execute a failed step of a cancelled run", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(false);
+    plans.set("A", ["fail", "ok"]);
+    const { runId, walk } = await newRun(def);
+
+    // XDedup/XRun/XFail: A fails with a retry left; B completes. Run stays running.
+    await walk(["T"]);
+    expect((await stepsOf(runId, "A"))[0]?.nextRetryAt).toBeTruthy();
+
+    // Cancel: the failed A row counts as terminal, so its nextRetryAt survives.
+    await cancelWorkflowRun(runId);
+    await sleep(5);
+
+    // P1..P9: the poller selects A with no run filter and re-executes it.
+    await runPollerOnce();
+
+    expect(callsOf("A")).toBe(1);
+    expect((await getWorkflowRun(runId))?.status).toBe("cancelled");
+  });
+
+  test("CX2: a user retry does not re-execute a branch the live walk is still running", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(true);
+    const holdA = barrier();
+    plans.set("A", [holdA.behavior, "ok"]);
+    plans.set("B", ["async", "async"]);
+    const { runId, walk } = await newRun(def);
+
+    // Initial walk: B dispatches async (waiting), A is in flight.
+    const initial = walk(["T"]);
+    await holdA.entered;
+    const stepB = await untilStatus(runId, "B", "waiting");
+
+    // EF: B's task fails -> run failed.
+    await failStepAndRunIfWaiting(stepB!.id, runId, "task failed");
+    expect((await getWorkflowRun(runId))?.status).toBe("failed");
+
+    // U1/U2: the user retries; findReadyNodes returns A because it is not completed.
+    await retryFailedRun(runId, registry);
+    holdA.release();
+    await initial;
+
+    expect(callsOf("A")).toBe(1);
+  });
+
+  test("CX2: a user retry does not re-dispatch a branch whose waiting checkpoint lost to the run failing", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(true);
+    const holdA = barrier(true);
+    plans.set("A", [holdA.behavior, "async"]);
+    plans.set("B", ["async", "async"]);
+    const { runId, walk } = await newRun(def);
+
+    // XRun(A): A is dispatching its task while B waits on its own.
+    const initial = walk(["T"]);
+    await holdA.entered;
+    const stepB = await untilStatus(runId, "B", "waiting");
+
+    // EF: B's task fails -> run failed. XCkWait(A): the checkpoint CAS sees a
+    // failed run, so A's row stays `running` with its task out.
+    await failStepAndRunIfWaiting(stepB!.id, runId, "task failed");
+    holdA.release();
+    await initial;
+    expect((await stepsOf(runId, "A"))[0]?.status).toBe("running");
+
+    // U1/U2: the retry must not dispatch A a second time.
+    await retryFailedRun(runId, registry);
+
+    expect(callsOf("A")).toBe(1);
+    expect(await stepsOf(runId, "A")).toHaveLength(1);
+  });
+
+  test("CX3: an async branch completing does not fire the join while a sibling branch is still executing", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(true);
+    const holdA = barrier();
+    plans.set("A", [holdA.behavior]);
+    plans.set("B", ["async"]);
+    const { runId, ctx, walk } = await newRun(def);
+
+    const initial = walk(["T"]);
+    await holdA.entered;
+    const stepB = await untilStatus(runId, "B", "waiting");
+
+    // E2: B's task completes; the handler claims B and walks its successor M.
+    const routing = await completeTaskStepAndResolveSuccessors(
+      def,
+      runId,
+      stepB!,
+      { node: "B" },
+      ctx,
+    );
+    expect(routing.claimed).toBe(true);
+    await walk(routing.successors.map((n) => n.id));
+
+    const mBeforeA = callsOf("M");
+    const statusBeforeA = (await getWorkflowRun(runId))?.status;
+    holdA.release();
+    await initial;
+
+    expect(mBeforeA).toBe(0);
+    expect(statusBeforeA).not.toBe("completed");
+  });
+
+  test("CX4: two branch completions racing to the join execute it once", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(true);
+    plans.set("A", ["async"]);
+    plans.set("B", ["async"]);
+    const { runId, ctx, walk } = await newRun(def);
+
+    await walk(["T"]);
+    const [stepA] = await stepsOf(runId, "A");
+    const [stepB] = await stepsOf(runId, "B");
+
+    // E2, E2: both handlers claim their step before either walks M.
+    const ra = await completeTaskStepAndResolveSuccessors(def, runId, stepA!, { node: "A" }, ctx);
+    const rb = await completeTaskStepAndResolveSuccessors(def, runId, stepB!, { node: "B" }, ctx);
+    await Promise.all([walk(ra.successors.map((n) => n.id)), walk(rb.successors.map((n) => n.id))]);
+
+    expect(callsOf("M")).toBe(1);
+    expect(await stepsOf(runId, "M")).toHaveLength(1);
+  });
+
+  test("CX5: heartbeat recovery leaves a step that is pending retry to the retry poller", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(false);
+    plans.set("A", ["fail", "ok", "ok"]);
+    const { runId, walk } = await newRun(def);
+
+    // A fails with a retry pending; B completes; the walk ends with the run running.
+    await walk(["T"]);
+    expect((await getWorkflowRun(runId))?.status).toBe("running");
+
+    // H1..H3: recovery sees a running, idle run and re-walks A (findReadyNodes).
+    await recoverIncompleteRuns(registry);
+    // With A excluded nothing is ready, and recovery must not complete the run
+    // while A's retry is pending.
+    expect((await getWorkflowRun(runId))?.status).toBe("running");
+    await sleep(5);
+    // P1..P6: the poller retries the original failed A row.
+    await runPollerOnce();
+
+    // One original attempt plus one retry.
+    expect(callsOf("A")).toBe(2);
+  });
+
+  test("CX6: heartbeat recovery does not walk a run whose trigger is still resolving inputs", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(false);
+    const holdT = barrier();
+    plans.set("T", [holdT.behavior, "ok"]);
+
+    // IStart: startWorkflowExecution has committed the run as `running` and is
+    // awaiting resolveRenderedWorkflowInputs, so no walk is registered yet.
+    const { runId, walk } = await newRun(def);
+
+    // H1..H3: the sweep sees a running, idle run with no steps and walks T.
+    const recovery = recoverIncompleteRuns(registry);
+    await holdT.entered;
+
+    // IWalk: input resolution finishes and the trigger's own walk starts T.
+    await walk(["T"]);
+    holdT.release();
+    await recovery;
+
+    expect(callsOf("T")).toBe(1);
+    expect(await stepsOf(runId, "T")).toHaveLength(1);
+  });
+
+  test("CX7: the walk finalizer does not complete a run while the retry poller is executing a step", async () => {
+    plans.clear();
+    calls.length = 0;
+    const def = fanOut(false);
+    const holdB = barrier();
+    const holdA = barrier();
+    plans.set("A", ["fail", holdA.behavior]);
+    plans.set("B", [holdB.behavior]);
+    const { runId, walk } = await newRun(def);
+
+    // XFail: A fails with a retry pending while B is still executing.
+    const initial = walk(["T"]);
+    await holdB.entered;
+    await untilStatus(runId, "A", "failed");
+    await sleep(5);
+
+    // P1..P5: the poller claims A and is executing it.
+    startRetryPoller(registry, 1);
+    try {
+      await holdA.entered;
+      // XCkOk/WFinal: B finishes and the walk finalizes with A running.
+      holdB.release();
+      await initial;
+      const statusWhileARuns = (await getWorkflowRun(runId))?.status;
+      holdA.release();
+      await sleep(20);
+      expect(statusWhileARuns).not.toBe("completed");
+    } finally {
+      holdA.release();
+      stopRetryPoller();
+    }
+  });
+});

package/src/tests/workflow-validation-port-routing.test.ts

@@ -8,7 +8,8 @@ import {
   getWorkflowRunStepsByRunId,
   initDb,
 } from "../be/db";
-import type { Workflow, WorkflowDefinition } from "../types";
+import type { Workflow, WorkflowDefinition, WorkflowNode } from "../types";
+import { loadCompletedStepRouting } from "../workflows/completed-step-routing";
 import { startWorkflowExecution } from "../workflows/engine";
 import { workflowEventBus } from "../workflows/event-bus";
 import {
@@ -47,6 +48,28 @@ class ObjectOutputExecutor extends BaseExecutor<
   }
 }
 
+/**
+ * Mimics the `script` / `swarm-script` executors: always emits `nextPort: "success"`.
+ */
+class SuccessPortExecutor extends BaseExecutor<
+  typeof SuccessPortExecutor.schema,
+  typeof SuccessPortExecutor.outSchema
+> {
+  static readonly schema = z.object({ approved: z.boolean() });
+  static readonly outSchema = z.object({ approved: z.boolean() });
+
+  readonly type = "success-port";
+  readonly mode = "instant" as const;
+  readonly configSchema = SuccessPortExecutor.schema;
+  readonly outputSchema = SuccessPortExecutor.outSchema;
+
+  protected async execute(
+    config: z.infer<typeof SuccessPortExecutor.schema>,
+  ): Promise<ExecutorResult<z.infer<typeof SuccessPortExecutor.outSchema>>> {
+    return { status: "success", output: { approved: config.approved }, nextPort: "success" };
+  }
+}
+
 /**
  * Executor that mimics an agent-task review output shape.
  * Used for regression coverage around aliased property-match fields.
@@ -101,6 +124,7 @@ function createTestRegistry(): ExecutorRegistry {
   const registry = new ExecutorRegistry();
   registry.register(new ObjectOutputExecutor(mockDeps));
   registry.register(new ReviewOutputExecutor(mockDeps));
+  registry.register(new SuccessPortExecutor(mockDeps));
   registry.register(new NoopExecutor(mockDeps));
   registry.register(new PropertyMatchExecutor(mockDeps));
   return registry;
@@ -400,3 +424,91 @@ describe("Validation Port Routing", () => {
     expect(nodeIds).toContain("after-check");
   });
 });
+
+describe("Validation port routing when the executor emits its own port", () => {
+  function makeScriptLikeWorkflow(
+    approved: boolean,
+    next: WorkflowNode["next"],
+    withValidation = true,
+  ): WorkflowDefinition {
+    return {
+      nodes: [
+        {
+          id: "check",
+          type: "success-port",
+          config: { approved },
+          next,
+          ...(withValidation
+            ? {
+                validation: {
+                  executor: "property-match",
+                  config: {
+                    conditions: [{ field: "check.approved", op: "eq", value: true }],
+                  },
+                  mustPass: false,
+                },
+              }
+            : {}),
+        },
+        { id: "on-pass", type: "noop", config: {} },
+        { id: "on-fail", type: "noop", config: {} },
+        { id: "on-success", type: "noop", config: {} },
+      ],
+    };
+  }
+
+  async function runAndCollect(def: WorkflowDefinition) {
+    const workflow = await makeWorkflow(def);
+    const runId = await startWorkflowExecution(workflow, {}, registry);
+    const steps = await getWorkflowRunStepsByRunId(runId);
+    return { workflow, runId, steps, nodeIds: steps.map((s) => s.nodeId) };
+  }
+
+  test('script-like node + validation pass → "pass" port, checkpointed for resume', async () => {
+    const { workflow, runId, steps, nodeIds } = await runAndCollect(
+      makeScriptLikeWorkflow(true, { pass: "on-pass", fail: "on-fail" }),
+    );
+
+    expect(nodeIds).toContain("on-pass");
+    expect(nodeIds).not.toContain("on-fail");
+    expect(steps.find((s) => s.nodeId === "check")!.nextPort).toBe("pass");
+
+    // Recovery / resume rebuild active edges from the checkpointed nextPort.
+    const { activeEdges } = await loadCompletedStepRouting(
+      workflow.definition,
+      runId,
+      new Set(["check"]),
+    );
+    expect([...activeEdges]).toEqual(["check→on-pass"]);
+  });
+
+  test('script-like node + validation fail (mustPass: false) → "fail" port', async () => {
+    const { steps, nodeIds } = await runAndCollect(
+      makeScriptLikeWorkflow(false, { pass: "on-pass", fail: "on-fail" }),
+    );
+
+    expect(nodeIds).toContain("on-fail");
+    expect(nodeIds).not.toContain("on-pass");
+    expect(steps.find((s) => s.nodeId === "check")!.nextPort).toBe("fail");
+  });
+
+  test("executor port that is a key of next stays authoritative over validation", async () => {
+    const { steps, nodeIds } = await runAndCollect(
+      makeScriptLikeWorkflow(false, { success: "on-success", fail: "on-fail" }),
+    );
+
+    expect(nodeIds).toContain("on-success");
+    expect(nodeIds).not.toContain("on-fail");
+    expect(steps.find((s) => s.nodeId === "check")!.nextPort).toBe("success");
+  });
+
+  test("node without validation keeps the executor port", async () => {
+    const { steps, nodeIds } = await runAndCollect(
+      makeScriptLikeWorkflow(true, { pass: "on-pass", fail: "on-fail" }, false),
+    );
+
+    expect(nodeIds).not.toContain("on-pass");
+    expect(nodeIds).not.toContain("on-fail");
+    expect(steps.find((s) => s.nodeId === "check")!.nextPort).toBe("success");
+  });
+});

package/src/tools/cancel-approval-request.ts

@@ -0,0 +1,57 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { getAgentById } from "@/be/db";
+import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
+import { cancelApprovalRequest } from "@/workflows/approval-cancel";
+
+export const cancelApprovalRequestInputSchema = z.object({
+  requestId: z.uuid().describe("The ID of the approval request to cancel."),
+  reason: z.string().max(500).optional().describe("Reason for cancellation."),
+});
+
+export const cancelApprovalRequestOutputSchema = swarmToolOutputSchema({
+  yourAgentId: z.string().optional(),
+  approvalRequest: z.looseObject({}).optional(),
+  alreadyCancelled: z.boolean().optional(),
+  runCancelled: z.boolean().optional(),
+});
+
+export const registerCancelApprovalRequestTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "cancel-approval-request",
+    {
+      title: "Cancel approval request",
+      description:
+        "Cancel a pending approval request by id. Allowed for a lead agent, or for the agent that owns the request's source task. If the request gates a running or waiting workflow run, that run is cancelled too. A request whose explicit timeout passed is already 'timeout' and cannot be cancelled.",
+      annotations: { destructiveHint: true },
+      inputSchema: cancelApprovalRequestInputSchema,
+      outputSchema: cancelApprovalRequestOutputSchema,
+    },
+    async ({ requestId, reason }, info) => {
+      if (!info.agentId) {
+        return toolErr('Agent ID not found. Set the "X-Agent-ID" header.');
+      }
+      const agent = await getAgentById(info.agentId);
+      const result = await cancelApprovalRequest({
+        id: requestId,
+        reason,
+        principal: { kind: "agent", agentId: info.agentId, isLead: agent?.isLead ?? false },
+        resolvedBy: info.agentId,
+        source: "mcp",
+      });
+      if (!result.ok) {
+        return toolErr(result.message, { data: { yourAgentId: info.agentId } });
+      }
+      const data = {
+        yourAgentId: info.agentId,
+        approvalRequest: result.request,
+        alreadyCancelled: result.alreadyCancelled,
+        runCancelled: result.runCancelled,
+      };
+      const message = result.alreadyCancelled
+        ? `Approval request "${requestId}" was already cancelled.`
+        : `Approval request "${requestId}" cancelled${result.runCancelled ? ", and its workflow run with it" : ""}.`;
+      return toolOk(message, { data, details: JSON.stringify(data, null, 2) });
+    },
+  );
+};

package/src/tools/memory-search.ts

@@ -146,6 +146,7 @@ export const registerMemorySearchTool = (server: McpServer) => {
               ranked.map((r) => ({
                 memoryId: r.id,
                 similarity: r.similarity,
+                relevance: r.rawSimilarity,
                 retrievalSource: r.retrievalSource,
               })),
               requestInfo.sessionId,

package/src/tools/request-human-input.ts

@@ -37,7 +37,7 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
       title: "Request human input",
       annotations: { destructiveHint: false },
       description:
-        "Create an approval request that pauses until a human responds. " +
+        "Create an approval request and return at once with the request id and URL. The answer arrives later as a hitl-follow-up task. " +
         "Supports multiple question types: approval (yes/no), text, single-select, " +
         "multi-select, and boolean. Returns the request ID and URL for the human to respond.",
       inputSchema: z.object({
@@ -48,7 +48,9 @@ export const registerRequestHumanInputTool = (server: McpServer) => {
           .int()
           .min(1)
           .optional()
-          .describe("Timeout in seconds (auto-rejects on timeout)"),
+          .describe(
+            "Seconds until the request expires. After that the request becomes 'timeout' and you get a hitl-follow-up task. A request with no timeout is cancelled after APPROVAL_REQUEST_AUTO_CANCELLATION_DAYS days (default 7).",
+          ),
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),

package/src/tools/send-task.ts

@@ -409,6 +409,10 @@ export async function sendTaskHandler(
     slackUserId,
     overrideSlackContext,
     followUpConfig,
+    // A delegation with parentTaskId is new work and starts without the
+    // parent's followUpConfig. A `resume` re-delegation (the reroute-decision
+    // template) continues the parent's work, so it keeps it.
+    inheritParentFollowUpConfig: taskType === "resume",
     outputSchema,
     routingReason: effectiveRoutingReason,
     routingSource: effectiveRoutingSource,

package/src/tools/templates.ts

@@ -110,6 +110,25 @@ Continue your work based on the human's input.`,
   category: "task_lifecycle",
 });
 
+registerTemplate({
+  eventType: "hitl.timeout",
+  header: "",
+  defaultBody: `Your approval request ({{request_id}}) timed out with no answer.
+
+Title: {{title}}
+Deadline: {{expires_at}}
+Reason: {{reason}}
+
+No human responded before the deadline. Decide how to continue without this input.`,
+  variables: [
+    { name: "request_id", description: "The approval request ID" },
+    { name: "title", description: "Title of the approval request" },
+    { name: "expires_at", description: "The deadline that passed, ISO 8601" },
+    { name: "reason", description: "The resolutionReason stored on the request" },
+  ],
+  category: "task_lifecycle",
+});
+
 registerTemplate({
   eventType: "task.worker.failed",
   header: "",

package/src/tools/tool-config.ts

@@ -143,8 +143,9 @@ export const DEFERRED_TOOLS = new Set([
   // Metrics (1)
   "create_metric",
 
-  // Approval Requests (1)
+  // Approval Requests (2)
   "request-human-input",
+  "cancel-approval-request",
 
   // Skills (12)
   "skill-create",

package/src/tools/workflows/list-workflow-runs.ts

@@ -85,6 +85,7 @@ export async function listWorkflowRunsHandler({
       status,
       limit,
       offset,
+      includeContext,
     });
     const resultRuns = includeContext ? runs : runs.map(slimRun);
     return toolOk(`Found ${runs.length} run(s) at offset ${page.offset} (${page.total} total).`, {