@desplega.ai/agent-swarm 2.4.3 → 2.4.5

package/src/tools/chat-access.ts

@@ -1,8 +1,18 @@
+import * as z from "zod";
 import { getAgentById, getAgentCurrentTask, getTaskById } from "@/be/db";
 import { can } from "@/rbac";
 import { chatThreadOfContextKey } from "@/tasks/context-key";
 import type { RequestInfo } from "@/tools/utils";
 
+/** The `attachments` input of `chat-reply` and `chat-post`. */
+export const chatAttachmentsSchema = z
+  .array(z.string().min(1))
+  .max(10)
+  .optional()
+  .describe(
+    "Files to send after the text, up to 10: attachment ids of your current task (from get-task-details) or file paths in your agent-fs drive, such as thoughts/<agent-id>/report.pdf, read with your own agent-fs credential. Telegram shows JPEG and PNG as photos, MP4 as video, MP3 and M4A as audio, and anything else as a document. A file over the platform upload limit (Telegram 50 MB, Discord 10 MB) is not sent, and the thread gets a note naming it.",
+  );
+
 /** Chat SDK verbs; the legacy policy grants them to the lead only. */
 export type ChatVerb = "integration.chat.post" | "integration.chat.read" | "integration.chat.dm";
 

package/src/tools/chat-post.ts

@@ -2,8 +2,13 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { CHAT_SDK_ADAPTER_NAMES } from "@/integrations/chat-sdk/config";
 import { errorMessage } from "@/integrations/chat-sdk/logger";
-import { adapterOfChatId, postChatMessage } from "@/integrations/chat-sdk/outbound";
-import { canUseChatVerb } from "@/tools/chat-access";
+import {
+  adapterOfChatId,
+  postChatMessage,
+  unsentFilesSummary,
+} from "@/integrations/chat-sdk/outbound";
+import { resolveChatAttachmentRefs } from "@/integrations/chat-sdk/outbound-files";
+import { canUseChatVerb, chatAttachmentsSchema } from "@/tools/chat-access";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerChatPostTool = (server: McpServer) => {
@@ -27,6 +32,7 @@ export const registerChatPostTool = (server: McpServer) => {
           .optional()
           .describe("Full SDK channel id, such as slack:C123. Ignored when threadId is set."),
         text: z.string().min(1).max(20_000).describe("Markdown text to post."),
+        attachments: chatAttachmentsSchema,
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
@@ -34,9 +40,12 @@ export const registerChatPostTool = (server: McpServer) => {
         adapter: z.string().optional(),
         threadId: z.string().optional(),
         channelId: z.string().optional(),
+        unsentFiles: z
+          .array(z.looseObject({ name: z.string().optional(), reason: z.string().optional() }))
+          .optional(),
       }),
     },
