@opengeni/runtime 0.2.0

package/dist/chunk-2PO56VAL.js

@@ -0,0 +1,3478 @@
+// src/sandbox/index.ts
+import { collectSandboxEnvironment, parseExposedPorts } from "@opengeni/config";
+import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT7, TERMINAL_STREAM_PORT as TERMINAL_STREAM_PORT2 } from "@opengeni/contracts";
+
+// src/sandbox/providers/index.ts
+import { SandboxBackend as SandboxBackend2 } from "@opengeni/contracts";
+
+// src/sandbox/capabilities.ts
+import {
+  CAPABILITY_DESCRIPTORS,
+  DESKTOP_STREAM_PORT,
+  SandboxBackend
+} from "@opengeni/contracts";
+function assertDescriptorRegistryInvariants() {
+  for (const backend of SandboxBackend.options) {
+    const descriptor = CAPABILITY_DESCRIPTORS[backend];
+    if (!descriptor) {
+      throw new Error(`No CapabilityDescriptor for backend "${backend}"`);
+    }
+    if (descriptor.backend !== backend) {
+      throw new Error(`Descriptor.backend mismatch for "${backend}" (got "${descriptor.backend}")`);
+    }
+    if (descriptor.capabilities.DesktopStream.available && descriptor.portExposure.kind === "none") {
+      throw new Error(`"${backend}" claims DesktopStream but portExposure.kind=none`);
+    }
+    if (descriptor.capabilities.DesktopStream.available && descriptor.capabilities.DesktopStream.transport === null) {
+      throw new Error(`"${backend}" claims DesktopStream but transport is null`);
+    }
+    if (descriptor.capabilities.DesktopStream.available !== descriptor.capabilities.Recording.available) {
+      throw new Error(
+        `"${backend}" Recording.available (${descriptor.capabilities.Recording.available}) must equal DesktopStream.available (${descriptor.capabilities.DesktopStream.available})`
+      );
+    }
+    if (descriptor.persistable && descriptor.snapshot.kind === "none") {
+      throw new Error(`"${backend}" persistable but snapshot.kind=none`);
+    }
+    if (descriptor.nativeBucketMount && (descriptor.tier === "dev" || descriptor.tier === "none")) {
+      throw new Error(`"${backend}" claims nativeBucketMount on tier=${descriptor.tier}`);
+    }
+  }
+}
+
+// src/sandbox/providers/blaxel.ts
+import { BlaxelSandboxClient } from "@openai/agents-extensions/sandbox/blaxel";
+
+// src/sandbox/errors.ts
+var SandboxConfigError = class extends Error {
+  backend;
+  constructor(backend, message) {
+    super(`[sandbox:${backend}] ${message}`);
+    this.name = "SandboxConfigError";
+    this.backend = backend;
+  }
+};
+var SandboxProviderUnavailableError = class extends Error {
+  backend;
+  constructor(backend) {
+    super(`provider ${backend} not available in installed @openai/agents-extensions`);
+    this.name = "SandboxProviderUnavailableError";
+    this.backend = backend;
+  }
+};
+
+// src/sandbox/providers/blaxel.ts
+var blaxelProvider = {
+  backend: "blaxel",
+  descriptor: CAPABILITY_DESCRIPTORS.blaxel,
+  validateCredentials(settings) {
+    if (!settings.blaxelApiKey) {
+      throw new SandboxConfigError("blaxel", "OPENGENI_BLAXEL_API_KEY is required");
+    }
+  },
+  build({ settings, environment }) {
+    const options = {
+      apiKey: settings.blaxelApiKey,
+      env: environment
+    };
+    if (settings.blaxelImage) options.image = settings.blaxelImage;
+    if (settings.blaxelRegion) options.region = settings.blaxelRegion;
+    if (settings.blaxelExposedPortPublic !== void 0) {
+      options.exposedPortPublic = settings.blaxelExposedPortPublic;
+    }
+    if (settings.blaxelExposedPortUrlTtlSeconds) {
+      options.exposedPortUrlTtlS = settings.blaxelExposedPortUrlTtlSeconds;
+    }
+    if (settings.blaxelMemoryMb) options.memory = settings.blaxelMemoryMb;
+    if (settings.blaxelTtl) options.ttl = settings.blaxelTtl;
+    return new BlaxelSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/cloudflare.ts
+import { CloudflareSandboxClient } from "@openai/agents-extensions/sandbox/cloudflare";
+var cloudflareProvider = {
+  backend: "cloudflare",
+  descriptor: CAPABILITY_DESCRIPTORS.cloudflare,
+  validateCredentials(settings) {
+    if (!settings.cloudflareWorkerUrl) {
+      throw new SandboxConfigError("cloudflare", "OPENGENI_CLOUDFLARE_WORKER_URL is required");
+    }
+  },
+  build({ settings, exposedPorts }) {
+    const options = {
+      workerUrl: settings.cloudflareWorkerUrl,
+      exposedPorts
+    };
+    if (settings.cloudflareApiKey) options.apiKey = settings.cloudflareApiKey;
+    return new CloudflareSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/daytona.ts
+import { DaytonaSandboxClient } from "@openai/agents-extensions/sandbox/daytona";
+var daytonaProvider = {
+  backend: "daytona",
+  descriptor: CAPABILITY_DESCRIPTORS.daytona,
+  validateCredentials(settings) {
+    if (!settings.daytonaApiKey) {
+      throw new SandboxConfigError("daytona", "OPENGENI_DAYTONA_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options = {
+      apiKey: settings.daytonaApiKey,
+      env: environment,
+      exposedPorts
+    };
+    if (settings.daytonaApiUrl) options.apiUrl = settings.daytonaApiUrl;
+    if (settings.daytonaTarget) options.target = settings.daytonaTarget;
+    if (settings.daytonaImage) options.image = settings.daytonaImage;
+    if (settings.daytonaSnapshotName) options.sandboxSnapshotName = settings.daytonaSnapshotName;
+    if (settings.daytonaAutoStopInterval !== void 0) {
+      options.autoStopInterval = settings.daytonaAutoStopInterval;
+    }
+    if (settings.daytonaTimeoutSeconds) options.timeoutSec = settings.daytonaTimeoutSeconds;
+    if (settings.daytonaExposedPortUrlTtlSeconds) {
+      options.exposedPortUrlTtlS = settings.daytonaExposedPortUrlTtlSeconds;
+    }
+    return new DaytonaSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/docker.ts
+import { DockerSandboxClient } from "@openai/agents/sandbox/local";
+var dockerProvider = {
+  backend: "docker",
+  descriptor: CAPABILITY_DESCRIPTORS.docker,
+  // Local dev container — no credentials. (The dockerNetwork decoration is
+  // applied by the factory, not here: it wraps the constructed client.)
+  validateCredentials() {
+  },
+  build({ settings, exposedPorts }) {
+    return new DockerSandboxClient({
+      image: settings.dockerImage,
+      exposedPorts
+    });
+  }
+};
+
+// src/sandbox/providers/e2b.ts
+import { E2BSandboxClient } from "@openai/agents-extensions/sandbox/e2b";
+var e2bProvider = {
+  backend: "e2b",
+  descriptor: CAPABILITY_DESCRIPTORS.e2b,
+  validateCredentials(settings) {
+    if (!settings.e2bApiKey) {
+      throw new SandboxConfigError("e2b", "OPENGENI_E2B_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options = {
+      env: environment,
+      exposedPorts
+    };
+    if (settings.e2bTemplate) options.template = settings.e2bTemplate;
+    if (settings.e2bTimeoutSeconds) options.timeout = settings.e2bTimeoutSeconds;
+    if (settings.e2bTimeoutAction) options.timeoutAction = settings.e2bTimeoutAction;
+    if (settings.e2bAllowInternetAccess !== void 0) {
+      options.allowInternetAccess = settings.e2bAllowInternetAccess;
+    }
+    if (settings.e2bAutoResume !== void 0) options.autoResume = settings.e2bAutoResume;
+    if (settings.e2bWorkspacePersistence) {
+      options.workspacePersistence = settings.e2bWorkspacePersistence;
+    }
+    return new E2BSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/local.ts
+import { UnixLocalSandboxClient } from "@openai/agents/sandbox/local";
+var localProvider = {
+  backend: "local",
+  descriptor: CAPABILITY_DESCRIPTORS.local,
+  // UnixLocalSandboxClient runs in-process — no credentials, no options.
+  validateCredentials() {
+  },
+  build() {
+    return new UnixLocalSandboxClient();
+  }
+};
+
+// src/sandbox/providers/modal.ts
+import { ModalImageSelector, ModalSandboxClient } from "@openai/agents-extensions/sandbox/modal";
+import { effectiveModalIdleTimeoutSeconds } from "@opengeni/config";
+var modalProvider = {
+  backend: "modal",
+  descriptor: CAPABILITY_DESCRIPTORS.modal,
+  validateCredentials(settings) {
+    if (Boolean(settings.modalTokenId) !== Boolean(settings.modalTokenSecret)) {
+      throw new SandboxConfigError(
+        "modal",
+        "OPENGENI_MODAL_TOKEN_ID and OPENGENI_MODAL_TOKEN_SECRET must both be set or both omitted"
+      );
+    }
+    if (!settings.modalAppName) {
+      throw new SandboxConfigError("modal", "OPENGENI_MODAL_APP_NAME is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options = {
+      appName: settings.modalAppName,
+      timeoutMs: settings.modalTimeoutSeconds * 1e3,
+      exposedPorts,
+      env: environment
+    };
+    options.idleTimeoutMs = effectiveModalIdleTimeoutSeconds(settings) * 1e3;
+    if (settings.modalWorkspacePersistence) {
+      options.workspacePersistence = settings.modalWorkspacePersistence;
+    }
+    if (settings.modalImageRef) {
+      options.image = ModalImageSelector.fromTag(settings.modalImageRef);
+    }
+    if (settings.modalTokenId) {
+      options.tokenId = settings.modalTokenId;
+    }
+    if (settings.modalTokenSecret) {
+      options.tokenSecret = settings.modalTokenSecret;
+    }
+    if (settings.modalEnvironment) {
+      options.environment = settings.modalEnvironment;
+    }
+    return new ModalSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/none.ts
+var noneProvider = {
+  backend: "none",
+  descriptor: CAPABILITY_DESCRIPTORS.none,
+  // No sandbox: nothing to validate, and build() returns undefined. The factory
+  // short-circuits on "none" before calling build, but we keep build honest.
+  validateCredentials() {
+  },
+  build() {
+    return void 0;
+  }
+};
+
+// src/sandbox/providers/runloop.ts
+import { RunloopSandboxClient } from "@openai/agents-extensions/sandbox/runloop";
+var runloopProvider = {
+  backend: "runloop",
+  descriptor: CAPABILITY_DESCRIPTORS.runloop,
+  validateCredentials(settings) {
+    if (!settings.runloopApiKey) {
+      throw new SandboxConfigError("runloop", "OPENGENI_RUNLOOP_API_KEY is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options = {
+      apiKey: settings.runloopApiKey,
+      env: environment,
+      exposedPorts,
+      // Tunnel v2: one tunnel for all ports. Defaults to true in our config.
+      tunnel: settings.runloopTunnel
+    };
+    if (settings.runloopBaseUrl) options.baseUrl = settings.runloopBaseUrl;
+    if (settings.runloopBlueprintName) options.blueprintName = settings.runloopBlueprintName;
+    if (settings.runloopBlueprintId) options.blueprintId = settings.runloopBlueprintId;
+    if (settings.runloopKeepAliveSeconds) {
+      options.timeouts = { keepAliveTimeoutMs: settings.runloopKeepAliveSeconds * 1e3 };
+    }
+    return new RunloopSandboxClient(options);
+  }
+};
+
+// src/sandbox/selfhosted/control-rpc.ts
+import {
+  ControlRequest,
+  ControlResponse,
+  ErrorCode
+} from "@opengeni/agent-proto";
+function subjectFor(workspaceId, agentId) {
+  return `agent.${workspaceId}.${agentId}.rpc`;
+}
+var SelfhostedControlError = class extends Error {
+  name = "SelfhostedControlError";
+  code;
+  reason;
+  retryable;
+  fenced;
+  draining;
+  agentOffline;
+  osNotFound;
+  detail;
+  constructor(input) {
+    super(input.message);
+    this.code = input.code;
+    this.reason = input.reason;
+    this.retryable = input.retryable;
+    this.fenced = input.fenced ?? false;
+    this.draining = input.draining ?? false;
+    this.agentOffline = input.agentOffline ?? false;
+    this.osNotFound = input.osNotFound ?? false;
+    this.detail = input.detail ?? {};
+  }
+};
+function agentErrorToControlError(err) {
+  const message = err.message || `agent error (${err.code})`;
+  const detail = err.detail ?? {};
+  switch (err.code) {
+    case ErrorCode.ERROR_CODE_AGENT_OFFLINE:
+      return new SelfhostedControlError({
+        message: message || "the enrolled agent is offline",
+        code: err.code,
+        reason: "agent_offline",
+        retryable: false,
+        agentOffline: true,
+        detail
+      });
+    case ErrorCode.ERROR_CODE_TIMEOUT:
+      return new SelfhostedControlError({
+        message: message || "the enrolled agent did not respond in time",
+        code: err.code,
+        reason: "agent_reconnecting",
+        retryable: true,
+        detail
+      });
+    case ErrorCode.ERROR_CODE_CONSENT_REQUIRED:
+      return new SelfhostedControlError({
+        message: message || "the op requires consent that has not been granted",
+        code: err.code,
+        reason: "consent_required",
+        retryable: false,
+        detail
+      });
+    case ErrorCode.ERROR_CODE_DRAINING:
+      return new SelfhostedControlError({
+        message: message || "the agent is draining and cannot accept new work",
+        code: err.code,
+        reason: null,
+        retryable: true,
+        draining: true,
+        detail
+      });
+    case ErrorCode.ERROR_CODE_FENCED:
+      return new SelfhostedControlError({
+        message: message || "a stale op was fenced by the epoch guard; re-resolve and retry",
+        code: err.code,
+        reason: null,
+        retryable: true,
+        fenced: true,
+        detail
+      });
+    case ErrorCode.ERROR_CODE_NOT_FOUND:
+      return new SelfhostedControlError({
+        message: message || "the referenced path or ref does not exist",
+        code: err.code,
+        reason: null,
+        retryable: Boolean(err.retryable),
+        osNotFound: true,
+        detail
+      });
+    default:
+      return new SelfhostedControlError({
+        message,
+        code: err.code,
+        reason: null,
+        retryable: Boolean(err.retryable),
+        detail
+      });
+  }
+}
+function offlineAgentError(message = "no agent responded (offline)") {
+  return {
+    code: ErrorCode.ERROR_CODE_AGENT_OFFLINE,
+    message,
+    retryable: false,
+    detail: {}
+  };
+}
+function timeoutAgentError(message = "the agent did not respond in time") {
+  return {
+    code: ErrorCode.ERROR_CODE_TIMEOUT,
+    message,
+    retryable: true,
+    detail: {}
+  };
+}
+var NATS_NO_RESPONDERS_CODE = "503";
+function isNoRespondersError(err) {
+  const code = err?.code;
+  if (typeof code === "string" && code === NATS_NO_RESPONDERS_CODE) {
+    return true;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return /no responders|503/i.test(message);
+}
+function isRequestTimeoutError(err) {
+  const code = err?.code;
+  if (typeof code === "string" && /timeout/i.test(code)) {
+    return true;
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  return /timeout|timed out/i.test(message);
+}
+var NatsControlRpc = class {
+  connect;
+  connection;
+  constructor(connect) {
+    this.connect = connect;
+  }
+  async resolveConnection() {
+    if (this.connection === void 0) {
+      try {
+        this.connection = await this.connect();
+      } catch {
+        this.connection = null;
+        return null;
+      }
+    }
+    return this.connection ?? null;
+  }
+  async request(subject, req, opts) {
+    const conn = await this.resolveConnection();
+    if (!conn) {
+      return offlineControlResponse(req.requestId);
+    }
+    const payload = ControlRequest.encode(req).finish();
+    try {
+      const reply = await conn.request(subject, payload, { timeout: opts.timeoutMs });
+      return ControlResponse.decode(reply.data);
+    } catch (err) {
+      if (isNoRespondersError(err)) {
+        return offlineControlResponse(req.requestId);
+      }
+      if (isRequestTimeoutError(err)) {
+        return timeoutControlResponse(req.requestId);
+      }
+      this.connection = void 0;
+      return offlineControlResponse(req.requestId);
+    }
+  }
+};
+function offlineControlResponse(requestId) {
+  return { requestId, error: offlineAgentError(), result: void 0 };
+}
+function timeoutControlResponse(requestId) {
+  return { requestId, error: timeoutAgentError(), result: void 0 };
+}
+
+// src/sandbox/selfhosted/session.ts
+import {
+  FsEntryKind,
+  StreamKind
+} from "@opengeni/agent-proto";
+import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT2 } from "@opengeni/contracts";
+import { Manifest } from "@openai/agents/sandbox";
+var decoder = new TextDecoder();
+var encoder = new TextEncoder();
+var SELFHOSTED_VIRTUAL_ROOT = "/workspace";
+function toMachinePath(p, workingDir) {
+  const base = workingDir.replace(/\/$/, "");
+  if (!p || p === SELFHOSTED_VIRTUAL_ROOT) return base;
+  if (p.startsWith(`${SELFHOSTED_VIRTUAL_ROOT}/`)) {
+    const rel = p.slice(SELFHOSTED_VIRTUAL_ROOT.length + 1);
+    return base ? `${base}/${rel}` : rel;
+  }
+  if (p.startsWith("/")) return p;
+  return base ? `${base}/${p}` : p;
+}
+var injectedApplyDiff;
+function setSelfhostedApplyDiff(fn) {
+  injectedApplyDiff = fn;
+}
+var SELFHOSTED_DEFAULT_TIMEOUT_MS = 3e4;
+var SELFHOSTED_RELAY_STREAM_PATH = "/stream";
+var SelfhostedSession = class {
+  backendId = "selfhosted";
+  workspaceId;
+  agentId;
+  controlRpc;
+  relay;
+  epoch;
+  timeoutMs;
+  subject;
+  /** The session working directory — the path/cwd base every op is rooted under
+   *  (see `toMachinePath`). "" by default ⇒ today's workspace_root behavior. */
+  workingDir;
+  /**
+   * The structural `state` slice consumers read. `agentId`/`instanceId` serve the
+   * channel-a `readInstanceId` + docker-network decoration (the agentId IS the
+   * identity). `manifest` is the slice the @openai/agents SDK reads AND writes per
+   * turn (serializeManifestEnvironment / validateProvidedSessionManifestUpdate read
+   * `manifest.root` + iterate `manifest.environment`; providedSessionManifest WRITES
+   * `state.manifest = next`). It must be a real, MUTABLE Manifest field — when the
+   * RoutingSandboxSession proxy resolves THIS as the active backend it returns
+   * `session.state` BY REFERENCE, so the SDK's read and write must both land on a
+   * well-formed Manifest here (defined `root`, object `environment`). Without it the
+   * SDK crashes with `undefined is not an object (evaluating 'current.root')`.
+   *
+   * `manifest` is intentionally a plain mutable field (not `readonly`) so the SDK's
+   * `state.manifest = next` write succeeds. It is NOT part of the persistable state
+   * (`serializeSessionState` round-trips `{agentId}` only).
+   *
+   * `environment` is the SDK `SandboxSessionState.environment` (a `Record<string,
+   * string>`). It MUST be present because the GROUP box's client serializes THIS
+   * (the active backend's) state at end-of-turn — the non-owned injected session is
+   * serialized via the CONFIGURED client (modal in prod), NOT the selfhosted client.
+   * Modal's `serializeRemoteSandboxSessionState` does `Object.entries(state.environment)`;
+   * an absent field crashes the post-turn RunState serialize with "Object.entries
+   * requires that input parameter not be null or undefined". It carries the run's
+   * threaded environment (or `{}`). The resulting modal-tagged envelope is inert for
+   * selfhosted (resume re-addresses the machine by agentId via the lease pointer,
+   * never from this SDK envelope), so its only job is to not crash the serialize.
+   */
+  state;
+  constructor(deps) {
+    this.workspaceId = deps.workspaceId;
+    this.agentId = deps.agentId;
+    this.controlRpc = deps.controlRpc;
+    this.relay = deps.relay;
+    this.epoch = deps.epoch ?? 0;
+    this.timeoutMs = deps.timeoutMs ?? SELFHOSTED_DEFAULT_TIMEOUT_MS;
+    this.subject = subjectFor(deps.workspaceId, deps.agentId);
+    this.workingDir = deps.workingDir ?? "";
+    this.state = {
+      agentId: deps.agentId,
+      instanceId: deps.agentId,
+      manifest: new Manifest({ root: "/workspace", entries: {}, environment: deps.environment ?? {} }),
+      // The SDK `SandboxSessionState.environment` — the run's threaded env (or `{}`).
+      // The group client's end-of-turn serialize reads `state.environment` directly
+      // (Object.entries), so it must be a defined object, not absent.
+      environment: deps.environment ?? {}
+    };
+  }
+  /** Issue a control op, decoding the agent's reply or throwing the mapped
+   *  `SelfhostedControlError` on an AgentError (incl. a synthesized offline /
+   *  timeout error from the transport). */
+  async call(op) {
+    const req = {
+      requestId: crypto.randomUUID(),
+      epoch: this.epoch,
+      op
+    };
+    const res = await this.controlRpc.request(this.subject, req, { timeoutMs: this.timeoutMs });
+    if (res.error) {
+      throw agentErrorToControlError(res.error);
+    }
+    if (!res.result) {
+      throw agentErrorToControlError({
+        code: 7,
+        // ERROR_CODE_PROTOCOL — an empty result is a protocol violation
+        message: "agent returned an empty control response",
+        retryable: false,
+        detail: {}
+      });
+    }
+    return res.result;
+  }
+  /** Channel-A `exec`: run a command on the machine and return its output. */
+  async exec(args) {
+    const execReq = {
+      // The agent does NOT shell-interpret unless `shell` — Channel-A passes a
+      // single shell command string, so run it through the platform shell.
+      command: [args.cmd],
+      shell: true,
+      // Rewrite a virtual-root cwd ("/workspace[/…]") onto the machine's frame —
+      // an absolute "/workspace" would ENOENT on a real machine (see
+      // SELFHOSTED_VIRTUAL_ROOT). Empty → the session workingDir (itself "" by
+      // default ⇒ the agent runs in its workspace_root).
+      cwd: toMachinePath(args.workdir, this.workingDir),
+      env: {},
+      stdin: new Uint8Array(0),
+      timeoutMs: 0
+    };
+    const result = await this.call({ $case: "exec", exec: execReq });
+    if (result.$case !== "exec") {
+      throw new Error(`selfhosted exec: unexpected result ${result.$case}`);
+    }
+    return execResultToChannelA(result.exec);
+  }
+  // ── The agent-turn provided-session contract (over the SAME NATS primitives) ──
+  // These are what the @openai/agents shell/filesystem/skills capabilities call on
+  // the ACTIVE session once the routing proxy resolves selfhosted. They reuse the
+  // exec/fs ops above; the machine owns its filesystem (materialization is a no-op).
+  /** SDK shell capability `execCommand`: run a command and return its stdout (the
+   *  `exec_command` tool). Selfhosted exec is non-interactive (no PTY) — `tty` is
+   *  ignored; `supportsPty()` is false so the SDK never offers a stdin session. */
+  async execCommand(args) {
+    const result = await this.exec({ cmd: args.cmd, workdir: args.workdir, runAs: args.runAs });
+    return result.output;
+  }
+  /** SDK shell capability never calls this (gated on `supportsPty()` which is
+   *  false), but the surface advertises it. Selfhosted exec has no interactive PTY
+   *  session over the structured RPC, so a stdin write is unsupported. */
+  supportsPty() {
+    return false;
+  }
+  /** SDK filesystem capability `view_image`: read the image bytes off the machine
+   *  and wrap them in the tool-output image shape (magic-byte sniff + path fallback,
+   *  mirroring the SDK's `imageOutputFromBytes`). */
+  async viewImage(args) {
+    const bytes = await this.readFile({ path: args.path, ...args.runAs ? { runAs: args.runAs } : {} });
+    const mediaType = sniffImageMediaType(bytes, args.path);
+    if (!mediaType) {
+      throw new Error(`selfhosted view_image: unsupported image format for ${args.path}`);
+    }
+    return { type: "image", image: { data: Uint8Array.from(bytes), mediaType } };
+  }
+  /** SDK skills/filesystem `pathExists`: whether a path exists on the machine. */
+  async pathExists(path, _runAs) {
+    const { exists } = await this.statFile({ path });
+    return exists;
+  }
+  /** SDK skills `listDir`: list a directory as `{name, path, type}[]`. */
+  async listDir(args) {
+    const result = await this.listFiles({ path: args.path });
+    return result.fsList.entries.map((entry) => ({
+      name: entry.name,
+      path: entry.path,
+      type: entry.kind === FsEntryKind.FS_ENTRY_KIND_DIRECTORY ? "dir" : entry.kind === FsEntryKind.FS_ENTRY_KIND_FILE ? "file" : "other"
+    }));
+  }
+  /** SDK manifest-delta `materializeEntry`: a NO-OP for selfhosted. Source
+   *  materialization (cloning repos / staging files into the box) is how cloud
+   *  providers prepare a fresh box; a bring-your-own machine already owns its
+   *  filesystem and is prepared by the agent itself, so there is nothing to stage.
+   *  Present (not absent) so the SDK's provided-session manifest apply path — which
+   *  requires `applyManifest()` OR `materializeEntry()` when the agent declares
+   *  entries — is satisfied without error. The selfhosted manifest declares no
+   *  entries, so in practice this is never invoked with a real entry. */
+  async materializeEntry(_args) {
+    return;
+  }
+  /** SDK filesystem capability `createEditor`: the apply_patch host. Applies V4A
+   *  diffs over the NATS fs ops (read → applyDiff → write). `applyDiff` is the SDK's
+   *  own parser, injected by the runtime barrel (the leaf cannot import it). */
+  createEditor(runAs) {
+    const applyDiff = injectedApplyDiff;
+    if (!applyDiff) {
+      throw new Error(
+        "selfhosted createEditor: applyDiff not injected (the runtime barrel must call setSelfhostedApplyDiff before an agent turn binds the filesystem capability)"
+      );
+    }
+    const pathExists = (path) => this.pathExists(path, runAs);
+    const readText = async (path) => decoder.decode(await this.readFile({ path, ...runAs ? { runAs } : {} }));
+    const writeText = async (path, content) => {
+      await this.writeFile({ path, content, createParents: true });
+    };
+    const deletePath = async (path) => {
+      await this.exec({ cmd: `rm -rf -- ${shellQuote(toMachinePath(path, ""))}`, ...runAs ? { runAs } : {} });
+    };
+    return {
+      async createFile(operation) {
+        if (await pathExists(operation.path)) {
+          throw new Error(`selfhosted createFile: file already exists: ${operation.path}`);
+        }
+        await writeText(operation.path, applyDiff("", operation.diff, "create"));
+        return {};
+      },
+      async updateFile(operation) {
+        const current = await readText(operation.path);
+        const next = applyDiff(current, operation.diff);
+        const destination = operation.moveTo ?? operation.path;
+        await writeText(destination, next);
+        if (operation.moveTo && destination !== operation.path) {
+          await deletePath(operation.path);
+        }
+        return {};
+      },
+      async deleteFile(operation) {
+        await deletePath(operation.path);
+        return {};
+      }
+    };
+  }
+  /** Channel-A `readFile`: read a file off the machine (binary-safe). */
+  async readFile(args) {
+    const result = await this.call({
+      $case: "fsRead",
+      fsRead: {
+        path: toMachinePath(args.path, this.workingDir),
+        offset: "0",
+        length: args.maxBytes ? String(args.maxBytes) : "0"
+      }
+    });
+    if (result.$case !== "fsRead") {
+      throw new Error(`selfhosted readFile: unexpected result ${result.$case}`);
+    }
+    return result.fsRead.content;
+  }
+  /** Write a file onto the machine (the fs surface the descriptor advertises). */
+  async writeFile(args) {
+    const content = typeof args.content === "string" ? encoder.encode(args.content) : args.content;
+    const result = await this.call({
+      $case: "fsWrite",
+      fsWrite: {
+        path: toMachinePath(args.path, this.workingDir),
+        content,
+        createParents: args.createParents ?? true,
+        append: args.append ?? false,
+        mode: 0
+      }
+    });
+    if (result.$case !== "fsWrite") {
+      throw new Error(`selfhosted writeFile: unexpected result ${result.$case}`);
+    }
+    return Number(result.fsWrite.bytesWritten);
+  }
+  /** List a directory on the machine. */
+  async listFiles(args) {
+    const result = await this.call({
+      $case: "fsList",
+      fsList: { path: toMachinePath(args.path, this.workingDir), recursive: args.recursive ?? false }
+    });
+    if (result.$case !== "fsList") {
+      throw new Error(`selfhosted listFiles: unexpected result ${result.$case}`);
+    }
+    return result;
+  }
+  /** Stat a path on the machine. */
+  async statFile(args) {
+    const result = await this.call({ $case: "fsStat", fsStat: { path: toMachinePath(args.path, this.workingDir) } });
+    if (result.$case !== "fsStat") {
+      throw new Error(`selfhosted statFile: unexpected result ${result.$case}`);
+    }
+    return { exists: result.fsStat.exists };
+  }
+  // ── Computer-use control plane (the agent drives its OWN screen) ──────────────
+  // The CONTROL-PLANE twin of the relay DesktopInput/desktop stream: instead of a
+  // human viewer channel, the agent injects synthetic input into — and captures —
+  // its own display for the model's computer-use loop. Both route over the SAME
+  // `call()` primitive, so a consent/epoch rejection surfaces as the mapped
+  // `SelfhostedControlError` exactly like every other op. `NativeDesktopComputer`
+  // (sandbox-computer.ts) is the sole consumer.
+  /** Computer-use WRITE op: inject one synthetic desktop input event (pointer/key/
+   *  scroll) on the machine's OWN display. The agent injects via CGEvent (macOS) /
+   *  XTEST (Linux) and CONSENT-GATES it — an unconsented call never touches the OS
+   *  and surfaces the mapped control error (ERROR_CODE_CONSENT_REQUIRED) via `call()`. */
+  async desktopInput(event) {
+    const result = await this.call({ $case: "desktopInput", desktopInput: { event } });
+    if (result.$case !== "desktopInput") {
+      throw new Error(`selfhosted desktopInput: unexpected result ${result.$case}`);
+    }
+  }
+  /** Computer-use VIEW op: capture a single PNG screenshot of the machine's desktop
+   *  plus its geometry (via ScreenCaptureKit / x11). NOT consent-gated (a view op —
+   *  the view/control decoupling), so it works with a display but no screen-control
+   *  consent. Returns the raw encoded bytes + width/height. */
+  async screenshot() {
+    const result = await this.call({ $case: "desktopScreenshot", desktopScreenshot: {} });
+    if (result.$case !== "desktopScreenshot") {
+      throw new Error(`selfhosted screenshot: unexpected result ${result.$case}`);
+    }
+    return {
+      png: result.desktopScreenshot.png,
+      width: result.desktopScreenshot.width,
+      height: result.desktopScreenshot.height
+    };
+  }
+  /** A cheap liveness probe — request a Ping on the subject; returns true iff a
+   *  responder answered (no AgentError). Used by `negotiateSelfhostedCapabilities`.
+   *  The wire `nonce` is a uint64 (a numeric string), so the default is a random
+   *  numeric value — NOT a UUID (which would fail proto uint64 encoding). */
+  async ping(nonce = randomNonce()) {
+    const req = {
+      requestId: crypto.randomUUID(),
+      epoch: this.epoch,
+      op: { $case: "ping", ping: { nonce } }
+    };
+    const res = await this.controlRpc.request(this.subject, req, { timeoutMs: this.timeoutMs });
+    return !res.error && res.result?.$case === "ping";
+  }
+  /**
+   * Resolve an exposed port to a relay stream endpoint (the viewer/pty plane).
+   * Returns the relay URL SHAPE — `{host:relay, port, tls, query:channel-key}` —
+   * after asking the agent to ensure a stream channel for the port. M8b wires the
+   * real relay tier (the byte pump) behind THIS seam.
+   *
+   * THE CHANNEL-KEY QUERY (the M8b relay-dial contract, dossier §10.5): the relay
+   * routes by `{workspaceId, agentId, port}` — the EXACT `ChannelKey::query` the
+   * agent's relay client (`opengeni-agent-stream`) appends when it registers the
+   * producer side: `ws=<workspaceId>&agent=<agentId>&port=<port>`. We append the
+   * agent-registered `channel=<channelId>` as a correlation hint. So the viewer
+   * dials `wss://<relay>/stream?ws=&agent=&port=&channel=` and presents the minted
+   * `ogs_` token in-band (NEVER as a URL param) — the relay pairs it with the
+   * producer by the routing key.
+   */
+  async resolveExposedPort(port) {
+    let channel;
+    if (port === DESKTOP_STREAM_PORT2) {
+      const result = await this.call({
+        $case: "desktopEnsure",
+        desktopEnsure: { width: 0, height: 0 }
+      });
+      if (result.$case !== "desktopEnsure") {
+        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+      }
+      channel = result.desktopEnsure.channel;
+    } else {
+      const result = await this.call({
+        $case: "ptyOpen",
+        // Open the terminal in the session workingDir (default "" ⇒ the agent's
+        // workspace_root, byte-identical to before). A relative workingDir resolves
+        // under workspace_root; an absolute one is used as-is by the agent.
+        ptyOpen: { command: [], cwd: this.workingDir, env: {}, cols: 0, rows: 0, term: "xterm-256color" }
+      });
+      if (result.$case !== "ptyOpen") {
+        throw new Error(`selfhosted resolveExposedPort(${port}): unexpected result ${result.$case}`);
+      }
+      channel = result.ptyOpen.channel;
+    }
+    const channelId = channel?.channelId ?? channelKey(this.workspaceId, this.agentId, port);
+    const tls = this.relay.tls ?? true;
+    const routingQuery = `ws=${encodeURIComponent(this.workspaceId)}&agent=${encodeURIComponent(this.agentId)}&port=${port}&channel=${encodeURIComponent(channelId)}`;
+    return {
+      host: this.relay.host,
+      port: this.relay.port ?? (tls ? 443 : 80),
+      tls,
+      // The relay's wss route (`/stream`); buildStreamUrl honors `path`.
+      path: this.relay.path ?? SELFHOSTED_RELAY_STREAM_PATH,
+      query: routingQuery,
+      protocol: kindToProtocol(channel?.kind)
+    };
+  }
+  /** Round-trip the persistable state — `{agentId}` ONLY (resume = re-address). */
+  async serializeSessionState() {
+    return { agentId: this.agentId };
+  }
+};
+var SelfhostedSandboxClient = class {
+  backendId = "selfhosted";
+  supportsDefaultOptions = false;
+  workspaceId;
+  relay;
+  controlRpcFactory;
+  defaultAgentId;
+  epoch;
+  timeoutMs;
+  environment;
+  workingDir;
+  controlRpcMemo;
+  constructor(opts) {
+    this.workspaceId = opts.workspaceId;
+    this.relay = opts.relay;
+    this.controlRpcFactory = opts.controlRpcFactory;
+    this.defaultAgentId = opts.agentId;
+    this.epoch = opts.epoch;
+    this.timeoutMs = opts.timeoutMs;
+    this.environment = opts.environment;
+    this.workingDir = opts.workingDir;
+  }
+  controlRpc() {
+    if (!this.controlRpcMemo) {
+      this.controlRpcMemo = this.controlRpcFactory();
+    }
+    return this.controlRpcMemo;
+  }
+  bind(agentId) {
+    return new SelfhostedSession({
+      workspaceId: this.workspaceId,
+      agentId,
+      controlRpc: this.controlRpc(),
+      relay: this.relay,
+      ...this.epoch !== void 0 ? { epoch: this.epoch } : {},
+      ...this.timeoutMs !== void 0 ? { timeoutMs: this.timeoutMs } : {},
+      ...this.environment !== void 0 ? { environment: this.environment } : {},
+      ...this.workingDir !== void 0 ? { workingDir: this.workingDir } : {}
+    });
+  }
+  /** Bind a session to the live agent subject. There is no box to provision. */
+  async create(_manifest, _options) {
+    const agentId = this.requireAgentId();
+    return this.bind(agentId);
+  }
+  /** Resume = re-address the subject. Identical to create — no provider state. */
+  async resume(state, _options) {
+    const agentId = readAgentId(state) ?? this.requireAgentId();
+    return this.bind(agentId);
+  }
+  /** Serialize a live session's state → `{agentId}` ONLY. */
+  async serializeSessionState(state) {
+    const agentId = readAgentId(state) ?? this.requireAgentId();
+    return { agentId };
+  }
+  /** Deserialize `{agentId}` from the persisted envelope. */
+  async deserializeSessionState(state) {
+    const agentId = readAgentId(state) ?? this.requireAgentId();
+    return { agentId };
+  }
+  /** selfhosted is NOT persistable — there is no owned session state to preserve
+   *  (the machine is the persistence). The lease never snapshots it. */
+  async canPersistOwnedSessionState() {
+    return false;
+  }
+  requireAgentId() {
+    if (!this.defaultAgentId) {
+      throw new Error("selfhosted sandbox client: no agentId bound (create()/resume() need a session state carrying agentId)");
+    }
+    return this.defaultAgentId;
+  }
+};
+async function buildSelfhostedBackendSession(deps) {
+  const client = new SelfhostedSandboxClient({
+    workspaceId: deps.workspaceId,
+    relay: deps.relay,
+    controlRpcFactory: deps.controlRpcFactory,
+    agentId: deps.agentId,
+    epoch: deps.epoch,
+    ...deps.timeoutMs !== void 0 ? { timeoutMs: deps.timeoutMs } : {},
+    ...deps.environment !== void 0 ? { environment: deps.environment } : {},
+    ...deps.workingDir ? { workingDir: deps.workingDir } : {}
+  });
+  const session = await client.resume({ agentId: deps.agentId });
+  return { client, session };
+}
+function readAgentId(state) {
+  if (state && typeof state === "object") {
+    const candidate = state.agentId ?? state.providerState?.agentId;
+    if (typeof candidate === "string" && candidate.length > 0) {
+      return candidate;
+    }
+  }
+  return void 0;
+}
+function execResultToChannelA(res) {
+  const stdout = decoder.decode(res.stdout);
+  const stderr = decoder.decode(res.stderr);
+  return {
+    output: stdout,
+    stdout,
+    stderr,
+    exitCode: res.exitCode
+  };
+}
+function channelKey(workspaceId, agentId, port) {
+  return `${workspaceId}:${agentId}:${port}`;
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function sniffImageMediaType(bytes, path) {
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71) return "image/png";
+  if (bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "image/jpeg";
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 56) return "image/gif";
+  if (bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) return "image/webp";
+  if (bytes[0] === 66 && bytes[1] === 77) return "image/bmp";
+  if (bytes[0] === 73 && bytes[1] === 73 && bytes[2] === 42 && bytes[3] === 0 || bytes[0] === 77 && bytes[1] === 77 && bytes[2] === 0 && bytes[3] === 42) return "image/tiff";
+  if (looksLikeSvg(bytes)) return "image/svg+xml";
+  return mediaTypeFromPath(path);
+}
+function looksLikeSvg(bytes) {
+  const prefix = decoder.decode(bytes.subarray(0, Math.min(bytes.byteLength, 512))).trimStart().toLowerCase();
+  return prefix.startsWith("<svg") || /^<\?xml[\s\S]*<svg/u.test(prefix);
+}
+function mediaTypeFromPath(path) {
+  const p = path?.trim().toLowerCase() ?? "";
+  if (p.endsWith(".png")) return "image/png";
+  if (p.endsWith(".jpg") || p.endsWith(".jpeg")) return "image/jpeg";
+  if (p.endsWith(".gif")) return "image/gif";
+  if (p.endsWith(".webp")) return "image/webp";
+  if (p.endsWith(".bmp")) return "image/bmp";
+  if (p.endsWith(".tif") || p.endsWith(".tiff")) return "image/tiff";
+  if (p.endsWith(".svg") || p.endsWith(".svgz")) return "image/svg+xml";
+  return void 0;
+}
+function randomNonce() {
+  return String(Math.floor(Math.random() * Number.MAX_SAFE_INTEGER));
+}
+function kindToProtocol(kind) {
+  switch (kind) {
+    case StreamKind.STREAM_KIND_PTY:
+      return "pty";
+    case StreamKind.STREAM_KIND_DESKTOP:
+      return "vnc";
+    default:
+      return "raw";
+  }
+}
+function isSelfhostedProviderNotFoundError(_error) {
+  return false;
+}
+
+// src/sandbox/providers/selfhosted.ts
+function resolveRelayConfig(settings) {
+  const raw = settings.selfhostedRelayUrl?.trim();
+  if (!raw) {
+    return { host: "relay.opengeni.local", port: 443, tls: true, path: "/stream" };
+  }
+  try {
+    const url = new URL(raw.includes("://") ? raw : `wss://${raw}`);
+    const tls = url.protocol === "wss:" || url.protocol === "https:";
+    const port = url.port ? Number(url.port) : tls ? 443 : 80;
+    const path = url.pathname && url.pathname !== "/" ? url.pathname : "/stream";
+    return { host: url.hostname, port, tls, path };
+  } catch {
+    return { host: raw, port: 443, tls: true, path: "/stream" };
+  }
+}
+function defaultControlRpcFactory() {
+  return new NatsControlRpc(async () => null);
+}
+var selfhostedProvider = {
+  backend: "selfhosted",
+  descriptor: CAPABILITY_DESCRIPTORS.selfhosted,
+  /**
+   * No per-box credentials: the machine is reached over the agent's own
+   * enrollment. The enrollment-signing + relay-token secrets are deployment-level
+   * config that lands with the connectivity/enrollment milestones (M4/M5) — and
+   * the whole feature is gated by a `sandboxSelfhostedEnabled` flag (default off)
+   * that does not yet exist in Settings. So validation is LENIENT (no-op) in M3:
+   * boot must never break, and there is nothing per-box to validate. M4/M5 add
+   * the (flag-gated) signing/relay presence checks here behind the same seam.
+   */
+  validateCredentials() {
+  },
+  /**
+   * Build the registry client. `create()`/`resume()` bind a `SelfhostedSession`
+   * to the agent subject; the per-request `{workspaceId, agentId, controlRpc}`
+   * are supplied by the resume path (the lease's enrollment) — the registry
+   * client carries the relay config + the default (offline-until-M4) ControlRpc
+   * factory and a backendId-correct surface for `assertProviderRegistryInvariants`.
+   */
+  build({ settings }) {
+    return new SelfhostedSandboxClient({
+      // The workspaceId is bound per-request by the resume path (the API/worker
+      // construct a request-scoped client with the lease's workspace + a live
+      // ControlRpc). The registry-built client is the boot/assertion shape; an
+      // empty workspaceId is fine until a session is bound with a real one.
+      workspaceId: "",
+      relay: resolveRelayConfig(settings),
+      controlRpcFactory: defaultControlRpcFactory
+    });
+  }
+};
+
+// src/sandbox/providers/vercel.ts
+import { VercelSandboxClient } from "@openai/agents-extensions/sandbox/vercel";
+var vercelProvider = {
+  backend: "vercel",
+  descriptor: CAPABILITY_DESCRIPTORS.vercel,
+  validateCredentials(settings) {
+    if (!settings.vercelToken) {
+      throw new SandboxConfigError("vercel", "OPENGENI_VERCEL_TOKEN is required");
+    }
+    if (!settings.vercelProjectId) {
+      throw new SandboxConfigError("vercel", "OPENGENI_VERCEL_PROJECT_ID is required");
+    }
+  },
+  build({ settings, environment, exposedPorts }) {
+    const options = {
+      token: settings.vercelToken,
+      projectId: settings.vercelProjectId,
+      env: environment,
+      exposedPorts
+    };
+    if (settings.vercelTeamId) options.teamId = settings.vercelTeamId;
+    if (settings.vercelRuntime) options.runtime = settings.vercelRuntime;
+    return new VercelSandboxClient(options);
+  }
+};
+
+// src/sandbox/providers/index.ts
+var PROVIDER_REGISTRY = {
+  docker: dockerProvider,
+  modal: modalProvider,
+  local: localProvider,
+  none: noneProvider,
+  daytona: daytonaProvider,
+  runloop: runloopProvider,
+  e2b: e2bProvider,
+  blaxel: blaxelProvider,
+  cloudflare: cloudflareProvider,
+  vercel: vercelProvider,
+  selfhosted: selfhostedProvider
+};
+var ASSERTION_STUB_SETTINGS = {
+  dockerImage: "opengeni-sandbox:local",
+  modalAppName: "opengeni-sandbox",
+  modalTimeoutSeconds: 900,
+  daytonaApiKey: "stub",
+  runloopApiKey: "stub",
+  runloopTunnel: true,
+  e2bApiKey: "stub",
+  blaxelApiKey: "stub",
+  cloudflareWorkerUrl: "https://stub.example.com",
+  vercelToken: "stub",
+  vercelProjectId: "stub"
+};
+function assertProviderRegistryInvariants() {
+  assertDescriptorRegistryInvariants();
+  for (const backend of SandboxBackend2.options) {
+    const registration = PROVIDER_REGISTRY[backend];
+    if (registration.backend !== backend) {
+      throw new Error(`PROVIDER_REGISTRY["${backend}"].backend mismatch (got "${registration.backend}")`);
+    }
+    if (registration.descriptor.backend !== backend) {
+      throw new Error(`PROVIDER_REGISTRY["${backend}"].descriptor.backend mismatch (got "${registration.descriptor.backend}")`);
+    }
+    if (backend === "none") {
+      if (registration.descriptor.backendId !== "none") {
+        throw new Error(`"none" descriptor.backendId must be "none" (got "${registration.descriptor.backendId}")`);
+      }
+      continue;
+    }
+    const client = registration.build({
+      settings: ASSERTION_STUB_SETTINGS,
+      environment: {},
+      exposedPorts: []
+    });
+    const sdkBackendId = client?.backendId;
+    if (typeof sdkBackendId !== "string") {
+      throw new Error(`Provider "${backend}" SDK client has no string backendId`);
+    }
+    if (sdkBackendId !== registration.descriptor.backendId) {
+      throw new Error(
+        `Provider "${backend}" backendId mismatch: descriptor.backendId="${registration.descriptor.backendId}" but SDK client.backendId="${sdkBackendId}"`
+      );
+    }
+  }
+}
+assertProviderRegistryInvariants();
+
+// src/sandbox/index.ts
+import { collectSandboxEnvironment as collectSandboxEnvironment2, parseExposedPorts as parseExposedPorts2 } from "@opengeni/config";
+
+// src/sandbox/select.ts
+import {
+  CAPABILITY_DESCRIPTORS as CAPABILITY_DESCRIPTORS2
+} from "@opengeni/contracts";
+function selectBackend(backend) {
+  const descriptor = CAPABILITY_DESCRIPTORS2[backend];
+  if (!descriptor) {
+    throw new Error(`Unknown sandbox backend "${backend}"`);
+  }
+  return descriptor;
+}
+function backendSupportsOs(descriptor, os) {
+  return descriptor.os.supported.includes(os);
+}
+function desktopCapableBackend(backend) {
+  const direct = CAPABILITY_DESCRIPTORS2[backend];
+  if (direct) {
+    return direct.capabilities.DesktopStream.available === true;
+  }
+  for (const descriptor of Object.values(CAPABILITY_DESCRIPTORS2)) {
+    if (descriptor.backendId === backend) {
+      return descriptor.capabilities.DesktopStream.available === true;
+    }
+  }
+  return false;
+}
+function negotiateCapabilities(ctx) {
+  const descriptor = selectBackend(ctx.backend);
+  const osSupported = backendSupportsOs(descriptor, ctx.os);
+  const negotiatedAt = (ctx.now ?? /* @__PURE__ */ new Date()).toISOString();
+  const osReason = osSupported ? null : "os_unsupported";
+  const fileSystem = (() => {
+    if (osReason) {
+      return { available: false, readOnly: true, root: descriptor.workspaceRoot, pathSep: "/", treeMode: "lazy", reason: osReason };
+    }
+    const cap = descriptor.capabilities.FileSystem;
+    return {
+      available: cap.available,
+      readOnly: cap.readOnly,
+      root: descriptor.workspaceRoot,
+      pathSep: "/",
+      treeMode: "lazy",
+      reason: cap.available ? null : "backend_unsupported"
+    };
+  })();
+  const terminal = (() => {
+    const cap = descriptor.capabilities.Terminal;
+    if (osReason) {
+      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: osReason };
+    }
+    if (!cap.available) {
+      return { transport: null, ptyCapable: false, shell: "/bin/bash", url: null, token: null, expiresAt: null, reason: "backend_unsupported" };
+    }
+    const ptyCapable = cap.pty;
+    let transport = ptyCapable ? "pty-ws" : "sse-events";
+    let reason = null;
+    if (ptyCapable && ctx.terminalEnabled === false) {
+      transport = "sse-events";
+      reason = "disabled_by_policy";
+    } else if (ptyCapable && ctx.liveness === "cold" && !ctx.terminalStream) {
+      transport = "sse-events";
+      reason = "lease_cold";
+    }
+    const minted = transport === "pty-ws" ? ctx.terminalStream : void 0;
+    return {
+      transport,
+      ptyCapable,
+      shell: "/bin/bash",
+      url: minted?.url ?? null,
+      token: minted?.token ?? null,
+      expiresAt: minted?.expiresAt ?? null,
+      reason
+    };
+  })();
+  const git = (() => {
+    const cap = descriptor.capabilities.Git;
+    if (osReason) {
+      return { available: false, repos: [], reason: osReason };
+    }
+    return { available: cap.available, repos: [], reason: cap.available ? null : "backend_unsupported" };
+  })();
+  const desktop = (() => {
+    const cap = descriptor.capabilities.DesktopStream;
+    let reason = null;
+    let available = cap.available;
+    if (osReason) {
+      available = false;
+      reason = osReason;
+    } else if (!cap.available) {
+      available = false;
+      reason = descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported";
+    } else if (!ctx.desktopEnabled) {
+      available = false;
+      reason = "disabled_by_policy";
+    } else if (ctx.streamTokenSecretAvailable === false) {
+      available = false;
+      reason = "disabled_by_policy";
+    } else if (ctx.liveness === "cold" && !ctx.desktopStream) {
+      available = false;
+      reason = "lease_cold";
+    }
+    const shared = available ? Boolean(ctx.shared) : false;
+    const acknowledged = available ? Boolean(ctx.desktopAcknowledged) : false;
+    const minted = available && acknowledged ? ctx.desktopStream : void 0;
+    const selfhostedFrames = ctx.backend === "selfhosted";
+    const interactive = available && !selfhostedFrames && ctx.desktopInteractive !== false;
+    const mode = interactive ? "interactive" : "read-only";
+    return {
+      transport: available ? selfhostedFrames ? "relay-frames" : cap.transport : null,
+      client: available ? selfhostedFrames ? "frames" : "novnc" : null,
+      mode,
+      url: minted?.url ?? null,
+      token: minted?.token ?? null,
+      expiresAt: minted?.expiresAt ?? null,
+      resolution: minted?.resolution ?? [1024, 768],
+      // Desktop pixels are ALWAYS un-redacted when present (the literal
+      // framebuffer); the acknowledgment gate rests on this.
+      unredacted: true,
+      requiresAcknowledgment: available,
+      acknowledged: available ? Boolean(ctx.desktopAcknowledged) : false,
+      // Shared-exposure disclosure (addendum E.1): `shared` when the group has
+      // >1 session; `sharedSessionIds` is the OTHER sessions' ids ONLY (never
+      // their conversation/metadata). Empty/false for a solo box or when the
+      // desktop cell is unavailable.
+      shared,
+      sharedSessionIds: shared ? ctx.sharedSessionIds ?? [] : [],
+      reason
+    };
+  })();
+  const recording = (() => {
+    const cap = descriptor.capabilities.Recording;
+    if (osReason) {
+      return { available: false, modes: [], codecs: [], reason: osReason };
+    }
+    if (!cap.available) {
+      return { available: false, modes: [], codecs: [], reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported" };
+    }
+    if (!ctx.desktopEnabled) {
+      return { available: false, modes: [], codecs: [], reason: "disabled_by_policy" };
+    }
+    return {
+      available: true,
+      modes: ["manual", "on-turn", "on-verify"],
+      codecs: ["h264-mp4", "vp9-webm"],
+      reason: null
+    };
+  })();
+  const computerUse = (() => {
+    const desktopCapable = descriptor.capabilities.DesktopStream.available;
+    const readOnly = ctx.computerUseReadOnly ?? false;
+    if (osReason) {
+      return { available: false, readOnly, reason: osReason };
+    }
+    if (!desktopCapable) {
+      return { available: false, readOnly, reason: descriptor.tier === "headless" ? "tier_headless" : "backend_unsupported" };
+    }
+    if (!ctx.desktopEnabled || ctx.computerUseEnabled === false) {
+      return { available: false, readOnly, reason: "disabled_by_policy" };
+    }
+    return { available: true, readOnly, reason: null };
+  })();
+  return {
+    sessionId: ctx.sessionId,
+    backend: ctx.backend,
+    os: ctx.os,
+    liveness: ctx.liveness,
+    leaseEpoch: ctx.leaseEpoch,
+    viewerHeartbeatIntervalMs: 3e4,
+    FileSystem: fileSystem,
+    Terminal: terminal,
+    Git: git,
+    DesktopStream: desktop,
+    Recording: recording,
+    ComputerUse: computerUse,
+    negotiatedAt
+  };
+}
+
+// src/sandbox/stream-token.ts
+import {
+  DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT3,
+  StreamTokenPayload,
+  signStreamToken,
+  verifyStreamToken as verifyStreamTokenEnvelope
+} from "@opengeni/contracts";
+import { StreamTokenPayload as StreamTokenPayload2 } from "@opengeni/contracts";
+var STREAM_TOKEN_DEFAULT_TTL_SECONDS = 120;
+async function mintStreamToken(secret, input) {
+  const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const ttlSeconds = input.ttlSeconds ?? STREAM_TOKEN_DEFAULT_TTL_SECONDS;
+  const payload = StreamTokenPayload.parse({
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    viewerId: input.viewerId,
+    leaseEpoch: input.leaseEpoch,
+    mode: input.mode ?? "view",
+    port: input.port ?? DESKTOP_STREAM_PORT3,
+    exp: nowSeconds + ttlSeconds
+  });
+  return signStreamToken(secret, payload);
+}
+async function verifyStreamToken(secret, token, nowSeconds = Math.floor(Date.now() / 1e3)) {
+  return verifyStreamTokenEnvelope(secret, token, nowSeconds);
+}
+
+// src/sandbox/display-stack.ts
+import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT4 } from "@opengeni/contracts";
+var STREAM_PORT = DESKTOP_STREAM_PORT4;
+var DISPLAY_STACK_TIMEOUT_MS = 6e4;
+var DEFAULT_DESKTOP_GEOMETRY = { width: 1280, height: 800, dpi: 96 };
+var DisplayStackError = class extends Error {
+  exitCode;
+  stage;
+  constructor(exitCode, output) {
+    const stage = exitCode === 11 ? "xvfb" : exitCode === 12 ? "x11vnc" : exitCode === 13 ? "websockify" : "unknown";
+    super(`desktop display stack failed at stage "${stage}" (exit ${exitCode})${output ? `:
+${output}` : ""}`);
+    this.name = "DisplayStackError";
+    this.exitCode = exitCode;
+    this.stage = stage;
+  }
+};
+var DisplayStackUnsupportedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "DisplayStackUnsupportedError";
+  }
+};
+function buildDisplayStackScript(options = {}) {
+  const geometry = options.geometry ?? DEFAULT_DESKTOP_GEOMETRY;
+  const port = options.port ?? DESKTOP_STREAM_PORT4;
+  const env = `DESKTOP_W=${geometry.width} DESKTOP_H=${geometry.height} DESKTOP_DPI=${geometry.dpi} STREAM_PORT=${port}`;
+  return `if nc -z 127.0.0.1 ${port} >/dev/null 2>&1 && nc -z 127.0.0.1 5900 >/dev/null 2>&1; then echo "OPENGENI_DESKTOP_UP port=${port} geometry=${geometry.width}x${geometry.height} dpi=${geometry.dpi} (precheck)"; else mkdir -p /tmp/opengeni-desktop && flock -w 45 /tmp/opengeni-desktop/up.outer.lock env ${env} opengeni-desktop-up; fi`;
+}
+function execResultOutput(result) {
+  if (typeof result === "string") {
+    return result;
+  }
+  return [result.output, result.stderr, result.stdout].filter((v) => typeof v === "string" && v.length > 0).join("\n");
+}
+function execResultExitCode(result) {
+  if (typeof result === "string") {
+    return null;
+  }
+  return typeof result.exitCode === "number" ? result.exitCode : null;
+}
+function inferExitFromOutput(output) {
+  if (/OPENGENI_DESKTOP_UP\b/.test(output)) {
+    return 0;
+  }
+  if (/Xvfb failed to come up/.test(output)) {
+    return 11;
+  }
+  if (/x11vnc failed on/.test(output)) {
+    return 12;
+  }
+  if (/websockify failed on/.test(output)) {
+    return 13;
+  }
+  return -1;
+}
+async function ensureDisplayStack(session, options = {}) {
+  const s = session;
+  if (typeof s?.exec !== "function" && typeof s?.execCommand !== "function") {
+    throw new DisplayStackUnsupportedError(
+      "provider session cannot run commands (no exec/execCommand) \u2014 desktop tier unavailable"
+    );
+  }
+  const geometry = options.geometry ?? DEFAULT_DESKTOP_GEOMETRY;
+  const port = options.port ?? DESKTOP_STREAM_PORT4;
+  const timeoutMs = options.timeoutMs ?? DISPLAY_STACK_TIMEOUT_MS;
+  const cmd = buildDisplayStackScript({ geometry, port });
+  const result = typeof s.exec === "function" ? await s.exec({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 }) : await s.execCommand({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 });
+  const output = execResultOutput(result);
+  const exitCode = execResultExitCode(result) ?? inferExitFromOutput(output);
+  if (exitCode !== 0) {
+    throw new DisplayStackError(exitCode, output);
+  }
+  const marker = (output.match(/OPENGENI_DESKTOP_UP[^\n]*/) ?? [""])[0];
+  return { port, geometry, marker };
+}
+async function tearDownDisplayStack(session) {
+  const s = session;
+  if (typeof s?.exec === "function") {
+    await s.exec({ cmd: "opengeni-desktop-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+    return;
+  }
+  if (typeof s?.execCommand === "function") {
+    await s.execCommand({ cmd: "opengeni-desktop-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+  }
+}
+
+// src/sandbox/terminal-server.ts
+import { TERMINAL_STREAM_PORT } from "@opengeni/contracts";
+var TERMINAL_SERVER_TIMEOUT_MS = 6e4;
+var TerminalServerError = class extends Error {
+  exitCode;
+  stage;
+  constructor(exitCode, output) {
+    const stage = exitCode === 14 ? "ttyd" : "unknown";
+    super(`terminal server failed at stage "${stage}" (exit ${exitCode})${output ? `:
+${output}` : ""}`);
+    this.name = "TerminalServerError";
+    this.exitCode = exitCode;
+    this.stage = stage;
+  }
+};
+var TerminalServerUnsupportedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "TerminalServerUnsupportedError";
+  }
+};
+function buildTerminalServerScript(options = {}) {
+  const port = options.port ?? TERMINAL_STREAM_PORT;
+  return `mkdir -p /tmp/opengeni-terminal && flock -w 30 /tmp/opengeni-terminal/up.outer.lock env TERMINAL_PORT=${port} opengeni-terminal-up`;
+}
+function execResultOutput2(result) {
+  if (typeof result === "string") {
+    return result;
+  }
+  return [result.output, result.stderr, result.stdout].filter((v) => typeof v === "string" && v.length > 0).join("\n");
+}
+function execResultExitCode2(result) {
+  if (typeof result === "string") {
+    return null;
+  }
+  return typeof result.exitCode === "number" ? result.exitCode : null;
+}
+function inferExitFromOutput2(output) {
+  if (/OPENGENI_TERMINAL_UP\b/.test(output)) {
+    return 0;
+  }
+  if (/ttyd failed to come up/.test(output)) {
+    return 14;
+  }
+  return -1;
+}
+async function ensureTerminalServer(session, options = {}) {
+  const s = session;
+  if (typeof s?.exec !== "function" && typeof s?.execCommand !== "function") {
+    throw new TerminalServerUnsupportedError(
+      "provider session cannot run commands (no exec/execCommand) \u2014 terminal pty-ws unavailable"
+    );
+  }
+  const port = options.port ?? TERMINAL_STREAM_PORT;
+  const timeoutMs = options.timeoutMs ?? TERMINAL_SERVER_TIMEOUT_MS;
+  const cmd = buildTerminalServerScript({ port });
+  const result = typeof s.exec === "function" ? await s.exec({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 }) : await s.execCommand({ cmd, yieldTimeMs: timeoutMs, maxOutputTokens: 2e4 });
+  const output = execResultOutput2(result);
+  const exitCode = execResultExitCode2(result) ?? inferExitFromOutput2(output);
+  if (exitCode !== 0) {
+    throw new TerminalServerError(exitCode, output);
+  }
+  const marker = (output.match(/OPENGENI_TERMINAL_UP[^\n]*/) ?? [""])[0];
+  return { port, marker };
+}
+async function tearDownTerminalServer(session) {
+  const s = session;
+  if (typeof s?.exec === "function") {
+    await s.exec({ cmd: "opengeni-terminal-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+    return;
+  }
+  if (typeof s?.execCommand === "function") {
+    await s.execCommand({ cmd: "opengeni-terminal-down", yieldTimeMs: 1e4, maxOutputTokens: 4e3 });
+  }
+}
+
+// src/sandbox/stream-port.ts
+import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT5 } from "@opengeni/contracts";
+var StreamPortUnavailableError = class extends Error {
+  constructor(message, cause) {
+    super(message);
+    this.cause = cause;
+    this.name = "StreamPortUnavailableError";
+  }
+  cause;
+};
+var DEFAULT_RESOLUTION = [1280, 800];
+function buildStreamUrl(endpoint) {
+  if (typeof endpoint.host !== "string" || endpoint.host.length === 0 || typeof endpoint.port !== "number") {
+    throw new StreamPortUnavailableError(
+      `provider returned a malformed exposed-port endpoint (host=${String(endpoint.host)}, port=${String(endpoint.port)})`
+    );
+  }
+  const tls = endpoint.tls ?? false;
+  const scheme = tls ? "wss" : "ws";
+  const defaultPort = tls ? 443 : 80;
+  const host = endpoint.host.includes(":") && !endpoint.host.startsWith("[") ? `[${endpoint.host}]` : endpoint.host;
+  const rawPath = typeof endpoint.path === "string" && endpoint.path.length > 0 ? endpoint.path : "/";
+  const path = rawPath.startsWith("/") ? rawPath : `/${rawPath}`;
+  const origin = endpoint.port === defaultPort ? `${scheme}://${host}` : `${scheme}://${host}:${endpoint.port}`;
+  const authority = `${origin}${path}`;
+  const query = endpoint.query ?? "";
+  return query ? `${authority}?${query}` : authority;
+}
+async function exposeStreamPort(session, input) {
+  const s = session;
+  const port = input.port ?? DESKTOP_STREAM_PORT5;
+  if (typeof s?.resolveExposedPort !== "function") {
+    throw new StreamPortUnavailableError(
+      "provider session cannot resolve exposed ports (no resolveExposedPort) \u2014 desktop stream unavailable"
+    );
+  }
+  let endpoint;
+  try {
+    endpoint = await s.resolveExposedPort(port);
+  } catch (error) {
+    throw new StreamPortUnavailableError(
+      `provider failed to resolve the stream port ${port}: ${error instanceof Error ? error.message : String(error)}`,
+      error
+    );
+  }
+  const url = buildStreamUrl(endpoint);
+  const ttlSeconds = input.ttlSeconds ?? STREAM_TOKEN_DEFAULT_TTL_SECONDS;
+  const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const token = await mintStreamToken(input.streamTokenSecret, {
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    viewerId: input.viewerId,
+    leaseEpoch: input.leaseEpoch,
+    mode: "view",
+    port,
+    ttlSeconds,
+    nowSeconds
+  });
+  return {
+    url,
+    token,
+    expiresAt: new Date((nowSeconds + ttlSeconds) * 1e3).toISOString(),
+    transport: "vnc-ws",
+    client: "novnc",
+    resolution: input.resolution ?? DEFAULT_RESOLUTION,
+    leaseEpoch: input.leaseEpoch
+  };
+}
+
+// src/sandbox/recording.ts
+import { DESKTOP_STREAM_PORT as DESKTOP_STREAM_PORT6 } from "@opengeni/contracts";
+var DEFAULT_MAX_SECONDS = 600;
+var DEFAULT_FRAMERATE = 15;
+var DEFAULT_MAX_BYTES = 268435456;
+var DEFAULT_DIMENSIONS = [1280, 800];
+var STOP_YIELD_MS = 2e4;
+var EXEC_YIELD_MS = 15e3;
+function contentTypeForCodec(codec) {
+  return codec === "vp9-webm" ? "video/webm" : "video/mp4";
+}
+function extForCodec(codec) {
+  return codec === "vp9-webm" ? "webm" : "mp4";
+}
+var RecordingUnavailableError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "RecordingUnavailableError";
+  }
+};
+var RecordingError = class extends Error {
+  constructor(message, reason) {
+    super(message);
+    this.reason = reason;
+    this.name = "RecordingError";
+  }
+  reason;
+};
+function shq(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function resultOutput(result) {
+  if (typeof result === "string") return result;
+  return [result.output, result.stderr, result.stdout].filter((v) => typeof v === "string" && v.length > 0).join("\n");
+}
+var DEFAULT_MAX_OUTPUT_TOKENS = 4e3;
+async function run(session, cmd, runAs, yieldTimeMs = EXEC_YIELD_MS, maxOutputTokens = DEFAULT_MAX_OUTPUT_TOKENS) {
+  const args = { cmd, ...runAs ? { runAs } : {}, yieldTimeMs, maxOutputTokens };
+  if (typeof session.exec === "function") {
+    return resultOutput(await session.exec(args));
+  }
+  if (typeof session.execCommand === "function") {
+    return resultOutput(await session.execCommand(args));
+  }
+  throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) \u2014 recording unavailable");
+}
+function stripExecBanner(raw) {
+  const marker = raw.lastIndexOf("\nOutput:\n");
+  if (marker >= 0) return raw.slice(marker + "\nOutput:\n".length);
+  if (raw.startsWith("Output:\n")) return raw.slice("Output:\n".length);
+  return raw;
+}
+async function startRecording(session, input) {
+  const s = session;
+  const codec = input.codec ?? "h264-mp4";
+  const dimensions = input.dimensions ?? DEFAULT_DIMENSIONS;
+  const framerate = input.framerate ?? DEFAULT_FRAMERATE;
+  const maxSeconds = input.maxSeconds ?? DEFAULT_MAX_SECONDS;
+  const display = input.display ?? ":0";
+  const tmp = input.tmpDir ?? "/tmp";
+  const ext = extForCodec(codec);
+  const boxPath = `${tmp}/og-rec-${input.recordingId}.${ext}`;
+  const pidFile = `${tmp}/og-rec-${input.recordingId}.pid`;
+  const logFile = `${tmp}/og-rec-${input.recordingId}.log`;
+  const [w, h] = dimensions;
+  const enc = codec === "vp9-webm" ? `-c:v libvpx-vp9 -b:v 0 -crf 32 -row-mt 1` : `-c:v libx264 -preset veryfast -pix_fmt yuv420p -movflags +faststart`;
+  const ffmpeg = `nohup ffmpeg -hide_banner -loglevel error -f x11grab -draw_mouse 1 -framerate ${framerate} -video_size ${w}x${h} -i ${display}.0 -t ${maxSeconds} ${enc} ${boxPath} </dev/null >${logFile} 2>&1 & echo $! > ${pidFile}`;
+  await run(s, `bash -lc ${shq(ffmpeg)}`, input.runAs);
+  return {
+    recordingId: input.recordingId,
+    codec,
+    boxPath,
+    pidFile,
+    dimensions,
+    framerate,
+    startedAt: Date.now(),
+    display,
+    ...input.runAs ? { runAs: input.runAs } : {}
+  };
+}
+async function stopRecording(session, proc) {
+  const s = session;
+  const wait = `kill -INT "$(cat ${proc.pidFile})" 2>/dev/null; for i in $(seq 1 80); do kill -0 "$(cat ${proc.pidFile})" 2>/dev/null || break; sleep 0.1; done`;
+  await run(s, `bash -lc ${shq(wait)}`, proc.runAs, STOP_YIELD_MS).catch(() => void 0);
+}
+async function readRecordingBytes(session, proc, maxBytes = DEFAULT_MAX_BYTES) {
+  const s = session;
+  if (typeof s.exec !== "function" && typeof s.execCommand !== "function") {
+    throw new RecordingUnavailableError("session cannot run commands (no exec/execCommand) \u2014 recording finalize unavailable");
+  }
+  const sizeOut = (await run(s, `bash -lc ${shq(`stat -c %s ${proc.boxPath} 2>/dev/null || echo MISSING`)}`, proc.runAs)).trim();
+  const sizeLine = sizeOut.split("\n").map((l) => l.trim()).filter(Boolean).pop() ?? "MISSING";
+  if (sizeLine === "MISSING" || sizeLine === "") {
+    throw new RecordingError(`recording file missing on box: ${proc.boxPath}`, "box-death");
+  }
+  const size = Number(sizeLine);
+  if (!Number.isFinite(size) || size <= 0) {
+    throw new RecordingError(`recording file empty on box: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  if (size > maxBytes) {
+    throw new RecordingError(`recording ${size}B exceeds max ${maxBytes}B`, "max-bytes-exceeded");
+  }
+  const STOP_YIELD = 6e4;
+  const encoded = stripExecBanner(
+    await run(s, `bash -lc ${shq(`base64 ${proc.boxPath}`)}`, proc.runAs, STOP_YIELD, null)
+  );
+  const base64 = encoded.replace(/\s+/g, "");
+  if (base64.length === 0) {
+    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  let bytes;
+  try {
+    bytes = Uint8Array.from(Buffer.from(base64, "base64"));
+  } catch (error) {
+    throw new RecordingError(`recording base64 decode failed: ${error instanceof Error ? error.message : String(error)}`, "ffmpeg-error");
+  }
+  if (bytes.length === 0) {
+    throw new RecordingError(`recording read returned 0 bytes: ${proc.boxPath}`, "ffmpeg-error");
+  }
+  return {
+    bytes,
+    contentType: contentTypeForCodec(proc.codec),
+    sizeBytes: bytes.length,
+    durationSeconds: Math.max(0, Math.round((Date.now() - proc.startedAt) / 1e3))
+  };
+}
+async function deleteRecordingArtifacts(session, proc) {
+  const s = session;
+  const logFile = proc.boxPath.replace(/\.(mp4|webm)$/, ".log");
+  await run(s, `rm -f ${proc.boxPath} ${proc.pidFile} ${logFile}`, proc.runAs).catch(() => void 0);
+}
+function recordingStorageKey(workspaceId, sessionId, recordingId, codec) {
+  return `recordings/${workspaceId}/${sessionId}/${recordingId}.${extForCodec(codec)}`;
+}
+
+// src/sandbox/channel-a.ts
+var ChannelAValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChannelAValidationError";
+  }
+};
+var ChannelAConflictError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChannelAConflictError";
+  }
+};
+var ChannelANotFoundError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChannelANotFoundError";
+  }
+};
+var ChannelAUnsupportedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ChannelAUnsupportedError";
+  }
+};
+var NUL = String.fromCharCode(0);
+var US = String.fromCharCode(31);
+var RS = String.fromCharCode(30);
+var SandboxChannelAService = class {
+  session;
+  workspaceRoot;
+  leaseEpoch;
+  revision;
+  emit;
+  runAs;
+  constructor(opts) {
+    this.session = opts.session;
+    this.workspaceRoot = opts.workspaceRoot ?? "";
+    this.leaseEpoch = opts.leaseEpoch ?? 0;
+    this.revision = opts.revision ?? 0;
+    this.emit = opts.emit;
+    this.runAs = opts.runAs;
+  }
+  /** Capability probe — the compact Channel-A projection. */
+  capabilities(repos = []) {
+    const s = this.session;
+    const hasExec = Boolean(s.exec || s.execCommand);
+    const hasFs = Boolean(s.readFile && (s.exec || s.execCommand || s.createEditor));
+    return {
+      FileSystem: { available: hasFs, readOnly: !(s.exec || s.createEditor), root: this.workspaceRoot },
+      Terminal: {
+        events: hasExec,
+        exec: hasExec,
+        pty: { available: Boolean(s.supportsPty?.() && s.writeStdin) }
+      },
+      Git: { available: hasExec, repos }
+    };
+  }
+  // ════════════════════════════ exec primitive ══════════════════════════════
+  // RAW exec — returns {stdout, stderr, exitCode}. Uses session.exec when present
+  // (the local/docker sessions return raw output); falls back to execCommand +
+  // a banner strip (last resort; banner-truncation can mangle, so exec is always
+  // preferred). Throws ChannelAUnsupportedError when neither exists.
+  async run(args) {
+    const withRunAs = this.runAs ? { ...args, runAs: this.runAs } : args;
+    if (this.session.exec) {
+      const r = await this.session.exec(withRunAs);
+      return {
+        stdout: r.stdout ?? r.output ?? "",
+        stderr: r.stderr ?? "",
+        exitCode: r.exitCode ?? null,
+        ...typeof r.sessionId === "number" ? { sessionId: r.sessionId } : {},
+        wallTimeSeconds: r.wallTimeSeconds ?? 0
+      };
+    }
+    if (this.session.execCommand) {
+      const raw = await this.session.execCommand(withRunAs);
+      const sessionId = parseExecBannerSessionId(raw);
+      return {
+        stdout: stripExecBanner2(raw),
+        stderr: "",
+        exitCode: null,
+        ...sessionId !== null ? { sessionId } : {},
+        wallTimeSeconds: 0
+      };
+    }
+    throw new ChannelAUnsupportedError("the box does not support command execution");
+  }
+  // ════════════════════════════ FileSystem (A2) ═════════════════════════════
+  async fsList(req) {
+    const root = normalizeRelPath(req.path);
+    const findRoot = root === "" ? "." : shellQuote2(root);
+    const depthArg = Math.max(1, req.depth);
+    const hidden = req.includeHidden ? "" : ` -not -path '*/.*'`;
+    const gnuFind = `find ${findRoot} -mindepth 1 -maxdepth ${depthArg}${hidden} -printf '%y\\t%s\\t%T@\\t%m\\t%p\\0' 2>/dev/null`;
+    let { stdout } = await this.run({ cmd: `bash -lc ${shellQuote2(gnuFind)}`, workdir: this.workspaceRoot || void 0 });
+    if (!stdout) {
+      const portableFind = [
+        `find ${findRoot} -mindepth 1 -maxdepth ${depthArg}${hidden} -print0 2>/dev/null | while IFS= read -r -d '' p; do`,
+        `if [ -d "$p" ]; then t=d; size=0; elif [ -f "$p" ]; then t=f; size=$(wc -c < "$p" | tr -d ' '); elif [ -L "$p" ]; then t=l; size=0; else t=o; size=0; fi;`,
+        `mtime=$(date -r "$p" +%s 2>/dev/null || stat -c %Y "$p" 2>/dev/null || echo 0);`,
+        `mode=$(stat -f %Lp "$p" 2>/dev/null || stat -c %a "$p" 2>/dev/null || echo 0);`,
+        `printf '%s\\t%s\\t%s\\t%s\\t%s\\0' "$t" "$size" "$mtime" "$mode" "$p";`,
+        `done`
+      ].join(" ");
+      ({ stdout } = await this.run({ cmd: `bash -lc ${shellQuote2(portableFind)}`, workdir: this.workspaceRoot || void 0 }));
+    }
+    const entries = stdout.split(NUL).filter((s) => s.length > 0);
+    const rootNode = {
+      name: basename(root) || (root === "" ? "" : root),
+      path: root,
+      type: "dir",
+      sizeBytes: null,
+      mtimeMs: null,
+      mode: null,
+      children: [],
+      truncated: false
+    };
+    const byPath = /* @__PURE__ */ new Map();
+    byPath.set(root, rootNode);
+    let count = 0;
+    let truncated = false;
+    for (const entry of entries) {
+      if (count >= req.maxEntries) {
+        truncated = true;
+        break;
+      }
+      const parts = entry.split("	");
+      if (parts.length < 5) continue;
+      const [typeChar, sizeStr, mtimeStr, modeStr, ...pathParts] = parts;
+      const rawPath = pathParts.join("	");
+      const relPath = stripDotSlash(rawPath, root);
+      const node = {
+        name: basename(relPath),
+        path: relPath,
+        type: findTypeToNode(typeChar ?? ""),
+        sizeBytes: typeChar === "d" ? null : safeInt(sizeStr),
+        mtimeMs: mtimeToMs(mtimeStr),
+        mode: safeOctal(modeStr),
+        ...typeChar === "d" ? { children: [] } : {},
+        truncated: false
+      };
+      byPath.set(relPath, node);
+      count++;
+    }
+    for (const [path, node] of byPath) {
+      if (path === root) continue;
+      const parentPath = dirnameRel(path, root);
+      const parent = byPath.get(parentPath) ?? rootNode;
+      (parent.children ??= []).push(node);
+    }
+    sortTree(rootNode);
+    return { root: rootNode, revision: this.revision, truncated };
+  }
+  async fsRead(req) {
+    const path = assertSafeRelPath(req.path);
+    if (!this.session.readFile) {
+      return await this.fsReadViaExec(path, req);
+    }
+    let raw;
+    try {
+      raw = await this.session.readFile({ path: this.joinRoot(path), maxBytes: req.maxBytes, ...this.runAs ? { runAs: this.runAs } : {} });
+    } catch (error) {
+      if (isWorkspaceEscapeError(error)) {
+        return await this.fsReadViaExec(path, req);
+      }
+      throw new ChannelANotFoundError(`file not found: ${path} (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const bytes = typeof raw === "string" ? Buffer.from(raw, "utf8") : Buffer.from(raw);
+    return this.shapeRead(path, bytes, req);
+  }
+  /** Read a file by base64-ing it through exec. Binary-safe and — crucially —
+   *  NOT subject to the provider's native-readFile workspace-escape validation,
+   *  so it can render a symlink whose target lives outside /workspace (the link
+   *  node itself is in-workspace). `base64 <path>` follows the symlink. */
+  async fsReadViaExec(path, req) {
+    const abs = this.joinRoot(path);
+    const { stdout, exitCode } = await this.run({ cmd: `base64 ${shellQuote2(abs)} 2>/dev/null | head -c ${Math.ceil(req.maxBytes * 1.4)}` });
+    if (exitCode !== null && exitCode !== 0 && stdout === "") {
+      throw new ChannelANotFoundError(`file not found: ${path}`);
+    }
+    const bytes = Buffer.from(stdout.replace(/\n/g, ""), "base64");
+    return this.shapeRead(path, bytes, req);
+  }
+  shapeRead(path, bytes, req) {
+    const truncated = bytes.byteLength >= req.maxBytes;
+    const isBinary = sniffBinary(bytes);
+    const encoding = req.encoding === "base64" || isBinary ? "base64" : "utf8";
+    const content = encoding === "base64" ? bytes.toString("base64") : bytes.toString("utf8");
+    return {
+      path,
+      encoding,
+      content,
+      sizeBytes: bytes.byteLength,
+      truncated,
+      isBinary,
+      revision: this.revision
+    };
+  }
+  async fsWrite(req) {
+    const path = assertSafeRelPath(req.path);
+    const abs = this.joinRoot(path);
+    const bytes = req.encoding === "base64" ? Buffer.from(req.content, "base64") : Buffer.from(req.content, "utf8");
+    if (!req.overwrite) {
+      const { exitCode: exitCode2 } = await this.run({ cmd: `test -e ${shellQuote2(abs)}` });
+      if (exitCode2 === 0) {
+        throw new ChannelAConflictError(`path exists and overwrite is false: ${path}`);
+      }
+    }
+    if (req.createParents) {
+      const dir = dirnameAbs(abs);
+      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote2(dir)}` });
+    }
+    const b64 = bytes.toString("base64");
+    const { exitCode, stderr } = await this.run({
+      cmd: `printf %s ${shellQuote2(b64)} | base64 -d > ${shellQuote2(abs)}`
+    });
+    if (exitCode !== null && exitCode !== 0) {
+      if (req.encoding !== "base64" && this.session.createEditor) {
+        const ok2 = await this.tryEditorWrite(abs, req.content);
+        if (!ok2) throw new ChannelAValidationError(`failed to write ${path}: ${stderr || `exit ${exitCode}`}`);
+      } else {
+        throw new ChannelAValidationError(`failed to write ${path}: ${stderr || `exit ${exitCode}`}`);
+      }
+    }
+    this.revision++;
+    await this.emitFsChanged([{ path, kind: "modified", isDir: false, sizeBytes: bytes.byteLength }], "write");
+    return { path, sizeBytes: bytes.byteLength, revision: this.revision };
+  }
+  async tryEditorWrite(absPath, content) {
+    const editor = this.session.createEditor?.(this.runAs);
+    if (!editor?.createFile) return false;
+    try {
+      const diff = content.split("\n").map((line) => `+${line}`).join("\n");
+      await editor.createFile({ type: "create_file", path: absPath, diff });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  async fsDelete(req) {
+    const path = assertSafeRelPath(req.path);
+    const abs = this.joinRoot(path);
+    const flag = req.recursive ? "-rf" : "-f";
+    const { exitCode, stderr } = await this.run({ cmd: `rm ${flag} ${shellQuote2(abs)}` });
+    if (exitCode !== null && exitCode !== 0) {
+      throw new ChannelAValidationError(`failed to delete ${path}: ${stderr || `exit ${exitCode}`}`);
+    }
+    this.revision++;
+    await this.emitFsChanged([{ path, kind: "deleted", isDir: false, sizeBytes: null }], "write");
+    return { revision: this.revision };
+  }
+  async fsMove(req) {
+    const path = assertSafeRelPath(req.path);
+    const newPath = assertSafeRelPath(req.newPath);
+    const abs = this.joinRoot(path);
+    const newAbs = this.joinRoot(newPath);
+    if (!req.overwrite) {
+      const { exitCode: exitCode2 } = await this.run({ cmd: `test -e ${shellQuote2(newAbs)}` });
+      if (exitCode2 === 0) {
+        throw new ChannelAConflictError(`destination exists and overwrite is false: ${newPath}`);
+      }
+    }
+    if (req.createParents) {
+      const dir = dirnameAbs(newAbs);
+      if (dir) await this.run({ cmd: `mkdir -p ${shellQuote2(dir)}` });
+    }
+    const flag = req.overwrite ? "-f " : "";
+    const { exitCode, stderr } = await this.run({
+      cmd: `mv ${flag}${shellQuote2(abs)} ${shellQuote2(newAbs)}`
+    });
+    if (exitCode !== null && exitCode !== 0) {
+      throw new ChannelAValidationError(`failed to move ${path} -> ${newPath}: ${stderr || `exit ${exitCode}`}`);
+    }
+    this.revision++;
+    await this.emitFsChanged(
+      [
+        { path, kind: "deleted", isDir: false, sizeBytes: null },
+        { path: newPath, kind: "created", isDir: false, sizeBytes: null }
+      ],
+      "write"
+    );
+    return { path, newPath, revision: this.revision };
+  }
+  async fsMkdir(req) {
+    const path = assertSafeRelPath(req.path);
+    const abs = this.joinRoot(path);
+    const flag = req.recursive ? "-p " : "";
+    const { exitCode, stderr } = await this.run({ cmd: `mkdir ${flag}${shellQuote2(abs)}` });
+    if (exitCode !== null && exitCode !== 0) {
+      throw new ChannelAValidationError(`failed to mkdir ${path}: ${stderr || `exit ${exitCode}`}`);
+    }
+    this.revision++;
+    await this.emitFsChanged([{ path, kind: "created", isDir: true, sizeBytes: null }], "write");
+    return { path, revision: this.revision };
+  }
+  // ════════════════════════════ Git (A2, read-only) ═════════════════════════
+  async gitStatus(req) {
+    const repo = this.repoWorkdir(req.path);
+    const inside = await this.run({ cmd: "git rev-parse --is-inside-work-tree 2>/dev/null", workdir: repo });
+    if (inside.stdout.trim() !== "true") {
+      return { isRepo: false, head: null, detached: false, upstream: null, ahead: 0, behind: 0, files: [], revision: this.revision };
+    }
+    const { stdout } = await this.run({ cmd: "git status --porcelain=v2 --branch -z", workdir: repo });
+    return { ...parsePorcelainV2(stdout), revision: this.revision };
+  }
+  async gitDiff(req) {
+    const repo = this.repoWorkdir(req.path);
+    const ctx = req.contextLines;
+    let range = "";
+    if (req.fromRef && req.toRef) range = `${shellQuote2(req.fromRef)} ${shellQuote2(req.toRef)}`;
+    else if (req.fromRef) range = `${shellQuote2(req.fromRef)}`;
+    else if (req.staged) range = "--cached";
+    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote2).join(" ")}` : "";
+    const numstat = await this.run({ cmd: `git -c core.quotePath=false diff --no-color -z --numstat ${range}${pathspec}`.trim(), workdir: repo });
+    const stats = parseNumstatZ(numstat.stdout);
+    const files = [];
+    for (const stat of stats) {
+      const target = stat.newPath;
+      const fileStatus = stat.binary ? "modified" : "modified";
+      if (stat.binary) {
+        files.push({
+          path: target,
+          oldPath: stat.oldPath,
+          status: fileStatus,
+          isBinary: true,
+          isImage: isImagePath(target),
+          additions: 0,
+          deletions: 0,
+          hunks: [],
+          truncated: false
+        });
+        continue;
+      }
+      const patch = await this.run({
+        cmd: `git -c core.quotePath=false diff --no-color -U${ctx} ${range} -- ${shellQuote2(target)}`.trim(),
+        workdir: repo
+      });
+      const oversized = Buffer.byteLength(patch.stdout, "utf8") > req.maxBytesPerFile;
+      const parsed = oversized ? { hunks: [], status: "modified" } : parseUnifiedPatch(patch.stdout);
+      files.push({
+        path: target,
+        oldPath: stat.oldPath,
+        status: parsed.status,
+        isBinary: false,
+        isImage: isImagePath(target),
+        additions: stat.additions,
+        deletions: stat.deletions,
+        hunks: parsed.hunks,
+        truncated: oversized
+      });
+    }
+    return { files, revision: this.revision };
+  }
+  async gitLog(req) {
+    const repo = this.repoWorkdir(req.path);
+    const fmt = `%H${US}%h${US}%P${US}%an${US}%ae${US}%at${US}%cn${US}%ce${US}%ct${US}%s${US}%b${RS}`;
+    const pathspec = req.pathspec.length ? ` -- ${req.pathspec.map(shellQuote2).join(" ")}` : "";
+    const { stdout, exitCode } = await this.run({
+      cmd: `git log --format=${shellQuote2(fmt)} -n${req.maxCount + 1} --skip=${req.skip} ${shellQuote2(req.ref)}${pathspec}`,
+      workdir: repo
+    });
+    if (exitCode !== null && exitCode !== 0) {
+      return { commits: [], hasMore: false };
+    }
+    const records = stdout.split(RS).map((r) => r.replace(/^\n/, "")).filter((r) => r.trim().length > 0);
+    const commits = [];
+    for (const rec of records.slice(0, req.maxCount)) {
+      const f = rec.split(US);
+      if (f.length < 11) continue;
+      commits.push({
+        sha: f[0],
+        shortSha: f[1],
+        parents: (f[2] ?? "").trim() ? f[2].trim().split(" ") : [],
+        author: { name: f[3], email: f[4], timestamp: safeInt(f[5]) ?? 0 },
+        committer: { name: f[6], email: f[7], timestamp: safeInt(f[8]) ?? 0 },
+        subject: f[9],
+        body: f.slice(10).join(US),
+        refs: []
+      });
+    }
+    return { commits, hasMore: records.length > req.maxCount };
+  }
+  async gitShow(req) {
+    const repo = this.repoWorkdir(req.path);
+    if (req.filePath) {
+      const { stdout, exitCode } = await this.run({
+        cmd: `git cat-file blob ${shellQuote2(`${req.ref}:${req.filePath}`)} 2>/dev/null | base64`,
+        workdir: repo
+      });
+      if (exitCode !== null && exitCode !== 0 && stdout.trim() === "") {
+        throw new ChannelANotFoundError(`blob not found: ${req.ref}:${req.filePath}`);
+      }
+      const bytes = Buffer.from(stdout.replace(/\n/g, ""), "base64");
+      const truncated = bytes.byteLength > req.maxBytesPerFile;
+      const clamped = truncated ? bytes.subarray(0, req.maxBytesPerFile) : bytes;
+      const isBinary = sniffBinary(clamped);
+      const encoding = req.encoding === "base64" || isBinary ? "base64" : "utf8";
+      return {
+        commit: null,
+        files: [],
+        blob: { content: encoding === "base64" ? clamped.toString("base64") : clamped.toString("utf8"), encoding, sizeBytes: clamped.byteLength, truncated },
+        revision: this.revision
+      };
+    }
+    const log = await this.gitLog({ path: req.path, ref: req.ref, maxCount: 1, skip: 0, pathspec: [] });
+    const commit = log.commits[0] ?? null;
+    const diff = await this.gitDiff({ path: req.path, staged: false, fromRef: `${req.ref}^`, toRef: req.ref, pathspec: [], contextLines: 3, maxBytesPerFile: req.maxBytesPerFile });
+    return { commit, files: diff.files, blob: null, revision: this.revision };
+  }
+  /** Detect repo roots within the workspace (for the Git.repos capability). */
+  async detectRepos() {
+    try {
+      const { stdout } = await this.run({ cmd: `find . -maxdepth 3 -name .git -type d 2>/dev/null`, workdir: this.workspaceRoot || void 0 });
+      return stdout.split("\n").map((l) => l.trim()).filter(Boolean).map((g) => dirnameAbs(stripDotSlash(g, "")) || "");
+    } catch {
+      return [];
+    }
+  }
+  // ════════════════════════ Terminal exec + PTY (A2) ════════════════════════
+  /** Run a bounded command, return buffered stdout/stderr + exit code inline. The
+   *  long-running tail (when the process hasn't exited within timeoutMs) keeps
+   *  running in-box; if emitStream is set the buffered output is also published as
+   *  the agent firehose so other viewers see it. */
+  async terminalExec(req) {
+    const r = await this.run({
+      cmd: req.command,
+      workdir: this.repoWorkdir(req.cwd),
+      yieldTimeMs: req.timeoutMs
+    });
+    const running = r.exitCode === null && typeof r.sessionId === "number";
+    if (req.emitStream && (r.stdout || r.stderr)) {
+      const events = [];
+      const commandId = crypto.randomUUID();
+      if (r.stdout) events.push({ type: "sandbox.command.output.delta", payload: { stream: "stdout", chunk: r.stdout, commandId, seq: 0 } });
+      if (r.stderr) events.push({ type: "sandbox.command.output.delta", payload: { stream: "stderr", chunk: r.stderr, commandId, seq: 1 } });
+      await this.emitEvents(events);
+    }
+    return {
+      stdout: r.stdout,
+      stderr: r.stderr,
+      exitCode: r.exitCode,
+      running,
+      wallTimeSeconds: r.wallTimeSeconds
+    };
+  }
+  /** Open an interactive PTY: exec the shell with tty:true, yielding the numeric
+   *  exec-session id the caller persists (ptyId<->execSessionId) so subsequent
+   *  writeStdin can drive it. Returns the supportsInput gate (false when the
+   *  backend has no writeStdin). The caller emits terminal.pty.started after it
+   *  persists the row. */
+  async ptyOpen(req, ptyId) {
+    const supportsInput = Boolean(this.session.supportsPty?.() && this.session.writeStdin);
+    const shell = req.shell ?? "/bin/bash";
+    const r = await this.run({
+      cmd: shell,
+      workdir: this.repoWorkdir(req.cwd),
+      tty: true,
+      login: true,
+      yieldTimeMs: 250
+    });
+    return {
+      response: { ptyId, streamVia: "sse-events", supportsInput },
+      execSessionId: typeof r.sessionId === "number" ? r.sessionId : null,
+      shell,
+      initialOutput: r.stdout
+    };
+  }
+  /** Drive an open PTY's stdin. Returns the drained output (the caller publishes
+   *  it as terminal.pty.output.delta). Throws ChannelAUnsupportedError when the
+   *  backend has no writeStdin. */
+  async ptyWrite(_req, execSessionId, data) {
+    if (!this.session.writeStdin) {
+      throw new ChannelAUnsupportedError("interactive terminal unsupported on this backend");
+    }
+    const out = await this.session.writeStdin({ sessionId: execSessionId, chars: data, yieldTimeMs: 250 });
+    if (isExecSessionLostBanner(out, execSessionId)) {
+      throw new ChannelAConflictError("pty session lost on the live box; reopen the terminal");
+    }
+    return stripExecBanner2(out);
+  }
+  /** Resize an open PTY (SIGWINCH via stty against the exec-session). The SDK has
+   *  no resize method; stty in the same tty session updates the geometry. */
+  async ptyResize(req, execSessionId) {
+    if (!this.session.writeStdin) return;
+    await this.session.writeStdin({ sessionId: execSessionId, chars: `stty cols ${req.cols} rows ${req.rows}
+`, yieldTimeMs: 50 });
+  }
+  /** Close an open PTY: write exit/EOF. The caller marks the row closed + emits
+   *  terminal.pty.exited. */
+  async ptyClose(_req, execSessionId) {
+    if (execSessionId !== null && this.session.writeStdin) {
+      try {
+        await this.session.writeStdin({ sessionId: execSessionId, chars: "", yieldTimeMs: 50 });
+      } catch {
+      }
+    }
+  }
+  // ──────────────────────────── helpers ──────────────────────────────────────
+  /** The current FS revision (for the caller to persist/seed). */
+  currentRevision() {
+    return this.revision;
+  }
+  joinRoot(rel) {
+    if (!this.workspaceRoot) return rel === "" ? "." : rel;
+    return rel === "" ? this.workspaceRoot : `${this.workspaceRoot}/${rel}`;
+  }
+  repoWorkdir(rel) {
+    const safe = normalizeRelPath(rel);
+    const joined = this.joinRoot(safe);
+    return joined === "." ? this.workspaceRoot || void 0 : joined;
+  }
+  async emitEvents(events) {
+    if (!this.emit || events.length === 0) return;
+    try {
+      await this.emit(events);
+    } catch {
+    }
+  }
+  async emitFsChanged(changes, source) {
+    const payload = { changes, source, revision: this.revision, leaseEpoch: this.leaseEpoch };
+    await this.emitEvents([{ type: "fs.changed", payload }]);
+  }
+  /** Re-probe git after a mutation and emit git.changed (best-effort, used by the
+   *  worker agent-turn side after FS-mutating tools). */
+  async emitGitChanged(repoPath, reason) {
+    try {
+      const status = await this.gitStatus({ path: repoPath });
+      const payload = {
+        head: status.head,
+        dirty: status.files.length > 0,
+        ahead: status.ahead,
+        behind: status.behind,
+        changedFileCount: status.files.length,
+        reason,
+        revision: this.revision,
+        leaseEpoch: this.leaseEpoch
+      };
+      await this.emitEvents([{ type: "git.changed", payload }]);
+    } catch {
+    }
+  }
+};
+function stripExecBanner2(raw) {
+  const marker = raw.indexOf("\nOutput:\n");
+  if (marker >= 0) return raw.slice(marker + "\nOutput:\n".length);
+  if (raw.startsWith("Output:\n")) return raw.slice("Output:\n".length);
+  return raw;
+}
+function isWorkspaceEscapeError(error) {
+  const msg = error instanceof Error ? error.message : String(error ?? "");
+  const lower = msg.toLowerCase();
+  return lower.includes("workspace escape") || lower.includes("remote validation") && lower.includes("escape");
+}
+function isExecSessionLostBanner(out, execSessionId) {
+  if (!out) return false;
+  const lower = out.toLowerCase();
+  if (!lower.includes("session not found")) return false;
+  return lower.includes(`session not found: ${execSessionId}`) || !/session not found:\s*\d+/.test(lower);
+}
+function parseExecBannerSessionId(raw) {
+  const outputIdx = raw.indexOf("\nOutput:\n");
+  const banner = outputIdx >= 0 ? raw.slice(0, outputIdx) : raw.startsWith("Output:\n") ? "" : raw;
+  const match = banner.match(/Process running with session ID (\d+)/);
+  if (!match) return null;
+  const n = Number.parseInt(match[1], 10);
+  return Number.isFinite(n) ? n : null;
+}
+function sniffBinary(bytes) {
+  const n = Math.min(bytes.byteLength, 8192);
+  for (let i = 0; i < n; i++) if (bytes[i] === 0) return true;
+  return false;
+}
+function normalizeRelPath(p) {
+  const trimmed = (p ?? "").replace(/^\/+/, "").replace(/\/+$/, "");
+  return trimmed;
+}
+function assertSafeRelPath(p) {
+  const norm = normalizeRelPath(p);
+  if (norm === "") throw new ChannelAValidationError("path is required");
+  if (p.startsWith("/")) throw new ChannelAValidationError(`absolute paths are not allowed: ${p}`);
+  if (norm.split("/").some((seg) => seg === "..")) throw new ChannelAValidationError(`path traversal is not allowed: ${p}`);
+  return norm;
+}
+function shellQuote2(s) {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+function basename(p) {
+  const parts = p.split("/").filter(Boolean);
+  return parts.length ? parts[parts.length - 1] : "";
+}
+function dirnameAbs(p) {
+  const idx = p.lastIndexOf("/");
+  return idx > 0 ? p.slice(0, idx) : "";
+}
+function dirnameRel(p, root) {
+  const idx = p.lastIndexOf("/");
+  if (idx < 0) return root;
+  return p.slice(0, idx);
+}
+function stripDotSlash(rawPath, root) {
+  let p = rawPath.startsWith("./") ? rawPath.slice(2) : rawPath;
+  p = p.replace(/^\/+/, "");
+  if (root && !p.startsWith(`${root}/`) && p !== root) {
+    return root ? `${root}/${p}` : p;
+  }
+  return p;
+}
+function findTypeToNode(t) {
+  if (t === "d") return "dir";
+  if (t === "f") return "file";
+  if (t === "l") return "symlink";
+  return "other";
+}
+function safeInt(s) {
+  if (s === void 0) return null;
+  const n = Number.parseInt(s, 10);
+  return Number.isFinite(n) ? n : null;
+}
+function safeOctal(s) {
+  if (s === void 0) return null;
+  const n = Number.parseInt(s, 8);
+  return Number.isFinite(n) ? n : null;
+}
+function mtimeToMs(s) {
+  if (s === void 0) return null;
+  const f = Number.parseFloat(s);
+  return Number.isFinite(f) ? Math.round(f * 1e3) : null;
+}
+function sortTree(node) {
+  if (!node.children) return;
+  node.children.sort((a, b) => {
+    if (a.type === "dir" && b.type !== "dir") return -1;
+    if (a.type !== "dir" && b.type === "dir") return 1;
+    return a.name.localeCompare(b.name);
+  });
+  for (const child of node.children) sortTree(child);
+}
+function isImagePath(p) {
+  return /\.(png|jpe?g|gif|webp|bmp|ico|svg|tiff?)$/i.test(p);
+}
+function parsePorcelainV2(z) {
+  const records = z.split(NUL);
+  let head = null;
+  let upstream = null;
+  let detached = false;
+  let ahead = 0;
+  let behind = 0;
+  const files = [];
+  for (let i = 0; i < records.length; i++) {
+    const rec = records[i];
+    if (rec === "") continue;
+    if (rec.startsWith("# branch.head ")) {
+      const v = rec.slice("# branch.head ".length);
+      if (v === "(detached)") {
+        detached = true;
+        head = null;
+      } else head = v;
+    } else if (rec.startsWith("# branch.upstream ")) {
+      upstream = rec.slice("# branch.upstream ".length);
+    } else if (rec.startsWith("# branch.ab ")) {
+      const m = rec.slice("# branch.ab ".length).match(/\+(\d+)\s+-(\d+)/);
+      if (m) {
+        ahead = Number(m[1]);
+        behind = Number(m[2]);
+      }
+    } else if (rec.startsWith("1 ")) {
+      const fields = rec.split(" ");
+      const xy = fields[1] ?? "..";
+      const path = fields.slice(8).join(" ");
+      files.push(statusFromXY(xy, path, null));
+    } else if (rec.startsWith("2 ")) {
+      const fields = rec.split(" ");
+      const xy = fields[1] ?? "..";
+      const path = fields.slice(9).join(" ");
+      const oldPath = records[i + 1] ?? null;
+      i++;
+      files.push(statusFromXY(xy, path, oldPath));
+    } else if (rec.startsWith("u ")) {
+      const fields = rec.split(" ");
+      const path = fields.slice(10).join(" ");
+      files.push({ path, oldPath: null, index: "conflicted", worktree: "conflicted", isConflicted: true });
+    } else if (rec.startsWith("? ")) {
+      files.push({ path: rec.slice(2), oldPath: null, index: null, worktree: "untracked", isConflicted: false });
+    } else if (rec.startsWith("! ")) {
+      files.push({ path: rec.slice(2), oldPath: null, index: null, worktree: "ignored", isConflicted: false });
+    }
+  }
+  return { isRepo: true, head, detached, upstream, ahead, behind, files };
+}
+function xyCode(c) {
+  switch (c) {
+    case "A":
+      return "added";
+    case "M":
+      return "modified";
+    case "D":
+      return "deleted";
+    case "R":
+      return "renamed";
+    case "C":
+      return "copied";
+    case "T":
+      return "typechange";
+    case "U":
+      return "conflicted";
+    case ".":
+      return null;
+    default:
+      return null;
+  }
+}
+function statusFromXY(xy, path, oldPath) {
+  const x = xy[0] ?? ".";
+  const y = xy[1] ?? ".";
+  return {
+    path,
+    oldPath,
+    index: xyCode(x),
+    worktree: xyCode(y),
+    isConflicted: x === "U" || y === "U"
+  };
+}
+function parseNumstatZ(z) {
+  const fields = z.split(NUL);
+  const out = [];
+  let i = 0;
+  while (i < fields.length) {
+    const head = fields[i];
+    if (head === "") {
+      i++;
+      continue;
+    }
+    const m = head.match(/^(\d+|-)\t(\d+|-)\t(.*)$/s);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const addStr = m[1];
+    const delStr = m[2];
+    const pathPart = m[3];
+    const binary = addStr === "-" && delStr === "-";
+    if (pathPart === "") {
+      const oldPath = fields[i + 1] ?? null;
+      const newPath = fields[i + 2] ?? "";
+      out.push({ additions: binary ? 0 : Number(addStr), deletions: binary ? 0 : Number(delStr), binary, oldPath, newPath });
+      i += 3;
+    } else {
+      out.push({ additions: binary ? 0 : Number(addStr), deletions: binary ? 0 : Number(delStr), binary, oldPath: null, newPath: pathPart });
+      i++;
+    }
+  }
+  return out;
+}
+function parseUnifiedPatch(patch) {
+  const lines = patch.split("\n");
+  const hunks = [];
+  let status = "modified";
+  let current = null;
+  let oldNo = 0;
+  let newNo = 0;
+  for (const line of lines) {
+    if (line.startsWith("new file mode")) status = "added";
+    else if (line.startsWith("deleted file mode")) status = "deleted";
+    else if (line.startsWith("rename from") || line.startsWith("rename to")) status = "renamed";
+    if (line.startsWith("@@")) {
+      const m = line.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(.*)$/);
+      if (m) {
+        const oldStart = Number(m[1]);
+        const oldLines = m[2] !== void 0 ? Number(m[2]) : 1;
+        const newStart = Number(m[3]);
+        const newLines = m[4] !== void 0 ? Number(m[4]) : 1;
+        current = { oldStart, oldLines, newStart, newLines, header: (m[5] ?? "").trim(), lines: [] };
+        hunks.push(current);
+        oldNo = oldStart;
+        newNo = newStart;
+      }
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("\\")) continue;
+    const marker = line[0];
+    const text = line.slice(1);
+    if (marker === "+") {
+      current.lines.push({ type: "add", oldNo: null, newNo, text });
+      newNo++;
+    } else if (marker === "-") {
+      current.lines.push({ type: "del", oldNo, newNo: null, text });
+      oldNo++;
+    } else if (marker === " ") {
+      current.lines.push({ type: "context", oldNo, newNo, text });
+      oldNo++;
+      newNo++;
+    }
+  }
+  return { hunks, status };
+}
+
+// src/sandbox/selfhosted/capabilities.ts
+var SELFHOSTED_RECONNECT_WINDOW_MS = 3e4;
+function selfhostedLiveness(input) {
+  const { enrollment } = input;
+  if (!enrollment || enrollment.status !== "active") {
+    return { state: "offline", consented: false, hasDisplay: false };
+  }
+  const consented = enrollment.exposure === "whole-machine" && enrollment.allowScreenControl;
+  const hasDisplay = enrollment.hasDisplay;
+  if (input.probeResponded) {
+    return { state: "online", consented, hasDisplay };
+  }
+  const now = (input.now ?? /* @__PURE__ */ new Date()).getTime();
+  const lastSeen = enrollment.lastSeenAt ? new Date(enrollment.lastSeenAt).getTime() : null;
+  if (lastSeen !== null && now - lastSeen <= SELFHOSTED_RECONNECT_WINDOW_MS) {
+    return { state: "reconnecting", consented, hasDisplay };
+  }
+  return { state: "offline", consented, hasDisplay };
+}
+async function negotiateSelfhostedCapabilities(input) {
+  const probeResponded = input.probeResponded ?? (input.session ? await input.session.ping() : false);
+  const liveness = selfhostedLiveness({
+    enrollment: input.enrollment,
+    probeResponded,
+    ...input.now ? { now: input.now } : {}
+  });
+  const baseLiveness = liveness.state === "online" ? "warm" : "cold";
+  const base = {
+    sessionId: input.sessionId,
+    backend: "selfhosted",
+    os: input.os ?? "linux",
+    liveness: baseLiveness,
+    leaseEpoch: input.leaseEpoch,
+    desktopEnabled: input.desktopEnabled ?? true,
+    terminalEnabled: input.terminalEnabled ?? true,
+    computerUseEnabled: input.computerUseEnabled ?? true,
+    ...input.desktopAcknowledged !== void 0 ? { desktopAcknowledged: input.desktopAcknowledged } : {},
+    ...input.shared !== void 0 ? { shared: input.shared } : {},
+    ...input.sharedSessionIds !== void 0 ? { sharedSessionIds: input.sharedSessionIds } : {},
+    ...input.now ? { now: input.now } : {}
+  };
+  const caps = negotiateCapabilities(base);
+  if (liveness.state !== "online") {
+    const reason = liveness.state === "offline" ? "agent_offline" : "agent_reconnecting";
+    return {
+      ...caps,
+      FileSystem: { ...caps.FileSystem, available: false, readOnly: true, reason },
+      Terminal: { ...caps.Terminal, transport: null, url: null, token: null, expiresAt: null, reason },
+      Git: { ...caps.Git, available: false, reason },
+      DesktopStream: {
+        ...caps.DesktopStream,
+        transport: null,
+        client: null,
+        mode: "read-only",
+        url: null,
+        token: null,
+        expiresAt: null,
+        requiresAcknowledgment: false,
+        acknowledged: false,
+        shared: false,
+        sharedSessionIds: [],
+        reason
+      },
+      Recording: { ...caps.Recording, available: false, modes: [], codecs: [], reason },
+      ComputerUse: { ...caps.ComputerUse, available: false, reason }
+    };
+  }
+  if (!liveness.hasDisplay) {
+    const reason = "display_unavailable";
+    return {
+      ...caps,
+      DesktopStream: caps.DesktopStream.transport !== null ? {
+        ...caps.DesktopStream,
+        transport: null,
+        client: null,
+        mode: "read-only",
+        url: null,
+        token: null,
+        expiresAt: null,
+        requiresAcknowledgment: false,
+        acknowledged: false,
+        shared: false,
+        sharedSessionIds: [],
+        reason
+      } : caps.DesktopStream,
+      Recording: caps.Recording.available ? { ...caps.Recording, available: false, modes: [], codecs: [], reason } : caps.Recording,
+      ComputerUse: caps.ComputerUse.available ? { ...caps.ComputerUse, available: false, reason } : caps.ComputerUse
+    };
+  }
+  if (!liveness.consented) {
+    return {
+      ...caps,
+      DesktopStream: caps.DesktopStream.transport !== null ? { ...caps.DesktopStream, mode: "read-only" } : caps.DesktopStream,
+      ComputerUse: caps.ComputerUse.available ? { ...caps.ComputerUse, available: false, reason: "consent_required" } : caps.ComputerUse
+    };
+  }
+  return caps;
+}
+
+// src/sandbox/selfhosted/testing.ts
+import {
+  ErrorCode as ErrorCode2,
+  FsEntryKind as FsEntryKind2
+} from "@opengeni/agent-proto";
+var encoder2 = new TextEncoder();
+var decoder2 = new TextDecoder();
+var MockAgentResponder = class {
+  online;
+  consented;
+  draining;
+  files = /* @__PURE__ */ new Map();
+  execHandler;
+  hostname;
+  /** Every request seen, for assertion (subject + decoded ControlRequest). */
+  requests = [];
+  constructor(opts = {}) {
+    this.online = opts.online ?? true;
+    this.consented = opts.consented ?? true;
+    this.draining = opts.draining ?? false;
+    this.hostname = opts.hostname ?? "mock-machine";
+    this.execHandler = opts.exec ?? ((req) => defaultEcho(req, this.hostname));
+    for (const [path, content] of Object.entries(opts.files ?? {})) {
+      this.files.set(normalize(path), typeof content === "string" ? encoder2.encode(content) : content);
+    }
+  }
+  /** Flip the responder offline mid-test (a deliberate stop / blip). */
+  setOnline(online) {
+    this.online = online;
+  }
+  /** Read a file the session wrote (test assertion helper). */
+  fileText(path) {
+    const bytes = this.files.get(normalize(path));
+    return bytes ? decoder2.decode(bytes) : void 0;
+  }
+  async request(subject, req, _opts) {
+    this.requests.push({ subject, req });
+    if (!this.online) {
+      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_AGENT_OFFLINE, "the enrolled agent is offline", false);
+    }
+    if (this.draining) {
+      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_DRAINING, "the agent is draining", true);
+    }
+    const op = req.op;
+    if (!op) {
+      return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_PROTOCOL, "empty op", false);
+    }
+    switch (op.$case) {
+      case "ping":
+        return ok(req.requestId, { $case: "ping", ping: { nonce: op.ping.nonce, agentMonotonicMs: "0" } });
+      case "exec": {
+        const res = await this.execHandler(op.exec);
+        return ok(req.requestId, { $case: "exec", exec: res });
+      }
+      case "fsRead": {
+        const bytes = this.files.get(normalize(op.fsRead.path));
+        if (!bytes) {
+          return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_NOT_FOUND, `no such file: ${op.fsRead.path}`, false);
+        }
+        const res = { content: bytes, totalSize: String(bytes.length) };
+        return ok(req.requestId, { $case: "fsRead", fsRead: res });
+      }
+      case "fsWrite": {
+        const path = normalize(op.fsWrite.path);
+        const next = op.fsWrite.append ? concat(this.files.get(path) ?? new Uint8Array(0), op.fsWrite.content) : op.fsWrite.content;
+        this.files.set(path, next);
+        const res = { bytesWritten: String(op.fsWrite.content.length) };
+        return ok(req.requestId, { $case: "fsWrite", fsWrite: res });
+      }
+      case "fsList": {
+        const prefix = normalize(op.fsList.path).replace(/\/?$/, "/");
+        const res = {
+          entries: [...this.files.keys()].filter((p) => p.startsWith(prefix)).map((p) => {
+            const bytes = this.files.get(p);
+            const rel = p.slice(prefix.length);
+            return {
+              name: rel.split("/").pop() ?? rel,
+              path: rel,
+              kind: FsEntryKind2.FS_ENTRY_KIND_FILE,
+              size: String(bytes.length),
+              modifiedMs: "0",
+              mode: 420
+            };
+          })
+        };
+        return ok(req.requestId, { $case: "fsList", fsList: res });
+      }
+      case "fsStat": {
+        const bytes = this.files.get(normalize(op.fsStat.path));
+        const res = bytes ? {
+          exists: true,
+          entry: {
+            name: normalize(op.fsStat.path).split("/").pop() ?? "",
+            path: op.fsStat.path,
+            kind: FsEntryKind2.FS_ENTRY_KIND_FILE,
+            size: String(bytes.length),
+            modifiedMs: "0",
+            mode: 420
+          }
+        } : { exists: false, entry: void 0 };
+        return ok(req.requestId, { $case: "fsStat", fsStat: res });
+      }
+      case "desktopEnsure": {
+        return ok(req.requestId, {
+          $case: "desktopEnsure",
+          desktopEnsure: {
+            channel: { channelId: "mock-desktop", workspaceId: "", agentId: "", kind: 1, port: 6080 },
+            display: { id: ":99", width: 1024, height: 768, virtual: true }
+          }
+        });
+      }
+      case "ptyOpen": {
+        return ok(req.requestId, {
+          $case: "ptyOpen",
+          ptyOpen: {
+            ptyId: "mock-pty",
+            channel: { channelId: "mock-pty", workspaceId: "", agentId: "", kind: 1, port: 7681 }
+          }
+        });
+      }
+      default:
+        return errorResponse(req.requestId, ErrorCode2.ERROR_CODE_UNSUPPORTED, `mock does not implement ${op.$case}`, false);
+    }
+  }
+};
+function defaultEcho(req, hostname) {
+  const joined = req.command.join(" ");
+  const stdout = /hostname|HOSTNAME/.test(joined) ? hostname : joined;
+  return {
+    exitCode: 0,
+    stdout: encoder2.encode(`${stdout}
+`),
+    stderr: new Uint8Array(0),
+    timedOut: false,
+    durationMs: "1"
+  };
+}
+function ok(requestId, result) {
+  return { requestId, error: void 0, result };
+}
+function errorResponse(requestId, code, message, retryable) {
+  const error = { code, message, retryable, detail: {} };
+  return { requestId, error, result: void 0 };
+}
+function normalize(path) {
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+function concat(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+
+// src/sandbox/routing/routing-session.ts
+var RoutingUnsupportedError = class extends Error {
+  name = "RoutingUnsupportedError";
+  constructor(op, kind) {
+    super(`the active sandbox (${kind}) does not support "${op}"`);
+  }
+};
+function isFenceError(error) {
+  if (!error || typeof error !== "object") {
+    return false;
+  }
+  if (error.fenced === true) {
+    return true;
+  }
+  const name = typeof error.name === "string" ? error.name : "";
+  const message = error instanceof Error ? error.message : String(error.message ?? "");
+  const haystack = `${name} ${message}`.toLowerCase();
+  return haystack.includes("fenced") || haystack.includes("epoch") && haystack.includes("super");
+}
+var RoutingSandboxSession = class {
+  deps;
+  maxFenceRetries;
+  // The per-epoch resolved-backend cache. Keyed by activeEpoch: a swap bumps the
+  // epoch, invalidating the cache so the NEXT op re-resolves the new backend.
+  cachedEpoch;
+  cached;
+  // The last-resolved backend, exposed via the `state` getter (a method-free read
+  // of the active backend's `state`). Updated on every resolve.
+  lastResolved;
+  // The native-desktop control-plane ops (self-hosted / macOS). Declared as OPTIONAL
+  // INSTANCE fields — NOT prototype methods — because their PRESENCE is the selection
+  // signal `isNativeDesktopSession` (sandbox-computer.ts) uses to pick the native vs
+  // exec-shelling Computer. If they were unconditional prototype methods, this proxy
+  // would ALWAYS duck-type as native — misclassifying a Modal-fronting proxy (whose
+  // real backend has no native surface) and driving CGEvent/screenshot ops at a box
+  // that cannot serve them. So the constructor assigns them ONLY when the
+  // construction-time default backend actually implements the native surface (below).
+  desktopInput;
+  screenshot;
+  constructor(deps) {
+    this.deps = deps;
+    this.maxFenceRetries = deps.maxFenceRetries ?? 3;
+    const def = deps.defaultResolved?.session;
+    if (typeof def?.desktopInput === "function" && typeof def?.screenshot === "function") {
+      this.desktopInput = (event) => this.dispatch("desktopInput", async (s) => {
+        if (!s.desktopInput) {
+          throw new RoutingUnsupportedError("desktopInput", this.cached?.kind ?? "unknown");
+        }
+        return s.desktopInput(event);
+      });
+      this.screenshot = () => this.dispatch("screenshot", async (s) => {
+        if (!s.screenshot) {
+          throw new RoutingUnsupportedError("screenshot", this.cached?.kind ?? "unknown");
+        }
+        return s.screenshot();
+      });
+    }
+  }
+  /**
+   * A method-free read of the active backend's `state` (best-effort: the last
+   * resolved backend, falling back to the default backend resolved at construction
+   * so this is non-empty BEFORE the first op). Consumers that read `session.state`
+   * (instanceId/decoration) get the active backend's state.
+   *
+   * CRITICAL: this returns the underlying backend's `state` OBJECT BY REFERENCE
+   * (never a fresh `{}` when a backend exists). The @openai/agents SDK both READS
+   * `session.state.manifest` and WRITES `session.state.manifest = nextManifest`
+   * (providedSessionManifest); returning the live object by reference means those
+   * property writes land on the real backend state and persist. Only when NO
+   * backend has been resolved yet (no default seeded, no op dispatched) do we
+   * return an empty object — and that path no longer occurs in the turn wiring,
+   * which always seeds `defaultResolved`.
+   */
+  get state() {
+    const backendState = (this.lastResolved ?? this.deps.defaultResolved)?.session.state;
+    return backendState ?? {};
+  }
+  /**
+   * Re-read the pointer and resolve the active backend, using the per-epoch cache.
+   * The cache is keyed by `activeEpoch`: if the epoch is unchanged we return the
+   * cached backend; if it moved (a swap) we re-resolve and update the cache. This
+   * is THE per-call re-read that makes a mid-turn swap land on the next op.
+   */
+  async resolve() {
+    const pointer = await this.deps.readPointer();
+    if (this.cachedEpoch === pointer.activeEpoch && this.cached) {
+      return this.cached;
+    }
+    const fromEpoch = this.cachedEpoch ?? pointer.activeEpoch;
+    const resolved = await this.deps.resolveActiveBackend(pointer);
+    this.cachedEpoch = pointer.activeEpoch;
+    this.cached = resolved;
+    this.lastResolved = resolved;
+    this.deps.onTransition?.({
+      type: this.cachedEpoch !== void 0 && fromEpoch !== pointer.activeEpoch ? "epoch-changed" : "resolved",
+      fromEpoch,
+      toEpoch: pointer.activeEpoch,
+      sandboxId: resolved.sandboxId,
+      kind: resolved.kind
+    });
+    return resolved;
+  }
+  /**
+   * Dispatch an op to the currently-active backend, retrying on a stale-epoch
+   * fence. The sequence per attempt:
+   *   1. re-read the pointer + resolve the active backend (cached by epoch),
+   *   2. run `fn(activeSession)`,
+   *   3. on a FENCE error (the pointer moved under us / the backend rejected a
+   *      stale epoch), INVALIDATE the cache and retry against the re-resolved
+   *      active sandbox — up to `maxFenceRetries`.
+   * A non-fence error propagates immediately (it is a real op failure, not a swap
+   * race).
+   */
+  async dispatch(op, fn) {
+    let attempt = 0;
+    let lastError;
+    while (attempt <= this.maxFenceRetries) {
+      const backend = await this.resolve();
+      try {
+        return await fn(backend.session);
+      } catch (error) {
+        if (!isFenceError(error)) {
+          throw error;
+        }
+        lastError = error;
+        this.cachedEpoch = void 0;
+        this.cached = void 0;
+        this.deps.onTransition?.({
+          type: "fenced-retry",
+          fromEpoch: backend.sandboxId === null ? 0 : 0,
+          toEpoch: 0,
+          sandboxId: backend.sandboxId,
+          kind: backend.kind
+        });
+        attempt += 1;
+      }
+    }
+    throw lastError ?? new Error(`routing op "${op}" exhausted fence retries`);
+  }
+  // ── The forwarded structural surface ──────────────────────────────────────
+  // Every method is PRESENT on the proxy (the SDK binds presence once) and
+  // dispatches to the active backend at call-time. A missing backend method
+  // degrades via the natural fallback or RoutingUnsupportedError.
+  async exec(args) {
+    return this.dispatch("exec", async (s) => {
+      if (s.exec) {
+        return s.exec(args);
+      }
+      if (s.execCommand) {
+        return s.execCommand(args);
+      }
+      throw new RoutingUnsupportedError("exec", this.cached?.kind ?? "unknown");
+    });
+  }
+  async execCommand(args) {
+    return this.dispatch("execCommand", async (s) => {
+      if (s.execCommand) {
+        return s.execCommand(args);
+      }
+      if (s.exec) {
+        const r = await s.exec(args);
+        return r.stdout ?? r.output ?? "";
+      }
+      throw new RoutingUnsupportedError("execCommand", this.cached?.kind ?? "unknown");
+    });
+  }
+  async writeStdin(args) {
+    return this.dispatch("writeStdin", async (s) => {
+      if (!s.writeStdin) {
+        throw new RoutingUnsupportedError("writeStdin", this.cached?.kind ?? "unknown");
+      }
+      return s.writeStdin(args);
+    });
+  }
+  async readFile(args) {
+    return this.dispatch("readFile", async (s) => {
+      if (!s.readFile) {
+        throw new RoutingUnsupportedError("readFile", this.cached?.kind ?? "unknown");
+      }
+      return s.readFile(args);
+    });
+  }
+  async writeFile(args) {
+    return this.dispatch("writeFile", async (s) => {
+      if (!s.writeFile) {
+        throw new RoutingUnsupportedError("writeFile", this.cached?.kind ?? "unknown");
+      }
+      return s.writeFile(args);
+    });
+  }
+  async listDir(args) {
+    return this.dispatch("listDir", async (s) => {
+      if (!s.listDir) {
+        throw new RoutingUnsupportedError("listDir", this.cached?.kind ?? "unknown");
+      }
+      return s.listDir(args);
+    });
+  }
+  async pathExists(path, runAs) {
+    return this.dispatch("pathExists", async (s) => {
+      if (!s.pathExists) {
+        throw new RoutingUnsupportedError("pathExists", this.cached?.kind ?? "unknown");
+      }
+      return s.pathExists(path, runAs);
+    });
+  }
+  async viewImage(args) {
+    return this.dispatch("viewImage", async (s) => {
+      if (!s.viewImage) {
+        throw new RoutingUnsupportedError("viewImage", this.cached?.kind ?? "unknown");
+      }
+      return s.viewImage(args);
+    });
+  }
+  async materializeEntry(args) {
+    return this.dispatch("materializeEntry", async (s) => {
+      if (!s.materializeEntry) {
+        throw new RoutingUnsupportedError("materializeEntry", this.cached?.kind ?? "unknown");
+      }
+      return s.materializeEntry(args);
+    });
+  }
+  /** PTY support reflects the LAST-resolved backend (a synchronous probe; the SDK
+   *  reads it to decide if the terminal is interactive). It cannot re-read the
+   *  pointer (synchronous), so it answers from the last resolve — coherent with
+   *  the resolve the surrounding op already performed. Defaults false before the
+   *  first resolve. */
+  supportsPty() {
+    const s = (this.lastResolved ?? this.deps.defaultResolved)?.session;
+    return Boolean(s?.supportsPty?.());
+  }
+  /** createEditor is a synchronous factory in the SDK surface; it binds to the
+   *  last-resolved backend's editor (or the default backend before the first op).
+   *  Returns undefined when the active backend has no editor (channel-a falls back
+   *  to its exec-based write path). */
+  createEditor(runAs) {
+    return (this.lastResolved ?? this.deps.defaultResolved)?.session.createEditor?.(runAs);
+  }
+  async resolveExposedPort(port) {
+    return this.dispatch("resolveExposedPort", async (s) => {
+      if (!s.resolveExposedPort) {
+        throw new RoutingUnsupportedError("resolveExposedPort", this.cached?.kind ?? "unknown");
+      }
+      return s.resolveExposedPort(port);
+    });
+  }
+  /** Serialize the active backend's session state. Used by the resume-by-id seam
+   *  to fold the live box onto the lease. Dispatches to the active backend. */
+  async serializeSessionState() {
+    return this.dispatch("serializeSessionState", async (s) => {
+      if (!s.serializeSessionState) {
+        return void 0;
+      }
+      return s.serializeSessionState();
+    });
+  }
+  /** Force a resolve (priming the proxy before the first op so `state`/`supportsPty`
+   *  read a real backend). Optional — every op resolves lazily anyway. */
+  async prime() {
+    return this.resolve();
+  }
+};
+
+// src/sandbox/routing/backend-resolver.ts
+var ActiveBackendUnresolvableError = class extends Error {
+  name = "ActiveBackendUnresolvableError";
+  constructor(message) {
+    super(message);
+  }
+};
+function makeActiveBackendResolver(deps) {
+  return async (pointer) => {
+    if (pointer.activeSandboxId === null) {
+      return { session: deps.defaultBackend, sandboxId: null, kind: deps.defaultKind };
+    }
+    if (deps.pinnedSelfhosted && pointer.activeSandboxId === deps.pinnedSelfhosted.sandboxId && pointer.activeEpoch === deps.pinnedSelfhosted.epoch) {
+      return { session: deps.pinnedSelfhosted.session, sandboxId: pointer.activeSandboxId, kind: "selfhosted" };
+    }
+    const sandbox = await deps.getSandbox(pointer.activeSandboxId);
+    if (!sandbox) {
+      throw new ActiveBackendUnresolvableError(
+        `active sandbox ${pointer.activeSandboxId} not found in workspace ${deps.workspaceId}`
+      );
+    }
+    if (sandbox.kind === "selfhosted") {
+      if (!sandbox.enrollmentId) {
+        throw new ActiveBackendUnresolvableError(
+          `selfhosted sandbox ${sandbox.id} has no enrollment (agent id) to address`
+        );
+      }
+      const { session } = await buildSelfhostedBackendSession({
+        workspaceId: deps.workspaceId,
+        relay: deps.relay,
+        controlRpcFactory: deps.controlRpcFactory,
+        agentId: sandbox.enrollmentId,
+        epoch: pointer.activeEpoch,
+        ...deps.selfhostedTimeoutMs !== void 0 ? { timeoutMs: deps.selfhostedTimeoutMs } : {},
+        // The turn's declared environment → the session's manifest.environment, so
+        // the SDK's per-turn manifest-env delta is empty (no "cannot change manifest
+        // environment variables" throw on a pin-to-vm turn).
+        ...deps.environment !== void 0 ? { environment: deps.environment } : {},
+        // The session's working directory (per-session pointer) → the path/cwd base
+        // for this selfhosted backend. Absent/empty ⇒ the default workspace_root.
+        ...pointer.workingDir ? { workingDir: pointer.workingDir } : {}
+      });
+      return { session, sandboxId: sandbox.id, kind: "selfhosted" };
+    }
+    if (sandbox.kind === "modal") {
+      if (!deps.establishModalTarget) {
+        throw new ActiveBackendUnresolvableError(
+          `modal swap target ${sandbox.id} cannot be established in this context (no establisher wired)`
+        );
+      }
+      const session = await deps.establishModalTarget(sandbox);
+      return { session, sandboxId: sandbox.id, kind: "modal" };
+    }
+    throw new ActiveBackendUnresolvableError(
+      `unsupported swap target kind "${sandbox.kind}" for sandbox ${sandbox.id}`
+    );
+  };
+}
+
+// src/sandbox/index.ts
+function createSandboxClient(settings, environment = collectSandboxEnvironment(settings)) {
+  return createSandboxClientForBackend(settings.sandboxBackend, settings, environment);
+}
+function createSandboxClientForBackend(backend, settings, environment = collectSandboxEnvironment(settings)) {
+  const registration = PROVIDER_REGISTRY[backend];
+  if (!registration) {
+    throw new SandboxConfigError(backend, `Unknown sandbox backend "${backend}"`);
+  }
+  if (registration.backend === "none") {
+    return void 0;
+  }
+  registration.validateCredentials(settings);
+  const exposedPorts = parseExposedPorts(settings.dockerExposedPorts);
+  const desktop = registration.descriptor.capabilities.DesktopStream;
+  if (desktop.available && settings.sandboxDesktopEnabled && !registration.descriptor.portExposure.supportsOnDemandPorts && !exposedPorts.includes(DESKTOP_STREAM_PORT7)) {
+    exposedPorts.push(DESKTOP_STREAM_PORT7);
+  }
+  if (desktop.available && settings.sandboxDesktopEnabled && !registration.descriptor.portExposure.supportsOnDemandPorts && !exposedPorts.includes(TERMINAL_STREAM_PORT2)) {
+    exposedPorts.push(TERMINAL_STREAM_PORT2);
+  }
+  const raw = registration.build({ settings, environment, exposedPorts });
+  return registration.backend === "docker" ? withDockerNetwork(raw, settings.dockerNetwork) : raw;
+}
+function withDockerNetwork(client, network) {
+  const trimmed = network?.trim();
+  if (!trimmed) {
+    return client;
+  }
+  const wrapSession = async (session) => {
+    const containerId = session.state?.containerId;
+    if (typeof containerId === "string" && containerId.length > 0) {
+      await connectDockerNetwork(trimmed, containerId);
+    }
+    return session;
+  };
+  return {
+    backendId: client.backendId,
+    ...client.supportsDefaultOptions !== void 0 ? { supportsDefaultOptions: client.supportsDefaultOptions } : {},
+    ...client.create ? { create: async (...args) => await wrapSession(await client.create(...args)) } : {},
+    ...client.resume ? { resume: async (state) => await wrapSession(await client.resume(state)) } : {},
+    ...client.delete ? { delete: async (state) => await client.delete(state) } : {},
+    ...client.serializeSessionState ? { serializeSessionState: async (state, options) => await client.serializeSessionState(state, options) } : {},
+    ...client.canPersistOwnedSessionState ? { canPersistOwnedSessionState: async (state) => await client.canPersistOwnedSessionState(state) } : {},
+    ...client.canReusePreservedOwnedSession ? { canReusePreservedOwnedSession: async (state) => await client.canReusePreservedOwnedSession(state) } : {},
+    ...client.deserializeSessionState ? { deserializeSessionState: async (state) => await client.deserializeSessionState(state) } : {}
+  };
+}
+async function connectDockerNetwork(network, containerId) {
+  const result = Bun.spawnSync(["docker", "network", "connect", network, containerId], {
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (result.exitCode === 0) {
+    return;
+  }
+  const stderr = new TextDecoder().decode(result.stderr);
+  if (stderr.includes("already exists")) {
+    return;
+  }
+  throw new Error(`Failed to connect Docker sandbox container to network ${network}: ${stderr.trim()}`);
+}
+function sandboxStateEntryFromRunState(state) {
+  const sandboxState = state?._sandbox;
+  if (!sandboxState) {
+    return null;
+  }
+  const entry = sandboxState.sessionsByAgent?.[sandboxState.currentAgentKey] ?? (sandboxState.currentAgentKey && sandboxState.sessionState ? {
+    backendId: sandboxState.backendId,
+    currentAgentKey: sandboxState.currentAgentKey,
+    currentAgentName: sandboxState.currentAgentName,
+    sessionState: sandboxState.sessionState
+  } : null);
+  if (!entry || !entry.sessionState) {
+    return null;
+  }
+  return entry;
+}
+async function restoredSandboxSessionStateFromEntry(entry, client) {
+  if (!client || !entry || typeof entry !== "object" || !("sessionState" in entry)) {
+    return void 0;
+  }
+  if (entry.backendId && client.backendId !== entry.backendId) {
+    throw new Error("Stored sandbox envelope backend does not match the configured sandbox client");
+  }
+  return await deserializeSandboxSessionStateEnvelope(client, entry.sessionState);
+}
+function readWorkspaceArchiveFromEnvelopeSessionState(sessionState) {
+  if (!sessionState || typeof sessionState !== "object") {
+    return void 0;
+  }
+  const b64 = sessionState.workspaceArchive;
+  if (typeof b64 !== "string" || b64.length === 0) {
+    return void 0;
+  }
+  try {
+    return Uint8Array.from(Buffer.from(b64, "base64"));
+  } catch {
+    return void 0;
+  }
+}
+var MODAL_SNAPSHOT_REF_PREFIXES = [
+  "MODAL_SANDBOX_FS_SNAPSHOT_V1\n",
+  "MODAL_SANDBOX_DIR_SNAPSHOT_V1\n"
+];
+function decodeModalSnapshotId(archive) {
+  let text;
+  try {
+    text = new TextDecoder().decode(archive);
+  } catch {
+    return void 0;
+  }
+  for (const prefix of MODAL_SNAPSHOT_REF_PREFIXES) {
+    if (!text.startsWith(prefix)) {
+      continue;
+    }
+    try {
+      const payload = JSON.parse(text.slice(prefix.length));
+      return typeof payload.snapshot_id === "string" && payload.snapshot_id.length > 0 ? payload.snapshot_id : void 0;
+    } catch {
+      return void 0;
+    }
+  }
+  return void 0;
+}
+async function deletePriorPersistedSnapshot(session, priorArchiveBase64) {
+  if (!priorArchiveBase64) {
+    return void 0;
+  }
+  let bytes;
+  try {
+    bytes = Uint8Array.from(Buffer.from(priorArchiveBase64, "base64"));
+  } catch {
+    return void 0;
+  }
+  const snapshotId = decodeModalSnapshotId(bytes);
+  if (!snapshotId) {
+    return void 0;
+  }
+  const modal = session.modal;
+  const del = modal?.images?.delete;
+  if (typeof del !== "function") {
+    return void 0;
+  }
+  try {
+    await del.call(modal.images, snapshotId);
+    return snapshotId;
+  } catch {
+    return void 0;
+  }
+}
+async function deserializeSandboxSessionStateEnvelope(client, envelope) {
+  if (!envelope || typeof envelope !== "object") {
+    return void 0;
+  }
+  if (!client.deserializeSessionState) {
+    throw new Error("Sandbox client must implement deserializeSessionState() to resume RunState sandbox state");
+  }
+  const state = envelope;
+  return await client.deserializeSessionState({
+    ...state.providerState ?? {},
+    manifest: state.manifest,
+    ...state.snapshot !== void 0 ? { snapshot: state.snapshot } : {},
+    ...state.snapshotFingerprint !== void 0 ? { snapshotFingerprint: state.snapshotFingerprint } : {},
+    ...state.snapshotFingerprintVersion !== void 0 ? { snapshotFingerprintVersion: state.snapshotFingerprintVersion } : {},
+    workspaceReady: state.workspaceReady,
+    ...state.exposedPorts ? { exposedPorts: structuredClone(state.exposedPorts) } : {}
+  });
+}
+function isProviderSandboxNotFoundError(backendId, error) {
+  if (backendId === "selfhosted") {
+    return isSelfhostedProviderNotFoundError(error);
+  }
+  if (!error) {
+    return false;
+  }
+  const status = error.status ?? error.statusCode;
+  if (status === 404) {
+    return true;
+  }
+  const name = typeof error.name === "string" ? error.name : "";
+  const code = typeof error.code === "string" ? error.code : "";
+  const message = error instanceof Error ? error.message : typeof error === "string" ? error : String(error?.message ?? "");
+  const haystack = `${name} ${code} ${message}`.toLowerCase();
+  const goneMarkers = [
+    "not found",
+    "no longer running",
+    "no longer exists",
+    "does not exist",
+    "doesn't exist",
+    "has been terminated",
+    "was terminated",
+    "is terminated",
+    "sandbox terminated",
+    "notfound",
+    "sandbox_not_found",
+    "box no longer running"
+  ];
+  if (haystack.includes("already running") || haystack.includes("still running") || haystack.includes("already exists")) {
+    return false;
+  }
+  return goneMarkers.some((marker) => haystack.includes(marker));
+}
+function readInstanceId(session) {
+  const state = session.state ?? {};
+  const candidate = state.sandboxId ?? state.instanceId ?? state.id ?? state.hostId ?? state.containerId;
+  return typeof candidate === "string" && candidate.length > 0 ? candidate : "";
+}
+async function establishSandboxSessionFromEnvelope(settings, envelope, opts) {
+  const envelopeBackend = typeof envelope?.backendId === "string" ? envelope.backendId : void 0;
+  const backend = opts.backendOverride ?? envelopeBackend ?? settings.sandboxBackend;
+  const environment = opts.environment ?? collectSandboxEnvironment(settings);
+  const client = createSandboxClientForBackend(backend, settings, environment);
+  if (!client) {
+    throw new SandboxConfigError(backend, `Cannot establish a sandbox session for backend "${backend}" (no client; sandboxBackend=none?)`);
+  }
+  if (!client.create) {
+    throw new SandboxConfigError(backend, `Sandbox backend "${backend}" does not support create()`);
+  }
+  const createManifest = { environment };
+  const envelopeSessionState = envelope && typeof envelope === "object" ? envelope.sessionState : void 0;
+  const workspaceArchive = readWorkspaceArchiveFromEnvelopeSessionState(envelopeSessionState);
+  const coldRestore = async (resumeFallbackState) => {
+    const restored = await client.create({ manifest: createManifest });
+    if (workspaceArchive) {
+      const hydrate = restored.hydrateWorkspace;
+      if (typeof hydrate === "function") {
+        try {
+          await hydrate.call(restored, workspaceArchive);
+        } catch (hydrateError) {
+          const restoredState2 = restored.state;
+          const clientWithDelete = client;
+          if (typeof clientWithDelete.delete === "function" && restoredState2 !== void 0) {
+            try {
+              await clientWithDelete.delete(restoredState2);
+            } catch {
+            }
+          } else {
+            const sess = restored;
+            try {
+              await (sess.terminate ?? sess.close)?.();
+            } catch {
+            }
+          }
+          throw hydrateError;
+        }
+      }
+    }
+    const restoredState = restored.state;
+    return { client, session: restored, sessionState: restoredState ?? resumeFallbackState, instanceId: readInstanceId(restored), backendId: client.backendId };
+  };
+  const envelopeProviderState = envelopeSessionState && typeof envelopeSessionState === "object" ? envelopeSessionState.providerState : void 0;
+  const hasResumableInstance = Boolean(
+    envelopeProviderState && typeof envelopeProviderState === "object" && (envelopeProviderState.sandboxId || envelopeProviderState.instanceId || envelopeProviderState.id || envelopeProviderState.containerId)
+  );
+  if (hasResumableInstance && envelopeSessionState && client.resume && client.deserializeSessionState) {
+    let resumedState;
+    try {
+      resumedState = await deserializeSandboxSessionStateEnvelope(client, envelopeSessionState);
+    } catch (error) {
+      throw new SandboxConfigError(backend, `Failed to deserialize sandbox resume envelope for backend "${backend}": ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (resumedState !== void 0) {
+      try {
+        const session = await client.resume(resumedState);
+        return { client, session, sessionState: resumedState, instanceId: readInstanceId(session), backendId: client.backendId };
+      } catch (error) {
+        if (!isProviderSandboxNotFoundError(client.backendId, error)) {
+          throw error;
+        }
+        return await coldRestore(resumedState);
+      }
+    }
+  }
+  return await coldRestore();
+}
+async function serializeEstablishedSandboxEnvelope(established) {
+  const client = established.client;
+  if (!client || typeof client.serializeSessionState !== "function") {
+    return null;
+  }
+  if (established.sessionState === void 0 || established.sessionState === null) {
+    return null;
+  }
+  try {
+    const serialized = await client.serializeSessionState(established.sessionState);
+    const flat = serialized;
+    const manifest = flat.manifest;
+    const exposedPorts = flat.configuredExposedPorts ?? flat.exposedPorts;
+    const sessionState = {
+      providerState: flat,
+      ...manifest !== void 0 ? { manifest } : {},
+      ...exposedPorts !== void 0 ? { exposedPorts } : {},
+      workspaceReady: true
+    };
+    return { backendId: established.backendId, sessionState };
+  } catch {
+    return null;
+  }
+}
+
+export {
+  CAPABILITY_DESCRIPTORS,
+  DESKTOP_STREAM_PORT,
+  assertDescriptorRegistryInvariants,
+  SandboxConfigError,
+  SandboxProviderUnavailableError,
+  subjectFor,
+  SelfhostedControlError,
+  agentErrorToControlError,
+  offlineAgentError,
+  timeoutAgentError,
+  NatsControlRpc,
+  offlineControlResponse,
+  timeoutControlResponse,
+  setSelfhostedApplyDiff,
+  SELFHOSTED_DEFAULT_TIMEOUT_MS,
+  SELFHOSTED_RELAY_STREAM_PATH,
+  SelfhostedSession,
+  SelfhostedSandboxClient,
+  buildSelfhostedBackendSession,
+  isSelfhostedProviderNotFoundError,
+  PROVIDER_REGISTRY,
+  assertProviderRegistryInvariants,
+  selectBackend,
+  backendSupportsOs,
+  desktopCapableBackend,
+  negotiateCapabilities,
+  STREAM_TOKEN_DEFAULT_TTL_SECONDS,
+  mintStreamToken,
+  verifyStreamToken,
+  StreamTokenPayload2 as StreamTokenPayload,
+  STREAM_PORT,
+  DISPLAY_STACK_TIMEOUT_MS,
+  DEFAULT_DESKTOP_GEOMETRY,
+  DisplayStackError,
+  DisplayStackUnsupportedError,
+  buildDisplayStackScript,
+  ensureDisplayStack,
+  tearDownDisplayStack,
+  TERMINAL_STREAM_PORT,
+  TERMINAL_SERVER_TIMEOUT_MS,
+  TerminalServerError,
+  TerminalServerUnsupportedError,
+  buildTerminalServerScript,
+  ensureTerminalServer,
+  tearDownTerminalServer,
+  StreamPortUnavailableError,
+  buildStreamUrl,
+  exposeStreamPort,
+  contentTypeForCodec,
+  extForCodec,
+  RecordingUnavailableError,
+  RecordingError,
+  startRecording,
+  stopRecording,
+  readRecordingBytes,
+  deleteRecordingArtifacts,
+  recordingStorageKey,
+  ChannelAValidationError,
+  ChannelAConflictError,
+  ChannelANotFoundError,
+  ChannelAUnsupportedError,
+  SandboxChannelAService,
+  stripExecBanner2 as stripExecBanner,
+  isWorkspaceEscapeError,
+  isExecSessionLostBanner,
+  parseExecBannerSessionId,
+  assertSafeRelPath,
+  parsePorcelainV2,
+  parseNumstatZ,
+  parseUnifiedPatch,
+  SELFHOSTED_RECONNECT_WINDOW_MS,
+  selfhostedLiveness,
+  negotiateSelfhostedCapabilities,
+  MockAgentResponder,
+  RoutingUnsupportedError,
+  RoutingSandboxSession,
+  ActiveBackendUnresolvableError,
+  makeActiveBackendResolver,
+  createSandboxClient,
+  createSandboxClientForBackend,
+  sandboxStateEntryFromRunState,
+  restoredSandboxSessionStateFromEntry,
+  readWorkspaceArchiveFromEnvelopeSessionState,
+  decodeModalSnapshotId,
+  deletePriorPersistedSnapshot,
+  deserializeSandboxSessionStateEnvelope,
+  isProviderSandboxNotFoundError,
+  establishSandboxSessionFromEnvelope,
+  serializeEstablishedSandboxEnvelope,
+  collectSandboxEnvironment2 as collectSandboxEnvironment,
+  parseExposedPorts2 as parseExposedPorts
+};
+//# sourceMappingURL=chunk-2PO56VAL.js.map