@opengeni/api-router 0.21.10 → 0.21.14

package/dist/index.js

@@ -1,7 +1,7 @@
 import {
   createAppComposition,
   startSlackInteractionPump
-} from "./chunk-J4JS2F7L.js";
+} from "./chunk-R5PDSH2A.js";
 
 // src/index.ts
 import {

package/dist/integrations/slack-interactions.d.ts

@@ -13,7 +13,7 @@ export declare const SLACK_TASK_INSTRUCTIONS: string;
  * selection at session creation while keeping Slack mutations out of the model
  * surface; interaction delivery remains owned by the durable delivery pump.
  */
-export declare const SLACK_TASK_FIRST_PARTY_MCP_TOOLS: ("artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_publish" | "artifacts_rollback" | "environment_list" | "environment_set_variable" | "github_connect_link" | "github_repositories_list" | "github_token" | "goal_complete" | "goal_pause" | "goal_set" | "goal_update" | "memory_correct" | "memory_save" | "memory_search" | "preference_registry_get" | "preference_registry_summary" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_pause" | "session_resume" | "session_send_message" | "session_steer" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "variable_set_list" | "variable_set_set_variable")[];
+export declare const SLACK_TASK_FIRST_PARTY_MCP_TOOLS: ("artifacts_create" | "artifacts_get_source" | "artifacts_list" | "artifacts_publish" | "artifacts_rollback" | "environment_list" | "environment_set_variable" | "github_connect_link" | "github_repositories_list" | "goal_complete" | "goal_pause" | "goal_set" | "goal_update" | "memory_correct" | "memory_save" | "memory_search" | "preference_registry_get" | "preference_registry_summary" | "rig_get" | "rig_list" | "rig_promote" | "rig_propose_change" | "rig_verify" | "run_on" | "sandbox_attach" | "sandbox_provision" | "sandbox_swap" | "sandboxes_list" | "scheduled_task_runs_list" | "scheduled_tasks_create" | "scheduled_tasks_delete" | "scheduled_tasks_get" | "scheduled_tasks_list" | "scheduled_tasks_pause" | "scheduled_tasks_resume" | "scheduled_tasks_trigger" | "scheduled_tasks_update" | "session_create" | "session_events" | "session_get" | "session_pause" | "session_resume" | "session_send_message" | "session_steer" | "sessions_list" | "set_other_session_title" | "set_session_title" | "slack_bot_channel_history" | "slack_bot_delete_message" | "slack_bot_file_content" | "slack_bot_file_info" | "slack_bot_list_channels" | "slack_bot_list_files" | "slack_bot_list_users" | "slack_bot_post_message" | "slack_bot_thread_replies" | "social_connections_list" | "social_daily_analysis_context" | "social_mentions_live" | "social_post_reply" | "social_posts_recent" | "social_posts_sync" | "social_search_live" | "social_thread_fetch" | "variable_set_list" | "variable_set_set_variable")[];
 export type NormalizedSlackInteraction = {
     providerEventId: string;
     providerMessageId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/api-router",
-  "version": "0.21.10",
+  "version": "0.21.14",
   "description": "OpenGeni HTTP surface: the Hono adapter/router (createApp), routes, MCP HTTP transport, and HTTP access adapters over @opengeni/core. An engine-distribution surface — its runtime closure includes engine-internal packages.",
   "license": "Apache-2.0",
   "repository": {
@@ -43,18 +43,18 @@
     "@hono/zod-validator": "^0.7.6",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@opengeni/agent-proto": "^0.3.0",
-    "@opengeni/codex": "^0.2.10",
-    "@opengeni/config": "^0.10.12",
-    "@opengeni/contracts": "^0.38.2",
-    "@opengeni/core": "^0.20.12",
-    "@opengeni/db": "^0.27.9",
-    "@opengeni/documents": "^0.5.5",
-    "@opengeni/events": "^0.3.75",
-    "@opengeni/github": "^0.4.28",
+    "@opengeni/codex": "^0.2.11",
+    "@opengeni/config": "^0.10.14",
+    "@opengeni/contracts": "^0.38.3",
+    "@opengeni/core": "^0.20.16",
+    "@opengeni/db": "^0.27.11",
+    "@opengeni/documents": "^0.5.7",
+    "@opengeni/events": "^0.3.77",
+    "@opengeni/github": "^0.4.30",
     "@opengeni/network": "^0.2.0",
-    "@opengeni/observability": "^0.4.15",
-    "@opengeni/runtime": "^0.18.11",
-    "@opengeni/storage": "^0.2.65",
+    "@opengeni/observability": "^0.4.16",
+    "@opengeni/runtime": "^0.18.15",
+    "@opengeni/storage": "^0.2.67",
     "@temporalio/client": "^1.17.0",
     "better-auth": "^1.6.14",
     "hono": "^4.12.18",

package/src/mcp/server.ts

@@ -43,7 +43,6 @@ import {
   getPreferenceRegistryFullContent,
   getVariableSet,
   getVariableSetByName,
-  areGitHubRepositoriesAllowedForWorkspace,
   listScheduledTaskRuns,
   listScheduledTasks,
   listSessionEventPage,
@@ -84,7 +83,6 @@ import {
 import { appendAndPublishEvents, publishDurableSessionEvents } from "@opengeni/events";
 import {
   createSignedState,
-  createGitHubAppInstallationToken,
   GitHubAppConfigurationError,
   githubAppMissingSettings,
 } from "@opengeni/github";
@@ -233,7 +231,6 @@ const FIRST_PARTY_TOOL_AUTHORIZATION = {
   variable_set_set_variable: { allOf: ["variable-sets:manage"] },
   environment_set_variable: { allOf: ["variable-sets:manage"] },
   github_connect_link: { allOf: ["github:use"] },
-  github_token: { sessionRequired: true, allOf: ["github:use"] },
   github_repositories_list: { allOf: ["github:use"] },
   social_connections_list: { allOf: ["connections:read"] },
   social_posts_recent: { allOf: ["connections:read"] },
@@ -443,26 +440,21 @@ export function buildOpenGeniMcpServer(
     registerSlackBotTools(server, deps, grant, sessionId, json);
   }
 
-  // Orchestration, variableSet, and GitHub status/token tools are permission-gated
+  // Orchestration, variableSet, and GitHub status tools are permission-gated
   // at registration: a grant without the permission does not see the tool.
   // Sandboxed workers reach this server with the first-party delegated
   // permission set (firstPartyMcpPermissions in @opengeni/runtime), which is
   // POWERFUL BY DEFAULT — it carries sessions:*, variable sets:*, and github:use,
   // so agents can spawn/read sessions, manage variable set variables, inspect
-  // GitHub connection availability, and refresh scoped tokens for already-bound
-  // repositories out of the box. A user DEMOTES a specific
+  // GitHub connection availability, and use already-bound repository resources
+  // out of the box. GitHub installation credentials are refreshed host-side and
+  // never returned through a model-visible MCP tool. A user DEMOTES a specific
   // session by setting a narrower session.firstPartyMcpPermissions (capped to
   // the creator's own grant); operators still cap what any session can be given.
   registerWorkspaceOrchestrationTools(server, deps, grant, can, sessionId, toolspaceMode, json);
   registerVariableSetTools(server, deps, grant, can, json);
   if (can("github:use")) {
     registerGitHubConnectTool(server, deps, grant, options, json);
-    // TOKEN-BROKER (B1): the agent-refreshable git token. Session-scoped (keys off the
-    // worker-signed sessionId claim so it mints for THIS session's repos), gated on
-    // the same github:use capability as github_connect_link.
-    if (sessionId !== null) {
-      registerGitHubTokenTool(server, deps, grant, sessionId, json);
-    }
   }
 
   if (!toolspaceMode || can("github:use")) {
@@ -2960,73 +2952,6 @@ function registerGitHubConnectTool(
   );
 }
 
-// TOKEN-BROKER (B1): mint a FRESH short-lived GitHub App installation token for the
-// session's repository resources. The agent calls this to refresh git auth before
-// the current token expires. The MCP server CANNOT write the box, so the tool RETURNS
-// the token as JSON; the agent writes it to the token file (via exec) to refresh
-// GIT_ASKPASS. Same github:use capability gate as github_connect_link.
-function registerGitHubTokenTool(
-  server: McpServer,
-  deps: ApiRouteDeps,
-  grant: AccessGrant,
-  sessionId: string,
-  json: JsonResult,
-): void {
-  server.registerTool(
-    "github_token",
-    {
-      description:
-        "Mint a fresh short-lived GitHub token for this session's repositories. Write it to $OPENGENI_GIT_TOKEN_FILE (default $HOME/.opengeni/git-token) to refresh git auth before the current token expires.",
-      inputSchema: {},
-    },
-    async () => {
-      const session = await requireSession(deps.db, grant.workspaceId, sessionId);
-      // Resolve the run-scoped installation + repository ids from THIS session's
-      // repository resources (same shape sandboxEnvironmentForRun mints against). Only
-      // private GitHub-App repos carry the installation/repository ids.
-      const selected = (session.resources ?? []).flatMap((resource) => {
-        if (resource.kind !== "repository") {
-          return [];
-        }
-        const installationId = resource.githubInstallationId;
-        const repositoryId = resource.githubRepositoryId;
-        return typeof installationId === "number" &&
-          installationId > 0 &&
-          typeof repositoryId === "number" &&
-          repositoryId > 0
-          ? [{ installationId, repositoryId }]
-          : [];
-      });
-      if (selected.length === 0) {
-        throw new Error("this session has no GitHub App repository resources to mint a token for");
-      }
-      const installationId = selected[0]!.installationId;
-      if (selected.some((item) => item.installationId !== installationId)) {
-        throw new Error("GitHub App repository resources must belong to one installation");
-      }
-      const repositoryIds = selected.map((item) => item.repositoryId);
-      if (
-        !(await areGitHubRepositoriesAllowedForWorkspace(
-          deps.db,
-          grant.workspaceId,
-          installationId,
-          repositoryIds,
-        ))
-      ) {
-        throw new Error("this workspace no longer authorizes the session's GitHub repositories");
-      }
-      const token = await createGitHubAppInstallationToken(deps.settings, {
-        installationId,
-        repositoryIds,
-      });
-      return json({
-        token,
-        tokenFile: "$OPENGENI_GIT_TOKEN_FILE (default $HOME/.opengeni/git-token)",
-      });
-    },
-  );
-}
-
 // Defense-in-depth for invariant "agents cannot self-attach": the worker's
 // first-party delegated token never carries variable-sets:use, so sandboxed
 // agents calling these MCP tools cannot attach a variable set.

package/src/mcp/toolspace.ts

@@ -45,7 +45,10 @@ import {
   boundedParallelMap,
   cancelMcpResponseBody,
   guardedMcpFetch,
+  mcpJsonRpcErrorPayloadForRequest,
+  mcpRequestReplayInfo,
   mcpSerializedSizeBytes,
+  type McpRequestReplayInfo,
 } from "@opengeni/runtime/mcp-network";
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
@@ -85,13 +88,21 @@ const TOOLSPACE_AUTH_NEEDED_ERROR = {
   code: 40_101,
   message: "Authentication required - a connection link was posted to the session.",
 } as const;
+const TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR = {
+  code: 40_102,
+  message:
+    "Tool outcome uncertain: the provider returned 401 after receiving the request. OpenGeni did not replay this call. Do not retry automatically; verify provider state before any new attempt.",
+} as const;
 const TOOLSPACE_NO_ACTIVE_TURN_MESSAGE =
   "no active turn - toolspace calls require an in-flight turn";
 // First-party OpenGeni MCP proxies (files/docs) route back through the same
 // /mcp mount. They are excluded from the toolspace surface by construction so a
 // toolspace principal can never re-enter /mcp as a first-party caller, even if
 // a future grant carried files:read / documents:search (see docs invariants).
-const FIRST_PARTY_PROXY_IDS = new Set(["files", "docs"]);
+// Codex Apps is also excluded: its dynamic designated-owner authorization and
+// wire sanitizer live on the model MCP path and must never degrade into static
+// Toolspace headers.
+const FIRST_PARTY_PROXY_IDS = new Set(["files", "docs", "codex_apps"]);
 // In-process cache of the per-session upstream tool listing. Keyed on the set of
 // proxyable server ids + their credential versions, so a credential rotation
 // busts the entry; a short TTL bounds staleness for everything else. This is
@@ -754,6 +765,9 @@ async function callRemoteTool(
     if (isToolspaceAuthNeededError(error)) {
       return mcpError(TOOLSPACE_AUTH_NEEDED_ERROR.message);
     }
+    if (isToolspaceOutcomeUncertainError(error)) {
+      return mcpError(TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR.message);
+    }
     // The raw upstream error can carry provider-specific detail; log it
     // server-side and return only a generic result to the sandbox so no header
     // or credential material can ride the message back out.
@@ -840,9 +854,9 @@ function selectedMcpServerIds(tools: ToolRef[], sessionServerIds: string[]): Set
 }
 
 // Whether a selected server id may enter the toolspace proxy at all. The
-// first-party OpenGeni tool server and the files/docs proxies are excluded by
-// construction: they route back through /mcp, so admitting them would let a
-// toolspace principal re-enter as a first-party caller (recursion guard).
+// The first-party OpenGeni tool server and files/docs proxies are excluded by
+// construction because they route back through /mcp (recursion guard). Codex
+// Apps is excluded because Toolspace does not own its dynamic authorization.
 export function toolspaceCanProxyServerId(serverId: string): boolean {
   return serverId !== "opengeni" && !FIRST_PARTY_PROXY_IDS.has(serverId);
 }
@@ -891,12 +905,6 @@ function toolspaceRequestOptions(config: McpServerConfig): {
   return config.timeoutMs ? { timeout: config.timeoutMs, maxTotalTimeout: config.timeoutMs } : {};
 }
 
-type McpRequestInfo = {
-  method?: string;
-  id?: string | number | null;
-  toolName?: string;
-};
-
 function mcpRequestDestinationUrl(input: string | URL | Request): string {
   return new URL(input instanceof Request ? input.url : input.toString()).toString();
 }
@@ -950,7 +958,7 @@ export function connectionBrokerFetch(
     ownerHasWorkspaceMembership: delegatedOwnerHasMembership,
   });
   return async (requestInput, init) => {
-    const request = await mcpRequestInfo(requestInput, init);
+    const request = await mcpRequestReplayInfo(requestInput, init);
     const destinationUrl = mcpRequestDestinationUrl(requestInput);
     const resolverSubjectId =
       connectionRef.subjectScope !== "subject" && hostCredentialPort
@@ -978,10 +986,22 @@ export function connectionBrokerFetch(
     );
     if (response.status === 401) {
       await cancelMcpResponseBody(response);
-      const refreshed = await resolve(true);
+      let refreshed: ResolveConnectionCredentialResult;
+      try {
+        refreshed = await resolve(true);
+      } catch {
+        refreshed = authNeededFromStatus(input.config, first, "refresh_failed");
+      }
       if (refreshed.status === "auth_needed") {
+        if (!request.replaySafeAfter401) {
+          await publishToolspaceAuthNeeded(input, request, refreshed);
+          return toolspaceMcpOutcomeUncertainResponse(request);
+        }
         return await authNeededFetchResponse(input, request, refreshed);
       }
+      if (!request.replaySafeAfter401) {
+        return toolspaceMcpOutcomeUncertainResponse(request);
+      }
       const retry = await baseFetch(
         fetchInputForAttempt(requestInput),
         withConnectionHeaders(requestInput, init, refreshed.headers),
@@ -1044,9 +1064,27 @@ async function authNeededFetchResponse(
     sessionId: string;
     turn: SessionTurn;
   },
-  request: McpRequestInfo,
+  request: McpRequestReplayInfo,
   auth: Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }>,
 ): Promise<Response> {
+  await publishToolspaceAuthNeeded(input, request, auth);
+  if (request.method === "tools/call") {
+    return toolspaceMcpErrorResponse(request.id, TOOLSPACE_AUTH_NEEDED_ERROR);
+  }
+  return new Response("Authentication required for MCP server connection", { status: 401 });
+}
+
+async function publishToolspaceAuthNeeded(
+  input: {
+    deps: ApiRouteDeps;
+    grant: AccessGrant;
+    config: McpServerConfig;
+    sessionId: string;
+    turn: SessionTurn;
+  },
+  request: McpRequestReplayInfo,
+  auth: Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }>,
+): Promise<void> {
   await appendAndPublishEvents(
     input.deps.db,
     input.deps.bus,
@@ -1072,64 +1110,35 @@ async function authNeededFetchResponse(
       },
     ],
   ).catch(() => undefined);
-  if (request.method === "tools/call") {
-    return new Response(
-      JSON.stringify({
-        jsonrpc: "2.0",
-        id: request.id ?? null,
-        error: {
-          code: TOOLSPACE_AUTH_NEEDED_ERROR.code,
-          message: TOOLSPACE_AUTH_NEEDED_ERROR.message,
-        },
-      }),
-      {
-        status: 200,
-        headers: { "content-type": "application/json" },
-      },
-    );
-  }
-  return new Response("Authentication required for MCP server connection", { status: 401 });
 }
 
-async function mcpRequestInfo(
-  input: string | URL | Request,
-  init?: RequestInit,
-): Promise<McpRequestInfo> {
-  const body =
-    typeof init?.body === "string"
-      ? init.body
-      : input instanceof Request && (init?.method ?? input.method).toUpperCase() === "POST"
-        ? await input
-            .clone()
-            .text()
-            .catch(() => "")
-        : "";
-  if (!body) {
-    return {};
-  }
-  try {
-    const parsed = JSON.parse(body) as {
-      id?: unknown;
-      method?: unknown;
-      params?: { name?: unknown };
-    };
-    const method = typeof parsed.method === "string" ? parsed.method : undefined;
-    const id =
-      typeof parsed.id === "string" || typeof parsed.id === "number" || parsed.id === null
-        ? parsed.id
-        : undefined;
-    const toolName =
-      method === "tools/call" && typeof parsed.params?.name === "string"
-        ? parsed.params.name
-        : undefined;
-    return {
-      ...(method ? { method } : {}),
-      ...(id !== undefined ? { id } : {}),
-      ...(toolName ? { toolName } : {}),
-    };
-  } catch {
-    return {};
-  }
+function toolspaceMcpErrorResponse(
+  id: string | number | null | undefined,
+  error: { code: number; message: string },
+): Response {
+  return new Response(
+    JSON.stringify({
+      jsonrpc: "2.0",
+      id: id ?? null,
+      error,
+    }),
+    {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    },
+  );
+}
+
+function toolspaceMcpOutcomeUncertainResponse(request: McpRequestReplayInfo): Response {
+  return new Response(
+    JSON.stringify(
+      mcpJsonRpcErrorPayloadForRequest(request, TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR),
+    ),
+    {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    },
+  );
 }
 
 function withConnectionHeaders(
@@ -1162,3 +1171,16 @@ function isToolspaceAuthNeededError(error: unknown): boolean {
         `MCP error ${TOOLSPACE_AUTH_NEEDED_ERROR.code}: ${TOOLSPACE_AUTH_NEEDED_ERROR.message}`)
   );
 }
+
+function isToolspaceOutcomeUncertainError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = (error as { code?: unknown }).code;
+  return (
+    code === TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR.code &&
+    (error.message === TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR.message ||
+      error.message ===
+        `MCP error ${TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR.code}: ${TOOLSPACE_TOOL_OUTCOME_UNCERTAIN_ERROR.message}`)
+  );
+}

package/src/routes/codex.ts

@@ -35,6 +35,8 @@ import {
   buildCodexTokenResolver,
   claimCodexResetRedemption,
   completeCodexResetRedemption,
+  clearCodexAppsCredential,
+  designateCodexAppsCredential,
   disconnectAllCodexAccounts,
   disconnectCodexAccount,
   encryptEnvironmentValue,
@@ -44,6 +46,7 @@ import {
   fenceCodexResetRedemptionSend,
   getCodexResetRedemptionAttempt,
   getCodexCredentialStatus,
+  getCodexAppsSettings,
   getCodexRotationSettings,
   listPendingCodexCapacityWakeTargets,
   listCodexAccountStatuses,
@@ -68,7 +71,14 @@ const CODEX_PROVIDER_LABEL = "Codex subscription · no credits";
 // The wire shape for one Codex account (metadata only; never the secret column).
 // P2: fiveHour/weekly ride along, built from the CACHED usage columns (zero
 // provider calls, zero decrypts) so the bars render instantly off this read.
-function codexAccountJson(row: CodexAccountStatus) {
+function codexAccountJson(
+  row: CodexAccountStatus,
+  options: {
+    appsCredentialId?: string | null;
+    canManageApps?: boolean;
+    humanSubjectId?: string | null;
+  } = {},
+) {
   return {
     id: row.id,
     chatgptAccountId: row.chatgptAccountId,
@@ -98,6 +108,14 @@ function codexAccountJson(row: CodexAccountStatus) {
     resetCreditsCheckedAt: row.resetCreditsCheckedAt,
     // P3 rotation cooldown: when set and in the future, this account is cooling-down.
     exhaustedUntil: row.exhaustedUntil,
+    appsDesignated: options.appsCredentialId === row.id,
+    canEnableApps:
+      options.appsCredentialId === null &&
+      options.canManageApps === true &&
+      options.humanSubjectId !== null &&
+      options.humanSubjectId !== undefined &&
+      row.connectedBySubjectId === options.humanSubjectId &&
+      row.status === "active",
   };
 }
 
@@ -242,6 +260,28 @@ async function requireRedemptionHuman(
   return { human, accountId: grant.accountId };
 }
 
+async function requireCodexAppsHuman(
+  c: Context,
+  deps: ApiRouteDeps,
+  workspaceId: string,
+): Promise<{ human: ManagedCookieHuman; accountId: string }> {
+  if (c.req.header("authorization")) {
+    throw new HTTPException(403, {
+      message: "authorization bearer is not allowed for Codex Apps designation",
+    });
+  }
+  requireSameOriginBrowserMutation(c, deps);
+  const human = await managedCookieHuman(c, deps);
+  if (!human) {
+    throw new HTTPException(401, { message: "managed browser session required" });
+  }
+  const grant = await requireAccessGrant(c, deps, workspaceId, "connections:write");
+  if (grant.subjectId !== human.subjectId) {
+    throw new HTTPException(403, { message: "managed browser identity mismatch" });
+  }
+  return { human, accountId: grant.accountId };
+}
+
 function cachedUsage(row: CodexAccountStatus): CodexUsagePayload | null {
   const fiveHour = buildCodexUsageWindowFromCache(
     row.primaryUsedPercent,
@@ -721,15 +761,33 @@ export function registerCodexRoutes(app: Hono, deps: ApiRouteDeps): void {
   // workspace active pointer + rotation settings. Read access.
   app.get("/v1/workspaces/:workspaceId/codex/accounts", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:read");
-    const [accounts, rotation] = await Promise.all([
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:read");
+    const [accounts, rotation, apps, human] = await Promise.all([
       listCodexAccountStatuses(db, workspaceId),
       getCodexRotationSettings(db, workspaceId),
+      getCodexAppsSettings(db, workspaceId),
+      managedCookieHuman(c, deps),
     ]);
     const activeAccountId = rotation?.activeCredentialId ?? null;
+    const humanSubjectId = human?.subjectId === grant.subjectId ? human.subjectId : null;
+    const canManageApps =
+      humanSubjectId !== null && hasPermission(grant.permissions, "connections:write");
     return c.json({
-      accounts: accounts.map(codexAccountJson),
+      accounts: accounts.map((account) =>
+        codexAccountJson(account, {
+          appsCredentialId: apps.credentialId,
+          canManageApps: settings.codexConnectedAppsEnabled && canManageApps,
+          humanSubjectId,
+        }),
+      ),
       activeAccountId,
+      apps: {
+        available: settings.codexConnectedAppsEnabled,
+        credentialId: apps.credentialId,
+        version: apps.version,
+        designatedAt: apps.designatedAt,
+        canDisable: canManageApps && apps.credentialId !== null,
+      },
       settings: {
         rotationEnabled: rotation?.rotationEnabled ?? false,
         // sharded-rotation policy: rotation-enabled always behaves as sticky-sharded; report the
@@ -740,6 +798,78 @@ export function registerCodexRoutes(app: Hono, deps: ApiRouteDeps): void {
     });
   });
 
+  app.post("/v1/workspaces/:workspaceId/codex/apps", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    if (!settings.codexConnectedAppsEnabled) {
+      throw new HTTPException(409, { message: "Codex Apps is disabled for this deployment" });
+    }
+    const { human, accountId } = await requireCodexAppsHuman(c, deps, workspaceId);
+    const parsed = z
+      .object({
+        accountId: z.string().uuid(),
+        expectedVersion: z.number().int().nonnegative(),
+      })
+      .safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "accountId and expectedVersion are required" });
+    }
+    const result = await designateCodexAppsCredential(db, {
+      accountId,
+      workspaceId,
+      credentialId: parsed.data.accountId,
+      subjectId: human.subjectId,
+      expectedVersion: parsed.data.expectedVersion,
+    });
+    if (result.kind === "not_found") {
+      throw new HTTPException(404, { message: "codex account not found" });
+    }
+    if (result.kind === "not_owner") {
+      throw new HTTPException(403, {
+        message: "only the managed human who connected this subscription may designate it",
+      });
+    }
+    if (result.kind === "forbidden") {
+      throw new HTTPException(403, { message: "missing permission: connections:write" });
+    }
+    if (result.kind === "unavailable") {
+      throw new HTTPException(409, { message: "codex account requires relogin" });
+    }
+    const response = {
+      credentialId: result.credentialId,
+      version: result.version,
+      designatedAt: result.designatedAt,
+      changed: result.kind === "updated",
+    };
+    return result.kind === "updated" ? c.json(response) : c.json(response, 409);
+  });
+
+  app.delete("/v1/workspaces/:workspaceId/codex/apps", async (c) => {
+    const workspaceId = c.req.param("workspaceId");
+    const { human, accountId } = await requireCodexAppsHuman(c, deps, workspaceId);
+    const parsed = z
+      .object({ expectedVersion: z.number().int().nonnegative() })
+      .safeParse(await c.req.json().catch(() => null));
+    if (!parsed.success) {
+      throw new HTTPException(400, { message: "expectedVersion is required" });
+    }
+    const result = await clearCodexAppsCredential(db, {
+      accountId,
+      workspaceId,
+      subjectId: human.subjectId,
+      expectedVersion: parsed.data.expectedVersion,
+    });
+    if (result.kind === "forbidden") {
+      throw new HTTPException(403, { message: "missing permission: connections:write" });
+    }
+    const response = {
+      credentialId: result.credentialId,
+      version: result.version,
+      designatedAt: result.designatedAt,
+      changed: result.kind === "updated",
+    };
+    return result.kind === "conflict" ? c.json(response, 409) : c.json(response);
+  });
+
   // Manually switch the workspace ACTIVE account (the one unpinned sessions use).
   // Pure pointer flip; in-flight turns pick it up on their next token fetch.
   app.post("/v1/workspaces/:workspaceId/codex/accounts/:accountId/activate", async (c) => {
@@ -872,13 +1002,13 @@ export function registerCodexRoutes(app: Hono, deps: ApiRouteDeps): void {
   // row was active (FK ON DELETE SET NULL + re-pick in the same RLS txn).
   app.delete("/v1/workspaces/:workspaceId/codex/accounts/:accountId", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const accountId = c.req.param("accountId");
     const mutation = await withCodexCapacityMutation(
       db,
       { workspaceId, reason: "codex_credential_disconnected" },
       async (tx) => {
-        const result = await disconnectCodexAccount(tx, workspaceId, accountId);
+        const result = await disconnectCodexAccount(tx, workspaceId, accountId, grant.subjectId);
         return { result, changed: result.removed };
       },
     );
@@ -897,12 +1027,12 @@ export function registerCodexRoutes(app: Hono, deps: ApiRouteDeps): void {
   // the by-id route above.
   app.delete("/v1/workspaces/:workspaceId/codex", async (c) => {
     const workspaceId = c.req.param("workspaceId");
-    await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
+    const grant = await requireAccessGrant(c, deps, workspaceId, "workspace:admin");
     const mutation = await withCodexCapacityMutation(
       db,
       { workspaceId, reason: "codex_credentials_disconnected" },
       async (tx) => {
-        const result = await disconnectAllCodexAccounts(tx, workspaceId);
+        const result = await disconnectAllCodexAccounts(tx, workspaceId, grant.subjectId);
         return { result, changed: result.removed > 0 };
       },
     );