@opengeni/runtime 0.2.0

package/src/sandbox/selfhosted/testing.ts

@@ -0,0 +1,230 @@
+// `MockAgentResponder` — an in-process `ControlRpc` test double standing in for
+// a real enrolled agent over NATS (the live NATS transport is M4). It answers
+// the op table (ping / exec / fs.read / fs.write / fs.list / fs.stat / git /
+// metrics / desktopEnsure) against an in-memory virtual filesystem + a pluggable
+// exec handler, so the `SelfhostedSession` surface and the mocked-NATS
+// integration tests run with zero broker.
+//
+// It is shipped from the runtime package (a testing util, not test-only-private)
+// because the API/worker integration suites (M4+) reuse it to drive
+// `withChannelA`/viewer/swap end-to-end without a real machine (dossier §16).
+
+import {
+  AgentError,
+  ControlRequest,
+  ControlResponse,
+  ErrorCode,
+  FsEntryKind,
+  type ExecRequest,
+  type ExecResponse,
+  type FsListResponse,
+  type FsReadResponse,
+  type FsStatResponse,
+  type FsWriteResponse,
+} from "@opengeni/agent-proto";
+import type { ControlRpc } from "./control-rpc";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+
+/** A pluggable exec handler — given an ExecRequest, return an ExecResponse (or
+ *  throw to surface a synthesized error). Defaults to a trivial echo. */
+export type MockExecHandler = (req: ExecRequest) => ExecResponse | Promise<ExecResponse>;
+
+export interface MockAgentResponderOptions {
+  /** Whether a responder exists at all. When false EVERY request yields an
+   *  AGENT_OFFLINE error (the "machine is offline" condition) — used to drive the
+   *  agent_offline capability + the isProviderSandboxNotFoundError test. */
+  online?: boolean;
+  /** Whether the agent has acknowledged whole-machine / screen-control consent.
+   *  When false, an op gated on consent yields CONSENT_REQUIRED. Defaults true. */
+  consented?: boolean;
+  /** Force the agent into a draining posture (every op → DRAINING). */
+  draining?: boolean;
+  /** Seed files (path → string|Uint8Array) into the virtual filesystem. */
+  files?: Record<string, string | Uint8Array>;
+  /** A custom exec handler; defaults to an echo of argv. */
+  exec?: MockExecHandler;
+  /** The hostname the mock reports (so PTY/exec `$HOSTNAME`-style asserts work). */
+  hostname?: string;
+}
+
+/**
+ * An in-process `ControlRpc` answering the agent op table against an in-memory
+ * virtual filesystem. Drive a `SelfhostedSession` with this to test exec /
+ * readFile / writeFile / list / stat round-trips without any NATS.
+ */
+export class MockAgentResponder implements ControlRpc {
+  private online: boolean;
+  private readonly consented: boolean;
+  private readonly draining: boolean;
+  private readonly files = new Map<string, Uint8Array>();
+  private readonly execHandler: MockExecHandler;
+  readonly hostname: string;
+
+  /** Every request seen, for assertion (subject + decoded ControlRequest). */
+  readonly requests: Array<{ subject: string; req: ControlRequest }> = [];
+
+  constructor(opts: MockAgentResponderOptions = {}) {
+    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" ? encoder.encode(content) : content);
+    }
+  }
+
+  /** Flip the responder offline mid-test (a deliberate stop / blip). */
+  setOnline(online: boolean): void {
+    this.online = online;
+  }
+
+  /** Read a file the session wrote (test assertion helper). */
+  fileText(path: string): string | undefined {
+    const bytes = this.files.get(normalize(path));
+    return bytes ? decoder.decode(bytes) : undefined;
+  }
+
+  async request(subject: string, req: ControlRequest, _opts: { timeoutMs: number }): Promise<ControlResponse> {
+    this.requests.push({ subject, req });
+    if (!this.online) {
+      return errorResponse(req.requestId, ErrorCode.ERROR_CODE_AGENT_OFFLINE, "the enrolled agent is offline", false);
+    }
+    if (this.draining) {
+      return errorResponse(req.requestId, ErrorCode.ERROR_CODE_DRAINING, "the agent is draining", true);
+    }
+    const op = req.op;
+    if (!op) {
+      return errorResponse(req.requestId, ErrorCode.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, ErrorCode.ERROR_CODE_NOT_FOUND, `no such file: ${op.fsRead.path}`, false);
+        }
+        const res: FsReadResponse = { 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: FsWriteResponse = { 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: FsListResponse = {
+          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: FsEntryKind.FS_ENTRY_KIND_FILE,
+                size: String(bytes.length),
+                modifiedMs: "0",
+                mode: 0o644,
+              };
+            }),
+        };
+        return ok(req.requestId, { $case: "fsList", fsList: res });
+      }
+      case "fsStat": {
+        const bytes = this.files.get(normalize(op.fsStat.path));
+        const res: FsStatResponse = bytes
+          ? {
+            exists: true,
+            entry: {
+              name: normalize(op.fsStat.path).split("/").pop() ?? "",
+              path: op.fsStat.path,
+              kind: FsEntryKind.FS_ENTRY_KIND_FILE,
+              size: String(bytes.length),
+              modifiedMs: "0",
+              mode: 0o644,
+            },
+          }
+          : { exists: false, entry: undefined };
+        return ok(req.requestId, { $case: "fsStat", fsStat: res });
+      }
+      case "desktopEnsure": {
+        // The desktop STREAM (view) is DISPLAY-gated, not consent-gated: the real
+        // agent registers the channel + captures frames regardless of screen-control
+        // consent (`register_desktop` in hub.rs sets `allow_input` from consent and
+        // the pump captures anyway) — only INPUT injection is gated. This stub has a
+        // (mock) display and does not model input injection, so desktopEnsure always
+        // succeeds; `consented` only affects the computer-use INPUT plane.
+        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": {
+        // The PTY plane is display-INDEPENDENT and has NO consent gate (unlike
+        // desktopEnsure) — a terminal works on a headless machine. Returns a PTY
+        // StreamChannel on the 7681 port.
+        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, ErrorCode.ERROR_CODE_UNSUPPORTED, `mock does not implement ${op.$case}`, false);
+    }
+  }
+}
+
+function defaultEcho(req: ExecRequest, hostname: string): ExecResponse {
+  // A trivial deterministic exec: echo the joined argv; if argv mentions
+  // HOSTNAME, emit the mock hostname so terminal-style asserts work.
+  const joined = req.command.join(" ");
+  const stdout = /hostname|HOSTNAME/.test(joined) ? hostname : joined;
+  return {
+    exitCode: 0,
+    stdout: encoder.encode(`${stdout}\n`),
+    stderr: new Uint8Array(0),
+    timedOut: false,
+    durationMs: "1",
+  };
+}
+
+function ok(requestId: string, result: NonNullable<ControlResponse["result"]>): ControlResponse {
+  return { requestId, error: undefined, result };
+}
+
+function errorResponse(requestId: string, code: ErrorCode, message: string, retryable: boolean): ControlResponse {
+  const error: AgentError = { code, message, retryable, detail: {} };
+  return { requestId, error, result: undefined };
+}
+
+function normalize(path: string): string {
+  // Collapse to a leading-slash absolute form for stable keys.
+  const trimmed = path.replace(/\/+$/, "");
+  return trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+}
+
+function concat(a: Uint8Array, b: Uint8Array): Uint8Array {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}

