@opengeni/runtime 4.6.0 → 4.7.0-canary.37090756480001

package/src/sandbox/providers/modal-command-observation-errors.ts

@@ -0,0 +1,65 @@
+/** Only used inside a read-only provider RPC boundary. This is deliberately
+ * not a Start classifier: remote DNS prose never proves non-dispatch. */
+export function isModalCommandObservationTransportError(error: unknown): boolean {
+  const seen = new Map<object, boolean>();
+  let nodes = 0;
+  const own = (value: object, key: string): unknown => {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor && !("value" in descriptor)) throw new Error("Unreadable provider error graph");
+    return descriptor && "value" in descriptor ? descriptor.value : undefined;
+  };
+  const visit = (value: unknown, depth: number): boolean => {
+    if (!value || typeof value !== "object" || depth > 6 || ++nodes > 32) return false;
+    if (seen.has(value)) return seen.get(value)!;
+    // A cycle sees false until this bounded branch has been fully evaluated.
+    seen.set(value, false);
+    try {
+      const code = own(value, "code");
+      const nested: unknown[] = [own(value, "cause"), own(value, "error")].filter(
+        (item) => item !== undefined,
+      );
+      const errors = own(value, "errors");
+      if (errors !== undefined) {
+        if (!Array.isArray(errors) || !errors.length || errors.length > 16) return false;
+        for (let index = 0; index < errors.length; index++) nested.push(own(errors, String(index)));
+      }
+      if (code !== undefined) {
+        const normalized = typeof code === "string" ? code.trim().toUpperCase() : code;
+        if (
+          ![
+            1,
+            2,
+            4,
+            13,
+            14,
+            "1",
+            "2",
+            "4",
+            "13",
+            "14",
+            "CANCELLED",
+            "UNKNOWN",
+            "DEADLINE_EXCEEDED",
+            "INTERNAL",
+            "UNAVAILABLE",
+            "ECONNRESET",
+            "ECONNREFUSED",
+            "ETIMEDOUT",
+            "EAI_AGAIN",
+            "ENOTFOUND",
+          ].includes(normalized as never)
+        )
+          return false;
+        const result = nested.length === 0 || nested.every((item) => visit(item, depth + 1));
+        seen.set(value, result);
+        return result;
+      }
+      const result = nested.length > 0 && nested.every((item) => visit(item, depth + 1));
+      seen.set(value, result);
+      return result;
+    } catch {
+      return false;
+    }
+  };
+  return visit(error, 0);
+}

package/src/sandbox/providers/modal-command-raw-page.ts

