@opengeni/runtime 0.7.1 → 0.13.0

package/src/sandbox/exec-banner.ts

@@ -0,0 +1,67 @@
+// The SDK's execCommand/writeStdin fallback returns a formatted response with
+// provider metadata followed by an `Output:` delimiter and command-controlled
+// output. Terminal status is authoritative only in the metadata header; the
+// output body is untrusted and may contain exact copies of SDK banner lines.
+
+const EXEC_BANNER_HEADER_MAX_CHARS = 16 * 1024;
+const OUTPUT_DELIMITER = /\r?\nOutput:\r?\n/u;
+const SDK_METADATA_LINE =
+  /^(?:Chunk ID:|Wall time:|Original token count:|Output:|Process (?:running with session ID|exited with code))/mu;
+const RUNNING_LINE = /^Process running with session ID (\d+)$/u;
+const EXITED_LINE = /^Process exited with code (-?\d+)$/u;
+const PROCESS_STATUS_PREFIX = /^Process (?:running with session ID|exited with code)/u;
+
+export type ExecResponseBanner =
+  | { kind: "absent" }
+  | { kind: "invalid" }
+  | { kind: "running"; sessionId: number }
+  | { kind: "exited"; exitCode: number };
+
+/** Parse exactly one terminal status from the SDK metadata header. Responses
+ * that resemble SDK output but lack a complete delimiter/header are invalid,
+ * while raw provider output without SDK metadata remains `absent` so callers
+ * may use their provider-specific body markers. */
+export function parseExecResponseBanner(raw: string): ExecResponseBanner {
+  const delimiter = OUTPUT_DELIMITER.exec(raw);
+  if (!delimiter) {
+    return SDK_METADATA_LINE.test(raw) ? { kind: "invalid" } : { kind: "absent" };
+  }
+  if (delimiter.index > EXEC_BANNER_HEADER_MAX_CHARS) return { kind: "invalid" };
+
+  const header = raw.slice(0, delimiter.index);
+  const status: Array<{ kind: "running"; value: string } | { kind: "exited"; value: string }> = [];
+  for (const line of header.split(/\r?\n/u)) {
+    const running = RUNNING_LINE.exec(line);
+    if (running) {
+      status.push({ kind: "running", value: running[1]! });
+      continue;
+    }
+    const exited = EXITED_LINE.exec(line);
+    if (exited) {
+      status.push({ kind: "exited", value: exited[1]! });
+      continue;
+    }
+    // A status-looking metadata line that is malformed is ambiguous and must
+    // not be normalized into another process identity or terminal result.
+    if (PROCESS_STATUS_PREFIX.test(line)) return { kind: "invalid" };
+  }
+  if (status.length !== 1) return { kind: "invalid" };
+
+  const terminal = status[0]!;
+  const value = Number(terminal.value);
+  if (!Number.isSafeInteger(value)) return { kind: "invalid" };
+  if (terminal.kind === "running") {
+    return value >= 0 ? { kind: "running", sessionId: value } : { kind: "invalid" };
+  }
+  return { kind: "exited", exitCode: value };
+}
+
+export function parseExecBannerSessionId(raw: string): number | null {
+  const banner = parseExecResponseBanner(raw);
+  return banner.kind === "running" ? banner.sessionId : null;
+}
+
+export function parseExecBannerExitCode(raw: string): number | null {
+  const banner = parseExecResponseBanner(raw);
+  return banner.kind === "exited" ? banner.exitCode : null;
+}

package/src/sandbox/index.ts

@@ -1,7 +1,7 @@
 // @opengeni/runtime/sandbox — the agent-loop-free sandbox leaf.
 //
 // This module is the load-bearing pre-req for the API-direct control plane
-// (docs/design/sandbox-surfacing). It exposes the sandbox client factory plus
+// (docs/connected-machines.md). It exposes the sandbox client factory plus
 // the resume / recovery-envelope helpers that the API needs to touch a box by
 // id (resume-by-id, file/exec/port ops) WITHOUT importing the @openai/agents
 // agent-loop graph.