package/src/sandbox/stream-port.ts

@@ -0,0 +1,185 @@
+// @opengeni/runtime/sandbox — the pixel DATA PLANE: exposeStreamPort (P4.2).
+//
+// This is the heart of Channel B's data plane. exposeStreamPort resolves the
+// provider's scoped tunnel for the ONE exposed stream port (6080), assembles the
+// direct-to-provider WS URL (client → provider-tunnel direct; the pixel socket
+// never traverses OpenGeni), and mints the scoped OpenGeni stream token. It is a
+// plain function over a live, externally-owned `{session}` handle — NO Temporal,
+// NO worker RPC, NO actor. The API-direct handshake handler (apps/api) calls it
+// in-process on a freshly-resumed-by-id box and returns the result as the HTTP
+// response; the worker's per-turn resume path calls the same function when a turn
+// is the first to bring the box up. Both pull it from this single agent-loop-free
+// leaf (@opengeni/runtime/sandbox).
+//
+// THE TOKEN IS NOT A URL QUERY PARAM. The provider's own scoped tunnel URL
+// (Modal raw-TLS host:port, Daytona signed preview, Blaxel preview-token query)
+// carries the reach-the-port boundary; the OpenGeni stream token is RECORDED
+// against the viewer holder and is the in-box websockify edge boundary (P3/P5).
+// Per the master-spine ruling, exposeStreamPort returns the token alongside the
+// URL so the caller records it; it does NOT append it to `url`.
+
+import { DESKTOP_STREAM_PORT } from "@opengeni/contracts";
+import { mintStreamToken, STREAM_TOKEN_DEFAULT_TTL_SECONDS } from "./stream-token";
+
+/** The provider-resolved endpoint for an exposed port. Mirrors the SDK's
+ *  `ExposedPortEndpoint` (host/port/tls/query/...) WITHOUT importing the
+ *  agent-loop barrel — the leaf stays agent-loop-free. */
+export type ExposedPortEndpoint = {
+  host: string;
+  port: number;
+  tls?: boolean;
+  query?: string;
+  protocol?: string;
+  url?: string;
+  /** The URL path the socket connects on. Modal/Daytona/Blaxel serve the edge at
+   *  the root (`/`, the default); the selfhosted relay serves it at `/stream`
+   *  (M8b). When set, buildStreamUrl uses it instead of the root. */
+  path?: string;
+  [key: string]: unknown;
+};
+
+/** The structural slice of a provider session we need to resolve a tunnel. */
+type PortResolvableSession = {
+  resolveExposedPort?: (port: number) => Promise<ExposedPortEndpoint>;
+};
+
+/** Thrown when the provider cannot expose the stream port (no resolveExposedPort,
+ *  or the provider tunnel lookup failed). The caller degrades the desktop cell to
+ *  `transport:null` (a value, never a crash) — a headless-only provider or a
+ *  transient tunnel failure must not fail the whole handshake. */
+export class StreamPortUnavailableError extends Error {
+  constructor(message: string, readonly cause?: unknown) {
+    super(message);
+    this.name = "StreamPortUnavailableError";
+  }
+}
+
+export type ExposeStreamPortInput = {
+  workspaceId: string;
+  sessionId: string;
+  /** The sandbox_lease_holders viewer row id the token is scoped to. */
+  viewerId: string;
+  /** The live lease epoch — the fence the token is pinned to. */
+  leaseEpoch: number;
+  /** The HMAC secret for the scoped stream token (resolveStreamTokenSecret). */
+  streamTokenSecret: string;
+  /** The exposed stream port; defaults to 6080. */
+  port?: number;
+  /** Token TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+  ttlSeconds?: number;
+  /** The framebuffer geometry to echo back to the client. */
+  resolution?: [number, number];
+  /** Override the issue clock (tests). Seconds since the epoch. */
+  nowSeconds?: number;
+};
+
+export type ExposeStreamPortResult = {
+  /** The direct-to-provider WS URL the viewer connects to (provider-scoped; the
+   *  OpenGeni token is NOT appended). */
+  url: string;
+  /** The scoped OpenGeni stream token — recorded against the holder, NEVER a URL
+   *  query param. */
+  token: string;
+  /** ISO absolute expiry of the token (the rotation hot-swap window backstop). */
+  expiresAt: string;
+  /** The pixel transport the client speaks. */
+  transport: "vnc-ws";
+  /** The reference noVNC client the SDK helper mounts. */
+  client: "novnc";
+  resolution: [number, number];
+  leaseEpoch: number;
+};
+
+const DEFAULT_RESOLUTION: [number, number] = [1280, 800];
+
+/**
+ * Assemble the direct-to-provider WS URL from a resolved endpoint. The SDK's
+ * `urlForExposedPort(endpoint,'ws')` is the canonical tls-aware, IPv6-bracketing,
+ * provider-query-preserving assembler — we reimplement its exact logic here so
+ * the leaf stays agent-loop-free (the helper lives behind the bare
+ * `@openai/agents-core` root, which the import-discipline test forbids). The
+ * provider's own `endpoint.query` (Blaxel `bl_preview_token`, Daytona signed
+ * token) is preserved; the OpenGeni token is NOT appended (it is recorded against
+ * the holder + validated at the in-box websockify edge).
+ */
+export function buildStreamUrl(endpoint: ExposedPortEndpoint): string {
+  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;
+  // Bracket a bare IPv6 host (urlForExposedPort parity).
+  const host = endpoint.host.includes(":") && !endpoint.host.startsWith("[") ? `[${endpoint.host}]` : endpoint.host;
+  // The path: default the root `/` (Modal/Daytona/Blaxel edge), or the
+  // provider-supplied path (the selfhosted relay's `/stream` route, M8b). Always
+  // leading-slash-normalized.
+  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;
+}
+
+/**
+ * Resolve the provider's scoped tunnel for the stream port and mint the scoped
+ * OpenGeni stream token. Returns a coherent `{url, token, expiresAt, transport,
+ * client, resolution}` cell the caller records on the lease (data_plane_url) and
+ * returns in the DesktopStream handshake.
+ *
+ * Throws `StreamPortUnavailableError` when the provider session cannot resolve
+ * the port (no `resolveExposedPort`, or the tunnel lookup failed) — the caller
+ * maps this to a `transport:null` degradation (a value, never a crash).
+ */
+export async function exposeStreamPort(
+  session: unknown,
+  input: ExposeStreamPortInput,
+): Promise<ExposeStreamPortResult> {
+  const s = session as PortResolvableSession;
+  const port = input.port ?? DESKTOP_STREAM_PORT;
+  if (typeof s?.resolveExposedPort !== "function") {
+    throw new StreamPortUnavailableError(
+      "provider session cannot resolve exposed ports (no resolveExposedPort) — desktop stream unavailable",
+    );
+  }
+
+  let endpoint: ExposedPortEndpoint;
+  try {
+    // (I7/OD-7) per-provider URL re-resolution folds in here: a provider with a
+    // preview/signed token (Daytona/Blaxel) re-resolves its own short-TTL token
+    // on every call, so a rotation re-mints both planes' freshness in one place.
+    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() / 1000);
+  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) * 1000).toISOString(),
+    transport: "vnc-ws",
+    client: "novnc",
+    resolution: input.resolution ?? DEFAULT_RESOLUTION,
+    leaseEpoch: input.leaseEpoch,
+  };
+}