@@ -0,0 +1,147 @@
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+import { ModalRouterProviderCommand } from "@opengeni/contracts";
+import type { ProviderCommandOutput } from "../provider-command-session";
+import { decodePage } from "./modal-legacy-command-control";
+import { MODAL_ROUTER_READ_PAGE_BYTES } from "./modal-command-router-wire";
+
+const RawStream = z
+  .object({
+    bytes: z
+      .instanceof(Uint8Array)
+      .transform((bytes): Uint8Array<ArrayBufferLike> => bytes)
+      .refine(
+        (bytes) => bytes.byteLength <= MODAL_ROUTER_READ_PAGE_BYTES,
+        "Raw page exceeded its bound",
+      ),
+    eof: z.boolean(),
+  })
+  .strict();
+const RawExit = z.discriminatedUnion("source", [
+  z.object({ source: z.literal("router_poll"), code: z.number().int().nullable() }).strict(),
+  z.object({ source: z.literal("retained_terminal"), code: z.number().int() }).strict(),
+]);
+const RawPage = z
+  .object({
+    protocol: z.literal("modal-router-raw-page-v1"),
+    expected: ModalRouterProviderCommand,
+    command: ModalRouterProviderCommand,
+    streams: z.object({ stdout: RawStream, stderr: RawStream }).strict(),
+    exit: RawExit,
+  })
+  .strict();
+
+/** Bounded native RPC bytes and their exact cursor projection. The source tag
+ * distinguishes a fresh poll from previously captured terminal evidence; it
+ * does not authenticate an object supplied by a caller. No Start, custody,
+ * database settlement or parent completion authority is conveyed. */
+export type ModalRawOutputPage = z.infer<typeof RawPage>;
+export type ModalRawOutputStreams = ModalRawOutputPage["streams"];
+export type ModalRawOutputExit = ModalRawOutputPage["exit"];
+type NativeOutput = ProviderCommandOutput & {
+  expected: ModalRouterProviderCommand;
+  command: ModalRouterProviderCommand;
+};
+
+function project(
+  expected: ModalRouterProviderCommand,
+  streams: ModalRawOutputStreams,
+  exit: ModalRawOutputExit,
+): NativeOutput {
+  const command = structuredClone(expected);
+  const chunks: ProviderCommandOutput["chunks"] = [];
+  for (const stream of ["stdout", "stderr"] as const) {
+    const old = expected.streams[stream];
+    const page = streams[stream];
+    const decoded = decodePage(old.utf8Remainder, [page.bytes], page.eof);
+    const byteOffset = old.byteOffset + page.bytes.byteLength;
+    if (!Number.isSafeInteger(byteOffset)) throw new Error("Modal output offset exhausted");
+    command.streams[stream] = {
+      byteOffset,
+      utf8Remainder: decoded.remainder,
+      eof: page.eof,
+      exitCode: page.eof ? exit.code : null,
+    };
+    if (decoded.text)
+      chunks.push({
+        stream,
+        chunkId: `modal-router:${expected.execId}:${stream}:${old.byteOffset}:${byteOffset}:${page.eof ? 1 : 0}`,
+        text: decoded.text,
+      });
+  }
+  return {
+    command,
+    expected: structuredClone(expected),
+    chunks,
+    exitCode: command.streams.stdout.eof && command.streams.stderr.eof ? exit.code : null,
+    providerExited: exit.code !== null,
+    streamFidelity: expected.pty ? "merged" : "separate",
+  };
+}
+
+/** Provider-private construction from joined read/poll replies. Keep the SDK
+ * projection unchanged; this pure helper itself is not provider proof. */
+export function collectModalRawOutputPage(
+  command: ModalRouterProviderCommand,
+  streams: ModalRawOutputStreams,
+  exit: ModalRawOutputExit,
+): { raw: ModalRawOutputPage; output: NativeOutput } {
+  const expected = structuredClone(command);
+  const captured = {
+    stdout: { bytes: Buffer.from(streams.stdout.bytes), eof: streams.stdout.eof },
+    stderr: { bytes: Buffer.from(streams.stderr.bytes), eof: streams.stderr.eof },
+  };
+  const output = project(expected, captured, exit);
+  return {
+    raw: {
+      protocol: "modal-router-raw-page-v1",
+      expected,
+      command: structuredClone(output.command),
+      streams: captured,
+      exit: { ...exit },
+    },
+    output,
+  };
+}
+
+/** Recompute decoded output from exact bytes, never caller-decoded text. The
+ * current cursor must come from the caller's authoritative store. Equality
+ * checks are not a database CAS; coherent bytes still need trusted acquisition
+ * and atomic capture by the owner. */
+export function reduceModalRawOutputPage(
+  input: ModalRawOutputPage,
+  current: ModalRouterProviderCommand,
+): NativeOutput {
+  const page = RawPage.parse(input);
+  const expected = ModalRouterProviderCommand.parse(current);
+  if (!isDeepStrictEqual(page.expected, expected))
+    throw new Error("Raw page does not match the current native cursor");
+  for (const stream of ["stdout", "stderr"] as const) {
+    const old = expected.streams[stream];
+    const raw = page.streams[stream];
+    const remainder = Buffer.from(old.utf8Remainder, "base64");
+    if (
+      remainder.toString("base64") !== old.utf8Remainder ||
+      remainder.length > 3 ||
+      remainder.length > old.byteOffset ||
+      (old.eof && remainder.length !== 0)
+    )
+      throw new Error("Raw page has an invalid saved UTF-8 remainder");
+    if (old.eof && (!raw.eof || raw.bytes.byteLength !== 0))
+      throw new Error("Raw page reopened or advanced a completed stream");
+    if (old.exitCode !== null && page.exit.code !== old.exitCode)
+      throw new Error("Raw page rewrote captured terminal evidence");
+  }
+  if (
+    page.exit.source === "retained_terminal" &&
+    (!expected.streams.stdout.eof ||
+      !expected.streams.stderr.eof ||
+      expected.streams.stdout.exitCode !== page.exit.code ||
+      expected.streams.stderr.exitCode !== page.exit.code)
+  )
+    throw new Error("Raw page has no matching retained terminal evidence");
+  const output = project(expected, page.streams, page.exit);
+  if (!isDeepStrictEqual(page.command, output.command))
+    throw new Error("Raw page cursor delta or remainder does not match its bytes");
+  return output;
+}

