@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/realtime/auth.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage } from "node:http";
 import { getAgentById, getTaskById } from "../be/db";
 import { getUserGrant } from "../be/rbac-roles";
+import { getSessionRoot, sessionAccessForRoot } from "../be/session-shares";
 import { getCombConfig } from "../comb/config";
 import { mcpOverflowAuthError } from "../kv-overflow";
 import { reservedNamespaceError } from "../kv-reserved-namespaces";
@@ -19,6 +20,8 @@ export type RoomAuthorizationInfo = RoomNamespaceInfo & {
   callOrigin?: "http" | "mcp" | "ws";
   userId?: string;
   isOperator?: boolean;
+  /** The user an operator-key dashboard tab picked (`X-Swarm-User-Id`), captured on its ticket. */
+  dashboardUserId?: string;
 };
 
 export type ResolvedRoomNamespace = {
@@ -39,6 +42,7 @@ export type RoomNamespaceOperation =
 
 const COMB_PRESENCE_NAMESPACE = /^presence:comb:[A-Za-z0-9_-]{1,64}:[A-Za-z0-9_-]{1,64}$/;
 const COMB_PRESENCE_OPERATIONS = new Set<RoomNamespaceOperation>(["join", "leave", "presence"]);
+const SESSION_PRESENCE_NAMESPACE = /^presence:session:([A-Za-z0-9_-]{1,64})$/;
 
 function pageNamespace(pageId: string): string | null {
   try {
@@ -162,6 +166,10 @@ export async function authorizeRoomNamespace(
     return null;
   }
 
+  if (namespace.startsWith("presence:session:")) {
+    return authorizeSessionPresence(namespace, info, access);
+  }
+
   const reservedError = reservedNamespaceError(namespace);
   if (reservedError) return reservedError;
 
@@ -203,3 +211,64 @@ export async function authorizeRoomNamespace(
 
   return null;
 }
+
+/**
+ * Bus topic published after a session's shares change. Sockets in that
+ * session's presence room re-check access and are evicted when it ended.
+ */
+export function sessionAccessTopic(rootTaskId: string): string {
+  return `session-access:${rootTaskId}`;
+}
+
+/** The root task id of a `presence:session:<rootTaskId>` namespace, else undefined. */
+export function sessionPresenceRoot(namespace: string): string | undefined {
+  return SESSION_PRESENCE_NAMESPACE.exec(namespace)?.[1];
+}
+
+/**
+ * `presence:session:<rootTaskId>`: who is viewing (and typing in) a session.
+ * Presence-only, dashboard-only, and gated on read access so it never reveals
+ * who is inside a private session. An operator-key tab with no picked user
+ * keeps the access it has everywhere else.
+ */
+async function authorizeSessionPresence(
+  namespace: string,
+  info: RoomAuthorizationInfo,
+  access: boolean | RoomNamespaceOperation,
+): Promise<string | null> {
+  const match = SESSION_PRESENCE_NAMESPACE.exec(namespace);
+  if (!match) return "invalid session presence namespace";
+  if (info.pageId || info.agentId || (!info.isOperator && !info.userId)) {
+    return "Session presence requires dashboard authentication";
+  }
+  if (typeof access !== "string" || !COMB_PRESENCE_OPERATIONS.has(access)) {
+    return "Session presence rooms only allow join, leave, and presence";
+  }
+  const principal = info.isOperator
+    ? ({ kind: "operator" } as const)
+    : ({ kind: "user", userId: info.userId! } as const);
+  if (
+    !can({
+      principal,
+      verb: "session.presence",
+      resource: { kind: "kv-namespace", namespace },
+      source: info.callOrigin === "mcp" ? "mcp" : "http",
+    }).allow
+  ) {
+    return "Session presence requires the session.presence permission";
+  }
+  if (info.userId && isRbacEnabled()) {
+    const grant = await getUserGrant(info.userId);
+    if (!grant.grantsAll && !grant.verbs.has("session.presence")) {
+      return "Session presence requires the session.presence permission";
+    }
+  }
+  const viewerId = info.isOperator ? info.dashboardUserId : info.userId;
+  if (info.isOperator && !viewerId) return null;
+  const root = await getSessionRoot(match[1]!);
+  if (!root || root.id !== match[1]) return "session not found";
+  if ((await sessionAccessForRoot(viewerId ?? null, root)) === "none") {
+    return "You don't have access to this session";
+  }
+  return null;
+}

package/src/realtime/tickets.ts

@@ -3,7 +3,10 @@ import type { HttpRequestAuth } from "../utils/request-auth-context";
 export const REALTIME_TICKET_TTL_MS = 60_000;
 export const REALTIME_TICKET_CAPACITY = 10_000;
 
-export type RealtimeTicketAuth = Extract<HttpRequestAuth, { kind: "operator" | "user" }>;
+export type RealtimeTicketAuth = Extract<HttpRequestAuth, { kind: "operator" | "user" }> & {
+  /** The user an operator-key dashboard tab picked (`X-Swarm-User-Id`), for session presence. */
+  dashboardUserId?: string;
+};
 
 type StoredTicket = {
   auth: RealtimeTicketAuth;

package/src/realtime/transport.ts

@@ -10,7 +10,12 @@ import { extractAndVerifyCookie } from "../utils/page-session";
 import type { HttpRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { registerSessionTokenConnection } from "../utils/session-token-connections";
-import { authorizeRoomNamespace, resolveRoomNamespace } from "./auth";
+import {
+  authorizeRoomNamespace,
+  resolveRoomNamespace,
+  sessionAccessTopic,
+  sessionPresenceRoot,
+} from "./auth";
 import { realtimeBus } from "./bus";
 import {
   addWorkerSubscription,
@@ -64,6 +69,7 @@ type Identity = {
   pageId?: string;
   userId?: string;
   isOperator?: boolean;
+  dashboardUserId?: string;
 };
 type Viewer = { userId: string; name: string; kind: "user" | "guest" | "agent" };
 type AuthenticatedConnection = {
@@ -81,7 +87,7 @@ function header(req: IncomingMessage, name: string): string | undefined {
 
 function identityFromHttpAuth(
   req: IncomingMessage,
-  auth: HttpRequestAuth,
+  auth: HttpRequestAuth & { dashboardUserId?: string },
 ): AuthenticatedConnection {
   if (auth.kind === "controller") throw new Error("Controller tokens cannot use realtime");
   if (auth.kind === "agent") {
@@ -110,6 +116,7 @@ function identityFromHttpAuth(
         auth.kind === "agent" ? (auth.taskId ?? undefined) : header(req, "x-source-task-id"),
       userId: auth.kind === "user" ? auth.userId : undefined,
       isOperator: auth.kind === "operator",
+      dashboardUserId: auth.kind === "operator" ? auth.dashboardUserId : undefined,
     } satisfies Identity,
     me: {
       userId: auth.kind === "user" ? auth.userId : (agentId ?? guestId),
@@ -228,7 +235,12 @@ function connect(
       )
     : undefined;
   void auth.sessionToken?.check().catch(() => ws.close(1008, "Session token revoked or expired"));
-  const rooms = new Map<string, { room: LiveRoom; version: number; stop: () => void }>();
+  // `suspended`: a session presence room whose access is being re-checked
+  // after a share change; nothing is forwarded until the check passes.
+  const rooms = new Map<
+    string,
+    { room: LiveRoom; version: number; stop: () => void; suspended?: boolean }
+  >();
   const channels = new Map<string, () => void>();
   const pending = new Map<number, number>();
   const clientId = crypto.getRandomValues(new Uint32Array(1))[0]!;
@@ -313,6 +325,9 @@ function connect(
       if (namespace.startsWith("presence:comb:") && msg.name !== "default") {
         throw new Error("Comb presence uses the default room");
       }
+      if (namespace.startsWith("presence:session:") && msg.name !== "default") {
+        throw new Error("Session presence uses the default room");
+      }
       const denied = await authorizeRoomNamespace(namespace, auth.identity, msg.op, msg.name);
       if (denied) throw new Error(typeof denied === "string" ? denied : "Forbidden");
       if (closed) return;
@@ -352,12 +367,14 @@ function connect(
             room = await getRoom(namespace, msg.name, msg.schemaVersion, { create: false });
           } catch (error) {
             if (!(error instanceof Error) || error.message !== "room does not exist") throw error;
-            // Creating a room is a write. Comb presence rooms take only presence
-            // operations, so they check creation as a join.
+            // Creating a room is a write. Comb and session presence rooms take
+            // only presence operations, so they check creation as a join.
             const creationDenied = await authorizeRoomNamespace(
               namespace,
               auth.identity,
-              namespace.startsWith("presence:comb:") ? "join" : true,
+              namespace.startsWith("presence:comb:") || namespace.startsWith("presence:session:")
+                ? "join"
+                : true,
             );
             if (creationDenied) throw new Error(creationDenied);
             if (closed) return;
@@ -365,6 +382,7 @@ function connect(
           }
           if (closed) return;
           const stopRoom = realtimeBus.subscribe(key, (event) => {
+            if (rooms.get(key)?.suspended) return;
             const view = event as ReturnType<typeof roomView> & { type: string };
             const type = view.type;
             if (type === "deleted") {
@@ -387,17 +405,67 @@ function connect(
                 .catch(() => ws.close(1011, "Room reset failed"));
             }
           });
-          const stopPresence = realtimeBus.subscribe(`presence:${key}`, (peers) =>
-            send({ type: "presence", name: msg.name, namespace, peers }),
-          );
+          const stopPresence = realtimeBus.subscribe(`presence:${key}`, (peers) => {
+            if (rooms.get(key)?.suspended) return;
+            send({ type: "presence", name: msg.name, namespace, peers });
+          });
+          const sessionRoot = sessionPresenceRoot(namespace);
+          let accessCheck = 0;
+          // A share change can end this viewer's read access: stop forwarding
+          // at once, then evict, or resume if access remains.
+          const stopAccess = sessionRoot
+            ? realtimeBus.subscribe(sessionAccessTopic(sessionRoot), () => {
+                const joined = rooms.get(key);
+                if (!joined) return;
+                joined.suspended = true;
+                const check = ++accessCheck;
+                void authorizeRoomNamespace(namespace, auth.identity, "join")
+                  .catch(() => "Session access check failed")
+                  .then((denied) => {
+                    const current = rooms.get(key);
+                    if (closed || !current || check !== accessCheck) return;
+                    if (denied) {
+                      leave(key);
+                      send({ type: "error", name: msg.name, namespace, error: denied });
+                      return;
+                    }
+                    current.suspended = false;
+                    send({
+                      type: "presence",
+                      name: msg.name,
+                      namespace,
+                      peers: [...current.room.awareness.getStates().values()],
+                    });
+                  });
+              })
+            : undefined;
           rooms.set(key, {
             room,
             version: msg.schemaVersion,
             stop: () => {
               stopRoom();
               stopPresence();
+              stopAccess?.();
             },
+            suspended: sessionRoot !== undefined,
           });
+          if (sessionRoot) {
+            // A share change published while the room loaded reached no
+            // subscriber, so check again now that the access subscriber is
+            // live. Anything later is that subscriber's to handle.
+            const check = ++accessCheck;
+            const denied = await authorizeRoomNamespace(namespace, auth.identity, "join").catch(
+              () => "Session access check failed",
+            );
+            if (closed) return;
+            if (denied) {
+              leave(key);
+              throw new Error(denied);
+            }
+            const current = rooms.get(key);
+            if (!current) throw new Error("You don't have access to this session");
+            if (check === accessCheck) current.suspended = false;
+          }
           room.awareness.states.set(clientId, { ...auth.me, data: {} });
           room.awareness.meta.set(clientId, { clock: 1, lastUpdated: Date.now() });
           publishPresence(room);

package/src/slack/blocks.ts

@@ -97,6 +97,10 @@ export function splitSlackSectionText(text: string): string[] {
     if (splitIdx < MAX_SECTION_LENGTH / 2) {
       // No good break point at all, hard split
       splitIdx = MAX_SECTION_LENGTH;
+      // Keep a surrogate pair (emoji, astral char) together: never end a
+      // chunk on a lone high surrogate.
+      const prev = remaining.charCodeAt(splitIdx - 1);
+      if (prev >= 0xd800 && prev <= 0xdbff) splitIdx -= 1;
     }
     chunks.push(remaining.slice(0, splitIdx));
     remaining = remaining.slice(splitIdx).trimStart();
@@ -104,6 +108,20 @@ export function splitSlackSectionText(text: string): string[] {
   return chunks;
 }
 
+// Slack's hard cap on section text.
+const SLACK_SECTION_TEXT_LIMIT = 3000;
+
+/**
+ * Default blocks for a tool message sent without explicit `blocks`: one
+ * mrkdwn section per chunk, so text over the section limit still sends.
+ * Text Slack accepts in one section stays one section, so links and code
+ * fences are never split below the limit.
+ */
+export function buildMrkdwnSectionBlocks(text: string): SlackBlock[] {
+  if (text.length <= SLACK_SECTION_TEXT_LIMIT) return [sectionBlock(text)];
+  return splitSlackSectionText(text).map((chunk) => sectionBlock(chunk));
+}
+
 // --- Block primitives ---
 
 function contextBlock(...elements: string[]): SlackBlock {

package/src/slack/dm.ts

@@ -0,0 +1,29 @@
+import type { WebClient } from "@slack/web-api";
+
+/** Slack user ids start with U (or W on Enterprise Grid); conversation ids start with C, G or D. */
+export function isSlackUserId(id: string): boolean {
+  return /^[UW][A-Z0-9]+$/.test(id);
+}
+
+/**
+ * Resolves a user id to the bot's own DM with that user; returns any other id unchanged.
+ *
+ * chat.postMessage accepts a user id as `channel`, but Slack documents that the
+ * message then lands in the user's DM with Slackbot (USLACK), which the bot is
+ * not a member of. conversations.replies and chat.postMessage on the returned
+ * D id fail with channel_not_found, and human replies never reach the bot as
+ * message.im events. conversations.open returns the bot's own IM, which it can
+ * read, write, and receives events for.
+ */
+export async function resolveSlackConversationId(
+  client: WebClient,
+  channelId: string,
+): Promise<string> {
+  if (!isSlackUserId(channelId)) return channelId;
+  const result = await client.conversations.open({ users: channelId });
+  const dmId = result.channel?.id;
+  if (!dmId) {
+    throw new Error(`conversations.open returned no DM channel for user ${channelId}`);
+  }
+  return dmId;
+}

package/src/telemetry-contract/EVENTS.md

@@ -64,6 +64,9 @@ Common properties, allowed on every event of this product:
 | `popup.dismissed` | ui | 2026-10-12 | A dashboard pop-up was closed without submitting. | `method` (later \| close \| escape, required)<br>`popup` (feedback \| org_name \| used_by, required) |
 | `popup.shown` | ui | 2026-10-12 | A dashboard pop-up was shown. Telemetry-gated: never sent while telemetry is off. | `popup` (feedback \| org_name \| used_by, required)<br>`trigger` (task_failed \| tasks_completed \| workflow_completed \| quarterly \| missing_org_name, required) |
 | `popup.submitted` | ui | 2026-10-12 | A dashboard pop-up was submitted. Content stays out of telemetry: only flags for what was filled. | `has_contact` (boolean, required)<br>`has_message` (boolean, required)<br>`popup` (feedback \| org_name \| used_by, required)<br>`score` (integer ≥0) |
+| `ranking.opted_in` | api-server | 2026-10-18 | An admin opted the install into the public ranking, or the API rebuilt its listing after an org identity change. | `listing` (string, required) |
+| `ranking.opted_out` | api-server | 2026-10-18 | The install left the public ranking: the admin turned it off, or the org name or website was cleared or changed. | `domain` (string, required) |
+| `ranking.usage` | worker | 2026-10-18 | Token usage of one session on an install opted into the public ranking. Sent next to session.cost. | `cacheReadTokens` (integer ≥0)<br>`cacheWriteTokens` (integer ≥0)<br>`inputTokens` (integer ≥0, required)<br>`model` (string)<br>`outputTokens` (integer ≥0, required)<br>`provider` (string)<br>`totalTokens` (integer ≥0, required) |
 | `schedule.error` | api-server | 2026-09-30 | A schedule failed to fire. | `consecutiveErrors` (integer, required)<br>`scheduleType` (string, required)<br>`triggeredWorkflows` (boolean, required)<br>`wasRecovered` (boolean, required) |
 | `schedule.executed` | api-server | 2026-09-30 | A schedule fired. | `scheduleType` (string, required)<br>`triggeredWorkflows` (boolean, required)<br>`wasRecovered` (boolean, required) |
 | `server.shutdown` | api-server | 2026-09-30 | The API server shut down. | `sessionsProcessed` (integer, required)<br>`signal` (string, required)<br>`uptimeMs` (integer, required) |

package/src/telemetry-contract/SOURCE.json

@@ -1,9 +1,42 @@
 {
   "repo": "desplega-ai/proxy",
-  "commit": "09ef0f38647e387d1e10485de5968ba047a2cef1",
+  "commit": "6260f39827fc57784642b1adc88a43f61d882a6f",
   "files": {
-    "types.gen.ts": "9de6741502759552556b4073a1ca30cd1fbae8cf349dda6754b4ed7d7f271097",
-    "catalog.json": "b6dd31da171ac2545f311473f2b6cd306a03827870fa86472200aa938c044214",
-    "EVENTS.md": "8ae820a977bba7f4cb3972aae1295cb6b12e1e5ee81d3ffed55606e213a66004"
+    "types.gen.ts": "192c6769164a65b6e804ea088b38de6827d34fac26a7ecaccce881a46e98b1a7",
+    "catalog.json": "1b2b052f8e43f082e9d6efc2768752d6f194c0cbf0d26ae9c35643cce0e6486c",
+    "EVENTS.md": "9451da995ef04a049888715f960a1641bbc52fecb3dce97610c3c391bead1faf",
+    "ranking/fixtures/expected.json": "6d506546f48d99a089666bed2a4c08752ebb63a029392c76ffd057e9520adc70",
+    "ranking/fixtures/invalid/bad-category.json": "a4c36da6079c36d15e5e8c8e6322fc97b172de015a80a26cee8cab699f666236",
+    "ranking/fixtures/invalid/bad-claim.json": "cee14d465545d057cfb61922301a5119187ba17d70efabb16528a5e305d7b065",
+    "ranking/fixtures/invalid/blank-description.json": "bf1ae1a834613b67b59f42c158e892448f23268b41f1c851653f25e4843a20b0",
+    "ranking/fixtures/invalid/blank-name.json": "7e2cc0156ac5f5d42342a99c38fe0f822b893784f17cdcfa371277c847d83a2e",
+    "ranking/fixtures/invalid/description-too-long.json": "c96ed93d014fbdac8c674ab8266d41bca83547d42a0d6dec53f275a0258d1adf",
+    "ranking/fixtures/invalid/domain-uppercase.json": "5a3cefdceddf7716d0b6300453a928e122e3ca8fa55493d48666701ca9853ebb",
+    "ranking/fixtures/invalid/domain-with-scheme.json": "389f6216e350c8b13f472658b15bc485693a0064cf837a5a66a3f74cef8f26c3",
+    "ranking/fixtures/invalid/domain-with-www.json": "b936fd61b21ad5f0219e739686372b16e4e97c2101f239ed3497bb73b0307205",
+    "ranking/fixtures/invalid/http-source-url.json": "dcab46205d9113864f31966affe74edb9a9ffe1b2fc9bfb3923997daa30cf651",
+    "ranking/fixtures/invalid/missing-description.json": "9a3a3a1104c9e1c3dea17d3a81be87dcd96188d64729e601ecc94848215aea49",
+    "ranking/fixtures/invalid/missing-version.json": "81b54c7cae034bd6327b981ec17609e926f5ee03465b589bc997c5ec9ddfc60b",
+    "ranking/fixtures/invalid/name-not-string.json": "46af1d97dbe77735a8020dd3c7ea1b67f71d8310cc065341b82173229d6f9487",
+    "ranking/fixtures/invalid/name-too-long.json": "8c07bce282182b8e0d9476a70a78863c708ce25d6cce3c994e29c0ec10972255",
+    "ranking/fixtures/invalid/not-object.json": "53bd6a73a22019f092e9e6e454936e8ba172201553f897f43f478f4946effaea",
+    "ranking/fixtures/invalid/null.json": "38e0b9de817f645c4bec37c0d4a3e58baecccb040f5718dc069a72c7385a0bed",
+    "ranking/fixtures/invalid/other-with-subcategory.json": "e5bdaf6982b5bf8fedf08b31c40232808f91884177a88cae5c6ab45489aec892",
+    "ranking/fixtures/invalid/oversize.json": "e57b2d8030a3b62b6621fcd81eb90959c22d190d4bfb5ee834086808249ddbe2",
+    "ranking/fixtures/invalid/short-claim.json": "051e789f8989b052173ab90a21d6358200f45cadfb729f36081c462ba9a8096b",
+    "ranking/fixtures/invalid/subcategory-other-category.json": "3d4ca6ce612ace116e382b08579ee451b2c1cbf93716cb01ad61489b7cecbcd8",
+    "ranking/fixtures/invalid/trailing-data.json": "ffb822a83c7a2bfb41c6fdfab375c11232db70e5063ace529a1e4cc7b6be44ff",
+    "ranking/fixtures/invalid/unknown-field.json": "c24c57f208523d4de535057a636de1fc5abcad329d514baabb180cbcfdd6a5b9",
+    "ranking/fixtures/invalid/unsupported-version.json": "32e5c26b9c646090a3e94822594b208d629e60796c00f964216859ee8d086dc7",
+    "ranking/fixtures/invalid/updated-at-not-date.json": "a03111ddc50bcfc818b30e977a4b94c566884b04322e1600e7f70a04c120d5c1",
+    "ranking/fixtures/invalid/updated-at-offset.json": "91b78160eb83da274bb3d93fbd812b72f2e648935a31fb5685b32037391e63fc",
+    "ranking/fixtures/invalid/wrong-case-field.json": "76c8a019d0aabdd1ca394f3ea552511a98b2458e7b850b75289f88a665682087",
+    "ranking/fixtures/valid/category-without-subcategory.json": "45c5b872aec232bdcba791e6ba1a7aba698c825f389e194a38e96ad141f56e5a",
+    "ranking/fixtures/valid/full.json": "d6d93c4a6159e814c3f089c69083df700fb19359f127ccd2b71529a058dfe5e9",
+    "ranking/fixtures/valid/minimal.json": "de6629d6ee2c4b67598abfc5ec7f6470a93dd9893b07e6e7c93d018cf5445593",
+    "ranking/fixtures/valid/padded-text.json": "db71248bf83bb1ffb639208ec467a0228e5c37f604299d09838ab25dc61986a3",
+    "ranking/fixtures/valid/unicode-name.json": "01a9d2cc8c5fec128af3eef35bf16696286f28636dac21b9dec107b28fddf743",
+    "ranking/listing.v1.schema.json": "1895c57075bbb4b0945e1c5daf813d6c4eaccf1f4480cabd6dc0ce2f0d146776",
+    "ranking/taxonomy.json": "c6abe7e437635c9a3c1a82a3477a8757ba6c0cb7cbeae86c8c3d175fb37f402c"
   }
 }

package/src/telemetry-contract/catalog.json

@@ -1376,6 +1376,75 @@
         }
       }
     },
+    {
+      "product": "agent-swarm",
+      "event": "ranking.opted_in",
+      "description": "An admin opted the install into the public ranking, or the API rebuilt its listing after an org identity change.",
+      "since": "2026-10-18",
+      "source": "api-server",
+      "properties": {
+        "listing": {
+          "type": "string",
+          "required": true,
+          "description": "The stringified telemetry_ranking listing (contracts/telemetry/ranking/listing.v1.schema.json). The ingest also requires its name and domain to equal context.org_name and context.org_website."
+        }
+      }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "ranking.opted_out",
+      "description": "The install left the public ranking: the admin turned it off, or the org name or website was cleared or changed.",
+      "since": "2026-10-18",
+      "source": "api-server",
+      "properties": {
+        "domain": {
+          "type": "string",
+          "required": true,
+          "description": "The listing domain that leaves the ranking: a lowercase hostname."
+        }
+      }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "ranking.usage",
+      "description": "Token usage of one session on an install opted into the public ranking. Sent next to session.cost.",
+      "since": "2026-10-18",
+      "source": "worker",
+      "properties": {
+        "totalTokens": {
+          "type": "integer",
+          "required": true,
+          "minimum": 0,
+          "description": "inputTokens + cacheReadTokens + cacheWriteTokens + outputTokens. The ranking sums this."
+        },
+        "inputTokens": {
+          "type": "integer",
+          "required": true,
+          "minimum": 0
+        },
+        "outputTokens": {
+          "type": "integer",
+          "required": true,
+          "minimum": 0
+        },
+        "cacheReadTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cacheWriteTokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "model": {
+          "type": "string",
+          "description": "The session's model, the same value as session.cost.model. Usage without it, or with a value the ranking does not accept, is shown as the model unknown."
+        },
+        "provider": {
+          "type": "string",
+          "description": "The session's provider, the same value as session.cost.provider. Missing means unknown."
+        }
+      }
+    },
     {
       "product": "agent-fs",
       "event": "server.started",

package/src/telemetry-contract/ranking/fixtures/expected.json

@@ -0,0 +1,30 @@
+{
+  "$comment": "Every file in valid/ must parse in the proxy (ParseListing) and in agent-swarm (parseTelemetryRanking). Every file in invalid/ must fail in both; the value is the field the proxy names in its invalid_property message. A file's exact bytes are the listing string.",
+  "invalid": {
+    "bad-claim.json": "listing.claim",
+    "short-claim.json": "listing.claim",
+    "missing-description.json": "listing.description",
+    "unknown-field.json": "listing.logo",
+    "wrong-case-field.json": "listing.Claim",
+    "unsupported-version.json": "listing.v",
+    "missing-version.json": "listing.v",
+    "bad-category.json": "listing.category",
+    "subcategory-other-category.json": "listing.subcategory",
+    "other-with-subcategory.json": "listing.subcategory",
+    "http-source-url.json": "listing.sourceCodeUrl",
+    "domain-with-scheme.json": "listing.domain",
+    "domain-with-www.json": "listing.domain",
+    "domain-uppercase.json": "listing.domain",
+    "name-too-long.json": "listing.name",
+    "blank-name.json": "listing.name",
+    "blank-description.json": "listing.description",
+    "description-too-long.json": "listing.description",
+    "name-not-string.json": "listing.name",
+    "updated-at-offset.json": "listing.updatedAt",
+    "updated-at-not-date.json": "listing.updatedAt",
+    "not-object.json": "listing",
+    "null.json": "listing",
+    "trailing-data.json": "listing",
+    "oversize.json": "listing"
+  }
+}

package/src/telemetry-contract/ranking/fixtures/invalid/bad-category.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "games",
+  "subcategory": null,
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/bad-claim.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3F9A1C0E7B2D4A6F8E1C3B5D7F9A2C4E",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/blank-description.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "  ",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/blank-name.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "   ",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/description-too-long.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "ddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/domain-uppercase.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "Example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/domain-with-scheme.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "https://example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/domain-with-www.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "www.example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/http-source-url.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "http://github.com/example/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/missing-description.json

@@ -0,0 +1,10 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/missing-version.json

@@ -0,0 +1,10 @@
+{
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "qa-testing",
+  "description": "QA and release automation for our web apps",
+  "sourceCodeUrl": "https://example.org/agents",
+  "updatedAt": "2026-10-18T10:00:00.000Z"
+}