@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/tests/org-identity.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from "bun:test";
+import { orgIdentityStatus } from "../utils/org-identity";
+
+describe("orgIdentityStatus", () => {
+  test.each([
+    ["empty", {}, ["SWARM_ORG_NAME", "SWARM_ORG_WEBSITE"]],
+    [
+      "whitespace",
+      { SWARM_ORG_NAME: "   ", SWARM_ORG_WEBSITE: "  " },
+      ["SWARM_ORG_NAME", "SWARM_ORG_WEBSITE"],
+    ],
+    [
+      "the catalog default",
+      { SWARM_ORG_NAME: "Swarm", SWARM_ORG_WEBSITE: "acme.com" },
+      ["SWARM_ORG_NAME"],
+    ],
+    [
+      "the Slack fallback",
+      { SWARM_ORG_NAME: " your swarm ", SWARM_ORG_WEBSITE: "acme.com" },
+      ["SWARM_ORG_NAME"],
+    ],
+    [
+      "an invalid website",
+      { SWARM_ORG_NAME: "Acme", SWARM_ORG_WEBSITE: "localhost" },
+      ["SWARM_ORG_WEBSITE"],
+    ],
+    ["both set", { SWARM_ORG_NAME: " Acme ", SWARM_ORG_WEBSITE: "https://www.Acme.com/" }, []],
+  ] as const)("%s", (_label, src, missing) => {
+    const status = orgIdentityStatus(src);
+    expect(status.missing).toEqual([...missing]);
+    expect(status.ok).toBe(missing.length === 0);
+  });
+
+  test("returns the trimmed name and the normalized website", () => {
+    expect(
+      orgIdentityStatus({ SWARM_ORG_NAME: " Acme ", SWARM_ORG_WEBSITE: "https://www.Acme.com/" }),
+    ).toEqual({
+      name: "Acme",
+      website: "acme.com",
+      missing: [],
+      ok: true,
+    });
+  });
+});

package/src/tests/ranking-listing.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isInternalConfigKey, validateConfigValue } from "../be/swarm-config-guard";
+import {
+  buildListing,
+  mintRankingClaim,
+  parseTelemetryRanking,
+  rankingEntryFile,
+} from "../ranking/telemetry-ranking";
+import { RANKING_TAXONOMY } from "../telemetry-contract/ranking-taxonomy.gen";
+import { orgIdentityStatus } from "../utils/org-identity";
+
+const FIXTURES = join(import.meta.dir, "..", "telemetry-contract", "ranking", "fixtures");
+const read = (kind: string, file: string) => readFileSync(join(FIXTURES, kind, file), "utf8");
+
+describe("telemetry_ranking contract fixtures", () => {
+  const expected = JSON.parse(readFileSync(join(FIXTURES, "expected.json"), "utf8")) as {
+    invalid: Record<string, string>;
+  };
+
+  test("the fixture set is complete", () => {
+    expect(readdirSync(join(FIXTURES, "valid")).length).toBeGreaterThan(0);
+    expect(readdirSync(join(FIXTURES, "invalid")).sort()).toEqual(
+      Object.keys(expected.invalid).sort(),
+    );
+  });
+
+  for (const file of readdirSync(join(FIXTURES, "valid"))) {
+    test(`valid/${file} parses`, () => {
+      expect(() => parseTelemetryRanking(read("valid", file))).not.toThrow();
+    });
+  }
+
+  for (const file of readdirSync(join(FIXTURES, "invalid"))) {
+    test(`invalid/${file} is rejected (${expected.invalid[file]})`, () => {
+      expect(() => parseTelemetryRanking(read("invalid", file))).toThrow();
+    });
+  }
+});
+
+describe("buildListing", () => {
+  const identity = orgIdentityStatus({ SWARM_ORG_NAME: "Acme", SWARM_ORG_WEBSITE: "acme.dev" });
+  const claim = mintRankingClaim();
+
+  test("copies the name and domain from the org identity and blanks to null", () => {
+    const listing = buildListing(
+      identity,
+      {
+        category: "engineering",
+        subcategory: "qa-testing",
+        description: "  ",
+        sourceCodeUrl: null,
+      },
+      claim,
+      new Date("2026-10-18T10:00:00Z"),
+    );
+    expect(listing).toEqual({
+      v: 1,
+      claim,
+      name: "Acme",
+      domain: "acme.dev",
+      category: "engineering",
+      subcategory: "qa-testing",
+      description: null,
+      sourceCodeUrl: null,
+      updatedAt: "2026-10-18T10:00:00.000Z",
+    });
+    expect(JSON.parse(rankingEntryFile(listing))).toEqual({
+      $schema: "./schema.json",
+      domain: "acme.dev",
+      claim,
+    });
+  });
+
+  test("refuses a missing identity and an http source URL", () => {
+    expect(() =>
+      buildListing(
+        orgIdentityStatus({ SWARM_ORG_NAME: "Swarm", SWARM_ORG_WEBSITE: "acme.dev" }),
+        { category: "other" },
+        claim,
+      ),
+    ).toThrow("SWARM_ORG_NAME");
+    expect(() =>
+      buildListing(identity, { category: "other", sourceCodeUrl: "http://github.com/acme" }, claim),
+    ).toThrow();
+  });
+
+  test("mints rk_ + 32 hex claims", () => {
+    expect(mintRankingClaim()).toMatch(/^rk_[0-9a-f]{32}$/);
+    expect(mintRankingClaim()).not.toBe(mintRankingClaim());
+  });
+
+  test("the taxonomy comes from the vendored contract", () => {
+    expect(RANKING_TAXONOMY).toEqual(
+      JSON.parse(readFileSync(join(FIXTURES, "..", "taxonomy.json"), "utf8")),
+    );
+  });
+});
+
+describe("config guard", () => {
+  test("telemetry_ranking is internal and validated", () => {
+    expect(isInternalConfigKey("telemetry_ranking")).toBe(true);
+    expect(validateConfigValue("telemetry_ranking", "{}")).toContain("telemetry_ranking");
+    expect(validateConfigValue("telemetry_ranking", read("valid", "full.json"))).toBeNull();
+  });
+
+  test("PUBLIC_RANKING_ENABLED is a boolean", () => {
+    expect(validateConfigValue("PUBLIC_RANKING_ENABLED", "true")).toBeNull();
+    expect(validateConfigValue("PUBLIC_RANKING_ENABLED", "yes please")).not.toBeNull();
+  });
+});

