@desplega.ai/agent-swarm 2.4.2 → 2.4.4

package/src/http/apps.ts

@@ -62,14 +62,16 @@ import {
   rollbackApp,
   snapshotApp,
 } from "../apps/version";
-import { getAgentById, getAppVersion, getAppVersions } from "../be/db";
+import { getAgentById, getAppVersion, getAppVersions, getTaskById } from "../be/db";
 import type { RbacPrincipal, RbacResource } from "../rbac";
 import { can } from "../rbac";
 import { AgentTaskStatusSchema } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { scrubObject } from "../utils/secret-scrubber";
 import { resolveHttpFavoriteOwner } from "./favorite-owner";
-import { route } from "./route-def";
+import { agentFirstPrincipal } from "./request-principal";
+import { bodyTask, route } from "./route-def";
+import { denyParentAttach } from "./session-access";
 import { BODY_TOO_LARGE, enforceContentLengthCap, json, jsonError } from "./utils";
 
 const MAX_APP_BODY_BYTES = 5 * 1024 * 1024;
@@ -618,17 +620,27 @@ const runActionRoute = route({
   method: "post",
   path: "/api/apps/{id}/actions/{name}",
   pattern: ["api", "apps", null, "actions", null],
+  // A task-kind action may chain under `body.parentTaskId`: a user caller needs
+  // write access to that session, as for POST /api/tasks.
+  session: bodyTask("parentTaskId"),
   summary: "Run a custom app action",
   description: "Runs the saved script, or creates the agent task, named by the app definition.",
   tags: ["Apps"],
   params: z.object({ id: z.string().min(1), name: AppNameSchema }),
-  body: z.object({ input: z.record(z.string(), z.unknown()).optional() }),
+  body: z.object({
+    input: z.record(z.string(), z.unknown()).optional(),
+    /** Chains the new task off an existing one. Task-kind actions only: a script or sync action rejects it (400). */
+    parentTaskId: z.string().min(1).optional(),
+  }),
   responses: {
     200: { description: "Action invoked", schema: runActionResultSchema },
-    400: { description: "Invalid action input or stale script reference" },
+    400: {
+      description:
+        "Invalid action input, stale script reference, or parentTaskId on a non-task action",
+    },
     403: { description: "Permission denied" },
     409: { description: "App definition needs repair" },
-    404: { description: "App or action not found" },
+    404: { description: "App, action, or parent task not found" },
   },
   rbac: { permission: "app.use" },
 });
@@ -1382,10 +1394,36 @@ export async function handleApps(
       return true;
     }
     if (definitionNeedsRepair(res, app)) return true;
+    if (parsed.body.parentTaskId) {
+      // `parentTaskId` only means something to a task-kind action: a script or
+      // sync action rejects it rather than silently dropping it. An unknown
+      // action keeps `runAppAction`'s 404.
+      const actions = app.definition.actions;
+      const action =
+        actions && Object.hasOwn(actions, parsed.params.name)
+          ? actions[parsed.params.name]
+          : undefined;
+      if (action && action.kind !== "task") {
+        jsonError(res, "parentTaskId is only supported for task-kind actions", 400);
+        return true;
+      }
+      if (action) {
+        const parentTask = await getTaskById(parsed.body.parentTaskId);
+        if (!parentTask) {
+          jsonError(res, "parent task not found", 404);
+          return true;
+        }
+        // The same gate as POST /api/tasks: without it an app action would
+        // chain under any task past `task.parent.attach`.
+        const principal = await agentFirstPrincipal(req, myAgentId);
+        if (await denyParentAttach(req, res, myAgentId, parentTask, principal)) return true;
+      }
+    }
     const output = await runAppAction({
       app,
       name: parsed.params.name,
       input: parsed.body.input,
+      parentTaskId: parsed.body.parentTaskId,
       caller,
       actor,
     });

package/src/http/codex-oauth-keep-warm.ts

@@ -12,9 +12,10 @@
  * when a task happens to draw it within `REFRESH_SKEW_MS` of expiry — which
  * for an idle/rarely-drawn slot can be never, letting its refresh token sit
  * unexercised well past OpenAI's ~8-day session-staleness guidance. This
