@opengeni/runtime 0.11.0 → 0.13.3

package/src/index.ts

@@ -14,6 +14,7 @@ import {
 import {
   approvalIdentifier,
   CAPABILITY_DESCRIPTORS,
+  DEFAULT_FIRST_PARTY_MCP_PERMISSIONS,
   assertUniqueResourceMountPaths,
   gitCredentialBindingIdForRepository,
   gitCredentialProviderForRepository,
@@ -27,6 +28,7 @@ import {
   signDelegatedAccessToken,
   RequestHumanInputToolInput,
   type GitCredentialProvider,
+  type GitCredentialTransport,
   type HumanInputResponse,
   type McpServerConnectionRef,
   type Permission,
@@ -37,6 +39,19 @@ import {
   type ToolAuthNeededPayload,
   type ToolRef,
 } from "@opengeni/contracts";
+import {
+  MCP_MAX_CONCURRENT_SERVER_OPERATIONS,
+  MCP_MAX_TOOL_RESULT_BYTES,
+  McpAggregateToolListBudget,
+  assertMcpPayloadWithinBytes,
+  assertMcpServerSelectionWithinBounds,
+  assertMcpToolListWithinBounds,
+  boundedParallelMap,
+  cancelMcpResponseBody,
+  guardedMcpFetch,
+  mcpOuterConnectTimeoutMs,
+  undiciFetch,
+} from "./mcp-network";
 import {
   Agent,
   AgentsError,
@@ -117,6 +132,7 @@ import {
   CODEX_APPS_MCP_SERVER_ID,
   CODEX_MODEL_ID_PREFIX,
   CODEX_ORIGINATOR,
+  CODEX_RESPONSE_SDK_OUTER_TIMEOUT_MS,
   boundModelToolOutputItems,
   codexAppsSanitizingFetch,
   codexRequestStorage,
@@ -181,7 +197,16 @@ export {
 } from "./skill-library";
 
 export type { RuntimeMetricsHooks } from "./metrics";
-export type { TurnToolCancellationFence } from "./sandbox/turn-tool-cancellation";
+export {
+  createTurnToolCancellationController,
+  TurnSandboxCommandCancelledError,
+} from "./sandbox/turn-tool-cancellation";
+export type {
+  TurnSandboxCommandArgs,
+  TurnSandboxCommandSession,
+  TurnToolCancellationController,
+  TurnToolCancellationFence,
+} from "./sandbox/turn-tool-cancellation";
 
 // P4.3 computer-use surface (the agent's :0 driver). Re-exported from the barrel
 // so callers (the worker, live proofs) reach SandboxComputer/ComputerUseCapability
@@ -269,8 +294,17 @@ export type {
   CompactionItem,
   PreparedCompactionPromptInput,
 } from "./context-compaction";
-export { modelCallUsageTelemetry } from "./usage-telemetry";
-export type { ModelCallUsageTelemetry } from "./usage-telemetry";
+export {
+  MAX_MODEL_USAGE_TOKEN_COUNT,
+  modelCallUsageTelemetry,
+  modelUsageTokenCountOrNull,
+  normalizeModelCallUsage,
+} from "./usage-telemetry";
+export type {
+  ModelCallUsageInput,
+  ModelCallUsageNormalization,
+  ModelCallUsageTelemetry,
+} from "./usage-telemetry";
 
 ensureReadableStreamFrom();
 
@@ -289,6 +323,18 @@ export type ModelResponseUsage = {
     totalTokens?: number;
     inputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
     outputTokensDetails?: Record<string, number> | Array<Record<string, number>>;
+    requestUsageEntries?: Array<{
+      inputTokens?: number;
+      input_tokens?: number;
+      outputTokens?: number;
+      output_tokens?: number;
+      totalTokens?: number;
+      total_tokens?: number;
+      inputTokensDetails?: Record<string, number>;
+      input_tokens_details?: Record<string, number>;
+      outputTokensDetails?: Record<string, number>;
+      output_tokens_details?: Record<string, number>;
+    }>;
   };
 };
 
@@ -302,6 +348,8 @@ export type ResolveConnectionCredentialInput = {
   serverId: string;
   toolName?: string;
   connectionRef: McpServerConnectionRef;
+  /** Exact MCP destination whose request would receive the resolved headers. */
+  destinationUrl: string;
   forceRefresh?: boolean;
 };
 
@@ -564,6 +612,10 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
           // SDK retries on network/5xx/partial streams can replay provider work
           // or external tool side effects without a durable checkpoint.
           maxRetries: 0,
+          // The Codex transport owns finer headers/idle/whole deadlines and
+          // emits typed durable evidence. Keep the SDK's opaque envelope beyond
+          // that whole-response budget so `Request timed out.` cannot win first.
+          timeout: CODEX_RESPONSE_SDK_OUTER_TIMEOUT_MS,
           fetch: codexSubscriptionFetch(instrumentedModelFetch(provider.id, globalThis.fetch)),
         })
       : // ResolvedModelProvider.apiKey is already the resolved key (configuredProviders
@@ -625,7 +677,7 @@ export function resolveTurnModel(
   return {
     provider: resolved.provider,
     client,
-    model: buildModelInstance(resolved.provider, client, resolved.model.id),
+    model: buildModelInstance(resolved.provider, client, resolved.model.upstreamModelId),
     configured: resolved.model,
   };
 }
@@ -1188,6 +1240,7 @@ export type GitCredentialBindingSeed = {
   credentialBindingId: string;
   provider: GitCredentialProvider;
   token: string;
+  transport?: GitCredentialTransport;
   expiresAt?: string;
   /** Total active bindings for this provider, used to suppress unsafe aliases. */
   providerBindingCount?: number;
@@ -1907,14 +1960,17 @@ function maybeInstallCodexToolSearch(
 }
 
 /** True when the unprefixed tool `name` requires approval under `policy`. */
-function mcpToolRequiresApproval(policy: boolean | string[], unprefixedName: string): boolean {
-  return policy === true || (Array.isArray(policy) && policy.includes(unprefixedName));
+function mcpToolRequiresApproval(
+  policy: boolean | ReadonlySet<string>,
+  unprefixedName: string,
+): boolean {
+  return policy === true || (policy !== false && policy.has(unprefixedName));
 }
 
 /** A per-server approval policy keyed by the server's `<id>__` tool prefix. */
 type McpApprovalPolicy = {
   prefix: string;
-  requireApproval: boolean | string[];
+  requireApproval: boolean | ReadonlySet<string>;
 };
 
 /** The subset of the agent surface the approval wrap needs — including `clone`. */
@@ -2005,7 +2061,8 @@ function applyMcpApprovalPolicy(agent: Agent<any, any>, settings: Settings): voi
     )
     .map((server) => ({
       prefix: prefixedMcpToolName(server.id, ""),
-      requireApproval: server.requireApproval as boolean | string[],
+      requireApproval:
+        server.requireApproval === true ? true : new Set(server.requireApproval as string[]),
     }))
     .sort((a, b) => b.prefix.length - a.prefix.length);
   if (policies.length === 0) {
@@ -2266,8 +2323,76 @@ export type PrepareToolsOptions = {
     input: ResolveConnectionCredentialInput,
   ) => Promise<ResolveConnectionCredentialResult>;
   onAuthNeeded?: (payload: ToolAuthNeededPayload) => Promise<void> | void;
+  /** Injectable final MCP transport for tests and embedded hosts. */
+  mcpFetchImpl?: FetchLike;
 };
 
+type ConnectedMcpServerBatch = Awaited<ReturnType<typeof connectMcpServers>>;
+
+export type ConnectedMcpServerBatches = {
+  active: MCPServer[];
+  failed: MCPServer[];
+  errors: ReadonlyMap<MCPServer, Error>;
+  close: () => Promise<void>;
+};
+
+/**
+ * Connect SDK-managed MCP servers in stable, bounded batches. The SDK cleans a
+ * failing strict batch; this wrapper additionally closes every earlier batch
+ * before rethrowing, so a later-batch failure cannot leak live connections.
+ */
+export async function connectMcpServersInBatches(
+  servers: MCPServer[],
+  options: { strict: boolean; connectTimeoutMs?: number },
+): Promise<ConnectedMcpServerBatches> {
+  assertMcpServerSelectionWithinBounds(servers);
+  const batches: ConnectedMcpServerBatch[] = [];
+  try {
+    for (let offset = 0; offset < servers.length; offset += MCP_MAX_CONCURRENT_SERVER_OPERATIONS) {
+      batches.push(
+        await connectMcpServers(
+          servers.slice(offset, offset + MCP_MAX_CONCURRENT_SERVER_OPERATIONS),
+          {
+            ...(options.connectTimeoutMs === undefined
+              ? {}
+              : { connectTimeoutMs: options.connectTimeoutMs }),
+            connectInParallel: true,
+            strict: options.strict,
+          },
+        ),
+      );
+    }
+  } catch (error) {
+    await closeMcpServerBatches(batches).catch(() => undefined);
+    throw error;
+  }
+
+  const errors = new Map<MCPServer, Error>();
+  for (const batch of batches) {
+    for (const [server, error] of batch.errors) errors.set(server, error);
+  }
+  return {
+    active: batches.flatMap((batch) => batch.active),
+    failed: batches.flatMap((batch) => batch.failed),
+    errors,
+    close: async () => {
+      await closeMcpServerBatches(batches);
+    },
+  };
+}
+
+async function closeMcpServerBatches(batches: ConnectedMcpServerBatch[]): Promise<void> {
+  let firstError: unknown;
+  for (const batch of [...batches].reverse()) {
+    try {
+      await batch.close();
+    } catch (error) {
+      firstError ??= error;
+    }
+  }
+  if (firstError !== undefined) throw firstError;
+}
+
 export async function prepareAgentTools(
   settings: Settings,
   tools: ToolRef[],
@@ -2277,25 +2402,36 @@ export async function prepareAgentTools(
   // codex_apps sanitizing fetch so every tools/list this turn accumulates the
   // account's connector namespaces. Surfaced on PreparedAgentTools for the worker.
   const codexConnectorNamespaces = new Set<string>();
+  assertMcpServerSelectionWithinBounds(tools);
   if (tools.length === 0) {
     return { mcpServers: [], close: async () => {}, codexConnectorNamespaces };
   }
   const registry = new Map(settings.mcpServers.map((server) => [server.id, server]));
-  const servers = await Promise.all(
-    tools.map(async (tool) => {
+  const aggregateToolBudget = new McpAggregateToolListBudget();
+  const mcpFetchImpl = options.mcpFetchImpl ?? undiciFetch;
+  const servers = await boundedParallelMap(
+    tools,
+    MCP_MAX_CONCURRENT_SERVER_OPERATIONS,
+    async (tool, index) => {
       const config = registry.get(tool.id);
       if (!config) {
         throw new Error(`Unknown MCP server id: ${tool.id}`);
       }
       const url = firstPartyMcpServerUrlForRun(settings, config, options.workspaceId) ?? config.url;
+      const firstParty = isFirstPartyMcpServer(settings, config);
       const baseFetch = isCodexAppsMcpServer(config)
-        ? codexAppsSanitizingFetch(globalThis.fetch, codexConnectorNamespaces)
-        : globalThis.fetch;
+        ? codexAppsSanitizingFetch(mcpFetchImpl, codexConnectorNamespaces)
+        : mcpFetchImpl;
+      const guardedFetch = guardedMcpFetch(
+        firstParty ? { ...settings, integrationsAllowPrivateNetworkTargets: true } : settings,
+        baseFetch,
+        firstParty ? { requireHttpsOutsideLocalTest: false } : {},
+      );
       const fetchImpl = config.connectionRef
-        ? connectionBrokerFetch(baseFetch, config, options)
-        : isFirstPartyMcpServer(settings, config)
-          ? firstPartyAuthFetch(baseFetch, settings, options)
-          : baseFetch;
+        ? connectionBrokerFetch(guardedFetch, config, options)
+        : firstParty
+          ? firstPartyAuthFetch(guardedFetch, settings, options)
+          : guardedFetch;
       // A server is connected BEST-EFFORT (a connect OR tools-list failure drops
       // it — its tools go unavailable for the turn — instead of failing the turn)
       // in two cases:
@@ -2327,7 +2463,7 @@ export async function prepareAgentTools(
           // MCP SDK's strict Tool schema rejects (fails the turn during tools/list);
           // sanitize the response on the wire before validation. The namespace Set
           // also captures each tool's original connector namespace (P4 Part B.1).
-          ...(fetchImpl !== globalThis.fetch ? { fetch: fetchImpl } : {}),
+          fetch: fetchImpl,
           ...(await mcpServerRequestInit(settings, config)),
           ...(config.timeoutMs
             ? {
@@ -2339,36 +2475,50 @@ export async function prepareAgentTools(
         config.id,
         config.allowedTools,
         bestEffort,
+        aggregateToolBudget,
+        `${config.id}:${index}`,
       );
       return {
         server,
         bestEffort,
         optional,
+        timeoutMs: config.timeoutMs,
       };
-    }),
+    },
   );
-  const requiredServers = servers.filter((entry) => !entry.bestEffort).map((entry) => entry.server);
-  const bestEffortServers = servers
-    .filter((entry) => entry.bestEffort)
-    .map((entry) => entry.server);
+  const requiredEntries = servers.filter((entry) => !entry.bestEffort);
+  const bestEffortEntries = servers.filter((entry) => entry.bestEffort);
+  const requiredServers = requiredEntries.map((entry) => entry.server);
+  const bestEffortServers = bestEffortEntries.map((entry) => entry.server);
   // Names of the OPTIONAL servers (not codex_apps) so a drop is surfaced as a
   // warning; codex_apps keeps its historically-quiet drop (a not-logged-in
   // ChatGPT plan is a normal, non-noteworthy state).
   const optionalServerNames = new Set(
     servers.filter((entry) => entry.optional).map((entry) => entry.server.name),
   );
-  const connectedRequired = await connectMcpServers(requiredServers, {
-    connectInParallel: true,
+  const connectedRequired = await connectMcpServersInBatches(requiredServers, {
     strict: true,
+    connectTimeoutMs: mcpOuterConnectTimeoutMs(requiredEntries.map((entry) => entry.timeoutMs)),
   });
-  const connectedBestEffort = bestEffortServers.length
-    ? await connectMcpServers(bestEffortServers, {
-        connectInParallel: true,
-        strict: false,
-      })
-    : null;
+  let connectedBestEffort: ConnectedMcpServerBatches | null = null;
+  try {
+    connectedBestEffort = bestEffortServers.length
+      ? await connectMcpServersInBatches(bestEffortServers, {
+          strict: false,
+          connectTimeoutMs: mcpOuterConnectTimeoutMs(
+            bestEffortEntries.map((entry) => entry.timeoutMs),
+          ),
+        })
+      : null;
+  } catch (error) {
+    await connectedRequired.close().catch(() => undefined);
+    throw error;
+  }
   if (connectedBestEffort) {
     for (const failed of connectedBestEffort.failed) {
+      if (failed instanceof PrefixedMcpServer) {
+        failed.releaseAggregateBudget();
+      }
       if (!optionalServerNames.has(failed.name)) {
         continue;
       }
@@ -2382,10 +2532,20 @@ export async function prepareAgentTools(
   return {
     mcpServers: [...connectedRequired.active, ...(connectedBestEffort?.active ?? [])],
     close: async () => {
-      await connectedRequired.close();
+      let firstError: unknown;
       if (connectedBestEffort) {
-        await connectedBestEffort.close();
+        try {
+          await connectedBestEffort.close();
+        } catch (error) {
+          firstError ??= error;
+        }
       }
+      try {
+        await connectedRequired.close();
+      } catch (error) {
+        firstError ??= error;
+      }
+      if (firstError !== undefined) throw firstError;
     },
     codexConnectorNamespaces,
   };
@@ -2402,10 +2562,12 @@ function connectionBrokerFetch(
   }
   return async (input, init) => {
     const request = await mcpRequestInfo(input, init);
+    const destinationUrl = mcpRequestDestinationUrl(input);
     const first = await resolveConnectionForRequest(
       options,
       config.id,
       connectionRef,
+      destinationUrl,
       request.toolName,
       false,
     );
@@ -2417,10 +2579,12 @@ function connectionBrokerFetch(
       withConnectionHeaders(input, init, first.headers),
     );
     if (response.status === 401) {
+      await cancelMcpResponseBody(response);
       const refreshed = await resolveConnectionForRequest(
         options,
         config.id,
         connectionRef,
+        destinationUrl,
         request.toolName,
         true,
       );
@@ -2433,11 +2597,14 @@ function connectionBrokerFetch(
       );
       if (retry.status === 403) {
         const auth = insufficientScopeAuth(retry.headers, connectionRef, refreshed.connectionId);
-        return auth
-          ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef)
-          : retry;
+        if (auth) {
+          await cancelMcpResponseBody(retry);
+          return await authNeededFetchResponse(options, config.id, request, auth, connectionRef);
+        }
+        return retry;
       }
       if (retry.status === 401) {
+        await cancelMcpResponseBody(retry);
         return await authNeededFetchResponse(
           options,
           config.id,
@@ -2461,9 +2628,11 @@ function connectionBrokerFetch(
     }
     if (response.status === 403) {
       const auth = insufficientScopeAuth(response.headers, connectionRef, first.connectionId);
-      return auth
-        ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef)
-        : response;
+      if (auth) {
+        await cancelMcpResponseBody(response);
+        return await authNeededFetchResponse(options, config.id, request, auth, connectionRef);
+      }
+      return response;
     }
     return response;
   };
@@ -2473,6 +2642,7 @@ async function resolveConnectionForRequest(
   options: PrepareToolsOptions,
   serverId: string,
   connectionRef: McpServerConnectionRef,
+  destinationUrl: string,
   toolName: string | undefined,
   forceRefresh: boolean,
 ): Promise<ResolveConnectionCredentialResult> {
@@ -2494,6 +2664,7 @@ async function resolveConnectionForRequest(
     workspaceId: options.workspaceId,
     serverId,
     connectionRef,
+    destinationUrl,
     forceRefresh,
     ...(toolName ? { toolName } : {}),
     ...(options.subjectId ? { subjectId: options.subjectId } : {}),
@@ -2610,6 +2781,10 @@ type McpRequestInfo = {
   toolName?: string;
 };
 
+function mcpRequestDestinationUrl(input: string | URL | Request): string {
+  return new URL(input instanceof Request ? input.url : input.toString()).toString();
+}
+
 async function mcpRequestInfo(
   input: string | URL | Request,
   init?: RequestInit,
@@ -2838,7 +3013,7 @@ async function signFirstPartyDelegatedBearer(
     workspaceId: options.workspaceId,
     subjectId: options.subjectId ?? "worker:first-party-mcp",
     ...(options.subjectLabel ? { subjectLabel: options.subjectLabel } : {}),
-    permissions: options.firstPartyPermissions ?? firstPartyMcpPermissions,
+    permissions: options.firstPartyPermissions ?? [...DEFAULT_FIRST_PARTY_MCP_PERMISSIONS],
     ...(options.sessionId ? { sessionId: options.sessionId } : {}),
     ...(options.turnId ? { turnId: options.turnId } : {}),
     ...(options.attemptId ? { attemptId: options.attemptId } : {}),
@@ -2922,22 +3097,6 @@ async function codexAppsMcpRequestInit(
 // level scopes (billing/account/members/api_keys/workspace:admin) are
 // intentionally excluded: they gate no first-party tool and are not agent
 // capabilities. (A finer-grained capability model comes later.)
-const firstPartyMcpPermissions: Permission[] = [
-  "workspace:read",
-  "files:read",
-  "documents:search",
-  "scheduled_tasks:manage",
-  "scheduled_tasks:run",
-  "goals:manage",
-  "sessions:read",
-  "sessions:create",
-  "sessions:control",
-  "variable-sets:use",
-  "variable-sets:manage",
-  "rigs:use",
-  "github:use",
-];
-
 // codex_apps is third-party-by-trust (the external ChatGPT connectors backend)
 // but needs DYNAMIC auth, so it is its own category — deliberately NOT folded
 // into the first-party allowlist, which would wrongly sign an OpenGeni delegated
@@ -3044,6 +3203,8 @@ class PrefixedMcpServer implements MCPServer {
     registryId: string,
     allowedTools?: string[],
     bestEffort = false,
+    private readonly aggregateToolBudget?: McpAggregateToolListBudget,
+    private readonly aggregateSourceId = registryId,
   ) {
     this.name = registryId;
     this.prefix = prefixedMcpToolName(registryId, "");
@@ -3057,13 +3218,27 @@ class PrefixedMcpServer implements MCPServer {
   }
 
   close(): Promise<void> {
+    this.releaseAggregateBudget();
     return this.inner.close();
   }
 
+  releaseAggregateBudget(): void {
+    this.aggregateToolBudget?.remove(this.aggregateSourceId);
+  }
+
   async listTools(): Promise<RuntimeMcpTool[]> {
-    let tools: RuntimeMcpTool[];
     try {
-      tools = await this.inner.listTools();
+      const tools = assertMcpToolListWithinBounds(await this.inner.listTools()) as RuntimeMcpTool[];
+      const exposed = tools
+        .filter((tool) => this.isAllowed(tool.name))
+        .map((tool) => ({
+          ...tool,
+          name: prefixedMcpToolName(this.name, tool.name),
+        }));
+      const bounded = (this.aggregateToolBudget?.replace(this.aggregateSourceId, exposed) ??
+        assertMcpToolListWithinBounds(exposed)) as RuntimeMcpTool[];
+      this.listedToolSchemaTokens = estimateSerializedValueTokens(bounded);
+      return bounded;
     } catch (error) {
       // A REQUIRED server's tools/list failure is fatal (fail-loud default): the
       // caller explicitly requested it, so its absence must fail the turn.
@@ -3092,16 +3267,9 @@ class PrefixedMcpServer implements MCPServer {
           { serverId: this.name, ...safeMcpErrorFields(error) },
         );
       }
+      this.releaseAggregateBudget();
       return [];
     }
-    const exposed = tools
-      .filter((tool) => this.isAllowed(tool.name))
-      .map((tool) => ({
-        ...tool,
-        name: prefixedMcpToolName(this.name, tool.name),
-      }));
-    this.listedToolSchemaTokens = estimateSerializedValueTokens(exposed);
-    return exposed;
   }
 
   /** Latest exact tools/list projection used to build the model request. */
@@ -3119,7 +3287,9 @@ class PrefixedMcpServer implements MCPServer {
       throw new Error(`MCP tool ${unprefixed} is not allowed for server ${this.name}`);
     }
     try {
-      return await this.inner.callTool(unprefixed, args, meta);
+      const output = await this.inner.callTool(unprefixed, args, meta);
+      assertMcpPayloadWithinBytes(output, MCP_MAX_TOOL_RESULT_BYTES, "MCP tool result");
+      return output;
     } catch (error) {
       // The connection broker's auth-needed short-circuit arrives as a thrown
       // JSON-RPC error (an inline isError result would be stripped by the SDK
@@ -4829,6 +4999,7 @@ function usageFromResponse(response: unknown): ModelResponseUsage["usage"] | nul
     ...numberProp(record, "totalTokens", "totalTokens", "total_tokens"),
     ...inputTokenDetailsProp(record),
     ...outputTokenDetailsProp(record),
+    ...requestUsageEntriesProp(record),
   };
   return Object.keys(usage).length > 0 ? usage : null;
 }
@@ -4839,7 +5010,11 @@ function numberProp(
   ...keys: string[]
 ): Partial<ModelResponseUsage["usage"]> {
   const value = keys.map((key) => raw[key]).find((candidate) => candidate !== undefined);
-  return typeof value === "number" && Number.isFinite(value) ? { [outputKey]: value } : {};
+  // Preserve numeric provider values verbatim here, including malformed ones.
+  // The shared usage normalizer is the single bounded validation boundary and
+  // needs to see NaN/infinite/fractional/oversized values so it can emit safe
+  // field-path diagnostics rather than silently erasing the evidence.
+  return typeof value === "number" ? { [outputKey]: value } : {};
 }
 
 function inputTokenDetailsProp(raw: Record<string, unknown>): Partial<ModelResponseUsage["usage"]> {
@@ -4848,7 +5023,7 @@ function inputTokenDetailsProp(raw: Record<string, unknown>): Partial<ModelRespo
     raw.input_tokens_details ??
     raw.promptTokensDetails ??
     raw.prompt_tokens_details;
-  if (!details || typeof details !== "object") {
+  if (details === undefined || details === null) {
     return {};
   }
   return {
@@ -4861,7 +5036,7 @@ function outputTokenDetailsProp(
 ): Partial<ModelResponseUsage["usage"]> {
   const details = raw.outputTokensDetails ?? raw.output_tokens_details;
   const normalized = details ?? raw.completionTokensDetails ?? raw.completion_tokens_details;
-  if (!normalized || typeof normalized !== "object") {
+  if (normalized === undefined || normalized === null) {
     return {};
   }
   return {
@@ -4869,6 +5044,21 @@ function outputTokenDetailsProp(
   };
 }
 
+function requestUsageEntriesProp(
+  raw: Record<string, unknown>,
+): Partial<ModelResponseUsage["usage"]> {
+  const entries = raw.requestUsageEntries ?? raw.request_usage_entries;
+  if (entries === undefined || entries === null) {
+    return {};
+  }
+  return {
+    // The normalizer validates every entry and all supported field aliases.
+    // Preserve the SDK objects rather than rebuilding them and accidentally
+    // dropping provider detail fields such as cache_write_tokens.
+    requestUsageEntries: entries as NonNullable<ModelResponseUsage["usage"]["requestUsageEntries"]>,
+  };
+}
+
 export function serializeApprovals(interruptions: unknown[]): unknown[] {
   return interruptions
     .filter((item) => interruptionToolName(item) !== HUMAN_INPUT_TOOL_NAME)
@@ -5571,6 +5761,17 @@ type RuntimeGitBindingDescriptor = {
   uri: string;
 };
 
+type RuntimeGitHttpBrokerRouteDescriptor = {
+  provider: GitCredentialProvider;
+  credentialBindingId: string;
+  bindingHash: string;
+  repositoryUri: string;
+  brokerUri: string;
+  protocol: "https";
+  host: string;
+  path: string;
+};
+
 function runtimeGitBindingDescriptors(
   resources: Extract<ResourceRef, { kind: "repository" }>[],
 ): RuntimeGitBindingDescriptor[] {
@@ -5614,6 +5815,115 @@ function runtimeGitBindingDescriptors(
   });
 }
 
+function gitCredentialBindingKey(
+  provider: GitCredentialProvider,
+  credentialBindingId: string,
+): string {
+  return `${provider}\u0000${credentialBindingId}`;
+}
+
+function brokeredGitCredentialBindingKeys(
+  bindings: GitCredentialBindingSeed[],
+): ReadonlySet<string> {
+  return new Set(
+    bindings
+      .filter((binding) => binding.transport?.kind === "http_broker")
+      .map((binding) => gitCredentialBindingKey(binding.provider, binding.credentialBindingId)),
+  );
+}
+
+function runtimeGitHttpBrokerRouteDescriptors(
+  resources: Extract<ResourceRef, { kind: "repository" }>[],
+  bindings: GitCredentialBindingSeed[],
+): RuntimeGitHttpBrokerRouteDescriptor[] {
+  const resourceDescriptors = runtimeGitBindingDescriptors(resources);
+  const byBindingAndUri = new Map<string, RuntimeGitBindingDescriptor>();
+  for (const descriptor of resourceDescriptors) {
+    byBindingAndUri.set(
+      `${gitCredentialBindingKey(descriptor.provider, descriptor.credentialBindingId)}\u0000${descriptor.uri}`,
+      descriptor,
+    );
+  }
+
+  const routes: RuntimeGitHttpBrokerRouteDescriptor[] = [];
+  const claimedRepositoryUris = new Set<string>();
+  const claimedBrokerUris = new Set<string>();
+  for (const binding of bindings) {
+    if (!binding.transport) continue;
+    if (
+      typeof binding.transport !== "object" ||
+      binding.transport.kind !== "http_broker" ||
+      !Array.isArray(binding.transport.repositories)
+    ) {
+      throw new Error(
+        `Git credential binding ${binding.credentialBindingId} uses an unsupported transport`,
+      );
+    }
+    const bindingKey = gitCredentialBindingKey(binding.provider, binding.credentialBindingId);
+    const expected = resourceDescriptors.filter(
+      (descriptor) =>
+        gitCredentialBindingKey(descriptor.provider, descriptor.credentialBindingId) === bindingKey,
+    );
+    if (expected.length === 0 || binding.transport.repositories.length !== expected.length) {
+      throw new Error(
+        `Git HTTP broker binding ${binding.credentialBindingId} does not cover its exact repository set`,
+      );
+    }
+    for (const route of binding.transport.repositories) {
+      if (
+        !route ||
+        typeof route !== "object" ||
+        typeof route.repositoryUri !== "string" ||
+        typeof route.brokerUri !== "string"
+      ) {
+        throw new Error(
+          `Git HTTP broker binding ${binding.credentialBindingId} contains an invalid repository route`,
+        );
+      }
+      const descriptor = byBindingAndUri.get(`${bindingKey}\u0000${route.repositoryUri}`);
+      if (!descriptor || claimedRepositoryUris.has(route.repositoryUri)) {
+        throw new Error(
+          `Git HTTP broker binding ${binding.credentialBindingId} contains an unexpected repository route`,
+        );
+      }
+      let brokerUrl: URL;
+      try {
+        brokerUrl = new URL(route.brokerUri);
+      } catch {
+        throw new Error(
+          `Git HTTP broker binding ${binding.credentialBindingId} contains an invalid broker URI`,
+        );
+      }
+      if (
+        brokerUrl.protocol !== "https:" ||
+        brokerUrl.username ||
+        brokerUrl.password ||
+        brokerUrl.search ||
+        brokerUrl.hash ||
+        brokerUrl.href !== route.brokerUri ||
+        claimedBrokerUris.has(brokerUrl.href)
+      ) {
+        throw new Error(
+          `Git HTTP broker binding ${binding.credentialBindingId} contains an unsafe broker URI`,
+        );
+      }
+      claimedRepositoryUris.add(route.repositoryUri);
+      claimedBrokerUris.add(brokerUrl.href);
+      routes.push({
+        provider: binding.provider,
+        credentialBindingId: binding.credentialBindingId,
+        bindingHash: gitCredentialBindingHash(binding.credentialBindingId),
+        repositoryUri: route.repositoryUri,
+        brokerUri: route.brokerUri,
+        protocol: "https",
+        host: brokerUrl.host.toLowerCase(),
+        path: brokerUrl.pathname.replace(/^\/+|\/+$/g, ""),
+      });
+    }
+  }
+  return routes;
+}
+
 function gitUsernameForProvider(provider: GitCredentialProvider): string {
   if (provider === "github") return "x-access-token";
   if (provider === "gitlab") return "oauth2";
@@ -5622,22 +5932,48 @@ function gitUsernameForProvider(provider: GitCredentialProvider): string {
 
 function gitCredentialHelperBindingCaseLines(
   resources: Extract<ResourceRef, { kind: "repository" }>[],
+  bindings: GitCredentialBindingSeed[],
+): string[] {
+  const brokeredBindings = brokeredGitCredentialBindingKeys(bindings);
+  return runtimeGitBindingDescriptors(resources)
+    .filter(
+      (descriptor) =>
+        !brokeredBindings.has(
+          gitCredentialBindingKey(descriptor.provider, descriptor.credentialBindingId),
+        ),
+    )
+    .flatMap((descriptor) => {
+      const paths = new Set([
+        descriptor.path,
+        descriptor.path.replace(/\.git$/, ""),
+        `${descriptor.path.replace(/\.git$/, "")}.git`,
+      ]);
+      return [...paths].map(
+        (path) =>
+          `  ${shellQuote(`${descriptor.protocol}|${descriptor.host}|${path}`)}) username=${shellQuote(gitUsernameForProvider(descriptor.provider))}; token_file="$credential_dir/${descriptor.bindingHash}-token" ;;`,
+      );
+    });
+}
+
+function gitCredentialHelperBrokerCaseLines(
+  routes: RuntimeGitHttpBrokerRouteDescriptor[],
 ): string[] {
-  return runtimeGitBindingDescriptors(resources).flatMap((descriptor) => {
+  return routes.flatMap((route) => {
     const paths = new Set([
-      descriptor.path,
-      descriptor.path.replace(/\.git$/, ""),
-      `${descriptor.path.replace(/\.git$/, "")}.git`,
+      route.path,
+      route.path.replace(/\.git$/, ""),
+      `${route.path.replace(/\.git$/, "")}.git`,
     ]);
     return [...paths].map(
       (path) =>
-        `  ${shellQuote(`${descriptor.protocol}|${descriptor.host}|${path}`)}) username=${shellQuote(gitUsernameForProvider(descriptor.provider))}; token_file="$credential_dir/${descriptor.bindingHash}-token" ;;`,
+        `  ${shellQuote(`${route.protocol}|${route.host}|${path}`)}) username=opengeni; token_file="$credential_dir/${route.bindingHash}-token" ;;`,
     );
   });
 }
 
 function gitAskpassHostProviderCaseLines(
   resources: Extract<ResourceRef, { kind: "repository" }>[],
+  brokerRoutes: RuntimeGitHttpBrokerRouteDescriptor[],
 ): string[] {
   const hosts = new Map<string, { provider: GitCredentialProvider; bindings: Set<string> }>();
   for (const descriptor of runtimeGitBindingDescriptors(resources)) {
@@ -5648,13 +5984,19 @@ function gitAskpassHostProviderCaseLines(
     entry.bindings.add(`${descriptor.provider}\u0000${descriptor.credentialBindingId}`);
     hosts.set(descriptor.host, entry);
   }
-  return [...hosts.entries()]
-    .filter(([, entry]) => entry.bindings.size === 1)
-    .sort(([a], [b]) => a.localeCompare(b))
-    .map(
-      ([hostname, entry]) =>
-        `    ${shellQuote(hostname)}) printf '%s\\n' ${entry.provider}; return 0 ;;`,
-    );
+  const brokerHosts = [...new Set(brokerRoutes.map((route) => route.host))]
+    .sort((a, b) => a.localeCompare(b))
+    .map((hostname) => `    ${shellQuote(hostname)}) printf '\\n'; return 0 ;;`);
+  return [
+    ...brokerHosts,
+    ...[...hosts.entries()]
+      .filter(([, entry]) => entry.bindings.size === 1)
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(
+        ([hostname, entry]) =>
+          `    ${shellQuote(hostname)}) printf '%s\\n' ${entry.provider}; return 0 ;;`,
+      ),
+  ];
 }
 
 function gitCredentialTokenWriterCommandLines(bindings: GitCredentialBindingSeed[] = []): string[] {
@@ -5664,7 +6006,7 @@ function gitCredentialTokenWriterCommandLines(bindings: GitCredentialBindingSeed
     const count = Math.max(1, binding.providerBindingCount ?? 1);
     const provider = binding.provider;
     const lines = [`write_git_binding_token ${shellQuote(hash)} "\${${seedEnv}:-}"`];
-    if (count === 1) {
+    if (count === 1 && binding.transport?.kind !== "http_broker") {
       lines.push(`write_git_provider_token ${shellQuote(provider)} "\${${seedEnv}:-}"`);
     } else {
       lines.push(`remove_git_provider_token ${shellQuote(provider)}`);
@@ -5726,14 +6068,45 @@ function gitCredentialTokenWriterCommandLines(bindings: GitCredentialBindingSeed
   ];
 }
 
+function gitHttpBrokerConfigCommandLines(routes: RuntimeGitHttpBrokerRouteDescriptor[]): string[] {
+  return [
+    'git_http_broker_config="${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}/http-broker.gitconfig"',
+    'mkdir -p "$(dirname "$git_http_broker_config")"',
+    'broker_umask="$(umask)"',
+    "umask 077",
+    ': > "$git_http_broker_config.tmp.$$"',
+    ...routes.map(
+      (route) =>
+        `git config --file "$git_http_broker_config.tmp.$$" --add ${shellQuote(`url.${route.brokerUri}.insteadOf`)} ${shellQuote(route.repositoryUri)}`,
+    ),
+    'mv -f "$git_http_broker_config.tmp.$$" "$git_http_broker_config"',
+    'umask "$broker_umask"',
+    'git config --global --unset-all include.path "$git_http_broker_config" >/dev/null 2>&1 || true',
+    'git config --global --add include.path "$git_http_broker_config"',
+  ];
+}
+
 function gitCredentialHelperCommandLines(
   resources: Extract<ResourceRef, { kind: "repository" }>[] = [],
   bindings: GitCredentialBindingSeed[] = [],
 ): string[] {
-  const hostProviderCases = gitAskpassHostProviderCaseLines(resources);
-  const bindingCases = gitCredentialHelperBindingCaseLines(resources);
+  const brokerRoutes = runtimeGitHttpBrokerRouteDescriptors(resources, bindings);
+  const hostProviderCases = gitAskpassHostProviderCaseLines(resources, brokerRoutes);
+  const bindingCases = [
+    ...gitCredentialHelperBindingCaseLines(resources, bindings),
+    ...gitCredentialHelperBrokerCaseLines(brokerRoutes),
+  ];
   const descriptors = runtimeGitBindingDescriptors(resources);
-  const wrapperDescriptors = bindings.length > 0 ? descriptors : [];
+  const brokeredBindings = brokeredGitCredentialBindingKeys(bindings);
+  const wrapperDescriptors =
+    bindings.length > 0
+      ? descriptors.filter(
+          (descriptor) =>
+            !brokeredBindings.has(
+              gitCredentialBindingKey(descriptor.provider, descriptor.credentialBindingId),
+            ),
+        )
+      : [];
   const bindingProviders = new Map<GitCredentialProvider, Set<string>>();
   for (const descriptor of runtimeGitBindingDescriptors(resources)) {
     const ids = bindingProviders.get(descriptor.provider) ?? new Set<string>();
@@ -5766,6 +6139,31 @@ function gitCredentialHelperCommandLines(
           .filter(([, ids]) => ids.size > 1)
           .map(([provider]) => provider)
       : [];
+  const brokeredOriginCases = brokerRoutes.flatMap((route) => {
+    const base = route.repositoryUri.replace(/\.git$/, "");
+    return [...new Set([route.repositoryUri, base, `${base}.git`])].map(
+      (uri) => `    ${shellQuote(`${route.provider}|${uri}`)}) return 0 ;;`,
+    );
+  });
+  const brokeredBindingHashCases = bindings
+    .filter((binding) => binding.transport?.kind === "http_broker")
+    .map(
+      (binding) =>
+        `    ${shellQuote(`${binding.provider}|${gitCredentialBindingHash(binding.credentialBindingId)}`)}) return 0 ;;`,
+    );
+  const providerBindingKinds = new Map<
+    GitCredentialProvider,
+    { direct: number; brokered: number }
+  >();
+  for (const binding of bindings) {
+    const counts = providerBindingKinds.get(binding.provider) ?? { direct: 0, brokered: 0 };
+    if (binding.transport?.kind === "http_broker") counts.brokered += 1;
+    else counts.direct += 1;
+    providerBindingKinds.set(binding.provider, counts);
+  }
+  const brokerOnlyProviders = [...providerBindingKinds.entries()]
+    .filter(([, counts]) => counts.brokered > 0 && counts.direct === 0)
+    .map(([provider]) => provider);
   return [
     ...gitCredentialTokenWriterCommandLines(bindings),
     // Provision git/provider-CLI helpers at SETUP (runtime) before any clone
@@ -5857,6 +6255,7 @@ function gitCredentialHelperCommandLines(
     "git config --global --add credential.helper ''",
     'git config --global --add credential.helper "$git_credential_helper"',
     "git config --global credential.useHttpPath true",
+    ...gitHttpBrokerConfigCommandLines(brokerRoutes),
     'wrapper_dir="${OPENGENI_GIT_CLI_WRAPPER_DIR:-$HOME/.opengeni/bin}"',
     'mkdir -p "$wrapper_dir"',
     "for opengeni_git_cli_tool in gh glab az; do",
@@ -5884,12 +6283,24 @@ function gitCredentialHelperCommandLines(
     "    *) return 1 ;;",
     "  esac",
     "}",
+    "binding_hash_is_brokered() {",
+    '  case "$provider|$1" in',
+    ...brokeredBindingHashCases,
+    "    *) return 1 ;;",
+    "  esac",
+    "}",
     "binding_hash_for_origin() {",
     '  case "$provider|$1" in',
     ...originWrapperHashes,
     "    *) return 1 ;;",
     "  esac",
     "}",
+    "origin_is_brokered() {",
+    '  case "$provider|$1" in',
+    ...brokeredOriginCases,
+    "    *) return 1 ;;",
+    "  esac",
+    "}",
     "sole_binding_hash() {",
     '  case "$provider" in',
     ...soleWrapperHashes,
@@ -5897,19 +6308,25 @@ function gitCredentialHelperCommandLines(
     "  esac",
     "}",
     `multi_binding_providers=${shellQuote(multiWrapperProviders.join(" "))}`,
+    `broker_only_providers=${shellQuote(brokerOnlyProviders.join(" "))}`,
     'if [ -n "$provider" ]; then',
     "  binding_hash=",
     '  if [ -n "${OPENGENI_GIT_BINDING:-}" ]; then',
     '    binding_hash="$(hash_binding_id "$OPENGENI_GIT_BINDING")"',
+    '    binding_hash_is_brokered "$binding_hash" && { printf \'%s\\n\' "$tool provider API authentication is host-brokered for OPENGENI_GIT_BINDING; use the configured provider MCP tools" >&2; exit 2; }',
     '    binding_hash_allowed "$binding_hash" || { printf \'%s\\n\' "OPENGENI_GIT_BINDING does not select a $provider credential attached to this session" >&2; exit 2; }',
     "  elif command -v git >/dev/null 2>&1; then",
     '    origin="$(git config --get remote.origin.url 2>/dev/null || true)"',
+    '    [ -z "$origin" ] || ! origin_is_brokered "$origin" || { printf \'%s\\n\' "$tool provider API authentication is host-brokered for this repository; use the configured provider MCP tools" >&2; exit 2; }',
     '    [ -z "$origin" ] || binding_hash="$(binding_hash_for_origin "$origin" 2>/dev/null || true)"',
     "  fi",
     '  [ -n "$binding_hash" ] || binding_hash="$(sole_binding_hash 2>/dev/null || true)"',
     '  if [ -n "$binding_hash" ]; then',
     '    token_file="${OPENGENI_GIT_CREDENTIALS_DIR:-$HOME/.opengeni/git-credentials}/$binding_hash-token"',
     "  else",
+    '    case " $broker_only_providers " in',
+    '      *" $provider "*) printf \'%s\\n\' "$tool provider API authentication is host-brokered for this session; use the configured provider MCP tools" >&2; exit 2 ;;',
+    "    esac",
     '    case " $multi_binding_providers " in',
     '      *" $provider "*) printf \'%s\\n\' "Unable to select one of multiple $provider credentials; run inside an attached repository or set OPENGENI_GIT_BINDING" >&2; exit 2 ;;',
     "    esac",