@@ -72,7 +72,9 @@ export {
   type LiveModalSandboxLeaseAttribution,
   type ModalModuleLoader,
   type ModalOrphanSweepResult,
+  type ModalOrphanSweepTermination,
   type ModalSandboxAttribution,
+  type RevalidateModalOrphanTermination,
 } from "./providers/modal";
 export {
   selectBackend,
@@ -106,6 +108,11 @@ export {
   ensureDisplayStack,
   tearDownDisplayStack,
   type DesktopGeometry,
+  type DisplayStackCallerKind,
+  type DisplayStackClassification,
+  type DisplayStackTelemetryContext,
+  type DisplayStackTelemetryEvent,
+  type DisplayStackTelemetryStatus,
   type EnsureDisplayStackOptions,
   type EnsureDisplayStackResult,
 } from "./display-stack";
@@ -125,6 +132,39 @@ export {
   type EnsureTerminalServerResult,
 } from "./terminal-server";
 
+// Host-owned rotating run credentials. Material lives outside the persisted
+// workspace/manifest and is activated atomically per session generation.
+export {
+  RunCredentialValidationError,
+  normalizeRunCredentialsResolution,
+  runCredentialRoot,
+  runCredentialPointerFile,
+  materializeRunCredentials,
+  clearRunCredentials,
+  clearRunCredentialsForAttempt,
+  withRunCredentialEnvironment,
+  withRunCredentialsSession,
+  withRunCredentialsClient,
+  type RunCredentialExpectedScope,
+  type NormalizedRunCredentialMaterial,
+  type RunCredentialCommandSession,
+  type RunCredentialCommandRunner,
+  type RunCredentialSessionReady,
+  type MaterializeRunCredentialsOptions,
+} from "./run-credentials";
+
+// Session-specific Toolspace token routing. The manifest retains one stable
+// legacy pointer for warm-box env parity; every session command selects its own
+// hashed token file off-manifest.
+export {
+  ToolspaceTokenPathError,
+  toolspaceTokenFileForSession,
+  toolspaceTokenFileFromEnvironment,
+  withToolspaceTokenEnvironment,
+  withToolspaceTokenSession,
+  withToolspaceTokenClient,
+} from "./toolspace-token";
+
 // The Channel-B pixel DATA PLANE (P4.2). Resolves the provider's scoped tunnel
 // for port 6080 (client → provider-tunnel direct), assembles the WS URL, and
 // mints the scoped stream token. Called API-direct on the resumed handle.
@@ -164,12 +204,13 @@ export {
 export {
   SandboxChannelAService,
   ChannelAValidationError,
+  ChannelAUnavailableError,
   ChannelAConflictError,
   ChannelANotFoundError,
   ChannelAUnsupportedError,
   stripExecBanner,
   parseExecBannerSessionId,
-  isWorkspaceEscapeError,
+  parseExecBannerExitCode,
   isExecSessionLostBanner,
   assertSafeRelPath,
   parsePorcelainV2,

package/src/sandbox/providers/modal.ts

@@ -38,6 +38,10 @@ export type ModalOrphanSweepResult = {
   skipped: number;
 };
 
+export type RevalidateModalOrphanTermination = (
+  candidate: ModalOrphanSweepTermination,
+) => Promise<boolean>;
+
 export function modalSandboxAttributionEnvironment(
   input: ModalSandboxAttribution,
 ): Record<string, string> {
@@ -337,6 +341,9 @@ export async function sweepModalOrphanSandboxes(
     maxTerminations?: number;
     unattributedGraceMs?: number;
     client?: ModalClientLike;
+    /** Re-read durable ownership immediately before provider termination. A
+     * false result or callback failure skips the destructive action. */
+    revalidateTermination?: RevalidateModalOrphanTermination;
   } = {},
 ): Promise<ModalOrphanSweepResult> {
   const nowMs = options.now?.getTime() ?? Date.now();
@@ -437,10 +444,30 @@ export async function sweepModalOrphanSandboxes(
           skipped += 1;
           continue;
         }
+        const candidate = { sandboxId: info.id, reason, tags };
+        let sandbox: Awaited<ReturnType<typeof modal.sandboxes.fromId>>;
+        try {
+          sandbox = await modal.sandboxes.fromId(info.id);
+        } catch {
+          skipped += 1;
+          continue;
+        }
+        if (options.revalidateTermination) {
+          try {
+            if (!(await options.revalidateTermination(candidate))) {
+              skipped += 1;
+              continue;
+            }
+          } catch {
+            // Destructive provider cleanup fails closed when the fresh durable
+            // ownership read is unavailable or otherwise inconclusive.
+            skipped += 1;
+            continue;
+          }
+        }
         try {
-          const sandbox = await modal.sandboxes.fromId(info.id);
           await sandbox.terminate();
-          terminated.push({ sandboxId: info.id, reason, tags });
+          terminated.push(candidate);
         } catch {
           skipped += 1;
         }

package/src/sandbox/routing/routing-session.ts

@@ -1,6 +1,6 @@
 // `RoutingSandboxSession` — the per-session hot-swap routing proxy (M7).
 //
-// THE load-bearing SDK finding (dossier §10.3 / §20-M7): when a box is injected
+// THE load-bearing SDK finding: when a box is injected
 // NON-OWNED into a turn (`ownedSandbox.session`), the agent SDK's sandbox
 // capabilities bind to that ONE session OBJECT ONCE and call ITS methods
 // (`exec`/`execCommand`/`readFile`/`listDir`/`resolveExposedPort`/…) per tool
@@ -10,7 +10,7 @@
 // per-session active pointer `(active_sandbox_id, active_epoch)` and DISPATCHES
 // to the CURRENTLY-active backend session (Modal or selfhosted).
 //
-// The contract (dossier §10.3):
+// The contract:
 //   - ONE stable object implementing the `SandboxSessionLike` structural surface.
 //   - On EVERY op, re-read `(activeSandboxId, activeEpoch)` via `readPointer`.
 //   - Cache the resolved backend session keyed by `activeEpoch`; when the epoch
@@ -58,6 +58,7 @@ export interface RoutableBackendSession {
   exec?(args: unknown): Promise<unknown>;
   execCommand?(args: unknown): Promise<string>;
   writeStdin?(args: unknown): Promise<string>;
+  cancelExecCommand?(opId: string): Promise<boolean>;
   readFile?(args: unknown): Promise<string | Uint8Array>;
   writeFile?(args: unknown): Promise<unknown>;
   createEditor?(runAs?: string): unknown;
@@ -430,6 +431,13 @@ export class RoutingSandboxSession implements RoutableBackendSession {
     });
   }
 
+  async cancelExecCommand(opId: string): Promise<boolean> {
+    return await this.dispatch("cancelExecCommand", async (session) => {
+      if (!session.cancelExecCommand) return false;
+      return await session.cancelExecCommand(opId);
+    });
+  }
+
   async readFile(args: unknown): Promise<string | Uint8Array> {
     return this.dispatch("readFile", async (s) => {
       if (!s.readFile) {