@desplega.ai/agent-swarm 2.5.3 → 2.6.0

package/src/http/status.ts

@@ -29,6 +29,7 @@ import {
   getDbClient,
   getInstanceActivity,
   getLiveAgentCounts,
+  getReadyAgentCounts,
   hasFirstCompletedTask,
   listAgentsWithCredStatusByProvider,
   NOT_EXTENSION_AGENT_SQL,
@@ -121,6 +122,12 @@ export type StatusIdentity = z.infer<typeof StatusIdentitySchema>;
 export const StatusActivitySchema = z.object({
   agents_online: z.number().int().nonnegative(),
   leads_online: z.number().int().nonnegative(),
+  /**
+   * Leads that can take work now (status `idle` or `busy`). Unlike
+   * `leads_online`, this does not depend on a recent heartbeat: an idle lead
+   * stops updating its activity time.
+   */
+  leads_ready: z.number().int().nonnegative(),
   recent_tasks_count: z.number().int().nonnegative(),
 });
 export type StatusActivity = z.infer<typeof StatusActivitySchema>;
@@ -194,12 +201,13 @@ export type AutomationStatus = z.infer<typeof AutomationStatusSchema>;
 /**
  * Phase 2: Aggregate health derived from setup milestones.
  *
- * - `broken`  — harness or workers blocking (creds missing, no live workers ever).
- * - `degraded` — at least one optional integration `unverified`/`configured`
- *                 while another is configured, OR harness creds present but
- *                 the latest live test failed or never ran (`configured`).
- * - `ok`       — harness + workers `verified`; no integration left in
- *                 `configured` state.
+ * - `broken`: harness or workers blocking (creds missing, no live workers ever).
+ * - `degraded`: no lead can take work (none is `idle` or `busy`), OR at
+ *   least one optional integration `unverified`/`configured` while another
+ *   is configured, OR harness creds present but the latest live test failed
+ *   or never ran (`configured`).
+ * - `ok`: harness + workers `verified`, a lead can take work, and no
+ *   integration left in `configured` state.
  */
 export const StatusHealthSchema = z.enum(["ok", "degraded", "broken"]);
 export type StatusHealth = z.infer<typeof StatusHealthSchema>;
@@ -692,19 +700,23 @@ export async function buildSetup(
  * Decision matrix:
  * - Harness `unverified` (no creds at all) → `broken` — the swarm cannot run a task.
  * - Workers `unverified` (no agents ever) → `broken` — same reason.
+ * - No lead can take work (`readyLeads` is 0) → `degraded`. Tasks wait until a lead is online.
  * - Harness `configured` (creds present, never live-tested) → `degraded`.
  * - Any of {slack, github, linear, jira} `configured` (i.e. half-set-up) → `degraded`.
  * - Otherwise → `ok`.
  *
  * Notes:
+ * - `readyLeads` counts leads with status `idle` or `busy`
+ *   (`getReadyAgentCounts`). It does not use the heartbeat time: an agent
+ *   updates `lastActivityAt` only while a session runs, so an idle, healthy
+ *   lead looks stale.
  * - Worker `configured` (fleet exists but missed recent heartbeats) does NOT
- *   degrade the rollup. Heartbeat drift is a runtime concern surfaced on the
- *   /agents page and the dashboard canvas — not a setup health signal.
+ *   degrade the rollup on its own, for the same reason.
  * - Integrations in `unverified` are NOT degrading on their own — most
  *   deployments don't connect every integration. They only nudge the rollup if
  *   paired with another integration in `configured` (the brainstorm contract).
  */
-export function computeHealth(setup: SetupMilestone[]): StatusHealth {
+export function computeHealth(setup: SetupMilestone[], readyLeads: number): StatusHealth {
   const byId = new Map(setup.map((m) => [m.id, m] as const));
   const harness = byId.get("harness");
   const workers = byId.get("workers");
@@ -714,6 +726,7 @@ export function computeHealth(setup: SetupMilestone[]): StatusHealth {
   if (!workers || workers.state === "unverified") return "broken";
 
   // `degraded` rules.
+  if (readyLeads === 0) return "degraded";
   if (harness.state === "configured") return "degraded";
 
   for (const id of ["slack", "github", "linear", "jira"] as const) {
@@ -740,12 +753,13 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
     .map((automation) => toStatus(preflightAutomation(automation, automationSetup)))
     .sort((a, b) => a.name.localeCompare(b.name) || a.kind.localeCompare(b.kind));
   const activity = await getInstanceActivity();
+  const readyLeads = (await getReadyAgentCounts()).leads;
   const instance = await getInstanceFeedbackSignals();
   return {
     runtime_pools: { enabled: isRuntimePoolsEnabled(), supervisor: runtimeSupervisorStatus() },
     identity: buildIdentity(),
     setup,
-    activity,
+    activity: { ...activity, leads_ready: readyLeads },
     agent_fs: {
       configured: !!process.env.AGENT_FS_API_URL,
       base_url: process.env.AGENT_FS_API_URL ?? null,
@@ -753,7 +767,7 @@ export async function buildStatusPayload(): Promise<StatusResponse> {
       comb: getCombStatus(await combServiceUserId),
     },
     automations,
-    health: computeHealth(setup),
+    health: computeHealth(setup, readyLeads),
     telemetry: { enabled: isTelemetryEnabled() },
     instance,
   };
@@ -797,7 +811,7 @@ const getStatus = route({
   pattern: ["status"],
   summary: "Identity + setup readiness + live activity for the swarm dashboard",
   description:
-    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
+    "Single source of truth consumed by the UI home page. Identity comes from SWARM_* envs; setup milestones each emit `unverified | configured | verified`; automations report `running | needs_setup` from the same runtime preflight used at dispatch; activity counts agents alive in the last 5 min, leads that can take work (status idle or busy), and tasks created in the last 24h; agent_fs reports whether AGENT_FS_API_URL is set, plus the Comb settings (COMB_ENABLED, the browser-facing agent-fs URL, the shared org and drive ids, and the agent-fs user id of the swarm service account); telemetry reports the effective ANONYMIZED_TELEMETRY opt-out state.",
   tags: ["Status"],
   responses: {
     200: { description: "Status payload", schema: StatusResponseSchema },

package/src/http/tasks.ts

@@ -227,6 +227,8 @@ const listTasks = route({
     status: z.string().optional(),
     agentId: z.string().optional(),
     scheduleId: z.string().optional(),
+    /** Only tasks of this workflow run (indexed; independent of fleet size). */
+    workflowRunId: z.string().uuid().optional(),
     key: AssetKeySchema.optional(),
     keyPrefix: AssetKeySchema.optional(),
     search: z.string().optional(),
@@ -976,6 +978,7 @@ export async function handleTasks(
       status,
       agentId: parsed.query.agentId || undefined,
       scheduleId: parsed.query.scheduleId || undefined,
+      workflowRunId: parsed.query.workflowRunId,
       key: parsed.query.key,
       keyPrefix: parsed.query.keyPrefix,
       search: parsed.query.search || undefined,

package/src/http/used-by.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getDbClient, upsertSwarmConfig } from "../be/db";
 import { isTelemetryEnabled, trackRelayed } from "../telemetry";
-import { USER_FUNCTIONS } from "../utils/company-profile";
+import { reportedUserFunction, USER_FUNCTIONS } from "../utils/company-profile";
 import { orgIdentityStatus } from "../utils/org-identity";
 import { normalizeOrgWebsite, TELEMETRY_PROXY_ORIGIN } from "../utils/org-website";
 import { ensureConfigAdmin } from "./config";
@@ -129,7 +129,12 @@ export async function handleUsedBy(
         ...(orgDomain ? { org_domain: orgDomain } : {}),
         granted,
         ...(granted
-          ? { contact_email: contactEmail, contact_function: contactFunction, quote }
+          ? {
+              contact_email: contactEmail,
+              // The proxy rejects a job function its catalog does not list yet.
+              contact_function: reportedUserFunction(contactFunction),
+              quote,
+            }
           : {}),
         changed_at: changedAt,
       }),

package/src/http/workflows.ts

@@ -5,6 +5,7 @@ import { resolveHttpAuditUserId } from "../be/audit-user";
 import {
   createWorkflow,
   deleteWorkflow,
+  getDbClient,
   getWorkflow,
   getWorkflowRun,
   getWorkflowRunStepsByRunId,
@@ -15,7 +16,21 @@ import {
   type updateWorkflow,
   withFavoriteFlags,
 } from "../be/db";
-import { getWorkflowRunParent } from "../be/db/workflow-runs";
+import {
+  assertWorkflowIdempotencyKeyUnused,
+  IdempotencyKeyTakenError,
+  recordAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+  workflowRequestFingerprint,
+} from "../be/db/workflow-idempotency";
+import {
+  getWorkflowRunParent,
+  getWorkflowRunStepsSlimByRunId,
+  getWorkflowRunSummary,
+  getWorkflowRunTree,
+  WORKFLOW_RUN_TREE_MAX_DEPTH,
+  WorkflowRunTreeError,
+} from "../be/db/workflow-runs";
 import {
   AssetKeySchema,
   AutomationIntegrationIdSchema,
@@ -31,6 +46,7 @@ import {
   WorkflowRunSchema,
   WorkflowRunStatusSchema,
   WorkflowRunStepSchema,
+  WorkflowRunStepSlimSchema,
   WorkflowRunSummarySchema,
   WorkflowSchema,
   WorkflowVersionSchema,
@@ -46,6 +62,11 @@ import { cancelWorkflowRun, retryFailedRun } from "../workflows/resume";
 import { handleWebhookTrigger, WebhookError } from "../workflows/triggers";
 import { snapshotAndUpdateWorkflow } from "../workflows/version";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
+import {
+  idempotencyKeyHeader,
+  readIdempotencyKey,
+  replayAcceptedOperation,
+} from "./idempotency-key";
 import { route } from "./route-def";
 import { jsonError, parseBody, triggerSchemaErrorResponse } from "./utils";
 
@@ -96,6 +117,13 @@ const WorkflowRunPageSchema = z.object({
   }),
 });
 
+/** Mirrors `WorkflowRunTree` in src/be/db/workflow-runs.ts. */
+const WorkflowRunTreeSchema = z.object({
+  rootRunId: z.string(),
+  runs: z.array(WorkflowRunSummarySchema),
+  hasOpenWork: z.boolean(),
+});
+
 const SuccessResponseSchema = z.object({ success: z.literal(true) });
 
 /** Adds `warnings` to a just-saved workflow when a node in it cannot run yet. */
@@ -142,6 +170,7 @@ const createWorkflowRoute = route({
   pattern: ["api", "workflows"],
   summary: "Create a new workflow",
   tags: ["Workflows"],
+  headers: idempotencyKeyHeader("creates one workflow"),
   body: z.object({
     name: z.string().min(1),
     key: AssetKeySchema.optional(),
@@ -159,7 +188,9 @@ const createWorkflowRoute = route({
   }),
   responses: {
     201: { description: "Workflow created", schema: WorkflowSaveResponseSchema },
-    400: { description: "Invalid definition" },
+    400: { description: "Invalid definition, or a malformed Idempotency-Key" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow created under this Idempotency-Key was deleted" },
   },
 });
 
@@ -272,16 +303,21 @@ const triggerWorkflowRoute = route({
   path: "/api/workflows/{id}/trigger",
   pattern: ["api", "workflows", null, "trigger"],
   summary: "Trigger a workflow execution",
+  description:
+    "With an `Idempotency-Key`, a retry returns the accepted run's `runId` and `skipped` without starting, resuming or waiting for anything, even after the workflow was disabled or edited and whatever state the run is in now.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  headers: idempotencyKeyHeader("starts one run"),
   responses: {
     201: {
       description: "Workflow run started (or skipped if cooldown active)",
       schema: z.object({ runId: z.string(), skipped: z.boolean() }),
     },
-    400: { description: "Workflow is disabled" },
+    400: { description: "Workflow is disabled, or a malformed Idempotency-Key" },
     401: { description: "Unauthorized" },
     404: { description: "Workflow not found" },
+    409: { description: "Idempotency-Key was already used for a different request" },
+    410: { description: "The workflow triggered under this Idempotency-Key was deleted" },
   },
 });
 
@@ -328,22 +364,50 @@ const getWorkflowRunRoute = route({
   path: "/api/workflow-runs/{id}",
   pattern: ["api", "workflow-runs", null],
   summary: "Get a workflow run with steps (includes retry columns)",
+  description:
+    "Returns the run with its `context` and every step with its `input` by default. A step's `input` is a snapshot of the context when the step started, so in runs with loops (polling, `wait`, iterations) the response grows with steps × context size. Pass `fields=slim` to drop `run.context` and `steps[].input`; outputs, errors, diagnostics, retry fields and `parent` stay.",
   tags: ["Workflows"],
   params: z.object({ id: z.string() }),
+  query: z.object({
+    /** `slim` omits `run.context` and `steps[].input`; default is full. */
+    fields: z.enum(["full", "slim"]).optional(),
+  }),
   responses: {
     200: {
       description: "Workflow run details with steps including retry info",
-      schema: z.object({
-        run: WorkflowRunSchema,
-        steps: z.array(WorkflowRunStepSchema),
-        /** Set on a child run: the run and `sub-workflow` step that started it. */
-        parent: WorkflowRunParentSchema.optional(),
-      }),
+      schema: z.union([
+        z.object({
+          run: WorkflowRunSchema,
+          steps: z.array(WorkflowRunStepSchema),
+          /** Set on a child run: the run and `sub-workflow` step that started it. */
+          parent: WorkflowRunParentSchema.optional(),
+        }),
+        z.object({
+          run: WorkflowRunSummarySchema,
+          steps: z.array(WorkflowRunStepSlimSchema),
+          parent: WorkflowRunParentSchema.optional(),
+        }),
+      ]),
     },
     404: { description: "Run not found" },
   },
 });
 
+const getWorkflowRunTreeRoute = route({
+  method: "get",
+  path: "/api/workflow-runs/{id}/tree",
+  pattern: ["api", "workflow-runs", null, "tree"],
+  summary: "Get a workflow run and every sub-workflow run below it",
+  description: `Follows stored parent links (\`parentStepId\` → step → run) through every attempt of every step, terminal runs included. \`runs\` holds list rows without \`context\`, root first. \`hasOpenWork\` is true while any run in the tree is live, has a pending, running or waiting step, a queued retry, an open task or a pending approval; after a cancel it turns false once the tree has settled. Both come from one read snapshot. The tree is not paginated. Links that form a cycle or nest deeper than ${WORKFLOW_RUN_TREE_MAX_DEPTH} levels return 409.`,
+  tags: ["Workflows"],
+  params: z.object({ id: z.string() }),
+  responses: {
+    200: { description: "The run tree", schema: WorkflowRunTreeSchema },
+    404: { description: "Run not found" },
+    409: { description: "Stored parent links form a cycle or nest past the depth bound" },
+  },
+});
+
 const retryWorkflowRunRoute = route({
   method: "post",
   path: "/api/workflow-runs/{id}/retry",
@@ -574,8 +638,21 @@ export async function handleWorkflows(
   }
 
   if (createWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await createWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    const claim: WorkflowIdempotencyClaim | undefined = idempotency && {
+      ...idempotency,
+      operation: "workflow.create",
+      targetId: "",
+      fingerprint: workflowRequestFingerprint("workflow.create", parsed.body),
+    };
+    const replayCreate = (body: unknown) =>
+      createWorkflowRoute.respond(res, 201, body as z.input<typeof WorkflowSaveResponseSchema>);
+    // Before validation: a retry gets the original result even if the same
+    // definition would no longer validate.
+    if (claim && (await replayAcceptedOperation(res, claim, replayCreate))) return true;
 
     // Validate definition structure
     const validation = validateDefinition(parsed.body.definition, getExecutorRegistry());
@@ -603,27 +680,55 @@ export async function handleWorkflows(
       throw error;
     }
 
-    const workflow = await createWorkflow(
-      {
-        key,
-        name: parsed.body.name,
-        description: parsed.body.description,
-        definition: parsed.body.definition,
-        triggers: parsed.body.triggers,
-        cooldown: parsed.body.cooldown,
-        input: parsed.body.input,
-        triggerSchema: parsed.body.triggerSchema,
-        params: parsed.body.params,
-        requiredParams: parsed.body.requiredParams,
-        requires: parsed.body.requires,
-        dir: parsed.body.dir,
-        vcsRepo: parsed.body.vcsRepo,
-        createdByAgentId: myAgentId ?? undefined,
-        createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
-      },
-      "api",
-    );
-    createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+    const data: Parameters<typeof createWorkflow>[0] = {
+      key,
+      name: parsed.body.name,
+      description: parsed.body.description,
+      definition: parsed.body.definition,
+      triggers: parsed.body.triggers,
+      cooldown: parsed.body.cooldown,
+      input: parsed.body.input,
+      triggerSchema: parsed.body.triggerSchema,
+      params: parsed.body.params,
+      requiredParams: parsed.body.requiredParams,
+      requires: parsed.body.requires,
+      dir: parsed.body.dir,
+      vcsRepo: parsed.body.vcsRepo,
+      createdByAgentId: myAgentId ?? undefined,
+      createdBy: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+    };
+    if (!claim) {
+      const workflow = await createWorkflow(data, "api");
+      createWorkflowRoute.respond(res, 201, await withSaveWarnings(workflow));
+      return true;
+    }
+
+    // Warnings are computed before the transaction (a readiness check may
+    // call out) and stored with the workflow, so a retry gets this snapshot,
+    // not the workflow as it is by then.
+    const warnings = await workflowSaveWarnings(parsed.body.definition, getExecutorRegistry());
+    let saved: z.input<typeof WorkflowSaveResponseSchema>;
+    try {
+      saved = await getDbClient().transaction(async () => {
+        // Before the insert: a concurrent winner's workflow holds the same name.
+        await assertWorkflowIdempotencyKeyUnused(claim);
+        const workflow = await createWorkflow(data, "api");
+        const body = warnings.length > 0 ? { ...workflow, warnings } : workflow;
+        await recordAcceptedWorkflowOperation(claim, {
+          workflowId: workflow.id,
+          status: 201,
+          body,
+        });
+        return body;
+      });
+    } catch (err) {
+      // A concurrent request with this key committed first; nothing of this one did.
+      if (err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayCreate)) return true;
+      }
+      throw err;
+    }
+    createWorkflowRoute.respond(res, 201, saved);
     return true;
   }
 
@@ -858,8 +963,26 @@ export async function handleWorkflows(
   }
 
   if (triggerWorkflowRoute.match(req.method, pathSegments)) {
+    const idempotency = readIdempotencyKey(req, res, myAgentId);
+    if (idempotency === null) return true;
     const parsed = await triggerWorkflowRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+    let claim: WorkflowIdempotencyClaim | undefined;
+    let keyedBody: Record<string, unknown> | undefined;
+    const replayTrigger = (body: unknown) =>
+      triggerWorkflowRoute.respond(res, 201, body as { runId: string; skipped: boolean });
+    if (idempotency) {
+      keyedBody = await parseBody<Record<string, unknown>>(req);
+      claim = {
+        ...idempotency,
+        operation: "workflow.trigger",
+        targetId: parsed.params.id,
+        fingerprint: workflowRequestFingerprint("workflow.trigger", keyedBody),
+      };
+      // Before the enabled, cooldown, readiness and trigger-schema checks: an
+      // accepted trigger replays even after the workflow changed.
+      if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+    }
     const workflow = await getWorkflow(parsed.params.id);
     if (!workflow) {
       res.writeHead(404);
@@ -870,20 +993,45 @@ export async function handleWorkflows(
       jsonError(res, "Workflow is disabled", 400);
       return true;
     }
-    const body = await parseBody<Record<string, unknown>>(req);
+    // Not `??`: a JSON `null` body is a parsed body too, and reading the
+    // already-ended stream again would wait forever.
+    const body = idempotency ? keyedBody : await parseBody<Record<string, unknown>>(req);
     let runId: string;
+    let accepted: { runId: string; skipped: boolean } | undefined;
     try {
       runId = await startWorkflowExecution(workflow, body, getExecutorRegistry(), {
         triggerType: "api",
         requestedByUserId: (await resolveHttpAuditUserId(req, myAgentId)) ?? undefined,
+        // Recorded in the run's own transaction, before the walk starts.
+        accept: claim
+          ? async (run) => {
+              const response = { runId: run.runId, skipped: run.skipped };
+              await recordAcceptedWorkflowOperation(claim, {
+                workflowId: workflow.id,
+                runId: run.runId,
+                status: 201,
+                body: response,
+              });
+              accepted = response;
+            }
+          : undefined,
       });
     } catch (err) {
       if (err instanceof TriggerSchemaError) {
         triggerSchemaErrorResponse(res, err.message, err.validationErrors);
         return true;
       }
+      // A concurrent request with this key committed its run first; this one
+      // created none and walks nothing.
+      if (claim && err instanceof IdempotencyKeyTakenError) {
+        if (await replayAcceptedOperation(res, claim, replayTrigger)) return true;
+      }
       throw err;
     }
+    if (accepted) {
+      triggerWorkflowRoute.respond(res, 201, accepted);
+      return true;
+    }
 
     // Check if skipped due to cooldown
     const run = await getWorkflowRun(runId);
@@ -909,18 +1057,44 @@ export async function handleWorkflows(
     const parsed = await getWorkflowRunRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     // Display view: the scrubbed context and step outputs, never replay state.
-    const run = await getWorkflowRun(parsed.params.id, "display");
+    // `fields=slim` skips the context and step-input columns in SQL too.
+    const slim = parsed.query.fields === "slim";
+    const run = slim
+      ? await getWorkflowRunSummary(parsed.params.id)
+      : await getWorkflowRun(parsed.params.id, "display");
     if (!run) {
       res.writeHead(404);
       res.end();
       return true;
     }
-    const steps = await getWorkflowRunStepsByRunId(parsed.params.id, "display");
+    const steps = slim
+      ? await getWorkflowRunStepsSlimByRunId(parsed.params.id)
+      : await getWorkflowRunStepsByRunId(parsed.params.id, "display");
     const parent = run.parentStepId ? await getWorkflowRunParent(run.parentStepId) : null;
     getWorkflowRunRoute.respond(res, 200, { run, steps, ...(parent ? { parent } : {}) });
     return true;
   }
 
+  if (getWorkflowRunTreeRoute.match(req.method, pathSegments)) {
+    const parsed = await getWorkflowRunTreeRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    let tree: Awaited<ReturnType<typeof getWorkflowRunTree>>;
+    try {
+      tree = await getWorkflowRunTree(parsed.params.id);
+    } catch (err) {
+      if (!(err instanceof WorkflowRunTreeError)) throw err;
+      jsonError(res, err.message, 409);
+      return true;
+    }
+    if (!tree) {
+      res.writeHead(404);
+      res.end();
+      return true;
+    }
+    getWorkflowRunTreeRoute.respond(res, 200, tree);
+    return true;
+  }
+
   if (retryWorkflowRunRoute.match(req.method, pathSegments)) {
     const parsed = await retryWorkflowRunRoute.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;

package/src/integrations/chat-sdk/inbound.ts

@@ -1,5 +1,7 @@
 import type { Adapter, Message, Thread } from "chat";
 import { z } from "zod";
+import { sessionGroupKey } from "@/assets/key";
+import { sessionSourceKey } from "@/assets/source-key";
 import {
   getAgentById,
   getAgentWorkingOnContextKey,
@@ -9,6 +11,7 @@ import {
   getLeadAgent,
   isExtensionAgent,
 } from "@/be/db";
+import { rememberSessionLabel } from "@/be/db/session-labels";
 import { resolveIdentity } from "@/be/identity";
 import { recordUnmappedIdentity } from "@/be/unmapped-identities";
 import { dispatchPre } from "@/extensions/dispatcher";
@@ -373,6 +376,20 @@ async function targetFromExtension(
  * Runs outside any transaction, so `pre.chat.route` is dispatched here, after
  * the flush and before any task exists.
  */
+/**
+ * The source group label a Telegram or Discord message gives: the DM sender,
+ * or a Telegram group title. Slack labels come from the Slack lookup instead.
+ */
+function chatSourceLabel(adapter: string, item: ChatBufferedMessage): string | undefined {
+  if (adapter !== "telegram" && adapter !== "discord") return undefined;
+  const { facts } = item;
+  if (facts.chatType === "dm" || item.isDirectMessage)
+    return facts.from ? `DM · ${facts.from}` : undefined;
+  if (adapter === "telegram" && (facts.chatType === "group" || facts.chatType === "supergroup"))
+    return facts.title || undefined;
+  return undefined;
+}
+
 export async function flushChatThread(
   threadId: string,
   items: ChatBufferedMessage[],
@@ -538,6 +555,7 @@ export async function flushChatThread(
   const latestActive = await getLatestActiveTaskByContextKey(contextKey, "chat");
   const dependsOn = !immediate && latestActive ? [latestActive.id] : undefined;
   let created = 0;
+  let sourceKey: string | null = null;
   for (const match of target.matches) {
     const options: CreateTaskOptions = {
       agentId: match.agent?.id ?? null,
@@ -564,6 +582,7 @@ export async function flushChatThread(
     };
     try {
       const { task, unattached } = await createChatTaskWithFiles(description, options, inbound);
+      sourceKey ??= sessionSourceKey(task);
       created++;
       console.log(
         `[chat-sdk] ${threadId}: task ${task.id} for ${match.agent ? `agent ${match.agent.id}` : "no agent (queued)"} (${match.matchedText}, dependsOn: ${dependsOn?.join(", ") ?? "none"}${unattached.length ? `, ${unattached.length} file(s) not attached` : ""})`,
@@ -578,6 +597,14 @@ export async function flushChatThread(
       }
     }
   }
+  const label = chatSourceLabel(adapter, requester);
+  if (sourceKey && label) {
+    // Every message refreshes the label, so a renamed group shows its new title.
+    // The error may echo the label, which can hold a person's name: do not log it.
+    await rememberSessionLabel(sessionGroupKey(sourceKey), label).catch(() => {
+      console.warn("[chat-sdk] Could not save a session source label");
+    });
+  }
   if (created > 0) {
     await rememberChatThreadRequester(threadId, requester.userId);
     await subscribe(thread);

package/src/kv-reserved-namespaces.ts

@@ -12,8 +12,20 @@ const RESERVED_FAMILIES = new Map([
   ["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"],
+  // Source group labels (src/be/db/session-labels.ts). Private, see PRIVATE_FAMILIES.
+  [
+    "session-labels",
+    "namespace is reserved for session source labels; GET /api/session-tree returns them",
+  ],
 ]);
 
+/**
+ * Reserved families that generic KV callers may not read either. Their rows
+ * hold data that another route returns only to callers with access (a
+ * source label names a private channel or a DM partner).
+ */
+const PRIVATE_FAMILIES = new Set(["session-labels"]);
+
 export function isReservedNamespace(namespace: string): boolean {
   return reservedNamespaceError(namespace) !== null;
 }
@@ -22,6 +34,13 @@ export function reservedNamespaceError(namespace: string): string | null {
   return RESERVED_FAMILIES.get(namespace.split(":", 1)[0] ?? "") ?? null;
 }
 
+/** The error a generic KV read of a private family gets, or null. */
+export function privateNamespaceError(namespace: string): string | null {
+  return PRIVATE_FAMILIES.has(namespace.split(":", 1)[0] ?? "")
+    ? reservedNamespaceError(namespace)
+    : null;
+}
+
 export function reservedRoomKeyError(key: string): string | null {
   return key.startsWith("_room/")
     ? "room snapshot keys are reserved; use the room endpoints"