@desplega.ai/agent-swarm 2.3.0 → 2.4.1

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-context.ts

@@ -9,6 +9,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import { type EventContext, TRIGGER_SURFACES, type TriggerSurface } from "./telemetry-contract";
 import catalog from "./telemetry-contract/catalog.json";
+import {
+  COMPANY_ACQUISITION_SOURCES,
+  COMPANY_TEAM_SIZES,
+  COMPANY_USE_CASES,
+  USER_FUNCTIONS,
+} from "./utils/company-profile";
 
 /** `org_` + 16 lowercase hex (self-host, minted here) or 27 alphanumerics (cloud). Same pattern the proxy enforces. */
 const ORG_ID_PATTERN = /^org_([0-9a-f]{16}|[A-Za-z0-9]{27})$/;
@@ -97,6 +103,9 @@ export interface ContextInput {
   installMethod?: string | null;
   installPreset?: string | null;
   acquisitionSource?: string | null;
+  teamSize?: string | null;
+  useCase?: string | null;
+  userFunction?: string | null;
 }
 
 /** Build the top-level `context` object of a schema_version 2 event. */
@@ -105,6 +114,11 @@ export function buildContext(input: ContextInput): EventContext {
   const orgName = input.orgName?.trim();
   const orgDomain = validOrgDomain(input.orgDomain);
   const orgWebsite = validOrgDomain(input.orgWebsite);
+  const teamSize = COMPANY_TEAM_SIZES.find((value) => value === input.teamSize);
+  const useCase = COMPANY_USE_CASES.find((value) => value === input.useCase);
+  const userFunction = userId
+    ? USER_FUNCTIONS.find((value) => value === input.userFunction)
+    : undefined;
   return {
     org_id: input.orgId,
     org_name: orgName ? orgName : null,
@@ -116,10 +130,14 @@ export function buildContext(input: ContextInput): EventContext {
     swarm_version: input.swarmVersion,
     install_method: input.installMethod ?? null,
     install_preset: input.installPreset ?? null,
-    acquisition_source: input.acquisitionSource ?? null,
+    acquisition_source:
+      COMPANY_ACQUISITION_SOURCES.find((value) => value === input.acquisitionSource) ?? null,
     // Optional in the catalog: left out, not null, when unset, so an ingest
     // that predates the field keeps accepting events from installs without one.
     ...(orgWebsite ? { org_website: orgWebsite } : {}),
+    ...(teamSize ? { team_size: teamSize } : {}),
+    ...(useCase ? { use_case: useCase } : {}),
+    ...(userFunction ? { user_function: userFunction } : {}),
   };
 }
 

package/src/telemetry-contract/EVENTS.md

@@ -4,18 +4,48 @@
 
 Every event the ingest accepts with `schema_version: 2`. A v2 event that is not listed here, or that sends a property not listed for it, is rejected with a typed 400. `Emitter` is the envelope `source`.
 
+## `acquisition_source`
+
+How the organization found Agent Swarm.
+
+Values: `search`, `github`, `social`, `colleague`, `newsletter`, `event`, `ai_assistant`, `hacker_news`, `other`.
+
+## `notification_moment`
+
+Moment that made the Slack Connect invite relevant.
+
+Values: `task_failed`, `first_workflow`, `default`.
+
 ## `popup`
 
 Dashboard pop-up that a popup.* event is about.
 
 Values: `feedback`, `org_name`, `used_by`.
 
+## `team_size`
+
+Size of the organization team.
+
+Values: `1`, `2-10`, `11-50`, `51+`.
+
 ## `trigger_surface`
 
 Surface that started a chain of work: agent-swarm's AgentTaskSourceSchema values plus other.
 
 Values: `slack`, `ui`, `api`, `mcp`, `github`, `gitlab`, `linear`, `jira`, `agentmail`, `schedule`, `workflow`, `system`, `other`.
 
+## `use_case`
+
+Primary use of the swarm.
+
+Values: `features`, `bugs`, `review`, `ops`, `docs`, `data`.
+
+## `user_function`
+
+Job function of a user, separate from the RBAC user_role.
+
+Values: `engineer`, `eng_lead`, `founder`, `product`, `ops`, `other`.
+
 ## `agent-fs`
 
 | Event | Emitter | Since | Description | Properties |
@@ -44,12 +74,15 @@ Common properties, allowed on every event of this product:
 | `agent.registered` | api-server | 2026-09-30 | An agent registered or reconnected. | `capabilities` (array, required)<br>`isReconnect` (boolean, required)<br>`role` (string) |
 | `compaction.triggered` | worker | 2026-09-30 | The harness compacted a session context. | `compactTrigger` (string, required)<br>`contextTotalTokens` (integer, required)<br>`preCompactTokens` (integer, required) |
 | `feature.used` | ui | 2026-09-30 | A dashboard feature was used. | `feature` (string, required) |
-| `fleet_benchmark.viewed` | ui | 2026-10-12 | The fleet benchmark card was shown. | `has_org_name` (boolean, required) |
+| `fleet_benchmark.unlocked` | ui | 2026-10-18 | An admin supplied the company profile fields for the full benchmark. | `fields` (array of website \| team_size \| use_case, required) |
+| `fleet_benchmark.viewed` | ui | 2026-10-12 | The fleet benchmark card was shown. | `has_org_name` (boolean, required)<br>`level` (basic \| full) |
+| `identity.lookup` | ui | 2026-10-18 | A dashboard identity lookup matched an existing user or found no match. | `matched` (boolean, required) |
+| `identity.user_created` | ui | 2026-10-18 | A user created a dashboard identity. Email and personal names stay out of telemetry. | `email_kind` (work \| personal, required)<br>`has_company` (boolean, required)<br>`has_function` (boolean, required)<br>`surface` (identity_modal \| setup, required) |
 | `integration.connected` | api-server | 2026-09-30 | An integration was connected. | `first_of_type` (boolean, required)<br>`provider` (string)<br>`type` (string, required) |
 | `lead.captured` | api-server | 2026-09-30 | A consented lead (Teams waitlist or private-beta sign-up). The email stays in feedback_submissions. | `channel` (string, required)<br>`consent` (boolean, required)<br>`submission_id` (string, required) |
-| `notification.dismissed` | ui | 2026-09-30 | A notification-centre item was dismissed. | `key` (string, required) |
-| `notification.submitted` | ui | 2026-09-30 | A notification-centre item was submitted. | `email_domain` (string)<br>`key` (string, required) |
-| `notification.viewed` | ui | 2026-09-30 | A notification-centre item was shown. | `key` (string, required) |
+| `notification.dismissed` | ui | 2026-09-30 | A notification-centre item was dismissed. | `key` (string, required)<br>`moment` (task_failed \| first_workflow \| default) |
+| `notification.submitted` | ui | 2026-09-30 | A notification-centre item was submitted. | `email_domain` (string)<br>`key` (string, required)<br>`moment` (task_failed \| first_workflow \| default)<br>`user_function` (engineer \| eng_lead \| founder \| product \| ops \| other) |
+| `notification.viewed` | ui | 2026-09-30 | A notification-centre item was shown. | `key` (string, required)<br>`moment` (task_failed \| first_workflow \| default) |
 | `onboarding.completed` | api-server | 2026-09-30 | Onboarding was completed. | `seconds_since_install` (integer)<br>`seconds_since_start` (integer, required) |
 | `onboarding.dismissed` | api-server | 2026-09-30 | Onboarding was dismissed. | `seconds_since_install` (integer)<br>`seconds_since_start` (integer, required) |
 | `onboarding.first_task_completed` | api-server | 2026-09-30 | The first task after onboarding completed. | `method` (string)<br>`seconds_since_install` (integer)<br>`seconds_since_start` (integer, required) |
@@ -58,12 +91,15 @@ Common properties, allowed on every event of this product:
 | `onboarding.step_failed` | api-server | 2026-09-30 | An onboarding step failed. | `error_class` (string, required)<br>`seconds_since_install` (integer)<br>`seconds_since_start` (integer, required)<br>`step` (string, required) |
 | `onboarding.step_skipped` | api-server | 2026-09-30 | An onboarding step was skipped. | `seconds_since_install` (integer)<br>`seconds_since_start` (integer, required)<br>`step` (string, required) |
 | `onboarding.step_viewed` | api-server | 2026-09-30 | An onboarding step was shown. | `seconds_since_install` (integer)<br>`seconds_since_start` (integer, required)<br>`step` (string, required) |
-| `org.profile_updated` | ui | 2026-10-12 | An admin changed the org profile. Lists which fields changed, never their values. | `fields` (array, required)<br>`surface` (prompt \| setup \| settings, required) |
+| `org.profile_updated` | ui | 2026-10-12 | An admin changed the org profile. Lists which fields changed, never their values. | `fields` (array of name \| website \| team_size \| use_case \| acquisition_source, required)<br>`surface` (enum, required) |
 | `org.snapshot` | api-server | 2026-09-30 | Daily per-install user and agent counts. Counts only: no names, emails or IDs. | `agents_total` (integer ≥0, required)<br>`users_active_7d` (integer ≥0, required)<br>`users_admin` (integer ≥0, required)<br>`users_linked_github` (integer ≥0, required)<br>`users_linked_gitlab` (integer ≥0, required)<br>`users_linked_jira` (integer ≥0, required)<br>`users_linked_linear` (integer ≥0, required)<br>`users_linked_other` (integer ≥0, required)<br>`users_linked_slack` (integer ≥0, required)<br>`users_suspended` (integer ≥0, required)<br>`users_total` (integer ≥0, required)<br>`users_with_login` (integer ≥0, required) |
 | `page.viewed` | ui | 2026-09-30 | A dashboard page was viewed. | `route_template` (string, required) |
 | `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) |
+| `popup.submitted` | ui | 2026-10-12 | A dashboard pop-up was submitted. Content stays out of telemetry: only flags for what was filled. | `answered` (integer ≥0)<br>`has_contact` (boolean, required)<br>`has_message` (boolean, required)<br>`perks` (array of used_by \| slack_connect)<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) |
@@ -74,6 +110,7 @@ Common properties, allowed on every event of this product:
 | `session.failure` | worker | 2026-09-30 | A session failed. | `agentId` (string, required)<br>`durationMs` (integer, required)<br>`errorCategory` (string, required)<br>`model` (string, required)<br>`provider` (string, required)<br>`taskId` (string, nullable, required)<br>`trigger_surface` (enum, nullable, required)<br>`wasRateLimited` (boolean, required) |
 | `session.started` | worker | 2026-09-30 | A worker or lead session started. | `agentId` (string, required)<br>`harnessProvider` (string, required)<br>`model` (string)<br>`role` (string, required)<br>`taskId` (string, nullable, required)<br>`trigger_surface` (enum, nullable, required) |
 | `session.steered` | api-server | 2026-09-30 | A running session received a steering message. | `by_kind` (string, required)<br>`trigger_surface` (enum, nullable, required) |
+| `setup.worker_command_copied` | ui | 2026-10-18 | An admin copied a worker command from the setup health popover. | `harness` (enum, required)<br>`target` (compose \| docker \| kubernetes, required) |
 | `skill.invoked` | worker | 2026-09-30 | A skill was invoked in a session. | `skill_name` (string, required)<br>`skill_source` (string, required)<br>`trigger_surface` (enum, nullable, required) |
 | `task.cancelled` | api-server | 2026-09-30 | A task was cancelled. | `agentId` (string)<br>`durationMs` (integer)<br>`previousStatus` (string, required)<br>`taskId` (string, required)<br>`task_source` (enum, required)<br>`trigger_surface` (enum, required) |
 | `task.claimed` | api-server | 2026-09-30 | An agent claimed a task. | `agentId` (string, required)<br>`taskId` (string, required)<br>`task_source` (enum, required)<br>`trigger_surface` (enum, required) |
@@ -83,9 +120,9 @@ Common properties, allowed on every event of this product:
 | `task.session_completed` | worker | 2026-09-30 | A worker session for a task finished. | `agentId` (string, required)<br>`durationMs` (integer, required)<br>`exitCode` (integer, required)<br>`harnessVariant` (string)<br>`harnessVersion` (string)<br>`isError` (boolean, required)<br>`model` (string, required)<br>`provider` (string, required)<br>`taskId` (string, nullable, required)<br>`trigger_surface` (enum, nullable, required) |
 | `task.started` | api-server | 2026-09-30 | A task started running. | `agentId` (string, required)<br>`taskId` (string, required)<br>`task_source` (enum, required)<br>`trigger_surface` (enum, required) |
 | `task.superseded` | api-server | 2026-09-30 | A task was superseded by another task. | `agentId` (string)<br>`durationMs` (integer)<br>`harnessVariant` (string)<br>`harnessVersion` (string)<br>`provider` (string)<br>`reason` (string, required)<br>`taskId` (string, required)<br>`task_source` (enum, required)<br>`trigger_surface` (enum, required) |
-| `telemetry.enabled` | api-server | 2026-10-12 | Telemetry was turned on. Sent once, on the first boot or re-init after opting in. | `via` (banner \| settings \| env, required) |
+| `telemetry.enabled` | api-server | 2026-10-12 | Telemetry was turned on. Sent once, on the first boot or re-init after opting in. | `via` (banner \| settings \| env \| benchmark, required) |
 | `ui.session_started` | ui | 2026-09-30 | A dashboard session started. | none |
-| `used_by.consent_changed` | ui | 2026-10-12 | An admin granted or revoked the "used by" logo consent. The request itself goes to /v1/used-by. | `granted` (boolean, required) |
+| `used_by.consent_changed` | ui | 2026-10-12 | An admin granted or revoked the "used by" logo consent. The request itself goes to /v1/used-by. | `granted` (boolean, required)<br>`has_function` (boolean)<br>`has_quote` (boolean) |
 | `workflow.completed` | api-server | 2026-09-30 | A workflow run completed. | `durationMs` (integer)<br>`stepsCompleted` (integer, required)<br>`stepsFailed` (integer, required)<br>`workflowId` (string, required) |
 | `workflow.created` | api-server | 2026-09-30 | A workflow was created. | `nodeCount` (integer, required)<br>`via` (api \| mcp)<br>`workflowId` (string, required) |
 | `workflow.deleted` | api-server | 2026-09-30 | A workflow was deleted. | `via` (api \| mcp)<br>`workflowId` (string, required) |

package/src/telemetry-contract/SOURCE.json

@@ -1,9 +1,43 @@
 {
   "repo": "desplega-ai/proxy",
-  "commit": "09ef0f38647e387d1e10485de5968ba047a2cef1",
+  "commit": "cc593585467a920dcb8731993d092639372dc7af",
   "files": {
-    "types.gen.ts": "9de6741502759552556b4073a1ca30cd1fbae8cf349dda6754b4ed7d7f271097",
-    "catalog.json": "b6dd31da171ac2545f311473f2b6cd306a03827870fa86472200aa938c044214",
-    "EVENTS.md": "8ae820a977bba7f4cb3972aae1295cb6b12e1e5ee81d3ffed55606e213a66004"
+    "types.gen.ts": "aa8a682f1d875515d63cf5bd3fa667dcb06cd851f8b2b798482a4c71cd775444",
+    "catalog.json": "595654f288ae2a7cbb265b6b2a72392acc33f5acde365d72829101912525a891",
+    "EVENTS.md": "51ee5491c633d684b163d727a369a08b5c1d3f4ba453277d840526449a0bad0c",
+    "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/no-claim.json": "fa5c08ec50c1b602f404cf36ce8b1c03d131111379d914699378dd448431cb84",
+    "ranking/fixtures/valid/padded-text.json": "db71248bf83bb1ffb639208ec467a0228e5c37f604299d09838ab25dc61986a3",
+    "ranking/fixtures/valid/unicode-name.json": "01a9d2cc8c5fec128af3eef35bf16696286f28636dac21b9dec107b28fddf743",
+    "ranking/listing.v1.schema.json": "f839b669abadb25e031515a5cc2abd3aa2024e85e6117cae83133fc9dfbb769d",
+    "ranking/taxonomy.json": "c6abe7e437635c9a3c1a82a3477a8757ba6c0cb7cbeae86c8c3d175fb37f402c"
   }
 }

package/src/telemetry-contract/catalog.json

@@ -27,6 +27,64 @@
         "org_name",
         "used_by"
       ]
+    },
+    "team_size": {
+      "type": "string",
+      "description": "Size of the organization team.",
+      "enum": [
+        "1",
+        "2-10",
+        "11-50",
+        "51+"
+      ]
+    },
+    "use_case": {
+      "type": "string",
+      "description": "Primary use of the swarm.",
+      "enum": [
+        "features",
+        "bugs",
+        "review",
+        "ops",
+        "docs",
+        "data"
+      ]
+    },
+    "acquisition_source": {
+      "type": "string",
+      "description": "How the organization found Agent Swarm.",
+      "enum": [
+        "search",
+        "github",
+        "social",
+        "colleague",
+        "newsletter",
+        "event",
+        "ai_assistant",
+        "hacker_news",
+        "other"
+      ]
+    },
+    "user_function": {
+      "type": "string",
+      "description": "Job function of a user, separate from the RBAC user_role.",
+      "enum": [
+        "engineer",
+        "eng_lead",
+        "founder",
+        "product",
+        "ops",
+        "other"
+      ]
+    },
+    "notification_moment": {
+      "type": "string",
+      "description": "Moment that made the Slack Connect invite relevant.",
+      "enum": [
+        "task_failed",
+        "first_workflow",
+        "default"
+      ]
     }
   },
   "common_properties": {
@@ -1125,6 +1183,9 @@
         "key": {
           "type": "string",
           "required": true
+        },
+        "moment": {
+          "ref": "notification_moment"
         }
       }
     },
@@ -1138,6 +1199,9 @@
         "key": {
           "type": "string",
           "required": true
+        },
+        "moment": {
+          "ref": "notification_moment"
         }
       }
     },
@@ -1155,6 +1219,12 @@
         "email_domain": {
           "type": "string",
           "description": "Domain of the email typed into the item, never the address."
+        },
+        "moment": {
+          "ref": "notification_moment"
+        },
+        "user_function": {
+          "ref": "user_function"
         }
       }
     },
@@ -1167,7 +1237,8 @@
       "properties": {
         "feature": {
           "type": "string",
-          "required": true
+          "required": true,
+          "description": "Feature identifier, including health_popover and kickoff_call_opened. Existing identifiers remain accepted."
         }
       }
     },
@@ -1222,7 +1293,8 @@
       "properties": {
         "channel": {
           "type": "string",
-          "required": true
+          "required": true,
+          "description": "Lead channel, including setup_help and fleet_report. Existing channels remain accepted."
         },
         "submission_id": {
           "type": "string",
@@ -1305,6 +1377,22 @@
           "type": "boolean",
           "required": true,
           "description": "A name or email was left. The values go to /v1/feedback, never here."
+        },
+        "answered": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Number of profile follow-up questions answered, never their values."
+        },
+        "perks": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "used_by",
+              "slack_connect"
+            ]
+          },
+          "description": "Perks the admin explicitly selected."
         }
       }
     },
@@ -1317,8 +1405,18 @@
       "properties": {
         "fields": {
           "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "name",
+              "website",
+              "team_size",
+              "use_case",
+              "acquisition_source"
+            ]
+          },
           "required": true,
-          "description": "Changed field names: name, website."
+          "description": "Changed profile field names, never their values."
         },
         "surface": {
           "type": "string",
@@ -1326,7 +1424,12 @@
           "enum": [
             "prompt",
             "setup",
-            "settings"
+            "settings",
+            "org_name_popup",
+            "feedback",
+            "fleet_benchmark",
+            "telemetry_banner",
+            "identity_modal"
           ],
           "description": "Where the change was made. Not trigger_surface: that key fills the raw_events.trigger_surface column."
         }
@@ -1342,6 +1445,12 @@
         "granted": {
           "type": "boolean",
           "required": true
+        },
+        "has_quote": {
+          "type": "boolean"
+        },
+        "has_function": {
+          "type": "boolean"
         }
       }
     },
@@ -1358,7 +1467,8 @@
           "enum": [
             "banner",
             "settings",
-            "env"
+            "env",
+            "benchmark"
           ]
         }
       }
@@ -1373,6 +1483,82 @@
         "has_org_name": {
           "type": "boolean",
           "required": true
+        },
+        "level": {
+          "type": "string",
+          "enum": [
+            "basic",
+            "full"
+          ]
+        }
+      }
+    },
+    {
+      "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."
         }
       }
     },
@@ -1485,6 +1671,109 @@
           "required": true
         }
       }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "identity.lookup",
+      "description": "A dashboard identity lookup matched an existing user or found no match.",
+      "since": "2026-10-18",
+      "source": "ui",
+      "properties": {
+        "matched": {
+          "type": "boolean",
+          "required": true
+        }
+      }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "identity.user_created",
+      "description": "A user created a dashboard identity. Email and personal names stay out of telemetry.",
+      "since": "2026-10-18",
+      "source": "ui",
+      "properties": {
+        "surface": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "identity_modal",
+            "setup"
+          ]
+        },
+        "email_kind": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "work",
+            "personal"
+          ]
+        },
+        "has_function": {
+          "type": "boolean",
+          "required": true
+        },
+        "has_company": {
+          "type": "boolean",
+          "required": true
+        }
+      }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "fleet_benchmark.unlocked",
+      "description": "An admin supplied the company profile fields for the full benchmark.",
+      "since": "2026-10-18",
+      "source": "ui",
+      "properties": {
+        "fields": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "website",
+              "team_size",
+              "use_case"
+            ]
+          },
+          "required": true,
+          "description": "Profile fields supplied, never their values."
+        }
+      }
+    },
+    {
+      "product": "agent-swarm",
+      "event": "setup.worker_command_copied",
+      "description": "An admin copied a worker command from the setup health popover.",
+      "since": "2026-10-18",
+      "source": "ui",
+      "properties": {
+        "target": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "compose",
+            "docker",
+            "kubernetes"
+          ]
+        },
+        "harness": {
+          "type": "string",
+          "required": true,
+          "enum": [
+            "claude",
+            "codex",
+            "pi",
+            "devin",
+            "claude-managed",
+            "opencode",
+            "acp",
+            "dsh",
+            "amp",
+            "cursor",
+            "grok"
+          ]
+        }
+      }
     }
   ]
 }

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"
+  }
+}