- * sweep calls the SAME `getValidCodexOAuth` with `opts.maxAgeMs` ≈ 7 days so
- * every slot refreshes on a roughly-weekly cadence regardless of task draw
- * frequency — zero logic duplication, all lock/persist/quarantine behavior
+ * sweep calls the SAME `getValidCodexOAuth` with `opts.maxAgeMs` (default 5
+ * days, `CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS`) so every slot refreshes on a
+ * fixed cadence regardless of task draw frequency — zero logic
+ * duplication, all lock/persist/quarantine behavior
  * reused verbatim (see storage.ts doc comment; hand-rolling a refresher here
  * would re-create the 2026-06-19 race).
  *
@@ -25,6 +26,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getKv } from "../be/db";
+import { CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS } from "../be/swarm-config-guard";
 import { deriveCodexKeySuffix } from "../providers/codex-oauth/auth-json.js";
 import { getValidCodexOAuth, loadAllCodexOAuthSlots } from "../providers/codex-oauth/storage.js";
 import { getApiKey } from "../utils/api-key";
@@ -32,8 +34,25 @@ import { CODEX_AUTH_WATCH_NAMESPACE, codexAuthBenchMarkerKey } from "../utils/co
 import { getMcpBaseUrl } from "../utils/constants";
 import { route } from "./route-def";
 
-/** ~weekly refresh cadence, comfortably inside OpenAI's ~8-day staleness window given the 10-day TTL. */
-const KEEP_WARM_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Default refresh age. The old 7-day value lost a slot whose ChatGPT session
+ * OpenAI ended at about 6 days 20 hours, before the first attempt. 5 days
+ * leaves 44 hours of margin, so even a daily trigger refreshes by 6 days.
+ */
+const DEFAULT_KEEP_WARM_MAX_AGE_HOURS = 120;
+
+/**
+ * Read on every sweep, never at module load, so a stored override applies on
+ * config reload without a restart. A non-integer or out-of-range value falls
+ * back to the default; the config API rejects writes outside the same bounds.
+ */
+export function keepWarmMaxAgeMs(env: NodeJS.ProcessEnv = process.env): number {
+  const raw = env.CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS?.trim();
+  const { min, max } = CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS_BOUNDS;
+  const value = raw && /^\d+$/.test(raw) ? Number(raw) : Number.NaN;
+  const hours = value >= min && value <= max ? value : DEFAULT_KEEP_WARM_MAX_AGE_HOURS;
+  return hours * 60 * 60 * 1000;
+}
 
 type SlotOutcome =
   | { slot: number; keySuffix: string; outcome: "warm" | "refreshed" }