package/src/tests/ranking-route.test.ts

@@ -0,0 +1,319 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { unlink } from "node:fs/promises";
+import { Readable } from "node:stream";
+import { closeDb, getSwarmConfigs, initDb, upsertSwarmConfig } from "../be/db";
+import { handleConfig } from "../http/config";
+import { handleRanking } from "../http/ranking";
+import { getPathSegments, parseQueryParams } from "../http/utils";
+import { parseTelemetryRanking } from "../ranking/telemetry-ranking";
+import { _resetTelemetryStateForTests, initTelemetry } from "../telemetry";
+import type { HttpRequestAuth } from "../utils/request-auth-context";
+import { setRequestAuth } from "../utils/request-auth-context";
+
+const TEST_DB_PATH = "./test-ranking-route.sqlite";
+const OPERATOR: HttpRequestAuth = { kind: "operator", fingerprint: "op:test" };
+const INSTALL_ID = "install_0123456789abcdef0123456789abcdef";
+const ENV_KEYS = [
+  "ANONYMIZED_TELEMETRY",
+  "SWARM_ORG_ID",
+  "SWARM_ORG_NAME",
+  "SWARM_ORG_WEBSITE",
+  "PUBLIC_RANKING_ENABLED",
+] as const;
+
+async function removeDbFiles(): Promise<void> {
+  for (const suffix of ["", "-wal", "-shm"]) {
+    try {
+      await unlink(TEST_DB_PATH + suffix);
+    } catch {
+      // Not there.
+    }
+  }
+}
+
+type Handler = typeof handleRanking;
+
+async function call(
+  method: string,
+  url: string,
+  body?: unknown,
+  handler: Handler = handleRanking,
+  auth: HttpRequestAuth = OPERATOR,
+): Promise<{ statusCode: number; json: Record<string, unknown> }> {
+  const req = Readable.from(
+    body === undefined ? [] : [Buffer.from(JSON.stringify(body))],
+  ) as Readable & {
+    method: string;
+    url: string;
+    headers: Record<string, string>;
+  };
+  req.method = method;
+  req.url = url;
+  req.headers = { "content-type": "application/json" };
+  setRequestAuth(req as never, auth);
+  let statusCode = 200;
+  const chunks: string[] = [];
+  const res = {
+    setHeader: () => {},
+    writeHead: (code: number) => {
+      statusCode = code;
+    },
+    end: (chunk?: string) => {
+      if (chunk) chunks.push(chunk);
+    },
+  };
+  await handler(req as never, res as never, getPathSegments(url), parseQueryParams(url));
+  const text = chunks.join("");
+  return { statusCode, json: text ? JSON.parse(text) : {} };
+}
+
+const configValue = async (key: string) =>
+  (await getSwarmConfigs({ scope: "global", key }))?.[0]?.value;
+
+describe("ranking routes", () => {
+  const originalFetch = globalThis.fetch;
+  const savedEnv = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
+  let sent: Array<{
+    event: string;
+    properties: Record<string, unknown>;
+    context: Record<string, unknown>;
+  }>;
+
+  beforeAll(async () => {
+    for (const key of ENV_KEYS) delete process.env[key];
+    process.env.ANONYMIZED_TELEMETRY = "true";
+    process.env.SWARM_ORG_ID = "org_0123456789abcdef";
+    await removeDbFiles();
+    initDb(TEST_DB_PATH);
+    globalThis.fetch = (async (url: string, init?: { body?: string }) => {
+      if (String(url).endsWith("/v1/events")) sent.push(JSON.parse(init?.body ?? "{}"));
+      return new Response(null, { status: 202 });
+    }) as unknown as typeof fetch;
+    _resetTelemetryStateForTests();
+    await initTelemetry(
+      "api-server",
+      async (key) => (key === "telemetry_installation_id" ? INSTALL_ID : undefined),
+      async () => {},
+    );
+  });
+
+  afterAll(async () => {
+    for (const key of ENV_KEYS) {
+      if (savedEnv[key] === undefined) delete process.env[key];
+      else process.env[key] = savedEnv[key];
+    }
+    globalThis.fetch = originalFetch;
+    _resetTelemetryStateForTests();
+    closeDb();
+    await removeDbFiles();
+  });
+
+  beforeEach(async () => {
+    sent = [];
+    process.env.ANONYMIZED_TELEMETRY = "true";
+    await upsertSwarmConfig({
+      scope: "global",
+      key: "telemetry_installation_id",
+      value: INSTALL_ID,
+    });
+    await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_NAME", value: "Acme" });
+    await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_WEBSITE", value: "acme.dev" });
+    await upsertSwarmConfig({ scope: "global", key: "PUBLIC_RANKING_ENABLED", value: "false" });
+    await upsertSwarmConfig({ scope: "global", key: "telemetry_ranking", value: "" });
+  });
+
+  const form = {
+    category: "engineering",
+    subcategory: "qa-testing",
+    description: " QA ",
+    sourceCodeUrl: "",
+  };
+
+  test("telemetry off is a 409 telemetry_off", async () => {
+    process.env.ANONYMIZED_TELEMETRY = "false";
+    const result = await call("POST", "/api/ranking/opt-in", form);
+    expect(result.statusCode).toBe(409);
+    expect(result.json.error).toBe("telemetry_off");
+    expect(await configValue("PUBLIC_RANKING_ENABLED")).toBe("false");
+  });
+
+  test("a placeholder name and no website is a 409 that lists both", async () => {
+    await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_NAME", value: "Swarm" });
+    await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_WEBSITE", value: "" });
+    const result = await call("POST", "/api/ranking/opt-in", form);
+    expect(result.statusCode).toBe(409);
+    expect(result.json).toMatchObject({
+      error: "org_identity_missing",
+      missing: ["SWARM_ORG_NAME", "SWARM_ORG_WEBSITE"],
+    });
+    const state = await call("GET", "/api/ranking");
+    expect(state.json).toMatchObject({
+      eligible: false,
+      missing: ["SWARM_ORG_NAME", "SWARM_ORG_WEBSITE"],
+    });
+    expect(sent).toEqual([]);
+  });
+
+  test("a subcategory from another category is a 400", async () => {
+    const result = await call("POST", "/api/ranking/opt-in", { ...form, subcategory: "seo" });
+    expect(result.statusCode).toBe(400);
+    expect(String(result.json.error)).toContain("subcategory");
+  });
+
+  test("opt-in stores the listing, turns the setting on and emits it with a matching envelope", async () => {
+    const result = await call("POST", "/api/ranking/opt-in", form);
+    expect(result.statusCode).toBe(200);
+    const claim = String(result.json.claim);
+    expect(claim).toMatch(/^rk_[0-9a-f]{32}$/);
+    expect(result.json.domain).toBe("acme.dev");
+    expect(String(result.json.prUrl)).toContain("filename=community%2Franking%2Facme.dev.json");
+    expect(JSON.parse(String(result.json.fileJson))).toEqual({
+      $schema: "./schema.json",
+      domain: "acme.dev",
+      claim,
+    });
+    expect(String(result.json.verifyUrl)).toBe(
+      `https://proxy.desplega.sh/v1/ranking/verify?domain=acme.dev&claim=${claim}`,
+    );
+
+    const stored = parseTelemetryRanking(String(await configValue("telemetry_ranking")));
+    expect(stored).toMatchObject({
+      claim,
+      name: "Acme",
+      domain: "acme.dev",
+      category: "engineering",
+      subcategory: "qa-testing",
+      description: "QA",
+      sourceCodeUrl: null,
+    });
+    expect(await configValue("PUBLIC_RANKING_ENABLED")).toBe("true");
+
+    expect(sent.map((event) => event.event)).toEqual(["ranking.opted_in"]);
+    const listing = parseTelemetryRanking(String(sent[0]?.properties.listing));
+    expect(listing).toEqual(stored);
+    expect(sent[0]?.context).toMatchObject({ org_name: "Acme", org_website: "acme.dev" });
+
+    // A second opt-in for the same domain keeps the claim.
+    const again = await call("POST", "/api/ranking/opt-in", { category: "other" });
+    expect(again.json.claim).toBe(claim);
+
+    const state = await call("GET", "/api/ranking");
+    expect(state.json).toMatchObject({
+      eligible: true,
+      enabled: true,
+      missing: [],
+      listingMatchesDomain: true,
+    });
+  });
+
+  test("only a config admin reads the ranking state and its claim", async () => {
+    const claim = String((await call("POST", "/api/ranking/opt-in", form)).json.claim);
+    const worker: HttpRequestAuth = {
+      kind: "agent",
+      agentId: crypto.randomUUID(),
+      taskId: null,
+      runtimeId: null,
+      tokenId: "tok_test",
+      expiresAt: "2099-01-01T00:00:00.000Z",
+    };
+    const guest: HttpRequestAuth = { kind: "guest" };
+    for (const auth of [worker, guest]) {
+      const denied = await call("GET", "/api/ranking", undefined, handleRanking, auth);
+      expect(denied.statusCode).toBe(403);
+      expect(JSON.stringify(denied.json)).not.toContain(claim);
+    }
+    const state = await call("GET", "/api/ranking");
+    expect(state.statusCode).toBe(200);
+    expect((state.json.listing as { claim: string }).claim).toBe(claim);
+  });
+
+  test("concurrent first opt-ins share one claim, and leave then rejoin keeps it", async () => {
+    const [first, second] = await Promise.all([
+      call("POST", "/api/ranking/opt-in", form),
+      call("POST", "/api/ranking/opt-in", form),
+    ]);
+    expect(first.statusCode).toBe(200);
+    expect(second.statusCode).toBe(200);
+    // Either response may be the one merged into community/ranking.
+    const merged = String(first.json.claim);
+    expect(second.json.claim).toBe(merged);
+    expect(parseTelemetryRanking(String(await configValue("telemetry_ranking")))?.claim).toBe(
+      merged,
+    );
+
+    expect((await call("POST", "/api/ranking/opt-out")).statusCode).toBe(200);
+    const rejoin = await call("POST", "/api/ranking/opt-in", form);
+    expect(rejoin.json.claim).toBe(merged);
+  });
+
+  test("opt-out stores false, emits ranking.opted_out and returns the delete page", async () => {
+    await call("POST", "/api/ranking/opt-in", form);
+    sent = [];
+    const result = await call("POST", "/api/ranking/opt-out");
+    expect(result.statusCode).toBe(200);
+    expect(result.json).toEqual({
+      enabled: false,
+      leaveUrl:
+        "https://github.com/desplega-ai/agent-swarm/delete/main/community/ranking/acme.dev.json",
+    });
+    expect(await configValue("PUBLIC_RANKING_ENABLED")).toBe("false");
+    expect(sent.map((event) => [event.event, event.properties.domain])).toEqual([
+      ["ranking.opted_out", "acme.dev"],
+    ]);
+  });
+
+  test("PUT /api/config refuses telemetry_ranking", async () => {
+    const result = await call(
+      "PUT",
+      "/api/config",
+      { scope: "global", key: "telemetry_ranking", value: "{}" },
+      handleConfig,
+    );
+    expect(result.statusCode).toBe(400);
+    expect(String(result.json.error)).toContain("/api/ranking");
+  });
+
+  test("renaming the org re-emits the listing with the same claim", async () => {
+    const optIn = await call("POST", "/api/ranking/opt-in", form);
+    sent = [];
+    const put = await call(
+      "PUT",
+      "/api/config",
+      { scope: "global", key: "SWARM_ORG_NAME", value: "Acme Labs" },
+      handleConfig,
+    );
+    expect(put.statusCode).toBe(200);
+    expect(sent.map((event) => event.event)).toEqual(["ranking.opted_in"]);
+    const listing = parseTelemetryRanking(String(sent[0]?.properties.listing));
+    expect(listing).toMatchObject({
+      name: "Acme Labs",
+      claim: optIn.json.claim,
+      subcategory: "qa-testing",
+    });
+    // The envelope carries the new name before the config reload reaches process.env.
+    expect(sent[0]?.context).toMatchObject({ org_name: "Acme Labs", org_website: "acme.dev" });
+    expect(await configValue("PUBLIC_RANKING_ENABLED")).toBe("true");
+  });
+
+  test("a placeholder name, a changed website or a name too long for the listing opts out", async () => {
+    for (const [key, value] of [
+      ["SWARM_ORG_NAME", "Your Swarm"],
+      ["SWARM_ORG_NAME", "x".repeat(61)],
+      ["SWARM_ORG_WEBSITE", "acme.io"],
+    ] as const) {
+      await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_NAME", value: "Acme" });
+      await upsertSwarmConfig({ scope: "global", key: "SWARM_ORG_WEBSITE", value: "acme.dev" });
+      await call("POST", "/api/ranking/opt-in", form);
+      sent = [];
+      const put = await call("PUT", "/api/config", { scope: "global", key, value }, handleConfig);
+      expect(put.statusCode).toBe(200);
+      expect(await configValue("PUBLIC_RANKING_ENABLED")).toBe("false");
+      expect(sent.map((event) => [event.event, event.properties.domain])).toEqual([
+        ["ranking.opted_out", "acme.dev"],
+      ]);
+    }
+    // After the last case (a new website) the old listing needs a new PR.
+    const state = await call("GET", "/api/ranking");
+    expect(state.json).toMatchObject({ enabled: false, listingMatchesDomain: false, prUrl: null });
+  });
+});

