@opengeni/runtime 0.3.1 → 0.5.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,
@@ -43,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,
@@ -149,8 +151,10 @@ export { OpenAIChatCompletionsModel, OpenAIResponsesModel } from "@openai/agents
 export {
   CompactionNeededError,
   buildCompactionPromptInput,
+  buildDeterministicFallbackCompactionHistory,
   buildCompactionReplacementHistory,
   clientCompactionThresholdTokens,
+  clampCompactionThresholdRatio,
   decideClientCompaction,
   enforceInputBudget,
   buildSummaryItem,
@@ -164,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,
@@ -197,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>;
@@ -606,9 +635,10 @@ function recordModelCallMetric(provider: string, outcome: "completed" | "failed"
  * 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
@@ -622,18 +652,24 @@ function recordModelCallMetric(provider: string, outcome: "completed" | "failed"
 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() : "";
@@ -646,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;
   }
 }
@@ -780,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
@@ -896,6 +937,25 @@ export function appendSessionInstructions(composed: string, sessionInstructions?
   return trimmed ? `${composed} ${trimmed}` : composed;
 }
 
+/**
+ * Appends the generic programmatic-tool-calling (toolspace) directive to the
+ * composed workspace + CORE instructions, joined by " ". This is GENERIC
+ * substrate prompting — the same text for every host, never per-host copy.
+ *
+ * Included ONLY when `toolspaceAvailable` is true, which the caller sets from the
+ * exact condition that gates the sandbox token mint: the toolspace feature is
+ * enabled AND a toolspace token was minted for THIS turn. That mint now happens
+ * on every backend including selfhosted (connected machines get the token too),
+ * so the block appears there as well; a turn with no minted token (feature off)
+ * has no toolspace URL/token in its sandbox and must not advertise a capability
+ * that is not there — the gate is false and this is a no-op. Placed BEFORE the
+ * per-session instructions so host/session specificity still wins over this
+ * substrate note.
+ */
+export function appendToolspaceInstructions(composed: string, toolspaceAvailable: boolean): string {
+  return toolspaceAvailable ? `${composed} ${TOOLSPACE_PROGRAMMATIC_DIRECTIVE}` : composed;
+}
+
 /**
  * Appends the one-shot genesis title directive (genesis turn only), joined by
  * " " and always LAST so a white-label persona template or a per-session
@@ -913,11 +973,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
@@ -952,14 +1049,21 @@ export function buildOpenGeniAgent(settings: Settings, resources: ResourceRef[],
     // Persona composition order (all one system-level instructions string):
     //   1. workspace instructionsTemplate (or deployment default) with the
     //      non-bypassable CORE substituted at {{core}} — composeAgentInstructions,
-    //   2. + the per-session persona instructions (session-specific, LAST so it
-    //      refines the workspace persona),
-    //   3. + the one-shot genesis title directive (genesis turn only).
-    // With no session instructions and no genesis hint this is byte-identical to
-    // the historical composed instructions.
+    //   2. + the generic programmatic-tool-calling (toolspace) directive, ONLY
+    //      when a toolspace token was minted for this turn (feature enabled + a
+    //      per-turn seed — the mint gate, which includes selfhosted turns since
+    //      they now receive the token too) — appendToolspaceInstructions,
+    //   3. + the per-session persona instructions (session-specific, so it
+    //      refines both the workspace persona and the substrate note),
+    //   4. + the one-shot genesis title directive (genesis turn only).
+    // With no toolspace token, no session instructions, and no genesis hint this
+    // is byte-identical to the historical composed instructions.
     instructions: appendGenesisTitleDirective(
       appendSessionInstructions(
-        composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+        appendToolspaceInstructions(
+          composeAgentInstructions(options.instructionsTemplate ?? settings.agentInstructionsTemplate, options.workspaceEnvironment),
+          settings.toolspaceEnabled && Boolean(options.toolspaceTokenSeed),
+        ),
         options.sessionInstructions,
       ),
       options.genesisTitleHint,
@@ -993,11 +1097,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;
   }
 
@@ -1028,7 +1140,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;
 }
 
@@ -1050,6 +1166,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
@@ -1218,6 +1429,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> {
@@ -1235,6 +1448,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,
@@ -1243,7 +1462,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,
@@ -1262,7 +1481,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);
@@ -1306,6 +1525,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
@@ -1495,7 +1948,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 {
@@ -1531,7 +1984,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> {
@@ -1756,6 +2220,13 @@ export type ContextRobustnessFilterOptions = {
 export const GENESIS_TITLE_DIRECTIVE =
   "This is the first turn of a new session. Before responding to the user, call the opengeni__set_session_title tool with a concise 3-7 word title that summarizes what this session is about, then address the user's request normally.";
 
+// Generic substrate prompting for programmatic tool calling (toolspace). Same
+// text for every host; gated per-turn by appendToolspaceInstructions on the
+// presence of a minted toolspace token, so it only appears when the sandbox
+// actually exposes the ogtool CLI + $OPENGENI_TOOLSPACE_URL/_TOKEN_FILE.
+export const TOOLSPACE_PROGRAMMATIC_DIRECTIVE =
+  "Every tool on your MCP surface is also callable programmatically from the sandbox shell, so scripts can invoke tools without a model round trip per call. Run `ogtool list` to see the available tools and their input schemas (from tools/list), then `ogtool call <tool-name> '<json-args>'`; equivalently, POST MCP JSON-RPC to $OPENGENI_TOOLSPACE_URL with the bearer token read from $OPENGENI_TOOLSPACE_TOKEN_FILE. Prefer programmatic calls for loops, polling, and bulk filtering: their results stay in the sandbox and do not consume your context window. Tools that require human approval must still be invoked normally — called programmatically they return a typed error.";
+
 /**
  * callModelInputFilter that removes provider-assigned item ids (rs_/msg_/fc_…)
  * from every input item immediately before each model call. Responses-API
@@ -1919,8 +2390,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 = {
@@ -1928,6 +2401,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),
@@ -1957,6 +2431,22 @@ export async function runAgentStream(agent: Agent<any, any>, input: PreparedAgen
           ...(runAs ? { runAs } : {}),
         });
       }
+    } else {
+      // SELFHOSTED TOOLSPACE (parity): the platform setup hooks (repository clone,
+      // az login) and file materialization stay OFF the user's real machine — but
+      // the toolspace token seed is the ONE piece of per-turn material that must
+      // reach it. It writes a scoped, own-session-bound token to
+      // $OPENGENI_TOOLSPACE_TOKEN_FILE over the SAME exec channel the clone-seed
+      // uses (off-manifest, value never on the manifest), and it grants no more
+      // than the machine owner's own authority (toolspace:call, this session, turn
+      // TTL, budgeted, approval-tools excluded) — the invariant that makes it safe
+      // to cross to a user machine when the git token is not. It is also the
+      // machine's only path to programmatic tool calling. Seed it (only) here; the
+      // hook list is empty when no toolspace token was minted for this turn.
+      const toolspaceHooks = sandboxToolspaceTokenHooksForAgent(agent);
+      if (toolspaceHooks.length > 0) {
+        await runBeforeAgentStartHooks(setupSession, toolspaceHooks, ownedHookContext);
+      }
     }
     // Keep the decoration as a safety net for any session the SDK does create/resume
     // through the client during this run (it is inert for the provided session).
@@ -2002,15 +2492,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
@@ -2813,6 +3306,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 = {
@@ -2913,6 +3407,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[],
@@ -3114,6 +3622,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" }>[],