@opengeni/runtime 3.0.1 → 4.0.0-canary.35585322809001

package/src/lazy-manifest.ts

@@ -0,0 +1,55 @@
+import { Manifest, type SandboxSessionLike } from "@openai/agents/sandbox";
+import { isDeepStrictEqual } from "node:util";
+
+/** Record already-materialized directory placeholders after lazy setup. This is
+ * not manifest application: never change environment, permissions, grants,
+ * mounts, files, or existing entries. Non-placeholder deltas remain visible to
+ * the SDK's normal validation/invalidation path. */
+export async function recordLazyMaterializedDirectories(
+  session: SandboxSessionLike,
+  target: Manifest,
+): Promise<void> {
+  const current = session.state.manifest;
+  const { entries: currentEntries, ...currentMetadata } = current;
+  const { entries: targetEntries, ...targetMetadata } = target;
+  if (!isDeepStrictEqual(currentMetadata, targetMetadata) || !session.listDir) return;
+  const additions = Object.entries(targetEntries).filter(([path]) => !(path in currentEntries));
+  if (
+    Object.entries(currentEntries).some(
+      ([path, entry]) => path in targetEntries && !isDeepStrictEqual(entry, targetEntries[path]),
+    )
+  )
+    return;
+  // A plain directory is the logical placeholder for a repository cloned by
+  // setup. Rich directories, sources and permissions require SDK materialization.
+  const emptyDirectory = new Manifest({ entries: { placeholder: { type: "dir" } } }).entries
+    .placeholder;
+  if (additions.some(([, entry]) => !isDeepStrictEqual(entry, emptyDirectory))) return;
+  // iterEntries validates every logical path before any live filesystem access.
+  const paths = new Map([...target.iterEntries()].map((entry) => [entry.logicalPath, entry]));
+  const directories = new Map<
+    string,
+    Awaited<ReturnType<NonNullable<SandboxSessionLike["listDir"]>>>
+  >();
+  for (const [path] of additions) {
+    let directory = target.root;
+    // Listing the target itself follows symlinks on some adapters. Walk every
+    // ancestor through its parent's typed listing instead, exactly like the
+    // repository reader. Cache only these invocation-local parent listings.
+    for (const name of paths.get(path)!.logicalPath.split("/")) {
+      let entries = directories.get(directory);
+      if (!entries) {
+        entries = await session.listDir({ path: directory });
+        directories.set(directory, entries);
+      }
+      if (!entries.some((entry) => entry.name === name && entry.type === "dir")) return;
+      directory = `${directory.replace(/\/$/, "")}/${name}`;
+    }
+  }
+  // Do not overwrite a concurrent manifest update.
+  if (session.state.manifest !== current || additions.length === 0) return;
+  session.state.manifest = new Manifest({
+    ...current,
+    entries: { ...currentEntries, ...targetEntries },
+  });
+}

package/src/lazy-tool-transport.ts