package/src/sandbox/providers/modal-command-router-wire.ts

@@ -127,6 +127,63 @@ export type ModalRouterStart = ModalRouterIdentity & {
   };
 };
 
+declare const preparedStartBrand: unique symbol;
+/** An in-memory, single-use request on its issuing transport, NOT command
+ * admission or durable dispatch authority. Copies/serialized identities cannot
+ * be dispatched. The caller still owns authorization before physical Start. */
+export type ModalRouterPreparedStart = Readonly<ModalRouterIdentity> & {
+  readonly [preparedStartBrand]: true;
+};
+
+type PreparedStartRequest = ModalRouterStart & { stdoutConfig: number; stderrConfig: number };
+
+function prepareStartRequest(request: ModalRouterStart): PreparedStartRequest {
+  // Validate before protobuf's fromObject coercions and snapshot only the
+  // supported request fields. Caller mutations must not substitute parameters
+  // between preparation and the eventual dispatch boundary.
+  const { taskId, execId, commandArgs, workdir, env, ptyInfo } = request;
+  if (
+    !taskId ||
+    !execId ||
+    !Array.isArray(commandArgs) ||
+    !commandArgs.length ||
+    typeof workdir !== "string" ||
+    !env ||
+    typeof env !== "object" ||
+    Array.isArray(env)
+  )
+    throw new Error("Invalid Modal command Start request");
+  const snapshot: PreparedStartRequest = {
+    taskId,
+    execId,
+    commandArgs: [...commandArgs],
+    workdir,
+    env: { ...env },
+    ...(ptyInfo
+      ? {
+          ptyInfo: {
+            enabled: ptyInfo.enabled,
+            winszRows: ptyInfo.winszRows,
+            winszCols: ptyInfo.winszCols,
+            envTerm: ptyInfo.envTerm,
+            ptyType: ptyInfo.ptyType,
+            noTerminateOnIdleStdin: ptyInfo.noTerminateOnIdleStdin,
+          },
+        }
+      : {}),
+    stdoutConfig: 1,
+    stderrConfig: 1,
+  };
+  if (modalRouterWire.lookupType("Start").verify(snapshot))
+    throw new Error("Invalid Modal command Start request");
+  if (encode("Start", snapshot).length > maxWireBytes)
+    throw new Error("Modal command Start request exceeds the wire limit");
+  Object.freeze(snapshot.commandArgs);
+  Object.freeze(snapshot.env);
+  if (snapshot.ptyInfo) Object.freeze(snapshot.ptyInfo);
+  return Object.freeze(snapshot);
+}
+
 function encode(type: string, value: object): Buffer {
   const codec = modalRouterWire.lookupType(type);
   return Buffer.from(codec.encode(codec.fromObject(value)).finish());
@@ -139,6 +196,10 @@ function encode(type: string, value: object): Buffer {
 export class ModalCommandRouterWire {
   private readonly client: Client;
   private readonly metadata: Metadata;
+  readonly #preparedStarts = new WeakMap<
+    ModalRouterPreparedStart,
+    { request: PreparedStartRequest; spent: boolean }
+  >();
   private closed = false;
   constructor(access: ModalRouterAccess, trustedRoots?: Buffer) {
     const url = new URL(access.url);
@@ -199,12 +260,26 @@ export class ModalCommandRouterWire {
     });
   }
 
-  async start(request: ModalRouterStart, signal?: AbortSignal): Promise<void> {
+  /** Read-only transport preparation. It sends neither Start nor stdin and
+   * does not invoke a caller's dispatch/admission callback. Prevalidation is not
+   * wire proof: gRPC still serializes at RPC invocation after dispatch begins. */
+  async prepareStart(
+    request: ModalRouterStart,
+    signal?: AbortSignal,
+  ): Promise<ModalRouterPreparedStart> {
     try {
+      signal?.throwIfAborted();
       if (this.closed) throw new Error("Modal command router is closed");
+      const snapshot = prepareStartRequest(request);
       await ModalCommandStartPreDispatchUnavailableError.ensureReady(this.client, signal);
       signal?.throwIfAborted();
       if (this.closed) throw new Error("Modal command router is closed");
+      const prepared = Object.freeze({
+        taskId: snapshot.taskId,
+        execId: snapshot.execId,
+      }) as ModalRouterPreparedStart;
+      this.#preparedStarts.set(prepared, { request: snapshot, spent: false });
+      return prepared;
     } catch (error) {
       if (this.closed)
         throw new ModalCommandStartNotDispatchedError(
@@ -213,18 +288,30 @@ export class ModalCommandRouterWire {
       if (error instanceof ModalCommandStartPreDispatchUnavailableError) throw error;
       throw new ModalCommandStartNotDispatchedError(error);
     }
+  }
+
+  /** No readiness, route lookup or retry here. Consume the authentic local
+   * handle synchronously before RPC, including when cancellation/closure wins.
+   * Once spent it never resets, even if no acknowledgement was received. */
+  async dispatchPreparedStart(
+    prepared: ModalRouterPreparedStart,
+    signal?: AbortSignal,
+  ): Promise<void> {
+    const entry = this.#preparedStarts.get(prepared);
+    if (!entry || entry.spent)
+      // An invalid/spent reference is not proof that an earlier Start was never
+      // dispatched, and must not acquire a retry/settlement error brand.
+      throw new Error("Invalid or consumed Modal prepared Start handle");
+    entry.spent = true;
+    try {
+      signal?.throwIfAborted();
+      if (this.closed) throw new Error("Modal command router is closed");
+    } catch (error) {
+      throw new ModalCommandStartNotDispatchedError(error);
+    }
+    const request = entry.request;
     try {
-      await this.unary(
-        "TaskExecStart",
-        "Start",
-        "Empty",
-        {
-          ...request,
-          stdoutConfig: 1,
-          stderrConfig: 1,
-        },
-        signal,
-      );
+      await this.unary("TaskExecStart", "Start", "Empty", request, signal);
     } catch (error) {
       const code = (error as Partial<ServiceError> | null)?.code;
       if (
@@ -242,6 +329,11 @@ export class ModalCommandRouterWire {
     }
   }
 
+  async start(request: ModalRouterStart, signal?: AbortSignal): Promise<void> {
+    const prepared = await this.prepareStart(request, signal);
+    await this.dispatchPreparedStart(prepared, signal);
+  }
+
   async write(
     identity: ModalRouterIdentity,
     offset: number,

package/src/sandbox/providers/modal-command-session.ts

@@ -3,6 +3,7 @@ import { isDeepStrictEqual } from "node:util";
 import { truncateOutput } from "@openai/agents-core/sandbox/internal";
 import type { ChannelASession } from "../channel-a";
 import { ModalProcessObservationUnavailableError } from "../errors";
+import { classifyProviderSandboxFailure } from "../provider-errors";
 import { markTypedExecHandleLoss, parseExecResponseBanner } from "../exec-banner";
 import {
   MAX_PROVIDER_COMMAND_HANDLE,
@@ -11,6 +12,7 @@ import {
   type ProviderCommandSession,
   admittedProviderCommandHandle,
   ProviderCommandStartOutcomeUnknownError,
+  ProviderCommandInputOutcomeUnknownError,
 } from "../provider-command-session";
 import type { ModalCommandControl, ModalProviderCommand } from "./modal-command-control";
 import { verifyModalMaterializedPath } from "./modal-materialization-verification";
@@ -333,12 +335,13 @@ export function installModalCommandSession(
     const receipt = receipts.get(result);
     if (!receipt || receipt.page.command.kind !== "modal-router-v1") return false;
     if (
-      receipt.page.command.supervision &&
       !receipt.page.expected &&
       receipt.page.exitCode === null &&
       receipt.page.chunks.length === 0
     ) {
-      // Idle-launch receipt carries identity only; there are no bytes to ACK.
+      // Both a supervised idle launch and an unavailable first observation
+      // carry identity only. Retention already owns this command; there are
+      // no observed bytes or terminal evidence to ACK.
       receipts.delete(result);
       return true;
     }
@@ -406,8 +409,27 @@ export function installModalCommandSession(
       if (!retained || !sameExecution(entry.command, retained))
         throw new Error("Original Modal command identity is unavailable");
       const index = await entry.persistence.reserveInput(Buffer.byteLength(args.chars));
-      await control.write(retained, args.chars, index);
+      try {
+        await control.write(retained, args.chars, index);
+      } catch (error) {
+        // Native gRPC transport failure does not establish whether this reserved
+        // range reached stdin. Never resend it or recommend another input write.
+        if (
+          retained.kind === "modal-router-v1" &&
+          // Contain supported transport graphs, including mixed failures. This
+          // grants no read/write retry permission; the locator and byte range
+          // come only from the retained command and its one input reservation.
+          classifyProviderSandboxFailure("modal", error).kind === "transient_transport"
+        )
+          throw new ProviderCommandInputOutcomeUnknownError(
+            retained,
+            index,
+            Buffer.byteLength(args.chars),
+            error,
+          );
+        throw error;
+      }
     }
-    return read(args.sessionId, entry, args.yieldTimeMs ?? 250, args.maxOutputTokens);
+    return read(args.sessionId, entry, args.yieldTimeMs ?? 250, args.maxOutputTokens, args.signal);
   };
 }

package/src/sandbox/providers/modal-legacy-command-control.ts

@@ -6,7 +6,7 @@ import { ModalCommandStartPreDispatchUnavailableError } from "./modal-command-ro
 import { ProviderCommandStartRejectedError } from "../provider-command-session";
 import { ModalLegacyProviderCommand } from "@opengeni/contracts";
 import type { ChannelAExecArgs } from "../channel-a";
-import { shellQuote } from "@openai/agents-core/sandbox/internal";
+import { modalCommandArgv } from "./modal-command-argv";
 
 type ControlPlane = Pick<
   ModalClient["cpClient"],
@@ -162,14 +162,7 @@ export class ModalCommandControl {
     if (!task.taskId || task.taskResult) throw new Error("Modal command task is unavailable");
     if (sandboxId !== this.sandboxId)
       throw new Error("Modal sandbox changed during command preparation");
-    const login = args.shell ? (args.login ?? true) : false;
-    let command = [args.shell ?? "/bin/sh", login ? "-lc" : "-c", args.cmd];
-    if (args.runAs) {
-      const user = shellQuote(args.runAs);
-      const invocation = command.map(shellQuote).join(" ");
-      const script = `if [ "$(id -u)" = ${user} ] || [ "$(id -un 2>/dev/null)" = ${user} ]; then exec ${invocation}; elif [ "$(id -u)" = 0 ]; then exec su -s /bin/sh ${user} -c ${shellQuote(`exec ${invocation}`)}; else exec sudo -n -u ${user} -- ${invocation}; fi`;
-      command = ["/bin/sh", "-c", script];
-    }
+    let command = modalCommandArgv(args);
     const environment =
       typeof this.environment === "function" ? this.environment() : this.environment;
     if (Object.keys(environment).length) {

package/src/sandbox/providers/modal-materialization-verification.ts

@@ -1,9 +1,16 @@
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
 import {
   SandboxMaterializationVerificationError,
   retainMaterializationVerificationDiagnostic,
   type MaterializationVerificationDiagnostic,
 } from "../materialization-verification-error";
 import type { ModalCommandControl, ModalProviderCommand } from "./modal-command-control";
+import {
+  ProviderCommandObservationUnavailableError,
+  ProviderCommandStartOutcomeUnknownError,
+  type ProviderCommandOutput,
+} from "../provider-command-session";
 
 const MARKER = "__OPENGENI_MATERIALIZED_PATH_VISIBLE__";
 const OUTPUT_LIMIT = 16 * 1024;
@@ -25,6 +32,7 @@ export async function verifyModalMaterializedPath(
   const cancellation = new AbortController();
   const deadlineReason = new Error("Materialization visibility observation deadline exceeded");
   let providerCommand: ModalProviderCommand | undefined;
+  let startUnknown: ProviderCommandStartOutcomeUnknownError | undefined;
   let stdout = "";
   let stderr = "";
   const diagnostic = (
@@ -54,13 +62,57 @@ export async function verifyModalMaterializedPath(
   timer.unref();
   pending.add(cancellation);
   try {
-    providerCommand = await control.start(
-      { cmd: command, workdir, shell: "sh", login: false, tty: false },
-      cancellation.signal,
-    );
+    try {
+      providerCommand = await control.start(
+        { cmd: command, workdir, shell: "sh", login: false, tty: false },
+        cancellation.signal,
+      );
+    } catch (error) {
+      // A possibly dispatched fixed visibility probe has one original locator.
+      // Observe that invocation; never replay it or the surrounding mutation.
+      if (!(error instanceof ProviderCommandStartOutcomeUnknownError)) throw error;
+      providerCommand = structuredClone(error.command);
+      startUnknown = error;
+    }
     for (;;) {
       cancellation.signal.throwIfAborted();
-      const page = await control.readProbe(providerCommand, 1_000, cancellation);
+      let page: ProviderCommandOutput;
+      try {
+        page = await control.readProbe(providerCommand, 1_000, cancellation);
+      } catch (error) {
+        cancellation.signal.throwIfAborted();
+        if (
+          !(error instanceof ProviderCommandObservationUnavailableError) ||
+          !error.readRetryAllowed
+        ) {
+          if (!startUnknown) throw error;
+          // A missing/denied read cannot disprove the original Start. Preserve
+          // its exact invocation without granting any further read retry.
+          throw new ProviderCommandObservationUnavailableError(
+            structuredClone(providerCommand),
+            new AggregateError(
+              [startUnknown, error],
+              "Original visibility Start and observation remain uncertain",
+            ),
+            false,
+          );
+        }
+        // Unavailable reads do not advance any cursor. A contradictory locator
+        // is an invariant failure, never authority to inspect another process.
+        if (!isDeepStrictEqual(error.command, providerCommand))
+          throw new SandboxMaterializationVerificationError(diagnostic("invalid_response"), {
+            cause: error,
+          });
+        // Read retries remain inside this probe's original thirty-second
+        // deadline, including outages longer than a single bounded read.
+        try {
+          await delay(100, undefined, { signal: cancellation.signal });
+        } catch (interrupted) {
+          cancellation.signal.throwIfAborted();
+          throw interrupted;
+        }
+        continue;
+      }
       // Cancellation ends observation, not the process. Never accept a late
       // success after the attempt requested cancellation.
       cancellation.signal.throwIfAborted();
@@ -104,7 +156,19 @@ export async function verifyModalMaterializedPath(
           ...diagnostic("command_pending"),
           causeMessage: "Observation deadline exceeded; provider process completion is unconfirmed",
         },
-        { cause: error },
+        {
+          cause: providerCommand
+            ? new ProviderCommandObservationUnavailableError(
+                providerCommand,
+                startUnknown
+                  ? new AggregateError(
+                      [startUnknown, error],
+                      "Original visibility Start and observation deadline remain uncertain",
+                    )
+                  : error,
+              )
+            : error,
+        },
       );
     }
     if (!(error instanceof SandboxMaterializationVerificationError)) {