@opengeni/runtime 2.5.2 → 2.5.3-canary.1

package/dist/sandbox/workspace-archive.d.ts

@@ -1,4 +1,5 @@
 import { type NativeSnapshotDescriptor, type NativeSnapshotRef, type WorkspaceArchiveDescriptor, type WorkspaceTreeFingerprint } from "@opengeni/contracts";
+import type { VerifiedHostWorkspaceArchive } from "./archive-spool.js";
 export { WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION, decodeNativeSnapshotRef, encodeNativeSnapshotRef, parseWorkspaceArchiveDescriptor, type NativeSnapshotDescriptor, type NativeSnapshotProvider, type NativeSnapshotRef, type TarWorkspaceArchiveDescriptor, type WorkspaceArchiveDescriptor, type WorkspaceTreeFingerprint, } from "@opengeni/contracts";
 export type VerifiedWorkspaceArchive = {
     bytes: Uint8Array;
@@ -7,6 +8,12 @@ export type VerifiedWorkspaceArchive = {
     kind: "tar" | "provider_snapshot";
     nativeSnapshot?: NativeSnapshotRef;
 };
+export type VerifiedWorkspaceArchivePayload = VerifiedWorkspaceArchive | VerifiedHostWorkspaceArchive;
+/** Host-backed portable archives can go directly to object storage without an
+ * intermediate whole-document string or buffer. Existing inline/provider APIs
+ * retain their compatibility path when disk-backed publication is unavailable. */
+export declare function captureWorkspaceArchiveForStorage(session: unknown, capturedAtMs: number, options: WorkspaceArchiveCaptureOptions, objectStorageAvailable: boolean): Promise<VerifiedWorkspaceArchivePayload>;
+export declare function disposeWorkspaceArchive(archive: VerifiedWorkspaceArchivePayload | undefined): Promise<void>;
 export type WorkspaceArchiveIntegrityCode = "archive_metadata_missing" | "archive_metadata_invalid" | "archive_base64_invalid" | "archive_hash_mismatch" | "archive_hydration_failed" | "workspace_fingerprint_unavailable" | "workspace_changed_during_capture" | "workspace_fingerprint_mismatch" | "native_snapshot_reference_invalid" | "native_snapshot_fallback_unverified";
 export declare class WorkspaceArchiveIntegrityError extends Error {
     readonly code: WorkspaceArchiveIntegrityCode;

package/dist/workspace-skills.d.ts

@@ -1,3 +1,4 @@
+import { type Tool } from "@openai/agents";
 import { Capability, type SandboxSessionLike } from "@openai/agents/sandbox";
 export type WorkspaceSkillSearchPath = Readonly<{
     path: string;
@@ -24,6 +25,9 @@ export declare class WorkspaceSkillsCapability extends Capability {
     readonly type = "workspace-skills";
     private discovery?;
     constructor(searchPaths: readonly WorkspaceSkillSearchPath[], reservedNames?: ReadonlySet<string>, shadowedNames?: ReadonlySet<string>);
+    bind(session: SandboxSessionLike): this;
+    private discover;
+    tools(): Tool<unknown>[];
     instructions(): Promise<string | null>;
 }
 export declare function workspaceSkills(searchPaths: readonly WorkspaceSkillSearchPath[], reservedNames?: Iterable<string>, shadowedNames?: Iterable<string>): WorkspaceSkillsCapability;

package/dist/workspace-tool-gateway.js

@@ -1,12 +1,12 @@
 import {
   prepareAgentTools
-} from "./chunk-GJC7H2FC.js";
-import "./chunk-LGLJ5PVD.js";
-import "./chunk-CD22I76N.js";
+} from "./chunk-VUEWS4GI.js";
+import "./chunk-46BFUGFL.js";
+import "./chunk-FHGLYLBL.js";
 import "./chunk-GB763TSV.js";
 import "./chunk-UZ66CGC2.js";
 import "./chunk-JHM4OS7C.js";
-import "./chunk-25B3EQRW.js";
+import "./chunk-UNICCRW5.js";
 import "./chunk-PZ5AY32C.js";
 export {
   prepareAgentTools as prepareWorkspaceToolGatewayTools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "2.5.2",
+  "version": "2.5.3-canary.1",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -62,16 +62,16 @@
     "@openai/agents": "0.14.3",
     "@openai/agents-core": "0.14.3",
     "@openai/agents-extensions": "0.14.3",
-    "@opengeni/agent-proto": "^0.5.1",
-    "@opengeni/capabilities": "^0.3.3",
-    "@opengeni/codemode": "^0.5.5",
-    "@opengeni/codex": "^0.2.22",
-    "@opengeni/config": "^1.1.1",
-    "@opengeni/contracts": "^3.0.1",
-    "@opengeni/network": "^0.3.1",
-    "@opengeni/sdk": "^5.0.3",
-    "@opengeni/tool-gateway": "^0.1.6",
-    "@opengeni/xai-subscription": "^0.1.4",
+    "@opengeni/agent-proto": "^0.5.1-canary.27",
+    "@opengeni/capabilities": "^0.3.3-canary.9",
+    "@opengeni/codemode": "^0.5.6-canary.1",
+    "@opengeni/codex": "^0.2.22-canary.9",
+    "@opengeni/config": "^1.1.2-canary.1",
+    "@opengeni/contracts": "^3.0.2-canary.1",
+    "@opengeni/network": "^0.3.1-canary.9",
+    "@opengeni/sdk": "^5.0.5-canary.1",
+    "@opengeni/tool-gateway": "^0.1.7-canary.1",
+    "@opengeni/xai-subscription": "^0.1.4-canary.9",
     "debug": "4.4.3",
     "modal": "0.9.0",
     "openai": "6.47.0",

package/src/bundled_default_skills/document-parsing/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: document-parsing
+description: Extract readable Markdown from local Word, PowerPoint, Excel, OpenDocument, RTF, EPUB, CSV, and text-based PDF files using the preinstalled AnyDoc runtime.
+license: MIT
+metadata:
+  runtime: anydoc@0.1.8
+  upstream: https://github.com/firecrawl/anydoc
+---
+
+# Parse local documents
+
+Use the preinstalled `anydoc` CLI when a task needs the contents of a local
+office document, ebook, CSV, or text-based PDF. This is read-only extraction;
+it does not edit the source or replace OpenGeni's durable artifact tools.
+
+```bash
+anydoc report.docx
+anydoc slides.pptx -o /tmp/slides.md
+anydoc - --format csv < data-without-extension
+```
+
+Rules:
+
+1. Supported inputs: `.doc`, `.docx`, `.docm`, `.odt`, `.rtf`, `.epub`,
+   `.pdf`, `.ppt`, `.pps`, `.pot`, `.pptx`, `.pptm`, `.ppsx`, `.ppsm`,
+   `.odp`, `.xls`, `.xlsx`, `.xlsm`, `.xlsb`, `.ods`, and `.csv`.
+2. Let AnyDoc detect the format from file content. Specify `--format` only for
+   signature-less input such as CSV on stdin or a file without a useful name.
+3. For large output, use `-o` and inspect only the relevant sections instead
+   of streaming the whole document into model context.
+4. Preserve the source file. AnyDoc output is a derived reading aid, not a new
+   canonical document or editable artifact.
+5. Scanned/image-only PDFs need OCR and are unsupported. Encrypted, malformed,
+   or resource-limit failures must be reported rather than guessed around.
+6. Never install or download AnyDoc at runtime. If `anydoc` is unavailable,
+   report that the selected compute image lacks the parsing runtime.

package/src/bundled_site_skills/opengeni-sites/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: opengeni-sites
-description: Build, inspect, edit, validate, and publish OpenGeni Sites as ordinary Bun + React source projects compiled to one self-contained HTML artifact. Use for interactive pages, dashboards, visualizations, workflows, and focused apps that may call workspace tools through the typed Site bridge.
+description: Build, edit, and publish OpenGeni Sites. Proactively recommend Sites for visual or interactive deliverables such as dashboards, explorable reports, landing pages, demos, trackers, portals, directories, calculators, forms, and custom agent interfaces—even when the user doesn't name Sites. Prefer Sites when the delivery format is open. When working on an existing application, follow its established architecture and workflow; consider Sites only when relevant to the requested outcome, not as an automatic conversion. Respect explicit format and platform choices.
 ---
 
 # OpenGeni Sites

package/src/index.ts

@@ -1,5 +1,29 @@
 import type { ModelProviderApi, ResolvedModelProvider, Settings } from "@opengeni/config";
 import { executeCommandReadWithRefresh } from "./command-read-refresh";
+import {
+  captureMcpOperationDispatch,
+  hasActiveRecoverableMcpOperation,
+  runRecoverableMcpOperation,
+  type McpOperationPersistence,
+} from "./mcp-operation-dispatch";
+export {
+  captureMcpOperationDispatch,
+  hasActiveRecoverableMcpOperation,
+  McpOperationOutcomeUnknownError,
+  runRecoverableMcpOperation,
+  type CapturedMcpOperation,
+  type McpOperationPersistence,
+  type RecoverableMcpOperation,
+} from "./mcp-operation-dispatch";
+import { assertMcpOperationObservationAuthority } from "./mcp-operation-observation";
+export {
+  assertMcpOperationObservationAuthority,
+  observeMcpOperation,
+  runMcpOperationObservationWithAuthority,
+  type McpOperationObservationAuthority,
+  type McpObservationBinding,
+  type McpObservationReceipt,
+} from "./mcp-operation-observation";
 import { formatSkillCatalog, type SkillCatalogDescriptor } from "./skill-catalog";
 export { formatSkillCatalog, type SkillCatalogDescriptor } from "./skill-catalog";
 import {
@@ -11,6 +35,7 @@ import {
   AGENT_INSTRUCTIONS_CORE_PLACEHOLDER,
   collectSandboxEnvironment,
   configuredProviders,
+  McpOperationRecoverySchema,
   firstPartyMcpInternalBaseUrl,
   firstPartyMcpInternalWorkspaceUrl,
   resolveFirstPartyDelegationSecret,
@@ -683,6 +708,8 @@ export type ResolveConnectionCredentialResult =
       connectionId: string;
       authoritySource?: "host";
       authorizeProviderRequest?: () => Promise<boolean>;
+      /** Metadata-only immutable authority binding supplied by the trusted worker resolver. */
+      operationAuthorityDigest?: string;
       expiresAt?: Date | null;
     }
   | {
@@ -1723,6 +1750,11 @@ type ModelToolInvocation = {
 };
 
 const modelToolInvocation = new AsyncLocalStorage<ModelToolInvocation>();
+// Correlation must not activate the separate approval-only invocation guard.
+const modelMcpCallIdentity = new AsyncLocalStorage<{
+  modelName: string;
+  callId: string;
+} | null>();
 const agentInputWaitYields = new WeakMap<object, InputWaitYield>();
 
 export type BuildAgentOptions = {
@@ -2657,6 +2689,7 @@ export function buildOpenGeniAgent(
       agent as unknown as ApprovalCapableAgent,
       options.approvedToolCallId,
     );
+    installModelMcpCallIdentity(agent as unknown as ApprovalCapableAgent);
     return agent;
   }
 
@@ -2785,6 +2818,7 @@ export function buildOpenGeniAgent(
     agent as unknown as ApprovalCapableAgent,
     options.approvedToolCallId,
   );
+  installModelMcpCallIdentity(agent as unknown as ApprovalCapableAgent);
   return agent;
 }
 
@@ -2876,6 +2910,42 @@ type ApprovalCapableAgent = {
   clone?: (config: unknown) => ApprovalCapableAgent;
 };
 
+/** Preserve SDK correlation through MCP projection without granting approval.
+ * SandboxAgent clones rebuild instance methods, so reinstall on every clone. */
+function installModelMcpCallIdentity(agent: ApprovalCapableAgent): void {
+  const listMcpTools = agent.getMcpTools.bind(agent);
+  agent.getMcpTools = async (resolutionContext: unknown) =>
+    (await listMcpTools(resolutionContext)).map((tool) => {
+      if (tool.type !== "function") return tool;
+      const invoke = tool.invoke.bind(tool);
+      return {
+        ...tool,
+        invoke: async (runContext, input, details) => {
+          const callId = details?.toolCall?.callId;
+          return await modelMcpCallIdentity.run(
+            typeof callId === "string" && callId.length > 0
+              ? { modelName: tool.name, callId }
+              : null,
+            async () => await invoke(runContext, input, details),
+          );
+        },
+      };
+    });
+  const clone = agent.clone?.bind(agent);
+  if (clone) {
+    agent.clone = (config: unknown) => {
+      const cloned = clone(config);
+      installModelMcpCallIdentity(cloned);
+      return cloned;
+    };
+  }
+}
+
+function modelMcpSourceCallId(modelName: string): string | undefined {
+  const identity = modelMcpCallIdentity.getStore();
+  return identity?.modelName === modelName ? identity.callId : undefined;
+}
+
 /**
  * Install the approval wrap on a single agent instance: replace `getMcpTools`
  * with one that stamps `needsApproval: () => true` on every MCP tool whose
@@ -3612,6 +3682,8 @@ export type ToolPreparationPhaseMeasurement = {
 };
 
 export type PrepareToolsOptions = {
+  /** Opt-in exact-attempt persistence; absence preserves ordinary MCP execution. */
+  mcpOperationPersistence?: McpOperationPersistence;
   /** Live exact-owner control refresh; API remains read/observation authority. */
   refreshOwnedCommand?: (commandId: string) => Promise<boolean>;
   accountId?: string;
@@ -3986,24 +4058,30 @@ export async function prepareAgentTools(
           }
           const optional = tool.optional === true;
           return {
-            server: new PrefixedMcpServer(
-              local.server,
-              config.id,
-              config.allowedTools,
-              optional || Boolean(config.connectionRef),
-              aggregateToolBudget,
-              `${config.id}:${index}`,
-              false,
-              buildConnectorAttachmentAuthority(
-                config,
-                options,
-                resolvedMcpToolConnectionIds,
-                config.url,
-                local.resolvedConnectionId,
+            server: configureMcpOperationRecovery(
+              new PrefixedMcpServer(
+                local.server,
+                config.id,
+                config.allowedTools,
+                optional || Boolean(config.connectionRef),
+                aggregateToolBudget,
+                `${config.id}:${index}`,
+                false,
+                buildConnectorAttachmentAuthority(
+                  config,
+                  options,
+                  resolvedMcpToolConnectionIds,
+                  config.url,
+                  local.resolvedConnectionId,
+                ),
+                tool.eager !== true,
+                local.preflightCall,
+                local.approvalAuthority,
               ),
-              tool.eager !== true,
-              local.preflightCall,
-              local.approvalAuthority,
+              config,
+              options,
+              config.url,
+              false,
             ),
             bestEffort: optional || Boolean(config.connectionRef),
             optional,
@@ -4121,24 +4199,30 @@ export async function prepareAgentTools(
                 }
               : {}),
           });
-        const server = new PrefixedMcpServer(
-          innerServer,
-          config.id,
-          config.allowedTools,
-          bestEffort,
-          aggregateToolBudget,
-          `${config.id}:${index}`,
-          firstParty && !bestEffort,
-          buildConnectorAttachmentAuthority(config, options, resolvedMcpToolConnectionIds, url),
-          tool.eager !== true,
-          undefined,
-          undefined,
-          firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
-            ? inputWaitYield
-            : undefined,
-          firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
-            ? options.refreshOwnedCommand
-            : undefined,
+        const server = configureMcpOperationRecovery(
+          new PrefixedMcpServer(
+            innerServer,
+            config.id,
+            config.allowedTools,
+            bestEffort,
+            aggregateToolBudget,
+            `${config.id}:${index}`,
+            firstParty && !bestEffort,
+            buildConnectorAttachmentAuthority(config, options, resolvedMcpToolConnectionIds, url),
+            tool.eager !== true,
+            undefined,
+            undefined,
+            firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
+              ? inputWaitYield
+              : undefined,
+            firstParty && config.id === "opengeni" && !config.connectionRef && !bridge
+              ? options.refreshOwnedCommand
+              : undefined,
+          ),
+          config,
+          options,
+          url,
+          Boolean(config.connectionRef) && !bridge && !isCodexAppsMcpServer(config),
         );
         return {
           server,
@@ -4788,18 +4872,42 @@ async function prepareToolGatewayDefinitionsFromServers(
                   }),
               }
             : {}),
-          execute: async (args, context) =>
-            await server.executeCatalogTool(
-              toolName,
-              args,
-              {
-                ...(context.transportMeta ?? {}),
-                opengeniOperationId: context.operationId,
-              },
+          execute: async (args, context) => {
+            const execute = async () =>
+              await server.executeCatalogTool(
+                toolName,
+                args,
+                {
+                  ...(context.transportMeta ?? {}),
+                  opengeniOperationId: context.operationId,
+                },
+                {
+                  ...(context.signal ? { signal: context.signal } : {}),
+                },
+              );
+            const recovery = configuredMcpOperationRecovery(server, toolName);
+            if (!recovery) return await execute();
+            if (!recovery.supported || !["model", "codemode"].includes(context.caller.kind)) {
+              throw new Error(
+                "MCP operation recovery requires an exact attempt and remote brokered execution",
+              );
+            }
+            return await runRecoverableMcpOperation(
               {
-                ...(context.signal ? { signal: context.signal } : {}),
+                operationId: context.operationId,
+                ...(context.sourceCallId === undefined
+                  ? {}
+                  : { sourceCallId: context.sourceCallId }),
+                serverId: server.registryId,
+                originalTool: toolName,
+                observerTool: recovery.policy[toolName]!.observerTool,
+                destinationDigest: recovery.destinationDigest,
+                argumentDigest: digestCanonicalJson(args),
               },
-            ),
+              recovery.persistence,
+              execute,
+            );
+          },
         };
       });
     },