@@ -61,7 +80,7 @@ const keepWarmRoute = route({
   pattern: ["api", "oauth", "keep-warm", "codex"],
   summary: "Locked keep-warm refresh sweep across all Codex OAuth pool slots",
   description:
-    "Enumerates codex_oauth_* slots and refreshes any older than ~7 days through the same locked getValidCodexOAuth path used at task time. Skips slots with a codex-auth-watch bench marker (auth-failure bench or codex-auth-expiry-watch).",
+    "Enumerates codex_oauth_* slots and refreshes any older than CODEX_OAUTH_KEEP_WARM_MAX_AGE_HOURS (default 120 hours) through the same locked getValidCodexOAuth path used at task time. Skips slots with a codex-auth-watch bench marker (auth-failure bench or codex-auth-expiry-watch).",
   tags: ["OAuth"],
   responses: {
     200: {
@@ -82,6 +101,7 @@ export async function handleCodexOAuthKeepWarm(
 
   const apiUrl = getMcpBaseUrl();
   const apiKey = getApiKey();
+  const maxAgeMs = keepWarmMaxAgeMs();
   const slots = await loadAllCodexOAuthSlots(apiUrl, apiKey);
   const results: SlotOutcome[] = [];
 
@@ -95,9 +115,7 @@ export async function handleCodexOAuthKeepWarm(
 
     try {
       const beforeAccess = creds.access;
-      const refreshed = await getValidCodexOAuth(apiUrl, apiKey, slot, {
-        maxAgeMs: KEEP_WARM_MAX_AGE_MS,
-      });
+      const refreshed = await getValidCodexOAuth(apiUrl, apiKey, slot, { maxAgeMs });
       if (!refreshed) {
         results.push({ slot, outcome: "no-credentials" });
       } else {

package/src/http/config.ts

@@ -86,7 +86,9 @@ async function requestSecretReadScope(
       }).allow
     )
       return "all";
-    if (!auth.runtimeId || resolvedScope?.agentId !== auth.agentId) return "none";
+    // Runtime and agent tokens stand in for a worker and read their own agent's
+    // scope. Task tokens are ACP harness credentials and read no secrets.
+    if (auth.tokenKind === "task" || resolvedScope?.agentId !== auth.agentId) return "none";
     return "self";
   }
   if (auth?.kind === "guest") return "none";
@@ -107,7 +109,7 @@ async function resolveSecretsRead(
   const auth = getRequestAuth(req);
   return {
     effectiveIncludeSecrets: includeSecrets && scope !== "none",
-    includeRepoSecrets: !(auth?.kind === "agent" && auth.runtimeId && scope !== "all"),
+    includeRepoSecrets: !(auth?.kind === "agent" && auth.tokenKind !== "task" && scope !== "all"),
     secretsNote: includeSecrets && scope === "none" ? SECRETS_FORCE_MASK_NOTE : "",
   };
 }
@@ -363,7 +365,7 @@ export async function handleConfig(
     const resolvedScope = {
       agentId:
         parsed.query.agentId ||
-        (auth?.kind === "agent" && auth.runtimeId ? auth.agentId : undefined),
+        (auth?.kind === "agent" && auth.tokenKind !== "task" ? auth.agentId : undefined),
       repoId: parsed.query.repoId || undefined,
     };
     const { effectiveIncludeSecrets, includeRepoSecrets, secretsNote } = await resolveSecretsRead(

package/src/http/core.ts

@@ -547,6 +547,8 @@ export async function handleCore(
         return true;
       }
       req.headers["x-runtime-instance-id"] = auth.runtimeId;
+    }
+    if (auth.tokenKind !== "task") {
       const sourceHeader = req.headers["x-source-task-id"];
       const taskId = Array.isArray(sourceHeader) ? sourceHeader[0] : sourceHeader;
       if (taskId !== undefined && (await getTaskById(taskId))?.agentId !== auth.agentId) {

package/src/http/session-access.ts

@@ -1,4 +1,4 @@
-import type { IncomingMessage } from "node:http";
+import type { IncomingMessage, ServerResponse } from "node:http";
 import { getSteeringMessageById } from "../be/db";
 import { getActiveSessionById } from "../be/db/active-sessions";
 import { getUserGrant } from "../be/rbac-roles";
@@ -10,10 +10,12 @@ import {
   sessionAccessForRoot,
 } from "../be/session-shares";
 import { findUserById } from "../be/users";
-import { isRbacEnabled } from "../rbac";
+import { can, isRbacEnabled, type RbacPrincipal } from "../rbac";
+import type { AgentTask } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { dashboardUserIdHeader } from "./favorite-owner";
 import { type RouteDef, routePathParams } from "./route-def";
+import { jsonError } from "./utils";
 
 /**
  * Who a request acts for when it touches a session.
@@ -76,6 +78,53 @@ export function readableByFor(actor: SessionActor): { userId: string | null } |
 export const SESSION_WRITE_DENIED =
   "You can't write in this session. Ask the owner to share it with edit access.";
 
+/** True unless the request acts for a user who lacks write access to the task's session. */
+export 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");
+}
+
+/**
+ * The parent gate shared by `POST /api/tasks` and `POST /api/apps/{id}/actions/{name}`.
+ * The child inherits the parent's thread context, so an agent caller must own or
+ * have created the parent (`task.parent.attach`; operator and user callers keep
+ * their access), and a follow-up in someone else's session needs a write share.
+ * Writes the 403 and returns true when denied.
+ */
+export async function denyParentAttach(
+  req: IncomingMessage,
+  res: ServerResponse,
+  myAgentId: string | undefined,
+  parentTask: Pick<AgentTask, "id" | "requestedByUserId" | "creatorAgentId" | "agentId">,
+  principal: RbacPrincipal,
+): Promise<boolean> {
+  const attach = can({
+    principal,
+    verb: "task.parent.attach",
+    resource: {
+      kind: "task",
+      taskId: parentTask.id,
+      requestedByUserId: parentTask.requestedByUserId,
+      creatorAgentId: parentTask.creatorAgentId,
+      agentId: parentTask.agentId,
+    },
+    source: "http",
+  });
+  if (!attach.allow) {
+    jsonError(res, `You don't have context for parent task ${parentTask.id}.`, 403);
+    return true;
+  }
+  if (!(await hasSessionWrite(req, myAgentId, parentTask.id))) {
+    jsonError(res, SESSION_WRITE_DENIED, 403);
+    return true;
+  }
+  return false;
+}
+
 /**
  * The denial for an actor lacking `needed` access to the session holding
  * `taskId`, or null. An unknown task passes, so the handler still answers 404.

package/src/http/sessions.ts

@@ -2,11 +2,14 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import {
   countSessions,
+  createAgent,
+  getAgentById,
   getDbClient,
   getRootTaskChain,
   getTaskById,
   listRecentSessions,
 } from "../be/db";
+import { getUserGrant } from "../be/rbac-roles";
 import {
   getSessionRoot,
   listActiveSessionShares,
@@ -18,13 +21,17 @@ import {
 import { getTaskSteeringFieldsForTasks } from "../be/steering";
 import { getTaskCitationsForTasks, TaskCitationSchema } from "../be/task-citations";
 import {
+  AgentTokenExistsError,
   findUserById,
   InvalidRuntimeTokenError,
+  mintAgentToken,
   mintRuntimeToken,
   mintSessionToken,
+  revokeAgentTokens,
   revokeSessionToken,
+  rotateAgentToken,
 } from "../be/users";
-import { can } from "../rbac";
+import { can, isRbacEnabled } from "../rbac";
 import { sessionAccessTopic } from "../realtime/auth";
 import { realtimeBus } from "../realtime/bus";
 import {
@@ -39,6 +46,7 @@ import {
 } from "../types";
 import { getRequestAuth } from "../utils/request-auth-context";
 import { isRuntimePoolsEnabled } from "../utils/runtime-pools-flag";
+import { agentFirstPrincipal } from "./request-principal";
 import { route } from "./route-def";
 import { resolveSessionActor, type SessionActor } from "./session-access";
 import { jsonError } from "./utils";
@@ -118,7 +126,7 @@ const mintSessionTokenRoute = route({
   },
   summary: "Mint an ephemeral task or runtime token",
   description:
-    "Operators can mint task or runtime tokens. Runtime tokens can mint task tokens for their own assigned tasks. Child tokens expire with their parent runtime.",
+    "Operators can mint task or runtime tokens. Runtime and agent tokens can mint task tokens for their own assigned tasks. A child token never outlives its parent and is revoked with it.",
   tags: ["Sessions"],
   body: z
     .object({
@@ -147,7 +155,8 @@ const mintSessionTokenRoute = route({
   },
   auth: { apiKey: true },
   rbac: {
-    ungated: "operator or runtime token minting for its own assigned task, enforced in the handler",
+    ungated:
+      "operator, or a runtime or agent token minting for its own assigned task, enforced in the handler",
   },
 });
 
@@ -157,7 +166,7 @@ const revokeSessionTokenRoute = route({
   pattern: ["api", "sessions", "tokens", null],
   summary: "Revoke an ephemeral session token",
   description:
-    "Operators can revoke any ephemeral token. With runtime pools enabled, runtime tokens can revoke their own child task tokens. Repeated revocation has no effect.",
+    "Operators can revoke any ephemeral token. Agent tokens, and runtime tokens when runtime pools are enabled, can revoke their own child task tokens. Repeated revocation has no effect.",
   tags: ["Sessions"],
   params: z.object({ tokenId: z.string() }),
   responses: {
@@ -167,10 +176,234 @@ const revokeSessionTokenRoute = route({
   },
   auth: { apiKey: true },
   rbac: {
-    ungated: "operator or runtime token revoking its own child, enforced in the handler",
+    ungated:
+      "operator, or a runtime or agent token revoking its own child, enforced in the handler",
   },
 });
 
+/** Default rotation grace: the old worker token keeps working this long. */
+const AGENT_TOKEN_ROTATE_GRACE_SEC = 300;
+
+const AgentTokenSchema = z.object({
+  agentId: z.string(),
+  tokenId: z.string(),
+  plaintext: z.string(),
+  expiresAt: z.string().nullable().describe("null when the token does not expire"),
+});
+
+const agentTokenTtl = z
+  .number()
+  .int()
+  .positive()
+  .optional()
+  .describe("Token lifetime in ms. Omit for the default (no expiry).");
+
+const mintAgentTokenRoute = route({
+  method: "post",
+  path: "/api/agents/{id}/token",
+  pattern: ["api", "agents", null, "token"],
+  operationId: "agents_mintWorkerToken",
+  summary: "Mint an agent-bound worker token",
+  description:
+    "Returns the token once. A worker runs on it in place of the swarm API key and acts only as this agent. Creates the agent when it does not exist and `name` is given. Fails with 409 when the agent already holds an active token.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z
+    .object({ name: z.string().min(1).optional(), ttlMs: agentTokenTtl })
+    .strict()
+    .optional(),
+  responses: {
+    200: {
+      description: "Minted worker token",
+      schema: AgentTokenSchema.extend({ agentCreated: z.boolean() }),
+    },
+    403: { description: "Operator or user credentials required" },
+    404: { description: "Agent not found and no name given" },
+    409: { description: "Agent already holds an active token" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const rotateAgentTokenRoute = route({
+  method: "post",
+  path: "/api/agents/{id}/token/rotate",
+  pattern: ["api", "agents", null, "token", "rotate"],
+  operationId: "agents_rotateWorkerToken",
+  summary: "Rotate an agent-bound worker token",
+  description:
+    "Returns a new token once. The previous token keeps working for `graceSec` (default 300), then expires. Use revoke for a token that must stop now.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  body: z
+    .object({ graceSec: z.number().int().min(0).max(86_400).optional(), ttlMs: agentTokenTtl })
+    .strict()
+    .optional(),
+  responses: {
+    200: {
+      description: "New worker token",
+      schema: AgentTokenSchema.extend({ previousExpiresAt: z.string() }),
+    },
+    403: { description: "Operator or user credentials required" },
+    404: { description: "Agent holds no active token" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const revokeAgentTokenRoute = route({
+  method: "delete",
+  path: "/api/agents/{id}/token",
+  pattern: ["api", "agents", null, "token"],
+  operationId: "agents_revokeWorkerToken",
+  summary: "Revoke an agent-bound worker token",
+  description:
+    "Revokes every active worker token of the agent and the task tokens they minted. Open realtime connections on them close.",
+  tags: ["Sessions"],
+  params: z.object({ id: z.string().min(1) }),
+  responses: {
+    200: {
+      description: "Number of worker tokens revoked (0 when none was active)",
+      schema: z.object({ revoked: z.number().int() }),
+    },
+    403: { description: "Operator or user credentials required" },
+  },
+  rbac: { permission: "agent.token.manage" },
+});
+
+const AGENT_TOKEN_ROUTES = [mintAgentTokenRoute, rotateAgentTokenRoute, revokeAgentTokenRoute];
+
+/**
+ * Gate the worker-token routes. Only an operator key or a user may manage
+ * them, never a session token. The principal is agent-first: an operator key
+ * sent with X-Agent-ID acts as that agent and is refused, as on the
+ * controller-token route.
+ */
+async function ensureAgentTokenManager(
+  req: IncomingMessage,
+  res: ServerResponse,
+  agentId: string,
+): Promise<boolean> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "operator" && auth?.kind !== "user") {
+    jsonError(res, "Worker tokens require operator or user credentials", 403);
+    return false;
+  }
+  const header = req.headers["x-agent-id"];
+  const decision = can({
+    principal: await agentFirstPrincipal(req, Array.isArray(header) ? header[0] : header),
+    verb: "agent.token.manage",
+    resource: { kind: "agent", agentId },
+    source: "http",
+  });
+  if (!decision.allow) {
+    jsonError(res, decision.reason, 403);
+    return false;
+  }
+  // A worker token carries the target agent's privileges and reads that
+  // agent's resolved config, global secrets included. A user without a
+  // grant-all role must already hold both, and may not manage the token of an
+  // agent that may itself act on any agent (a lead).
+  if (auth.kind === "user" && isRbacEnabled()) {
+    const grant = await getUserGrant(auth.userId);
+    if (!grant.grantsAll) {
+      const target = await getAgentById(agentId);
+      const targetActsOnAny = can({
+        principal: { kind: "agent", agentId, isLead: target?.isLead ?? false },
+        verb: "agent.act.any",
+        resource: { kind: "agent", agentId },
+        source: "http",
+      }).allow;
+      if (targetActsOnAny) {
+        jsonError(res, "A lead agent's worker token requires a grant-all role", 403);
+        return false;
+      }
+      const missing = (["agent.act.any", "config.read.secrets"] as const).filter(
+        (verb) => !grant.verbs.has(verb),
+      );
+      if (missing.length > 0) {
+        jsonError(res, `Worker tokens also require: ${missing.join(", ")}`, 403);
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+async function handleAgentTokens(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  const matched = AGENT_TOKEN_ROUTES.find((def) => def.match(req.method, pathSegments));
+  if (!matched) return false;
+  if (!(await ensureAgentTokenManager(req, res, pathSegments[2]!))) return true;
+  res.setHeader("Cache-Control", "no-store");
+
+  if (matched === mintAgentTokenRoute) {
+    const parsed = await mintAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const agentId = parsed.params.id;
+    const result = await getDbClient()
+      .transaction(async () => {
+        let agentCreated = false;
+        if (!(await getAgentById(agentId))) {
+          if (!parsed.body?.name) return { status: 404 as const };
+          // Same defaults as a worker's first registration; it is offline until it connects.
+          await createAgent({
+            id: agentId,
+            name: parsed.body.name,
+            isLead: false,
+            status: "offline",
+            capabilities: [],
+            maxTasks: 1,
+          });
+          agentCreated = true;
+        }
+        return {
+          status: 200 as const,
+          agentCreated,
+          token: await mintAgentToken(agentId, parsed.body?.ttlMs),
+        };
+      })
+      .catch((error) => {
+        if (error instanceof AgentTokenExistsError) return { status: 409 as const };
+        throw error;
+      });
+    if (result.status === 404) {
+      jsonError(res, "Agent not found; pass name to create it", 404);
+      return true;
+    }
+    if (result.status === 409) {
+      jsonError(res, "Agent already holds an active worker token; rotate or revoke it", 409);
+      return true;
+    }
+    mintAgentTokenRoute.respond(res, 200, {
+      agentId,
+      ...result.token,
+      agentCreated: result.agentCreated,
+    });
+    return true;
+  }
+
+  if (matched === rotateAgentTokenRoute) {
+    const parsed = await rotateAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const graceSec = parsed.body?.graceSec ?? AGENT_TOKEN_ROTATE_GRACE_SEC;
+    const token = await rotateAgentToken(parsed.params.id, graceSec * 1000, parsed.body?.ttlMs);
+    if (!token) {
+      jsonError(res, "Agent holds no active worker token", 404);
+      return true;
+    }
+    rotateAgentTokenRoute.respond(res, 200, { agentId: parsed.params.id, ...token });
+    return true;
+  }
+
+  const parsed = await revokeAgentTokenRoute.parse(req, res, pathSegments, queryParams);
+  if (!parsed) return true;
+  revokeAgentTokenRoute.respond(res, 200, { revoked: await revokeAgentTokens(parsed.params.id) });
+  return true;
+}
+
 const listSessions = route({
   method: "get",
   path: "/api/sessions",
@@ -309,9 +542,11 @@ export async function handleSessions(
   queryParams: URLSearchParams,
   myAgentId?: string,
 ): Promise<boolean> {
+  if (await handleAgentTokens(req, res, pathSegments, queryParams)) return true;
+
   if (mintSessionTokenRoute.match(req.method, pathSegments)) {
     const auth = getRequestAuth(req);
-    if (auth?.kind !== "operator" && !(auth?.kind === "agent" && auth.runtimeId)) {
+    if (auth?.kind !== "operator" && !(auth?.kind === "agent" && auth.tokenKind !== "task")) {
       jsonError(res, "Unauthorized", 401);
       return true;
     }
@@ -334,7 +569,7 @@ export async function handleSessions(
           return {
             token: await mintSessionToken(agentId, taskId!, ttlMs!, {
               tokenId: auth.tokenId,
-              runtimeId: auth.runtimeId!,
+              runtimeId: auth.runtimeId,
             }),
           };
         }
@@ -365,7 +600,10 @@ export async function handleSessions(
     const auth = getRequestAuth(req);
     if (
       auth?.kind !== "operator" &&
-      !(isRuntimePoolsEnabled() && auth?.kind === "agent" && auth.runtimeId)
+      !(
+        auth?.kind === "agent" &&
+        (auth.tokenKind === "agent" || (auth.tokenKind === "runtime" && isRuntimePoolsEnabled()))
+      )
     ) {
       jsonError(res, "Unauthorized", 401);
       return true;
@@ -375,8 +613,9 @@ export async function handleSessions(
     const revoked = await getDbClient().transaction(async (client) => {
       if (auth.kind === "agent") {
         const child = await client.get(
-          "SELECT id FROM session_tokens WHERE id = ? AND agentId = ? AND parentRuntimeId = ? AND taskId IS NOT NULL",
-          [parsed.params.tokenId, auth.agentId, auth.runtimeId!],
+          `SELECT id FROM session_tokens WHERE id = ? AND agentId = ? AND taskId IS NOT NULL
+           AND ${auth.runtimeId ? "parentRuntimeId" : "parentTokenId"} = ?`,
+          [parsed.params.tokenId, auth.agentId, auth.runtimeId ?? auth.tokenId],
         );
         if (!child) return false;
       }