@opengeni/runtime 3.2.2 → 3.3.0

package/dist/index.js

@@ -187,7 +187,7 @@ import {
   workspaceEnvironmentInstructions,
   wrapAttemptToolDefinitions,
   wrapAttemptToolExecute
-} from "./chunk-2AUDDDO2.js";
+} from "./chunk-XRX57ZQO.js";
 import {
   ActiveBackendUnresolvableError,
   BROWSER_CONTROL_ADMIN_TOKEN_FILE,
@@ -403,7 +403,7 @@ import {
   withRunCredentialsSession,
   withoutSandboxProviderIdentity,
   workspaceArchiveDownloadTemporaryDirectory
-} from "./chunk-462CH77G.js";
+} from "./chunk-EK7IW2FR.js";
 import {
   SKILL_MAX_FILES,
   SKILL_MAX_FILE_BYTES,

package/dist/sandbox/browser-control-client.d.ts

@@ -3,6 +3,7 @@ import { type BrowserFrameMetadata } from "@opengeni/sdk";
 import { BROWSER_PROFILE_ARTIFACT_FORMAT, type BrowserActionCommand as BrowserActionCommandValue, type BrowserActionReceipt as BrowserActionReceiptValue, type BrowserClipboard as BrowserClipboardValue, type BrowserDiagnosticBatch as BrowserDiagnosticBatchValue, type BrowserDownload as BrowserDownloadValue, type BrowserDownloadExportReceipt as BrowserDownloadExportReceiptValue, type BrowserDownloadExportRequest as BrowserDownloadExportRequestValue, type BrowserDownloadListResponse as BrowserDownloadListResponseValue, type BrowserDomReadRequest as BrowserDomReadRequestValue, type BrowserDomReadResponse as BrowserDomReadResponseValue, type BrowserExternalAuthCommand as BrowserExternalAuthCommandValue, type BrowserExternalAuthResult as BrowserExternalAuthResultValue, type BrowserDiagnosticKind, type BrowserTargetListResponse as BrowserTargetListResponseValue, type BrowserObservation as BrowserObservationValue, type BrowserRevisionMaterialization as BrowserRevisionMaterializationValue, type BrowserTarget as BrowserTargetValue, type BrowserTargetState as BrowserTargetStateValue, type BrowserWorkspaceFileStageRequest as BrowserWorkspaceFileStageRequestValue, type BrowserWorkspaceFileStageResponse as BrowserWorkspaceFileStageResponseValue, type BrowserPasskeySyncRequest as BrowserPasskeySyncRequestValue, type BrowserPasskeySyncResponse as BrowserPasskeySyncResponseValue, type ComputerActionCommand as ComputerActionCommandValue, type ComputerActionReceipt as ComputerActionReceiptValue, type ComputerClipboard as ComputerClipboardValue, type ComputerObservation as ComputerObservationValue, type ComputerSessionCapabilities as ComputerSessionCapabilitiesValue, type ComputerTarget as ComputerTargetValue, type InteractionError as InteractionErrorValue, type NetworkRouteConsistency as NetworkRouteConsistencyValue } from "@opengeni/contracts";
 import type { BrowserControlEnsureRequest, BrowserControlEnsureResponse, BrowserFramesOpenRequest, ComputerFramesOpenRequest, StreamChannel } from "@opengeni/agent-proto";
 import { type EnsureBrowserControlServerResult } from "./browser-control-server.js";
+import type { BrowserControlHttpCall, BrowserControlHttpOutcome } from "./browser-control-http.js";
 import { type ExposedPortEndpoint } from "./stream-port.js";
 export declare const BROWSER_CONTROL_ADMIN_TOKEN_FILE = "/tmp/opengeni-browserd/authority/admin-token";
 type ExecResultLike = {
@@ -68,6 +69,8 @@ export type BrowserControlPlacementSession = {
         }) => void;
     };
     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;
