@opengeni/runtime 3.2.2 → 3.4.0

package/src/sandbox/browser-control-client.ts

@@ -87,6 +87,7 @@ import {
 } from "./browser-control-server";
 import { parseExecResponseBanner } from "./exec-banner";
 import { controllerStreamRequest, parseControllerStreamResponse } from "./browser-control-stream";
+import type { BrowserControlHttpCall, BrowserControlHttpOutcome } from "./browser-control-http";
 import {
   buildStreamUrl,
   exposedPortAllowsHostFetch,
@@ -177,6 +178,8 @@ export type BrowserControlPlacementSession = {
   ensureBrowserControl?: (
     request: BrowserControlEnsureRequest,
   ) => Promise<BrowserControlEnsureResponse>;
+  /** Agent-native controller transport, addressed by authority scope. */
+  browserControlHttp?: (request: BrowserControlHttpCall) => Promise<BrowserControlHttpOutcome>;
   openBrowserFrames?: (
     request: BrowserFramesOpenRequest,
   ) => Promise<{ channel: StreamChannel; endpoint: ExposedPortEndpoint }>;
@@ -267,6 +270,8 @@ export type PlacementBrowserSessionReference = {
 
 export type PlacementBrowserSession = PlacementBrowserSessionReference & {
   observation: BrowserObservationValue;
+  /** The tab inventory at creation, when the controller reports it. */
+  targets?: BrowserTargetValue[];
 };
 
 export type PlacementComputerSessionReference = {
@@ -412,6 +417,73 @@ export type PlacementBrowserStateCaptureReceipt = PlacementBrowserSessionReferen
   };
 };
 
+/** The exact controller authority a preserved working copy was launched
+ * under; the controller refuses any other. */
+export type PlacementBrowserWorkingCopyAuthority = PlacementBrowserSessionReference & {
+  tokenGeneration: number;
+  controlToken: string;
+  viewToken: string;
+};
+
+export const BROWSER_WORKING_COPY_REFUSALS = [
+  "unsupported_platform",
+  "browser_running",
+  "working_copy_invalid",
+  "receipt_not_adoptable",
+  "authority_changed",
+  "process_state_unknown",
+  "adoption_not_needed",
+  "adoption_unresolved",
+] as const;
+export type PlacementBrowserWorkingCopyRefusal = (typeof BROWSER_WORKING_COPY_REFUSALS)[number];
+
+export const BROWSER_WORKING_COPY_ADOPTION_PHASES = [
+  "intent",
+  "copied",
+  "receipt",
+  "source_preserved",
+  "adopted",
+  "interrupted",
+  "failed",
+  "collision",
+  "reverting",
+  "reverted",
+] as const;
+export type PlacementBrowserWorkingCopyAdoptionPhase =
+  (typeof BROWSER_WORKING_COPY_ADOPTION_PHASES)[number];
+
+export type PlacementBrowserWorkingCopyAdoption = PlacementBrowserSessionReference & {
+  operationId: string;
+  manifestDigest: string;
+  phase: PlacementBrowserWorkingCopyAdoptionPhase;
+  failureCode: string | null;
+  /** Directories this adoption kept beside the browser's own, by name. */
+  retainedDirectories: string[];
+  createdAt: string;
+  updatedAt: string;
+};
+
+export type PlacementBrowserWorkingCopyInspection = PlacementBrowserSessionReference & {
+  platformSupported: boolean;
+  refusal: PlacementBrowserWorkingCopyRefusal | null;
+  /** Exact digest of the bytes an adoption would take; null when refused. */
+  manifest: { digest: string; entries: number; bytes: number; excluded: string[] } | null;
+  profileIdentityMatches: boolean;
+  /** false only when no process provably uses the profile. */
+  profileInUse: boolean | null;
+  receipt: {
+    operationId: string;
+    intent: "launch" | "suspend" | "retire" | "adopt";
+    state: string;
+    directoryLaunchAllowed: boolean;
+    authorityMatches: boolean;
+    /** True when this working copy was first launched from a saved checkpoint. */
+    launchedFromCheckpoint: boolean;
+    adoption: { operationId: string; manifestDigest: string } | null;
+  } | null;
+  activeAdoption: PlacementBrowserWorkingCopyAdoption | null;
+};
+
 export type ProvisionBrowserControlClientInput = {
   adminToken: string;
   adminTokenFile?: string;
@@ -649,6 +721,7 @@ export class BrowserControlClient {
     return {
       ...returnedReference,
       observation: BrowserObservation.parse(data.observation),
+      ...creationTargets(data.targets, returnedReference),
     };
   }
 
@@ -879,6 +952,103 @@ export class BrowserControlClient {
     return receipt;
   }
 
+  /** Read-only evidence about a preserved working copy whose controller
+   * memory was lost: the exact digest of its bytes and whether it can be
+   * adopted. Hashing a large profile can take minutes. */
+  async inspectWorkingCopy(
+    input: PlacementBrowserWorkingCopyAuthority,
+  ): Promise<PlacementBrowserWorkingCopyInspection> {
+    const reference = parseReference(input);
+    const data = await this.requestJson({
+      method: "POST",
+      path: `/v1/browser-sessions/${reference.browserSessionId}/working-copy/inspection`,
+      token: this.adminToken,
+      body: workingCopyAuthorityBody(reference, input),
+      timeoutMs: BROWSER_STATE_TRANSFER_TIMEOUT_MS,
+    });
+    return parseWorkingCopyInspection(data, reference);
+  }
+
+  /** Adopt the exact inspected bytes of a preserved working copy. A lost reply
+   * is checked with {@link workingCopyAdoption}. Sending the same operation id
+   * again never repeats a side effect: it only settles what that operation
+   * already did, under the authority that approved it. */
+  async adoptWorkingCopy(
+    input: PlacementBrowserWorkingCopyAuthority & { operationId: string; manifestDigest: string },
+  ): Promise<PlacementBrowserWorkingCopyAdoption> {
+    const reference = parseReference(input);
+    const operationId = requireUuid(input.operationId, "working copy adoption id");
+    const data = await this.requestJson({
+      method: "POST",
+      path: `/v1/browser-sessions/${reference.browserSessionId}/working-copy/adoptions`,
+      token: this.adminToken,
+      body: {
+        ...workingCopyAuthorityBody(reference, input),
+        operationId,
+        manifestDigest: sha256(input.manifestDigest, "working copy manifest digest"),
+      },
+      timeoutMs: BROWSER_STATE_TRANSFER_TIMEOUT_MS,
+    });
+    const adoption = parseWorkingCopyAdoption(data, reference, "current");
+    if (adoption.operationId !== operationId) {
+      throw new BrowserControlProtocolError("browser controller returned another adoption");
+    }
+    return adoption;
+  }
+
+  /** The recorded state of one adoption, read without changing it. */
+  async workingCopyAdoption(
+    reference: PlacementBrowserSessionReference,
+    operationId: string,
+  ): Promise<{ inFlight: boolean; adoption: PlacementBrowserWorkingCopyAdoption | null }> {
+    const binding = parseReference(reference);
+    const id = requireUuid(operationId, "working copy adoption id");
+    const data = await this.requestJson({
+      method: "GET",
+      path: `/v1/browser-sessions/${binding.browserSessionId}/working-copy/adoptions/${id}`,
+      token: this.adminToken,
+    });
+    if (!isRecord(data) || typeof data.inFlight !== "boolean") {
+      throw new BrowserControlProtocolError(
+        "browser controller returned malformed adoption status",
+      );
+    }
+    const adoption =
+      data.adoption === null ? null : parseWorkingCopyAdoption(data.adoption, binding, "recorded");
+    if (adoption && adoption.operationId !== id) {
+      throw new BrowserControlProtocolError("browser controller returned another adoption");
+    }
+    return { inFlight: data.inFlight, adoption };
+  }
+
+  /** Revert one unfinished adoption under the browser's current authority:
+   * its own directory goes back to the live path and the staged copy is
+   * kept. Retrying the same revert finishes one that stopped part way. */
+  async revertWorkingCopyAdoption(
+    input: PlacementBrowserWorkingCopyAuthority & { operationId: string },
+  ): Promise<{ inFlight: boolean; adoption: PlacementBrowserWorkingCopyAdoption | null }> {
+    const reference = parseReference(input);
+    const id = requireUuid(input.operationId, "working copy adoption id");
+    const data = await this.requestJson({
+      method: "POST",
+      path: `/v1/browser-sessions/${reference.browserSessionId}/working-copy/adoptions/${id}/revert`,
+      token: this.adminToken,
+      body: workingCopyAuthorityBody(reference, input),
+      timeoutMs: BROWSER_STATE_TRANSFER_TIMEOUT_MS,
+    });
+    if (!isRecord(data) || typeof data.inFlight !== "boolean") {
+      throw new BrowserControlProtocolError("browser controller returned malformed revert status");
+    }
+    const adoption =
+      data.adoption === null
+        ? null
+        : parseWorkingCopyAdoption(data.adoption, reference, "recorded");
+    if (adoption && adoption.operationId !== id) {
+      throw new BrowserControlProtocolError("browser controller returned another adoption");
+    }
+    return { inFlight: data.inFlight, adoption };
+  }
+
   sessionClient(input: {
     reference: PlacementBrowserSessionReference;
     controlToken: string;
@@ -1176,6 +1346,19 @@ export class BrowserControlClient {
       );
     }
 
+    const native = await this.requestNative(input, BROWSER_CONTROL_MAX_JSON_BYTES);
+    if (native) {
+      let text: string;
+      try {
+        text = new TextDecoder("utf-8", { fatal: true }).decode(native.body);
+      } catch (error) {
+        throw new BrowserControlProtocolError("browser controller response is not UTF-8", {
+          cause: error,
+        });
+      }
+      return parseEnvelope(text, native.status);
+    }
+
     if (
       this.session.execWithInput &&
       (input.body === undefined || Buffer.byteLength(JSON.stringify(input.body)) <= 32 * 1024)
@@ -1357,6 +1540,18 @@ export class BrowserControlClient {
       );
     }
 
+    const nativeFrame = await this.requestNative(
+      input,
+      input.surface === "browser" ? 24 * 1024 * 1024 : COMPUTER_SCREENSHOT_MAX_BYTES,
+    );
+    if (nativeFrame) {
+      if (nativeFrame.status < 200 || nativeFrame.status >= 300) {
+        parseEnvelope(new TextDecoder().decode(nativeFrame.body), nativeFrame.status);
+        throw new BrowserControlProtocolError("browser controller image response is invalid");
+      }
+      return controllerImageFrame(nativeFrame.body, nativeFrame.headers, input);
+    }
+
     if (this.session.execWithInput) {
       try {
         const response = await this.requestStream(
@@ -1512,8 +1707,69 @@ export class BrowserControlClient {
   }
 
   private async controllerPort(): Promise<number> {
+    if (!this.nativeAuthority || !this.session.ensureBrowserControl) return this.port;
+    return await this.ensureControllerPort(false);
+  }
+
+  /** The agent-native transport: one in-process loopback request on the
+   * Connected Machine, addressed by authority scope, with no process started.
+   * Null when the placement does not serve it; the caller then keeps its
+   * command transport. A controller that is not running receives nothing, so
+   * it is ensured and the request sent once more whatever its method. */
+  private async requestNative(
+    input: { method: string; path: string; token: string; body?: unknown; timeoutMs?: number },
+    maxResponseBytes: number,
+    retry = true,
+  ): Promise<{ status: number; headers: Map<string, string>; body: Uint8Array } | null> {
+    const authority = this.nativeAuthority;
+    if (!authority || !this.session.browserControlHttp || !this.session.ensureBrowserControl) {
+      return null;
+    }
+    const method = input.method;
+    if (method !== "GET" && method !== "POST" && method !== "PUT" && method !== "DELETE") {
+      throw new BrowserControlProtocolError("browser controller request method is invalid");
+    }
+    // Validates the path exactly as the command transport does.
+    localControllerUrl(this.port, input.path);
+    const body =
+      input.body === undefined ? undefined : new TextEncoder().encode(JSON.stringify(input.body));
+    if (body !== undefined && body.byteLength > BROWSER_CONTROL_MAX_JSON_BYTES) {
+      throw new RangeError("browser controller request body is too large");
+    }
+    let outcome: BrowserControlHttpOutcome;
+    try {
+      outcome = await this.session.browserControlHttp({
+        scopeId: authority.scopeId,
+        scopeGeneration: authority.scopeGeneration,
+        method,
+        path: input.path,
+        bearerToken: requireToken(input.token, "browser controller token"),
+        ...(body === undefined ? {} : { body }),
+        timeoutMs: boundedTimeout(input.timeoutMs ?? this.timeoutMs),
+        maxResponseBytes,
+      });
+    } catch (error) {
+      if (retry && method === "GET") {
+        await this.ensureControllerPort(true);
+        return await this.requestNative(input, maxResponseBytes, false);
+      }
+      throw new BrowserControlTransportError("browser controller request transport failed", {
+        cause: error,
+      });
+    }
+    if (outcome.kind === "unsupported") return null;
+    if (outcome.kind === "controller_absent") {
+      if (!retry) throw new BrowserControlTransportError("browser controller is not running");
+      await this.ensureControllerPort(true);
+      return await this.requestNative(input, maxResponseBytes, false);
+    }
+    return outcome;
+  }
+
+  private async ensureControllerPort(replace: boolean): Promise<number> {
     if (!this.nativeAuthority || !this.session.ensureBrowserControl) return this.port;
     const key = nativeControllerKey(this.nativeAuthority);
+    if (replace) nativeControllerPorts.delete(key);
     const cached = nativeControllerPorts.get(key);
     if (cached !== undefined) return cached;
     const ensured = await this.session.ensureBrowserControl({
@@ -2615,6 +2871,28 @@ function parseReference(value: unknown): PlacementBrowserSessionReference {
   };
 }
 
+/** A create's tab inventory is a convenience: an older controller omits it,
+ * and an inventory that does not validate, or that belongs to another
+ * binding, is dropped rather than failing a browser that did launch. */
+function creationTargets(
+  value: unknown,
+  reference: PlacementBrowserSessionReference,
+): { targets?: BrowserTargetValue[] } {
+  if (!Array.isArray(value) || value.length > 10_000) return {};
+  const targets: BrowserTargetValue[] = [];
+  for (const entry of value) {
+    const parsed = BrowserTarget.safeParse(entry);
+    if (
+      !parsed.success ||
+      parsed.data.browserSessionId !== reference.browserSessionId ||
+      parsed.data.controllerGeneration !== reference.controllerGeneration
+    )
+      return {};
+    targets.push(parsed.data);
+  }
+  return { targets };
+}
+
 function parseComputerReference(value: unknown): PlacementComputerSessionReference {
   if (!isRecord(value)) {
     throw new BrowserControlProtocolError("computer session binding is invalid");
@@ -2790,6 +3068,140 @@ function boundedProxyUrl(value: string): string {
   return url.toString();
 }
 
+function workingCopyAuthorityBody(
+  reference: PlacementBrowserSessionReference,
+  input: PlacementBrowserWorkingCopyAuthority,
+) {
+  return {
+    controllerGeneration: reference.controllerGeneration,
+    tokenGeneration: positiveSafeInteger(input.tokenGeneration, "token generation"),
+    controlToken: requireToken(input.controlToken, "control token"),
+    viewToken: requireToken(input.viewToken, "view token"),
+  };
+}
+
+/**
+ * An adoption record. `generation: "current"` (a new adoption) requires the
+ * record to belong to the requesting controller generation. `"recorded"`
+ * (status, revert, inspection) keeps the generation the adoption was recorded
+ * under: recovering an unfinished adoption after a controller restart means
+ * reading and reverting a record made by an earlier generation, under the
+ * browser's legitimate current control. The browser and operation always
+ * have to match exactly.
+ */
+function parseWorkingCopyAdoption(
+  value: unknown,
+  reference: PlacementBrowserSessionReference,
+  generation: "current" | "recorded",
+): PlacementBrowserWorkingCopyAdoption {
+  if (
+    !isRecord(value) ||
+    value.browserSessionId !== reference.browserSessionId ||
+    (generation === "current" && value.controllerGeneration !== reference.controllerGeneration) ||
+    !BROWSER_WORKING_COPY_ADOPTION_PHASES.includes(
+      value.phase as PlacementBrowserWorkingCopyAdoptionPhase,
+    ) ||
+    !(value.failureCode === null || typeof value.failureCode === "string") ||
+    !Array.isArray(value.retainedDirectories) ||
+    value.retainedDirectories.length > 64 ||
+    !value.retainedDirectories.every(
+      (name) => typeof name === "string" && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/u.test(name),
+    )
+  ) {
+    throw new BrowserControlProtocolError("browser controller returned a malformed adoption");
+  }
+  return {
+    browserSessionId: reference.browserSessionId,
+    controllerGeneration:
+      generation === "current"
+        ? reference.controllerGeneration
+        : requireGeneration(value.controllerGeneration),
+    operationId: requireUuid(value.operationId, "working copy adoption id"),
+    manifestDigest: sha256(value.manifestDigest, "working copy manifest digest"),
+    phase: value.phase as PlacementBrowserWorkingCopyAdoptionPhase,
+    failureCode:
+      value.failureCode === null ? null : requireOpaqueId(value.failureCode, "failure code"),
+    retainedDirectories: value.retainedDirectories as string[],
+    createdAt: timestamp(value.createdAt, "adoption created at"),
+    updatedAt: timestamp(value.updatedAt, "adoption updated at"),
+  };
+}
+
+function parseWorkingCopyInspection(
+  value: unknown,
+  reference: PlacementBrowserSessionReference,
+): PlacementBrowserWorkingCopyInspection {
+  if (
+    !isRecord(value) ||
+    value.browserSessionId !== reference.browserSessionId ||
+    value.controllerGeneration !== reference.controllerGeneration ||
+    typeof value.platformSupported !== "boolean" ||
+    typeof value.profileIdentityMatches !== "boolean" ||
+    !(value.profileInUse === null || typeof value.profileInUse === "boolean") ||
+    !(
+      value.refusal === null ||
+      BROWSER_WORKING_COPY_REFUSALS.includes(value.refusal as PlacementBrowserWorkingCopyRefusal)
+    )
+  ) {
+    throw new BrowserControlProtocolError("browser controller returned a malformed inspection");
+  }
+  let manifest: PlacementBrowserWorkingCopyInspection["manifest"] = null;
+  if (value.manifest !== null) {
+    if (!isRecord(value.manifest)) {
+      throw new BrowserControlProtocolError("browser controller returned a malformed manifest");
+    }
+    manifest = {
+      digest: sha256(value.manifest.digest, "working copy manifest digest"),
+      entries: nonnegativeSafeInteger(value.manifest.entries, "working copy entries"),
+      bytes: nonnegativeSafeInteger(value.manifest.bytes, "working copy bytes"),
+      excluded: excludedWorkingCopyEntries(value.manifest.excluded),
+    };
+  }
+  let receipt: PlacementBrowserWorkingCopyInspection["receipt"] = null;
+  if (value.receipt !== null) {
+    const raw = value.receipt;
+    if (
+      !isRecord(raw) ||
+      !["launch", "suspend", "retire", "adopt"].includes(raw.intent as string) ||
+      typeof raw.state !== "string" ||
+      typeof raw.directoryLaunchAllowed !== "boolean" ||
+      typeof raw.authorityMatches !== "boolean" ||
+      !(raw.restoreAuthorityDigest === null || typeof raw.restoreAuthorityDigest === "string") ||
+      !(raw.adoption === null || isRecord(raw.adoption))
+    ) {
+      throw new BrowserControlProtocolError("browser controller returned a malformed receipt");
+    }
+    receipt = {
+      operationId: requireUuid(raw.operationId, "working runtime receipt id"),
+      intent: raw.intent as "launch" | "suspend" | "retire" | "adopt",
+      state: requireOpaqueId(raw.state, "working runtime receipt state"),
+      directoryLaunchAllowed: raw.directoryLaunchAllowed,
+      authorityMatches: raw.authorityMatches,
+      launchedFromCheckpoint: raw.restoreAuthorityDigest !== null,
+      adoption: isRecord(raw.adoption)
+        ? {
+            operationId: requireUuid(raw.adoption.operationId, "working copy adoption id"),
+            manifestDigest: sha256(raw.adoption.manifestDigest, "working copy manifest digest"),
+          }
+        : null,
+    };
+  }
+  return {
+    browserSessionId: reference.browserSessionId,
+    controllerGeneration: reference.controllerGeneration,
+    platformSupported: value.platformSupported,
+    refusal: value.refusal as PlacementBrowserWorkingCopyRefusal | null,
+    manifest,
+    profileIdentityMatches: value.profileIdentityMatches,
+    profileInUse: value.profileInUse,
+    receipt,
+    activeAdoption:
+      value.activeAdoption === null || value.activeAdoption === undefined
+        ? null
+        : parseWorkingCopyAdoption(value.activeAdoption, reference, "recorded"),
+  };
+}
+
 function parseStateCaptureReceipt(value: unknown): PlacementBrowserStateCaptureReceipt {
   if (!isRecord(value) || !isRecord(value.manifest)) {
     throw new BrowserControlProtocolError(
@@ -3598,6 +4010,19 @@ function nonnegativeSafeInteger(value: unknown, label: string): number {
   return value;
 }
 
+function excludedWorkingCopyEntries(value: unknown): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.length > 16 ||
+    !value.every((entry) => typeof entry === "string" && entry.length > 0 && entry.length <= 256)
+  ) {
+    throw new BrowserControlProtocolError(
+      "browser controller returned malformed working copy exclusions",
+    );
+  }
+  return [...value];
+}
+
 function parseUnsignedInteger(value: string, label: string): number {
   const trimmed = value.trim();
   if (!/^(0|[1-9][0-9]*)$/u.test(trimmed)) {

package/src/sandbox/browser-control-http.ts

@@ -0,0 +1,32 @@
+/** One request to an agent-owned browser/computer controller, addressed by its
+ * exact authority scope rather than a local port. */
+export type BrowserControlHttpCall = {
+  scopeId: string;
+  scopeGeneration: string;
+  method: "GET" | "POST" | "PUT" | "DELETE";
+  /** Absolute controller path with optional query. */
+  path: string;
+  bearerToken: string;
+  /** JSON request body bytes, when the request has a body. */
+  body?: Uint8Array;
+  timeoutMs: number;
+  maxResponseBytes: number;
+};
+
+/** What a placement transport did with one controller request. */
+export type BrowserControlHttpOutcome =
+  /** The placement cannot serve it natively; nothing was sent. */
+  | { kind: "unsupported" }
+  /** No controller for that scope and generation accepted it; nothing was
+   * delivered, so the caller may ensure the controller and send again. */
+  | { kind: "controller_absent" }
+  | {
+      kind: "response";
+      status: number;
+      /** Lowercase header names. */
+      headers: Map<string, string>;
+      body: Uint8Array;
+    };
+
+/** Extra time beyond the request's own deadline for the reply to arrive. */
+export const BROWSER_CONTROL_HTTP_REPLY_GRACE_MS = 5_000;

package/src/sandbox/index.ts

@@ -361,6 +361,10 @@ export {
   type PlacementBrowserNetworkRoute,
   type PlacementBrowserTransport,
   type PlacementBrowserStateCaptureReceipt,
+  type PlacementBrowserWorkingCopyAdoption,
+  type PlacementBrowserWorkingCopyAuthority,
+  type PlacementBrowserWorkingCopyInspection,
+  type PlacementBrowserWorkingCopyRefusal,
   type ComputerControlFrame,
   type ComputerControlFrameMetadata,
   type ComputerFrameEvidenceMismatchReason,

package/src/sandbox/routing/backend-resolver.ts

@@ -67,6 +67,7 @@ export interface SelfhostedConnectionBinding {
   operationResourcePolicySupported: boolean;
   operationCpuQuotaSupported: boolean;
   transactionalFsWriteSupported?: boolean;
+  browserControlHttpSupported?: boolean;
 }
 
 export interface ActiveBackendResolverDeps {
@@ -406,6 +407,7 @@ export function makeActiveBackendResolver(
         operationResourcePolicySupported: connection.operationResourcePolicySupported,
         operationCpuQuotaSupported: connection.operationCpuQuotaSupported,
         transactionalFsWriteSupported: connection.transactionalFsWriteSupported === true,
+        browserControlHttpSupported: connection.browserControlHttpSupported === true,
         // The routing proxy caches this session by sandbox+epoch, but command
         // policy and runner authority are mutable. Re-read one coherent DB
         // snapshot only when a new exec/Git is admitted.