@desplega.ai/agent-swarm 2.5.3 → 2.6.0

package/src/http/api-keys.ts

@@ -10,6 +10,7 @@ import {
   recordKeyRateLimitWindows,
   recordKeySeatMismatch,
   recordKeyUsage,
+  recordKeyValidation,
   setApiKeyName,
   setApiKeyPlan,
 } from "../be/db";
@@ -79,6 +80,39 @@ const reportRateLimit = route({
   auth: { apiKey: true },
 });
 
+const reportValidation = route({
+  method: "post",
+  path: "/api/keys/report-validation",
+  pattern: ["api", "keys", "report-validation"],
+  summary: "Record live validation results for a credential pool",
+  tags: ["API Keys"],
+  body: z.object({
+    keyType: z.string(),
+    keys: z
+      .array(
+        z.object({
+          keyIndex: z.number().int().min(0),
+          keySuffix: z.string().min(1).max(10),
+          ok: z.boolean(),
+          httpStatus: z.number().int().optional(),
+        }),
+      )
+      .min(1)
+      .max(100),
+    scope: z.string().optional(),
+    scopeId: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Validation recorded", schema: successMessageSchema },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+  rbac: {
+    ungated: "worker credential telemetry, same posture as POST /api/keys/report-rate-limit",
+  },
+});
+
 const reportAuthFailure = route({
   method: "post",
   path: "/api/keys/report-auth-failure",
@@ -223,6 +257,7 @@ const getAvailable = route({
       schema: z.object({
         success: z.literal(true),
         availableIndices: z.array(z.number().int()),
+        rejectedIndices: z.array(z.number().int()).optional(),
         totalKeys: z.number().int(),
         /** Indices excluded only by an active model-scoped window block. Present only when `model` was passed. */
         modelBlockedIndices: z.array(z.number().int()).optional(),
@@ -273,6 +308,8 @@ const ApiKeyStatusSchema = z.object({
   /** Auth failures in a row since the last success or clear. */
   consecutiveAuthFailures: z.number().int(),
   lastAuthFailureAt: z.string().nullable(),
+  lastValidationError: z.string().nullable(),
+  lastValidationFailedAt: z.string().nullable(),
   /** Derived, readable view of any rejected model-scoped window (Fable/Opus/Sonnet) on this key. */
   modelLimits: z.array(
     z.object({
@@ -555,6 +592,21 @@ export async function handleApiKeys(
     return true;
   }
 
+  // POST /api/keys/report-validation
+  if (reportValidation.match(req.method, pathSegments)) {
+    const parsed = await reportValidation.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    const { keyType, keys, scope, scopeId } = parsed.body;
+    try {
+      await recordKeyValidation(keyType, keys, scope, scopeId ?? null);
+      reportValidation.respond(res, 200, { success: true, message: "Key validation recorded" });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to record key validation", 500);
+    }
+    return true;
+  }
+
   // POST /api/keys/report-auth-failure
   if (reportAuthFailure.match(req.method, pathSegments)) {
     const parsed = await reportAuthFailure.parse(req, res, pathSegments, queryParams);
@@ -650,6 +702,7 @@ export async function handleApiKeys(
       getAvailable.respond(res, 200, {
         success: true,
         availableIndices: result.availableIndices,
+        rejectedIndices: result.rejectedIndices,
         totalKeys,
         authFailureFence: result.authFailureFence,
         ...(model !== undefined

package/src/http/assets.ts

@@ -1,6 +1,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { getApp } from "../apps/store";
+import { normalizeAssetKey } from "../assets/key";
+import { sourceMoveError, sourceOfKey } from "../assets/source-key";
 import { auditAssetKeys } from "../be/asset-key-audit";
 import { AssetKeyAuthorizationError, authorizeAssetKeyWrite } from "../be/asset-key-auth";
 import { resolveHttpAuditUserId } from "../be/audit-user";
@@ -15,6 +17,7 @@ import {
   upsertAssetKeyMapping,
 } from "../be/db";
 import { getScriptById } from "../be/scripts/db";
+import { getSessionRoot } from "../be/session-shares";
 import { can, type RbacResource } from "../rbac";
 import {
   type AssetEntityType,
@@ -334,6 +337,18 @@ export async function handleAssets(
         );
         return true;
       }
+      const destination = normalizeAssetKey(parsed.body.key);
+      if (sourceOfKey(destination)) {
+        // The session root's own source key is the only allowed source key
+        // (Undo). A root we cannot load allows none.
+        const rootId = task.parentTaskId ? (await getSessionRoot(task.id))?.id : task.id;
+        const root = rootId === task.id ? task : rootId ? await getTaskById(rootId) : null;
+        const sourceError = sourceMoveError(destination, root ?? { id: task.id });
+        if (sourceError) {
+          jsonError(res, sourceError, 400);
+          return true;
+        }
+      }
       // Only the tasks checked here move: a subtask created after this read stays put.
       const tasks = parsed.body.cascade ? await getRootTaskChain(task.id) : [task];
       for (const target of tasks) {

package/src/http/codex-oauth-accounts.ts

@@ -0,0 +1,191 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { decryptSecret, getEncryptionKey } from "../be/crypto";
+import { deleteKv, deleteSwarmConfigByKey, getDbClient, getKeyStatuses, getKv } from "../be/db";
+import { retirePoolKeyStatus } from "../be/db/api-keys";
+import { deriveCodexKeySuffix } from "../providers/codex-oauth/auth-json";
+import { decodeJwt, extractChatgptPlanType } from "../providers/codex-oauth/flow";
+import { MAX_CODEX_OAUTH_SLOT } from "../providers/codex-oauth/storage";
+import {
+  CODEX_AUTH_FAILURE_BENCH_THRESHOLD,
+  CODEX_AUTH_WATCH_NAMESPACE,
+  codexAuthBenchMarkerKey,
+} from "../utils/codex-auth-failure";
+import { ensureConfigAdmin, requestSecretReadScope, runConfigWriteSideEffects } from "./config";
+import { route } from "./route-def";
+import { jsonError } from "./utils";
+
+export const CodexAccountSchema = z.object({
+  slot: z.number().int().min(0),
+  configKey: z.string(),
+  legacy: z.boolean(),
+  suffix: z.string().nullable(),
+  plan: z.string().nullable(),
+  email: z.string().nullable(),
+  status: z.enum(["ok", "needs_login", "unchecked"]),
+});
+export type CodexAccount = z.infer<typeof CodexAccountSchema>;
+
+export const CodexAccountsResponseSchema = z.object({ accounts: z.array(CodexAccountSchema) });
+export type CodexAccountsResponse = z.infer<typeof CodexAccountsResponseSchema>;
+
+const listAccounts = route({
+  method: "get",
+  path: "/api/codex-oauth/accounts",
+  pattern: ["api", "codex-oauth", "accounts"],
+  summary: "List stored Codex ChatGPT accounts",
+  tags: ["Codex OAuth"],
+  responses: {
+    200: { description: "Stored account metadata", schema: CodexAccountsResponseSchema },
+    403: { description: "Caller cannot read all secrets" },
+  },
+});
+
+const deleteAccount = route({
+  method: "delete",
+  path: "/api/codex-oauth/accounts/{slot}",
+  pattern: ["api", "codex-oauth", "accounts", null],
+  summary: "Remove a stored Codex ChatGPT account",
+  tags: ["Codex OAuth"],
+  rbac: { permission: "config.delete.any" },
+  params: z.object({ slot: z.coerce.number().int().min(0).max(MAX_CODEX_OAUTH_SLOT) }),
+  responses: {
+    200: { description: "Remaining accounts", schema: CodexAccountsResponseSchema },
+    403: { description: "Config administration and permission to read all secrets required" },
+    404: { description: "Account slot does not exist" },
+  },
+});
+
+type AccountRow = { key: string; value: string; encrypted: number };
+
+async function accountRows(): Promise<Array<AccountRow & { slot: number; legacy: boolean }>> {
+  const rows = await getDbClient().query<AccountRow>(
+    "SELECT key, value, encrypted FROM swarm_config WHERE scope = 'global' AND (key = 'codex_oauth' OR key GLOB 'codex_oauth_[0-9]*')",
+  );
+  const hasSlotZero = rows.some((row) => row.key === "codex_oauth_0");
+  return rows
+    .flatMap((row) => {
+      if (row.key === "codex_oauth") {
+        return hasSlotZero ? [] : [{ ...row, slot: 0, legacy: true }];
+      }
+      const match = /^codex_oauth_(0|[1-9]\d*)$/.exec(row.key);
+      if (!match) return [];
+      const slot = Number(match[1]);
+      return slot <= MAX_CODEX_OAUTH_SLOT ? [{ ...row, slot, legacy: false }] : [];
+    })
+    .sort((a, b) => a.slot - b.slot);
+}
+
+const AccountCredentialsSchema = z.object({
+  access: z.string().min(1),
+  refresh: z.string().min(1),
+  expires: z.number().finite(),
+  accountId: z.string().min(1),
+});
+
+function readCredentials(row: AccountRow): z.infer<typeof AccountCredentialsSchema> | null {
+  try {
+    const value = row.encrypted ? decryptSecret(row.value, getEncryptionKey()) : row.value;
+    return AccountCredentialsSchema.parse(JSON.parse(value));
+  } catch {
+    return null;
+  }
+}
+
+function accountSuffix(row: AccountRow): string | null {
+  const credentials = readCredentials(row);
+  return credentials ? deriveCodexKeySuffix(credentials.access, credentials.accountId) : null;
+}
+
+async function accountsResponse(): Promise<CodexAccountsResponse> {
+  const rows = await accountRows();
+  const statuses = await getKeyStatuses("CODEX_OAUTH", "global", null);
+  const accounts: CodexAccount[] = [];
+  for (const row of rows) {
+    const account: CodexAccount = {
+      slot: row.slot,
+      configKey: row.key,
+      legacy: row.legacy,
+      suffix: null,
+      plan: null,
+      email: null,
+      status: "needs_login",
+    };
+    const credentials = readCredentials(row);
+    if (!credentials) {
+      accounts.push(account);
+      continue;
+    }
+    account.suffix = deriveCodexKeySuffix(credentials.access, credentials.accountId);
+    account.plan = extractChatgptPlanType(credentials.access);
+    const profile = decodeJwt(credentials.access)?.["https://api.openai.com/profile"];
+    if (profile && typeof profile === "object" && "email" in profile) {
+      account.email = typeof profile.email === "string" && profile.email ? profile.email : null;
+    }
+    const status = statuses.find((entry) => entry.keySuffix === account.suffix);
+    const marker = await getKv(CODEX_AUTH_WATCH_NAMESPACE, codexAuthBenchMarkerKey(account.suffix));
+    const statusBenched =
+      status &&
+      status.consecutiveAuthFailures >= CODEX_AUTH_FAILURE_BENCH_THRESHOLD &&
+      status.status === "rate_limited";
+    account.status = marker || statusBenched ? "needs_login" : status ? "ok" : "unchecked";
+    accounts.push(account);
+  }
+  return { accounts };
+}
+
+/** Both responses list account emails and plans, so both routes need this gate. */
+async function ensureSecretRead(req: IncomingMessage, res: ServerResponse): Promise<boolean> {
+  if ((await requestSecretReadScope(req)) === "all") return true;
+  jsonError(res, "Reading Codex accounts requires access to all secrets", 403);
+  return false;
+}
+
+export async function handleCodexOAuthAccounts(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listAccounts.match(req.method, pathSegments)) {
+    const parsed = await listAccounts.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureSecretRead(req, res))) return true;
+    listAccounts.respond(res, 200, await accountsResponse());
+    return true;
+  }
+
+  if (deleteAccount.match(req.method, pathSegments)) {
+    const parsed = await deleteAccount.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    if (!(await ensureConfigAdmin(req, res, "config.delete.any"))) return true;
+    if (!(await ensureSecretRead(req, res))) return true;
+    const deletedKey = await getDbClient().transaction(async () => {
+      const rows = await accountRows();
+      const account = rows.find((row) => row.slot === parsed.params.slot);
+      if (!account || !(await deleteSwarmConfigByKey("global", null, account.key))) return null;
+      // A new sign-in takes the first free slot, so it must not inherit this
+      // account's auth bench (keyed by slot) or its bench marker.
+      const suffix = accountSuffix(account);
+      if (suffix) {
+        const remaining = rows.flatMap((row) => {
+          const keySuffix = row === account ? null : accountSuffix(row);
+          return keySuffix ? [{ keySuffix, keyIndex: row.slot }] : [];
+        });
+        await retirePoolKeyStatus("CODEX_OAUTH", suffix, remaining);
+        if (!remaining.some((row) => row.keySuffix === suffix)) {
+          await deleteKv(CODEX_AUTH_WATCH_NAMESPACE, codexAuthBenchMarkerKey(suffix));
+        }
+      }
+      return account.key;
+    });
+    if (deletedKey === null) {
+      jsonError(res, "Codex account slot does not exist", 404);
+      return true;
+    }
+    await runConfigWriteSideEffects("global", deletedKey, "");
+    deleteAccount.respond(res, 200, await accountsResponse());
+    return true;
+  }
+  return false;
+}

package/src/http/comb.ts

@@ -2,7 +2,12 @@ import type { IncomingMessage, ServerResponse } from "node:http";
 import { z } from "zod";
 import { resolveHttpAuditUserId } from "../be/audit-user";
 import { getCombConfig } from "../comb/config";
-import { REVIEW_BATCH_MAX, ReviewBatchError, sendReviewBatch } from "../comb/review-batch";
+import {
+  REVIEW_BATCH_MAX,
+  REVIEW_NOTE_MAX,
+  ReviewBatchError,
+  sendReviewBatch,
+} from "../comb/review-batch";
 import { can } from "../rbac";
 import { TaskCreationBlockedError } from "../tasks/errors";
 import { scrubSecrets } from "../utils/secret-scrubber";
@@ -24,6 +29,12 @@ const resultSchema = z.object({
   skipped: z.array(skippedSchema),
   /** Comments of an earlier send whose missing "sent" reply this batch posted again. */
   repaired: z.array(z.object({ id: z.string(), taskId: z.string() })),
+  /**
+   * With a new task only. `online`: a lead got it. `offline`: every lead is offline,
+   * so the task waits for one. `none`: no lead, so the task waits
+   * unassigned in the pool.
+   */
+  lead: z.enum(["online", "offline", "none"]).optional(),
 });
 
 const batchErrorSchema = z.object({ error: z.string(), skipped: z.array(skippedSchema) });
@@ -41,7 +52,7 @@ const reviewBatchRoute = route({
   pattern: ["api", "comb", "review-batches"],
   summary: "Send agent-fs comments to the swarm as one lead task",
   description:
-    "Comb's 'Send to swarm'. The server reads each comment again from agent-fs with its bootstrap key, skips replies, resolved comments, and comments already sent, and creates ONE task for the lead. Each sent comment gets a `[comb:sent task=<id>]` reply from the swarm service account. A comment is sent at most once. When an earlier send lost its reply, the batch posts that reply again (`repaired`). Answers 404 while COMB_ENABLED is off.",
+    "Comb's 'Send to swarm'. The server reads each comment again from agent-fs with its bootstrap key, skips replies, resolved comments, and comments already sent, and creates ONE task for the lead. Each sent comment gets a `[comb:sent task=<id>]` reply from the swarm service account. A comment is sent at most once. An optional `note` from the sender goes into the task text. When an earlier send lost its reply, the batch posts that reply again (`repaired`). Answers 404 while COMB_ENABLED is off.",
   tags: ["Comb"],
   body: z.object({
     orgId: z.string().min(1),
@@ -54,6 +65,8 @@ const reviewBatchRoute = route({
       .min(1)
       .max(1024)
       .refine(isDrivePath, "scopePath must start with '/' and have no '.' or '..' segment"),
+    /** The sender's note for the lead about the whole batch. */
+    note: z.string().max(REVIEW_NOTE_MAX).optional(),
   }),
   responses: {
     200: {

package/src/http/config.ts

@@ -23,8 +23,9 @@ import {
   isInternalConfigKey,
   validateConfigEntry,
 } from "../be/swarm-config-guard";
+import { isScriptRunToken } from "../be/users";
 import { can, isRbacEnabled, type PermissionVerb } from "../rbac";
-import { SwarmConfigSchema } from "../types";
+import { type SwarmConfig, SwarmConfigSchema } from "../types";
 import { getRequestAuth, type HttpRequestAuth } from "../utils/request-auth-context";
 import { registerVolatileSecret } from "../utils/secret-scrubber";
 import { reloadGlobalConfigsAndIntegrations, scheduleIntegrationsReload } from "./core";
@@ -66,7 +67,7 @@ export function readsRepoSecrets(
   }).allow;
 }
 
-async function requestSecretReadScope(
+export async function requestSecretReadScope(
   req: IncomingMessage,
   resolvedScope?: { agentId?: string; repoId?: string },
 ): Promise<"all" | "self" | "none"> {
@@ -111,6 +112,49 @@ async function resolveSecretsRead(
   };
 }
 
+/**
+ * Ids of the rows a script run's token reads unmasked on its own
+ * `/api/config/resolved` (its agent over global, no repo secrets). The run
+ * already holds these values in `ctx.swarm.config`. `undefined` for any other
+ * caller.
+ */
+async function scriptRunHeldConfigIds(req: IncomingMessage): Promise<Set<string> | undefined> {
+  const auth = getRequestAuth(req);
+  if (auth?.kind !== "agent" || auth.tokenKind !== "agent") return undefined;
+  if (!(await isScriptRunToken(auth.tokenId))) return undefined;
+  const held = stripApiOnlyKeys(
+    await getResolvedConfig(auth.agentId, undefined, { includeRepoSecrets: false }),
+  );
+  return new Set(held.map((config) => config.id));
+}
+
+/**
+ * Mask a raw list or by-id read for this caller. A script run's token gets
+ * the rows it holds (see {@link scriptRunHeldConfigIds}) unmasked, so
+ * `config_list` and `ctx.swarm.config` agree; every other secret row stays
+ * masked. Unmasked secret values are registered with the scrubber.
+ */
+async function maskConfigRead(
+  req: IncomingMessage,
+  configs: SwarmConfig[],
+  includeSecrets: boolean,
+): Promise<{ result: SwarmConfig[]; secretsNote: string }> {
+  const { effectiveIncludeSecrets, secretsNote } = await resolveSecretsRead(req, includeSecrets);
+  const held =
+    includeSecrets && !effectiveIncludeSecrets ? await scriptRunHeldConfigIds(req) : undefined;
+  const reveal = (config: SwarmConfig) => effectiveIncludeSecrets || !!held?.has(config.id);
+  const result = configs.map((config) =>
+    config.isSecret && !reveal(config) ? maskSecrets([config])[0]! : config,
+  );
+  for (const config of result) {
+    if (config.isSecret && config.value && reveal(config)) {
+      registerVolatileSecret(config.value, `config:${config.key}`);
+    }
+  }
+  const anyMasked = result.some((config) => config.isSecret && !reveal(config));
+  return { result, secretsNote: held && !anyMasked ? "" : secretsNote };
+}
+
 /**
  * Gate a config write/delete over HTTP (DES-445 follow-up).
  *
@@ -455,13 +499,9 @@ export async function handleConfig(
       jsonError(res, "Config not found", 404);
       return true;
     }
-    const { effectiveIncludeSecrets, secretsNote } = await resolveSecretsRead(req, includeSecrets);
-    const singleResult = effectiveIncludeSecrets ? config : maskSecrets([config])[0]!;
-    if (effectiveIncludeSecrets && singleResult.isSecret && singleResult.value) {
-      registerVolatileSecret(singleResult.value, `config:${singleResult.key}`);
-    }
+    const { result, secretsNote } = await maskConfigRead(req, [config], includeSecrets);
     getConfigById.respond(res, 200, {
-      ...singleResult,
+      ...result[0]!,
       ...(secretsNote ? { message: `Found 1 config(s).${secretsNote}` } : {}),
     });
     return true;
@@ -471,7 +511,6 @@ export async function handleConfig(
     const parsed = await listConfig.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
     const includeSecrets = parsed.query.includeSecrets === "true";
-    const { effectiveIncludeSecrets, secretsNote } = await resolveSecretsRead(req, includeSecrets);
     const configs = stripApiOnlyKeys(
       await getSwarmConfigs({
         scope: parsed.query.scope || undefined,
@@ -479,14 +518,7 @@ export async function handleConfig(
         key: parsed.query.key,
       }),
     );
-    const listResult = effectiveIncludeSecrets ? configs : maskSecrets(configs);
-    if (effectiveIncludeSecrets) {
-      for (const c of listResult) {
-        if (c.isSecret && c.value) {
-          registerVolatileSecret(c.value, `config:${c.key}`);
-        }
-      }
-    }
+    const { result: listResult, secretsNote } = await maskConfigRead(req, configs, includeSecrets);
     listConfig.respond(res, 200, {
       configs: listResult,
       ...(secretsNote ? { message: `Found ${listResult.length} config(s).${secretsNote}` } : {}),

package/src/http/core.ts

@@ -95,6 +95,12 @@ import {
  */
 const injectedEnvOriginals = new Map<string, { original: string | undefined; injected: string }>();
 
+/** Read the deployment value without a stored config's temporary env injection. */
+export function getDeploymentEnvValue(key: string): string | undefined {
+  const tracked = injectedEnvOriginals.get(key);
+  return tracked && process.env[key] === tracked.injected ? tracked.original : process.env[key];
+}
+
 export async function loadGlobalConfigsIntoEnv(override = false): Promise<string[]> {
   const globalConfigs = await getInjectableGlobalConfigs();
   const updated: string[] = [];

package/src/http/fleet-benchmark.ts

@@ -11,7 +11,7 @@ import {
   localTasksPerWeek,
 } from "../fleet-benchmark";
 import { isTelemetryEnabled } from "../telemetry";
-import { COMPANY_TEAM_SIZES, COMPANY_USE_CASES } from "../utils/company-profile";
+import { COMPANY_TEAM_SIZES, COMPANY_USE_CASES, reportedUseCase } from "../utils/company-profile";
 import { normalizeOrgWebsite } from "../utils/org-website";
 import { globalConfig } from "./global-config";
 import { rejectGuest } from "./request-principal";
@@ -188,6 +188,9 @@ export async function buildFleetBenchmarkResponse(
     normalizeOrgWebsite(website) && team.success && use.success
       ? { teamSize: team.data, useCase: use.data }
       : null;
+  // The proxy answers 400 for a use case its catalog does not list yet, so
+  // that use case compares against the whole fleet.
+  const proxyPeerGroup = peerGroup && reportedUseCase(peerGroup.useCase) ? peerGroup : null;
   const empty = {
     level: peerGroup ? ("full" as const) : ("basic" as const),
     peerGroup: null,
@@ -215,7 +218,7 @@ export async function buildFleetBenchmarkResponse(
   if (finishedTasks < FLEET_MIN_FINISHED_TASKS)
     return { ...empty, state: "not_enough_tasks", local };
 
-  const fleet = await fleetBenchmarks(now.getTime(), peerGroup);
+  const fleet = await fleetBenchmarks(now.getTime(), proxyPeerGroup);
   const responsePeerGroup =
     peerGroup && fleet?.peer_group
       ? {

package/src/http/idempotency-key.ts

@@ -0,0 +1,117 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import {
+  findAcceptedWorkflowOperation,
+  type WorkflowIdempotencyClaim,
+} from "../be/db/workflow-idempotency";
+import { getRequestAuth } from "../utils/request-auth-context";
+import { jsonError } from "./utils";
+
+/** Visible ASCII, at most 255 characters: room for a UUID, a ULID or a client's own scheme. */
+const IDEMPOTENCY_KEY_PATTERN = /^[\x21-\x7E]{1,255}$/;
+
+/** Set on a response answered from an earlier accepted request. */
+export const IDEMPOTENT_REPLAYED_HEADER = "Idempotent-Replayed";
+
+/** OpenAPI declaration of the optional `Idempotency-Key` request header. */
+export const idempotencyKeyHeader = (accepted: string) =>
+  z.object({
+    "Idempotency-Key": z
+      .string()
+      .regex(IDEMPOTENCY_KEY_PATTERN)
+      .optional()
+      .describe(
+        "Optional client-generated key, 1-255 visible ASCII characters (a UUID works). " +
+          `The first request the server accepts under a key ${accepted}; a retry with the same key ` +
+          "and an equivalent body gets that request's status and body back (with " +
+          `\`${IDEMPOTENT_REPLAYED_HEADER}: true\`) and changes nothing. The key is scoped to the ` +
+          "caller's identity and this operation; it is not a credential. The same key with a " +
+          "different body is a 409. A request rejected before it is accepted (validation, auth, " +
+          "not found, disabled) does not use up the key. Accepted keys do not expire.",
+      ),
+  });
+
+/** A request that sent a usable `Idempotency-Key`. */
+export interface IdempotencyKeyRequest {
+  /** Stable identity of the authenticated caller, never a credential value. */
+  principal: string;
+  key: string;
+}
+
+/**
+ * The caller identity a key is scoped to. A user or session token names its
+ * user or agent; rotating the token keeps the scope. Requests on the swarm API
+ * key are the operator, or the agent named by X-Agent-ID: every worker shares
+ * that key, so this keeps their keys apart (it is not an access boundary; the
+ * swarm key may act as any agent). A guest page session has no identity.
+ */
+function idempotencyPrincipal(req: IncomingMessage, myAgentId: string | undefined): string | null {
+  const auth = getRequestAuth(req);
+  switch (auth?.kind) {
+    case "user":
+      return `user:${auth.userId}`;
+    case "agent":
+      return `agent:${auth.agentId}`;
+    case "controller":
+      return `controller:${auth.controllerId}`;
+    case "guest":
+      return null;
+    default:
+      return myAgentId ? `agent:${myAgentId}` : "operator";
+  }
+}
+
+/**
+ * Read the `Idempotency-Key` header. Undefined when none was sent; null when
+ * it is malformed or the caller has no identity to scope it to, after writing
+ * the 400.
+ */
+export function readIdempotencyKey(
+  req: IncomingMessage,
+  res: ServerResponse,
+  myAgentId: string | undefined,
+): IdempotencyKeyRequest | null | undefined {
+  const raw = req.headers["idempotency-key"];
+  if (raw === undefined) return undefined;
+  const key = Array.isArray(raw) ? raw.join(", ") : raw;
+  if (!IDEMPOTENCY_KEY_PATTERN.test(key)) {
+    jsonError(res, "Idempotency-Key must be 1-255 visible ASCII characters", 400);
+    return null;
+  }
+  const principal = idempotencyPrincipal(req, myAgentId);
+  if (!principal) {
+    jsonError(res, "Idempotency-Key needs an identified caller", 400);
+    return null;
+  }
+  return { principal, key };
+}
+
+/**
+ * Answer from the operation already accepted under this claim's scope, if
+ * any. Returns false, writing nothing, when there is none. Otherwise writes a
+ * 409 when the stored request differs, a 410 when its workflow was deleted,
+ * or hands the stored body to `send` with the replay header set, and returns
+ * true. Runs after authentication and before any check that may have changed
+ * since the original request.
+ */
+export async function replayAcceptedOperation(
+  res: ServerResponse,
+  claim: WorkflowIdempotencyClaim,
+  send: (body: unknown) => void,
+): Promise<boolean> {
+  const accepted = await findAcceptedWorkflowOperation(claim);
+  if (!accepted) return false;
+  if (accepted.fingerprint !== claim.fingerprint) {
+    jsonError(res, "Idempotency-Key was already used for a different request", 409);
+  } else if (accepted.resourceDeletedAt !== null) {
+    jsonError(
+      res,
+      "The workflow this Idempotency-Key created or triggered was deleted; send a new key to start over",
+      410,
+    );
+  } else {
+    res.setHeader(IDEMPOTENT_REPLAYED_HEADER, "true");
+    send(accepted.body);
+  }
+  return true;
+}

package/src/http/index.ts

@@ -76,6 +76,7 @@ import { handleApprovalRequests } from "./approval-requests";
 import { handleApps } from "./apps";
 import { handleAssets } from "./assets";
 import { handleBudgets } from "./budgets";
+import { handleCodexOAuthAccounts } from "./codex-oauth-accounts";
 import { handleCodexOAuthDevice } from "./codex-oauth-device";
 import { handleCodexOAuthKeepWarm } from "./codex-oauth-keep-warm";
 import { handleComb } from "./comb";
@@ -115,6 +116,7 @@ import { handlePageProxy } from "./page-proxy";
 import { handlePages } from "./pages";
 import { handlePagesPublic } from "./pages-public";
 import { handlePoll } from "./poll";
+import { handlePoolKeys } from "./pool-keys";
 import { handlePricing } from "./pricing";
 import { handlePromptTemplates } from "./prompt-templates";
 import { handleRanking } from "./ranking";
@@ -360,6 +362,7 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleStatus(req, res, pathSegments, queryParams),
         () => handleOnboarding(req, res, pathSegments, queryParams),
         () => handleCodexOAuthDevice(req, res, pathSegments, queryParams),
+        () => handleCodexOAuthAccounts(req, res, pathSegments, queryParams),
         () => handleActiveSessions(req, res, pathSegments, queryParams, myAgentId),
         () => handlePricing(req, res, pathSegments, queryParams, myAgentId),
         () => handleSchedules(req, res, pathSegments, queryParams, myAgentId),
@@ -367,6 +370,7 @@ const httpServer = createHttpServer(async (req, res) => {
         () => handleWorkflowEvents(req, res, pathSegments, queryParams),
         () => handleApprovalRequests(req, res, pathSegments, queryParams),
         () => handleApps(req, res, pathSegments, queryParams, myAgentId),
+        () => handlePoolKeys(req, res, pathSegments, queryParams),
         () => handleConfig(req, res, pathSegments, queryParams),
         () => handleFs(req, res, pathSegments, queryParams, myAgentId),
         () => handleComb(req, res, pathSegments, queryParams, myAgentId),
@@ -898,6 +902,13 @@ httpServer
       .catch((err) => {
         console.error("[boot-scrub-sweep] startup scrub failed (non-fatal):", err);
       });
+
+    // Source key backfill is idempotent, resumable, and non-fatal.
+    import("../be/session-source-backfill")
+      .then(({ runSessionSourceBackfill }) => runSessionSourceBackfill())
+      .catch((err) => {
+        console.error("[session-source-backfill] startup run failed (non-fatal):", err);
+      });
   })
   .on("error", (err) => {
     console.error("HTTP Server Error:", err);