@app-vitals/agent-admin 0.0.1 → 0.1.0

package/src/agents-api.ts

@@ -0,0 +1,2826 @@
+/**
+ * agent/src/agents-api.ts
+ * Admin CRUD API — OpenAPIHono app factory.
+ *
+ * Routes mounted at /agents/*. Full CRUD for:
+ *   - Agent (create/read/update/delete — POST /agents (APA-2.1) and the web
+ *     UI form at /admin/agents/new (see admin-ui.ts) both call the same
+ *     createAgent() implementation (agents.ts, APA-1.1), so there is exactly
+ *     one implementation of agent creation with two callers)
+ *   - AgentEnv
+ *   - AgentCronJob
+ *   - AgentTool
+ *   - AgentToken
+ *   - AgentPlugin
+ *
+ * Routes are declared via createRoute() with Zod request/response schemas
+ * (see openapi-schemas.ts). Malformed request bodies are rejected with 400 by
+ * the OpenAPIHono defaultHook before reaching handlers.
+ *
+ * Auth: admin key (SHIPWRIGHT_ADMIN_API_KEYS) OR per-agent bearer token OR
+ *       session cookie (httpOnly JWT, SHIPWRIGHT_SESSION_SECRET).
+ * Cookie name: admin_session.
+ */
+
+import {
+  isPoolTimeoutError,
+  type PoolLike,
+  poolErrorContext,
+  routeContextMiddleware,
+} from "@app-vitals/agent-lib/pool-observability";
+import { callerLabel } from "@app-vitals/agent-lib/request-context";
+import type { ErrorCapturingClient } from "@app-vitals/agent-lib/sentry";
+import { createRoute, OpenAPIHono, z } from "@hono/zod-openapi";
+import { HTTPException } from "hono/http-exception";
+import type { PrismaClient } from "../prisma/client/client.ts";
+import {
+  ACCOUNT_CREATE_ERROR_MESSAGES,
+  accountIdFromScope,
+  getSelfServeSpecialty,
+  isAccountCreateErrorCode,
+} from "./account-agent-create.ts";
+import { reconcileAgentAfterAccountChange } from "./agent-account-assignment.ts";
+import {
+  type AgentAskDeps,
+  type AskChatClient,
+  registerAgentAskRoutes,
+} from "./agent-ask.ts";
+import type { AgentChatTokenService } from "./agent-chat-tokens.ts";
+import type {
+  AgentCronJobService,
+  AgentCronJobWithRunSummary,
+} from "./agent-cron-jobs.ts";
+import type { AgentCronRunStatsService } from "./agent-cron-run-stats.ts";
+import type { AgentCronRunService } from "./agent-cron-runs.ts";
+import type { DeleteAgentFullyDeps } from "./agent-deletion.ts";
+import { deleteAgentFully } from "./agent-deletion.ts";
+import type { AgentEnvService } from "./agent-envs.ts";
+import type { AgentGitHubInstallationsService } from "./agent-github-installations.ts";
+import type { AgentMemberService } from "./agent-members.ts";
+import type { AgentPluginService } from "./agent-plugins.ts";
+import type { AgentProvisioner } from "./agent-provisioner.ts";
+import type { AgentTokenService } from "./agent-tokens.ts";
+import type { AgentToolService } from "./agent-tools.ts";
+import type { AgentService } from "./agents.ts";
+import {
+  createAgent,
+  describeRepoNameCollision,
+  resolveOwnerEmail,
+} from "./agents.ts";
+import {
+  ANTHROPIC_CREDENTIALS_BLOCKED_CODE,
+  AnthropicCredentialsBlockedError,
+  anthropicCredentialKeysIn,
+} from "./anthropic-credential-guard.ts";
+import type { AdminApiKey, AdminAuthEnv, AdminScope } from "./api-auth.ts";
+import {
+  createAdminAuthMiddleware,
+  parseAdminApiKeys,
+  requireScope,
+} from "./api-auth.ts";
+import {
+  type CallerScopeResolver,
+  memberOnlyCallerScopeResolver,
+} from "./caller-scope.ts";
+import type { ChatServiceProvisioningClient } from "./chat-service-provisioning-client.ts";
+import {
+  ApiError,
+  BadRequestError,
+  ForbiddenError,
+  NotFoundError,
+} from "./errors.ts";
+import {
+  AddAgentReposBodySchema,
+  AgentChatTokenUsageDailySchema,
+  AgentCronJobSchema,
+  AgentCronRunSchema,
+  AgentEnvBodySchema,
+  AgentEnvPatchBodySchema,
+  AgentEnvResponseSchema,
+  AgentGitHubInstallationsSnapshotSchema,
+  AgentIdParamSchema,
+  AgentPluginSchema,
+  AgentRepoParamSchema,
+  AgentSummarySchema,
+  AgentTokenSchema,
+  AgentToolSchema,
+  ChatCredentialsWrapperSchema,
+  ChatTokenStatsSchema,
+  CreateAgentBodySchema,
+  CreateAgentCronJobBodySchema,
+  CreateAgentCronRunBodySchema,
+  CreateAgentPluginBodySchema,
+  CreateAgentTokenBodySchema,
+  CreateAgentTokenResponseSchema,
+  CreateAgentToolBodySchema,
+  CreateChatCredentialBodySchema,
+  CreateChatCredentialResponseSchema,
+  CronIdParamSchema,
+  CronRunIdParamSchema,
+  CronRunOutcomesSchema,
+  CronRunsListSchema,
+  CronRunTokenStatsSchema,
+  CronsWithSummaryWrapperSchema,
+  DeleteAgentBodySchema,
+  DeleteAgentResultSchema,
+  EnvKeyParamSchema,
+  ErrorSchema,
+  ListCronRunsQuerySchema,
+  type ModelBreakdownEntry,
+  OkSchema,
+  PatchAgentBodySchema,
+  PatchAgentCronJobBodySchema,
+  PatchAgentCronRunBodySchema,
+  PatchAgentPluginBodySchema,
+  PatchAgentToolBodySchema,
+  PluginNameQuerySchema,
+  PutGitHubInstallationsBodySchema,
+  TokenIdParamSchema,
+  ToolIdParamSchema,
+  UpsertChatTokenDailyBodySchema,
+} from "./openapi-schemas.ts";
+import type { SelfServeConfig } from "./self-serve-config.ts";
+import type { SpecialtyManifestResolver } from "./specialty-manifest-loader.ts";
+import { managedReconcileTargets } from "./startup-policy-reconcile.ts";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+export interface AdminDeps {
+  agentService: Pick<
+    AgentService,
+    | "create"
+    | "delete"
+    | "list"
+    | "getSummary"
+    | "getDetail"
+    | "exists"
+    | "updateSelfHosted"
+    // "updateFields" and "runTransaction" are only needed by createAgent()
+    // (POST /agents, APA-2.1) — everything else in this file already went
+    // through the narrower Pick above.
+    | "updateFields"
+    | "runTransaction"
+  >;
+  agentEnvService: Pick<
+    AgentEnvService,
+    "upsert" | "patch" | "getByAgentId" | "deleteKey"
+  >;
+  agentCronJobService: Pick<
+    AgentCronJobService,
+    | "list"
+    | "listWithRunSummary"
+    | "create"
+    | "update"
+    | "delete"
+    | "reconcileSystemCrons"
+    | "get"
+    | "setEnabled"
+    | "updatePreCheck"
+  >;
+  agentCronRunService: Pick<AgentCronRunService, "create" | "list" | "patch">;
+  agentCronRunStatsService: Pick<
+    AgentCronRunStatsService,
+    "query" | "outcomes"
+  >;
+  agentToolService: Pick<
+    AgentToolService,
+    "list" | "add" | "remove" | "toggle"
+  >;
+  agentTokenService: Pick<
+    AgentTokenService,
+    "create" | "listForAgent" | "revoke" | "validate"
+  >;
+  agentPluginService: Pick<
+    AgentPluginService,
+    "list" | "add" | "remove" | "removeByName"
+  >;
+  agentMemberService: Pick<
+    AgentMemberService,
+    "add" | "listByAgentId" | "exists" | "listByEmail"
+  >;
+  /** Account-aware caller-scope resolver (SSP-2.1); defaults to AgentMember-only. */
+  callerScopeResolver?: CallerScopeResolver;
+  /**
+   * Resolves a specialty name to its parsed Specialty manifest. Consumed
+   * by POST /agents (createAgentRoute, APA-2.1) to seed AgentTool/AgentPlugin
+   * rows from the resolved manifest during agent creation — the same
+   * createAgent() call admin-ui.ts's POST /admin/agents form handler makes
+   * with its own independently-constructed specialtyRegistry instance.
+   * Required (not optional) because the route needs it unconditionally.
+   */
+  specialtyRegistry: SpecialtyManifestResolver;
+  agentChatTokenService: Pick<
+    AgentChatTokenService,
+    "upsertDailyByModel" | "queryStats"
+  >;
+  agentGitHubInstallationsService: Pick<
+    AgentGitHubInstallationsService,
+    "push" | "get"
+  >;
+  /**
+   * Retained solely as a pass-through to deleteAgentFully() (DELETE /agents/:id),
+   * which has its own internal prisma.agent/prisma.agentEnv access — out of
+   * scope for the AgentService migration. All other route handlers in this
+   * file go through `agentService` instead of touching `prisma.agent.*`
+   * directly.
+   */
+  prisma: Pick<PrismaClient, "agent" | "agentEnv">;
+  /**
+   * Provisions (and tears down) the workload backing an agent. Defaults to a
+   * no-op when Kubernetes provisioning is disabled (preserving create/delete
+   * behavior without a cluster). See `agent-provisioner.ts`.
+   */
+  provisioner: AgentProvisioner;
+  /**
+   * Cleanup deps for the full delete-agent orchestration (DELETE /agents/:id
+   * → deleteAgentFully()). Matches DeleteAgentFullyDeps's shapes exactly so
+   * this app can pass them straight through. Production wiring in main.ts
+   * defaults chatService to a no-op client and passes the extension-registered
+   * serviceIntegrations (task-store: a no-op client) when their respective when their respective
+   * URL/token env vars are unset (independent of SHIPWRIGHT_K8S_PROVISIONING),
+   * so this stays required rather than optional — there is always a valid
+   * (possibly no-op) value to inject.
+   */
+  serviceIntegrations: DeleteAgentFullyDeps["serviceIntegrations"];
+  chatService: DeleteAgentFullyDeps["chatService"];
+  slack: DeleteAgentFullyDeps["slack"];
+  decrypt: DeleteAgentFullyDeps["decrypt"];
+  sessionSecret: string;
+  /** Parsed SHIPWRIGHT_ADMIN_API_KEYS — optional; absent means env key auth is disabled. */
+  adminApiKeys?: Map<string, AdminApiKey>;
+  /**
+   * Optional Sentry client for reporting unhandled errors. Undefined means
+   * Sentry is not initialized (SENTRY_DSN unset) — onError simply skips the
+   * capture call. Production wiring in main.ts passes the real `Sentry` from
+   * `@sentry/bun` only when SENTRY_DSN is set.
+   */
+  sentryClient?: ErrorCapturingClient;
+  /**
+   * Admin's pg pool (PLO-1.3). When present, a pool-timeout error captured in
+   * onError carries pool stats context plus route/server_name tags.
+   */
+  pool?: PoolLike;
+  /** Resolved self-serve provisioning config (SSP-1.3). No consumers yet. */
+  selfServe?: SelfServeConfig;
+  /**
+   * Chat-credential mint flag (SHIPWRIGHT_CHAT_TOKEN_MINT_ENABLED === "enabled",
+   * see chat-credential-config.ts). Off (default) → the chat-credentials
+   * routes 404.
+   */
+  chatCredentialsEnabled?: boolean;
+  /**
+   * Chat-service client behind the chat-credentials routes. Absent (chat
+   * service not configured) → the routes 503. Distinct from `chatService`,
+   * which is the always-present (possibly no-op) deletion-cleanup client.
+   */
+  chatCredentials?: Pick<
+    ChatServiceProvisioningClient,
+    "mintToken" | "revokeToken" | "listTokensForAgent"
+  >;
+  /** WIF-2.1: Anthropic federation is enabled; defaults to false. */
+  anthropicFederationEnabled?: boolean;
+  /**
+   * Agent-to-agent ask (COS-31.1): flag + allowlist config, the AgentAsk
+   * audit store and an injectable clock. Absent or flag off → the ask routes
+   * 404. See agent-ask.ts.
+   */
+  agentAsk?: AgentAskDeps;
+  /**
+   * Chat-service thread/message client behind POST /agents/:id/ask
+   * (admin-boot wires the HttpChatClient the chat UI uses). Absent → the ask
+   * route 503s, even with the flag on.
+   */
+  chatClient?: AskChatClient;
+}
+
+export type { AdminApiKey };
+// Re-export for callers that need to build the map from an env string.
+export { parseAdminApiKeys };
+
+// ─── Response schema helpers ────────────────────────────────────────────────────
+
+const ReconcileCronResultSchema = z
+  .object({
+    created: z.number().int(),
+    updated: z.number().int(),
+    deleted: z.number().int(),
+  })
+  .openapi("ReconcileCronResult");
+
+const ReconcileAgentsResultSchema = z
+  .object({
+    recreated: z.array(z.string()),
+    updated: z.array(z.string()),
+    orphans: z.array(z.string()),
+    failed: z.array(z.object({ agentId: z.string(), error: z.string() })),
+    migrated: z.array(z.string()).openapi({
+      description:
+        "perAgent identity mode: agents moved (or, in a dry run, that would be moved) onto their own newly created identity",
+    }),
+    noOwner: z.array(z.string()).openapi({
+      description:
+        "perAgent identity mode: agents skipped because they have no owner; left unmodified",
+    }),
+    dryRun: z.boolean(),
+  })
+  .openapi("ReconcileAgentsResult");
+
+const ReconcileAgentsQuerySchema = z
+  .object({
+    dryRun: z.enum(["true", "false"]).default("false").openapi({
+      description:
+        "Defaults to false (reconcile for real). Pass true to report what would be recreated, updated and moved to per-agent identity without changing anything.",
+    }),
+  })
+  .openapi("ReconcileAgentsQuery");
+
+const StripCredentialsQuerySchema = z
+  .object({
+    dryRun: z.enum(["true", "false"]).default("true").openapi({
+      description:
+        "Defaults to true (report only). Pass false to delete the keys.",
+    }),
+  })
+  .openapi("StripCredentialsQuery");
+
+const StripCredentialsResultSchema = z
+  .object({
+    dryRun: z.boolean(),
+    agents: z.array(
+      z.object({ agentId: z.string(), keys: z.array(z.string()) }),
+    ),
+  })
+  .openapi("StripCredentialsResult");
+
+const ProvisionAgentResultSchema = z
+  .object({
+    resourceName: z.string(),
+    secretName: z.string(),
+    deploymentName: z.string(),
+  })
+  .openapi("ProvisionAgentResult");
+
+const ProvisionSkippedResultSchema = z
+  .object({
+    skipped: z.literal(true),
+    reason: z.string(),
+  })
+  .openapi("ProvisionSkippedResult");
+
+const GetAgentResultSchema = z
+  .object({
+    id: z.string(),
+    name: z.string(),
+    slackId: z.string().nullable().optional(),
+    selfHosted: z.boolean(),
+    repos: z.array(z.string()),
+    reviewAuthorAllowlist: z.array(z.string()),
+    patchAuthorAllowlist: z.array(z.string()),
+    restrictSlackToMembers: z.boolean(),
+    typeName: z.string(),
+    /** Owning account; null for unassigned agents (task-store maps null to its 'default' account). */
+    accountId: z.string().nullable(),
+    createdAt: z.string().datetime(),
+    updatedAt: z.string().datetime(),
+    /**
+     * Required env keys declared by the agent's type manifest that have no
+     * corresponding AgentEnv row yet — key names only, never values
+     * (secrets_in_logs). Always present; informational only (ATS-4.2).
+     */
+    missingRequiredEnv: z.array(z.string()),
+    /**
+     * Non-blocking warning surfaced when restrictSlackToMembers is set to
+     * true on an agent with zero AgentMember rows — the save still succeeds,
+     * this is informational only.
+     */
+    warning: z.string().optional(),
+    /**
+     * ATE-1.1: trial expiry tracking. trialExpiresAt is settable via
+     * PATCH /agents/:id (see PatchAgentBodySchema). trialExpiryWarnedAt is
+     * written internally by ATE-2.1's warning check — read-only via this
+     * route, GET/PATCH responses only.
+     */
+    trialExpiresAt: z.string().datetime().nullable().optional(),
+    trialExpiryWarnedAt: z.string().datetime().nullable().optional(),
+    /** APM-1.3: the six real agent-policy fields (APM-1.1 DB columns). */
+    autoPostReviews: z.boolean().openapi({ example: true }),
+    allowSelfReview: z.boolean().openapi({ example: false }),
+    minConfidence: z.number().int().openapi({ example: 75 }),
+    maxFindings: z.number().int().openapi({ example: 5 }),
+    cleanupMergedWorktrees: z.boolean().openapi({ example: true }),
+    cleanupAfterDays: z.number().int().openapi({ example: 14 }),
+    /**
+     * PAI-2.5: owner and Anthropic identity, so Platform and IT can trace an
+     * agent to its Anthropic identity. Null when unset. k8sServiceAccountName
+     * is deliberately not part of this response.
+     */
+    ownerEmail: z
+      .string()
+      .nullable()
+      .openapi({ example: "jane.doe@example.com" }),
+    anthropicIdentityName: z
+      .string()
+      .nullable()
+      .openapi({ example: "shipwright-my-agent" }),
+    anthropicServiceAccountId: z
+      .string()
+      .nullable()
+      .openapi({ example: "svac_01ABC" }),
+    anthropicFederationRuleId: z
+      .string()
+      .nullable()
+      .openapi({ example: "fdrl_01XYZ" }),
+  })
+  .openapi("GetAgentResult");
+
+const CronWrapperSchema = z
+  .object({ cron: AgentCronJobSchema })
+  .openapi("CronWrapper");
+
+const ToolWrapperSchema = z
+  .object({ tool: AgentToolSchema })
+  .openapi("ToolWrapper");
+
+const ToolsWrapperSchema = z
+  .object({ tools: z.array(AgentToolSchema) })
+  .openapi("ToolsWrapper");
+
+const TokensWrapperSchema = z
+  .object({ tokens: z.array(AgentTokenSchema) })
+  .openapi("TokensWrapper");
+
+const PluginWrapperSchema = z
+  .object({ plugin: AgentPluginSchema })
+  .openapi("PluginWrapper");
+
+const PluginsWrapperSchema = z
+  .object({ plugins: z.array(AgentPluginSchema) })
+  .openapi("PluginsWrapper");
+
+const jsonError = {
+  content: { "application/json": { schema: ErrorSchema } },
+};
+
+const GitHubInstallationsSnapshotWrapperSchema = z
+  .object({ snapshot: AgentGitHubInstallationsSnapshotSchema })
+  .openapi("GitHubInstallationsSnapshotWrapper");
+
+// ─── Route definitions ──────────────────────────────────────────────────────────
+
+const reconcileAgentsRoute = createRoute({
+  method: "post",
+  path: "/agents/reconcile",
+  summary: "Reconcile all agents' K8s state",
+  description:
+    "Admin-only. Reconciles Kubernetes Deployment state against all managed (non-self-hosted) agents in the DB, returning the recreated/updated deployments plus any orphaned deployments or per-agent failures. In perAgent Anthropic identity mode it also creates the missing identity of each existing agent that has an owner and moves its Deployment off the shared ServiceAccount (`migrated`); agents with no owner are listed in `noOwner` and left alone. Pass `dryRun=true` to only report: nothing is created, saved or patched.",
+  request: { query: ReconcileAgentsQuerySchema },
+  responses: {
+    200: {
+      description: "Reconciliation summary",
+      content: { "application/json": { schema: ReconcileAgentsResultSchema } },
+    },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const stripFederationCredentialsRoute = createRoute({
+  method: "post",
+  path: "/agents/federation/strip-credentials",
+  summary: "Strip Anthropic credentials from agents' saved env bundles",
+  description:
+    "Admin-only, one-off migration (WIF-2.2) for moving a deployment to Anthropic workload identity federation. Deletes CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN from every non-self-hosted agent's stored env bundle. `dryRun` defaults to true: nothing is deleted and the response lists what would be. Only agents holding at least one of the keys are listed, so a second applied call returns an empty list. Values are never returned or logged.",
+  request: { query: StripCredentialsQuerySchema },
+  responses: {
+    200: {
+      description: "Agents (and key names) removed, or that would be removed",
+      content: {
+        "application/json": { schema: StripCredentialsResultSchema },
+      },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const provisionAgentRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/provision",
+  summary: "Provision an agent's K8s workload",
+  description:
+    'Admin-only. Provisions or re-provisions the Kubernetes workload for a single managed agent — idempotent, safe to call on an already-provisioned agent. For self-hosted agents, returns `{ skipped: true, reason: "self-hosted" }` with no K8s changes.',
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description:
+        "Agent provisioned (or already-provisioned — idempotent), or skipped for self-hosted agents",
+      content: {
+        "application/json": {
+          schema: z.union([
+            ProvisionAgentResultSchema,
+            ProvisionSkippedResultSchema,
+          ]),
+        },
+      },
+    },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const listAgentsRoute = createRoute({
+  method: "get",
+  path: "/agents",
+  summary: "List all agents",
+  description:
+    "Admin-only. Returns every agent's `id`, `name`, `selfHosted`, and `typeName` — used for metrics name resolution.",
+  responses: {
+    200: {
+      description: "List of agents",
+      content: { "application/json": { schema: z.array(AgentSummarySchema) } },
+    },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const createAgentRoute = createRoute({
+  method: "post",
+  path: "/agents",
+  summary: "Create an agent",
+  description:
+    'Admin-only. Validates name/typeName, creates the Agent row, seeds AgentTool/AgentPlugin rows from the resolved type manifest, attaches repos/allowlists/members, patches Claude credentials, and provisions Kubernetes when `runtime` is "in-cluster" — the same createAgent() implementation (APA-1.1) the web UI form at /admin/agents/new uses. Transactional: on any failure zero rows persist, and this route never returns a partial-success 200. Returns the created agent in the same shape as GET /agents/:id.',
+  request: {
+    body: {
+      content: { "application/json": { schema: CreateAgentBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Agent created",
+      content: { "application/json": { schema: GetAgentResultSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const getAgentRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}",
+  summary: "Get an agent",
+  description:
+    "Admin-only. Returns the full agent record including `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `typeName`, `accountId` (null for unassigned agents), and `missingRequiredEnv` — required env keys declared by the agent's type manifest with no corresponding AgentEnv row yet (informational only).",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "Full agent record",
+      content: { "application/json": { schema: GetAgentResultSchema } },
+    },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const patchAgentRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}",
+  summary: "Update an agent",
+  description:
+    "Admin-only. Updates `selfHosted`, `repos`, `reviewAuthorAllowlist`, `patchAuthorAllowlist`, `restrictSlackToMembers`, `slackId`, `trialExpiresAt`, and/or `accountId` (platform admin only — 403 for session members; `null` clears it; reconciles the workload of in-cluster agents; does not move historical task-store rows). `typeName` and `trialExpiryWarnedAt` are not updatable via this route. `repos` here REPLACES the whole list; for incremental changes use `POST /agents/{id}/repos` (add) and `DELETE /agents/{id}/repos/{owner}/{name}` (remove). Returns the updated agent, including a `warning` field when `restrictSlackToMembers` is set true on an agent with zero members.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: { "application/json": { schema: PatchAgentBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Agent updated",
+      content: { "application/json": { schema: GetAgentResultSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const addAgentReposRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/repos",
+  summary: "Add repos to an agent",
+  description:
+    "Admin, the agent's own key, or platform.ops. Additive alternative to `PATCH /agents/{id}` (which replaces the whole `repos` array): unions the given `org/repo` entries into the agent's current list, preserving the order of existing entries and appending new ones. Idempotent — adding a repo the agent already has is a no-op. 400 when the resulting list has two repos sharing a basename. Returns the full updated agent.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: { "application/json": { schema: AddAgentReposBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Repos added (or already present)",
+      content: { "application/json": { schema: GetAgentResultSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const removeAgentRepoRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/repos/{owner}/{name}",
+  summary: "Remove a repo from an agent",
+  description:
+    "Admin, the agent's own key, or platform.ops. Removes one `owner/name` repo from the agent's `repos`, preserving the order of the rest. 404 when the agent does not have that repo. Returns the full updated agent.",
+  request: { params: AgentRepoParamSchema },
+  responses: {
+    200: {
+      description: "Repo removed",
+      content: { "application/json": { schema: GetAgentResultSchema } },
+    },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent or repo not found", ...jsonError },
+  },
+});
+
+const deleteAgentRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}",
+  summary: "Delete an agent",
+  description:
+    "Admin-only. Runs the full deleteAgentFully() teardown: deprovisions the K8s workload, removes the agent's per-agent Anthropic identity when it has one (federation rule, then Anthropic service account, then Kubernetes ServiceAccount), revokes task-store and chat-service tokens, deletes chat threads, and — if an `xoxpToken` is supplied — deletes the Slack app. The Agent row (and its cascade-deleted child records) is deleted last, only if every automatable step succeeded; `agentDeleted: false` means the row was preserved and the call is safe to retry.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      required: false,
+      content: { "application/json": { schema: DeleteAgentBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description:
+        "Delete outcome — agentDeleted is false when a cleanup step failed; the Agent row is preserved for retry",
+      content: { "application/json": { schema: DeleteAgentResultSchema } },
+    },
+    403: { description: "Forbidden", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const upsertEnvsRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/envs",
+  summary: "Replace all env vars",
+  description:
+    "Bulk-replaces all env vars for the agent atomically. Values are stored encrypted (AES-256-GCM).",
+  request: {
+    params: AgentIdParamSchema,
+    body: { content: { "application/json": { schema: AgentEnvBodySchema } } },
+  },
+  responses: {
+    201: {
+      description: "Env vars replaced",
+      content: { "application/json": { schema: OkSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const getEnvsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/envs",
+  summary: "Get env vars",
+  description:
+    "Returns the agent's env vars. Non-secret values are decrypted; values flagged secret are masked as `***` and their keys listed in `secretKeys`.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "Decrypted env vars",
+      content: { "application/json": { schema: AgentEnvResponseSchema } },
+    },
+  },
+});
+
+const patchEnvsRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}/envs",
+  summary: "Update specific env vars",
+  description:
+    "Updates only the specified keys, leaving other existing env vars untouched.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: { "application/json": { schema: AgentEnvPatchBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Env vars updated",
+      content: { "application/json": { schema: OkSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const deleteEnvKeyRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/envs/{key}",
+  summary: "Delete an env var",
+  description: "Deletes a single env var by key.",
+  request: { params: EnvKeyParamSchema },
+  responses: {
+    204: { description: "Key deleted" },
+  },
+});
+
+const createCronRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/crons",
+  summary: "Create a cron job",
+  description:
+    "Creates a cron job for the agent. `channel` and `user` are mutually exclusive delivery targets. Returns the created job including system-managed read-only fields (`id`, `system`, `parentCronId`, `createdAt`, `updatedAt`) — `parentCronId` is never settable by the caller.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: CreateAgentCronJobBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Cron job created",
+      content: { "application/json": { schema: CronWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const reconcileCronsRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/crons/reconcile",
+  summary: "Reconcile system crons",
+  description:
+    "Reconciles the agent's system crons against the cron list declared by its Specialty manifest. Runs in three passes within a single transaction: create-or-update matched-by-name system crons (preserving IDs so run history survives), link/unlink parent-child cron relationships, and delete orphaned system crons no longer in the manifest. Called automatically on agent startup; returns created/updated/deleted counts.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "Reconciliation summary",
+      content: { "application/json": { schema: ReconcileCronResultSchema } },
+    },
+  },
+});
+
+const patchCronRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}/crons/{cronId}",
+  summary: "Update a cron job",
+  description:
+    "Updates a cron job. `schedule` and `prompt` must be provided together for a content update; `enabled` and `preCheck` are orthogonal and may be sent alone or combined with any other field. At least one field must be present — an empty body returns 400. System crons (`system: true`) reject `schedule`, `prompt`, and/or `preCheck` changes with 403; an enabled-only body is allowed and toggles the cron via the same path used for non-system crons.",
+  request: {
+    params: CronIdParamSchema,
+    body: {
+      content: { "application/json": { schema: PatchAgentCronJobBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Cron job updated",
+      content: { "application/json": { schema: CronWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const deleteCronRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/crons/{cronId}",
+  summary: "Delete a cron job",
+  description:
+    "Deletes a cron job. System crons (`system: true`) cannot be deleted and return 403.",
+  request: { params: CronIdParamSchema },
+  responses: {
+    204: { description: "Cron job deleted" },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const listCronsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/crons/summary",
+  summary: "List cron jobs with run summary",
+  description:
+    "Returns each cron job's last-run timestamp, outcome, and today's run count alongside its config — without full prompt text. Useful for dashboards.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "List of cron jobs with run summary",
+      content: {
+        "application/json": { schema: CronsWithSummaryWrapperSchema },
+      },
+    },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const createCronRunRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/crons/{cronId}/runs",
+  summary: "Create a cron run record",
+  description:
+    "Records the start of a cron job execution, including optional skip/outcome data and dispatch attribution (`itemType`/`itemId`, write-once at creation).",
+  request: {
+    params: CronIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: CreateAgentCronRunBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Run record created",
+      content: {
+        "application/json": {
+          schema: z
+            .object({ run: AgentCronRunSchema })
+            .openapi("CronRunWrapper"),
+        },
+      },
+    },
+    400: { description: "Bad request", ...jsonError },
+    404: { description: "Cron job not found", ...jsonError },
+  },
+});
+
+const listCronRunsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/crons/{cronId}/runs",
+  summary: "List cron runs",
+  description:
+    "Returns a paginated list of runs for a cron job (`limit` default 20, `offset` default 0). `itemId` and `phaseId` are optional server-side filters that combine with AND when both are supplied.",
+  request: {
+    params: CronIdParamSchema,
+    query: ListCronRunsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Paginated list of cron runs",
+      content: { "application/json": { schema: CronRunsListSchema } },
+    },
+    404: { description: "Cron job not found", ...jsonError },
+  },
+});
+
+const patchCronRunRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}/crons/{cronId}/runs/{runId}",
+  summary: "Update a cron run record",
+  description:
+    "Records completion data after a run finishes — `completedAt`, `outcome`, `error`, `skipped`, `skipReason`, `sessionId`, and `modelBreakdown` (per-model token/cost entries, upserted per `[cronRunId, model]`). At least one field must be provided.",
+  request: {
+    params: CronRunIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: PatchAgentCronRunBodySchema },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Run record updated",
+      content: {
+        "application/json": {
+          schema: z
+            .object({ run: AgentCronRunSchema })
+            .openapi("PatchCronRunWrapper"),
+        },
+      },
+    },
+    400: { description: "Bad request", ...jsonError },
+    404: { description: "Run not found or not owned by agent", ...jsonError },
+  },
+});
+
+const createToolRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/tools",
+  summary: "Add a tool pattern",
+  description:
+    'Adds an allowed-tool entry — a glob or exact Claude Code tool name (e.g. "Read", "Bash", "mcp__*") the agent can call.',
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: CreateAgentToolBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Tool added",
+      content: { "application/json": { schema: ToolWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const listToolsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/tools",
+  summary: "List tool patterns",
+  description:
+    "Returns every allowed-tool entry for the agent, each with `id`, `pattern`, and `enabled`.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "List of tool patterns",
+      content: { "application/json": { schema: ToolsWrapperSchema } },
+    },
+  },
+});
+
+const patchToolRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}/tools/{toolId}",
+  summary: "Enable or disable a tool pattern",
+  description: "Updates a tool entry's `pattern` and/or `enabled` state.",
+  request: {
+    params: ToolIdParamSchema,
+    body: {
+      content: { "application/json": { schema: PatchAgentToolBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Tool toggled",
+      content: { "application/json": { schema: ToolWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const deleteToolRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/tools/{toolId}",
+  summary: "Remove a tool pattern",
+  description: "Deletes a tool entry from the agent's allowed-tools list.",
+  request: { params: ToolIdParamSchema },
+  responses: {
+    204: { description: "Tool removed" },
+  },
+});
+
+const createTokenRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/tokens",
+  summary: "Create an API token",
+  description:
+    "Creates a per-agent bearer token for scoped API access. The raw token value is returned once in this response — only its SHA-256 hash is persisted, so it must be saved immediately.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      required: false,
+      content: {
+        "application/json": { schema: CreateAgentTokenBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Token created (raw value returned once)",
+      content: {
+        "application/json": { schema: CreateAgentTokenResponseSchema },
+      },
+    },
+  },
+});
+
+const listTokensRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/tokens",
+  summary: "List API tokens",
+  description:
+    "Returns token metadata (hash excluded) for the agent — raw token values are never returned after creation.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "List of token metadata",
+      content: { "application/json": { schema: TokensWrapperSchema } },
+    },
+  },
+});
+
+const deleteTokenRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/tokens/{tokenId}",
+  summary: "Revoke an API token",
+  description: "Soft-deletes the token by setting `revokedAt`.",
+  request: { params: TokenIdParamSchema },
+  responses: {
+    204: { description: "Token revoked" },
+  },
+});
+
+const chatCredentialErrors = {
+  403: { description: "Forbidden", ...jsonError },
+  404: {
+    description: "Not found, or chat-credential minting disabled",
+    ...jsonError,
+  },
+  503: { description: "Chat service not configured", ...jsonError },
+};
+
+const createChatCredentialRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/chat-credentials",
+  summary: "Mint a chat credential",
+  description:
+    "Mints a chat-service token scoped to the agent in the path. `*` or `platform.ops` callers only — never the agent's own key. The body is closed: an `agentId` field is rejected with 400, so an unrestricted chat admin token cannot be minted here. The raw token is returned once and is never logged or stored by admin. 404 unless SHIPWRIGHT_CHAT_TOKEN_MINT_ENABLED is `enabled`.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: CreateChatCredentialBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Credential minted (raw token returned once)",
+      content: {
+        "application/json": { schema: CreateChatCredentialResponseSchema },
+      },
+    },
+    400: { description: "Bad request", ...jsonError },
+    ...chatCredentialErrors,
+  },
+});
+
+const listChatCredentialsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/chat-credentials",
+  summary: "List chat credentials",
+  description:
+    "Lists the chat-service tokens scoped to the agent (id and label only — raw values are never returned). `*` or `platform.ops` callers only.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "Chat credential metadata",
+      content: {
+        "application/json": { schema: ChatCredentialsWrapperSchema },
+      },
+    },
+    ...chatCredentialErrors,
+  },
+});
+
+const deleteChatCredentialRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/chat-credentials/{tokenId}",
+  summary: "Revoke a chat credential",
+  description:
+    "Revokes a chat-service token. 404 when the token is not scoped to the agent in the path. `*` or `platform.ops` callers only.",
+  request: { params: TokenIdParamSchema },
+  responses: {
+    204: { description: "Credential revoked" },
+    ...chatCredentialErrors,
+  },
+});
+
+const createPluginRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/plugins",
+  summary: "Install a plugin",
+  description: "Adds a Claude Code marketplace plugin for the agent.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: CreateAgentPluginBodySchema },
+      },
+    },
+  },
+  responses: {
+    201: {
+      description: "Plugin added",
+      content: { "application/json": { schema: PluginWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const listPluginsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/plugins",
+  summary: "List plugins",
+  description: "Returns every plugin installed for the agent.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "List of plugins",
+      content: { "application/json": { schema: PluginsWrapperSchema } },
+    },
+  },
+});
+
+const patchPluginRoute = createRoute({
+  method: "patch",
+  path: "/agents/{id}/plugins",
+  summary: "Update a plugin",
+  description:
+    'Re-upserts the plugin identified by the required `name` query param with a new `version` and/or `enabled` state. Uses a query param rather than a path segment because a canonical plugin spec like "my-plugin@org/my-marketplace" can contain a literal "/" that would break path matching.',
+  request: {
+    params: AgentIdParamSchema,
+    query: PluginNameQuerySchema,
+    body: {
+      content: { "application/json": { schema: PatchAgentPluginBodySchema } },
+    },
+  },
+  responses: {
+    200: {
+      description: "Plugin version updated",
+      content: { "application/json": { schema: PluginWrapperSchema } },
+    },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const deletePluginRoute = createRoute({
+  method: "delete",
+  path: "/agents/{id}/plugins",
+  summary: "Remove a plugin",
+  description:
+    "Removes the plugin identified by the required `name` query param.",
+  request: {
+    params: AgentIdParamSchema,
+    query: PluginNameQuerySchema,
+  },
+  responses: {
+    204: { description: "Plugin removed" },
+    400: { description: "Bad request", ...jsonError },
+  },
+});
+
+const upsertChatTokenDailyRoute = createRoute({
+  method: "post",
+  path: "/agents/{id}/chat-tokens/daily",
+  summary: "Record daily chat token usage",
+  description:
+    "Atomically accumulates Slack chat token usage into the existing rows for each `(agentId, date, model)` tuple, creating them if absent. Supply a `modelBreakdown` array to split a single day's usage across multiple models. Returns the updated daily rows, one per model.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: UpsertChatTokenDailyBodySchema },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Updated daily chat token usage rows (one per model)",
+      content: {
+        "application/json": { schema: z.array(AgentChatTokenUsageDailySchema) },
+      },
+    },
+    400: { description: "Bad request", ...jsonError },
+    404: { description: "Agent not found", ...jsonError },
+  },
+});
+
+const putGitHubInstallationsRoute = createRoute({
+  method: "put",
+  path: "/agents/{id}/github-installations",
+  summary: "Replace the agent's GitHub installations snapshot",
+  description:
+    "Upserts the agent's single GitHub App installations snapshot (owner, installation id, state, sanitized lastError), replacing the prior list wholesale — an installation absent from the body is dropped. The body schema is closed: unknown fields (e.g. tokens) are rejected with 400.",
+  request: {
+    params: AgentIdParamSchema,
+    body: {
+      content: {
+        "application/json": { schema: PutGitHubInstallationsBodySchema },
+      },
+    },
+  },
+  responses: {
+    200: {
+      description: "Snapshot replaced",
+      content: {
+        "application/json": {
+          schema: GitHubInstallationsSnapshotWrapperSchema,
+        },
+      },
+    },
+    400: { description: "Bad request", ...jsonError },
+    401: { description: "Unauthorized", ...jsonError },
+    403: {
+      description: "Forbidden — token does not own this agent",
+      ...jsonError,
+    },
+  },
+});
+
+const getGitHubInstallationsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/github-installations",
+  summary: "Get the latest GitHub installations snapshot",
+  description:
+    "Returns the most recently reported GitHub installations snapshot, or 404 if the agent has never reported one.",
+  request: { params: AgentIdParamSchema },
+  responses: {
+    200: {
+      description: "Latest GitHub installations snapshot",
+      content: {
+        "application/json": {
+          schema: GitHubInstallationsSnapshotWrapperSchema,
+        },
+      },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: {
+      description: "Forbidden — token does not own this agent",
+      ...jsonError,
+    },
+    404: { description: "No snapshot reported yet", ...jsonError },
+  },
+});
+
+/** `from`/`to` ISO datetime bounds shared by the cron-run report routes. */
+export const cronRunStatsQuerySchema = z
+  .object({
+    from: z
+      .string()
+      .datetime()
+      .optional()
+      .openapi({ example: "2026-01-01T00:00:00Z" }),
+    to: z
+      .string()
+      .datetime()
+      .optional()
+      .openapi({ example: "2026-02-01T00:00:00Z" }),
+  })
+  .openapi("CronRunStatsQuery");
+
+const cronRunTokenStatsRoute = createRoute({
+  method: "get",
+  path: "/agents/all/cron-runs/stats",
+  summary: "Get aggregated cron-run token stats",
+  description:
+    "Admin-only. Returns token usage and cost aggregated across all agents' cron runs, broken down by agent, cron, model, day, and pipeline phase. Optional `from`/`to` ISO datetime query params bound the range.",
+  request: {
+    query: cronRunStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Aggregated cron-run token stats across all agents",
+      content: { "application/json": { schema: CronRunTokenStatsSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden — requires admin scope", ...jsonError },
+  },
+});
+
+const agentCronRunTokenStatsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/cron-runs/stats",
+  summary: "Get aggregated cron-run token stats for one agent",
+  description:
+    "Same shape as GET /agents/all/cron-runs/stats, scoped to the given agent's runs. An agent's own bearer token may read its own stats; other agents' tokens are rejected. Optional `from`/`to` ISO datetime query params bound the range.",
+  request: {
+    params: z.object({ id: z.string() }),
+    query: cronRunStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Aggregated cron-run token stats for the agent",
+      content: { "application/json": { schema: CronRunTokenStatsSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const cronRunOutcomesRoute = createRoute({
+  method: "get",
+  path: "/agents/all/cron-runs/outcomes",
+  summary: "Get cron-run outcomes per phase and context fingerprint",
+  description:
+    "Admin-only. Returns, per (phase, contextFingerprint): run, completed, failed, and skipped counts, a skipReasons histogram, avg and p50 duration, avg turns, avg tool calls, and avg first-turn context tokens. Optional `from`/`to` ISO datetime query params bound the range on startedAt.",
+  request: {
+    query: cronRunStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Outcome series per (phase, contextFingerprint)",
+      content: { "application/json": { schema: CronRunOutcomesSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden — requires admin scope", ...jsonError },
+  },
+});
+
+const agentCronRunOutcomesRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/cron-runs/outcomes",
+  summary:
+    "Get cron-run outcomes per phase and context fingerprint for one agent",
+  description:
+    "Same shape as GET /agents/all/cron-runs/outcomes, scoped to the given agent's runs. An agent's own bearer token may read its own outcomes; other agents' tokens are rejected. Optional `from`/`to` ISO datetime query params bound the range on startedAt.",
+  request: {
+    params: z.object({ id: z.string() }),
+    query: cronRunStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description:
+        "Outcome series per (phase, contextFingerprint) for the agent",
+      content: { "application/json": { schema: CronRunOutcomesSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+const chatTokenDailyStatsQuerySchema = z
+  .object({
+    from: z.string().date().optional().openapi({ example: "2026-01-01" }),
+    to: z.string().date().optional().openapi({ example: "2026-02-01" }),
+  })
+  .openapi("ChatTokenDailyStatsQuery");
+
+const chatTokenDailyStatsRoute = createRoute({
+  method: "get",
+  path: "/agents/chat-tokens/daily/stats",
+  summary: "Get aggregated chat token daily stats",
+  description:
+    "Admin-only. Returns Slack chat token usage aggregated across all agents, broken down by agent, model, and day. Optional `from`/`to` YYYY-MM-DD query params bound the range.",
+  request: {
+    query: chatTokenDailyStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Aggregated chat token daily stats across all agents",
+      content: { "application/json": { schema: ChatTokenStatsSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden — requires admin scope", ...jsonError },
+  },
+});
+
+const selfChatTokenDailyStatsRoute = createRoute({
+  method: "get",
+  path: "/agents/{id}/chat-tokens/daily/stats",
+  summary: "Get this agent's chat token daily stats",
+  description:
+    "Self-serve variant of the fleet-wide chat token daily stats, scoped to the agent in the path. Access is gated by the generic agent-route auth (an agent's own bearer token, an admin, or a member session) — no admin scope required. Same response shape and optional `from`/`to` params as GET /agents/chat-tokens/daily/stats.",
+  request: {
+    params: AgentIdParamSchema,
+    query: chatTokenDailyStatsQuerySchema,
+  },
+  responses: {
+    200: {
+      description: "Chat token daily stats for this agent only",
+      content: { "application/json": { schema: ChatTokenStatsSchema } },
+    },
+    401: { description: "Unauthorized", ...jsonError },
+    403: { description: "Forbidden", ...jsonError },
+  },
+});
+
+// ─── App factory ──────────────────────────────────────────────────────────────
+
+/**
+ * The admin API's OpenAPIHono app: a 400 for request-validation failures
+ * (defaultHook) and the shared error mapping (onError). Exported so extension
+ * API apps (AEP-3.2) answer validation failures and errors exactly like the
+ * platform API. `pool`, when given, attaches pg pool stats to pool-timeout
+ * captures (PLO-1.3).
+ */
+export function createAdminApiHono(
+  sentryClient?: ErrorCapturingClient,
+  pool?: PoolLike,
+): OpenAPIHono<AdminAuthEnv> {
+  const app = new OpenAPIHono<AdminAuthEnv>({
+    // Fires when Zod request validation fails — surface a 400 with the issues.
+    defaultHook: (result, c) => {
+      if (!result.success) {
+        const message = result.error.issues
+          .map((i) => `${i.path.join(".")}: ${i.message}`)
+          .join(", ");
+        return c.json({ error: message }, 400);
+      }
+    },
+  });
+
+  // Record method + matched route so pool diagnostics can name the route.
+  app.use("*", routeContextMiddleware());
+
+  // Capture an unhandled error. Pool-timeout errors additionally carry pool
+  // stats + route/server_name (PLO-1.3); every other error is captured as-is.
+  const captureUnhandled = (err: unknown) => {
+    if (!sentryClient) return;
+    if (pool && sentryClient.withScope && isPoolTimeoutError(err)) {
+      const ctx = poolErrorContext(pool);
+      void sentryClient.withScope(async (scope) => {
+        scope.setContext?.("pg_pool", ctx);
+        scope.setTag("server_name", "admin");
+        if (typeof ctx.route === "string") scope.setTag("route", ctx.route);
+        sentryClient.captureException(err);
+      });
+      return;
+    }
+    sentryClient.captureException(err);
+  };
+
+  app.onError((err, c) => {
+    if (err instanceof ApiError && err.statusCode < 500) {
+      return c.json(
+        {
+          error: err.message,
+          ...(err instanceof AnthropicCredentialsBlockedError && {
+            code: err.code,
+          }),
+        },
+        err.statusCode as 400 | 401 | 403 | 404 | 409 | 422,
+      );
+    }
+    if (err instanceof ApiError) {
+      captureUnhandled(err);
+      return c.json({ error: err.message }, err.statusCode as 500 | 502);
+    }
+    // zod-openapi 1.x throws an HTTPException for request-shape problems —
+    // 415 for a non-JSON Content-Type on a JSON-body route, 400 for an
+    // unparseable body. Client errors: respond with the exception's status.
+    if (err instanceof HTTPException && err.status < 500) {
+      return c.json({ error: err.message }, err.status as 400 | 415);
+    }
+    captureUnhandled(err);
+    console.error(
+      `[agents-api] unhandled error (caller: ${callerLabel(c.get("caller"), c.get("scope")?.kind)}):`,
+      err,
+    );
+    return c.json({ error: "Internal server error" }, 500);
+  });
+
+  return app;
+}
+
+export function createAdminApp(deps: AdminDeps): OpenAPIHono<AdminAuthEnv> {
+  const {
+    agentService,
+    agentEnvService,
+    agentCronJobService,
+    agentCronRunService,
+    agentCronRunStatsService,
+    agentToolService,
+    agentTokenService,
+    agentPluginService,
+    agentMemberService,
+    specialtyRegistry,
+    agentChatTokenService,
+    agentGitHubInstallationsService,
+    prisma,
+    provisioner,
+    serviceIntegrations,
+    chatService,
+    slack,
+    decrypt,
+    sessionSecret,
+    adminApiKeys,
+    sentryClient,
+    pool,
+  } = deps;
+  const callerScopeResolver =
+    deps.callerScopeResolver ??
+    memberOnlyCallerScopeResolver(agentMemberService);
+
+  const app = createAdminApiHono(sentryClient, pool);
+
+  const authMiddleware = createAdminAuthMiddleware({
+    sessionSecret,
+    agentTokenService,
+    adminApiKeys,
+    agentMemberService,
+    callerScopeResolver,
+  });
+
+  // Platform readers/operators (platform.read / platform.ops admin keys): the
+  // auth middleware has already enforced the method and PLATFORM_OPS_ROUTES
+  // allowlist, so handlers only widen their reader checks for them.
+  const isPlatformCaller = (c: { get: (k: "scope") => unknown }) => {
+    const kind = (c.get("scope") as AdminScope | undefined)?.kind;
+    return kind === "platform-read" || kind === "platform-ops";
+  };
+
+  // Admin, a platform reader/operator, or a session-cookie caller (membership
+  // of the route's agent already enforced by the auth middleware). Bearer
+  // non-admins stay denied.
+  const isAdminOrSessionMember = (c: {
+    get: (k: "isAdmin" | "callerEmail" | "scope") => unknown;
+  }) =>
+    c.get("isAdmin") === true ||
+    c.get("callerEmail") !== undefined ||
+    isPlatformCaller(c);
+
+  // Apply combined auth (bearer token OR session cookie) to all /agents/* routes.
+  app.use("/agents/*", authMiddleware);
+
+  // /agents/* covers all /agents/… paths with at least one trailing segment
+  // (e.g. /agents/:id, /agents/:id/crons). Only the zero-segment paths
+  // (/agents and /agents/reconcile) are not covered above — apply auth to them
+  // explicitly.
+  app.use("/agents", authMiddleware);
+  app.use("/agents/reconcile", authMiddleware);
+
+  // ─── Agents ────────────────────────────────────────────────────────────────
+
+  // POST /agents/reconcile — reconcile K8s Deployment state against the DB (admin only)
+  app.openapi(reconcileAgentsRoute, async (c) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can reconcile agents",
+      );
+    }
+    const dryRun = c.req.valid("query").dryRun === "true";
+    const result = await provisioner.reconcile(
+      managedReconcileTargets(await agentService.list()),
+      { dryRun },
+    );
+    return c.json(result, 200);
+  });
+
+  // POST /agents/federation/strip-credentials — WIF-2.2 migration (admin only).
+  // Static path "federation" must be registered before any /agents/:id/* routes
+  // so the literal is never matched as an agentId.
+  app.openapi(stripFederationCredentialsRoute, async (c) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can strip federation credentials",
+      );
+    }
+    const dryRun = c.req.valid("query").dryRun !== "false";
+    const agents: Array<{ agentId: string; keys: string[] }> = [];
+    for (const agent of await agentService.list()) {
+      if (agent.selfHosted) continue;
+      const bundle = await agentEnvService.getByAgentId(agent.id);
+      if (bundle === null) continue;
+      const keys = anthropicCredentialKeysIn(Object.keys(bundle.env));
+      if (keys.length === 0) continue;
+      if (!dryRun) {
+        for (const key of keys) await agentEnvService.deleteKey(agent.id, key);
+        console.log(
+          `[agents-api] stripped Anthropic credentials from agent ${agent.id}: ${keys.join(", ")}`,
+        );
+      }
+      agents.push({ agentId: agent.id, keys });
+    }
+    return c.json({ dryRun, agents }, 200);
+  });
+
+  // POST /agents/:id/provision — provision a single agent's K8s workload (admin only).
+  // Idempotent: safe to call on an already-provisioned agent.
+  app.openapi(provisionAgentRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can provision agents",
+      );
+    }
+    const { id: agentId } = c.req.valid("param");
+
+    const agent = await agentService.getSummary(agentId);
+    if (!agent) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+
+    if (agent.selfHosted) {
+      return c.json({ skipped: true as const, reason: "self-hosted" }, 200);
+    }
+
+    const { resourceName, secretName, deploymentName } =
+      await provisioner.provision(agent.id, {
+        slug: agent.name,
+        accountId: agent.accountId,
+      });
+    return c.json({ resourceName, secretName, deploymentName }, 200);
+  });
+
+  // GET /agents/:id — get full agent record including selfHosted and repos
+  app.openapi(getAgentRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError("Admin access required to get agent");
+    }
+    const { id: agentId } = c.req.valid("param");
+    const agent = await agentService.getDetail(agentId);
+    if (!agent) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    return c.json(serializeAgent(agent), 200);
+  });
+
+  // PATCH /agents/:id — update agent fields (selfHosted, repos)
+  app.openapi(patchAgentRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError("Admin access required to update agent");
+    }
+    requireScope(c, "ops");
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+
+    const existing = await agentService.exists(agentId);
+    if (!existing) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    // SSP-5.3: assigning an agent to an account is platform-admin only —
+    // session members (admitted by isAdminOrSessionMember) must not move
+    // agents between tenants.
+    if (body.accountId !== undefined) {
+      if (c.get("isAdmin") !== true) {
+        throw new ForbiddenError("Admin access required to change accountId");
+      }
+    }
+    const collision =
+      body.repos !== undefined ? describeRepoNameCollision(body.repos) : null;
+    if (collision) {
+      throw new BadRequestError(collision);
+    }
+    const agent = await agentService
+      .updateSelfHosted(agentId, {
+        selfHosted: body.selfHosted,
+        ...(body.accountId !== undefined ? { accountId: body.accountId } : {}),
+        ...(body.repos !== undefined ? { repos: body.repos } : {}),
+        ...(body.reviewAuthorAllowlist !== undefined
+          ? { reviewAuthorAllowlist: body.reviewAuthorAllowlist }
+          : {}),
+        ...(body.patchAuthorAllowlist !== undefined
+          ? { patchAuthorAllowlist: body.patchAuthorAllowlist }
+          : {}),
+        ...(body.restrictSlackToMembers !== undefined
+          ? { restrictSlackToMembers: body.restrictSlackToMembers }
+          : {}),
+        ...(body.slackId !== undefined ? { slackId: body.slackId } : {}),
+        ...(body.trialExpiresAt !== undefined
+          ? {
+              trialExpiresAt: body.trialExpiresAt
+                ? new Date(body.trialExpiresAt)
+                : null,
+            }
+          : {}),
+        ...(body.autoPostReviews !== undefined
+          ? { autoPostReviews: body.autoPostReviews }
+          : {}),
+        ...(body.allowSelfReview !== undefined
+          ? { allowSelfReview: body.allowSelfReview }
+          : {}),
+        ...(body.minConfidence !== undefined
+          ? { minConfidence: body.minConfidence }
+          : {}),
+        ...(body.maxFindings !== undefined
+          ? { maxFindings: body.maxFindings }
+          : {}),
+        ...(body.cleanupMergedWorktrees !== undefined
+          ? { cleanupMergedWorktrees: body.cleanupMergedWorktrees }
+          : {}),
+        ...(body.cleanupAfterDays !== undefined
+          ? { cleanupAfterDays: body.cleanupAfterDays }
+          : {}),
+      })
+      .catch((err: unknown) => {
+        // FK violation: Agent.accountId references a nonexistent Account.
+        if ((err as { code?: string } | null)?.code === "P2003") {
+          throw new NotFoundError(`account ${body.accountId} not found`);
+        }
+        throw err;
+      });
+    const slackWarning = await computeRestrictSlackToMembersWarning(
+      agentMemberService,
+      agentId,
+      agent.restrictSlackToMembers,
+    );
+    const reconcileWarning =
+      body.accountId !== undefined
+        ? await reconcileAgentAfterAccountChange(provisioner, agent)
+        : undefined;
+    const warning =
+      [slackWarning, reconcileWarning].filter(Boolean).join("; ") || undefined;
+    return c.json(serializeAgent(agent, warning), 200);
+  });
+
+  // POST /agents/:id/repos — additive repo attach (same gating as PATCH).
+  // Registered with the other /agents/:id routes; no static /agents/repos
+  // route exists, and "/agents/{id}/repos" has an extra segment so it cannot
+  // shadow or be shadowed by the single-segment "/agents/{id}".
+  app.openapi(addAgentReposRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError("Admin access required to update agent");
+    }
+    requireScope(c, "ops");
+    const { id: agentId } = c.req.valid("param");
+    const { repos: toAdd } = c.req.valid("json");
+    const current = await agentService.getDetail(agentId);
+    if (!current) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    const merged = [...new Set([...current.repos, ...toAdd])];
+    const collision = describeRepoNameCollision(merged);
+    if (collision) {
+      throw new BadRequestError(collision);
+    }
+    const agent = await agentService.updateSelfHosted(agentId, {
+      selfHosted: current.selfHosted,
+      repos: merged,
+    });
+    return c.json(serializeAgent(agent), 200);
+  });
+
+  // DELETE /agents/:id/repos/:owner/:name — remove one repo.
+  app.openapi(removeAgentRepoRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError("Admin access required to update agent");
+    }
+    requireScope(c, "ops");
+    const { id: agentId, owner, name } = c.req.valid("param");
+    const current = await agentService.getDetail(agentId);
+    if (!current) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    const repo = `${owner}/${name}`;
+    if (!current.repos.includes(repo)) {
+      throw new NotFoundError(`agent ${agentId} does not have repo ${repo}`);
+    }
+    const agent = await agentService.updateSelfHosted(agentId, {
+      selfHosted: current.selfHosted,
+      repos: current.repos.filter((r) => r !== repo),
+    });
+    return c.json(serializeAgent(agent), 200);
+  });
+
+  // DELETE /agents/:id — delete an agent and tear down its workload (admin only)
+  app.openapi(deleteAgentRoute, async (c) => {
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can delete agents",
+      );
+    }
+    const { id: agentId } = c.req.valid("param");
+
+    // Body is optional — an absent/empty body is the common case (most
+    // current callers don't send one) and simply means no xoxpToken.
+    const body = c.req.valid("json");
+
+    // Full teardown: K8s workload, task-store + chat-service tokens/threads,
+    // optional Slack app deletion, then the Agent row itself (deleted last,
+    // only if every automatable step succeeded). deleteAgentFully() does its
+    // own findUnique and throws NotFoundError for an unknown id (→ 404 via
+    // the existing onError handler), so no separate pre-check is needed here.
+    // It catches per-step teardown failures internally and reports them in
+    // the result rather than throwing, so this call is intentionally NOT
+    // wrapped in try/catch — a 500 here would only mean a genuinely
+    // unexpected error, which should propagate like any other ApiError.
+    const result = await deleteAgentFully(
+      agentId,
+      {
+        prisma,
+        provisioner,
+        serviceIntegrations,
+        chatService,
+        slack,
+        decrypt,
+      },
+      { xoxpToken: body?.xoxpToken },
+    );
+
+    return c.json(result, 200);
+  });
+
+  // GET /agents — list all agents (id + name + selfHosted) for metrics name resolution.
+  app.openapi(listAgentsRoute, async (c) => {
+    const email = c.get("callerEmail");
+    if (!isAdminOrSessionMember(c)) {
+      throw new ForbiddenError("Admin access required to list agents");
+    }
+    // list() also selects the owner and identity IDs for reconcile targets;
+    // they are not part of this response.
+    const agents = (await agentService.list()).map(
+      ({
+        ownerEmail: _o,
+        anthropicIdentityName: _n,
+        anthropicServiceAccountId: _s,
+        anthropicFederationRuleId: _r,
+        k8sServiceAccountName: _k,
+        ...summary
+      }) => summary,
+    );
+    if (c.get("isAdmin") === true || email === undefined) {
+      return c.json(agents, 200);
+    }
+    // Non-admin session: only agents the caller has an AgentMember row for.
+    const scope = await callerScopeResolver(email, false);
+    const memberAgentIds = new Set(scope.kind === "all" ? [] : scope.agentIds);
+    return c.json(
+      agents.filter((a) => memberAgentIds.has(a.id)),
+      200,
+    );
+  });
+
+  // POST /agents — create a new agent (admin only). Delegates to createAgent()
+  // (agents.ts, APA-1.1) — the same implementation admin-ui.ts's POST
+  // /admin/agents form handler calls, so this route is a second caller, not a
+  // second implementation.
+  app.openapi(createAgentRoute, async (c) => {
+    const body = c.req.valid("json");
+
+    // SSP-4.2: platform admins keep today's behavior (and may create
+    // unassigned agents). A session user with an account (flag on) may create
+    // agents in THEIR account only: accountId comes from the resolved scope —
+    // never the body — and the type is forced to "coding".
+    let accountId: string | undefined;
+    if (c.get("isAdmin") !== true) {
+      const email = c.get("callerEmail");
+      const callerAccountId =
+        email === undefined
+          ? null
+          : accountIdFromScope(await callerScopeResolver(email, false));
+      if (callerAccountId === null) {
+        throw new ForbiddenError("Admin access required to create agent");
+      }
+      accountId = callerAccountId;
+    }
+
+    const result = await createAgent(
+      {
+        // Bind each method explicitly rather than spreading `agentService`:
+        // in production this is a real AgentService instance whose methods
+        // live on the prototype, and object spread copies only own
+        // enumerable properties — it would silently drop
+        // create/delete/updateFields/runTransaction and throw at the first
+        // call. Mirrors admin-ui.ts's POST /admin/agents wiring exactly.
+        agentService: {
+          create: agentService.create.bind(agentService),
+          delete: agentService.delete.bind(agentService),
+          updateFields: agentService.updateFields.bind(agentService),
+          runTransaction: agentService.runTransaction.bind(agentService),
+        },
+        agentToolService,
+        agentPluginService,
+        agentMemberService,
+        agentEnvService,
+        agentCronJobService,
+        provisioner,
+        specialtyRegistry,
+        anthropicFederationEnabled: deps.anthropicFederationEnabled,
+      },
+      {
+        name: body.name,
+        typeName:
+          accountId !== undefined ? getSelfServeSpecialty() : body.typeName,
+        ...(accountId !== undefined ? { accountId } : {}),
+        // PAI-1.2: owner comes from the authenticated caller only; the body
+        // schema has no owner field, so a client-supplied one is stripped.
+        ownerEmail: resolveOwnerEmail(c.get("callerEmail"), c.get("caller")),
+        runtime: body.runtime,
+        reposRaw: body.reposRaw,
+        authorAllowlistRaw: body.authorAllowlistRaw,
+        patchAuthorAllowlistRaw: body.patchAuthorAllowlistRaw,
+        memberEmailsRaw: body.memberEmailsRaw,
+        restrictSlackToMembersRaw: body.restrictSlackToMembersRaw,
+        claudeCodeOauthToken: body.claudeCodeOauthToken,
+        anthropicApiKey: body.anthropicApiKey,
+      },
+    );
+
+    if (!result.ok) {
+      // createAgent()'s transactional design guarantees zero rows persist on
+      // any of these failure codes — no partial-success 200, no redundant
+      // cleanup needed here.
+      if (isAccountCreateErrorCode(result.errorCode)) {
+        throw new ForbiddenError(
+          ACCOUNT_CREATE_ERROR_MESSAGES[result.errorCode],
+        );
+      }
+      if (result.errorCode === ANTHROPIC_CREDENTIALS_BLOCKED_CODE) {
+        throw new AnthropicCredentialsBlockedError([
+          ...(body.claudeCodeOauthToken ? ["CLAUDE_CODE_OAUTH_TOKEN"] : []),
+          ...(body.anthropicApiKey ? ["ANTHROPIC_API_KEY"] : []),
+        ]);
+      }
+      throw new BadRequestError(
+        result.errorMessage ?? `create agent failed: ${result.errorCode}`,
+      );
+    }
+
+    return c.json(serializeAgent(result.agent), 200);
+  });
+
+  // ─── Env vars ──────────────────────────────────────────────────────────────
+
+  // POST /agents/:id/envs — replace all env vars (bulk upsert)
+  app.openapi(upsertEnvsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    await agentEnvService.upsert(agentId, body);
+    return c.json({ ok: true } as const, 201);
+  });
+
+  // GET /agents/:id/envs — get all env vars (decrypted, secret values masked)
+  app.openapi(getEnvsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const result = await agentEnvService.getByAgentId(agentId);
+    return c.json(
+      { env: result?.env ?? {}, secretKeys: result?.secretKeys ?? [] },
+      200,
+    );
+  });
+
+  // PATCH /agents/:id/envs — update specific keys (without replacing all)
+  app.openapi(patchEnvsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const { env, secretKeys } = c.req.valid("json");
+    await agentEnvService.patch(
+      agentId,
+      env,
+      secretKeys ? new Set(secretKeys) : undefined,
+    );
+    return c.json({ ok: true } as const, 200);
+  });
+
+  // DELETE /agents/:id/envs/:key — delete a single key
+  app.openapi(deleteEnvKeyRoute, async (c) => {
+    const { id: agentId, key } = c.req.valid("param");
+    await agentEnvService.deleteKey(agentId, key);
+    return c.body(null, 204);
+  });
+
+  // ─── Cron jobs ─────────────────────────────────────────────────────────────
+
+  // POST /agents/:id/crons — create a cron job
+  app.openapi(createCronRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const cron = await agentCronJobService.create(agentId, body);
+    return c.json({ cron: serializeCron(cron) }, 201);
+  });
+
+  // POST /agents/:id/crons/reconcile — static path must precede /:cronId routes
+  app.openapi(reconcileCronsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const result = await agentCronJobService.reconcileSystemCrons(agentId);
+    return c.json(result, 200);
+  });
+
+  // PATCH /agents/:id/crons/:cronId — update a cron job
+  //
+  // schedule and prompt must be provided together (content update).
+  // enabled and preCheck are orthogonal — each may be sent alone or combined
+  // with a content update or with each other. Empty body returns 400.
+  // System crons (system: true) reject schedule/prompt/preCheck changes with
+  // 403, but an enabled-only body is allowed through to setEnabled().
+  // These are business-logic checks (not schema-level), so they remain manual.
+  app.openapi(patchCronRoute, async (c) => {
+    const { id: agentId, cronId } = c.req.valid("param");
+    const body = c.req.valid("json");
+
+    const hasSchedule = body.schedule != null;
+    const hasPrompt = body.prompt != null;
+    const hasEnabled = body.enabled !== undefined;
+    const hasPreCheck = body.preCheck !== undefined;
+
+    if (!hasSchedule && !hasPrompt && !hasEnabled && !hasPreCheck) {
+      throw new BadRequestError(
+        "provide at least one field: schedule+prompt, enabled, or preCheck",
+      );
+    }
+    if (hasSchedule !== hasPrompt) {
+      throw new BadRequestError(
+        "schedule and prompt must be provided together",
+      );
+    }
+
+    const existing = await agentCronJobService.get(agentId, cronId);
+    if (existing.system && (hasSchedule || hasPrompt || hasPreCheck)) {
+      throw new ForbiddenError(
+        "system crons cannot have schedule, prompt, or preCheck updated",
+      );
+    }
+
+    let cron: Awaited<ReturnType<AgentCronJobService["update"]>> | undefined;
+    if (hasSchedule && hasPrompt) {
+      // Content update — preCheck and enabled are folded into update()
+      cron = await agentCronJobService.update(agentId, cronId, {
+        schedule: body.schedule as string,
+        prompt: body.prompt as string,
+        channel: body.channel,
+        user: body.user,
+        silent: body.silent,
+        preCheck: body.preCheck,
+        enabled: body.enabled,
+      });
+    } else {
+      // Orthogonal-field-only update — apply each independently
+      if (hasPreCheck) {
+        cron = await agentCronJobService.updatePreCheck(
+          agentId,
+          cronId,
+          body.preCheck as string | null,
+        );
+      }
+      if (hasEnabled) {
+        cron = await agentCronJobService.setEnabled(
+          agentId,
+          cronId,
+          body.enabled as boolean,
+        );
+      }
+      // When both ran, fetch final state so the response reflects all writes.
+      if (hasPreCheck && hasEnabled) {
+        cron = await agentCronJobService.get(agentId, cronId);
+      }
+    }
+
+    // Narrowing: cron is always set here since at least one update ran (guarded
+    // above), but TypeScript cannot prove it through the disjoint if-blocks.
+    if (cron === undefined) {
+      throw new BadRequestError(
+        "provide at least one field: schedule+prompt, enabled, or preCheck",
+      );
+    }
+
+    return c.json({ cron: serializeCron(cron) }, 200);
+  });
+
+  // DELETE /agents/:id/crons/:cronId — delete a cron job
+  app.openapi(deleteCronRoute, async (c) => {
+    const { id: agentId, cronId } = c.req.valid("param");
+    const cron = await agentCronJobService.get(agentId, cronId);
+    if (cron.system) {
+      throw new ForbiddenError("system crons cannot be deleted");
+    }
+    await agentCronJobService.delete(agentId, cronId);
+    return c.body(null, 204);
+  });
+
+  // GET /agents/:id/crons — list cron jobs with run summary
+  app.openapi(listCronsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const jobs = await agentCronJobService.listWithRunSummary(agentId);
+    return c.json({ crons: jobs.map(serializeCronWithSummary) }, 200);
+  });
+
+  // POST /agents/:id/crons/:cronId/runs — create a cron run record
+  // Static path /runs suffix must follow the :cronId param routes
+  app.openapi(createCronRunRoute, async (c) => {
+    const { id: agentId, cronId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const run = await agentCronRunService.create(cronId, agentId, {
+      startedAt: new Date(body.startedAt),
+      completedAt: body.completedAt ? new Date(body.completedAt) : null,
+      skipped: body.skipped,
+      skipReason: body.skipReason,
+      outcome: body.outcome,
+      error: body.error,
+      phaseId: body.phaseId,
+      itemType: body.itemType,
+      itemId: body.itemId,
+      commandVariant: body.commandVariant,
+    });
+    return c.json({ run: serializeCronRun(run) }, 201);
+  });
+
+  // GET /agents/:id/crons/:cronId/runs — list cron runs (paginated)
+  app.openapi(listCronRunsRoute, async (c) => {
+    const { id: agentId, cronId } = c.req.valid("param");
+    const { limit, offset, itemId, phaseId } = c.req.valid("query");
+    const result = await agentCronRunService.list(cronId, agentId, {
+      limit,
+      offset,
+      itemId,
+      phaseId,
+    });
+    return c.json(
+      {
+        items: result.items.map(serializeCronRun),
+        total: result.total,
+        limit: result.limit,
+        offset: result.offset,
+      },
+      200,
+    );
+  });
+
+  // PATCH /agents/:id/crons/:cronId/runs/:runId — update a cron run record
+  app.openapi(patchCronRunRoute, async (c) => {
+    const { id: agentId, cronId, runId } = c.req.valid("param");
+    const body = c.req.valid("json");
+
+    // At least one field must be provided
+    if (Object.keys(body).length === 0) {
+      throw new BadRequestError("provide at least one field to update");
+    }
+
+    const run = await agentCronRunService.patch(runId, agentId, cronId, {
+      ...(body.completedAt !== undefined && {
+        completedAt: body.completedAt ? new Date(body.completedAt) : null,
+      }),
+      ...(body.outcome !== undefined && { outcome: body.outcome }),
+      ...(body.error !== undefined && { error: body.error }),
+      ...(body.skipped !== undefined && { skipped: body.skipped }),
+      ...(body.skipReason !== undefined && { skipReason: body.skipReason }),
+      ...(body.inputTokens !== undefined && { inputTokens: body.inputTokens }),
+      ...(body.outputTokens !== undefined && {
+        outputTokens: body.outputTokens,
+      }),
+      ...(body.cacheReadTokens !== undefined && {
+        cacheReadTokens: body.cacheReadTokens,
+      }),
+      ...(body.cacheCreationTokens !== undefined && {
+        cacheCreationTokens: body.cacheCreationTokens,
+      }),
+      ...(body.sessionId !== undefined && { sessionId: body.sessionId }),
+      ...(body.lastHeartbeatAt !== undefined && {
+        lastHeartbeatAt: body.lastHeartbeatAt
+          ? new Date(body.lastHeartbeatAt)
+          : null,
+      }),
+      ...(body.modelBreakdown !== undefined && {
+        modelBreakdown: body.modelBreakdown,
+      }),
+      ...(body.contextBaseline !== undefined && {
+        contextBaseline: body.contextBaseline,
+      }),
+      ...(body.turns !== undefined && { turns: body.turns }),
+      ...(body.toolCalls !== undefined && { toolCalls: body.toolCalls }),
+      ...(body.contextFingerprint !== undefined && {
+        contextFingerprint: body.contextFingerprint,
+      }),
+      ...(body.pluginVersion !== undefined && {
+        pluginVersion: body.pluginVersion,
+      }),
+      ...(body.claudeCodeVersion !== undefined && {
+        claudeCodeVersion: body.claudeCodeVersion,
+      }),
+      ...(body.skillUsage !== undefined && { skillUsage: body.skillUsage }),
+    });
+
+    return c.json({ run: serializeCronRun(run) }, 200);
+  });
+
+  // ─── Tools ─────────────────────────────────────────────────────────────────
+
+  // POST /agents/:id/tools — add a tool pattern
+  app.openapi(createToolRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const tool = await agentToolService.add(agentId, body.pattern);
+    return c.json({ tool: serializeTool(tool) }, 201);
+  });
+
+  // GET /agents/:id/tools — list tool patterns
+  app.openapi(listToolsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const tools = await agentToolService.list(agentId);
+    return c.json({ tools: tools.map(serializeTool) }, 200);
+  });
+
+  // PATCH /agents/:id/tools/:toolId — enable or disable a tool pattern
+  app.openapi(patchToolRoute, async (c) => {
+    const { id: agentId, toolId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const tool = await agentToolService.toggle(agentId, toolId, body.enabled);
+    return c.json({ tool: serializeTool(tool) }, 200);
+  });
+
+  // DELETE /agents/:id/tools/:toolId — remove a tool pattern
+  app.openapi(deleteToolRoute, async (c) => {
+    const { id: agentId, toolId } = c.req.valid("param");
+    await agentToolService.remove(agentId, toolId);
+    return c.body(null, 204);
+  });
+
+  // ─── Tokens ────────────────────────────────────────────────────────────────
+
+  // POST /agents/:id/tokens — create a token (returns raw once)
+  app.openapi(createTokenRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const { token, rawToken } = await agentTokenService.create(
+      agentId,
+      body?.label,
+    );
+    // Return the token record (without the hashed token value) + rawToken
+    const { token: _hash, ...tokenMeta } = token;
+    return c.json(
+      {
+        token: {
+          ...tokenMeta,
+          createdAt: tokenMeta.createdAt.toISOString(),
+          revokedAt: tokenMeta.revokedAt
+            ? tokenMeta.revokedAt.toISOString()
+            : null,
+        },
+        rawToken,
+      },
+      201,
+    );
+  });
+
+  // GET /agents/:id/tokens — list tokens (hash metadata only)
+  app.openapi(listTokensRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const records = await agentTokenService.listForAgent(agentId);
+    // Never expose the stored hash — return only metadata
+    const tokens = records.map(({ token: _hash, ...meta }) => ({
+      ...meta,
+      createdAt: meta.createdAt.toISOString(),
+      revokedAt: meta.revokedAt ? meta.revokedAt.toISOString() : null,
+    }));
+    return c.json({ tokens }, 200);
+  });
+
+  // DELETE /agents/:id/tokens/:tokenId — revoke a token
+  app.openapi(deleteTokenRoute, async (c) => {
+    const { tokenId } = c.req.valid("param");
+    await agentTokenService.revoke(tokenId);
+    return c.body(null, 204);
+  });
+
+  // ─── Chat credentials ──────────────────────────────────────────────────────
+
+  // Shared gate: flag (404 when off) → caller (`*` / platform.ops only, never
+  // an agent's own key) → client wired (503). Returns the client.
+  const chatCredentialClient = (c: {
+    get: (k: "isAdmin" | "scope") => unknown;
+  }) => {
+    if (!deps.chatCredentialsEnabled) throw new NotFoundError();
+    const kind = (c.get("scope") as AdminScope | undefined)?.kind;
+    if (c.get("isAdmin") !== true && kind !== "platform-ops") {
+      throw new ForbiddenError(
+        "Only * and platform.ops callers can manage chat credentials",
+      );
+    }
+    return deps.chatCredentials ?? null;
+  };
+  const chatCredentialsUnavailable = { error: "Chat service not configured" };
+
+  // POST /agents/:id/chat-credentials — mint a chat token scoped to the agent
+  app.openapi(createChatCredentialRoute, async (c) => {
+    const client = chatCredentialClient(c);
+    if (!client) return c.json(chatCredentialsUnavailable, 503);
+    const { id: agentId } = c.req.valid("param");
+    const { label } = c.req.valid("json");
+    if (!(await agentService.exists(agentId))) {
+      throw new NotFoundError(`agent ${agentId} not found`);
+    }
+    const { id: tokenId, rawToken } = await client.mintToken(label, agentId);
+    // Never log rawToken.
+    console.log(
+      JSON.stringify({
+        event: "chat-credential.mint",
+        agentId,
+        tokenId,
+        label,
+        callerLabel: callerLabel(c.get("caller"), c.get("scope")?.kind),
+      }),
+    );
+    return c.json({ tokenId, rawToken, label, agentId }, 201);
+  });
+
+  // GET /agents/:id/chat-credentials — list (no raw values)
+  app.openapi(listChatCredentialsRoute, async (c) => {
+    const client = chatCredentialClient(c);
+    if (!client) return c.json(chatCredentialsUnavailable, 503);
+    const { id: agentId } = c.req.valid("param");
+    const tokens = await client.listTokensForAgent(agentId);
+    return c.json(
+      {
+        credentials: tokens.map((t) => ({
+          tokenId: t.id,
+          label: t.label ?? null,
+          agentId,
+        })),
+      },
+      200,
+    );
+  });
+
+  // DELETE /agents/:id/chat-credentials/:tokenId — revoke
+  app.openapi(deleteChatCredentialRoute, async (c) => {
+    const client = chatCredentialClient(c);
+    if (!client) return c.json(chatCredentialsUnavailable, 503);
+    const { id: agentId, tokenId } = c.req.valid("param");
+    // Only tokens scoped to this agent may be revoked through its path.
+    const tokens = await client.listTokensForAgent(agentId);
+    const token = tokens.find((t) => t.id === tokenId);
+    if (!token) {
+      throw new NotFoundError(
+        `chat credential ${tokenId} not found for agent ${agentId}`,
+      );
+    }
+    await client.revokeToken(tokenId);
+    console.log(
+      JSON.stringify({
+        event: "chat-credential.revoke",
+        agentId,
+        tokenId,
+        label: token.label ?? null,
+        callerLabel: callerLabel(c.get("caller"), c.get("scope")?.kind),
+      }),
+    );
+    return c.body(null, 204);
+  });
+
+  // ─── Agent ask (COS-31.1) ─────────────────────────────────────────────────
+
+  registerAgentAskRoutes(app, {
+    agentAsk: deps.agentAsk,
+    chatClient: deps.chatClient,
+    agentService,
+  });
+
+  // ─── Plugins ───────────────────────────────────────────────────────────────
+
+  // POST /agents/:id/plugins — add a plugin
+  app.openapi(createPluginRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const plugin = await agentPluginService.add(
+      agentId,
+      body.name,
+      body.version,
+    );
+    return c.json({ plugin: serializePlugin(plugin) }, 201);
+  });
+
+  // GET /agents/:id/plugins — list plugins
+  app.openapi(listPluginsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const plugins = await agentPluginService.list(agentId);
+    return c.json({ plugins: plugins.map(serializePlugin) }, 200);
+  });
+
+  // PATCH /agents/:id/plugins?name=<name> — update plugin version (re-upsert)
+  // Uses a query param rather than a path segment because a canonical spec like
+  // "my-plugin@org/my-marketplace" can contain a literal "/" that breaks path
+  // matching. The name param is validated by Zod (PluginNameQuerySchema).
+  app.openapi(patchPluginRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const { name } = c.req.valid("query");
+    const body = c.req.valid("json");
+    const plugin = await agentPluginService.add(agentId, name, body.version);
+    return c.json({ plugin: serializePlugin(plugin) }, 200);
+  });
+
+  // DELETE /agents/:id/plugins?name=<name> — remove a plugin by name
+  app.openapi(deletePluginRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const { name } = c.req.valid("query");
+    await agentPluginService.removeByName(agentId, name);
+    return c.body(null, 204);
+  });
+
+  // ─── Cron-run token stats ──────────────────────────────────────────────────
+
+  // GET /agents/all/cron-runs/stats — aggregated token stats across all agents
+  // Static path "all" must be registered before any /:id routes to prevent
+  // the literal "all" being matched as an agentId.
+  app.openapi(cronRunTokenStatsRoute, async (c) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can access cross-agent stats",
+      );
+    }
+    const { from, to } = c.req.valid("query");
+    const stats = await agentCronRunStatsService.query(from, to);
+    return c.json(stats, 200);
+  });
+
+  // GET /agents/all/cron-runs/outcomes — per-(phase, contextFingerprint) outcomes
+  app.openapi(cronRunOutcomesRoute, async (c) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can access cross-agent stats",
+      );
+    }
+    const { from, to } = c.req.valid("query");
+    const outcomes = await agentCronRunStatsService.outcomes(from, to);
+    return c.json(outcomes, 200);
+  });
+
+  // GET /agents/:id/cron-runs/stats — self-serve stats for one agent. Auth is the
+  // generic agentId-match middleware (api-auth.ts); registered after the static
+  // /agents/all/... routes so it cannot swallow them.
+  app.openapi(agentCronRunTokenStatsRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const { from, to } = c.req.valid("query");
+    const stats = await agentCronRunStatsService.query(from, to, id);
+    return c.json(stats, 200);
+  });
+
+  // GET /agents/:id/cron-runs/outcomes — self-serve outcomes for one agent. Auth is
+  // the generic agentId-match middleware (api-auth.ts); registered after the
+  // static /agents/all/... routes so it cannot swallow them.
+  app.openapi(agentCronRunOutcomesRoute, async (c) => {
+    const { id } = c.req.valid("param");
+    const { from, to } = c.req.valid("query");
+    const outcomes = await agentCronRunStatsService.outcomes(from, to, id);
+    return c.json(outcomes, 200);
+  });
+
+  // GET /agents/chat-tokens/daily/stats — aggregated daily chat token stats
+  // Static path "chat-tokens" must be registered before any /:id routes to
+  // prevent "chat-tokens" from being matched as an agentId.
+  app.openapi(chatTokenDailyStatsRoute, async (c) => {
+    if (c.get("isAdmin") !== true) {
+      throw new ForbiddenError(
+        "Only admin bearers and session users can access cross-agent stats",
+      );
+    }
+    const { from, to } = c.req.valid("query");
+    const stats = await agentChatTokenService.queryStats(from, to);
+    return c.json(stats, 200);
+  });
+
+  // GET /agents/{id}/chat-tokens/daily/stats — same stats scoped to one agent.
+  // No isAdmin check: the generic agent-route auth middleware already rejects
+  // a bearer whose agentId doesn't match the path. Registered after the static
+  // /agents/chat-tokens/... route above.
+  app.openapi(selfChatTokenDailyStatsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const { from, to } = c.req.valid("query");
+    const stats = await agentChatTokenService.queryStats(from, to, agentId);
+    return c.json(stats, 200);
+  });
+
+  // ─── Chat token usage ──────────────────────────────────────────────────────
+
+  // POST /agents/:id/chat-tokens/daily — atomically accumulate daily chat token usage per model
+  app.openapi(upsertChatTokenDailyRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const rows = await Promise.all(
+      body.modelBreakdown.map((entry) =>
+        agentChatTokenService.upsertDailyByModel(
+          agentId,
+          body.date,
+          entry.model,
+          {
+            inputTokens: entry.inputTokens,
+            outputTokens: entry.outputTokens,
+            cacheReadTokens: entry.cacheReadTokens,
+            cacheCreationTokens: entry.cacheCreationTokens,
+            costUsd: entry.costUsd,
+          },
+        ),
+      ),
+    );
+    return c.json(rows.map(serializeChatTokenDaily), 200);
+  });
+
+  // ─── GitHub installations snapshot ─────────────────────────────────────────
+
+  // PUT /agents/:id/github-installations — replace-all upsert of the single row
+  app.openapi(putGitHubInstallationsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const body = c.req.valid("json");
+    const snapshot = await agentGitHubInstallationsService.push(agentId, {
+      reportedAt: new Date(body.reportedAt),
+      installations: body.installations,
+    });
+    return c.json(
+      { snapshot: serializeGitHubInstallationsSnapshot(snapshot) },
+      200,
+    );
+  });
+
+  // GET /agents/:id/github-installations — latest snapshot, 404 if none yet
+  app.openapi(getGitHubInstallationsRoute, async (c) => {
+    const { id: agentId } = c.req.valid("param");
+    const snapshot = await agentGitHubInstallationsService.get(agentId);
+    if (!snapshot) {
+      throw new NotFoundError(
+        `no github-installations snapshot for agent ${agentId}`,
+      );
+    }
+    return c.json(
+      { snapshot: serializeGitHubInstallationsSnapshot(snapshot) },
+      200,
+    );
+  });
+
+  return app;
+}
+
+// ─── Serializers ────────────────────────────────────────────────────────────────
+//
+// Prisma returns Date objects; the Zod response schemas expect ISO strings.
+// These helpers normalize date fields so c.json() output matches the schema.
+
+function serializeCron(cron: {
+  createdAt: Date;
+  updatedAt: Date;
+  [k: string]: unknown;
+}): z.infer<typeof AgentCronJobSchema> {
+  return {
+    ...cron,
+    createdAt: cron.createdAt.toISOString(),
+    updatedAt: cron.updatedAt.toISOString(),
+  } as z.infer<typeof AgentCronJobSchema>;
+}
+
+function serializeCronWithSummary(job: AgentCronJobWithRunSummary): z.infer<
+  typeof AgentCronJobSchema
+> & {
+  lastRun: {
+    startedAt: string;
+    completedAt: string | null;
+    skipped: boolean;
+    outcome: string | null;
+  } | null;
+  runCountToday: number;
+} {
+  return {
+    id: job.id,
+    agentId: job.agentId,
+    schedule: job.schedule,
+    prompt: job.prompt,
+    channel: job.channel,
+    user: job.user,
+    silent: job.silent,
+    enabled: job.enabled,
+    preCheck: job.preCheck,
+    name: job.name,
+    system: job.system,
+    parentCronId: job.parentCronId,
+    createdAt: job.createdAt.toISOString(),
+    updatedAt: job.updatedAt.toISOString(),
+    lastRun: job.lastRun
+      ? {
+          startedAt: job.lastRun.startedAt.toISOString(),
+          completedAt: job.lastRun.completedAt
+            ? job.lastRun.completedAt.toISOString()
+            : null,
+          skipped: job.lastRun.skipped,
+          outcome: job.lastRun.outcome,
+        }
+      : null,
+    runCountToday: job.runCountToday,
+  } as ReturnType<typeof serializeCronWithSummary>;
+}
+
+function serializeCronRun(run: {
+  id: string;
+  cronId: string;
+  agentId: string;
+  startedAt: Date;
+  completedAt: Date | null;
+  skipped: boolean;
+  skipReason: string | null;
+  outcome: string | null;
+  error: string | null;
+  phaseId: string | null;
+  itemType: string | null;
+  itemId: string | null;
+  commandVariant: string | null;
+  sessionId: string | null;
+  lastHeartbeatAt: Date | null;
+  createdAt: Date;
+  modelBreakdown?: ModelBreakdownEntry[];
+  baselineModel?: string | null;
+  baselineContextTokens?: number | null;
+  baselineInputTokens?: number | null;
+  baselineCacheCreationTokens?: number | null;
+  baselineCacheReadTokens?: number | null;
+  turns?: number | null;
+  toolCalls?: number | null;
+  contextFingerprint?: string | null;
+  pluginVersion?: string | null;
+  claudeCodeVersion?: string | null;
+}): z.infer<typeof AgentCronRunSchema> {
+  // The baseline is reported as one object; null unless every column is set
+  // (an older agent build, or a resumed session, leaves them all null).
+  const contextBaseline =
+    run.baselineModel != null &&
+    run.baselineContextTokens != null &&
+    run.baselineInputTokens != null &&
+    run.baselineCacheCreationTokens != null &&
+    run.baselineCacheReadTokens != null
+      ? {
+          model: run.baselineModel,
+          contextTokens: run.baselineContextTokens,
+          inputTokens: run.baselineInputTokens,
+          cacheCreationTokens: run.baselineCacheCreationTokens,
+          cacheReadTokens: run.baselineCacheReadTokens,
+        }
+      : null;
+  // Token totals are no longer columns on AgentCronRun — they're summed from
+  // the per-model breakdown, the sole source of truth post-consolidation.
+  // A run with no breakdown rows reports null (unknown), not zero.
+  const breakdown = run.modelBreakdown ?? [];
+  const tokenTotals =
+    breakdown.length === 0
+      ? {
+          inputTokens: null,
+          outputTokens: null,
+          cacheReadTokens: null,
+          cacheCreationTokens: null,
+        }
+      : {
+          inputTokens: breakdown.reduce((sum, m) => sum + m.inputTokens, 0),
+          outputTokens: breakdown.reduce((sum, m) => sum + m.outputTokens, 0),
+          cacheReadTokens: breakdown.reduce(
+            (sum, m) => sum + m.cacheReadTokens,
+            0,
+          ),
+          cacheCreationTokens: breakdown.reduce(
+            (sum, m) => sum + m.cacheCreationTokens,
+            0,
+          ),
+        };
+
+  return {
+    id: run.id,
+    cronId: run.cronId,
+    agentId: run.agentId,
+    startedAt: run.startedAt.toISOString(),
+    completedAt: run.completedAt ? run.completedAt.toISOString() : null,
+    skipped: run.skipped,
+    skipReason: run.skipReason,
+    outcome: run.outcome,
+    error: run.error,
+    phaseId: run.phaseId,
+    itemType: run.itemType,
+    itemId: run.itemId,
+    commandVariant: run.commandVariant,
+    sessionId: run.sessionId,
+    lastHeartbeatAt: run.lastHeartbeatAt
+      ? run.lastHeartbeatAt.toISOString()
+      : null,
+    ...tokenTotals,
+    createdAt: run.createdAt.toISOString(),
+    contextBaseline,
+    turns: run.turns ?? null,
+    toolCalls: run.toolCalls ?? null,
+    contextFingerprint: run.contextFingerprint ?? null,
+    pluginVersion: run.pluginVersion ?? null,
+    claudeCodeVersion: run.claudeCodeVersion ?? null,
+    ...(run.modelBreakdown !== undefined && {
+      modelBreakdown: run.modelBreakdown.map((entry) => ({
+        model: entry.model,
+        inputTokens: entry.inputTokens,
+        outputTokens: entry.outputTokens,
+        cacheReadTokens: entry.cacheReadTokens,
+        cacheCreationTokens: entry.cacheCreationTokens,
+        costUsd: entry.costUsd,
+      })),
+    }),
+  };
+}
+
+function serializeTool(tool: {
+  createdAt: Date;
+  [k: string]: unknown;
+}): z.infer<typeof AgentToolSchema> {
+  return {
+    ...tool,
+    createdAt: tool.createdAt.toISOString(),
+  } as z.infer<typeof AgentToolSchema>;
+}
+
+function serializePlugin(plugin: {
+  createdAt: Date;
+  updatedAt: Date;
+  [k: string]: unknown;
+}): z.infer<typeof AgentPluginSchema> {
+  return {
+    ...plugin,
+    createdAt: plugin.createdAt.toISOString(),
+    updatedAt: plugin.updatedAt.toISOString(),
+  } as z.infer<typeof AgentPluginSchema>;
+}
+
+function serializeAgent(
+  agent: {
+    id: string;
+    name: string;
+    slackId: string | null | undefined;
+    selfHosted: boolean;
+    repos?: string[];
+    reviewAuthorAllowlist?: string[];
+    patchAuthorAllowlist?: string[];
+    restrictSlackToMembers?: boolean;
+    typeName: string;
+    accountId?: string | null;
+    createdAt: Date;
+    updatedAt: Date;
+    missingRequiredEnv?: string[];
+    trialExpiresAt?: Date | null;
+    trialExpiryWarnedAt?: Date | null;
+    autoPostReviews?: boolean;
+    allowSelfReview?: boolean;
+    minConfidence?: number;
+    maxFindings?: number;
+    cleanupMergedWorktrees?: boolean;
+    cleanupAfterDays?: number;
+    ownerEmail?: string | null;
+    anthropicIdentityName?: string | null;
+    anthropicServiceAccountId?: string | null;
+    anthropicFederationRuleId?: string | null;
+  },
+  warning?: string,
+): z.infer<typeof GetAgentResultSchema> {
+  return {
+    id: agent.id,
+    name: agent.name,
+    slackId: agent.slackId,
+    selfHosted: agent.selfHosted,
+    repos: agent.repos ?? [],
+    reviewAuthorAllowlist: agent.reviewAuthorAllowlist ?? [],
+    patchAuthorAllowlist: agent.patchAuthorAllowlist ?? [],
+    restrictSlackToMembers: agent.restrictSlackToMembers ?? false,
+    typeName: agent.typeName,
+    accountId: agent.accountId ?? null,
+    createdAt: agent.createdAt.toISOString(),
+    updatedAt: agent.updatedAt.toISOString(),
+    missingRequiredEnv: agent.missingRequiredEnv ?? [],
+    trialExpiresAt: agent.trialExpiresAt
+      ? agent.trialExpiresAt.toISOString()
+      : null,
+    trialExpiryWarnedAt: agent.trialExpiryWarnedAt
+      ? agent.trialExpiryWarnedAt.toISOString()
+      : null,
+    autoPostReviews: agent.autoPostReviews ?? true,
+    allowSelfReview: agent.allowSelfReview ?? false,
+    minConfidence: agent.minConfidence ?? 75,
+    maxFindings: agent.maxFindings ?? 5,
+    cleanupMergedWorktrees: agent.cleanupMergedWorktrees ?? true,
+    cleanupAfterDays: agent.cleanupAfterDays ?? 14,
+    ownerEmail: agent.ownerEmail ?? null,
+    anthropicIdentityName: agent.anthropicIdentityName ?? null,
+    anthropicServiceAccountId: agent.anthropicServiceAccountId ?? null,
+    anthropicFederationRuleId: agent.anthropicFederationRuleId ?? null,
+    ...(warning !== undefined ? { warning } : {}),
+  };
+}
+
+/**
+ * Computes the non-blocking "no members" warning surfaced when
+ * restrictSlackToMembers is true on an agent with zero AgentMember rows.
+ * Never blocks the create/update it's called after — callers await this
+ * strictly to enrich the response, not to gate persistence. Returns
+ * undefined (no warning) when the flag is false or the agent has at least
+ * one member.
+ */
+async function computeRestrictSlackToMembersWarning(
+  agentMemberService: Pick<AgentMemberService, "listByAgentId">,
+  agentId: string,
+  restrictSlackToMembers: boolean,
+): Promise<string | undefined> {
+  if (!restrictSlackToMembers) return undefined;
+  const members = await agentMemberService.listByAgentId(agentId);
+  if (members.length > 0) return undefined;
+  return "this agent has no members — enabling this will block all Slack senders";
+}
+
+function serializeGitHubInstallationsSnapshot(snapshot: {
+  id: string;
+  agentId: string;
+  reportedAt: Date;
+  installations: unknown;
+  createdAt: Date;
+}): z.infer<typeof AgentGitHubInstallationsSnapshotSchema> {
+  return {
+    id: snapshot.id,
+    agentId: snapshot.agentId,
+    reportedAt: snapshot.reportedAt.toISOString(),
+    installations: snapshot.installations as z.infer<
+      typeof AgentGitHubInstallationsSnapshotSchema
+    >["installations"],
+    createdAt: snapshot.createdAt.toISOString(),
+  };
+}
+
+function serializeChatTokenDaily(row: {
+  id: string;
+  agentId: string;
+  date: string;
+  model: string;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheCreationTokens: number;
+  costUsd: number;
+  createdAt: Date;
+  updatedAt: Date;
+}): z.infer<typeof AgentChatTokenUsageDailySchema> {
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    date: row.date,
+    model: row.model,
+    inputTokens: row.inputTokens,
+    outputTokens: row.outputTokens,
+    cacheReadTokens: row.cacheReadTokens,
+    cacheCreationTokens: row.cacheCreationTokens,
+    costUsd: row.costUsd,
+    createdAt: row.createdAt.toISOString(),
+    updatedAt: row.updatedAt.toISOString(),
+  };
+}