@@ -4818,6 +4926,38 @@ function attemptToolCodemodePath(serverId: string, toolName: string): readonly s
   return [serverId, toolName];
 }
 
+type PreparedMcpOperationRecovery = {
+  policy: NonNullable<Settings["mcpServers"][number]["operationRecovery"]>;
+  persistence: McpOperationPersistence;
+  destinationDigest: string;
+  supported: boolean;
+};
+
+const mcpOperationRecoveryByServer = new WeakMap<PrefixedMcpServer, PreparedMcpOperationRecovery>();
+
+function configureMcpOperationRecovery(
+  server: PrefixedMcpServer,
+  config: Settings["mcpServers"][number],
+  options: PrepareToolsOptions,
+  destinationUrl: string,
+  brokered: boolean,
+): PrefixedMcpServer {
+  if (config.operationRecovery && options.mcpOperationPersistence) {
+    mcpOperationRecoveryByServer.set(server, {
+      policy: McpOperationRecoverySchema.parse(config.operationRecovery),
+      persistence: options.mcpOperationPersistence,
+      destinationDigest: digestCanonicalJson(new URL(destinationUrl).toString()),
+      supported: brokered && attemptToolScope(options) !== null,
+    });
+  }
+  return server;
+}
+
+function configuredMcpOperationRecovery(server: PrefixedMcpServer, toolName: string) {
+  const recovery = mcpOperationRecoveryByServer.get(server);
+  return recovery && Object.hasOwn(recovery.policy, toolName) ? recovery : undefined;
+}
+
 function attemptToolSource(serverId: string): ToolGatewayDefinition["source"] {
   if (serverId === "opengeni" || serverId === "files" || serverId === "docs") {
     return serverId;
@@ -4889,6 +5029,35 @@ function connectionBrokerFetch(
         suppressSetupAuthNeeded,
       );
     }
+    if (request.method === "tools/call") {
+      assertMcpOperationObservationAuthority({
+        serverId: config.id,
+        ...(request.toolName === undefined ? {} : { toolName: request.toolName }),
+        destinationDigest: digestCanonicalJson(destinationUrl),
+        ...(first.operationAuthorityDigest === undefined
+          ? {}
+          : { authorityDigest: first.operationAuthorityDigest }),
+      });
+      if (
+        hasActiveRecoverableMcpOperation() &&
+        (request.batch ||
+          request.id === undefined ||
+          request.id === null ||
+          !request.operationId ||
+          !request.toolName)
+      ) {
+        throw new Error("Recoverable MCP request is missing its exact dispatch identity");
+      }
+      // The helper is a no-op without its private context. Always enter it for
+      // tools/call so a late transport continuation cannot bypass a closed context.
+      await captureMcpOperationDispatch({
+        operationId: request.operationId ?? "",
+        serverId: config.id,
+        toolName: request.toolName ?? "",
+        destinationDigest: digestCanonicalJson(destinationUrl),
+        authorityDigest: first.operationAuthorityDigest ?? "",
+      });
+    }
     const response = await baseFetch(
       fetchInputForAttempt(input),
       withConnectionHeaders(input, init, first.headers),
@@ -6387,9 +6556,11 @@ class AttemptDefinitionMcpServer implements MCPServer {
   ): Promise<any> {
     if (this.closed) throw new Error("local model tool server is closed");
     const environment = await this.requiredAttemptToolEnvironment();
+    const sourceCallId = modelMcpSourceCallId(toolName);
     return await this.resultCustomDataBridge.captureResult(args, async (cleanArgs) =>
       environment.callModel({
         modelName: toolName,
+        ...(sourceCallId === undefined ? {} : { sourceCallId }),
         arguments: cleanArgs ?? {},
         subjectId: this.subjectId,
         ...(meta === undefined ? {} : { transportMeta: meta }),
@@ -6711,8 +6882,10 @@ export class PrefixedMcpServer implements MCPServer {
     }
     return await this.resultCustomDataBridge.captureResult(args, async (cleanArgs) => {
       if (this.attemptToolEnvironment) {
+        const sourceCallId = modelMcpSourceCallId(toolName);
         return await this.attemptToolEnvironment.callModel({
           modelName: toolName,
+          ...(sourceCallId === undefined ? {} : { sourceCallId }),
           arguments: cleanArgs ?? {},
           subjectId: this.attemptToolSubjectId,
           ...(meta === undefined ? {} : { transportMeta: meta }),
@@ -6741,6 +6914,9 @@ export class PrefixedMcpServer implements MCPServer {
     if (!this.isAllowed(unprefixed)) {
       throw new Error(`MCP tool ${unprefixed} is not allowed for server ${this.registryId}`);
     }
+    if (configuredMcpOperationRecovery(this, unprefixed) && !hasActiveRecoverableMcpOperation()) {
+      throw new Error("MCP operation recovery requires its trusted attempt execution context");
+    }
     // Nested prefix wrappers are a projection seam around one physical
     // tools/call. The innermost wrapper owns the single metric observation.
     const recordsPhysicalCall = !(this.inner instanceof PrefixedMcpServer);
@@ -6814,6 +6990,16 @@ export class PrefixedMcpServer implements MCPServer {
       // state. The broker refreshed credentials for future requests but did not
       // replay this call. Preserve that ambiguity as an explicit model-visible
       // error for required and best-effort servers alike.
+      if (hasActiveRecoverableMcpOperation()) {
+        recordOutcome(
+          isToolOutcomeUncertainMcpError(error)
+            ? "outcome_uncertain"
+            : isAuthNeededMcpError(error)
+              ? "auth_needed"
+              : mcpThrownToolCallOutcome(error, options?.signal),
+        );
+        throw error;
+      }
       if (isToolOutcomeUncertainMcpError(error)) {
         recordOutcome("outcome_uncertain");
         return boundedMcpToolResult({

package/src/lazy-tool-transport.ts

@@ -33,6 +33,8 @@ const ALWAYS_VISIBLE_BASE_TOOL_NAMES: ReadonlySet<string> = new Set([
   "apply_patch",
   // The server-backed reader needs neither sandbox setup nor tool search.
   "skill_read",
+  // Repository descriptors route to the live sandbox reader.
+  "repository_skill_read",
   "request_human_input",
   "list_models",
 ]);