package/src/tests/ranking-usage.test.ts

@@ -0,0 +1,50 @@
+import { describe, expect, test } from "bun:test";
+import { rankingUsageProps } from "../ranking/usage";
+
+const ON = {
+  ANONYMIZED_TELEMETRY: "true",
+  PUBLIC_RANKING_ENABLED: "true",
+  SWARM_ORG_NAME: "Acme",
+  SWARM_ORG_WEBSITE: "acme.dev",
+};
+const COST = { inputTokens: 100, outputTokens: 20, cacheReadTokens: 5, cacheWriteTokens: 3 };
+const SESSION = { model: "claude-opus-5-5", provider: "claude" };
+
+describe("rankingUsageProps (the worker's ranking.usage gate)", () => {
+  test("emits token counts, model and provider when every gate passes", () => {
+    const props = rankingUsageProps(COST, SESSION, ON);
+    expect(props).toEqual({
+      model: "claude-opus-5-5",
+      provider: "claude",
+      totalTokens: 128,
+      inputTokens: 100,
+      outputTokens: 20,
+      cacheReadTokens: 5,
+      cacheWriteTokens: 3,
+    });
+    // Tokens are the only metric: no cost, task or agent.
+    for (const key of ["totalCostUsd", "taskId", "agentId", "durationMs", "numTurns"]) {
+      expect(props).not.toHaveProperty(key);
+    }
+  });
+
+  test.each([
+    ["telemetry off", { ANONYMIZED_TELEMETRY: "false" }],
+    ["the setting off", { PUBLIC_RANKING_ENABLED: "false" }],
+    ["the setting unset", { PUBLIC_RANKING_ENABLED: undefined }],
+    ["no org name", { SWARM_ORG_NAME: "" }],
+    ["a placeholder org name", { SWARM_ORG_NAME: "Swarm" }],
+    ["no website", { SWARM_ORG_WEBSITE: undefined }],
+  ])("nothing with %s", (_label, override) => {
+    expect(rankingUsageProps(COST, SESSION, { ...ON, ...override })).toBeNull();
+  });
+
+  test("omits cache counts the harness did not report", () => {
+    expect(rankingUsageProps({ inputTokens: 7, outputTokens: 1 }, SESSION, ON)).toEqual({
+      ...SESSION,
+      totalTokens: 8,
+      inputTokens: 7,
+      outputTokens: 1,
+    });
+  });
+});