@@ -1,3 +1,4 @@
+import { rememberPreparedModelRequest } from "./prepared-compaction-request";
 import {
   tool as agentTool,
   toolSearchTool,
@@ -185,6 +186,7 @@ export class LazyToolRuntime {
     private readonly toolPreparationReady?: Promise<void>,
     private readonly deferredMcpServerIds: ReadonlySet<string> = mcpServerIds,
     private readonly preparationIndependentToolNames: ReadonlySet<string> = new Set(),
+    private readonly modelMcpServerIds: () => ReadonlyMap<string, string> = () => new Map(),
   ) {
     this.controlTools =
       transport !== "generic_dispatch"
@@ -289,6 +291,7 @@ export class LazyToolRuntime {
     this.currentTools = tools;
     this.functionTools.clear();
     this.searchableToolNames.clear();
+    const modelServerIds = this.modelMcpServerIds();
     for (const tool of tools) {
       if (!isFunctionTool(tool)) continue;
       this.functionTools.set(tool.name, tool);
@@ -297,8 +300,8 @@ export class LazyToolRuntime {
       // Origin, not transport: deferred MCP plus every non-MCP function tool
       // outside the base set. ToolRef.eager still decides the MCP arm.
       const lazy =
-        isSearchableMcpFunctionTool(tool, this.deferredMcpServerIds) ||
-        !isSearchableMcpFunctionTool(tool, this.mcpServerIds);
+        isSearchableMcpFunctionTool(tool, this.deferredMcpServerIds, modelServerIds) ||
+        !isSearchableMcpFunctionTool(tool, this.mcpServerIds, modelServerIds);
       if (lazy) {
         // After the preparation fence, deferred tools stay off the Agent
         // list. Search teaches names; a remembered raw name binds later
@@ -489,6 +492,12 @@ export class LazyToolRuntime {
           tools: descriptors,
           total: tools.length,
           nextCursor: index < tools.length ? descriptors.at(-1)!.name : null,
+          ...(prefix && tools.length === 0
+            ? {
+                message:
+                  "No tool names match this literal prefix. Retry tool_list without namePrefix to browse the authorized catalog; tool names can include a server namespace.",
+              }
+            : {}),
         });
       },
     }) as unknown as Tool;
@@ -581,6 +590,7 @@ export function installLazyToolRuntime(
   toolPreparationReady?: Promise<void>,
   deferredMcpServerIds: ReadonlySet<string> = mcpServerIds,
   preparationIndependentToolNames: ReadonlySet<string> = new Set(),
+  modelMcpServerIds?: () => ReadonlyMap<string, string>,
 ): LazyToolRuntime {
   const runtime = new LazyToolRuntime(
     transport,
@@ -588,6 +598,7 @@ export function installLazyToolRuntime(
     toolPreparationReady,
     deferredMcpServerIds,
     preparationIndependentToolNames,
+    modelMcpServerIds,
   );
   installLazyToolRuntimeOnAgent(agent, runtime);
   return runtime;
@@ -815,6 +826,7 @@ class LazyToolModel implements Model {
 
   async getResponse(request: ModelRequest): Promise<ModelResponse> {
     const prepared = prepareLazyToolRequest(request, this.runtime);
+    rememberPreparedModelRequest(prepared);
     void notifyModelRequestCapture(prepared);
     const response = await this.inner.getResponse(prepared);
     if (responseRequiresToolPreparation(response, this.runtime)) {
@@ -827,6 +839,7 @@ class LazyToolModel implements Model {
 
   async *getStreamedResponse(request: ModelRequest): AsyncIterable<StreamEvent> {
     const prepared = prepareLazyToolRequest(request, this.runtime);
+    rememberPreparedModelRequest(prepared);
     void notifyModelRequestCapture(prepared);
     for await (const event of this.inner.getStreamedResponse(prepared)) {
       if (event.type === "response_done") {

package/src/metrics.ts

@@ -48,6 +48,12 @@ export type RuntimeMetricsHooks = {
     outcome: "put" | "put_failed" | "deleted_unpublished";
     backend: string;
   }) => void;
+  /** Physical capture plus publication; emitted at settlement, not caller timeout. */
+  onWorkspaceCapture?: (input: {
+    backend: string;
+    outcome: "completed" | "failed";
+    durationSeconds: number;
+  }) => void;
   /**
    * One physical MCP tools/call invocation. The closed outcome enum deliberately
    * excludes server, tool, tenant, request, and error-content labels.

package/src/model-request-capture.ts

@@ -1,3 +1,4 @@
+import { rememberPreparedModelRequest } from "./prepared-compaction-request";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Model, ModelProvider, ModelRequest, StreamEvent } from "@openai/agents";
 
@@ -132,11 +133,13 @@ export class ModelRequestCaptureModel implements Model {
   constructor(private readonly inner: Model) {}
 
   async getResponse(request: ModelRequest) {
+    rememberPreparedModelRequest(request);
     void notifyModelRequestCapture(request);
     return this.inner.getResponse(request);
   }
 
   async *getStreamedResponse(request: ModelRequest): AsyncIterable<StreamEvent> {
+    rememberPreparedModelRequest(request);
     void notifyModelRequestCapture(request);
     yield* this.inner.getStreamedResponse(request);
   }

package/src/operational-instructions.ts

@@ -60,9 +60,12 @@ In your final answer back to the user, focus on the most important information.
 Your answer is being rendered by an application for the user. Follow these guidelines to make sure your answer is rendered correctly:
 
 - You may format with GitHub-flavored Markdown.
-- When referencing a real local file, prefer a clickable markdown link.
+- User-facing reports are durable document Artifacts by default, including audit or summary reports produced while doing another task. Read the opengeni-documents Skill and create the native document artifact before authoring the report. Do not write a sandbox Markdown/DOCX report first or treat publishing a file as native document creation.
+- Declare report deliverables through the available goal tools before authoring, including reports discovered after a goal was created. Inspect the relevant final artifact head after the last edit, supply its verified delivery evidence at goal completion, and give the user the artifact reference returned by the tools. A sandbox path, a raw file ID, or an assertion that a report exists is not completed report delivery.
+- If artifact creation, inspection, access, or delivery tooling is unavailable or fails, report the concrete blocker and leave report delivery incomplete. Do not silently fall back to a sandbox link, invent an artifact reference, or claim success. Ordinary in-chat answers, brief progress updates, internal worker findings, source-code navigation, and explicitly requested local-file workflows do not become report deliverables merely because they contain Markdown or a file link.
+- When referencing a real local source file or an explicitly requested local file, prefer a clickable markdown link.
   * Clickable file links should look like [app.py](sandbox:/workspace/app.py:12): plain label, sandbox:/workspace/... target, with optional line number after the path.
-  * If a file path has spaces, wrap the target in angle brackets: [My Report.md](<sandbox:/workspace/My Project/My Report.md:3>).
+  * If a file path has spaces, wrap the target in angle brackets: [My Component.ts](<sandbox:/workspace/My Project/My Component.ts:3>).
   * Use the active workspace path exactly as exposed to you. Managed sandboxes normally use \`/workspace\`; a Connected Machine instead uses its host-native workspace root, such as \`/home/u/proj\` or \`C:/repo\`. Both are valid inside a \`sandbox:\` link when they are the active workspace.
   * Connected Machine examples are [app.py](sandbox:/home/u/proj/app.py:12) on POSIX and [app.ts](<sandbox:C:/repo/app.ts:12>) on Windows.
   * On a Connected Machine, absolute file links may point outside the working directory (including sibling worktrees and temporary files); use the real path on the selected machine.
@@ -147,12 +150,18 @@ Skills are reusable instructions supplied dynamically for the current session. W
 - The user's instructions take precedence over skill guidance.
 - If a named skill is unavailable or cannot be read, say so briefly and continue with the best fallback.
 
+# Integration setup
+
+Use available integration tools directly. If the task needs an integration you cannot access, discover it with \`capability_catalog_search\` before declaring a setup blocker. For a suitable match with \`setup.nextAction\`, call \`capability_authorization_request\` with the returned capability ID and a brief task-specific rationale to show its Connect card in chat. Requesting the card does not need integration-management permission; the authenticated human must authorize setup. After setup, rediscover the tools and continue the task, verifying the access it needs. If access remains blocked, explain the specific blocker from the returned facts. If either setup tool is unavailable, report the missing setup path.
+
 # Session coordination
 
 Use \`session_events\` for conversation history: its default returns user and completed assistant messages, not execution noise. Cursors only paginate. Request \`results\` for final outcomes, \`tools\` for tool receipts, or \`debug\` for explicit diagnostics; request large tool bodies only when needed. Use the returned continuation cursor rather than rereading whole pages. Audit reads do not acknowledge command completion.
 
 For a yielded command, use \`command_read\` to read available output and status, or \`command_wait\` to wait briefly using the same command interface. Keep the command ID and output cursor. A terminal read suppresses any still-pending completion notification; a running read does not. Earlier tool results and delivered messages never change. Use \`command_input\` only to send input where supported, not to poll output. An unsupported input capability does not imply output is unavailable. Give foreground commands a realistic requested wait; default to 10 seconds (yield_time_ms: 10000). An internal polling slice is not a reason to return a background handle.
 
+Command completion alone resumes you only while you have an explicit \`wait_for_input\` registered. If remaining work depends on background commands, register that session-level wait before ending your turn. If you finish normally, command results remain retained and can accompany later input, but do not start another turn by themselves. No per-command dismissal is required.
+
 If the user asks to create, inspect, continue, pause, resume, steer, rename, or otherwise manage a session, use the corresponding session tool. Pause affects the selected workstream and its descendants: pausing an ancestor also stops you, so you cannot then Resume yourself. Coordinate disjoint edits through messages instead of ancestor Pause.
 
 Create a child worker only for a concrete, bounded subtask that can run independently and whose result has a clear integration point in the current request. Before spawning, decide what output you need and keep the parent's concurrent work disjoint. Do not delegate a scope that you will also perform yourself. If no useful independent work remains, continue in this session. Do not repurpose or direct an unrelated existing session unless the user explicitly asks. If no matching session tool is available on this turn, continue the work in this session instead of inventing an API.

package/src/prepared-compaction-request.ts

@@ -0,0 +1,51 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { CallModelInputFilter, ModelRequest } from "@openai/agents";
+import { findCompactionNeededError } from "./context-compaction";
+
+/** One owner per run; never share a prefix between sessions or rebuilt agents. */
+const requests = new WeakMap<object, Omit<ModelRequest, "input">>();
+const dispatch = new AsyncLocalStorage<{ agent: object; pending?: unknown }>();
+const queued = new WeakMap<object, unknown>();
+
+export function queuePreparedCompaction(agent: object, error: unknown): void {
+  queued.set(agent, error);
+}
+
+export function withPreparedCompactionRequest<T>(agent: object, run: () => T): T {
+  const pending = queued.get(agent);
+  queued.delete(agent);
+  return dispatch.run({ agent, pending }, run);
+}
+
+/** Called after SDK sandbox preparation AND lazy-tool filtering, before transport. */
+export function rememberPreparedModelRequest(request: ModelRequest): void {
+  const scope = dispatch.getStore();
+  if (!scope) return;
+  const { input: _input, ...prefix } = request;
+  requests.set(scope.agent, {
+    ...prefix,
+    tools: structuredClone(request.tools),
+    modelSettings: structuredClone(request.modelSettings),
+  });
+  if (scope.pending) throw scope.pending;
+}
+
+export function preparedCompactionRequest(agent: object): Omit<ModelRequest, "input"> {
+  const request = requests.get(agent);
+  if (!request) throw new Error("Compaction requires a prepared model request");
+  return request;
+}
+
+/** Finish normal preparation, but never send ordinary inference once compaction is due. */
+export function deferCompactionToModelBoundary(filter: CallModelInputFilter): CallModelInputFilter {
+  return async (args) => {
+    try {
+      return await filter(args);
+    } catch (error) {
+      const scope = dispatch.getStore();
+      if (!scope || !findCompactionNeededError(error)) throw error;
+      scope.pending = error;
+      return args.modelData;
+    }
+  };
+}

package/src/provider-history-adapter.ts

@@ -73,15 +73,24 @@ function isChatIncompatibleHostedToolCall(item: Record<string, unknown>): boolea
 
 /**
  * Build the one attempt-local history view required by the target wire API.
- * Canonical history remains untouched. Responses history is returned by
- * reference. Chat-compatible history is also returned by reference when every
+ * Canonical history remains untouched. SDK-unsupported developer messages use
+ * the Responses pass-through item. Other history is returned by reference when every
  * item is already representable by the SDK's Chat Completions converter.
  */
 export function projectHistoryForProvider(
   items: Array<Record<string, unknown>>,
   providerApi: HistoryProviderApi,
 ): Array<Record<string, unknown>> {
-  if (providerApi === "responses") return items;
+  if (providerApi === "responses") {
+    if (!items.some((item) => item.type === "message" && item.role === "developer")) return items;
+    // agents-js 0.14's message converter supports system/user/assistant only.
+    // The Responses API itself supports developer; use the SDK's raw-item adapter.
+    return items.map((item) =>
+      item.type === "message" && item.role === "developer"
+        ? { type: "unknown", providerData: item }
+        : item,
+    );
+  }
 
   const incompatibleCallIds = new Set<string>();
   for (const item of items) {

package/src/runtime-skills.ts

@@ -19,8 +19,7 @@ export type RuntimeSkillArtifactFile = Readonly<{
 
 /**
  * One immutable Skill artifact that may be activated by an installation, a
- * Pack, or an exact session selection. The artifact itself is deliberately
- * acquisition-neutral: Packs do not own a second Skill representation.
+ * session selection. The artifact itself is acquisition-neutral.
  */
 export type RuntimeSkillArtifact = Readonly<{
   name: string;
@@ -37,13 +36,6 @@ export type InstalledSkillActivation = Readonly<{
   reason: string;
 }>;
 
-export type PackSkillActivation = Readonly<{
-  source: "pack";
-  id: string;
-  artifact: RuntimeSkillArtifact;
-  reason: string;
-}>;
-
 export type SessionSkillActivation = Readonly<{
   source: "session";
   id: string;
@@ -51,10 +43,7 @@ export type SessionSkillActivation = Readonly<{
   reason: string;
 }>;
 
-export type RuntimeSkillActivation =
-  | InstalledSkillActivation
-  | PackSkillActivation
-  | SessionSkillActivation;
+export type RuntimeSkillActivation = InstalledSkillActivation | SessionSkillActivation;
 
 export type NativeToolSkillSet = Readonly<{
   /** False when an embedding host owns the complete Skill catalog and reader. */
@@ -67,7 +56,7 @@ export type NativeToolSkillSet = Readonly<{
 export type EffectiveSkillSelection = Readonly<{
   id: string;
   name: string;
-  source: "installation" | "pack" | "session" | "native_tool";
+  source: "installation" | "session" | "native_tool";
   version: string | null;
   contentSha256: string | null;
   reason: string;
@@ -321,8 +310,6 @@ function activationPrecedence(source: RuntimeSkillActivation["source"]): number
   switch (source) {
     case "installation":
       return 1;
-    case "pack":
-      return 2;
     case "session":
       return 3;
   }
@@ -369,7 +356,6 @@ function selectionForActivation({
         contentSha256,
         reason: activation.reason,
       });
-    case "pack":
     case "session":
       return Object.freeze({
         id: activation.id,

package/src/sandbox/codemode-client.ts

@@ -0,0 +1,204 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, posix, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { SandboxSessionLike } from "@openai/agents/sandbox";
+import { sandboxCommandExitCode } from "./command-result";
+
+/** Data shipped with the worker, never fetched from a package registry at turn time. */
+export type ManagedCodemodeClient = {
+  version: 1;
+  files: { ogtool: string; "client.mjs": string; "package.json": string };
+};
+
+export function managedCodemodeClientDigest(client: ManagedCodemodeClient): string {
+  return createHash("sha256").update(JSON.stringify(client)).digest("hex");
+}
+
+export function managedCodemodeClientDirectory(
+  client: ManagedCodemodeClient,
+  workspaceRoot = "/workspace",
+): string {
+  if (!posix.isAbsolute(workspaceRoot) || workspaceRoot.includes("\0")) {
+    throw new Error("Managed Codemode client workspace root must be absolute");
+  }
+  return posix.join(
+    workspaceRoot,
+    ".opengeni/codemode-clients",
+    managedCodemodeClientDigest(client),
+  );
+}
+
+export async function buildManagedCodemodeClient(root: string): Promise<ManagedCodemodeClient> {
+  const bundle = async (entry: string, format: "esm" | "cjs", banner?: string) => {
+    const result = await Bun.build({
+      entrypoints: [join(root, entry)],
+      target: "node",
+      format,
+      minify: true,
+      sourcemap: "none",
+      ...(banner ? { banner } : {}),
+    });
+    if (!result.success || result.outputs.length !== 1) {
+      throw new Error(`Managed Codemode client build failed: ${entry}`);
+    }
+    return await result.outputs[0]!.text();
+  };
+  return {
+    version: 1,
+    files: {
+      ogtool: await bundle("packages/ogtool/src/cli.ts", "cjs", "#!/usr/bin/env node"),
+      "client.mjs": await bundle("packages/codemode/src/index.ts", "esm"),
+      // The extensionless executable must not inherit a user's ESM workspace.
+      "package.json": '{"type":"commonjs"}\n',
+    },
+  };
+}
+
+let releaseClient: Promise<ManagedCodemodeClient> | undefined;
+export function loadManagedCodemodeClient(): Promise<ManagedCodemodeClient> {
+  return (releaseClient ??= (async () => {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    // A checkout must not reuse stale dist assets after source changes.
+    const root = resolve(moduleDir, "../../../..");
+    if (
+      import.meta.url.endsWith("/src/sandbox/codemode-client.ts") &&
+      existsSync(join(root, "packages/ogtool/src/cli.ts"))
+    ) {
+      return await buildManagedCodemodeClient(root);
+    }
+    const candidates = [
+      join(moduleDir, "assets/codemode-client.json"),
+      join(moduleDir, "../assets/codemode-client.json"),
+      join(moduleDir, "../../dist/assets/codemode-client.json"),
+    ];
+    for (const path of candidates) {
+      if (!existsSync(path)) continue;
+      const value = JSON.parse(readFileSync(path, "utf8")) as ManagedCodemodeClient;
+      if (
+        !value ||
+        typeof value !== "object" ||
+        value.version !== 1 ||
+        Object.keys(value).sort().join(",") !== "files,version" ||
+        typeof value.files?.ogtool !== "string" ||
+        typeof value.files?.["client.mjs"] !== "string" ||
+        value.files?.["package.json"] !== '{"type":"commonjs"}\n' ||
+        Object.keys(value.files).sort().join(",") !== "client.mjs,ogtool,package.json"
+      ) {
+        throw new Error(
+          "Invalid deployment-owned managed Codemode client asset; rebuild the worker release",
+        );
+      }
+      return value;
+    }
+    // Published runtimes must carry their own exact bytes.
+    throw new Error(
+      "Managed Codemode client asset missing; rebuild and deploy the matching worker/runtime package (do not install latest or replace the sandbox)",
+    );
+  })());
+}
+
+function quote(value: string): string {
+  return `'${value.replace(/'/g, "'\\''")}'`;
+}
+
+/** Immutable per-release paths permit old/new workers to share a warm box. */
+export async function installManagedCodemodeClient(
+  session: SandboxSessionLike,
+  client: ManagedCodemodeClient,
+  run: (cmd: string) => Promise<unknown>,
+  runAs?: string,
+  workspaceRoot = "/workspace",
+): Promise<void> {
+  const directory = managedCodemodeClientDirectory(client, workspaceRoot);
+  const digest = managedCodemodeClientDigest(client);
+  const verify = `
+const fs = require('node:fs'), crypto = require('node:crypto');
+const root = ${JSON.stringify(directory)};
+if (!fs.lstatSync(root).isDirectory()) process.exit(1);
+for (const name of ['ogtool', 'client.mjs', 'package.json']) {
+  if (!fs.lstatSync(root + '/' + name).isFile()) process.exit(1);
+}
+fs.accessSync(root + '/ogtool', fs.constants.X_OK);
+const files = {ogtool: fs.readFileSync(root + '/ogtool', 'utf8'), 'client.mjs': fs.readFileSync(root + '/client.mjs', 'utf8'), 'package.json': fs.readFileSync(root + '/package.json', 'utf8')};
+if (crypto.createHash('sha256').update(JSON.stringify({version: 1, files})).digest('hex') !== ${JSON.stringify(digest)}) process.exit(1);
+`;
+  if (sandboxCommandExitCode(await run(`node -e ${quote(verify)} 2>/dev/null`)) === 0) return;
+  const editor = session.createEditor?.(runAs);
+  if (!editor)
+    throw new Error(
+      "Managed Codemode client delivery requires sandbox file ingress; update the sandbox provider adapter",
+    );
+  const stage = `${posix.dirname(directory)}/stage-${randomUUID()}.json`;
+  let installationFailure: { error: unknown } | undefined;
+  try {
+    await editor.createFile({
+      type: "create_file",
+      path: stage,
+      diff: `+${JSON.stringify(client)}`,
+    });
+    const install = `
+const fs = require('node:fs'), crypto = require('node:crypto');
+const raw = fs.readFileSync(${JSON.stringify(stage)}, 'utf8').trim();
+if (crypto.createHash('sha256').update(raw).digest('hex') !== ${JSON.stringify(digest)}) throw Error('Codemode client transfer integrity failure');
+const data = JSON.parse(raw), root = ${JSON.stringify(directory)};
+fs.mkdirSync(root, {recursive: true});
+if (!fs.lstatSync(root).isDirectory()) throw Error('Codemode client directory must not be a symlink');
+for (const name of ['package.json', 'ogtool', 'client.mjs']) {
+  const tmp = root + '/' + name + '.' + crypto.randomUUID();
+  fs.writeFileSync(tmp, data.files[name], {mode: 0o755, flag: 'wx'});
+  fs.renameSync(tmp, root + '/' + name);
+}
+`;
+    const result = await run(`node -e ${quote(install)} && node -e ${quote(verify)}`);
+    if (sandboxCommandExitCode(result) !== 0) {
+      throw new Error(
+        "Managed Codemode client delivery failed; verify Node and sandbox file ingress, then retry with the same worker release",
+      );
+    }
+  } catch (error) {
+    installationFailure = { error };
+  }
+  let cleanupFailure: Error | undefined;
+  try {
+    await editor.deleteFile({ type: "delete_file", path: stage });
+  } catch (editorFailure) {
+    // A provider can support ingress but lose its delete reply. Remove only
+    // this exact attempt's staging file, through the same command fence.
+    try {
+      const cleanup = await run(
+        `node -e ${quote(`require('node:fs').rmSync(${JSON.stringify(stage)}, {force: true})`)}`,
+      );
+      if (sandboxCommandExitCode(cleanup) !== 0) {
+        throw new Error("Staging file removal failed", { cause: editorFailure });
+      }
+    } catch (commandFailure) {
+      cleanupFailure = new AggregateError(
+        [editorFailure, commandFailure],
+        "Both cleanup paths failed",
+        { cause: commandFailure },
+      );
+    }
+  }
+  if (cleanupFailure) {
+    throw new AggregateError(
+      installationFailure ? [installationFailure.error, cleanupFailure] : [cleanupFailure],
+      "Managed Codemode client staging cleanup failed; restore sandbox file ingress/command execution before retrying",
+      { cause: installationFailure?.error ?? cleanupFailure },
+    );
+  }
+  if (installationFailure) throw installationFailure.error;
+}
+
+export function managedCodemodeClientEnvironment(directory: string): string[] {
+  return [
+    // A routing proxy can switch to a Connected Machine during the attempt.
+    // Its native client is projected by the connection-bound exec transport.
+    'if [ -z "${OPENGENI_CODEMODE_NATIVE_CLIENT:-}" ]; then',
+    `  export PATH=${quote(directory)}:"$PATH"`,
+    `  export OPENGENI_CODEMODE_CLIENT_MODULE=${quote(`${directory}/client.mjs`)}`,
+    "else",
+    "  unset OPENGENI_CODEMODE_CLIENT_MODULE",
+    "fi",
+  ];
+}

package/src/sandbox/codemode-token.ts

@@ -1,5 +1,6 @@
 import { createHash } from "node:crypto";
 import { posix as posixPath } from "node:path";
+import { managedCodemodeClientEnvironment } from "./codemode-client";
 
 import type {
   ExecCommandArgs,
@@ -86,10 +87,12 @@ export function withCodemodeTokenEnvironment(
   cmd: string,
   tokenFile: string,
   codemodeUrl?: string,
+  clientDirectory?: string,
 ): string {
   return [
     `export OPENGENI_CODEMODE_TOKEN_FILE=${shellCodemodePath(tokenFile)}`,
     ...(codemodeUrl ? [`export OPENGENI_CODEMODE_URL=${shellQuote(codemodeUrl)}`] : []),
+    ...(clientDirectory ? managedCodemodeClientEnvironment(clientDirectory) : []),
     cmd,
   ].join("\n");
 }
@@ -99,6 +102,7 @@ export function withCodemodeTokenSession<T extends object>(
   session: T,
   tokenFile: string,
   codemodeUrl?: string,
+  clientDirectory?: string,
 ): T {
   return new Proxy(session, {
     get(target, property, receiver) {
@@ -110,7 +114,7 @@ export function withCodemodeTokenSession<T extends object>(
         return async (args: ExecCommandArgs) =>
           await command.call(target, {
             ...args,
-            cmd: withCodemodeTokenEnvironment(args.cmd, tokenFile, codemodeUrl),
+            cmd: withCodemodeTokenEnvironment(args.cmd, tokenFile, codemodeUrl, clientDirectory),
           });
       }
       const value = Reflect.get(target, property, receiver) as unknown;
@@ -124,12 +128,13 @@ export function withCodemodeTokenClient(
   client: SandboxClient,
   tokenFile: string,
   codemodeUrl?: string,
+  clientDirectory?: string,
 ): SandboxClient {
   const decorated = new WeakMap<object, SandboxSessionLike>();
   const wrap = <T extends SandboxSessionLike>(session: T): T => {
     const existing = decorated.get(session);
     if (existing) return existing as T;
-    const wrapped = withCodemodeTokenSession(session, tokenFile, codemodeUrl);
+    const wrapped = withCodemodeTokenSession(session, tokenFile, codemodeUrl, clientDirectory);
     decorated.set(session, wrapped);
     return wrapped;
   };

package/src/sandbox/index.ts

@@ -86,6 +86,12 @@ import type { ExposedPortEndpoint } from "./stream-port";
 // a single agent-loop-free entrypoint. They physically live in @opengeni/config
 // (moving them into runtime would create a config→runtime cycle — ledger CR8).
 export { collectSandboxEnvironment, parseExposedPorts } from "@opengeni/config";
+export {
+  SandboxMaterializationVerificationError,
+  materializationVerificationDiagnostic,
+  type MaterializationFailureReason,
+  type MaterializationVerificationDiagnostic,
+} from "./materialization-verification-error";
 export { sendCommandInput, type CommandInputSession } from "./command-input";
 export { OpStreamExecClient, type OpStreamOutputFrame } from "./selfhosted/op-stream";
 
@@ -593,6 +599,7 @@ export {
   type RoutingSandboxFirstOperationPhaseObservation,
   type RoutingSandboxOperationObservation,
   type RoutingSandboxOperationObserver,
+  type RoutingSandboxCaptureWaitObserver,
   type RoutingSandboxPhaseOutcome,
   type RoutingSandboxWaitObservation,
   type RoutingRetainedProcess,