@@ -434,6 +437,13 @@ export declare class BrowserControlClient {
     private requestBytes;
     private requestStream;
     private controllerPort;
+    /** 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 requestNative;
+    private ensureControllerPort;
 }
 export declare class BrowserControlSessionClient {
     readonly reference: PlacementBrowserSessionReference;

package/dist/sandbox/browser-control-http.d.ts

@@ -0,0 +1,33 @@
+/** 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 declare const BROWSER_CONTROL_HTTP_REPLY_GRACE_MS = 5000;

package/dist/sandbox/index.js

@@ -213,7 +213,7 @@ import {
   withRunCredentialsSession,
   withoutSandboxProviderIdentity,
   workspaceArchiveDownloadTemporaryDirectory
-} from "../chunk-462CH77G.js";
+} from "../chunk-EK7IW2FR.js";
 import "../chunk-5ULGMFKR.js";
 import {
   CODE_SEARCH_RG_MAX_BYTES,

package/dist/sandbox/routing/backend-resolver.d.ts

@@ -32,6 +32,7 @@ export interface SelfhostedConnectionBinding {
     operationResourcePolicySupported: boolean;
     operationCpuQuotaSupported: boolean;
     transactionalFsWriteSupported?: boolean;
+    browserControlHttpSupported?: boolean;
 }
 export interface ActiveBackendResolverDeps {
     /** The workspace the session belongs to (the control-plane subject scope). */

package/dist/sandbox/selfhosted/session.d.ts

@@ -1,6 +1,7 @@
 import { ControlResponse, type BrowserControlEnsureRequest, type BrowserControlEnsureResponse, type BrowserFramesOpenRequest, type ComputerFramesOpenRequest, type StreamChannel } from "@opengeni/agent-proto";
 import { Manifest } from "@openai/agents/sandbox";
 import type { ExposedPortEndpoint } from "../stream-port.js";
+import { type BrowserControlHttpCall, type BrowserControlHttpOutcome } from "../browser-control-http.js";
 import { type ControlRpc } from "./control-rpc.js";
 import { type SelfhostedRetryClock } from "./retry-policy.js";
 import type { SelfhostedOpObserver } from "./op-observer.js";
@@ -100,6 +101,8 @@ export interface SelfhostedBackgroundCommandAdoption {
  * every exec/Git admission; retries and already-started operations retain it. */
 export interface SelfhostedOperationAdmission {
     transactionalFsWriteSupported?: boolean;
+    /** The live runner serves in-process browser/computer controller requests. */
+    browserControlHttpSupported?: boolean;
     /** Workspace segment of the physical agent/relay route. Personal machines may
      * originate in a different same-organization workspace than the session. */
     workspaceId?: string;
@@ -123,6 +126,9 @@ export interface SelfhostedOperationAdmission {
 export interface SelfhostedSessionDeps {
     /** Exact live daemon capability; absent preserves legacy small-file writes. */
     transactionalFsWriteSupported?: boolean;
+    /** Exact live daemon capability; absent keeps controller requests on the
+     * command transport. */
+    browserControlHttpSupported?: boolean;
     /** Authorization/session workspace. */
     workspaceId: string;
     /** Physical control-plane workspace. Defaults to workspaceId for legacy and
@@ -303,6 +309,7 @@ export declare class SelfhostedSession {
     private readonly resourcePolicySupported;
     private readonly operationCpuQuotaSupported;
     private readonly transactionalFsWriteSupported;
+    private readonly browserControlHttpSupported;
     private readonly defaultOpStream;
     private readonly connectionInstanceId;
     private readonly resolveOperationAdmission;
@@ -524,6 +531,14 @@ export declare class SelfhostedSession {
     /** Ensure the loopback browser controller sidecar owned by this connected
      * machine. The authority scope is supplied by the caller and remains local. */
     ensureBrowserControl(request: BrowserControlEnsureRequest): Promise<BrowserControlEnsureResponse>;
+    /** Send one request to the agent-owned controller of an exact authority
+     * scope, served inside the runner over loopback without starting a process.
+     * `unsupported` means this connection's runner does not serve it and nothing
+     * was sent. `controller_absent` means no controller for that scope and
+     * generation accepted the request, so it was not delivered and the caller may
+     * ensure the controller and send again. A body too large for one reply is
+     * drained from the runner's spool; the request is never repeated. */
+    browserControlHttp(request: BrowserControlHttpCall): Promise<BrowserControlHttpOutcome>;
     /** Open one browser-native frame producer and return its canonical relay
      * endpoint. This does not route through `resolveExposedPort`: that legacy
      * method allocates PTY/desktop resources based on fixed ports, while this op
@@ -597,6 +612,7 @@ export declare class SelfhostedSandboxClient {
     private readonly operationResourcePolicySupported;
     private readonly operationCpuQuotaSupported;
     private readonly transactionalFsWriteSupported;
+    private readonly browserControlHttpSupported;
     private readonly resolveOperationAdmission;
     private readonly adoptBackgroundCommand;
     private readonly settleBackgroundCommand;
@@ -631,6 +647,7 @@ export declare class SelfhostedSandboxClient {
         operationResourcePolicySupported?: boolean;
         operationCpuQuotaSupported?: boolean;
         transactionalFsWriteSupported?: boolean;
+        browserControlHttpSupported?: boolean;
         resolveOperationAdmission?: () => Promise<SelfhostedOperationAdmission | null>;
         adoptBackgroundCommand?: SelfhostedSessionDeps["adoptBackgroundCommand"];
         settleBackgroundCommand?: SelfhostedSessionDeps["settleBackgroundCommand"];
@@ -711,6 +728,8 @@ export interface SelfhostedSessionBuild {
     /** Exact live CPU enforcement capability paired with the initial snapshot. */
     operationCpuQuotaSupported?: boolean;
     transactionalFsWriteSupported?: boolean;
+    /** Exact live runner capability for in-process controller requests. */
+    browserControlHttpSupported?: boolean;
     /** Live last-boundary operation admission resolver; see SelfhostedSessionDeps. */
     resolveOperationAdmission?: () => Promise<SelfhostedOperationAdmission | null>;
     adoptBackgroundCommand?: SelfhostedSessionDeps["adoptBackgroundCommand"];

package/dist/workspace-tool-gateway.js

@@ -3,8 +3,8 @@ import {
   prepareAgentTools,
   secretArgumentMode,
   sessionMcpApprovalConnectionId
-} from "./chunk-2AUDDDO2.js";
-import "./chunk-462CH77G.js";
+} from "./chunk-XRX57ZQO.js";
+import "./chunk-EK7IW2FR.js";
 import "./chunk-4KFT2G3W.js";
 import "./chunk-7OUG7WBV.js";
 import "./chunk-5ULGMFKR.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/runtime",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -75,19 +75,19 @@
     "@openai/agents": "0.14.3",
     "@openai/agents-core": "0.14.3",
     "@openai/agents-extensions": "0.14.3",
-    "@opengeni/agent-proto": "3.2.2",
-    "@opengeni/capabilities": "3.2.2",
-    "@opengeni/codemode": "3.2.2",
-    "@opengeni/codex": "3.2.2",
-    "@opengeni/config": "3.2.2",
-    "@opengeni/contracts": "3.2.2",
-    "@opengeni/interaction": "3.2.2",
-    "@opengeni/network": "3.2.2",
-    "@opengeni/observability": "3.2.2",
-    "@opengeni/sdk": "3.2.2",
-    "@opengeni/tool-gateway": "3.2.2",
-    "@opengeni/vaults": "3.2.2",
-    "@opengeni/xai-subscription": "3.2.2",
+    "@opengeni/agent-proto": "3.3.0",
+    "@opengeni/capabilities": "3.3.0",
+    "@opengeni/codemode": "3.3.0",
+    "@opengeni/codex": "3.3.0",
+    "@opengeni/config": "3.3.0",
+    "@opengeni/contracts": "3.3.0",
+    "@opengeni/interaction": "3.3.0",
+    "@opengeni/network": "3.3.0",
+    "@opengeni/observability": "3.3.0",
+    "@opengeni/sdk": "3.3.0",
+    "@opengeni/tool-gateway": "3.3.0",
+    "@opengeni/vaults": "3.3.0",
+    "@opengeni/xai-subscription": "3.3.0",
     "debug": "4.4.3",
     "modal": "0.9.0",
     "openai": "6.47.0",

package/src/bundled_site_skills/opengeni-sites/SKILL.md

@@ -18,8 +18,9 @@ Site on the web is built in (see "Publish to the web").
 
 A Site never needs its own server, API key, or hosting provider to reach
 Opengeni. Model access, agent conversations, and workspace tools all come from
-the host bridge: `createOpenGeniSiteClient` from `@opengeni/sdk/site` plus the
-`@opengeni/react/session-ui` conversation surface. The parent page owns the
+the host bridge: `createOpenGeniSiteClient` from `@opengeni/sdk/site`. Use its
+`ai.run` helper for inline results, or `@opengeni/react/session-ui` when the app
+needs a conversation surface. The parent page owns the
 credentials and workspace identity; Site code receives neither, so "keep
 credentials server-side" is already satisfied by that bridge.
 
@@ -239,6 +240,33 @@ const client = createOpenGeniSiteClient();
 const issues = await client.tools.linear.issues_list({ state: "Todo" });
 ```
 
+### Inline AI: the app chooses the interaction
+
+Use `site.ai.run({ initialMessage: appDefinedPrompt, idempotencyKey: actionId })`
+to return AI output inside the app without mounting chat or displaying history.
+Prompts, context, controls and results are app-designed; Draft, Summarize or
+Classify are merely possible examples, never required buttons or templates.
+Use `onText` for incremental text and `onSession` to retain a native handle before
+waiting. A result has `text`, `sessionId`, `turnId`, `after` and `status`:
+`completed`, `pending` (approval/input needed), or `cancelled`; failures reject.
+Validate any app-defined structured output before using it.
+
+This is ordinary native execution with the same model access, subscriptions,
+permissions, tool selection, approvals, metering and outsider caps. Aborting the
+observation does not cancel the task. `site.ai.result(id, { turnId })` replays
+without creating more work. Supplying `after` returns subsequent text only;
+retain earlier text or omit it for a full replay. Keep retry keys stable per
+action and handles in viewer-private state/storage, not shared Site Data.
+
+Site AI is private per viewer by default and does not clutter the workspace
+sidebar or ordinary search. Signed-in members use their real human identity;
+guests use existing cookie/visitor continuity, not a shared anonymous chat.
+If organization policy disallows private execution, surface its explicit
+refusal; never fall back to shared sessions. Privacy does not automatically
+extend to separately published artifacts or shared Site Data.
+
+### Optional conversation UI
+
 For embedded conversations, `site.client` is the ordinary Opengeni SDK client;
 `site.workspaceId` is a host-resolved routing alias. Use the normal React
 complete conversation surface—do not implement session REST or SSE yourself:
@@ -259,7 +287,7 @@ const site = createOpenGeniSiteClient();
 ```
 
 `sessionId` is the existing session or the id returned by `site.client.createSession`.
-For a normal chat app, offer a conversation selector and “New conversation”.
+For a normal chat app, a conversation selector and “New conversation” are optional.
 Create on first Send rather than mounting the page; keep the selected id in React
 state and reopen existing conversations through the SDK.
 Keep first-send creation single-flight; reuse its `idempotencyKey` when retrying,
@@ -272,14 +300,17 @@ write origin metadata yourself. The local preview has no published identity, so
 this filter returns no Site history there; test newly created/current conversations
 locally and the selector after publication.
 
-This is a default, not a restriction. For a project-focused app, use `channelId`
-on SDK creation/listing instead; its list may include conversations created
-elsewhere. Project management tools use `projectId` (see `opengeni-projects`
-when available). Do not automatically create a project just to group Site chats.
-Unfiled Site conversations group under their Site in the main sidebar; explicit
-projects and pins take precedence. Origin remains visible regardless of placement.
-The host Site page always provides its own Conversations panel independently of
-the navigation you build. Opening existing sessions never changes their origin.
+Do not automatically create a project just to group Site chats. Site execution
+does not appear in ordinary workspace discovery, even for its owner. The host
+Site page provides a viewer-scoped Conversations panel independently of app
+navigation. Opening existing sessions never changes their origin or audience.
+Page code cannot widen the Site boundary by supplying project, visibility,
+tools or credential fields; use ordinary authoring tools for project management.
+
+Per-Site AI costs are in Insights: actual credit charges are distinct from
+API-equivalent subscription/own-key estimates and unbilled platform counters.
+Usage is for limits. Do not build private transcript or viewer analytics into
+shared dashboards just because aggregate costs are visible there.
 
 `SessionConversation` connects timeline/history, durable composer drafts,
 queue display/edit/delete/steer, pause/resume, and human-input forms. Prefer it
@@ -667,8 +698,11 @@ workspace first.
   `rate_limited`, `site_budget_exhausted` and retryable `site_budget_busy` (429), and
   `site_platform_brake_engaged` (503) as normal UI states.
 - The same Site HTML and Site Data work there; no rebuild is needed.
-- Every published-host agent gets this Site's `site_data_query` and `site_data_write`,
+- Published-host agents get this Site's `site_data_query` and `site_data_write`,
   plus `site_sql_run` when SQL is enabled; members also get read-only `site_sql_query`.
+  Member tools are intersected with live permissions: a member without artifact
+  publishing can still use AI without write tools, and without data-read permission
+  can use plain AI without data tools. Never request extra permission just to chat.
   The server pins the Site and binds calls to the conversation's viewer, including
   collection ownership and query audiences. No management tools or sandbox are
   supplied; publication settings have no sandbox opt-in. Members get no Site

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 }>;
@@ -1176,6 +1179,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 +1373,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 +1540,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({

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/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.