@desplega.ai/agent-swarm 2.2.0 → 2.4.0

package/src/http/tasks.ts

@@ -37,6 +37,7 @@ import {
 } from "../be/db";
 import { modelProfileRefError, taskProfileError } from "../be/db/model-profiles";
 import { explicitModelErrorForAgent } from "../be/model-validation";
+import { hasSessionAccess, type SessionAccess } from "../be/session-shares";
 import {
   getTaskSteeringFields,
   markSteeringUndeliverable,
@@ -80,7 +81,15 @@ import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import { rejectGuest } from "./request-principal";
 import { buildTaskRequestedBy, TaskRequestedBySchema } from "./requested-by";
-import { route } from "./route-def";
+import { bodyTask, route } from "./route-def";
+import {
+  canReadSession,
+  readableByFor,
+  resolveSessionActor,
+  SESSION_READ_DENIED,
+  SESSION_WRITE_DENIED,
+  sessionAccessFor,
+} from "./session-access";
 import { jsonError, parseBody } from "./utils";
 
 // ─── Response Schemas ────────────────────────────────────────────────────────
@@ -207,7 +216,7 @@ const listTasks = route({
   pattern: ["api", "tasks"],
   summary: "List tasks with filters",
   description:
-    "Returns tasks with the full `task` text replaced by a bounded `taskPreview` and completion/integration blobs dropped by default — list views only need the preview. Pass `fields=full` to restore the full `AgentTask`, or `fields=timeline` for the narrow shape the dashboard timeline draws. Fetch a single task in full via `GET /api/tasks/{id}`. `total` (the filtered row count, ignoring limit/offset) is computed only with `includeTotal=true`.",
+    "Returns tasks with the full `task` text replaced by a bounded `taskPreview` and completion/integration blobs dropped by default — list views only need the preview. Pass `fields=full` to restore the full `AgentTask`, or `fields=timeline` for the narrow shape the dashboard timeline draws. Every shape gives a user caller only tasks of sessions they can read. Fetch a single task in full via `GET /api/tasks/{id}`. `total` (the filtered row count, ignoring limit/offset) is computed only with `includeTotal=true`.",
   tags: ["Tasks"],
   query: z.object({
     /** Single status, or comma-separated list (e.g. "failed,cancelled"). */
@@ -263,6 +272,7 @@ const createTask = route({
   method: "post",
   path: "/api/tasks",
   pattern: ["api", "tasks"],
+  session: bodyTask("parentTaskId"),
   summary: "Create a new task",
   tags: ["Tasks"],
   body: z
@@ -340,6 +350,7 @@ const promoteDraftTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/promote-draft",
   pattern: ["api", "tasks", null, "promote-draft"],
+  session: { taskParam: "id" },
   summary: "Promote a draft task out of the pre-dispatch draft state",
   description:
     "Transitions a `draft` task (#1240 — created with attachments still uploading) to its normal dispatch-eligible status: `offered` if it was offered to an agent, `pending` if it has an owning agent (the common case — UI-composer tasks default to Lead), otherwise `unassigned`. Called by the UI composer once its attachment upload batch settles, whether every file uploaded, some failed, or all failed — a draft must never be stranded by an upload error. Idempotent: calling it on a task that already left `draft` returns the current task unchanged rather than erroring, so a retried request is safe.",
@@ -357,6 +368,7 @@ const updateSession = route({
   method: "put",
   path: "/api/tasks/{id}/session",
   pattern: ["api", "tasks", null, "session"],
+  session: { taskParam: "id" },
   summary: "Update provider session ID and harness metadata for a task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -392,6 +404,7 @@ const cancelTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/cancel",
   pattern: ["api", "tasks", null, "cancel"],
+  session: { taskParam: "id" },
   summary: "Cancel a pending or in-progress task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -407,6 +420,7 @@ const steerTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/steer",
   pattern: ["api", "tasks", null, "steer"],
+  session: { taskParam: "id" },
   summary: "Deliver a steering message to a running task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -439,6 +453,7 @@ const getTaskSteeringMessagesRoute = route({
   method: "get",
   path: "/api/tasks/{id}/steering-messages",
   pattern: ["api", "tasks", null, "steering-messages"],
+  session: { taskParam: "id" },
   summary: "List steering messages for a task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -467,6 +482,7 @@ const markSteeringDeliveredRoute = route({
   method: "post",
   path: "/api/steering-messages/{id}/delivered",
   pattern: ["api", "steering-messages", null, "delivered"],
+  session: { steeringParam: "id" },
   summary: "Mark a steering message delivered",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -492,6 +508,7 @@ const markSteeringHandledRoute = route({
   method: "post",
   path: "/api/steering-messages/{id}/handled",
   pattern: ["api", "steering-messages", null, "handled"],
+  session: { steeringParam: "id" },
   summary: "Mark a steering message handled",
   description:
     "Optionally accepts a JSON body `{ note?: string }` — a short acceptance note describing how the steering was incorporated, persisted as `handledNote`.",
@@ -517,6 +534,7 @@ const markSteeringUndeliverableRoute = route({
   method: "post",
   path: "/api/steering-messages/{id}/undeliverable",
   pattern: ["api", "steering-messages", null, "undeliverable"],
+  session: { steeringParam: "id" },
   summary: "Promote an undeliverable steering message",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -542,6 +560,7 @@ const getTask = route({
   method: "get",
   path: "/api/tasks/{id}",
   pattern: ["api", "tasks", null],
+  session: { taskParam: "id" },
   summary: "Get task details with logs and attachments",
   description:
     "Returns the full `AgentTask` row decorated with `logs` (capped by `logsLimit`) and `attachments` (pointer-based artifacts stored on the task, ordered by `created_at`).",
@@ -553,6 +572,7 @@ const getTask = route({
   }),
   responses: {
     200: { description: "Task with logs and attachments", schema: GetTaskResponseSchema },
+    403: { description: "A user caller cannot read the task's session" },
     404: { description: "Task not found" },
   },
 });
@@ -561,6 +581,7 @@ const updateTaskProgressRoute = route({
   method: "post",
   path: "/api/tasks/{id}/progress",
   pattern: ["api", "tasks", null, "progress"],
+  session: { taskParam: "id" },
   summary: "Update task progress text",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -579,6 +600,7 @@ const finishTask = route({
   method: "post",
   path: "/api/tasks/{id}/finish",
   pattern: ["api", "tasks", null, "finish"],
+  session: { taskParam: "id" },
   summary: "Mark task as completed or failed (runner endpoint)",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -631,6 +653,7 @@ const pauseTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/pause",
   pattern: ["api", "tasks", null, "pause"],
+  session: { taskParam: "id" },
   summary: "Pause an in-progress task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -646,6 +669,7 @@ const resumeTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/resume",
   pattern: ["api", "tasks", null, "resume"],
+  session: { taskParam: "id" },
   summary: "Resume a paused task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -661,6 +685,7 @@ const supersedeTaskRoute = route({
   method: "post",
   path: "/api/tasks/{id}/supersede",
   pattern: ["api", "tasks", null, "supersede"],
+  session: { taskParam: "id" },
   summary: "Supersede an in-progress task (terminate + spawn resume follow-up)",
   description:
     'Marks the original task `superseded` (terminal) and creates a fresh `taskType="resume"` follow-up so a worker can pick up the work in a new provider session. Workflow-step tasks (those with `workflowRunStepId`) are carved out: the original is marked `failed` with reason `superseded_workflow_task` and no follow-up is created — the workflow engine\'s retry/failure policy applies.',
@@ -683,6 +708,7 @@ const updateTaskVcsRoute = route({
   method: "patch",
   path: "/api/tasks/{id}/vcs",
   pattern: ["api", "tasks", null, "vcs"],
+  session: { taskParam: "id" },
   summary: "Update VCS (PR/MR) info for a task",
   tags: ["Tasks"],
   params: z.object({ id: z.string() }),
@@ -704,6 +730,7 @@ const updateTaskTitleRoute = route({
   method: "patch",
   path: "/api/tasks/{id}/title",
   pattern: ["api", "tasks", null, "title"],
+  session: { taskParam: "id" },
   summary: "Set or clear a task's display title (session rename)",
   description:
     "Sets a human-facing display title override on a task. The sessions UI only reads this from root tasks (session list items), but titles on child tasks are harmless. Pass `title: null` (or an empty string) to clear the override and fall back to the task prompt.",
@@ -722,22 +749,37 @@ const updateTaskTitleRoute = route({
   },
 });
 
+/** True unless the request acts for a user who lacks write access to the task's session. */
+async function hasSessionWrite(
+  req: IncomingMessage,
+  myAgentId: string | undefined,
+  taskId: string,
+): Promise<boolean> {
+  const access = await sessionAccessFor(await resolveSessionActor(req, myAgentId), taskId);
+  return hasSessionAccess(access, "write");
+}
+
 async function canSteerTask(
   req: IncomingMessage,
   myAgentId: string | undefined,
   task: AgentTask,
+  sessionAccess: SessionAccess = "none",
 ): Promise<boolean> {
+  const auth = getRequestAuth(req);
   const resource: RbacResource = {
     kind: "task",
     taskId: task.id,
-    requestedByUserId: task.requestedByUserId,
+    // A user with a write share steers as if the session were their own; the
+    // verb gate (and any role grant) still applies. Only an actual share
+    // counts: `owner` from an ownerless root must not widen steering.
+    requestedByUserId:
+      auth?.kind === "user" && sessionAccess === "write" ? auth.userId : task.requestedByUserId,
     creatorAgentId: task.creatorAgentId,
     agentId: task.agentId,
   };
   let principal: RbacPrincipal;
   let verb: "task.steer.any" | "task.steer.own";
 
-  const auth = getRequestAuth(req);
   if (auth?.kind === "operator") {
     principal = { kind: "operator" };
     verb = "task.steer.own";
@@ -906,6 +948,9 @@ export async function handleTasks(
       if (validated.length > 0) source = validated;
     }
 
+    // Every shape carries task text, so a user sees only sessions they can
+    // read, and `total` counts the same rows.
+    const actor = await resolveSessionActor(req, myAgentId);
     const filters = {
       status,
       agentId: parsed.query.agentId || undefined,
@@ -925,6 +970,7 @@ export async function handleTasks(
       orderBy: parsed.query.orderBy,
       limit: parsed.query.limit,
       offset: parsed.query.offset,
+      readableBy: actor.kind === "user" ? { userId: actor.userId } : undefined,
     };
     // List responses default to slim (full `task` text → bounded `taskPreview`,
     // heavy blobs dropped); `?fields=full` restores the full `AgentTask`.
@@ -1013,6 +1059,11 @@ export async function handleTasks(
       jsonError(res, `You don't have context for parent task ${parentTask.id}.`, 403);
       return true;
     }
+    // A follow-up in someone else's session needs a write share.
+    if (parentTask && !(await hasSessionWrite(req, myAgentId, parentTask.id))) {
+      jsonError(res, SESSION_WRITE_DENIED, 403);
+      return true;
+    }
     // A chat-sdk contextKey binds the task to a chat thread that its assignee and creator
     // may then read and post to. An agent may only name a thread other than the parent's
     // with the lead's chat post permission.
@@ -1285,7 +1336,13 @@ export async function handleTasks(
       jsonError(res, "Task not found", 404);
       return true;
     }
-    if (!(await canSteerTask(req, myAgentId, task))) {
+    const sessionActor = await resolveSessionActor(req, myAgentId);
+    const steerAccess = await sessionAccessFor(sessionActor, task.id);
+    if (!hasSessionAccess(steerAccess, "write")) {
+      jsonError(res, SESSION_WRITE_DENIED, 403);
+      return true;
+    }
+    if (!(await canSteerTask(req, myAgentId, task, steerAccess))) {
       jsonError(res, "Forbidden: caller cannot steer this task", 403);
       return true;
     }
@@ -1338,6 +1395,10 @@ export async function handleTasks(
       jsonError(res, "Task not found", 404);
       return true;
     }
+    if (!(await canReadSession(req, myAgentId, parsed.params.id))) {
+      jsonError(res, SESSION_READ_DENIED, 403);
+      return true;
+    }
     getTaskSteeringMessagesRoute.respond(res, 200, {
       messages: await getSteeringMessagesForTask(parsed.params.id),
     });
@@ -1357,7 +1418,12 @@ export async function handleTasks(
       return true;
     }
 
+    // A user token naming an agent in X-Agent-ID still reads only its sessions.
     if (parsed.query.taskId) {
+      if (!(await canReadSession(req, myAgentId, parsed.query.taskId))) {
+        jsonError(res, SESSION_READ_DENIED, 403);
+        return true;
+      }
       const task = await getTaskById(parsed.query.taskId);
       const messages =
         task?.agentId === myAgentId ? await getPendingSteeringForTask(parsed.query.taskId) : [];
@@ -1365,8 +1431,9 @@ export async function handleTasks(
       return true;
     }
 
+    const actor = await resolveSessionActor(req, myAgentId);
     getPendingSteeringMessagesRoute.respond(res, 200, {
-      messages: await getPendingSteeringForAgent(myAgentId),
+      messages: await getPendingSteeringForAgent(myAgentId, readableByFor(actor)),
     });
     return true;
   }
@@ -1529,6 +1596,11 @@ export async function handleTasks(
       jsonError(res, "Task not found", 404);
       return true;
     }
+    const readAccess = await sessionAccessFor(await resolveSessionActor(req, myAgentId), task.id);
+    if (!hasSessionAccess(readAccess, "read")) {
+      jsonError(res, "You don't have access to this session. Ask the owner to share it.", 403);
+      return true;
+    }
 
     const logs = await getLogsByTaskId(parsed.params.id, parsed.query.logsLimit ?? 200);
     const attachments = await getTaskAttachments(parsed.params.id);
@@ -1758,7 +1830,11 @@ export async function handleTasks(
       jsonError(res, "Missing X-Agent-ID header", 400);
       return true;
     }
-    const pausedTasks = await getPausedTasksForAgent(myAgentId);
+    // A user token naming an agent in X-Agent-ID still reads only its sessions.
+    const pausedTasks = await getPausedTasksForAgent(
+      myAgentId,
+      readableByFor(await resolveSessionActor(req, myAgentId)),
+    );
     const tasks = await Promise.all(
       pausedTasks.map(async (task) => {
         const requestedBy = await buildTaskRequestedBy(task);

package/src/http/used-by.ts

@@ -2,6 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getSwarmConfigs, upsertSwarmConfig } from "../be/db";
 import { isTelemetryEnabled, trackRelayed } from "../telemetry";
+import { orgIdentityStatus } from "../utils/org-identity";
 import { normalizeOrgWebsite, TELEMETRY_PROXY_ORIGIN } from "../utils/org-website";
 import { ensureConfigAdmin } from "./config";
 import { scheduleIntegrationsReload } from "./core";
@@ -46,7 +47,8 @@ const usedBy = route({
 
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 
-async function globalConfig(key: string): Promise<string | undefined> {
+/** A global config value, falling back to the process env. */
+export async function globalConfig(key: string): Promise<string | undefined> {
   const stored = (await getSwarmConfigs({ scope: "global", key }))?.[0]?.value?.trim();
   return stored || process.env[key]?.trim() || undefined;
 }
@@ -79,8 +81,14 @@ export async function handleUsedBy(
   if (!(await ensureConfigAdmin(req, res, "config.write.any"))) return true;
 
   const { granted } = parsed.body;
-  const currentName = await globalConfig("SWARM_ORG_NAME");
-  const currentWebsite = normalizeOrgWebsite(await globalConfig("SWARM_ORG_WEBSITE"));
+  // The shared identity reader. The grant keeps its own rule (any non-empty
+  // name), so it does not apply the ranking's placeholder-name check.
+  const current = orgIdentityStatus({
+    SWARM_ORG_NAME: await globalConfig("SWARM_ORG_NAME"),
+    SWARM_ORG_WEBSITE: await globalConfig("SWARM_ORG_WEBSITE"),
+  });
+  const currentName = current.name ?? undefined;
+  const currentWebsite = current.website;
   const grantedName = granted ? undefined : await globalConfig(GRANTED_NAME_KEY);
   const grantedWebsite = granted
     ? null

package/src/kv-reserved-namespaces.ts

@@ -8,6 +8,7 @@ const RESERVED_FAMILIES = new Map([
   ["apps", "namespace is reserved for swarm apps; use the app row endpoints"],
   // step-9: Comb's "Send to swarm" claims (`comb:sent`).
   ["comb", "namespace is reserved for Comb; use POST /api/comb/review-batches"],
+  ["heartbeat-checklist", "namespace is reserved for heartbeat checklist receipts"],
   ["worker", "namespace is reserved for worker nudges"],
   // Durable dedupe for SLACK_BLOCK_EXTERNAL_CHANNELS alerts (src/slack/external-channel.ts).
   ["slack-external-alert", "namespace is reserved for Slack external channel alerts"],

package/src/prompts/session-templates.ts

@@ -555,12 +555,14 @@ registerTemplate({
   header: "",
   defaultBody: `{{prompt}}
 
-[App action] app={{app_id}} action={{action_name}} input={{input_json}}`,
+[App action] app={{app_id}} action={{action_name}} input={{input_json}}
+Caller (server-verified): {{caller_json}}`,
   variables: [
     { name: "prompt", description: "The task prompt configured on the app action" },
     { name: "app_id", description: "The app identifier" },
     { name: "action_name", description: "The invoked action name" },
     { name: "input_json", description: "The action input serialized as JSON" },
+    { name: "caller_json", description: "The server-verified action caller serialized as JSON" },
   ],
   category: "task_lifecycle",
 });

package/src/providers/amp-adapter.ts

@@ -44,7 +44,7 @@ import type {
  * default; the image installs exactly this version and the per-task settings
  * set `amp.updates.mode: "disabled"`. Bump it deliberately, with a live run.
  */
-export const AMP_PACKAGE = "@ampcode/cli@0.0.1792238457-g6ec988";
+export const AMP_PACKAGE = "@ampcode/cli@0.0.1792324855-g9c86a5";
 
 /** MCP server name. Amp exposes its tools as `agent_swarm` / `store_progress` (dashes become underscores). */
 const AMP_MCP_SERVER_NAME = "agent-swarm";

package/src/ranking/telemetry-ranking.ts

@@ -0,0 +1,147 @@
+/**
+ * The `telemetry_ranking` listing: what an install opted into the public ranking
+ * shows on agent-swarm.dev/ranking. Stored stringified in the global
+ * `swarm_config` key `telemetry_ranking` and sent as the `listing` property of
+ * `ranking.opted_in`.
+ *
+ * The proxy owns the contract (`src/telemetry-contract/ranking/`, vendored by
+ * `bun run sync:telemetry-contract`). This schema and the proxy's Go decoder are
+ * both held to its fixtures. Pure: imported by the API and the dashboard.
+ */
+import { z } from "zod";
+import { RANKING_TAXONOMY } from "../telemetry-contract/ranking-taxonomy.gen";
+import type { OrgIdentityStatus } from "../utils/org-identity";
+import { normalizeOrgWebsite } from "../utils/org-website";
+
+export { RANKING_TAXONOMY };
+
+export const TELEMETRY_RANKING_KEY = "telemetry_ranking";
+export const PUBLIC_RANKING_ENABLED_KEY = "PUBLIC_RANKING_ENABLED";
+export const TELEMETRY_RANKING_MAX_BYTES = 2048;
+
+export const RANKING_CATEGORIES = Object.keys(RANKING_TAXONOMY) as [
+  keyof typeof RANKING_TAXONOMY,
+  ...(keyof typeof RANKING_TAXONOMY)[],
+];
+export const RANKING_CLAIM_PATTERN = /^rk_[0-9a-f]{32}$/;
+
+const hostname = z.string().refine((v) => normalizeOrgWebsite(v) === v, "bare hostname");
+const nullableText = (max: number) => z.string().trim().min(1).max(max).nullable();
+
+function inCategory(category: string, subcategory: string | null): boolean {
+  if (subcategory === null) return true;
+  const subs: readonly string[] = RANKING_TAXONOMY[category as keyof typeof RANKING_TAXONOMY];
+  return subs?.includes(subcategory) ?? false;
+}
+
+export const telemetryRankingV1 = z
+  .strictObject({
+    v: z.literal(1),
+    claim: z.string().regex(RANKING_CLAIM_PATTERN),
+    name: z.string().trim().min(1).max(60),
+    domain: hostname,
+    category: z.enum(RANKING_CATEGORIES),
+    subcategory: z
+      .string()
+      .regex(/^[a-z0-9]+(-[a-z0-9]+)*$/)
+      .max(40)
+      .nullable(),
+    description: nullableText(160),
+    sourceCodeUrl: z
+      .url({ protocol: /^https$/ })
+      .max(200)
+      .nullable(),
+    updatedAt: z.iso.datetime(),
+  })
+  .refine((l) => inCategory(l.category, l.subcategory), {
+    path: ["subcategory"],
+    message: "not in this category",
+  });
+
+/** Discriminated on `v`; a v2 is added here, never by editing v1. */
+export const telemetryRankingSchema = z.discriminatedUnion("v", [telemetryRankingV1]);
+export type TelemetryRanking = z.infer<typeof telemetryRankingSchema>;
+
+export function parseTelemetryRanking(raw: string): TelemetryRanking {
+  if (new TextEncoder().encode(raw).length > TELEMETRY_RANKING_MAX_BYTES) {
+    throw new Error(`telemetry_ranking exceeds ${TELEMETRY_RANKING_MAX_BYTES} bytes`);
+  }
+  return telemetryRankingSchema.parse(JSON.parse(raw));
+}
+
+/** The stored listing, or null when it is missing or no longer valid. */
+export function readTelemetryRanking(raw: string | null | undefined): TelemetryRanking | null {
+  if (!raw?.trim()) return null;
+  try {
+    return parseTelemetryRanking(raw);
+  } catch {
+    return null;
+  }
+}
+
+/** What the admin picks in the ranking form. Name and domain are never typed here. */
+export const rankingFormSchema = z.object({
+  category: z.enum(RANKING_CATEGORIES),
+  subcategory: z.string().nullable().optional(),
+  description: z.string().nullable().optional(),
+  sourceCodeUrl: z.string().nullable().optional(),
+});
+export type RankingForm = z.infer<typeof rankingFormSchema>;
+
+/** `rk_` + 32 lowercase hex characters from the platform CSPRNG. */
+export function mintRankingClaim(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(16));
+  return `rk_${Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")}`;
+}
+
+const blankToNull = (value: string | null | undefined) => value?.trim() || null;
+
+/**
+ * Build and validate the listing. Name and domain are copied from the org
+ * identity (`SWARM_ORG_NAME`, `SWARM_ORG_WEBSITE`); throws when the identity is
+ * not set or a form field breaks the contract.
+ */
+export function buildListing(
+  identity: OrgIdentityStatus,
+  form: RankingForm,
+  claim: string,
+  now: Date = new Date(),
+): TelemetryRanking {
+  if (!identity.ok || !identity.name || !identity.website) {
+    throw new Error(`Org identity is missing: ${identity.missing.join(", ")}`);
+  }
+  const listing = {
+    v: 1 as const,
+    claim,
+    name: identity.name,
+    domain: identity.website,
+    category: form.category,
+    subcategory: blankToNull(form.subcategory),
+    description: blankToNull(form.description),
+    sourceCodeUrl: blankToNull(form.sourceCodeUrl),
+    updatedAt: now.toISOString(),
+  };
+  return parseTelemetryRanking(JSON.stringify(listing));
+}
+
+/** The `community/ranking/<domain>.json` file that approves this install. */
+export function rankingEntryFile(listing: Pick<TelemetryRanking, "domain" | "claim">): string {
+  return `${JSON.stringify({ $schema: "./schema.json", domain: listing.domain, claim: listing.claim }, null, 2)}\n`;
+}
+
+export const RANKING_REPO = "desplega-ai/agent-swarm";
+
+/** GitHub's "new file" page, prefilled with the entry, as a PR from the admin's fork. */
+export function rankingPrUrl(listing: Pick<TelemetryRanking, "domain" | "claim">): string {
+  const params = new URLSearchParams({
+    filename: `community/ranking/${listing.domain}.json`,
+    value: rankingEntryFile(listing),
+    message: `chore(ranking): add ${listing.domain}`,
+  });
+  return `https://github.com/${RANKING_REPO}/new/main?${params.toString()}`;
+}
+
+/** GitHub's delete page for an entry, to leave the ranking for good. */
+export function rankingLeaveUrl(domain: string): string {
+  return `https://github.com/${RANKING_REPO}/delete/main/community/ranking/${domain}.json`;
+}

package/src/ranking/usage.ts

@@ -0,0 +1,57 @@
+/**
+ * Worker side of the public ranking: the `ranking.usage` properties for one
+ * session. Pure, so the runner and its test share the gate.
+ */
+import { isEnvFlagEnabled } from "../utils/env-flag";
+import { orgIdentityStatus } from "../utils/org-identity";
+
+export interface SessionTokens {
+  inputTokens?: number | null;
+  outputTokens?: number | null;
+  cacheReadTokens?: number | null;
+  cacheWriteTokens?: number | null;
+}
+
+export interface RankingUsageProps {
+  /** The same model and provider `session.cost` reports for the session. */
+  model: string;
+  provider: string;
+  totalTokens: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+}
+
+const tokens = (value: number | null | undefined) =>
+  typeof value === "number" && Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+
+/**
+ * Null unless telemetry is on, `PUBLIC_RANKING_ENABLED` is set and both org
+ * identity envs are set. Carries token counts plus the model and provider
+ * (for the per-model chart), never the task, agent or cost.
+ */
+export function rankingUsageProps(
+  cost: SessionTokens,
+  session: { model: string; provider: string },
+  env: NodeJS.ProcessEnv = process.env,
+): RankingUsageProps | null {
+  if (!isEnvFlagEnabled("ANONYMIZED_TELEMETRY", true, env)) return null;
+  if (!isEnvFlagEnabled("PUBLIC_RANKING_ENABLED", false, env)) return null;
+  const identity = { SWARM_ORG_NAME: env.SWARM_ORG_NAME, SWARM_ORG_WEBSITE: env.SWARM_ORG_WEBSITE };
+  if (!orgIdentityStatus(identity).ok) return null;
+  const input = tokens(cost.inputTokens);
+  const output = tokens(cost.outputTokens);
+  const cacheRead = tokens(cost.cacheReadTokens);
+  const cacheWrite = tokens(cost.cacheWriteTokens);
+  return {
+    model: session.model,
+    provider: session.provider,
+    // The unified sum, as computeContextUsedUnified counts it.
+    totalTokens: input + cacheRead + cacheWrite + output,
+    inputTokens: input,
+    outputTokens: output,
+    ...(cost.cacheReadTokens != null ? { cacheReadTokens: cacheRead } : {}),
+    ...(cost.cacheWriteTokens != null ? { cacheWriteTokens: cacheWrite } : {}),
+  };
+}

package/src/rbac/admission.ts

@@ -8,7 +8,20 @@ export type AdmissionGrant = {
   };
 };
 
-export type AdmissionRbac = { permission: PermissionVerb } | { ungated: string };
+/**
+ * `alsoAdmits` names verbs that admit the route as well as `permission`, for a
+ * route that serves two features (each handler check still names its own verb).
+ */
+export type AdmissionRbac =
+  | { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] }
+  | { ungated: string };
+
+function grantedVerb(
+  rbac: { permission: PermissionVerb; alsoAdmits?: readonly PermissionVerb[] },
+  grant: AdmissionGrant,
+): PermissionVerb | undefined {
+  return [rbac.permission, ...(rbac.alsoAdmits ?? [])].find((verb) => grant.verbs.has(verb));
+}
 
 export type AdmissionDecision =
   | { allow: true; verb?: PermissionVerb }
@@ -29,10 +42,11 @@ export function decideAdmission(input: {
   }
 
   if (input.rbac && "permission" in input.rbac) {
-    const verb = input.rbac.permission;
-    if (input.grant.verbs.has(verb)) {
-      return { allow: true, verb };
+    const granted = grantedVerb(input.rbac, input.grant);
+    if (granted) {
+      return { allow: true, verb: granted };
     }
+    const verb = input.rbac.permission;
     return { allow: false, reason: `admission: missing permission '${verb}'`, verb };
   }
 
@@ -54,10 +68,11 @@ export function decideToolAdmission(input: {
   }
 
   if (input.rbac && "permission" in input.rbac) {
-    const verb = input.rbac.permission;
-    if (input.grant.verbs.has(verb)) {
-      return { allow: true, verb };
+    const granted = grantedVerb(input.rbac, input.grant);
+    if (granted) {
+      return { allow: true, verb: granted };
     }
+    const verb = input.rbac.permission;
     return { allow: false, reason: `admission: missing permission '${verb}'`, verb };
   }
 

package/src/rbac/legacy-policy.ts

@@ -285,6 +285,8 @@ export const LEGACY_POLICY = {
   "task.action.own": requesterOwnsTask,
   "task.fs.mutate": taskFsMutate,
   "task.parent.attach": taskFsMutate,
+  "session.share": operatorOrUser,
+  "session.presence": operatorOrUser,
   "task.progress.write": taskProgressWrite,
   "favorite.write.own": anyAuthenticated,
   "memory.learning.inject": leadOnly,

package/src/rbac/permissions.ts

@@ -89,6 +89,15 @@ export const PERMISSIONS = {
       "Write a task's progress, status, or output (its assignee, a lead, a human, or anyone while unassigned).",
     namespace: "task",
   },
+  "session.share": {
+    description:
+      "Change who can view or edit a session the principal owns (the owner check runs in the handler).",
+    namespace: "task",
+  },
+  "session.presence": {
+    description: "Join the presence room of a session the principal can view.",
+    namespace: "task",
+  },
   "favorite.write.own": {
     description: "Set a favorite the caller owns.",
     namespace: "favorite",