package/src/sandbox/stream-token.ts

@@ -0,0 +1,90 @@
+// @opengeni/runtime/sandbox — scoped stream-token mint/verify (P3.1).
+//
+// The agent-loop-free home for the scoped data-plane stream token used by the
+// desktop pixel plane (Channel B, master-spine §C.3 / crosscut PART 1.3). It is
+// a THIN wrapper over the contracts HMAC envelope (signStreamToken /
+// verifyStreamToken) — NOT a second crypto: it REUSES the exact base64Url +
+// hmacSha256 construction that backs signDelegatedAccessToken, with the distinct
+// `ogs_` prefix and the hard-narrow StreamTokenPayload claim set.
+//
+// It lives under @opengeni/runtime/sandbox so the API-direct control plane
+// (apps/api) can mint + verify stream tokens from the same single agent-loop-free
+// leaf it already pulls createSandboxClient / resume-by-id from.
+
+import {
+  DESKTOP_STREAM_PORT,
+  StreamTokenPayload,
+  signStreamToken,
+  verifyStreamToken as verifyStreamTokenEnvelope,
+  type StreamTokenPayload as StreamTokenPayloadType,
+} from "@opengeni/contracts";
+
+// The default stream-token TTL (seconds). The token is short-lived by design:
+// URL rotation is event-driven under the epoch fence (re-resolve recorded on the
+// lease), not on a keepalive clock — so the token never needs a long life.
+export const STREAM_TOKEN_DEFAULT_TTL_SECONDS = 120;
+
+export type MintStreamTokenInput = {
+  workspaceId: string;
+  sessionId: string;
+  /** The sandbox_lease_holders viewer row id. */
+  viewerId: string;
+  /** The epoch the token is fenced to. For a Modal box this is the live LEASE
+   *  epoch (re-minted on box rollover). For a SELFHOSTED relay stream (M8b) this is
+   *  the session's swap `active_epoch`: the relay tracks the highest epoch any
+   *  viewer presented per channel and REJECTS a token with a lower epoch, so a
+   *  viewer whose token predates a swap-away cannot reach the machine the session
+   *  swapped off of. One field, two fences — the relay/in-box edge reads it as the
+   *  stale-viewer floor either way. */
+  leaseEpoch: number;
+  /** v1 is always "view"; "control" is the never-granted raw-input plane. */
+  mode?: "view" | "control";
+  /** The exposed stream port (noVNC); defaults to 6080. */
+  port?: number;
+  /** TTL in seconds; defaults to STREAM_TOKEN_DEFAULT_TTL_SECONDS. */
+  ttlSeconds?: number;
+  /** Override the issue clock (tests). Seconds since the epoch. */
+  nowSeconds?: number;
+};
+
+/**
+ * Mint a scoped stream token for one viewer holder. Builds the hard-narrow
+ * StreamTokenPayload (the claim set the in-box edge / control plane validates)
+ * and signs it with the resolved stream-token secret via the contracts HMAC
+ * envelope (`ogs_` prefix). The token is RECORDED against the holder row by the
+ * caller and is NEVER appended to the data-plane URL as a query param.
+ */
+export async function mintStreamToken(secret: string, input: MintStreamTokenInput): Promise<string> {
+  const nowSeconds = input.nowSeconds ?? Math.floor(Date.now() / 1000);
+  const ttlSeconds = input.ttlSeconds ?? STREAM_TOKEN_DEFAULT_TTL_SECONDS;
+  const payload: StreamTokenPayloadType = StreamTokenPayload.parse({
+    workspaceId: input.workspaceId,
+    sessionId: input.sessionId,
+    viewerId: input.viewerId,
+    leaseEpoch: input.leaseEpoch,
+    mode: input.mode ?? "view",
+    port: input.port ?? DESKTOP_STREAM_PORT,
+    exp: nowSeconds + ttlSeconds,
+  });
+  return signStreamToken(secret, payload);
+}
+
+/**
+ * Verify a scoped stream token. Returns the parsed claims on success, or null on
+ * a bad prefix / malformed envelope / bad HMAC signature / schema-invalid claims
+ * / expiry. Re-exports the contracts verify; the leaf is the agent-loop-free
+ * import surface the API uses.
+ *
+ * The epoch fence (claim.leaseEpoch vs the LIVE lease epoch) and the
+ * workspace+session scope are enforced at USE by the caller against the live
+ * lease + route params — verify proves authenticity + freshness only.
+ */
+export async function verifyStreamToken(
+  secret: string,
+  token: string,
+  nowSeconds = Math.floor(Date.now() / 1000),
+): Promise<StreamTokenPayloadType | null> {
+  return verifyStreamTokenEnvelope(secret, token, nowSeconds);
+}
+
+export { StreamTokenPayload, type StreamTokenPayload as StreamTokenPayloadType } from "@opengeni/contracts";