@desplega.ai/agent-swarm 2.3.0 → 2.4.0

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

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

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": 42,
+  "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/name-too-long.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+  "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/not-object.json

@@ -0,0 +1 @@
+[{"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/null.json

@@ -0,0 +1 @@
+null

package/src/telemetry-contract/ranking/fixtures/invalid/other-with-subcategory.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "other",
+  "subcategory": "coding-agents",
+  "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/oversize.json

@@ -0,0 +1 @@
+{                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    "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/short-claim.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_1234",
+  "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/subcategory-other-category.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "engineering",
+  "subcategory": "seo",
+  "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/trailing-data.json

@@ -0,0 +1 @@
+{"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/unknown-field.json

@@ -0,0 +1,12 @@
+{
+  "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",
+  "logo": "https://example.com/logo.png"
+}

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

@@ -0,0 +1,11 @@
+{
+  "v": 2,
+  "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/updated-at-not-date.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": "yesterday"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/updated-at-offset.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-18T12:00:00+02:00"
+}

package/src/telemetry-contract/ranking/fixtures/invalid/wrong-case-field.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "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",
+  "Claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e"
+}

package/src/telemetry-contract/ranking/fixtures/valid/category-without-subcategory.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "marketing",
+  "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/valid/full.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/valid/minimal.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Example Org",
+  "domain": "example.com",
+  "category": "other",
+  "subcategory": null,
+  "description": null,
+  "sourceCodeUrl": null,
+  "updatedAt": "2026-10-18T10:00:00Z"
+}

package/src/telemetry-contract/ranking/fixtures/valid/padded-text.json

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

package/src/telemetry-contract/ranking/fixtures/valid/unicode-name.json

@@ -0,0 +1,11 @@
+{
+  "v": 1,
+  "claim": "rk_3f9a1c0e7b2d4a6f8e1c3b5d7f9a2c4e",
+  "name": "Ñandú Labs · 日本",
+  "domain": "nandu-labs.com",
+  "category": "product",
+  "subcategory": "research",
+  "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/listing.v1.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://proxy.desplega.sh/contracts/telemetry/ranking/listing.v1.schema.json",
+  "title": "TelemetryRankingV1",
+  "description": "The telemetry_ranking listing, version 1. agent-swarm stores it stringified in the global swarm_config key telemetry_ranking and sends the same string as the listing property of ranking.opted_in. The string must not exceed 2048 bytes. The ingest also requires name to equal context.org_name and domain to equal context.org_website. Text fields are trimmed before their length is checked; lengths count UTF-16 code units, as JavaScript does.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["v", "claim", "name", "domain", "category", "subcategory", "description", "sourceCodeUrl", "updatedAt"],
+  "properties": {
+    "v": {
+      "const": 1,
+      "description": "Listing version. A new version is a new schema file, never an edit to this one."
+    },
+    "claim": {
+      "type": "string",
+      "pattern": "^rk_[0-9a-f]{32}$",
+      "description": "Claim minted by the install. The ranking PR carries it, and the proxy binds it to the first install that sent it. Never served publicly."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 60,
+      "description": "Copied from SWARM_ORG_NAME. Served as app.title."
+    },
+    "domain": {
+      "type": "string",
+      "maxLength": 253,
+      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$",
+      "description": "Copied from SWARM_ORG_WEBSITE: a lowercase hostname without scheme, path or port. Served as app.slug."
+    },
+    "category": {
+      "type": "string",
+      "enum": ["engineering", "product", "marketing", "support", "operations", "other"],
+      "description": "A key of taxonomy.json. Served as the group filter."
+    },
+    "subcategory": {
+      "type": ["string", "null"],
+      "maxLength": 40,
+      "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
+      "description": "One of taxonomy.json's subcategories for category, or null. Served as app.categories."
+    },
+    "description": {
+      "type": ["string", "null"],
+      "minLength": 1,
+      "maxLength": 160,
+      "description": "Optional one-line description. Served as app.description."
+    },
+    "sourceCodeUrl": {
+      "type": ["string", "null"],
+      "maxLength": 200,
+      "pattern": "^https://",
+      "description": "Optional https URL. Served as app.source_code_url."
+    },
+    "updatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$",
+      "description": "When the install built this listing, in UTC with a Z suffix."
+    }
+  }
+}

package/src/telemetry-contract/ranking/taxonomy.json

@@ -0,0 +1,8 @@
+{
+  "engineering": ["coding-agents", "qa-testing", "devops", "code-review"],
+  "product": ["research", "design", "analytics"],
+  "marketing": ["content", "seo", "social"],
+  "support": ["customer-support", "docs"],
+  "operations": ["back-office", "sales-ops", "finance"],
+  "other": []
+}