@desplega.ai/agent-swarm 1.79.0 → 1.79.2

package/src/tests/kv-page-proxy.test.ts

@@ -0,0 +1,212 @@
+/**
+ * Page proxy + KV: spawn the real http server, register a page-owning agent,
+ * create + launch a page to mint a cookie, then exercise `/@swarm/api/kv/*`.
+ *
+ * Verifies:
+ *   1. KV via the cookie writes under `task:page:<id>` automatically.
+ *   2. Even when the SDK constructs a path with a different explicit
+ *      namespace (`/@swarm/api/kv/_/<other-ns>/k`), the proxy's injected
+ *      `X-Page-Id` is treated as the highest-priority namespace source —
+ *      the request lands in `task:page:<id>` regardless.
+ *   3. Reading from the agent's `task:agent:*` namespace via the cookie is
+ *      ALSO forced to the page namespace (the page can't see the agent's
+ *      scratchpad).
+ */
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { randomUUID } from "node:crypto";
+import { unlink } from "node:fs/promises";
+import type { Subprocess } from "bun";
+
+const TEST_PORT = 19877 + 4; // avoid colliding with page-proxy.test.ts
+const TEST_DB_PATH = `/tmp/test-kv-page-proxy-${Date.now()}.sqlite`;
+const BASE = `http://localhost:${TEST_PORT}`;
+const API_KEY = "test-kv-page-proxy-key";
+const PAGE_SECRET = "test-kv-page-proxy-secret";
+
+let serverProc: Subprocess;
+const agentId = randomUUID();
+
+async function waitForServer(url: string, timeoutMs = 15000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const r = await fetch(url);
+      if (r.ok) return;
+    } catch {}
+    await Bun.sleep(50);
+  }
+  throw new Error(`Server did not start within ${timeoutMs}ms`);
+}
+
+beforeAll(async () => {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+
+  process.env.PAGE_SESSION_SECRET = PAGE_SECRET;
+  serverProc = Bun.spawn(["bun", "src/http.ts"], {
+    cwd: `${import.meta.dir}/../..`,
+    env: {
+      ...process.env,
+      PORT: String(TEST_PORT),
+      DATABASE_PATH: TEST_DB_PATH,
+      API_KEY,
+      PAGE_SESSION_SECRET: PAGE_SECRET,
+      MCP_BASE_URL: `http://127.0.0.1:${TEST_PORT}`,
+      CAPABILITIES: "core,task-pool,messaging,profiles,services,scheduling,memory,pages,kv",
+      SLACK_BOT_TOKEN: "",
+      GITHUB_WEBHOOK_SECRET: "",
+      AGENTMAIL_API_KEY: "",
+    },
+    stdout: "ignore",
+    stderr: "ignore",
+  });
+  await waitForServer(`${BASE}/health`);
+
+  const reg = await fetch(`${BASE}/api/agents`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_KEY}`,
+      "X-Agent-ID": agentId,
+    },
+    body: JSON.stringify({
+      name: "KvPageOwner",
+      isLead: false,
+      description: "owns the kv page",
+      role: "worker",
+      capabilities: ["core", "pages", "kv"],
+      maxTasks: 1,
+    }),
+  });
+  if (reg.status !== 201 && reg.status !== 200) {
+    throw new Error(`Failed to register agent: ${reg.status} ${await reg.text()}`);
+  }
+}, 20000);
+
+afterAll(async () => {
+  if (serverProc) {
+    serverProc.kill();
+    try {
+      await serverProc.exited;
+    } catch {}
+  }
+  await Bun.sleep(50);
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+});
+
+async function createPage(): Promise<string> {
+  const res = await fetch(`${BASE}/api/pages`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${API_KEY}`,
+      "X-Agent-ID": agentId,
+    },
+    body: JSON.stringify({
+      slug: `kv-${randomUUID().slice(0, 8)}`,
+      title: "KV Proxy Test",
+      contentType: "text/html",
+      authMode: "public", // /launch issues a cookie regardless of mode
+      body: "<h1>kv test</h1>",
+    }),
+  });
+  expect(res.status).toBe(201);
+  const json = (await res.json()) as { id: string };
+  return json.id;
+}
+
+async function launchPage(pageId: string): Promise<string> {
+  const res = await fetch(`${BASE}/api/pages/${pageId}/launch`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${API_KEY}`, "X-Agent-ID": agentId },
+  });
+  expect(res.status).toBe(204);
+  const setCookie = res.headers.get("set-cookie");
+  expect(setCookie).toBeTruthy();
+  const cookieValue = /page_session=([^;]+)/.exec(setCookie!)?.[1];
+  expect(cookieValue).toBeTruthy();
+  return cookieValue!;
+}
+
+describe("page proxy → kv", () => {
+  test("writes via the proxy land in task:page:<id> automatically", async () => {
+    const id = await createPage();
+    const cookie = await launchPage(id);
+
+    const put = await fetch(`${BASE}/@swarm/api/kv/clicks`, {
+      method: "PUT",
+      headers: {
+        "Content-Type": "application/json",
+        Cookie: `page_session=${cookie}`,
+      },
+      body: JSON.stringify({ value: 1, valueType: "integer" }),
+    });
+    expect(put.status).toBe(200);
+    const stored = (await put.json()) as { namespace: string; value: number };
+    expect(stored.namespace).toBe(`task:page:${id}`);
+    expect(stored.value).toBe(1);
+
+    // Reading server-side with bearer + the explicit page ns sees the same row.
+    const directGet = await fetch(
+      `${BASE}/api/kv/_/${encodeURIComponent(`task:page:${id}`)}/clicks`,
+      {
+        headers: { Authorization: `Bearer ${API_KEY}`, "X-Agent-ID": agentId },
+      },
+    );
+    expect(directGet.status).toBe(200);
+  });
+
+  test("INCR via the proxy works on the page namespace", async () => {
+    const id = await createPage();
+    const cookie = await launchPage(id);
+    const r1 = await fetch(`${BASE}/@swarm/api/kv/votes/incr`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Cookie: `page_session=${cookie}` },
+      body: JSON.stringify({ by: 2 }),
+    });
+    expect(r1.status).toBe(200);
+    const r2 = await fetch(`${BASE}/@swarm/api/kv/votes/incr`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Cookie: `page_session=${cookie}` },
+      body: JSON.stringify({}),
+    });
+    const v = (await r2.json()) as { value: number; namespace: string };
+    expect(v.value).toBe(3);
+    expect(v.namespace).toBe(`task:page:${id}`);
+  });
+
+  test("page can't escape its own namespace even with an explicit /_/<other-ns>/... path", async () => {
+    const id = await createPage();
+    const cookie = await launchPage(id);
+
+    // Try to write to a completely different namespace via the explicit
+    // URL shape. The proxy's X-Page-Id should force task:page:<id>.
+    const fakeNs = `task:agent:${agentId}`;
+    const put = await fetch(`${BASE}/@swarm/api/kv/_/${encodeURIComponent(fakeNs)}/escape`, {
+      method: "PUT",
+      headers: { "Content-Type": "application/json", Cookie: `page_session=${cookie}` },
+      body: JSON.stringify({ value: "leaked", valueType: "string" }),
+    });
+    // The kv handler treats X-Page-Id as the highest-priority namespace
+    // source. For the *explicit-ns variant*, the URL still resolves a route,
+    // but the proxy-injected X-Page-Id signals page-mode auth. To keep the
+    // strict rule "pages never write anything except task:page:<own>", the
+    // request must either succeed under the page namespace OR be rejected.
+    // We assert that the entry, if created, lives under task:page:<id>,
+    // and that the supposedly-target agent namespace contains nothing.
+    expect([200, 403]).toContain(put.status);
+
+    // The fake target ns must NOT have been written.
+    const verify = await fetch(`${BASE}/api/kv/_/${encodeURIComponent(fakeNs)}/escape`, {
+      headers: { Authorization: `Bearer ${API_KEY}`, "X-Agent-ID": agentId },
+    });
+    expect(verify.status).toBe(404);
+  });
+});

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

@@ -0,0 +1,227 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import {
+  closeDb,
+  countKv,
+  deleteKv,
+  getDb,
+  getKv,
+  incrKv,
+  initDb,
+  KvTypeCollisionError,
+  listKv,
+  upsertKv,
+} from "../be/db";
+
+const TEST_DB_PATH = "./test-kv-storage.sqlite";
+
+const NS = "task:agent:test-agent";
+
+async function clearDb() {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {}
+  }
+}
+
+describe("kv-storage helpers", () => {
+  beforeAll(async () => {
+    await clearDb();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await clearDb();
+  });
+
+  beforeEach(() => {
+    // Tests use distinct keys per case; nothing to wipe between tests.
+    getDb().run(`DELETE FROM kv_entries WHERE namespace = ?`, [NS]);
+  });
+
+  test("get returns null for missing keys", () => {
+    expect(getKv(NS, "missing")).toBeNull();
+  });
+
+  test("upsertKv + getKv round-trip json values", () => {
+    const entry = upsertKv({
+      namespace: NS,
+      key: "obj",
+      value: { a: 1, b: ["two", 3] },
+      valueType: "json",
+    });
+    expect(entry.value).toEqual({ a: 1, b: ["two", 3] });
+    expect(entry.valueType).toBe("json");
+
+    const read = getKv(NS, "obj");
+    expect(read?.value).toEqual({ a: 1, b: ["two", 3] });
+  });
+
+  test("upsertKv overwrites the existing row in place", () => {
+    upsertKv({ namespace: NS, key: "k", value: "first", valueType: "string" });
+    const second = upsertKv({ namespace: NS, key: "k", value: "second", valueType: "string" });
+    expect(second.value).toBe("second");
+    expect(getKv(NS, "k")?.value).toBe("second");
+  });
+
+  test("string value type stores raw bytes", () => {
+    upsertKv({ namespace: NS, key: "s", value: 'hello "world"', valueType: "string" });
+    const got = getKv(NS, "s");
+    expect(got?.value).toBe('hello "world"');
+    expect(got?.valueType).toBe("string");
+  });
+
+  test("integer value type stores as number", () => {
+    upsertKv({ namespace: NS, key: "n", value: 42, valueType: "integer" });
+    expect(getKv(NS, "n")?.value).toBe(42);
+  });
+
+  test("deleteKv removes and returns true; second delete returns false", () => {
+    upsertKv({ namespace: NS, key: "del", value: 1, valueType: "integer" });
+    expect(deleteKv(NS, "del")).toBe(true);
+    expect(deleteKv(NS, "del")).toBe(false);
+    expect(getKv(NS, "del")).toBeNull();
+  });
+
+  test("TTL: expired key returns null on read AND is deleted from row store", () => {
+    upsertKv({
+      namespace: NS,
+      key: "ttl",
+      value: "soon",
+      valueType: "string",
+      expiresAt: Date.now() - 1, // already expired
+    });
+    expect(getKv(NS, "ttl")).toBeNull();
+    // Row should have been deleted by the lazy sweep
+    const raw = getDb()
+      .prepare<{ key: string }, [string, string]>(
+        `SELECT key FROM kv_entries WHERE namespace = ? AND key = ?`,
+      )
+      .get(NS, "ttl");
+    expect(raw).toBeNull();
+  });
+
+  test("TTL: non-expired keys are returned normally", () => {
+    upsertKv({
+      namespace: NS,
+      key: "live",
+      value: "now",
+      valueType: "string",
+      expiresAt: Date.now() + 60_000,
+    });
+    expect(getKv(NS, "live")?.value).toBe("now");
+  });
+
+  test("listKv filters expired but does not delete them inline", () => {
+    upsertKv({
+      namespace: NS,
+      key: "exp",
+      value: "x",
+      valueType: "string",
+      expiresAt: Date.now() - 1,
+    });
+    upsertKv({ namespace: NS, key: "alive", value: "x", valueType: "string" });
+    const all = listKv(NS, { limit: 100, offset: 0 });
+    expect(all.map((e) => e.key)).toEqual(["alive"]);
+    // The expired row should still exist on disk because listKv doesn't sweep.
+    const stillThere = getDb()
+      .prepare<{ key: string }, [string, string]>(
+        `SELECT key FROM kv_entries WHERE namespace = ? AND key = ?`,
+      )
+      .get(NS, "exp");
+    expect(stillThere?.key).toBe("exp");
+  });
+
+  test("listKv prefix filter & ordering", () => {
+    upsertKv({ namespace: NS, key: "a-1", value: 1, valueType: "integer" });
+    upsertKv({ namespace: NS, key: "a-2", value: 2, valueType: "integer" });
+    upsertKv({ namespace: NS, key: "b-1", value: 3, valueType: "integer" });
+    const a = listKv(NS, { prefix: "a-", limit: 100, offset: 0 });
+    expect(a.map((e) => e.key)).toEqual(["a-1", "a-2"]);
+    expect(countKv(NS, { prefix: "a-" })).toBe(2);
+    expect(countKv(NS, {})).toBe(3);
+  });
+
+  test("listKv prefix escapes SQL LIKE wildcards", () => {
+    upsertKv({ namespace: NS, key: "x_1", value: 1, valueType: "integer" });
+    upsertKv({ namespace: NS, key: "xyz", value: 2, valueType: "integer" });
+    const exact = listKv(NS, { prefix: "x_", limit: 100, offset: 0 });
+    // Without escaping, `_` would match any char and we'd get both rows.
+    expect(exact.map((e) => e.key)).toEqual(["x_1"]);
+  });
+
+  test("incrKv creates from missing", () => {
+    const entry = incrKv(NS, "counter", 3);
+    expect(entry.value).toBe(3);
+    expect(entry.valueType).toBe("integer");
+  });
+
+  test("incrKv increments existing integer", () => {
+    incrKv(NS, "counter", 1);
+    incrKv(NS, "counter", 4);
+    const entry = incrKv(NS, "counter", -2);
+    expect(entry.value).toBe(3);
+  });
+
+  test("incrKv treats expired row as missing", () => {
+    upsertKv({
+      namespace: NS,
+      key: "decay",
+      value: 100,
+      valueType: "integer",
+      expiresAt: Date.now() - 1,
+    });
+    const entry = incrKv(NS, "decay", 5);
+    expect(entry.value).toBe(5);
+    expect(entry.expiresAt).toBeNull();
+  });
+
+  test("incrKv collides with json valueType (409 surface)", () => {
+    upsertKv({ namespace: NS, key: "obj", value: { n: 1 }, valueType: "json" });
+    let thrown: unknown;
+    try {
+      incrKv(NS, "obj", 1);
+    } catch (err) {
+      thrown = err;
+    }
+    expect(thrown).toBeInstanceOf(KvTypeCollisionError);
+    if (thrown instanceof KvTypeCollisionError) {
+      expect(thrown.existingType).toBe("json");
+    }
+  });
+
+  test("incrKv collides with string valueType", () => {
+    upsertKv({ namespace: NS, key: "str", value: "5", valueType: "string" });
+    expect(() => incrKv(NS, "str", 1)).toThrow(KvTypeCollisionError);
+  });
+
+  test("2 MiB exactly succeeds; 2 MiB + 1 byte rejected via upsert encoder is N/A — boundary lives in HTTP/MCP layer", () => {
+    // The DB helpers themselves don't enforce size — that's the HTTP/MCP
+    // boundary. But we can store a 2 MiB string here to prove the engine
+    // accepts it. The 2 MiB + 1 case is covered by the HTTP test.
+    const twoMiB = "x".repeat(2 * 1024 * 1024);
+    const entry = upsertKv({ namespace: NS, key: "big", value: twoMiB, valueType: "string" });
+    expect((entry.value as string).length).toBe(2 * 1024 * 1024);
+  });
+});
+
+describe("kv-storage namespaces are isolated", () => {
+  beforeAll(async () => {
+    await clearDb();
+    initDb(TEST_DB_PATH);
+  });
+
+  afterAll(async () => {
+    closeDb();
+    await clearDb();
+  });
+
+  test("different namespaces with same key are independent", () => {
+    upsertKv({ namespace: "task:agent:a", key: "shared", value: "A", valueType: "string" });
+    upsertKv({ namespace: "task:agent:b", key: "shared", value: "B", valueType: "string" });
+    expect(getKv("task:agent:a", "shared")?.value).toBe("A");
+    expect(getKv("task:agent:b", "shared")?.value).toBe("B");
+  });
+});

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

@@ -0,0 +1,217 @@
+/**
+ * KV MCP tools — unit-level coverage. Registers each tool against a fresh
+ * McpServer, pulls handlers out of the SDK registry, invokes them with a
+ * stubbed `requestInfo` (mirrors create-page-tool.test.ts).
+ *
+ * Verifies:
+ *   - kv-set / kv-get round-trip on the auto-resolved agent namespace
+ *   - kv-incr atomicity + 'integer' coercion
+ *   - kv-list shape (entries, total, namespace)
+ *   - kv-delete returns deleted flag
+ *   - cross-agent write 403 (lead bypass tested too)
+ *   - missing namespace + no agent header → structured error
+ */
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { closeDb, createAgent, getDb, initDb } from "../be/db";
+import {
+  registerKvDeleteTool,
+  registerKvGetTool,
+  registerKvIncrTool,
+  registerKvListTool,
+  registerKvSetTool,
+} from "../tools/kv";
+
+const TEST_DB_PATH = "./test-kv-tool.sqlite";
+
+type RegisteredTool = {
+  handler: (args: unknown, extra: unknown) => Promise<unknown>;
+};
+
+function buildServer() {
+  const server = new McpServer({ name: "kv-tool-test", version: "1.0.0" });
+  registerKvGetTool(server);
+  registerKvSetTool(server);
+  registerKvDeleteTool(server);
+  registerKvIncrTool(server);
+  registerKvListTool(server);
+  const registered = (server as unknown as { _registeredTools: Record<string, RegisteredTool> })
+    ._registeredTools;
+  return {
+    get: registered["kv-get"]!,
+    set: registered["kv-set"]!,
+    del: registered["kv-delete"]!,
+    incr: registered["kv-incr"]!,
+    list: registered["kv-list"]!,
+  };
+}
+
+function meta(agentId: string | undefined, sourceTaskId?: string) {
+  const headers: Record<string, string> = {};
+  if (agentId !== undefined) headers["x-agent-id"] = agentId;
+  if (sourceTaskId !== undefined) headers["x-source-task-id"] = sourceTaskId;
+  return { sessionId: "s1", requestInfo: { headers } };
+}
+
+type StructuredResult<T> = { structuredContent: T };
+
+let agentA: string;
+let agentB: string;
+let lead: string;
+
+beforeAll(async () => {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+  initDb(TEST_DB_PATH);
+  const a = createAgent({ name: "kv-tool-a", isLead: false, status: "idle" });
+  const b = createAgent({ name: "kv-tool-b", isLead: false, status: "idle" });
+  const l = createAgent({ name: "kv-tool-lead", isLead: true, status: "idle" });
+  agentA = a.id;
+  agentB = b.id;
+  lead = l.id;
+});
+
+afterAll(async () => {
+  closeDb();
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(`${TEST_DB_PATH}${suffix}`);
+    } catch {}
+  }
+});
+
+beforeEach(() => {
+  getDb().run("DELETE FROM kv_entries");
+});
+
+describe("kv MCP tools", () => {
+  test("kv-set + kv-get round-trip on agent namespace", async () => {
+    const tools = buildServer();
+    const setRes = (await tools.set.handler(
+      { key: "k1", value: { hello: "world" } },
+      meta(agentA),
+    )) as StructuredResult<{
+      success: boolean;
+      namespace: string;
+      entry: { value: unknown; valueType: string };
+    }>;
+    expect(setRes.structuredContent.success).toBe(true);
+    expect(setRes.structuredContent.namespace).toBe(`task:agent:${agentA}`);
+    expect(setRes.structuredContent.entry.value).toEqual({ hello: "world" });
+
+    const getRes = (await tools.get.handler({ key: "k1" }, meta(agentA))) as StructuredResult<{
+      success: boolean;
+      entry: { value: unknown } | null;
+    }>;
+    expect(getRes.structuredContent.success).toBe(true);
+    expect(getRes.structuredContent.entry?.value).toEqual({ hello: "world" });
+  });
+
+  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<{
+      success: boolean;
+      entry: unknown | null;
+    }>;
+    expect(getRes.structuredContent.success).toBe(true);
+    expect(getRes.structuredContent.entry).toBeNull();
+  });
+
+  test("kv-incr creates + increments + reports value", async () => {
+    const tools = buildServer();
+    const r1 = (await tools.incr.handler({ key: "ctr", by: 5 }, meta(agentA))) as StructuredResult<{
+      entry: { value: number; valueType: string };
+    }>;
+    expect(r1.structuredContent.entry.value).toBe(5);
+    expect(r1.structuredContent.entry.valueType).toBe("integer");
+    const r2 = (await tools.incr.handler({ key: "ctr" }, meta(agentA))) as StructuredResult<{
+      entry: { value: number };
+    }>;
+    expect(r2.structuredContent.entry.value).toBe(6);
+  });
+
+  test("kv-incr returns structured error on valueType collision", async () => {
+    const tools = buildServer();
+    await tools.set.handler({ key: "obj", value: { n: 1 } }, meta(agentA));
+    const r = (await tools.incr.handler({ key: "obj" }, meta(agentA))) as StructuredResult<{
+      success: boolean;
+      message: string;
+    }>;
+    expect(r.structuredContent.success).toBe(false);
+    expect(r.structuredContent.message).toMatch(/Cannot INCR/);
+  });
+
+  test("kv-list returns entries + total + namespace", async () => {
+    const tools = buildServer();
+    await tools.set.handler({ key: "a-1", value: 1, valueType: "integer" }, meta(agentA));
+    await tools.set.handler({ key: "a-2", value: 2, valueType: "integer" }, meta(agentA));
+    await tools.set.handler({ key: "b-1", value: 3, valueType: "integer" }, meta(agentA));
+
+    const r = (await tools.list.handler({ prefix: "a-" }, meta(agentA))) as StructuredResult<{
+      success: boolean;
+      entries: { key: string }[];
+      total: number;
+      namespace: string;
+    }>;
+    expect(r.structuredContent.entries.map((e) => e.key)).toEqual(["a-1", "a-2"]);
+    expect(r.structuredContent.total).toBe(2);
+    expect(r.structuredContent.namespace).toBe(`task:agent:${agentA}`);
+  });
+
+  test("kv-delete returns deleted flag", async () => {
+    const tools = buildServer();
+    await tools.set.handler({ key: "del-me", value: "x", valueType: "string" }, meta(agentA));
+    const r1 = (await tools.del.handler({ key: "del-me" }, meta(agentA))) as StructuredResult<{
+      deleted: boolean;
+    }>;
+    expect(r1.structuredContent.deleted).toBe(true);
+    const r2 = (await tools.del.handler({ key: "del-me" }, meta(agentA))) as StructuredResult<{
+      deleted: boolean;
+    }>;
+    expect(r2.structuredContent.deleted).toBe(false);
+  });
+
+  test("cross-agent write is rejected for non-lead callers", async () => {
+    const tools = buildServer();
+    const r = (await tools.set.handler(
+      { key: "k", value: 1, namespace: `task:agent:${agentB}` },
+      meta(agentA),
+    )) as StructuredResult<{ success: boolean; message: string }>;
+    expect(r.structuredContent.success).toBe(false);
+    expect(r.structuredContent.message).toMatch(/lead/);
+  });
+
+  test("lead can write to another agent's namespace", async () => {
+    const tools = buildServer();
+    const r = (await tools.set.handler(
+      { key: "k", value: 1, namespace: `task:agent:${agentB}`, valueType: "integer" },
+      meta(lead),
+    )) as StructuredResult<{ success: boolean; namespace: string }>;
+    expect(r.structuredContent.success).toBe(true);
+    expect(r.structuredContent.namespace).toBe(`task:agent:${agentB}`);
+  });
+
+  test("missing agent header → namespace cannot be resolved", async () => {
+    const tools = buildServer();
+    const r = (await tools.get.handler({ key: "k" }, meta(undefined))) as StructuredResult<{
+      success: boolean;
+      message: string;
+    }>;
+    expect(r.structuredContent.success).toBe(false);
+    expect(r.structuredContent.message).toMatch(/namespace/);
+  });
+
+  test("page namespace writes are rejected (MCP can't be a page)", async () => {
+    const tools = buildServer();
+    const r = (await tools.set.handler(
+      { key: "k", value: 1, namespace: "task:page:doesntmatter" },
+      meta(agentA),
+    )) as StructuredResult<{ success: boolean; message: string }>;
+    expect(r.structuredContent.success).toBe(false);
+    expect(r.structuredContent.message).toMatch(/page-proxy/);
+  });
+});

package/src/tests/page-proxy.test.ts

@@ -226,7 +226,11 @@ describe("/@swarm/api/* proxy", () => {
     const exp = Math.floor(Date.now() / 1000) + 3600;
     const good = await signPageSession({ pageId: id, exp });
     const [head, sig] = good.split(".");
-    const tamperedSig = `${sig!.slice(0, -1)}${sig!.slice(-1) === "A" ? "B" : "A"}`;
+    // Flip a decoded HMAC byte rather than a base64url char — flipping the
+    // last char is flaky (see src/tests/page-session.test.ts for why).
+    const sigBytes = Buffer.from(sig!, "base64url");
+    sigBytes[0] ^= 0x01;
+    const tamperedSig = sigBytes.toString("base64url").replace(/=/g, "");
     const bad = `${head}.${tamperedSig}`;
     const res = await fetch(`${BASE}/@swarm/api/agents/${agentId}`, {
       headers: { Cookie: `page_session=${bad}` },

package/src/tests/page-session.test.ts

@@ -59,11 +59,16 @@ describe("page-session HMAC helpers", () => {
     const token = await signPageSession(payload);
     const [head, sig] = token.split(".");
     expect(sig).toBeDefined();
-    // Flip the last character — keeps length identical so we exercise the
-    // constant-time compare branch (not the length-mismatch early-return).
-    const lastChar = sig!.slice(-1);
-    const flipped = lastChar === "A" ? "B" : "A";
-    const tamperedSig = sig!.slice(0, -1) + flipped;
+    // Flip a decoded HMAC byte rather than a base64url character. Flipping the
+    // last *character* is flaky: for a 32-byte (SHA-256) HMAC the final base64url
+    // char encodes 4 real bits + 2 LSB padding zeros, so "A"→"B" only toggles a
+    // padding bit and the decoded HMAC is unchanged (~1/16 probability), causing
+    // the verifier to incorrectly accept the token. Operating on decoded bytes is
+    // deterministic and still produces a same-length re-encoded token, exercising
+    // the constant-time compare branch (not the length-mismatch early-return).
+    const sigBytes = Buffer.from(sig!, "base64url");
+    sigBytes[0] ^= 0x01;
+    const tamperedSig = sigBytes.toString("base64url").replace(/=/g, "");
     const tampered = `${head}.${tamperedSig}`;
     expect(await verifyPageSession(tampered)).toBeNull();
   });