@desplega.ai/agent-swarm 2.5.2 → 2.5.4

package/src/tests/approval-requests.test.ts

@@ -418,7 +418,7 @@ describe("Approval Requests", () => {
       expect(result).toBeNull();
     });
 
-    test("does not resolve a workflow approval after its run and HITL step are cancelled", async () => {
+    test("does not resolve a workflow approval after its run is cancelled", async () => {
       const workflow = await createWorkflow({
         name: `approval-cancel-${crypto.randomUUID()}`,
         definition: { nodes: [] },
@@ -432,11 +432,12 @@ describe("Approval Requests", () => {
         nodeId: "approval",
         nodeType: "human-in-the-loop",
       });
-      await updateWorkflowRun(runId, { status: "cancelled" });
-      await updateWorkflowRunStep(stepId, { status: "cancelled" });
+      // Asked while the run was live; the run was cancelled after, leaving
+      // the request pending (a cancelled step's trigger would close it).
       const approval = await createApprovalRequest(
         makeApprovalData({ workflowRunId: runId, workflowRunStepId: stepId }),
       );
+      await updateWorkflowRun(runId, { status: "cancelled" });
 
       const result = await resolveApprovalRequest(
         approval.id,
@@ -1864,15 +1865,17 @@ describe("Approval Requests", () => {
 
     test("cancel on a waiting run cancels the run, its step, and its task", async () => {
       const { runId, stepId, approvalId } = await makeRun("waiting");
+      // Linked directly: the engine binds a step's task while the step is
+      // still running, and this step is already parked.
       const task = await createTaskExtended("step task", {
         agentId: owner.id,
         source: "mcp",
         workflowRunId: runId,
-        workflowRunStepId: stepId,
       });
-      await getDbClient().run("UPDATE agent_tasks SET status = 'in_progress' WHERE id = ?", [
-        task.id,
-      ]);
+      await getDbClient().run(
+        "UPDATE agent_tasks SET status = 'in_progress', workflowRunStepId = ? WHERE id = ?",
+        [stepId, task.id],
+      );
 
       const res = await post(
         `/api/approval-requests/${approvalId}/cancel`,

package/src/tests/approval-sweeps.test.ts

@@ -223,15 +223,17 @@ describe("approval sweeps", () => {
 
     test("cancels the waiting run, its step, and its linked task", async () => {
       const { runId, stepId } = await makeRun("waiting");
+      // Linked directly: the engine binds a step's task while the step is
+      // still running, and this step is already parked.
       const task = await createTaskExtended("step task", {
         agentId,
         source: "mcp",
         workflowRunId: runId,
-        workflowRunStepId: stepId,
       });
-      await getDbClient().run("UPDATE agent_tasks SET status = 'in_progress' WHERE id = ?", [
-        task.id,
-      ]);
+      await getDbClient().run(
+        "UPDATE agent_tasks SET status = 'in_progress', workflowRunStepId = ? WHERE id = ?",
+        [stepId, task.id],
+      );
       const id = await makeRequest({ ageDays: 8, workflowRunId: runId, workflowRunStepId: stepId });
 
       const result = await autoCancelStaleApprovalRequests();
@@ -300,8 +302,10 @@ describe("approval sweeps", () => {
     });
 
     test("leaves a failed run as it is", async () => {
-      const { runId, stepId } = await makeRun("failed");
+      // The request was asked while the run was live; the run failed after.
+      const { runId, stepId } = await makeRun("waiting");
       const id = await makeRequest({ ageDays: 8, workflowRunId: runId, workflowRunStepId: stepId });
+      await updateWorkflowRun(runId, { status: "failed" });
 
       const result = await autoCancelStaleApprovalRequests();
 
@@ -415,13 +419,15 @@ describe("approval sweeps", () => {
     });
 
     test("times out a request on a completed run", async () => {
-      const { runId, stepId } = await makeRun("completed");
+      // The request was asked while the run was live; the run completed after.
+      const { runId, stepId } = await makeRun("waiting");
       const id = await makeRequest({
         ageDays: 0,
         expiresInMs: -60_000,
         workflowRunId: runId,
         workflowRunStepId: stepId,
       });
+      await updateWorkflowRun(runId, { status: "completed" });
       await timeoutExpiredApprovalRequests();
       expect((await getApprovalRequestById(id))!.status).toBe("timeout");
     });

package/src/tests/base-prompt.test.ts

@@ -490,7 +490,7 @@ describe("getBasePrompt: outputs section", () => {
     expect(result).toContain("## Outputs");
     expect(result).toContain(AGENT_FS_LINE);
     expect(result).toContain(
-      "For a file anyone outside the swarm opens, use an `agent-fs share-create` link; `AGENT_FS_LIVE_URL` links are for signed-in teammates.",
+      `Give people the live app link \`\${AGENT_FS_LIVE_URL}/file/~/<org>/<drive>/<path>\`. Make an \`agent-fs share-create\` link only when the requester asks for one or the reader has no agent-fs login.`,
     );
     expect(result).not.toContain(NO_AGENT_FS_LINE);
   });

package/src/tests/chat-sdk-inbound.test.ts

@@ -332,6 +332,26 @@ describe("Chat SDK inbound pipeline", () => {
     }
   });
 
+  test("a mention in a subscribed group gets 👀 before the flush, and the flush does not react again", async () => {
+    await postTelegramUpdate(telegramUpdate(group(-2991), "@swarm_test_bot first ask"));
+    await flushChatBuffers();
+    const ask = telegramUpdate(group(-2991), "@swarm_test_bot second ask");
+    await postTelegramUpdate(ask);
+    expect(reactionsOn(-2991, ask)).toEqual(["👀"]);
+    await flushChatBuffers();
+    expect(await chatTasks(-2991)).toHaveLength(2);
+    expect(reactionsOn(-2991, ask)).toEqual(["👀"]);
+  });
+
+  test("a !now mention in a subscribed group gets ⚡, not 👀", async () => {
+    await postTelegramUpdate(telegramUpdate(group(-2992), "@swarm_test_bot first ask"));
+    await flushChatBuffers();
+    const ask = telegramUpdate(group(-2992), "@swarm_test_bot !now second ask");
+    await postTelegramUpdate(ask);
+    expect(await chatTasks(-2992)).toHaveLength(2);
+    expect(reactionsOn(-2992, ask)).toEqual(["⚡"]);
+  });
+
   test("two asks back to back each anchor to their own message, not the parent's", async () => {
     const firstAsk = telegramUpdate(group(-2010), "@swarm_test_bot !now summarize the PR");
     await postTelegramUpdate(firstAsk);

package/src/tests/claude-hook-output.test.ts

@@ -82,7 +82,11 @@ afterAll(async () => {
   await rm(projectDir, { recursive: true, force: true });
 });
 
-async function runHook(event: Record<string, unknown>, taskId: string) {
+async function runHook(
+  event: Record<string, unknown>,
+  taskId: string,
+  extraEnv: Record<string, string> = {},
+) {
   const taskFile = join(projectDir, `task-${taskId}.json`);
   await Bun.write(
     taskFile,
@@ -92,6 +96,8 @@ async function runHook(event: Record<string, unknown>, taskId: string) {
     ...process.env,
     CLAUDE_PROJECT_DIR: projectDir,
     TASK_FILE: taskFile,
+    CONTEXT_BOUND_NOTE_TOKENS: undefined,
+    ...extraEnv,
   };
   return runChild(["bun", HOOK_PATH], {
     cwd: projectDir,
@@ -107,6 +113,9 @@ function parseSoleJson(stdout: string): Record<string, unknown> {
   return JSON.parse(trimmed) as Record<string, unknown>;
 }
 
+/** The note is off unless CONTEXT_BOUND_NOTE_TOKENS is set. */
+const noteOn = { CONTEXT_BOUND_NOTE_TOKENS: "200000" };
+
 const bashTouch = {
   tool_name: "Bash",
   tool_input: { command: "touch /tmp/probe" },
@@ -230,4 +239,73 @@ describe("claude hook stdout", () => {
     },
     CHILD_PROCESS_TEST_BUDGET_MS,
   );
+
+  test(
+    "worker context-bound note fires once as PostToolUse additionalContext",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const taskId = crypto.randomUUID();
+      await Bun.write(
+        join(projectDir, `task-${taskId}.json.context.json`),
+        JSON.stringify({ contextTokens: 250_000, model: "claude-opus-5-5" }),
+      );
+      const event = { hook_event_name: "PostToolUse", ...bashTouch, tool_response: {} };
+
+      const first = await runHook(event, taskId, noteOn);
+      const out = parseSoleJson(first.stdout) as { hookSpecificOutput: Record<string, string> };
+      expect(out.hookSpecificOutput.hookEventName).toBe("PostToolUse");
+      expect(out.hookSpecificOutput.additionalContext).toStartWith(
+        "Context is 250,000 tokens (25% of the 1,000,000-token window). Keep this task bounded",
+      );
+
+      const second = await runHook(event, taskId, noteOn);
+      expect(second.exitCode).toBe(0);
+      expect(second.stdout.trim()).toBe("");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS * 2,
+  );
+
+  test(
+    "a subagent tool call does not consume the context-bound note",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const taskId = crypto.randomUUID();
+      await Bun.write(
+        join(projectDir, `task-${taskId}.json.context.json`),
+        JSON.stringify({ contextTokens: 250_000, model: "made-up-model" }),
+      );
+      const event = { hook_event_name: "PostToolUse", ...bashTouch, tool_response: {} };
+
+      const child = await runHook({ ...event, agent_id: "child" }, taskId, noteOn);
+      expect(child.exitCode).toBe(0);
+      expect(child.stdout.trim()).toBe("");
+
+      // Unknown model: no window share rather than a percent of the 200k fallback.
+      const main = await runHook(event, taskId, noteOn);
+      const out = parseSoleJson(main.stdout) as { hookSpecificOutput: Record<string, string> };
+      expect(out.hookSpecificOutput.additionalContext).toStartWith(
+        "Context is 250,000 tokens. Keep this task bounded",
+      );
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS * 2,
+  );
+
+  test(
+    "the context-bound note is off when CONTEXT_BOUND_NOTE_TOKENS is unset",
+    async () => {
+      Object.assign(state, { isLead: false, cancelledTaskId: null, shouldBlockPolling: false });
+      const taskId = crypto.randomUUID();
+      await Bun.write(
+        join(projectDir, `task-${taskId}.json.context.json`),
+        JSON.stringify({ contextTokens: 900_000, model: "claude-opus-5-5" }),
+      );
+      const result = await runHook(
+        { hook_event_name: "PostToolUse", ...bashTouch, tool_response: {} },
+        taskId,
+      );
+      expect(result.exitCode).toBe(0);
+      expect(result.stdout.trim()).toBe("");
+    },
+    CHILD_PROCESS_TEST_BUDGET_MS,
+  );
 });

package/src/tests/claude-managed-adapter.test.ts

@@ -1,6 +1,7 @@
 import { afterAll, afterEach, beforeAll, describe, expect, test } from "bun:test";
 import { mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
+import { renderContextBoundNote } from "../prompts/context-bound-note";
 import { createProviderAdapter } from "../providers";
 import {
   ClaudeManagedAdapter,
@@ -13,6 +14,7 @@ import {
   getClaudeManagedModelPricing,
 } from "../providers/claude-managed-models";
 import type { ProviderEvent, ProviderSessionConfig } from "../providers/types";
+import { HELD_NOTE_TEXT, holdTemplateRender } from "./fixtures/held-template-render";
 
 // Stash + restore env vars so this file plays nicely with the rest of the
 // suite (other tests don't expect MANAGED_AGENT_ID / MANAGED_ENVIRONMENT_ID
@@ -1503,3 +1505,276 @@ describe("ClaudeManagedAdapter (Phase 6) — full happy-path integration", () =>
     expect(result.output).toBe("Read the file and here's what I found.");
   });
 });
+
+describe("ClaudeManagedAdapter — one-time context-bound note", () => {
+  const tmpLogDir = `/tmp/claude-managed-adapter-bound-note-${Date.now()}`;
+  let seq = 0;
+
+  beforeAll(() => {
+    mkdirSync(tmpLogDir, { recursive: true });
+    process.env.ANTHROPIC_API_KEY = "sk-test";
+    process.env.MANAGED_AGENT_ID = "agent_x";
+    process.env.MANAGED_ENVIRONMENT_ID = "env_x";
+  });
+
+  afterAll(() => {
+    rmSync(tmpLogDir, { recursive: true, force: true });
+  });
+
+  /** A main-thread model request whose prompt is `input + cacheRead + cacheWrite`. */
+  function requestEnd(input: unknown, cacheRead: unknown = 0, cacheWrite: unknown = 0) {
+    seq += 1;
+    return {
+      type: "span.model_request_end",
+      id: `req-${seq}`,
+      processed_at: "2026-01-01T00:00:00Z",
+      is_error: false,
+      model_request_start_id: `start-${seq}`,
+      model_usage: {
+        input_tokens: input,
+        output_tokens: 10,
+        cache_read_input_tokens: cacheRead,
+        cache_creation_input_tokens: cacheWrite,
+      },
+    };
+  }
+
+  function toolUse(kind: "agent.tool_use" | "agent.mcp_tool_use" = "agent.tool_use") {
+    seq += 1;
+    return {
+      type: kind,
+      id: `tu-${seq}`,
+      processed_at: "2026-01-01T00:00:00Z",
+      name: "read_file",
+      ...(kind === "agent.mcp_tool_use" ? { mcp_server_name: "agent-swarm" } : {}),
+      input: { path: `/tmp/${seq}` },
+    };
+  }
+
+  const idle = () => ({
+    type: "session.status_idle",
+    id: `idle-${++seq}`,
+    processed_at: "2026-01-01T00:00:00Z",
+    stop_reason: { type: "end_turn" },
+  });
+
+  /** Run a session over `events` and return the texts of every message sent after the prompt. */
+  async function runNotes(
+    events: Array<Record<string, unknown>>,
+    threshold: string,
+    onSend?: Parameters<typeof makeFakeClient>[0]["onSend"],
+    model?: string,
+  ) {
+    const spy = makeFakeClient({
+      streamEvents: async function* () {
+        for (const e of events) yield e;
+      },
+      onSend,
+    });
+    const adapter = new ClaudeManagedAdapter({ client: spy.client });
+    const session = await adapter.createSession(
+      tConfig({
+        logFile: join(tmpLogDir, `note-${++seq}.log`),
+        env: { CONTEXT_BOUND_NOTE_TOKENS: threshold },
+        ...(model ? { model } : {}),
+      }),
+    );
+    const result = await session.waitForCompletion();
+    // The note is rendered and sent off the event loop; let it land.
+    await Bun.sleep(150);
+    const notes = spy.sent.slice(1).map((sent) => {
+      const content = sent.events[0]?.content as Array<{ text?: string }> | undefined;
+      return { type: sent.events[0]?.type, text: content?.[0]?.text };
+    });
+    return { result, notes };
+  }
+
+  test("fires once when a tool call follows a request at the threshold, not again", async () => {
+    const { result, notes } = await runNotes(
+      [
+        requestEnd(150_000, 40_000, 10_000),
+        toolUse(),
+        requestEnd(240_000, 10_000, 0),
+        toolUse("agent.mcp_tool_use"),
+        requestEnd(260_000),
+        toolUse(),
+        idle(),
+      ],
+      "200000",
+    );
+    expect(result.isError).toBe(false);
+    expect(notes).toEqual([
+      { type: "user.message", text: await renderContextBoundNote(200_000, "claude-sonnet-4-6") },
+    ]);
+  });
+
+  test("the note shows the window share for a known model and omits it for an unknown one", async () => {
+    const noteFor = async (model: string) =>
+      (await runNotes([requestEnd(250_000), toolUse(), idle()], "200000", undefined, model)).notes;
+    const rest =
+      "Keep this task bounded: finish the current step, store-progress, and complete or defer instead of starting new exploration.";
+    expect(await noteFor("claude-sonnet-4-6")).toEqual([
+      {
+        type: "user.message",
+        text: `Context is 250,000 tokens (25% of the 1,000,000-token window). ${rest}`,
+      },
+    ]);
+    expect(await noteFor("made-up-model")).toEqual([
+      { type: "user.message", text: `Context is 250,000 tokens. ${rest}` },
+    ]);
+  });
+
+  test("no-op below the threshold, then fires once it is crossed", async () => {
+    const { notes } = await runNotes(
+      [requestEnd(199_999), toolUse(), requestEnd(205_000), toolUse(), idle()],
+      "200000",
+    );
+    expect(notes).toEqual([
+      { type: "user.message", text: await renderContextBoundNote(205_000, "claude-sonnet-4-6") },
+    ]);
+  });
+
+  test("off at 0 and when unset", async () => {
+    const events = () => [requestEnd(500_000), toolUse(), idle()];
+    expect((await runNotes(events(), "0")).notes).toEqual([]);
+    expect((await runNotes(events(), "")).notes).toEqual([]);
+    // Control: the same session with a threshold gets the note.
+    expect((await runNotes(events(), "200000")).notes).toHaveLength(1);
+  });
+
+  test("no note when the request ends the turn without a tool call", async () => {
+    expect((await runNotes([requestEnd(300_000), idle()], "200000")).notes).toEqual([]);
+    // Control: a tool call after the same request carries the note.
+    expect((await runNotes([requestEnd(300_000), toolUse(), idle()], "200000")).notes).toHaveLength(
+      1,
+    );
+  });
+
+  test("fails open on missing or corrupt usage", async () => {
+    const { result, notes } = await runNotes(
+      [
+        // Missing: a tool call before any request reported usage.
+        toolUse(),
+        // Corrupt: non-numeric usage fields.
+        requestEnd("lots", null, {}),
+        toolUse(),
+        requestEnd(Number.NaN),
+        toolUse(),
+        // Control: a valid request afterwards still gets the note.
+        requestEnd(210_000),
+        toolUse(),
+        idle(),
+      ],
+      "200000",
+    );
+    expect(result.isError).toBe(false);
+    expect(notes).toEqual([
+      { type: "user.message", text: await renderContextBoundNote(210_000, "claude-sonnet-4-6") },
+    ]);
+  });
+
+  test("fails open when sending the note rejects", async () => {
+    let sends = 0;
+    const { result, notes } = await runNotes(
+      [requestEnd(300_000), toolUse(), requestEnd(310_000), toolUse(), idle()],
+      "200000",
+      () => {
+        sends += 1;
+        if (sends > 1) throw new Error("send failed");
+      },
+    );
+    expect(result.isError).toBe(false);
+    // One attempt only: a failed send does not re-arm the note.
+    expect(notes).toHaveLength(1);
+  });
+
+  describe("note rendered late", () => {
+    const toolResult = (toolUseId: string) => ({
+      type: "agent.tool_result",
+      id: `tr-${++seq}`,
+      processed_at: "2026-01-01T00:00:00Z",
+      tool_use_id: toolUseId,
+      content: [],
+    });
+
+    /**
+     * Holds the render until the stream reaches `releaseAt`. Returns the
+     * `user.message` events sent after the prompt, read once the late render
+     * had time to land.
+     */
+    async function lateNotes(
+      releaseAt: "tool-open" | "tool-returned" | "idle" | "abort",
+    ): Promise<{ notes: unknown[]; isError: boolean }> {
+      const held = holdTemplateRender();
+      const tool = toolUse();
+      let unblock!: () => void;
+      const blocked = new Promise<void>((resolve) => {
+        unblock = resolve;
+      });
+      const spy = makeFakeClient({
+        streamEvents: async function* () {
+          yield requestEnd(300_000);
+          yield tool;
+          await held.requested;
+          if (releaseAt === "tool-open") {
+            held.release();
+            await Bun.sleep(50);
+          }
+          yield toolResult(tool.id);
+          if (releaseAt === "tool-returned") {
+            held.release();
+            await Bun.sleep(50);
+          }
+          if (releaseAt === "abort") await blocked;
+          yield idle();
+        },
+      });
+      try {
+        const session = await new ClaudeManagedAdapter({ client: spy.client }).createSession(
+          tConfig({
+            logFile: join(tmpLogDir, `late-${++seq}.log`),
+            env: { CONTEXT_BOUND_NOTE_TOKENS: "200000" },
+          }),
+        );
+        if (releaseAt === "abort") {
+          await held.requested;
+          await session.abort();
+          unblock();
+        }
+        const result = await session.waitForCompletion();
+        held.release();
+        await Bun.sleep(100);
+        const notes = spy.sent
+          .slice(1)
+          .filter((sent) => sent.events[0]?.type === "user.message")
+          .map((sent) => sent.events[0]);
+        return { notes, isError: result.isError };
+      } finally {
+        unblock();
+        held.stop();
+      }
+    }
+
+    test("control: a note ready while its tool call is open is sent", async () => {
+      const { notes, isError } = await lateNotes("tool-open");
+      expect(isError).toBe(false);
+      expect(notes).toEqual([
+        { type: "user.message", content: [{ type: "text", text: HELD_NOTE_TEXT }] },
+      ]);
+    });
+
+    test("dropped once the tool result is back and the final reply is pending", async () => {
+      expect((await lateNotes("tool-returned")).notes).toEqual([]);
+    });
+
+    test("dropped after the session went idle", async () => {
+      const { notes, isError } = await lateNotes("idle");
+      expect(isError).toBe(false);
+      expect(notes).toEqual([]);
+    });
+
+    test("dropped after abort", async () => {
+      expect((await lateNotes("abort")).notes).toEqual([]);
+    });
+  });
+});