@opengeni/runtime 0.3.0 → 0.4.0

package/src/index.ts

@@ -1,6 +1,6 @@
 import type { ConfiguredModel, ContextCompactionMode, ModelProviderApi, ResolvedModelProvider, Settings } from "@opengeni/config";
 import { AGENT_INSTRUCTIONS_CORE_PLACEHOLDER, collectSandboxEnvironment, contextInputBudgetTokens, contextServerCompactThreshold, firstPartyMcpBaseUrl, parseExposedPorts, resolveContextCompactionMode, resolveModelProvider, sandboxLifecycleHookIds } from "@opengeni/config";
-import { CAPABILITY_DESCRIPTORS, isClearedRunStateBlob, signDelegatedAccessToken, type Permission, type ReasoningEffort, type ResourceRef, type SessionEventType, type ToolRef } from "@opengeni/contracts";
+import { CAPABILITY_DESCRIPTORS, isClearedRunStateBlob, prefixedMcpToolName as sharedPrefixedMcpToolName, signDelegatedAccessToken, type McpServerConnectionRef, type Permission, type ReasoningEffort, type ResourceRef, type SessionEventType, type ToolAuthNeededPayload, type ToolRef } from "@opengeni/contracts";
 import {
   Agent,
   AgentsError,
@@ -27,6 +27,7 @@ import {
   setDefaultOpenAIClient,
   setDefaultOpenAIKey,
   setOpenAIResponsesTransport,
+  setTracingDisabled,
   // Hosted web_search tool factory. Re-exported from @openai/agents-openai via
   // `export * from '@openai/agents-openai'` in @openai/agents' index (0.11.6);
   // it returns a { type: 'hosted_tool', providerData: { type: 'web_search' } }
@@ -42,9 +43,11 @@ import {
   type AgentInputItem,
   type CallModelInputFilter,
   type MCPServer,
+  type MCPToolErrorFunction,
   type Model,
   type ModelProvider,
   type RunStreamEvent,
+  type Tool,
 } from "@openai/agents";
 import {
   localDirLazySkillSource,
@@ -101,6 +104,9 @@ import {
   setSelfhostedApplyDiff,
 } from "./sandbox";
 import { computerUse, type ComputerToolMode } from "./sandbox-computer";
+import type { RuntimeMetricsHooks } from "./metrics";
+
+export type { RuntimeMetricsHooks } from "./metrics";
 
 // P4.3 computer-use surface (the agent's :0 driver). Re-exported from the barrel
 // so callers (the worker, live proofs) reach SandboxComputer/ComputerUseCapability
@@ -145,8 +151,10 @@ export { OpenAIChatCompletionsModel, OpenAIResponsesModel } from "@openai/agents
 export {
   CompactionNeededError,
   buildCompactionPromptInput,
+  buildDeterministicFallbackCompactionHistory,
   buildCompactionReplacementHistory,
   clientCompactionThresholdTokens,
+  clampCompactionThresholdRatio,
   decideClientCompaction,
   enforceInputBudget,
   buildSummaryItem,
@@ -160,7 +168,9 @@ export {
   COMPACTION_SUMMARY_MARKER,
   COMPACTION_PROMPT,
   COMPACT_USER_MESSAGE_MAX_TOKENS,
-  CLIENT_COMPACTION_TRIGGER_FRACTION,
+  DEFAULT_COMPACTION_THRESHOLD_RATIO,
+  MIN_COMPACTION_THRESHOLD_RATIO,
+  MAX_COMPACTION_THRESHOLD_RATIO,
   SUMMARY_BUFFER_TOKENS,
   SUMMARY_PREFIX,
   USER_MESSAGE_TRUNCATION_MARKER,
@@ -193,6 +203,29 @@ export type ModelResponseUsage = {
 
 type RuntimeMcpTool = Awaited<ReturnType<MCPServer["listTools"]>>[number];
 
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export type ResolveConnectionCredentialInput = {
+  workspaceId: string;
+  subjectId?: string;
+  serverId: string;
+  toolName?: string;
+  connectionRef: McpServerConnectionRef;
+  forceRefresh?: boolean;
+};
+
+export type ResolveConnectionCredentialResult =
+  | { status: "ok"; headers: Record<string, string>; connectionId: string; expiresAt?: Date | null }
+  | {
+    status: "auth_needed";
+    reason: ToolAuthNeededPayload["reason"];
+    providerDomain: string;
+    connectionId?: string;
+    scopes?: string[];
+    resource?: string;
+    authorizationUrl?: string;
+  };
+
 export function ensureReadableStreamFrom(): void {
   const ctor = globalThis.ReadableStream as (typeof ReadableStream & {
     from?: <T>(source: Iterable<T> | AsyncIterable<T>) => ReadableStream<T>;
@@ -253,6 +286,12 @@ export type SandboxFileDownload = {
   sizeBytes?: number;
 };
 
+let runtimeMetricsHooks: RuntimeMetricsHooks | null = null;
+
+export function configureRuntimeMetricsHooks(hooks: RuntimeMetricsHooks | null | undefined): void {
+  runtimeMetricsHooks = hooks ?? null;
+}
+
 export type OpenGeniRuntime = {
   configure: (settings: Settings) => void;
   // Multi-provider per-turn model routing. Returns the resolved provider, its
@@ -270,11 +309,15 @@ export type OpenGeniRuntime = {
 export type ProductionRuntimeOverrides = {
   model?: Model;
   sandboxClient?: unknown;
+  metrics?: RuntimeMetricsHooks;
 };
 
 export function createProductionAgentRuntime(overrides: ProductionRuntimeOverrides = {}): OpenGeniRuntime {
   return {
-    configure: configureOpenAI,
+    configure: (settings) => {
+      configureRuntimeMetricsHooks(overrides.metrics);
+      configureOpenAI(settings);
+    },
     // A test/override model shadows the registry routing entirely (the scripted
     // model used in worker tests is not in any provider's allow-list), so when
     // one is supplied resolveTurnModel reports "no resolution" and the caller
@@ -301,7 +344,7 @@ export function createProductionAgentRuntime(overrides: ProductionRuntimeOverrid
  * the OpenAI-platform path has only a key (the SDK default client is used via
  * setDefaultOpenAIKey there); the caller then constructs a key-only client.
  */
-export function buildOpenAIClientFromSettings(settings: Settings): OpenAI {
+export function buildOpenAIClientFromSettings(settings: Settings, providerId: string = settings.openaiProvider): OpenAI {
   if (settings.openaiProvider === "azure") {
     const baseURL = settings.azureOpenaiBaseUrl ?? azureDeploymentBaseUrl(settings);
     const apiKey = settings.azureOpenaiApiKey ?? settings.azureOpenaiAdToken ?? "azure-ad-token";
@@ -318,13 +361,14 @@ export function buildOpenAIClientFromSettings(settings: Settings): OpenAI {
       // seam — below the SDK responses converter, which always re-synthesizes BOTH
       // `action` and `actions` (rejected 400 "exactly one of action or actions").
       // See computerCallNormalizingFetch / rewriteComputerCallsToActionsOnly.
-      fetch: computerCallNormalizingFetch(globalThis.fetch),
+      fetch: computerCallNormalizingFetch(instrumentedModelFetch(providerId, globalThis.fetch)),
     });
   }
   return new OpenAI({
     apiKey: settings.openaiApiKey ?? process.env.OPENAI_API_KEY,
     ...(settings.openaiBaseUrl ? { baseURL: settings.openaiBaseUrl } : {}),
     maxRetries: settings.openaiMaxRetries,
+    fetch: instrumentedModelFetch(providerId, globalThis.fetch),
   });
 }
 
@@ -346,7 +390,7 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
     return cached;
   }
   const client = provider.builtin
-    ? buildOpenAIClientFromSettings(settings)
+    ? buildOpenAIClientFromSettings(settings, provider.id)
     : provider.kind === "codex-subscription"
       // Codex subscription: the static apiKey is a placeholder — the real per-request
       // bearer + ChatGPT-Account-ID, the /responses->/codex/responses rewrite, and the
@@ -358,7 +402,7 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
         apiKey: provider.apiKey ?? "codex-subscription",
         ...(provider.baseUrl ? { baseURL: provider.baseUrl } : {}),
         maxRetries: settings.openaiMaxRetries,
-        fetch: codexSubscriptionFetch(globalThis.fetch),
+        fetch: codexSubscriptionFetch(instrumentedModelFetch(provider.id, globalThis.fetch)),
       })
     // ResolvedModelProvider.apiKey is already the resolved key (configuredProviders
     // ran resolveProviderApiKey at config time, collapsing apiKey/apiKeyEnv), so it
@@ -369,6 +413,7 @@ export function buildProviderClient(provider: ResolvedModelProvider, settings: S
       maxRetries: settings.openaiMaxRetries,
       ...(provider.defaultQuery ? { defaultQuery: provider.defaultQuery } : {}),
       ...(provider.defaultHeaders ? { defaultHeaders: provider.defaultHeaders } : {}),
+      fetch: instrumentedModelFetch(provider.id, globalThis.fetch),
     });
   providerClientCache.set(provider.id, client);
   return client;
@@ -521,6 +566,7 @@ export class CodexSubscriptionUnavailableError extends Error {
 
 export function configureOpenAI(settings: Settings): void {
   setOpenAIResponsesTransport(settings.openaiResponsesTransport);
+  setTracingDisabled(settings.disableOpenaiTracing || !settings.observabilityOtlpEndpoint);
   // Install the registry-aware router as the process default model provider so a
   // model name re-resolved on the SandboxAgent/Modal path (where a Model instance
   // does not survive) routes to its provider instead of the built-in client.
@@ -540,13 +586,59 @@ export function configureOpenAI(settings: Settings): void {
   setDefaultModelProvider(router);
 }
 
+function instrumentedModelFetch(provider: string, inner: typeof fetch): typeof fetch {
+  return (async (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => {
+    if (!isModelCallFetch(input)) {
+      return await inner(input, init);
+    }
+    const started = performance.now();
+    try {
+      const response = await inner(input, init);
+      recordModelCallMetric(provider, response.ok ? "completed" : "failed", started);
+      return response;
+    } catch (error) {
+      recordModelCallMetric(provider, "failed", started);
+      throw error;
+    }
+  }) as typeof fetch;
+}
+
+function isModelCallFetch(input: Parameters<typeof fetch>[0]): boolean {
+  const rawUrl = typeof input === "string"
+    ? input
+    : input instanceof URL
+      ? input.toString()
+      : (input as { url?: unknown }).url;
+  if (typeof rawUrl !== "string" || rawUrl.length === 0) {
+    return false;
+  }
+  try {
+    const pathname = new URL(rawUrl, "http://opengeni.local").pathname;
+    return pathname.endsWith("/responses")
+      || pathname.endsWith("/chat/completions")
+      || pathname.endsWith("/codex/responses");
+  } catch {
+    return /\/(?:codex\/)?responses(?:\?|$)|\/chat\/completions(?:\?|$)/.test(rawUrl);
+  }
+}
+
+function recordModelCallMetric(provider: string, outcome: "completed" | "failed", started: number): void {
+  const durationSeconds = Math.max(0, (performance.now() - started) / 1000);
+  try {
+    runtimeMetricsHooks?.onModelCall?.({ provider, outcome, durationSeconds });
+  } catch {
+    // Metrics emission must never affect a model call.
+  }
+}
+
 /**
  * Run the compaction summarizer as one plain, tool-less, non-streaming model
  * call against the resolved provider. `input` is the active history plus
  * Codex's checkpoint prompt. Returns the trimmed summary text, or null on any
- * failure (the caller treats a failed summarize as "skip compaction this turn"
- * - never fatal). The call deliberately does NOT request reasoning encryption,
- * tools, or server-side compaction; it is a self-contained summarize.
+ * failure (the caller can retry with a harder-trimmed transcript, then fall
+ * back to deterministic non-LLM compaction). The call deliberately does NOT
+ * request reasoning encryption, tools, or server-side compaction; it is a
+ * self-contained summarize.
  *
  * Provider-aware: the summary always runs on the SAME provider that serves the
  * turn (registry providers can't summarize through OpenAI/Azure, and vice
@@ -560,18 +652,24 @@ export function configureOpenAI(settings: Settings): void {
 export async function summarizeForCompaction(
   settings: Settings,
   input: Array<Record<string, unknown>>,
-  options: { client?: OpenAI; api?: ModelProviderApi; maxOutputTokens?: number; model?: string } = {},
+  options: { client?: OpenAI; api?: ModelProviderApi; maxOutputTokens?: number; model?: string; maxTranscriptTokens?: number } = {},
 ): Promise<string | null> {
   const client = options.client ?? buildOpenAIClientFromSettings(settings);
   const api = options.api ?? "responses";
   const model = options.model ?? settings.openaiModel;
   const maxTokens = options.maxOutputTokens ?? SUMMARY_BUFFER_TOKENS;
+  const transcript = renderCompactionPromptInputForChat(
+    input,
+    typeof options.maxTranscriptTokens === "number" && options.maxTranscriptTokens > 0
+      ? { maxEstimatedTokens: options.maxTranscriptTokens }
+      : {},
+  );
   try {
     if (api === "chat") {
       const completion = await client.chat.completions.create({
         model,
         max_tokens: maxTokens,
-        messages: [{ role: "user", content: renderCompactionPromptInputForChat(input) }],
+        messages: [{ role: "user", content: transcript }],
       } as any);
       const text = (completion as { choices?: Array<{ message?: { content?: unknown } }> }).choices?.[0]?.message?.content;
       const trimmed = typeof text === "string" ? text.trim() : "";
@@ -584,13 +682,13 @@ export async function summarizeForCompaction(
       // built-in path (api "responses"), so gate it on the built-in provider.
       ...(settings.openaiProvider === "azure" ? {} : { store: false }),
       max_output_tokens: maxTokens,
-      input,
+      input: transcript,
     } as any);
     const text = extractResponseOutputText(response);
     const trimmed = text.trim();
     return trimmed.length > 0 ? trimmed : null;
   } catch (error) {
-    console.error("context compaction summarize failed (compaction skipped this turn)", error);
+    console.error("context compaction summarize failed", error);
     return null;
   }
 }
@@ -718,6 +816,11 @@ export type BuildAgentOptions = {
   // seeds it to the box's token FILE before the clone runs. Omitted on the
   // selfhosted path (the machine uses its own git creds) — a NO-OP there.
   gitTokenSeed?: string;
+  // TOOLSPACE: the run-scoped delegated token to seed into
+  // $OPENGENI_TOOLSPACE_TOKEN_FILE. Like gitTokenSeed, this stays off the
+  // manifest/env delta and is written into the sandbox filesystem by a lifecycle
+  // hook before the agent starts.
+  toolspaceTokenSeed?: string;
   // Genesis turn only: append a one-shot instruction to the agent's system
   // prompt telling it to title the session via opengeni__set_session_title
   // before responding. Delivered through the instructions channel (where the
@@ -851,11 +954,48 @@ const agentRepositoryCloneHooks = new WeakMap<object, SandboxLifecycleHook[]>();
 // session env; runStream reads it to build the clone hook context. Absent when
 // no repo is attached / on the selfhosted path.
 const agentGitTokenSeed = new WeakMap<object, string>();
+const agentToolspaceTokenSeed = new WeakMap<object, string>();
 // The EFFECTIVE backend the turn resolved for this agent (undefined -> the home
 // backend). Read by runStream's owned branch to keep platform box-setup hooks off
 // connected machines (a user's real computer).
 const agentActiveSandboxBackend = new WeakMap<object, Settings["sandboxBackend"]>();
 
+/**
+ * The tool output emitted for an MCP tool call that FAILED with a THROWN error
+ * — a JSON-RPC protocol error (e.g. -32602 invalid params), an auth 401/403, a
+ * transport failure, a timeout, or tool-not-found. Shaped as an MCP
+ * `{ isError: true, content }` result so the failure is CARRIED on the tool
+ * output rather than erased.
+ *
+ * The SDK's `defaultToolErrorFunction` would instead turn a thrown tool error
+ * into a plain STRING ("An error occurred while running the tool…") returned as
+ * a NORMAL, successful-looking result — so `agent.toolCall.output` carried no
+ * error signal and the timeline rendered the failure as success. `normalizeSdkEvent`
+ * captures `RunToolCallOutputItem.output` (the raw function return) verbatim, so
+ * returning this object makes the emitted payload's `output.isError === true`,
+ * which the timeline projection's `isErrorOutput` (packages/react/src/timeline/
+ * projection.ts) settles to "failed" and downstream client normalizers read the same field.
+ *
+ * SCOPE: this only covers THROWN MCP failures (the ones that reach an
+ * errorFunction). An MCP tool result carrying `isError: true` INLINE alongside
+ * content is stripped to its `content` by @openai/agents-core's streamable-http
+ * shim (dist/shims/mcp-server/node.js `callTool` returns `parsed.content`,
+ * dropping `parsed.isError`) BEFORE the runtime ever sees it. Covering that mode
+ * requires an SDK-level change (preserve `isError`) or reading the raw
+ * CallToolResult — tracked separately.
+ */
+export function mcpToolErrorOutput(error: unknown): { isError: true; content: [{ type: "text"; text: string }] } {
+  const details = error instanceof Error ? error.message : String(error);
+  return { isError: true, content: [{ type: "text", text: `An error occurred while running the tool. Please try again. Error: ${details}` }] };
+}
+
+// Applied to EVERY MCP server via the agent's `mcpConfig.errorFunction`
+// (server-level errorFunctions would win, but PrefixedMcpServer sets none). The
+// SDK types the return as `string`; the runtime actually stores the raw return
+// as the tool output, so we return the MCP-shaped error object and cast — this
+// is the only way to attach an `isError` flag to a failed MCP tool call's output.
+const mcpToolErrorFunction: MCPToolErrorFunction = ({ error }) => mcpToolErrorOutput(error) as unknown as string;
+
 export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[], options: BuildAgentOptions = {}): Agent<any, any> {
   // Resolved per-turn gating. Each override defaults to today's settings-derived
   // behaviour, so the legacy global-client callers (no resolved model) build the
@@ -931,11 +1071,19 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
     // spread; the SDK concatenates these with MCP and sandbox capability tools.
     ...(hostedTools.length ? { tools: hostedTools } : {}),
     ...(options.mcpServers?.length ? { mcpServers: options.mcpServers } : {}),
+    // Surface FAILED MCP tool calls as `{ isError: true }` tool output (see
+    // mcpToolErrorFunction / mcpToolErrorOutput) instead of the SDK's default
+    // flat error string, so a thrown MCP failure (protocol error, auth, timeout,
+    // tool-not-found) settles the timeline tool to "failed" rather than rendering
+    // as success. Applies to every MCP server on this agent (session, first-party,
+    // capability, codex_apps) since none set a server-level errorFunction.
+    mcpConfig: { errorFunction: mcpToolErrorFunction },
   } as const;
 
   if (settings.sandboxBackend === "none") {
     const agent = new Agent(baseConfig);
     maybeInstallCodexToolSearch(agent, settings, options);
+    applyMcpApprovalPolicy(agent, settings);
     return agent;
   }
 
@@ -966,7 +1114,11 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
   if (options.gitTokenSeed) {
     agentGitTokenSeed.set(agent, options.gitTokenSeed);
   }
+  if (options.toolspaceTokenSeed) {
+    agentToolspaceTokenSeed.set(agent, options.toolspaceTokenSeed);
+  }
   maybeInstallCodexToolSearch(agent, settings, options);
+  applyMcpApprovalPolicy(agent, settings);
   return agent;
 }
 
@@ -988,6 +1140,101 @@ function maybeInstallCodexToolSearch(agent: Agent<any, any>, settings: Settings,
   }
 }
 
+/** 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));
+}
+
+/** A per-server approval policy keyed by the server's `<id>__` tool prefix. */
+type McpApprovalPolicy = { prefix: string; requireApproval: boolean | string[] };
+
+/** The subset of the agent surface the approval wrap needs — including `clone`. */
+type ApprovalCapableAgent = {
+  getMcpTools: (runContext: unknown) => Promise<Tool<any>[]>;
+  clone?: (config: unknown) => ApprovalCapableAgent;
+};
+
+/**
+ * Install the approval wrap on a single agent instance: replace `getMcpTools`
+ * with one that stamps `needsApproval: () => true` on every MCP tool whose
+ * server policy demands it. Tools are matched by the server's `<id>__` prefix
+ * (LONGEST prefix first — see {@link applyMcpApprovalPolicy}), then the
+ * unprefixed tool name.
+ *
+ * CLONE SURVIVAL (mirrors {@link installCodexToolSearch}): the sandbox runtime
+ * resolves tools not on the agent we build here but on a FRESH clone —
+ * `prepareSandboxAgent` calls `agent.clone(...)`, and `SandboxAgent.clone`
+ * reconstructs from a FIXED field list (name/tools/mcpServers/…), so an
+ * instance-own `getMcpTools` override is dropped and approval would silently
+ * bypass on every sandbox turn. We therefore also wrap `clone` to RE-INSTALL the
+ * policy onto every clone, recursively — covering clone-of-clone and the resume
+ * paths. The base (non-sandbox) `Agent.clone` spreads `...this` and would carry
+ * the override, but re-installing is idempotent there and keeps one code path.
+ */
+function installMcpApprovalPolicy(agent: ApprovalCapableAgent, policies: McpApprovalPolicy[]): void {
+  const listMcpTools = agent.getMcpTools.bind(agent);
+  agent.getMcpTools = async (runContext: unknown) => {
+    const tools = await listMcpTools(runContext);
+    return tools.map((tool) => {
+      if (tool.type !== "function") {
+        return tool;
+      }
+      const policy = policies.find((entry) => tool.name.startsWith(entry.prefix));
+      if (!policy) {
+        return tool;
+      }
+      const unprefixed = tool.name.slice(policy.prefix.length);
+      return mcpToolRequiresApproval(policy.requireApproval, unprefixed)
+        ? { ...tool, needsApproval: async () => true }
+        : tool;
+    });
+  };
+  const originalClone = agent.clone?.bind(agent);
+  if (originalClone) {
+    agent.clone = (config: unknown) => {
+      const cloned = originalClone(config);
+      installMcpApprovalPolicy(cloned, policies);
+      return cloned;
+    };
+  }
+}
+
+/**
+ * Enforce per-MCP-server human approval. `settings.mcpServers[].requireApproval`
+ * is `true` (every tool of that server requires approval) or a string[] of
+ * UNPREFIXED tool names (only those do); absent = auto-run. The SDK converts MCP
+ * tools to function tools with `needsApproval` unset (defaults false) and exposes
+ * no per-server/agent approval knob, so we wrap the agent's `getMcpTools` to
+ * attach a `needsApproval: () => true` predicate to the matching tools — matched
+ * by the server's `<id>__` prefix, then the unprefixed tool name. A tool that
+ * needs approval raises a run INTERRUPTION, which the worker turns into
+ * `session.requiresAction` and resolves via `user.approvalDecision`
+ * (resumeApproval) — the same generic path shell/computer-use approvals use, so
+ * no extra plumbing. No-op when no server requests approval, so the default
+ * (auto-run everything) is byte-for-byte unchanged.
+ *
+ * Two robustness properties the wrap must hold:
+ *  - LONGEST-PREFIX-FIRST. Server ids can be prefixes of one another (`my` vs
+ *    `my_`), so their tool prefixes collide (`my__` vs `my___`): a tool like
+ *    `my___run` (from server `my_`) also `startsWith` `my__` (server `my`). A
+ *    first-match `find` over unsorted policies could bind it to the WRONG
+ *    server's policy and bypass gating. Sorting policies by DESCENDING prefix
+ *    length makes the most-specific (longest) prefix win, so each tool resolves
+ *    to its own server.
+ *  - CLONE SURVIVAL. The wrap is re-installed onto every clone; see
+ *    {@link installMcpApprovalPolicy}.
+ */
+function applyMcpApprovalPolicy(agent: Agent<any, any>, settings: Settings): void {
+  const policies: McpApprovalPolicy[] = settings.mcpServers
+    .filter((server) => server.requireApproval === true || (Array.isArray(server.requireApproval) && server.requireApproval.length > 0))
+    .map((server) => ({ prefix: prefixedMcpToolName(server.id, ""), requireApproval: server.requireApproval as boolean | string[] }))
+    .sort((a, b) => b.prefix.length - a.prefix.length);
+  if (policies.length === 0) {
+    return;
+  }
+  installMcpApprovalPolicy(agent as unknown as ApprovalCapableAgent, policies);
+}
+
 /**
  * Force a sandbox capability to emit its FUNCTION-transport tool variants instead
  * of the hosted ones, by dropping the model instance the SDK's transport
@@ -1156,6 +1403,8 @@ export type PrepareToolsOptions = {
   // delegated token (manager-style sessions). The caller is responsible for
   // having validated the set against the session creator's grant.
   firstPartyPermissions?: Permission[];
+  resolveCredential?: (input: ResolveConnectionCredentialInput) => Promise<ResolveConnectionCredentialResult>;
+  onAuthNeeded?: (payload: ToolAuthNeededPayload) => Promise<void> | void;
 };
 
 export async function prepareAgentTools(settings: Settings, tools: ToolRef[], options: PrepareToolsOptions = {}): Promise<PreparedAgentTools> {
@@ -1173,6 +1422,12 @@ export async function prepareAgentTools(settings: Settings, tools: ToolRef[], op
       throw new Error(`Unknown MCP server id: ${tool.id}`);
     }
     const url = firstPartyMcpServerUrlForRun(settings, config, options.workspaceId) ?? config.url;
+    const baseFetch = isCodexAppsMcpServer(config)
+      ? codexAppsSanitizingFetch(globalThis.fetch, codexConnectorNamespaces)
+      : globalThis.fetch;
+    const fetchImpl = config.connectionRef
+      ? connectionBrokerFetch(baseFetch, config, options)
+      : baseFetch;
     const server = new PrefixedMcpServer(new MCPServerStreamableHttp({
       url,
       name: config.name ?? config.id,
@@ -1181,7 +1436,7 @@ export async function prepareAgentTools(settings: Settings, tools: ToolRef[], op
       // 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).
-      ...(isCodexAppsMcpServer(config) ? { fetch: codexAppsSanitizingFetch(globalThis.fetch, codexConnectorNamespaces) } : {}),
+      ...(fetchImpl !== globalThis.fetch ? { fetch: fetchImpl } : {}),
       ...await mcpServerRequestInit(settings, config, options),
       ...(config.timeoutMs ? {
         timeout: config.timeoutMs,
@@ -1200,7 +1455,7 @@ export async function prepareAgentTools(settings: Settings, tools: ToolRef[], op
     //    with a warning, never killing the turn before the model runs. Bare
     //    refs stay strict (below), preserving the fail-loud default.
     const optional = tool.optional === true;
-    return { server, bestEffort: isCodexAppsMcpServer(config) || optional, optional };
+    return { server, bestEffort: isCodexAppsMcpServer(config) || optional || !!config.connectionRef, optional };
   }));
   const requiredServers = servers.filter((entry) => !entry.bestEffort).map((entry) => entry.server);
   const bestEffortServers = servers.filter((entry) => entry.bestEffort).map((entry) => entry.server);
@@ -1244,6 +1499,240 @@ export async function prepareAgentTools(settings: Settings, tools: ToolRef[], op
   };
 }
 
+function connectionBrokerFetch(
+  baseFetch: FetchLike,
+  config: Settings["mcpServers"][number],
+  options: PrepareToolsOptions,
+): FetchLike {
+  const connectionRef = config.connectionRef;
+  if (!connectionRef) {
+    return baseFetch;
+  }
+  return async (input, init) => {
+    const request = await mcpRequestInfo(input, init);
+    const first = await resolveConnectionForRequest(options, config.id, connectionRef, request.toolName, false);
+    if (first.status === "auth_needed") {
+      return await authNeededFetchResponse(options, config.id, request, first, connectionRef);
+    }
+    const response = await baseFetch(fetchInputForAttempt(input), withConnectionHeaders(input, init, first.headers));
+    if (response.status === 401) {
+      const refreshed = await resolveConnectionForRequest(options, config.id, connectionRef, request.toolName, true);
+      if (refreshed.status === "auth_needed") {
+        return await authNeededFetchResponse(options, config.id, request, refreshed, connectionRef);
+      }
+      const retry = await baseFetch(fetchInputForAttempt(input), withConnectionHeaders(input, init, refreshed.headers));
+      if (retry.status === 403) {
+        const auth = insufficientScopeAuth(retry.headers, connectionRef, refreshed.connectionId);
+        return auth ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef) : retry;
+      }
+      if (retry.status === 401) {
+        return await authNeededFetchResponse(options, config.id, request, {
+          status: "auth_needed",
+          reason: "expired",
+          providerDomain: connectionRef.providerDomain,
+          connectionId: refreshed.connectionId,
+          ...(connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+          ...(connectionRef.resource ? { resource: connectionRef.resource } : {}),
+        }, connectionRef);
+      }
+      return retry;
+    }
+    if (response.status === 403) {
+      const auth = insufficientScopeAuth(response.headers, connectionRef, first.connectionId);
+      return auth ? await authNeededFetchResponse(options, config.id, request, auth, connectionRef) : response;
+    }
+    return response;
+  };
+}
+
+async function resolveConnectionForRequest(
+  options: PrepareToolsOptions,
+  serverId: string,
+  connectionRef: McpServerConnectionRef,
+  toolName: string | undefined,
+  forceRefresh: boolean,
+): Promise<ResolveConnectionCredentialResult> {
+  if (!options.workspaceId || !options.resolveCredential) {
+    return {
+      status: "auth_needed",
+      reason: "missing_connection",
+      providerDomain: connectionRef.providerDomain,
+      ...(connectionRef.connectionId ? { connectionId: connectionRef.connectionId } : {}),
+      ...(connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+      ...(connectionRef.resource ? { resource: connectionRef.resource } : {}),
+    };
+  }
+  const request: ResolveConnectionCredentialInput = {
+    workspaceId: options.workspaceId,
+    serverId,
+    connectionRef,
+    forceRefresh,
+    ...(toolName ? { toolName } : {}),
+    ...(options.subjectId ? { subjectId: options.subjectId } : {}),
+  };
+  try {
+    return await options.resolveCredential(request);
+  } catch {
+    return {
+      status: "auth_needed",
+      reason: "refresh_failed",
+      providerDomain: connectionRef.providerDomain,
+      ...(connectionRef.connectionId ? { connectionId: connectionRef.connectionId } : {}),
+      ...(connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+      ...(connectionRef.resource ? { resource: connectionRef.resource } : {}),
+    };
+  }
+}
+
+function insufficientScopeAuth(
+  headers: Headers,
+  connectionRef: McpServerConnectionRef,
+  connectionId: string,
+): Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }> | null {
+  const challenge = parseWwwAuthenticate(headers.get("www-authenticate"));
+  if (challenge.error !== "insufficient_scope") {
+    return null;
+  }
+  return {
+    status: "auth_needed",
+    reason: "insufficient_scope",
+    providerDomain: connectionRef.providerDomain,
+    connectionId,
+    ...(challenge.scope?.length ? { scopes: challenge.scope } : connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+    ...(challenge.resource ? { resource: challenge.resource } : connectionRef.resource ? { resource: connectionRef.resource } : {}),
+  };
+}
+
+async function authNeededFetchResponse(
+  options: PrepareToolsOptions,
+  serverId: string,
+  request: McpRequestInfo,
+  auth: Extract<ResolveConnectionCredentialResult, { status: "auth_needed" }>,
+  connectionRef: McpServerConnectionRef,
+): Promise<Response> {
+  const connectionId = auth.connectionId ?? connectionRef.connectionId;
+  await publishAuthNeeded(options, {
+    serverId,
+    toolName: request.toolName ?? null,
+    providerDomain: auth.providerDomain,
+    reason: auth.reason,
+    ...(connectionId ? { connectionId } : {}),
+    ...(auth.scopes ? { scopes: auth.scopes } : connectionRef.scopes ? { scopes: connectionRef.scopes } : {}),
+    ...(auth.resource ? { resource: auth.resource } : connectionRef.resource ? { resource: connectionRef.resource } : {}),
+    ...(auth.authorizationUrl ? { authorizationUrl: auth.authorizationUrl } : {}),
+    ...(options.subjectId ? { subjectId: options.subjectId } : {}),
+  });
+  if (request.method === "tools/call") {
+    return mcpToolAuthNeededResponse(request.id);
+  }
+  return new Response("Authentication required for MCP server connection", { status: 401 });
+}
+
+async function publishAuthNeeded(options: PrepareToolsOptions, payload: ToolAuthNeededPayload): Promise<void> {
+  try {
+    await options.onAuthNeeded?.(payload);
+  } catch {
+    // Auth-needed events are advisory UI/audit signals; a publisher failure must
+    // not turn an auth-recoverable tool condition into a failed agent turn.
+  }
+}
+
+type McpRequestInfo = {
+  method?: string;
+  id?: string | number | null;
+  toolName?: string;
+};
+
+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 withConnectionHeaders(input: string | URL | Request, init: RequestInit | undefined, authHeaders: Record<string, string>): RequestInit {
+  const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+  for (const [name, value] of Object.entries(authHeaders)) {
+    headers.set(name, value);
+  }
+  return { ...init, headers };
+}
+
+function fetchInputForAttempt(input: string | URL | Request): string | URL | Request {
+  return input instanceof Request ? input.clone() : input;
+}
+
+function parseWwwAuthenticate(header: string | null): { error?: string; scope?: string[]; resource?: string } {
+  if (!header) {
+    return {};
+  }
+  const bearerIndex = header.toLowerCase().indexOf("bearer");
+  if (bearerIndex < 0) {
+    return {};
+  }
+  const paramsText = header.slice(bearerIndex + "bearer".length);
+  const params: Record<string, string> = {};
+  const re = /([a-zA-Z_][a-zA-Z0-9_-]*)\s*=\s*("(?:[^"\\]|\\.)*"|[^,\s]+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = re.exec(paramsText)) !== null) {
+    const raw = match[2]!;
+    params[match[1]!.toLowerCase()] = raw.startsWith("\"") ? raw.slice(1, -1).replace(/\\"/g, "\"") : raw;
+  }
+  return {
+    ...(params.error ? { error: params.error } : {}),
+    ...(params.scope ? { scope: params.scope.split(/\s+/).filter(Boolean) } : {}),
+    ...(params.resource ? { resource: params.resource } : {}),
+  };
+}
+
+// Application-defined JSON-RPC error code marking "this tool call needs a
+// connection". A RESULT carrying inline `isError: true` cannot be used here:
+// the agents SDK's streamable-http shim strips `isError` and returns only the
+// content, erasing the failure. A JSON-RPC error survives the shim as a thrown
+// McpError, which PrefixedMcpServer.callTool converts back into an MCP-shaped
+// `{ isError: true }` output for the model.
+const MCP_AUTH_NEEDED_ERROR_CODE = -32001;
+const MCP_AUTH_NEEDED_MESSAGE = "Authentication required - a connection link was posted to the session.";
+
+function mcpToolAuthNeededResponse(id: string | number | null | undefined): Response {
+  return new Response(JSON.stringify({
+    jsonrpc: "2.0",
+    id: id ?? null,
+    error: {
+      code: MCP_AUTH_NEEDED_ERROR_CODE,
+      message: MCP_AUTH_NEEDED_MESSAGE,
+    },
+  }), {
+    status: 200,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function isAuthNeededMcpError(error: unknown): boolean {
+  if (!(error instanceof Error)) {
+    return false;
+  }
+  const code = (error as { code?: unknown }).code;
+  return code === MCP_AUTH_NEEDED_ERROR_CODE || error.message.includes(MCP_AUTH_NEEDED_MESSAGE);
+}
+
 async function mcpServerRequestInit(settings: Settings, config: Settings["mcpServers"][number], options: PrepareToolsOptions): Promise<{ requestInit: { headers: Record<string, string> } } | {}> {
   // codex_apps is checked FIRST so the static-headers path can never apply to
   // it: its refreshing ChatGPT/Codex bearer is resolved per-connect from the
@@ -1433,7 +1922,7 @@ function normalizeUrl(raw: string): string | null {
 }
 
 export function prefixedMcpToolName(registryId: string, toolName: string): string {
-  return `${registryId}__${toolName}`;
+  return sharedPrefixedMcpToolName(registryId, toolName);
 }
 
 class PrefixedMcpServer implements MCPServer {
@@ -1469,7 +1958,18 @@ class PrefixedMcpServer implements MCPServer {
     if (!this.isAllowed(unprefixed)) {
       throw new Error(`MCP tool ${unprefixed} is not allowed for server ${this.name}`);
     }
-    return await this.inner.callTool(unprefixed, args, meta);
+    try {
+      return await this.inner.callTool(unprefixed, args, meta);
+    } 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
+      // shim). Surface it to the model as a failed-but-recoverable tool result
+      // instead of failing the turn; the timeline chip was already published.
+      if (isAuthNeededMcpError(error)) {
+        return { isError: true, content: [{ type: "text", text: MCP_AUTH_NEEDED_MESSAGE }] };
+      }
+      throw error;
+    }
   }
 
   invalidateToolsCache(): Promise<void> {
@@ -1857,8 +2357,10 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
     // TOKEN-BROKER (B1): the per-turn git token seed, forwarded OFF-MANIFEST so the
     // repository-clone hook seeds it to the box's token file before the clone.
     const ownedGitTokenSeed = gitTokenSeedForAgent(agent);
+    const ownedToolspaceTokenSeed = toolspaceTokenSeedForAgent(agent);
     const ownedHooks = [
       ...sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+      ...sandboxToolspaceTokenHooksForAgent(agent),
       ...sandboxRepositoryCloneHooksForAgent(agent),
     ];
     const ownedHookContext: SandboxLifecycleHookContext = {
@@ -1866,6 +2368,7 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
       ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
       ...(runAs ? { runAs } : {}),
       ...(ownedGitTokenSeed ? { gitTokenSeed: ownedGitTokenSeed } : {}),
+      ...(ownedToolspaceTokenSeed ? { toolspaceTokenSeed: ownedToolspaceTokenSeed } : {}),
     };
     // OWNED-PATH HOOKS: the SDK NEVER calls client.create/resume when handed a live
     // provided session (SandboxRuntimeManager uses `sandboxConfig.session` directly),
@@ -1940,15 +2443,18 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
   // TOKEN-BROKER (B1): the per-turn git token seed, forwarded OFF-MANIFEST so the
   // repository-clone hook seeds it to the box's token file before the clone.
   const gitTokenSeed = gitTokenSeedForAgent(agent);
+  const toolspaceTokenSeed = toolspaceTokenSeedForAgent(agent);
   const client = resourceClient
     ? withSandboxLifecycleHooks(resourceClient, [
       ...sandboxLifecycleHooksForIds(sandboxLifecycleHookIds(settings)),
+      ...sandboxToolspaceTokenHooksForAgent(agent),
       ...sandboxRepositoryCloneHooksForAgent(agent),
     ], {
       environment,
       ...(overrides.onRuntimeEvent ? { onRuntimeEvent: overrides.onRuntimeEvent } : {}),
       ...(runAs ? { runAs } : {}),
       ...(gitTokenSeed ? { gitTokenSeed } : {}),
+      ...(toolspaceTokenSeed ? { toolspaceTokenSeed } : {}),
     })
     : undefined;
   const sandboxSessionState = prepared.sandboxSessionState
@@ -1982,7 +2488,6 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
     // every mid-turn follow-up.
     callModelInputFilter,
   };
-  void settings.disableOpenaiTracing;
   if (client) {
     runOptions.sandbox = {
       client,
@@ -2752,6 +3257,7 @@ export type SandboxLifecycleHookContext = {
   // the clone exec's per-call env (OPENGENI_GIT_TOKEN_SEED), NEVER the box/agent
   // manifest env (validateNoEnvironmentDelta must never see a rotating value).
   gitTokenSeed?: string;
+  toolspaceTokenSeed?: string;
 };
 
 export type SandboxLifecycleHook = {
@@ -2852,6 +3358,20 @@ function gitTokenSeedForAgent(agent: Agent<any, any>): string | undefined {
   return agentGitTokenSeed.get(agent);
 }
 
+function toolspaceTokenSeedForAgent(agent: Agent<any, any>): string | undefined {
+  return agentToolspaceTokenSeed.get(agent);
+}
+
+function sandboxToolspaceTokenHooksForAgent(agent: Agent<any, any>): SandboxLifecycleHook[] {
+  return toolspaceTokenSeedForAgent(agent)
+    ? [{
+        id: "toolspace-token",
+        phase: "beforeAgentStart",
+        run: runToolspaceTokenSeedHook,
+      }]
+    : [];
+}
+
 function sandboxRepositoryCloneHooks(
   settings: Settings,
   resources: ResourceRef[],
@@ -3053,6 +3573,53 @@ export function repositoryCloneCommand(resources: Extract<ResourceRef, { kind: "
   return commands.join("\n");
 }
 
+export function toolspaceTokenSeedCommand(): string {
+  return [
+    "set -eu",
+    "export HOME=\"${HOME:-/workspace}\"",
+    "if [ -n \"${OPENGENI_TOOLSPACE_TOKEN_SEED:-}\" ]; then",
+    "  seed_umask=\"$(umask)\"",
+    "  umask 077",
+    "  token_file=\"${OPENGENI_TOOLSPACE_TOKEN_FILE:-$HOME/.opengeni/toolspace-token}\"",
+    "  mkdir -p \"$(dirname \"$token_file\")\"",
+    "  printf '%s' \"$OPENGENI_TOOLSPACE_TOKEN_SEED\" > \"$token_file.tmp.$$\"",
+    "  mv -f \"$token_file.tmp.$$\" \"$token_file\"",
+    "  umask \"$seed_umask\"",
+    "fi",
+  ].join("\n");
+}
+
+export async function runToolspaceTokenSeedHook(
+  session: SandboxSessionLike,
+  context: SandboxLifecycleHookContext,
+): Promise<void> {
+  if (!context.toolspaceTokenSeed) {
+    return;
+  }
+  const command = `export OPENGENI_TOOLSPACE_TOKEN_SEED=${shellQuote(context.toolspaceTokenSeed)}\n${toolspaceTokenSeedCommand()}`;
+  if (session.exec) {
+    const result = await session.exec({
+      cmd: command,
+      workdir: "/workspace",
+      ...(context.runAs ? { runAs: context.runAs } : {}),
+      yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
+      maxOutputTokens: 4_000,
+    });
+    assertSandboxCommandSucceeded(result, "Toolspace token seed hook");
+  } else if (session.execCommand) {
+    const result = await session.execCommand({
+      cmd: command,
+      workdir: "/workspace",
+      ...(context.runAs ? { runAs: context.runAs } : {}),
+      yieldTimeMs: SANDBOX_LIFECYCLE_COMMAND_TIMEOUT_MS,
+      maxOutputTokens: 4_000,
+    });
+    assertSandboxCommandSucceeded(result, "Toolspace token seed hook");
+  } else {
+    throw new Error("Sandbox session does not support command execution");
+  }
+}
+
 export async function runRepositoryCloneHook(
   session: SandboxSessionLike,
   resources: Extract<ResourceRef, { kind: "repository" }>[],