@opengeni/runtime 0.14.1 → 0.14.15

package/src/sandbox/turn-tool-cancellation.ts

@@ -308,15 +308,53 @@ function shellMarkerPath(token: string): string {
   return `${SHELL_MARKER_DIR}/${token}`;
 }
 
+function processInspectionCommandLines(): string[] {
+  return [
+    "__opengeni_process_group_id() {",
+    '  __opengeni_lookup_pid="$1"',
+    '  __opengeni_lookup_pgid=""',
+    "  if command -v ps >/dev/null 2>&1; then",
+    '    __opengeni_lookup_pgid="$(command ps -o pgid= -p "$__opengeni_lookup_pid" 2>/dev/null | command tr -d \'[:space:]\')"',
+    "  fi",
+    '  case "$__opengeni_lookup_pgid" in',
+    '    ""|*[!0-9]*) ;;',
+    "    *) command printf '%s\\n' \"$__opengeni_lookup_pgid\"; return 0 ;;",
+    "  esac",
+    '  [ -r "/proc/$__opengeni_lookup_pid/stat" ] || return 1',
+    '  IFS= read -r __opengeni_lookup_stat < "/proc/$__opengeni_lookup_pid/stat" || return 1',
+    '  __opengeni_lookup_tail="${__opengeni_lookup_stat##*) }"',
+    '  [ "$__opengeni_lookup_tail" != "$__opengeni_lookup_stat" ] || return 1',
+    "  set -- $__opengeni_lookup_tail",
+    '  [ "$#" -ge 3 ] || return 1',
+    '  case "$3" in ""|*[!0-9]*) return 1 ;; esac',
+    "  command printf '%s\\n' \"$3\"",
+    "}",
+    "__opengeni_process_args() {",
+    '  __opengeni_lookup_pid="$1"',
+    '  __opengeni_lookup_args=""',
+    "  if command -v ps >/dev/null 2>&1; then",
+    '    __opengeni_lookup_args="$(command ps -ww -o args= -p "$__opengeni_lookup_pid" 2>/dev/null)"',
+    "  fi",
+    '  if [ -n "$__opengeni_lookup_args" ]; then',
+    "    command printf '%s\\n' \"$__opengeni_lookup_args\"",
+    "    return 0",
+    "  fi",
+    '  [ -r "/proc/$__opengeni_lookup_pid/cmdline" ] || return 1',
+    "  command tr '\\000' ' ' < \"/proc/$__opengeni_lookup_pid/cmdline\"",
+    "}",
+  ];
+}
+
 function cancellableGroupLeaderCommand(command: string, markerPath: string): string {
   const marker = singleQuote(markerPath);
   const markerDir = singleQuote(SHELL_MARKER_DIR);
   return [
+    ...processInspectionCommandLines(),
     `__opengeni_marker=${marker}`,
     "umask 077",
     `command mkdir -p ${markerDir} || exit 125`,
     '__opengeni_pid="$$"',
-    '__opengeni_pgid="$(command ps -o pgid= -p "$__opengeni_pid" 2>/dev/null | command tr -d \'[:space:]\')"',
+    '__opengeni_pgid="$(__opengeni_process_group_id "$__opengeni_pid")"',
     'case "$__opengeni_pid:$__opengeni_pgid" in *[!0-9:]*|*:|:*) exit 125 ;; esac',
     '[ "$__opengeni_pid" -gt 1 ] && [ "$__opengeni_pgid" -gt 1 ] || exit 125',
     // Never signal a provider/container-wide process group. A cancellable PTY
@@ -335,8 +373,9 @@ function cancellableGroupLeaderCommand(command: string, markerPath: string): str
 export function cancellableShellCommand(command: string, markerPath: string): string {
   const groupLeaderCommand = cancellableGroupLeaderCommand(command, markerPath);
   return [
+    ...processInspectionCommandLines(),
     '__opengeni_outer_pid="$$"',
-    '__opengeni_outer_pgid="$(command ps -o pgid= -p "$__opengeni_outer_pid" 2>/dev/null | command tr -d \'[:space:]\')"',
+    '__opengeni_outer_pgid="$(__opengeni_process_group_id "$__opengeni_outer_pid")"',
     'case "$__opengeni_outer_pid:$__opengeni_outer_pgid" in *[!0-9:]*|*:|:*) exit 125 ;; esac',
     'if [ "$__opengeni_outer_pid" != "$__opengeni_outer_pgid" ]; then',
     '  __opengeni_setsid="$(command -v setsid 2>/dev/null)"',
@@ -400,15 +439,16 @@ function identityGuardScript(
   if (!identity || !state.token) return `exit ${missingIdentityExitCode}`;
   const token = singleQuote(state.token);
   return [
+    ...processInspectionCommandLines(),
     `__opengeni_pid=${identity.pid}`,
     `__opengeni_pgid=${identity.processGroupId}`,
     `__opengeni_token=${token}`,
-    // The randomized token lands late in the wrapped command line. Procps
-    // otherwise truncates `args` to the terminal width, which can make a live
-    // group look stale and open the quiescence fence without signalling it.
-    '__opengeni_args="$(command ps -ww -o args= -p "$__opengeni_pid" 2>/dev/null)"',
+    // The randomized token lands late in the wrapped command line. Procps needs
+    // `-ww` to avoid terminal-width truncation; minimal Linux images may omit ps,
+    // so the same exact command line is read from /proc instead.
+    `__opengeni_args="$(__opengeni_process_args "$__opengeni_pid")" || exit ${missingIdentityExitCode}`,
     'case "$__opengeni_args" in *"$__opengeni_token"*) ;; *) exit 0 ;; esac',
-    '__opengeni_live_pgid="$(command ps -o pgid= -p "$__opengeni_pid" 2>/dev/null | command tr -d \'[:space:]\')"',
+    `__opengeni_live_pgid="$(__opengeni_process_group_id "$__opengeni_pid")" || exit ${missingIdentityExitCode}`,
     '[ "$__opengeni_live_pgid" = "$__opengeni_pgid" ] || exit 0',
     body,
   ].join("\n");

package/src/sandbox/workspace-archive.ts

@@ -1,28 +1,34 @@
 import { createHash } from "node:crypto";
+import {
+  WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  decodeNativeSnapshotRef,
+  parseWorkspaceArchiveDescriptor,
+  type NativeSnapshotDescriptor,
+  type NativeSnapshotRef,
+  type TarWorkspaceArchiveDescriptor,
+  type WorkspaceArchiveDescriptor,
+  type WorkspaceTreeFingerprint,
+} from "@opengeni/contracts";
+import { withSandboxProviderCapture } from "./provider-operation-gate";
 
-export const WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION = 1 as const;
-
-export type WorkspaceTreeFingerprint = {
-  algorithm: "sha256";
-  sha256: string;
-  entryCount: number;
-  fileCount: number;
-  totalFileBytes: number;
-};
-
-export type WorkspaceArchiveDescriptor = {
-  version: typeof WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION;
-  revision: string;
-  archiveSha256: string;
-  archiveBytes: number;
-  capturedAt: string;
-  workspace: WorkspaceTreeFingerprint;
-};
+export {
+  WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  decodeNativeSnapshotRef,
+  parseWorkspaceArchiveDescriptor,
+  type NativeSnapshotDescriptor,
+  type NativeSnapshotProvider,
+  type NativeSnapshotRef,
+  type TarWorkspaceArchiveDescriptor,
+  type WorkspaceArchiveDescriptor,
+  type WorkspaceTreeFingerprint,
+} from "@opengeni/contracts";
 
 export type VerifiedWorkspaceArchive = {
   bytes: Uint8Array;
   base64: string;
   descriptor: WorkspaceArchiveDescriptor;
+  kind: "tar" | "provider_snapshot";
+  nativeSnapshot?: NativeSnapshotRef;
 };
 
 export type WorkspaceArchiveIntegrityCode =
@@ -33,7 +39,9 @@ export type WorkspaceArchiveIntegrityCode =
   | "archive_hydration_failed"
   | "workspace_fingerprint_unavailable"
   | "workspace_changed_during_capture"
-  | "workspace_fingerprint_mismatch";
+  | "workspace_fingerprint_mismatch"
+  | "native_snapshot_reference_invalid"
+  | "native_snapshot_fallback_unverified";
 
 export class WorkspaceArchiveIntegrityError extends Error {
   readonly name = "WorkspaceArchiveIntegrityError";
@@ -61,46 +69,18 @@ type WorkspaceSession = {
     maxOutputTokens?: number;
   }) => Promise<unknown>;
   persistWorkspace?: () => Promise<Uint8Array | undefined>;
+  state?: {
+    workspacePersistence?: unknown;
+    manifest?: {
+      ephemeralPersistencePaths?: () => Set<unknown>;
+    };
+  };
 };
 
-const SHA256 = /^[a-f0-9]{64}$/;
-const REVISION = /^wa1:[0-9]{13}:[a-f0-9]{64}$/;
-
 function sha256(bytes: Uint8Array): string {
   return createHash("sha256").update(bytes).digest("hex");
 }
 
-function nonnegativeInteger(value: unknown): value is number {
-  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
-}
-
-export function parseWorkspaceArchiveDescriptor(value: unknown): WorkspaceArchiveDescriptor | null {
-  if (!value || typeof value !== "object") return null;
-  const candidate = value as Partial<WorkspaceArchiveDescriptor>;
-  const workspace = candidate.workspace as Partial<WorkspaceTreeFingerprint> | undefined;
-  if (
-    candidate.version !== WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION ||
-    typeof candidate.revision !== "string" ||
-    !REVISION.test(candidate.revision) ||
-    typeof candidate.archiveSha256 !== "string" ||
-    !SHA256.test(candidate.archiveSha256) ||
-    !nonnegativeInteger(candidate.archiveBytes) ||
-    candidate.archiveBytes === 0 ||
-    typeof candidate.capturedAt !== "string" ||
-    !Number.isFinite(Date.parse(candidate.capturedAt)) ||
-    !workspace ||
-    workspace.algorithm !== "sha256" ||
-    typeof workspace.sha256 !== "string" ||
-    !SHA256.test(workspace.sha256) ||
-    !nonnegativeInteger(workspace.entryCount) ||
-    !nonnegativeInteger(workspace.fileCount) ||
-    !nonnegativeInteger(workspace.totalFileBytes)
-  ) {
-    return null;
-  }
-  return candidate as WorkspaceArchiveDescriptor;
-}
-
 function decodeBase64Strict(value: string): Uint8Array | null {
   if (value.length === 0 || value.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(value)) {
     return null;
@@ -109,6 +89,37 @@ function decodeBase64Strict(value: string): Uint8Array | null {
   return Buffer.from(bytes).toString("base64") === value ? bytes : null;
 }
 
+export function describeNativeSnapshotArchive(
+  bytes: Uint8Array,
+  capturedAtMs = Date.now(),
+): NativeSnapshotDescriptor | null {
+  const native = decodeNativeSnapshotRef(bytes);
+  if (!native) return null;
+  const archiveSha256 = sha256(bytes);
+  return {
+    version: WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+    kind: "provider_snapshot",
+    revision: `wa2:${String(capturedAtMs).padStart(13, "0")}:${archiveSha256}`,
+    archiveSha256,
+    archiveBytes: bytes.length,
+    capturedAt: new Date(capturedAtMs).toISOString(),
+    provider: native.provider,
+    snapshotId: native.snapshotId,
+    ...(native.workspacePersistence ? { workspacePersistence: native.workspacePersistence } : {}),
+  };
+}
+
+export function describeLegacyNativeSnapshotArchive(
+  base64: unknown,
+  observedAtMs = Date.now(),
+): { archiveBase64: string; descriptor: NativeSnapshotDescriptor } | null {
+  if (typeof base64 !== "string") return null;
+  const bytes = decodeBase64Strict(base64);
+  if (!bytes) return null;
+  const descriptor = describeNativeSnapshotArchive(bytes, observedAtMs);
+  return descriptor ? { archiveBase64: base64, descriptor } : null;
+}
+
 export function readVerifiedWorkspaceArchive(
   base64: unknown,
   metadata: unknown,
@@ -147,7 +158,34 @@ export function readVerifiedWorkspaceArchive(
       `workspace archive revision ${descriptor.revision} failed SHA-256/size verification`,
     );
   }
-  return { bytes, base64, descriptor };
+  const nativeSnapshot = decodeNativeSnapshotRef(bytes);
+  if (descriptor.version === WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION) {
+    if (
+      !nativeSnapshot ||
+      nativeSnapshot.provider !== descriptor.provider ||
+      nativeSnapshot.snapshotId !== descriptor.snapshotId ||
+      nativeSnapshot.workspacePersistence !== descriptor.workspacePersistence
+    ) {
+      throw new WorkspaceArchiveIntegrityError(
+        "native_snapshot_reference_invalid",
+        `native snapshot receipt does not match descriptor revision ${descriptor.revision}`,
+      );
+    }
+  } else if (nativeSnapshot) {
+    throw new WorkspaceArchiveIntegrityError(
+      "native_snapshot_reference_invalid",
+      `legacy native snapshot receipt ${descriptor.revision} was not durably upgraded to a v2 provider descriptor`,
+    );
+  }
+  return {
+    bytes,
+    base64,
+    descriptor,
+    kind: descriptor.version === WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION ? "provider_snapshot" : "tar",
+    ...(descriptor.version === WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION && nativeSnapshot
+      ? { nativeSnapshot }
+      : {}),
+  };
 }
 
 function stdoutFromExecResult(value: unknown): string {
@@ -164,19 +202,47 @@ function stdoutFromExecResult(value: unknown): string {
       : "";
 }
 
-const WORKSPACE_FINGERPRINT_COMMAND = String.raw`bash -o pipefail -c '
-set -eu
+function shellQuote(value: string): string {
+  return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+
+function workspaceFingerprintExcludes(session: WorkspaceSession): string[] {
+  const paths = session.state?.manifest?.ephemeralPersistencePaths?.();
+  if (!paths) return [];
+  return [...paths]
+    .filter((path): path is string => typeof path === "string" && path.length > 0)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function workspaceFingerprintCommand(excludedPaths: readonly string[]): string {
+  const tarExcludes = excludedPaths.flatMap((path) => [
+    shellQuote(`--exclude=${path}`),
+    shellQuote(`--exclude=./${path}`),
+  ]);
+  const findExcludes = excludedPaths.flatMap((path) => [
+    `-path ${shellQuote(`./${path}`)}`,
+    `-path ${shellQuote(`./${path}/*`)}`,
+  ]);
+  const findPrefix =
+    findExcludes.length === 0 ? "" : `\\( ${findExcludes.join(" -o ")} \\) -prune -o `;
+  const script = String.raw`set -eu
 cd /workspace
-digest=$(LC_ALL=C tar --sort=name --mtime="@0" --owner=0 --group=0 --numeric-owner --format=gnu -cf - . | sha256sum | awk "{print \$1}")
-entries=$(find . -xdev -mindepth 1 -printf x | wc -c | tr -d " ")
-files=$(find . -xdev -type f -printf x | wc -c | tr -d " ")
-bytes=$(find . -xdev -type f -printf "%s\n" | awk "{s+=\$1} END {printf \"%.0f\", s+0}")
-printf "OPENGENI_WORKSPACE_FINGERPRINT_V1 %s %s %s %s\n" "$digest" "$entries" "$files" "$bytes"
-'`;
+digest=$(LC_ALL=C tar ${tarExcludes.join(" ")} --sort=name --mtime="@0" --owner=0 --group=0 --numeric-owner --hard-dereference --format=gnu -cf - . | sha256sum | awk "{print \$1}")
+entries=$(find . -xdev -mindepth 1 ${findPrefix}-printf x | wc -c | tr -d " ")
+files=$(find . -xdev ${findPrefix}-type f -printf x | wc -c | tr -d " ")
+bytes=$(find . -xdev ${findPrefix}-type f -printf "%s\n" | awk "{s+=\$1} END {printf \"%.0f\", s+0}")
+printf "OPENGENI_WORKSPACE_FINGERPRINT_V1 %s %s %s %s\n" "$digest" "$entries" "$files" "$bytes"`;
+  return `bash -o pipefail -c ${shellQuote(script)}`;
+}
 
 /** Hashes names, kinds, modes, symlink targets and all file bytes through one
- * deterministic GNU tar stream. Only the aggregate is returned; paths and file
- * contents never enter logs or durable metadata. */
+ * deterministic GNU tar stream. Hardlinks are dereferenced deliberately:
+ * content-preserving providers may restore them as independent files, and inode
+ * topology is not part of OpenGeni's workspace contract. Manifest paths that
+ * the provider's tar persistence deliberately excludes are pruned from both the
+ * digest and counters, so verification covers the exact persistent projection.
+ * Only the aggregate is returned; paths and file contents never enter logs or
+ * durable metadata. */
 export async function fingerprintSandboxWorkspace(
   session: unknown,
 ): Promise<WorkspaceTreeFingerprint> {
@@ -189,7 +255,7 @@ export async function fingerprintSandboxWorkspace(
     );
   }
   const result = await run.call(target, {
-    cmd: WORKSPACE_FINGERPRINT_COMMAND,
+    cmd: workspaceFingerprintCommand(workspaceFingerprintExcludes(target)),
     yieldTimeMs: 120_000,
     maxOutputTokens: 1_000,
   });
@@ -230,12 +296,22 @@ function fingerprintsEqual(a: WorkspaceTreeFingerprint, b: WorkspaceTreeFingerpr
   );
 }
 
-/** Capture is accepted only when the complete tree is byte-identical immediately
- * before and after the provider snapshot. A concurrent mutation makes the
- * candidate non-durable and it is never folded onto the lease. */
+/** Provider-native persistence returns an opaque receipt and is accepted under
+ * the provider/artifact publication fence. A real tar capture is accepted only
+ * when the complete persistent tree is byte-identical immediately before and
+ * after serialization; a concurrent mutation makes that candidate unusable. */
 export async function captureVerifiedWorkspaceArchive(
   session: unknown,
   capturedAtMs = Date.now(),
+): Promise<VerifiedWorkspaceArchive> {
+  return await withSandboxProviderCapture(session, async () => {
+    return await captureVerifiedWorkspaceArchiveExclusive(session, capturedAtMs);
+  });
+}
+
+async function captureVerifiedWorkspaceArchiveExclusive(
+  session: unknown,
+  capturedAtMs: number,
 ): Promise<VerifiedWorkspaceArchive> {
   const target = session as WorkspaceSession;
   if (typeof target.persistWorkspace !== "function") {
@@ -244,7 +320,13 @@ export async function captureVerifiedWorkspaceArchive(
       "sandbox session does not support workspace persistence",
     );
   }
-  const before = await fingerprintSandboxWorkspace(target);
+  const configuredPersistence = target.state?.workspacePersistence;
+  const configuredTarFallback = workspaceFingerprintExcludes(target).length > 0;
+  const expectsNativeSnapshot =
+    typeof configuredPersistence === "string" &&
+    configuredPersistence !== "tar" &&
+    !configuredTarFallback;
+  const before = expectsNativeSnapshot ? null : await fingerprintSandboxWorkspace(target);
   const bytes = await target.persistWorkspace();
   if (!bytes || bytes.length === 0) {
     throw new WorkspaceArchiveIntegrityError(
@@ -253,8 +335,25 @@ export async function captureVerifiedWorkspaceArchive(
       { retryable: true },
     );
   }
+  const nativeSnapshot = decodeNativeSnapshotRef(bytes);
+  if (nativeSnapshot) {
+    const descriptor = describeNativeSnapshotArchive(bytes, capturedAtMs)!;
+    return {
+      bytes,
+      base64: Buffer.from(bytes).toString("base64"),
+      descriptor,
+      kind: "provider_snapshot",
+      nativeSnapshot,
+    };
+  }
+  if (expectsNativeSnapshot) {
+    throw new WorkspaceArchiveIntegrityError(
+      "native_snapshot_fallback_unverified",
+      `sandbox configured for ${String(configuredPersistence)} returned a tar archive instead of a native snapshot receipt`,
+    );
+  }
   const after = await fingerprintSandboxWorkspace(target);
-  if (!fingerprintsEqual(before, after)) {
+  if (!before || !fingerprintsEqual(before, after)) {
     throw new WorkspaceArchiveIntegrityError(
       "workspace_changed_during_capture",
       "workspace changed while its durable archive was being captured",
@@ -262,8 +361,8 @@ export async function captureVerifiedWorkspaceArchive(
     );
   }
   const archiveSha256 = sha256(bytes);
-  const descriptor: WorkspaceArchiveDescriptor = {
-    version: WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  const descriptor: TarWorkspaceArchiveDescriptor = {
+    version: 1,
     revision: `wa1:${String(capturedAtMs).padStart(13, "0")}:${archiveSha256}`,
     archiveSha256,
     archiveBytes: bytes.length,
@@ -274,13 +373,17 @@ export async function captureVerifiedWorkspaceArchive(
     bytes,
     base64: Buffer.from(bytes).toString("base64"),
     descriptor,
+    kind: "tar",
   };
 }
 
 export async function verifyRestoredWorkspace(
   session: unknown,
   descriptor: WorkspaceArchiveDescriptor,
-): Promise<WorkspaceTreeFingerprint> {
+): Promise<WorkspaceTreeFingerprint | null> {
+  if (descriptor.version === WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION) {
+    return null;
+  }
   const actual = await fingerprintSandboxWorkspace(session);
   if (!fingerprintsEqual(actual, descriptor.workspace)) {
     throw new WorkspaceArchiveIntegrityError(

package/src/sandbox-computer.ts

@@ -940,23 +940,6 @@ function renderImageForTextTransport(output: ToolOutputImage | string): string {
   return `data:${mediaType};base64,${Buffer.from(image.data).toString("base64")}`;
 }
 
-/** Whether the bound model supports the structured tool-output transport, in
- *  lockstep with the SDK's private `supportsStructuredToolOutputTransport`
- *  (capabilities/transport): a ChatCompletions-family model — and an UNBOUND model
- *  (undefined) — does NOT, so it gets the function tools; every other model keeps
- *  the hosted `computer_use_preview` tool. The codex neutralize trick in index.ts
- *  drops `_modelInstance`, so this returns false there and the function tools win. */
-function supportsStructuredToolOutputTransport(modelInstance: unknown): boolean {
-  if (!modelInstance) return false;
-  const constructorName =
-    typeof modelInstance === "object" &&
-    modelInstance &&
-    typeof (modelInstance as { constructor?: unknown }).constructor === "function"
-      ? ((modelInstance as { constructor: { name?: string } }).constructor.name ?? "")
-      : "";
-  return !constructorName.includes("ChatCompletions");
-}
-
 const COMPUTER_READ_ONLY_MESSAGE =
   "computer-use is read-only for this session — click, double_click, move, scroll, type, keypress, and drag are disabled. Call computer_screenshot to observe the desktop.";
 
@@ -1193,39 +1176,28 @@ export function computerFunctionTools(
 /**
  * EXPLICIT tool-transport selection, decided by the caller that knows the
  * provider's true wire identity (the worker's model resolution — see agent-turn.ts),
- * NOT inferred from the bound model instance's constructor name. This is the
- * HARDENING seam: `supportsStructuredToolOutputTransport` string-sniffs the
- * constructor for "ChatCompletions", which a wrapped / proxied / minified model
- * instance would defeat — silently handing a chat-completions provider the HOSTED
- * `computer_use_preview` tool it 400s on every turn. When `toolMode` is set, tools()
- * OBEYS it and never consults the sniff:
+ * never inferred from the bound model instance's constructor name:
  *   • "hosted"         → the single hosted `computer_use_preview` tool (Responses backends).
  *   • "function-image" → the FUNCTION `computer_*` tools with screenshots delivered as a
  *                        structured `{type:'image'}` output (the codex/ChatGPT backend,
  *                        which rejects hosted tool types but SEES structured image results).
- *   • "function-text"  → the FUNCTION tools with screenshots rendered as a text
- *                        `data:…;base64` URL (chat-completions providers, which can't read
- *                        structured image tool results).
+ *   • "disabled"       → no computer tools. Providers without a proven visual image
+ *                        transport fail closed instead of receiving base64 as text.
+ *   • "function-text"  → deprecated fail-closed alias retained for source compatibility.
+ *   • omitted           → fail closed exactly like "disabled"; public runtime callers must
+ *                        prove the transport explicitly before computer tools are exposed.
  */
-export type ComputerToolMode = "hosted" | "function-image" | "function-text";
+export type ComputerToolMode = "hosted" | "function-image" | "disabled" | "function-text";
 
 export type ComputerUseArgs = {
   dimensions?: [number, number];
   readOnly?: boolean;
   display?: string;
   needsApproval?: boolean | ((ctx: unknown, action: unknown) => boolean | Promise<boolean>);
-  // Deliver screenshots from the FUNCTION tools as a REAL image the model can see
-  // (a structured `{type:'image'}` tool output → agents-core normalizes it to an
-  // `input_image` content item inside the function_call_output) instead of the text
-  // data-URL string. Only the codex/ChatGPT backend can read structured image tool
-  // results; chat-completions providers cannot, so this stays OFF (text rendering)
-  // by default and is turned on only on the codex path (see index.ts). Ignored when
-  // `toolMode` is set (the mode carries its own image-delivery choice).
+  /** @deprecated Use `toolMode: "function-image"`. Omitted transport now fails closed. */
   imageFunctionResults?: boolean;
-  // EXPLICIT transport selection (see {@link ComputerToolMode}). When present, tools()
-  // obeys it directly — the constructor-name sniff is NOT consulted. When ABSENT, the
-  // legacy sniff behaviour is preserved byte-for-byte (back-compat for any embedder
-  // that constructs the capability without threading a mode).
+  // EXPLICIT transport selection (see {@link ComputerToolMode}). When absent, tools()
+  // returns no computer tools; constructor-name sniffing is never a transport proof.
   toolMode?: ComputerToolMode;
   /** Called after the display is ready on the first actual computer action. */
   onReady?: (session: SandboxSessionLike) => Promise<void>;
@@ -1241,17 +1213,9 @@ export function computerUse(args: ComputerUseArgs = {}): ComputerUseCapability {
  * the LIVE externally-owned session, so the agent's actions and the viewers'
  * pixels are one display.
  *
- * `tools()` is TRANSPORT-AWARE, mirroring the SDK's `filesystem()` capability
- * (which branches its `view_image` / `apply_patch` on
- * `supportsStructuredToolOutputTransport(this._modelInstance)`):
- *   • structured transport (the Responses/OpenAI backend) → the single HOSTED
- *     `computer_use_preview` tool over a Computer bound to the session (unchanged).
- *   • text transport (codex / ChatGPT backend — or an unbound model) → a set of
- *     FUNCTION tools ({@link computerFunctionTools}) that route to the SAME Computer,
- *     because the codex backend rejects the hosted computer tool type.
- * The bound model instance is captured by the SDK's `bind().bindRunAs().bindModel()`
- * chain (base `Capability._modelInstance`); the codex path in index.ts neutralizes
- * `bindModel` so `_modelInstance` stays undefined here → the function tools win.
+ * `tools()` is transport-aware only through `ComputerUseArgs.toolMode`. The bound
+ * model instance is intentionally ignored: a constructor name cannot prove whether
+ * screenshots travel as hosted computer output or structured function images.
  */
 export class ComputerUseCapability extends Capability {
   readonly type = "computer-use";
@@ -1288,12 +1252,8 @@ export class ComputerUseCapability extends Capability {
             await this.args.onReady?.(preparedSession);
           },
         });
-    // HARDENING: when the caller declares an EXPLICIT toolMode, obey it and NEVER
-    // consult `supportsStructuredToolOutputTransport` — tool selection must not
-    // depend on the model instance's constructor name (a wrapped/proxied/minified
-    // instance would defeat the "ChatCompletions" string-sniff and silently hand a
-    // chat-completions provider the hosted tool it 400s on). The mode is decided by
-    // the worker, where provider identity is authoritative (see agent-turn.ts).
+    // Tool selection must not depend on the model instance's constructor name. The
+    // worker supplies a proven explicit mode; public callers that omit it fail closed.
     switch (this.args.toolMode) {
       case "hosted":
         return [this.hostedComputerTool(computer)];
@@ -1304,31 +1264,21 @@ export class ComputerUseCapability extends Capability {
           this.args.needsApproval,
           true,
         );
+      case "disabled":
       case "function-text":
-        return computerFunctionTools(
-          computer,
-          this.args.readOnly ?? false,
-          this.args.needsApproval,
-          false,
-        );
       case undefined:
-        break; // fall through to the legacy sniff (back-compat), preserved byte-for-byte
-    }
-    // Legacy (no toolMode): structured transport keeps the HOSTED computer tool
-    // (unchanged); the codex / text backend gets the FUNCTION tools it can call.
-    if (supportsStructuredToolOutputTransport(this._modelInstance)) {
-      return [this.hostedComputerTool(computer)];
+        // A text data URL is not a visual observation for the provider and can
+        // consume hundreds of thousands of apparent text tokens. Disable the
+        // entire coordinate-dependent capability: action tools without a usable
+        // screenshot would be blind and unsafe.
+        return [];
     }
-    return computerFunctionTools(
-      computer,
-      this.args.readOnly ?? false,
-      this.args.needsApproval,
-      this.args.imageFunctionResults ?? false,
-    );
+    // Runtime callers may bypass TypeScript or pass a value from a newer client.
+    // Unknown transport modes must remain fail-closed.
+    return [];
   }
 
-  /** The single HOSTED `computer_use_preview` tool bound to `computer` — identical
-   *  construction for the explicit "hosted" mode and the legacy structured-sniff path. */
+  /** The single HOSTED `computer_use_preview` tool bound to `computer`. */
   private hostedComputerTool(computer: Computer): Tool<unknown> {
     return computerTool({
       computer,