@desplega.ai/agent-swarm 2.2.0 → 2.3.0

package/src/tests/inbox-state.test.ts

@@ -0,0 +1,167 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { createServer, type Server } from "node:http";
+import {
+  closeDb,
+  createUser,
+  getDbClient,
+  initDb,
+  listInboxState,
+  upsertInboxState,
+} from "../be/db";
+import { handleInboxState } from "../http/inbox-state";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { listenOnFreePort } from "./test-net";
+
+const TEST_DB_PATH = "./test-inbox-state.sqlite";
+const earlier = "2026-01-01T00:00:00.000Z";
+const later = "2026-02-01T00:00:00.000Z";
+let userId: string;
+let server: Server;
+let baseUrl: string;
+
+beforeAll(async () => {
+  initDb(TEST_DB_PATH);
+  userId = (await createUser({ name: "Inbox User", email: "inbox-state@example.com" })).id;
+  server = createServer(async (req, res) => {
+    const url = req.url ?? "";
+    if (await handleInboxState(req, res, getPathSegments(url), parseQueryParams(url))) return;
+    res.writeHead(404).end();
+  });
+  baseUrl = `http://127.0.0.1:${await listenOnFreePort(server)}`;
+});
+
+afterAll(async () => {
+  await new Promise<void>((resolve) => server.close(() => resolve()));
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    const file = Bun.file(`${TEST_DB_PATH}${suffix}`);
+    if (await file.exists()) await file.delete();
+  }
+});
+
+async function patch(path: string, body: Record<string, unknown>) {
+  return fetch(`${baseUrl}/api/inbox-state${path}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ userId, ...body }),
+  });
+}
+
+describe("inbox read cursor", () => {
+  test("sets, preserves, moves back, and clears the cursor independently of sticky readAt", async () => {
+    const item = {
+      userId,
+      itemType: "to_read" as const,
+      itemId: "cursor",
+      status: "open" as const,
+    };
+    const initial = await upsertInboxState(item);
+    expect(initial.lastReadAt).toBeUndefined();
+    const set = await upsertInboxState({ ...item, readAt: earlier, lastReadAt: later });
+    expect(set.lastReadAt).toBe(later);
+    expect((await upsertInboxState({ ...item, readAt: later })).lastReadAt).toBe(later);
+    const movedBack = await upsertInboxState({ ...item, readAt: later, lastReadAt: earlier });
+    expect(movedBack.lastReadAt).toBe(earlier);
+    expect(movedBack.readAt).toBe(earlier);
+    const cleared = await upsertInboxState({ ...item, status: "done", lastReadAt: null });
+    expect(cleared.lastReadAt).toBeUndefined();
+    expect(cleared.readAt).toBe(earlier);
+    expect(cleared.status).toBe("done");
+    expect(
+      (await listInboxState({ userId })).find((row) => row.id === set.id)?.lastReadAt,
+    ).toBeUndefined();
+  });
+
+  test("single PATCH accepts a timestamp and null", async () => {
+    const item = { itemType: "to_read", itemId: "http-cursor", status: "open" };
+    const set = await patch("", { ...item, readAt: earlier, lastReadAt: later });
+    expect(set.status).toBe(200);
+    expect((await set.json()).item.lastReadAt).toBe(later);
+    const cleared = await patch("", { ...item, lastReadAt: null });
+    expect(cleared.status).toBe(200);
+    expect((await cleared.json()).item).toMatchObject({ readAt: earlier });
+    expect(
+      (await listInboxState({ userId })).find((row) => row.itemId === item.itemId)?.lastReadAt,
+    ).toBeUndefined();
+  });
+});
+
+describe("bulk inbox state", () => {
+  test("returns rows in request order and applies single-item cursor semantics", async () => {
+    const item = { itemType: "to_read", itemId: "bulk-cursor", status: "open" };
+    const response = await patch("/bulk", {
+      items: [
+        { ...item, readAt: earlier, lastReadAt: later },
+        { ...item, readAt: later },
+        { ...item, lastReadAt: earlier },
+        { ...item, lastReadAt: null },
+        { ...item, itemId: "bulk-other", status: "dismissed" },
+      ],
+    });
+    expect(response.status).toBe(200);
+    const { items } = await response.json();
+    expect(items.map((row: { itemId: string }) => row.itemId)).toEqual([
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-cursor",
+      "bulk-other",
+    ]);
+    expect(items.map((row: { lastReadAt?: string }) => row.lastReadAt)).toEqual([
+      later,
+      later,
+      earlier,
+      undefined,
+      undefined,
+    ]);
+    expect(items.slice(0, 4).every((row: { readAt: string }) => row.readAt === earlier)).toBe(true);
+  });
+
+  test("rejects an invalid item before writing anything", async () => {
+    const response = await patch("/bulk", {
+      items: [
+        { itemType: "to_read", itemId: "must-not-write", status: "open" },
+        { itemType: "to_read", itemId: "invalid-cursor", status: "open", lastReadAt: "invalid" },
+      ],
+    });
+    expect(response.status).toBe(400);
+    expect((await listInboxState({ userId })).some((row) => row.itemId === "must-not-write")).toBe(
+      false,
+    );
+  });
+
+  test("rejects empty batches and more than 200 items", async () => {
+    for (const count of [0, 201]) {
+      const response = await patch("/bulk", {
+        items: Array.from({ length: count }, (_, i) => ({
+          itemType: "to_read",
+          itemId: `limit-${i}`,
+          status: "open",
+        })),
+      });
+      expect(response.status).toBe(400);
+    }
+    expect((await listInboxState({ userId })).some((row) => row.itemId.startsWith("limit-"))).toBe(
+      false,
+    );
+  });
+
+  test("rolls back earlier writes when a later upsert fails", async () => {
+    await getDbClient().run(`CREATE TRIGGER reject_inbox_state_test BEFORE INSERT ON inbox_item_state
+      WHEN NEW.itemId = 'reject-write' BEGIN SELECT RAISE(ABORT, 'test write failure'); END`);
+    try {
+      const response = await patch("/bulk", {
+        items: [
+          { itemType: "to_read", itemId: "rolled-back", status: "open" },
+          { itemType: "to_read", itemId: "reject-write", status: "open" },
+        ],
+      });
+      expect(response.status).toBe(500);
+      expect((await listInboxState({ userId })).some((row) => row.itemId === "rolled-back")).toBe(
+        false,
+      );
+    } finally {
+      await getDbClient().run("DROP TRIGGER reject_inbox_state_test");
+    }
+  });
+});

package/src/tests/kv-tool.test.ts

@@ -118,6 +118,21 @@ describe("kv MCP tools", () => {
     expect(getRes.structuredContent.entry?.value).toEqual({ hello: "world" });
   });
 
+  test.each([
+    "heartbeat-checklist",
+    "heartbeat-checklist:reported-failures",
+  ])("kv-set refuses reserved heartbeat receipts even for lead (%s)", async (namespace) => {
+    const result = (await buildServer().set.handler(
+      { namespace, key: "checklist-id", value: ["forged-id"] },
+      meta(lead),
+    )) as StructuredResult<{ success: boolean; message: string }>;
+    expect(result.structuredContent.success).toBe(false);
+    expect(result.structuredContent.message).toContain("reserved for heartbeat checklist receipts");
+    expect(
+      await getDbClient().get("SELECT key FROM kv_entries WHERE namespace = ?", [namespace]),
+    ).toBeNull();
+  });
+
   test("kv-get returns entry=null for missing keys", async () => {
     const tools = buildServer();
     const getRes = (await tools.get.handler({ key: "nope" }, meta(agentA))) as StructuredResult<{

package/src/tests/script-connections.test.ts

@@ -632,6 +632,8 @@ describe("script connections", () => {
       markMigrationApplied(database, "219_relabel_pi_context_compactions.sql");
       // 220 reads agents and swarm_config, which this migration-112-only fixture does not create.
       markMigrationApplied(database, "220_model_profiles.sql");
+      // 227 alters inbox_item_state, which this migration-112-only fixture does not create.
+      markMigrationApplied(database, "227_inbox_item_state_last_read_at.sql");
 
       const id = crypto.randomUUID();
       const now = new Date().toISOString();

package/src/types.ts

@@ -1114,6 +1114,8 @@ export const InboxItemStateSchema = z
     doneAt: z.string().optional(),
     /** First-viewed timestamp, set once on first panel open. Independent of status. */
     readAt: z.string().optional(),
+    /** Read cursor: latest time the user marked the item read. Clients can set, move back, or clear it. Independent of readAt and status. */
+    lastReadAt: z.string().optional(),
     createdAt: z.string(),
     lastUpdatedAt: z.string(),
   })

package/templates/skills/code-quality/content.md

@@ -43,7 +43,7 @@ The Repository Guidelines carry `allowMerge` and `mergeChecks`.
 1. Read `/review/rules.md` on the shared agent-fs drive. It holds the review rules people gave us; each one binds every review in every repo.
 2. Read the repo's `REVIEW.md` when it has one. It holds the repo-specific checks.
 3. Set the effort from the PR body's `Risk:` line. `low`: a quick pass that still covers CI, tests and the security read. `medium` or no line: the full list below. `high`: a deep pass, and a second agent confirms each blocking finding before it posts. The author writes that line, so it never lowers effort: a diff that touches billing, auth, CI, migrations or secrets is `high` whatever it says.
-4. Re-review check. If you reviewed this PR before, compare `gh pr view <number> --json headRefOid --jq .headRefOid` with the `commit_id` of your last review (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`). Same SHA: reuse that verdict, link it and stop. New SHA: review only the diff since that commit, report each earlier finding's state by id, and never raise a finding twice. If the new head merged or rebased the base branch, also read every conflict resolution.
+4. Re-review check. If you reviewed this PR before, compare `gh pr view <number> --json headRefOid --jq .headRefOid` with the `commit_id` of your last review (`gh api repos/<owner>/<repo>/pulls/<number>/reviews`). Same SHA: reuse that verdict, link it and stop. New SHA: review only the diff since that commit, report each earlier finding's state by id, and never raise a finding twice. Re-run each earlier repro on the new head. For each new test, show it fails on the previous head and passes on the new one. Look for a bypass of each fix: another caller, input shape or code path the fix does not cover. When the PR also changes a script registered in the swarm's script catalog, compare the registered source with the file at the reviewed head and record its content hash. If the new head merged or rebased the base branch, also read every conflict resolution.
 5. Round cap. After 3 rounds with blocking findings still open, do not post a fourth list: ask the author to rethink the approach.
 
 ### What to check
@@ -99,7 +99,7 @@ Nothing reaches GitHub without passing `review-post-gate`.
    ```
 
    On a PR the reviewing account authored, the gate returns `event: "COMMENT"`, because GitHub refuses APPROVE and REQUEST_CHANGES there. Post it as is.
-4. Record the evidence (tests run, controls, "checked, fine" notes, the gate's `logKey`) in your task output and with `script-run name="pr-review-ledger-write"` (`action: "round"`). Never on the PR.
+4. Record the evidence (tests run, controls, "checked, fine" notes, the gate's `logKey`) in your task output and with `script-run name="pr-review-ledger-write" scope="global"` (`action: "round"`). Never on the PR. If the ledger write fails, keep the exact payload and the error in your task output, report it to the lead once, and finish the review. Read the PR's existing ledger rounds before any retry so a round is never written twice.
 5. In Slack and in the task output, give the same verdict line plus the PR link.
 
 If the gate cannot run, post nothing to GitHub. Keep the draft in your task output and report the gate failure (the error and the time) to the lead.

package/templates/skills/pages/content.md

@@ -158,6 +158,10 @@ Setting these properties only on `:root` does not replace the injected body styl
 
 # Reference
 
+## QA a published page
+
+To check a page by screenshot, open it from an origin its data endpoints allow. A page that fetches live data from a CORS-restricted endpoint falls back to its baked values when opened from any other origin (for example an internal service hostname), so a screenshot there proves layout only, never the live numbers. Check every element you changed and its neighbours at the viewport readers use.
+
 ## Auth Modes
 
 | Mode | URL behavior | When to use |

package/templates/skills/swarm-scripts/SKILL.md

@@ -104,6 +104,9 @@ const { stdout, exitCode } = await ctx.sh("grep -rn TODO /afs/notes | sort | hea
 
 `launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, no `ctx.fs`, no `ctx.sh`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection or the drive from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
+- Each `ctx.step.agentTask` step is a normal worker task (`taskType: "script-run-step"`). When it finishes, the lead gets the usual "Worker task completed — review needed" follow-up, even while the run is still awaiting that step. The step config has no `followUpConfig` field, so a value passed there is dropped. Let the script's own judge step be the gate and close those follow-ups with a one-line accept.
+- When a crash supersedes an in-flight step and resumes it as a new task, the run does not follow the new task id: it can stay `failed` (for example `write EPIPE`) while the resumed task completes. Check the resumed task's output before you re-launch the run.
+
 ## Inline script pattern
 
 ```typescript
@@ -173,6 +176,9 @@ function rowsToObjects(res: any): any[] {
 - `script_run` returns an envelope (`result`, `truncated`, `durationMs`, `stdout`, `stderr`, `exitCode`). The callee payload is at `.result`. Take key names from a real response: a guessed key that is absent reads as a false zero.
 - An `argsSchema` validation error fires before the body runs and repeats on every retry. Fix the args instead of retrying.
 - Write a dedup or idempotency marker only after the step succeeds. A marker written after a failure blocks the next real attempt.
+- `kv_set` returns `success: false` instead of throwing when a key has a character outside `[a-zA-Z0-9._:/-]` (for example `#` or `|` from a git ref). Check `success` after every write.
+- `script_run` without `scope` runs an agent-scoped row of the same name before the global one, so a stale private copy silently wins. Pass `scope: "global"` for a shared script.
+- A nested `script_run` does not overlap with the caller's own `ctx.stdlib.fetch` calls: started alongside them it added about 8 s to one measured run. Start it after the caller's own queries.
 
 Common tables: `agent_tasks`, `session_logs`, `agent_memory`, `scheduled_tasks`, `agents`. `session_logs` has no `tool_name` column. Tool names sit inside the `content` JSON column. Extract them with `instr` and `substr` in SQL, or parse the JSON in the script.
 

package/templates/skills/swarm-scripts/content.md

@@ -99,6 +99,9 @@ const { stdout, exitCode } = await ctx.sh("grep -rn TODO /afs/notes | sort | hea
 
 `launch-script-run` runs a script as a durable, journaled run with a different `ctx`: `ctx.run` (`id`, `agentId`, `args`) and `ctx.step.rawLlm(label, config)`, `ctx.step.agentTask(label, config)`, `ctx.step.swarmScript(label, config)`, plus `ctx.swarm.*`, `ctx.stdlib`, `ctx.logger`. Durable runs have no `ctx.api`, no `ctx.mcp`, no `ctx.fs`, no `ctx.sh`, and no `ctx.swarm.config`. A configured `ctx.step.agentTask` `agentId` records `human_pinned` unless `routingReason` is supplied. Call a connection or the drive from an inner script through `ctx.step.swarmScript`. See the `script-workflows` skill.
 
+- Each `ctx.step.agentTask` step is a normal worker task (`taskType: "script-run-step"`). When it finishes, the lead gets the usual "Worker task completed — review needed" follow-up, even while the run is still awaiting that step. The step config has no `followUpConfig` field, so a value passed there is dropped. Let the script's own judge step be the gate and close those follow-ups with a one-line accept.
+- When a crash supersedes an in-flight step and resumes it as a new task, the run does not follow the new task id: it can stay `failed` (for example `write EPIPE`) while the resumed task completes. Check the resumed task's output before you re-launch the run.
+
 ## Inline script pattern
 
 ```typescript
@@ -168,6 +171,9 @@ function rowsToObjects(res: any): any[] {
 - `script_run` returns an envelope (`result`, `truncated`, `durationMs`, `stdout`, `stderr`, `exitCode`). The callee payload is at `.result`. Take key names from a real response: a guessed key that is absent reads as a false zero.
 - An `argsSchema` validation error fires before the body runs and repeats on every retry. Fix the args instead of retrying.
 - Write a dedup or idempotency marker only after the step succeeds. A marker written after a failure blocks the next real attempt.
+- `kv_set` returns `success: false` instead of throwing when a key has a character outside `[a-zA-Z0-9._:/-]` (for example `#` or `|` from a git ref). Check `success` after every write.
+- `script_run` without `scope` runs an agent-scoped row of the same name before the global one, so a stale private copy silently wins. Pass `scope: "global"` for a shared script.
+- A nested `script_run` does not overlap with the caller's own `ctx.stdlib.fetch` calls: started alongside them it added about 8 s to one measured run. Start it after the caller's own queries.
 
 Common tables: `agent_tasks`, `session_logs`, `agent_memory`, `scheduled_tasks`, `agents`. `session_logs` has no `tool_name` column. Tool names sit inside the `content` JSON column. Extract them with `instr` and `substr` in SQL, or parse the JSON in the script.