-    async ({ adapter, threadId, channelId, text }, requestInfo) => {
+    async ({ adapter, threadId, channelId, text, attachments }, requestInfo) => {
       const data = { yourAgentId: requestInfo.agentId };
       const target = threadId ?? channelId;
       if (!target) return toolErr("Give a threadId or a channelId.", { data });
@@ -49,22 +58,33 @@ export const registerChatPostTool = (server: McpServer) => {
           { data },
         );
       }
+      const resolved = await resolveChatAttachmentRefs(
+        attachments ?? [],
+        requestInfo.sourceTaskId,
+        requestInfo.agentId,
+      );
+      if ("error" in resolved) return toolErr(resolved.error, { data });
       try {
         const sent = await postChatMessage({
           adapter,
           ...(threadId ? { threadId } : { channelId }),
           text,
           taskId: requestInfo.sourceTaskId,
+          files: resolved.files,
         });
-        return toolOk(`Posted to ${adapter} ${threadId ? "thread" : "channel"} ${target}.`, {
-          data: {
-            ...data,
-            messageId: sent.messageIds.at(-1),
-            adapter: sent.adapter,
-            threadId: sent.threadId,
-            channelId: sent.channelId,
+        return toolOk(
+          `Posted to ${adapter} ${threadId ? "thread" : "channel"} ${target}.${unsentFilesSummary(sent.unsentFiles)}`,
+          {
+            data: {
+              ...data,
+              messageId: sent.messageIds.at(-1),
+              adapter: sent.adapter,
+              threadId: sent.threadId,
+              channelId: sent.channelId,
+              unsentFiles: sent.unsentFiles,
+            },
           },
-        });
+        );
       } catch (error) {
         const message = errorMessage(error);
         return toolErr(`Could not post: ${message}`, { data });

package/src/tools/chat-reply.ts

@@ -2,8 +2,14 @@ import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import * as z from "zod";
 import { getAgentCurrentTask, getTaskById } from "@/be/db";
 import { errorMessage } from "@/integrations/chat-sdk/logger";
-import { ChatAdapterUnavailableError, postChatMessage } from "@/integrations/chat-sdk/outbound";
+import {
+  ChatAdapterUnavailableError,
+  postChatMessage,
+  unsentFilesSummary,
+} from "@/integrations/chat-sdk/outbound";
+import { resolveChatAttachmentRefs } from "@/integrations/chat-sdk/outbound-files";
 import { chatThreadOfContextKey } from "@/tasks/context-key";
+import { chatAttachmentsSchema } from "@/tools/chat-access";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 
 export const registerChatReplyTool = (server: McpServer) => {
@@ -12,19 +18,23 @@ export const registerChatReplyTool = (server: McpServer) => {
     {
       title: "Reply in the chat thread of this task",
       description:
-        "Post a message to the Telegram, Slack, Discord or Teams thread your current task came from. Works only on a task whose contextKey starts with task:chat-sdk:. The task's final output is posted to the thread automatically when the task ends, so use this only for a question to the user or a short progress note on long work. Markdown is supported; long text is split into several messages.",
+        "Post a message to the Telegram, Slack, Discord or Teams thread your current task came from. Works only on a task whose contextKey starts with task:chat-sdk:. The task's final output is posted to the thread automatically when the task ends, so use this only for a question to the user, a short progress note on long work, or to send files (attachments). Markdown is supported; long text is split into several messages. When the final output of a task is posted, the files attached to that task go with it.",
       annotations: { openWorldHint: true },
       inputSchema: z.object({
         text: z.string().min(1).max(20_000).describe("Markdown text to post to the thread."),
+        attachments: chatAttachmentsSchema,
       }),
       outputSchema: swarmToolOutputSchema({
         yourAgentId: z.string().optional(),
         messageId: z.string().optional(),
         adapter: z.string().optional(),
         threadId: z.string().optional(),
+        unsentFiles: z
+          .array(z.looseObject({ name: z.string().optional(), reason: z.string().optional() }))
+          .optional(),
       }),
     },
-    async ({ text }, requestInfo) => {
+    async ({ text, attachments }, requestInfo) => {
       if (!requestInfo.agentId) return toolErr("Agent ID not found.");
       const data = { yourAgentId: requestInfo.agentId };
 
@@ -46,21 +56,33 @@ export const registerChatReplyTool = (server: McpServer) => {
         );
       }
 
+      const resolved = await resolveChatAttachmentRefs(
+        attachments ?? [],
+        task.id,
+        requestInfo.agentId,
+      );
+      if ("error" in resolved) return toolErr(resolved.error, { data });
+
       try {
         const sent = await postChatMessage({
           adapter: thread.adapter,
           threadId: thread.threadId,
           text,
           taskId: task.id,
+          files: resolved.files,
         });
-        return toolOk(`Posted to ${thread.adapter} thread ${sent.threadId}.`, {
-          data: {
-            ...data,
-            messageId: sent.messageIds.at(-1),
-            adapter: sent.adapter,
-            threadId: sent.threadId,
+        return toolOk(
+          `Posted to ${thread.adapter} thread ${sent.threadId}.${unsentFilesSummary(sent.unsentFiles)}`,
+          {
+            data: {
+              ...data,
+              messageId: sent.messageIds.at(-1),
+              adapter: sent.adapter,
+              threadId: sent.threadId,
+              unsentFiles: sent.unsentFiles,
+            },
           },
-        });
+        );
       } catch (error) {
         const message = errorMessage(error);
         return toolErr(

package/src/tools/memory-search.ts

@@ -11,6 +11,7 @@ import {
   recordRetrievals,
 } from "@/be/memory/raters/retrieval";
 import { rerank } from "@/be/memory/reranker";
+import { searchMemoryCandidates } from "@/be/memory/search-candidates";
 import { createToolRegistrar, swarmToolOutputSchema, toolErr, toolOk } from "@/tools/utils";
 import type { AgentMemorySource } from "@/types";
 import { AgentMemoryScopeSchema, AgentMemorySourceSchema } from "@/types";
@@ -122,7 +123,8 @@ export const registerMemorySearchTool = (server: McpServer) => {
       const queryEmbedding = await provider.embed(query);
 
       const candidateLimit = limit * CANDIDATE_SET_MULTIPLIER;
-      const candidates = await store.search(
+      const candidates = await searchMemoryCandidates(
+        store,
         queryEmbedding ?? new Float32Array(0),
         requestInfo.agentId,
         {

package/src/tools/system-one-decide.ts

@@ -10,7 +10,7 @@ import {
 import { SYSTEM_ONE_PROVIDER_IDS } from "@/workflows/executors/system-one-providers";
 
 /**
- * One typed decision (Jev and the other SystemOne hosts) made in the API
+ * One typed decision (Jev, Clef and the other SystemOne hosts) made in the API
  * process, the same way a `system-one-decision` workflow node makes it. The
  * provider credential is read and sent here and never reaches the caller, so a
  * script can ask for a decision without a credential binding in its own realm.
@@ -22,14 +22,16 @@ export const registerSystemOneDecideTool = (server: McpServer) => {
       title: "Ask a SystemOne decision model",
       annotations: { destructiveHint: false, openWorldHint: true },
       description:
-        "Send a state and typed questions (noul, choice, score) to a SystemOne decision host such as Jev, and return the validated answers. " +
+        "Send a state and typed questions (noul, choice, score) to a SystemOne decision host such as Jev or Clef, and return the validated answers. " +
         "Same request, provider list, credentials and validation as the `system-one-decision` workflow node, without its human review band. " +
         "The provider credential is a global secret that stays on the server; this tool never returns it.",
       inputSchema: z.object({
         provider: z
           .enum(SYSTEM_ONE_PROVIDER_IDS)
           .optional()
-          .describe("Decision host (default typesafe)"),
+          .describe(
+            "Decision host (default: the SYSTEM_ONE_DEFAULT_PROVIDER global config, typesafe when unset)",
+          ),
         model: z.string().min(1).optional().describe("Provider model id (default: the provider's)"),
         state: z
           .union([z.string(), z.array(z.string()), z.record(z.string(), z.unknown())])
@@ -55,6 +57,12 @@ export const registerSystemOneDecideTool = (server: McpServer) => {
         answers: z.record(z.string(), z.unknown()).optional(),
         usage: z.record(z.string(), z.unknown()).optional(),
         requestId: z.string().optional(),
+        providerUnavailable: z
+          .boolean()
+          .optional()
+          .describe(
+            "On an error: true when this deployment refuses the provider (e.g. OpenRouter behind a gateway) and no request was sent, so a caller choosing automatically can try its next provider",
+          ),
       }),
     },
     async ({ provider, model, state, questions, timeoutMs, maxRetries }, requestInfo) => {
@@ -88,7 +96,12 @@ export const registerSystemOneDecideTool = (server: McpServer) => {
         return toolErr("The system-one-decision executor is not available");
       }
       const decided = await executor.decide(parsed.data);
-      if (!decided.ok) return toolErr(decided.error);
+      if (!decided.ok) {
+        return toolErr(
+          decided.error,
+          decided.deploymentRefused ? { data: { providerUnavailable: true } } : {},
+        );
+      }
 
       const { output } = decided;
       return toolOk(`Decision from ${output.model}`, {

package/src/types.ts

@@ -905,6 +905,12 @@ export const CreateTaskOptionsSchema = z.object({
    * contract on completion (which would block the control task — DES-523).
    */
   inheritParentOutputSchema: z.boolean().optional(),
+  /**
+   * When a `parentTaskId` is set and `requestedByUserId` is not, the child
+   * inherits the parent's requester by default. Set this to `false` when the
+   * child answers a different person (a chat message whose sender is unknown).
+   */
+  inheritParentRequester: z.boolean().optional(),
   /**
    * Skip parent routing requirements only for a child with its own explicit
    * Lead-only control-plane authorization.
@@ -2287,7 +2293,7 @@ export const WorkflowNodeSchema = z
     type: z
       .string()
       .describe(
-        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'system-one-decision', 'validate', 'property-match'",
+        "Executor type: 'agent-task', 'script', 'swarm-script', 'raw-llm', 'system-one-decision', 'system-one-extraction', 'validate', 'property-match'",
       ),
     label: z.string().optional().describe("Human-readable label for UI display"),
     config: z
@@ -2297,6 +2303,7 @@ export const WorkflowNodeSchema = z
           "For script: { runtime, script, args?, timeout? }. " +
           "For swarm-script: { scriptName, scope?, pinHash?, args?, fsMode?, timeoutMs? (1000-300000) }. " +
           "For system-one-decision (typed decisions, Jev by default): { provider? ('typesafe' default | 'openrouter' | 'laya'; a literal, never a {{token}}), state, questions: { <id>: { type: 'noul'|'choice'|'score', instructions, criteria? } }, returns: { <id>: { type } }, model? (provider-specific; unset = the provider's default, and laya has none so it sends no model and picks its own checkpoint), timeoutMs?, maxRetries? (0-3), humanReview? { band: { min, max } (0-1, inclusive), approvers: { users?, roles?, policy }, title?, timeout?, notifications? } }; each provider needs its own global secret (TYPESAFE_API_KEY, OPENROUTER_API_KEY, or LAYA_API_KEY; laya also needs the global config LAYA_URL), and a save warns and a run fails before any node executes when one is missing; system-one-decision nodes must not set retry or validation.retry. With humanReview, an answer whose confidence is inside the band waits for a person (human-in-the-loop approval), and next must map ports { approved, rejected?, timeout? }. " +
+          "For system-one-extraction (typed extraction, Cloudflare Clairic by default): { provider? ('cloudflare'; a literal), state (text to read; may be empty when images are sent), fields: { <id>: { type: 'text'|'number'|'date'|'time'|'datetime'|'duration'|'list'|'estimate'|'forecast', instructions?, ...type options (number: unit?, integer?, decimals?; duration: unit? (seconds..years), integer?, decimals?; list: items ('text'|'number'|'date'); estimate: min, max, step?, scale?, unit?; forecast: min, max, horizon?, interval?, scale?, unit?; text/number/date/time/datetime/duration: null_threshold?) } }, images? (max 4 base64 data: URLs or { content_type, base64 }), referenceDate? (YYYY-MM-DD), model?, timeoutMs?, maxRetries? (0-3) }; output answers.<id> carries value (null when the input does not say), guess, p_null, confidence, span/spans, and for estimate/forecast median/p10/p90. Needs the global secret CLOUDFLARE_API_TOKEN (or CLOUDFLARE_API_KEY) and the global config CLOUDFLARE_ACCOUNT_ID; must not set retry or validation.retry. " +
           "Agent-task templates and ordinary config values support {{interpolation}} from the node's inputs context, including trigger and declared upstream aliases. " +
           "SECURITY: executable source for script/swarm-script nodes does not interpolate trigger.* or upstream node outputs; only input/workflow/swarm/run values are allowed in inline script source, and named swarm-script source is not workflow-interpolated. " +
           'Pass dynamic values through config.args instead (inline script receives them as argv, with runtime: "bash" running bash -c <script> ...args so args[0] is $0 and args[1] is $1; swarm-script receives its args object). ' +

package/src/utils/config-env-export.ts

@@ -8,7 +8,8 @@
  * binding instead.
  *
  * Keys below are read only by the API server (integration signing secrets, app
- * private keys, OAuth client secrets, the API's own agent-fs key). They can
+ * private keys, OAuth client secrets, the API's own agent-fs and
+ * speech-to-text keys). They can
  * never be exported: the config API rejects `exportToEnv: true` for them and
  * every reader treats a stored true as false.
  */
@@ -25,6 +26,7 @@ export const ENV_EXPORT_RESTRICTED_KEYS: ReadonlySet<string> = new Set([
   "AZURE_DEVOPS_WEBHOOK_SECRET",
   "AGENTMAIL_WEBHOOK_SECRET",
   "API_AGENT_FS_API_KEY",
+  "TRANSCRIPTION_API_KEY",
 ]);
 
 /**

package/src/utils/page-session.ts

@@ -246,23 +246,83 @@ export function parseCookieHeader(
 }
 
 /**
- * One-shot helper: pull `page_session` out of a request's `Cookie` header and
- * verify it. Returns the parsed payload on success, `null` on any failure
- * (no cookie, malformed, bad signature, expired, etc.).
- *
- * Shared by `/@swarm/api/*` (`src/http/page-proxy.ts`) and the authed `/p/:id`
- * branch (`src/http/pages-public.ts`) so both call sites converge on the same
- * verification semantics.
+ * The single shared cookie name used before sessions became per-page. Every
+ * launch overwrote it, so only the newest page in a browser had a session.
+ * Still read for back-compat, but only for the page its payload names.
+ */
+export const LEGACY_PAGE_SESSION_COOKIE = "page_session";
+
+/** Page ids are 32 hex chars today; anything outside the cookie-name-safe set is refused. */
+const COOKIE_SAFE_PAGE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+
+export function isCookieSafePageId(pageId: string): boolean {
+  return COOKIE_SAFE_PAGE_ID.test(pageId);
+}
+
+/** Per-page cookie name, so sessions for different pages coexist in one browser. */
+export function pageSessionCookieName(pageId: string): string {
+  return `${LEGACY_PAGE_SESSION_COOKIE}_${pageId}`;
+}
+
+export interface VerifiedPageSession {
+  /** The raw signed token, forwarded upstream by the page proxy. */
+  token: string;
+  payload: PageSessionPayload;
+}
+
+type CookieRequest = { headers: { cookie?: string | string[] | undefined } };
+
+async function verifyNamedCookie(
+  req: CookieRequest,
+  name: string,
+): Promise<VerifiedPageSession | null> {
+  const token = parseCookieHeader(req.headers.cookie, name);
+  const payload = await verifyPageSession(token);
+  return payload && token ? { token, payload } : null;
+}
+
+/**
+ * Find and verify the session for `pageId`: `page_session_<pageId>` first,
+ * then the legacy `page_session`. A cookie whose signed payload names a
+ * different page is ignored, so the result always satisfies
+ * `payload.pageId === pageId`. Returns `null` on any failure (no cookie,
+ * malformed, bad signature, expired, wrong page).
+ */
+export async function extractPageSession(
+  req: CookieRequest,
+  pageId: string,
+): Promise<VerifiedPageSession | null> {
+  if (!isCookieSafePageId(pageId)) return null;
+  for (const name of [pageSessionCookieName(pageId), LEGACY_PAGE_SESSION_COOKIE]) {
+    const session = await verifyNamedCookie(req, name);
+    if (session?.payload.pageId === pageId) return session;
+  }
+  return null;
+}
+
+/**
+ * Verify the legacy `page_session` cookie for whatever page it names. Only for
+ * callers that send no page id (clients predating per-page cookies).
+ */
+export async function extractLegacyPageSession(
+  req: CookieRequest,
+): Promise<VerifiedPageSession | null> {
+  return verifyNamedCookie(req, LEGACY_PAGE_SESSION_COOKIE);
+}
+
+/**
+ * Payload-only form of `extractPageSession`. Shared by the `/p/:id` handler
+ * (`src/http/pages-public.ts`) and the realtime upgrade
+ * (`src/realtime/transport.ts`) so they converge on the same semantics.
  *
  * Accepts an object with a `headers.cookie` field — duck-typed to keep this
  * helper test-friendly without dragging `node:http` types into the utility.
  */
-export async function extractAndVerifyCookie(req: {
-  headers: { cookie?: string | string[] | undefined };
-}): Promise<PageSessionPayload | null> {
-  const token = parseCookieHeader(req.headers.cookie, "page_session");
-  if (!token) return null;
-  return verifyPageSession(token);
+export async function extractAndVerifyCookie(
+  req: CookieRequest,
+  pageId: string,
+): Promise<PageSessionPayload | null> {
+  return (await extractPageSession(req, pageId))?.payload ?? null;
 }
 
 // ───────────────────────────────────────────────────────────────────────────
@@ -284,6 +344,10 @@ const PAGE_SESSION_TTL_SECONDS = 3600;
  * - `dev=true` → `SameSite=Lax` without `Secure` (works on http://localhost).
  * - `dev=false` → `SameSite=None; Secure` (cross-site iframe embedding in prod).
  *
+ * The cookie is named `page_session_<pageId>`, so launching page B leaves
+ * page A's session intact. Responses should go through `pageSessionSetCookies`,
+ * which also bounds how many of these a browser keeps.
+ *
  * The caller is responsible for setting `Set-Cookie` on the response — this
  * helper only builds the string. TTL is 1 hour; renewed on every issuance.
  */
@@ -299,13 +363,12 @@ export async function issuePageSessionCookie(
     ...(opts.name ? { name: opts.name } : {}),
     ...(opts.op ? { op: true as const } : {}),
   });
-  const attrs = [
-    `page_session=${token}`,
-    "HttpOnly",
-    "Path=/",
-    `Max-Age=${PAGE_SESSION_TTL_SECONDS}`,
-  ];
-  if (opts.dev) {
+  return buildCookie(pageSessionCookieName(pageId), token, PAGE_SESSION_TTL_SECONDS, opts.dev);
+}
+
+function buildCookie(name: string, value: string, maxAge: number, dev: boolean): string {
+  const attrs = [`${name}=${value}`, "HttpOnly", "Path=/", `Max-Age=${maxAge}`];
+  if (dev) {
     attrs.push("SameSite=Lax");
   } else {
     attrs.push("SameSite=None");
@@ -313,3 +376,53 @@ export async function issuePageSessionCookie(
   }
   return attrs.join("; ");
 }
+
+/**
+ * Most per-page session cookies one browser keeps, counting the one being
+ * issued. Each is ~220 bytes on the wire, and `Path=/` sends all of them on
+ * every request to this host, so an unbounded jar grows past the server's
+ * 16 KB header limit (431 on every route, `/health` included) after ~75
+ * launches within the hour. 20 keeps the jar near 4.5 KB.
+ */
+export const MAX_PAGE_SESSION_COOKIES = 20;
+
+const PAGE_SESSION_COOKIE_RE = new RegExp(
+  `(?:^|;\\s*)(${LEGACY_PAGE_SESSION_COOKIE}_[A-Za-z0-9_-]{1,64})=([^;]*)`,
+  "g",
+);
+
+/**
+ * `Set-Cookie` values for a launch of `pageId`: the new session, plus an
+ * expiring cookie for every other per-page session in the request's jar that
+ * is invalid or expired, or falls outside the `MAX_PAGE_SESSION_COOKIES - 1`
+ * newest. The browser then holds at most `MAX_PAGE_SESSION_COOKIES` of them.
+ * An evicted page's open tab loses its session, the same as after expiry.
+ */
+export async function pageSessionSetCookies(
+  req: CookieRequest,
+  pageId: string,
+  opts: { dev: boolean; uid?: string; name?: string; op?: true },
+): Promise<string[]> {
+  const issued = await issuePageSessionCookie(pageId, opts);
+  const header = Array.isArray(req.headers.cookie)
+    ? req.headers.cookie.join("; ")
+    : (req.headers.cookie ?? "");
+  const keep: { name: string; exp: number; order: number }[] = [];
+  const evict = new Set<string>();
+  const seen = new Set([pageSessionCookieName(pageId)]);
+  for (const [, name, token] of header.matchAll(PAGE_SESSION_COOKIE_RE)) {
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    const payload = await verifyPageSession(token);
+    if (payload && name === pageSessionCookieName(payload.pageId)) {
+      keep.push({ name, exp: payload.exp, order: keep.length });
+    } else {
+      evict.add(name);
+    }
+  }
+  // `exp` has one-second granularity. Browsers list older cookies first, so a
+  // later position breaks ties toward the more recent launch.
+  keep.sort((a, b) => b.exp - a.exp || b.order - a.order);
+  for (const { name } of keep.slice(MAX_PAGE_SESSION_COOKIES - 1)) evict.add(name);
+  return [issued, ...[...evict].map((name) => buildCookie(name, "", 0, opts.dev))];
+}

package/src/utils/request-auth-context.ts

@@ -8,9 +8,10 @@ export type HttpRequestAuth = (
   /** Password-page viewer with no user identity. Least privilege: every gate denies it. */
   | { kind: "guest" }
   | { kind: "controller"; controllerId: string; tokenId: string; expiresAt: string }
-  /** Ephemeral token bound to an ACP task or a worker runtime (aseph_ prefix). */
+  /** Session token bound to an ACP task, a worker runtime, or only its agent (aseph_ prefix). */
   | {
       kind: "agent";
+      tokenKind: "task" | "runtime" | "agent";
       agentId: string;
       taskId: string | null;
       runtimeId: string | null;