package/src/tests/rbac-admission-e2e.test.ts

@@ -254,6 +254,12 @@ describe("RBAC admission over real HTTP", () => {
     expect(deniedTaskCreate.status).toBe(403);
     expect(deniedTaskCreate.body.error).toContain("admission: route has no permission verb");
 
+    // The ranking state carries the private claim: a requester cannot read it.
+    const deniedRanking = await api(server.base, "GET", "/api/ranking", { bearer: userToken });
+    expect(deniedRanking.status).toBe(403);
+    expect(deniedRanking.body.error).toContain("missing permission 'config.write.any'");
+    expect(deniedRanking.body.listing).toBeUndefined();
+
     const deniedAppMove = await api(server.base, "PATCH", `/api/assets/app/${appId}/key`, {
       bearer: userToken,
       body: { key: "shared/rbac-denied/" },
@@ -369,6 +375,7 @@ describe("RBAC admission over real HTTP", () => {
         return (
           [
             "GET /api/agents/{id}/mcp-servers",
+            "GET /api/ranking",
             "GET /api/scripts/{id}/apis/{endpointId}/secret",
             "PATCH /api/assets/app/{id}/key",
             "POST /api/scripts/{id}/apis",
@@ -400,6 +407,7 @@ describe("RBAC admission over real HTTP", () => {
     const denyRows = userHttpRows.filter((row) => row.decision === "deny");
     expect(denyRows.map((row) => row.resourceId).sort()).toEqual([
       "GET /api/agents/{id}/mcp-servers",
+      "GET /api/ranking",
       "GET /api/scripts/{id}/apis/{endpointId}/secret",
       "PATCH /api/assets/app/{id}/key",
       "POST /api/scripts/{id}/apis",

package/src/tests/rbac-admission.test.ts

@@ -20,6 +20,7 @@ import { type IdentityActor, mintToken } from "../be/users";
 import { handleCore } from "../http/core";
 import { handleFs } from "../http/fs";
 import { handleMcpOAuth } from "../http/mcp-oauth";
+import { handleRealtimeTicket } from "../http/realtime";
 import { handleTasks } from "../http/tasks";
 import { getPathSegments, parseQueryParams } from "../http/utils";
 import { decideAdmission, decideToolAdmission, isRbacEnabled, type PermissionVerb } from "../rbac";
@@ -61,6 +62,7 @@ function createTestServer(): Server {
     if (await handleTasks(req, res, pathSegments, queryParams, myAgentId)) return;
     if (await handleFs(req, res, pathSegments, queryParams, myAgentId)) return;
     if (await handleMcpOAuth(req, res, pathSegments, queryParams)) return;
+    if (await handleRealtimeTicket(req, res, pathSegments, queryParams)) return;
 
     res.writeHead(404, { "Content-Type": "application/json" });
     res.end(JSON.stringify({ error: "Not Found" }));
@@ -483,6 +485,42 @@ describe("handleCore admission wiring", () => {
   });
 });
 
+describe("realtime ticket admission", () => {
+  async function grantOnly(userId: string, verbs: PermissionVerb[]): Promise<void> {
+    const roleId = `rbac-role-test-${crypto.randomUUID()}`;
+    await detachRole(userId, "admin");
+    await getDbClient().run(
+      `INSERT INTO roles (id, name, description, isBuiltin, grantsAll) VALUES (?, ?, 'test', 0, 0)`,
+      [roleId, roleId],
+    );
+    for (const verb of verbs) {
+      await getDbClient().run("INSERT INTO role_permissions (roleId, verb) VALUES (?, ?)", [
+        roleId,
+        verb,
+      ]);
+    }
+    await getDbClient().run(
+      `INSERT INTO principal_roles (principalType, principalId, roleId) VALUES ('user', ?, ?)`,
+      [userId, roleId],
+    );
+  }
+
+  test("a role with either presence verb gets a ticket; a role with neither does not", async () => {
+    process.env.RBAC_ENABLED = "true";
+    const cases: [PermissionVerb[], number][] = [
+      [["comb.presence"], 200],
+      [["session.presence"], 200],
+      [["task.read.own"], 403],
+    ];
+    for (const [verbs, expected] of cases) {
+      const { userId, plaintext } = await createTokenForUser(`Presence ${verbs.join(",")}`);
+      await grantOnly(userId, verbs);
+      const response = await api(port, "POST", "/api/realtime/ticket", { bearer: plaintext });
+      expect({ verbs, status: response.status }).toEqual({ verbs, status: expected });
+    }
+  });
+});
+
 test("RBAC defaults on and accepts explicit opt-outs", () => {
   const previous = process.env.RBAC_ENABLED;
   try {

package/src/tests/rbac-charact-http.test.ts

@@ -6,7 +6,8 @@
 //
 //   1. request auth kind "operator" (swarm key)  → allow — BEFORE any agent check,
 //      so an operator bearer with a non-owner X-Agent-ID is still allowed.
-//   2. request auth kind "user" (aswt_ token)    → allow.
+//   2. request auth kind "user" (aswt_ token)    → allow, unless it names an
+//      agent in X-Agent-ID: `handleCore` refuses that pair before any handler.
 //   3. otherwise (auth context unset): lead OR task-assignee OR task-creator
 //      → allow; anything else → 403 {"error":"Caller cannot mutate this task's files"}.
 //
@@ -205,9 +206,9 @@ describe("canMutateTask — real pipeline (handleCore auth → handleFs)", () =>
     expect(res.status).toBe(201);
   });
 
-  test("authenticated user with a non-owner X-Agent-ID is still allowed", async () => {
+  test("authenticated user naming an agent in X-Agent-ID is refused before the handler", async () => {
     const res = await pipelineUpload({ bearer: userToken, agentId: outsiderId });
-    expect(res.status).toBe(201);
+    expect(res.status).toBe(403);
   });
 });
 

package/src/tests/rbac-engine.test.ts

@@ -100,6 +100,8 @@ const LEAD_OR_OPERATOR_OR_USER_VERBS: PermissionVerb[] = [
 ];
 const OPERATOR_OR_USER_VERBS: PermissionVerb[] = [
   "comb.presence",
+  "session.share",
+  "session.presence",
   "approval.respond",
   "runtime_controller.write",
   "runtime_pool.write",

package/src/tests/rbac-roles.test.ts

@@ -17,6 +17,8 @@ const TEST_DB_PATH = "./test-rbac-roles.sqlite";
 const REQUESTER_ROLE_ID = "rbac-role-requester";
 const REQUESTER_VERBS = [
   "favorite.write.own",
+  "session.presence",
+  "session.share",
   "task.action.own",
   "task.cancel.own",
   "task.create.own",

package/src/tests/realtime-room-surfaces.test.ts

@@ -78,8 +78,10 @@ function request(path: string, body: unknown): Promise<Response> {
 }
 
 function getRequest(path: string, authorization = `Bearer ${API_KEY}`): Promise<Response> {
+  // A user token never names an agent; handleCore refuses that pair.
+  const asAgent = authorization === `Bearer ${API_KEY}`;
   return fetch(`http://localhost:${port}${path}`, {
-    headers: { Authorization: authorization, "X-Agent-ID": agentId },
+    headers: { Authorization: authorization, ...(asAgent ? { "X-Agent-ID": agentId } : {}) },
   });
 }