@opengeni/runtime 3.1.3-canary.38890816741001 → 3.3.0

package/dist/index.js

@@ -187,7 +187,7 @@ import {
   workspaceEnvironmentInstructions,
   wrapAttemptToolDefinitions,
   wrapAttemptToolExecute
-} from "./chunk-GPCVTVNT.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-GPCVTVNT.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.1.3-canary.38890816741001",
+  "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.1.3-canary.38890816741001",
-    "@opengeni/capabilities": "3.1.3-canary.38890816741001",
-    "@opengeni/codemode": "3.1.3-canary.38890816741001",
-    "@opengeni/codex": "3.1.3-canary.38890816741001",
-    "@opengeni/config": "3.1.3-canary.38890816741001",
-    "@opengeni/contracts": "3.1.3-canary.38890816741001",
-    "@opengeni/interaction": "3.1.3-canary.38890816741001",
-    "@opengeni/network": "3.1.3-canary.38890816741001",
-    "@opengeni/observability": "3.1.3-canary.38890816741001",
-    "@opengeni/sdk": "3.1.3-canary.38890816741001",
-    "@opengeni/tool-gateway": "3.1.3-canary.38890816741001",
-    "@opengeni/vaults": "3.1.3-canary.38890816741001",
-    "@opengeni/xai-subscription": "3.1.3-canary.38890816741001",
+    "@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_default_skills/opengeni-client/references/tools-and-auth.md

@@ -193,3 +193,54 @@ README's Workspace tools section for approval and migration details.
 Never put tokens in prompts, Skills, `modelContext`, tool URLs, browser code,
 or logs. Opengeni stores Connection and MCP header secrets encrypted and keeps
 them out of the model's context.
+
+### Your product as a vault provider
+
+Use native vaults when the agent needs to discover and use stored credentials.
+An embedding product can expose multiple remote vaults through a signed
+`external` connection; an in-process host can keep using
+`connectionCredentials.vaultProvider`. Keep the simple chat/tool integration
+above unchanged unless the product actually needs this optional capability.
+
+Configure remote connections on the server with `vaultsApi(client, workspaceId)`
+from `@opengeni/sdk`: `installVaultProvider`, `getVaultProviderCatalog`,
+`listProviderVaults`, and `linkProviderVault`. Never put provider tokens or the
+signing secret in browser code, model context, or URL parameters. Verify each
+request's raw-body signature and map its native account/workspace/subject to
+the host's actual tenant/user before authorizing it. A shared connection must
+not return a different user's inventory into the same metadata mirror; use
+separate user-owned connections for user-specific stores.
+
+Connection setup uses the existing `connections:write` and `secrets:write`
+permissions and native owner checks, including authorized agent attempts for
+shared connections. Personal setup requires the verified owner, and
+organization setup requires its admin. List/read/write operations always use
+the registered connection endpoint, not a per-call URL chosen by a tool caller.
+
+`getVaultProviderCatalog` includes deployment availability even before anyone
+connects; disable unavailable setup choices instead of collecting credentials
+that this deployment cannot use. `listVaultProviderConnections` remains a
+metadata-only convenience when only existing connections are needed.
+
+For a remote host, use `createExternalVaultReceiver` from the server-only
+`@opengeni/sdk/external-vault-receiver` subpath and a durable atomic replay and
+mutation store. The in-memory store is only for local tests. Its
+`resolveConnection` binds the native connection to one fixed host inventory;
+`authorize` checks the mapped person on every operation. If the host must
+register the native connection ID first, install returns saved/pending setup;
+register that ID, then verify. Never accept all unknown connections into one
+default tenant to avoid this registration step.
+
+Provider capabilities are granular: do not assume every read-write vault can
+update TOTP, upload files, restore history or archive items. Distinguish cached
+metadata from live value reads. Incomplete discovery or an unavailable source
+is not proof that the user has no matching secret. For a saved-but-pending
+setup (`discoveryPending: true`), use `verifyVaultProviderConnection` with the
+connection ID rather than resubmitting a consumed bootstrap token.
+
+The native secret ask card still saves to hosted vaults only. If the host must
+own collection, collect in the host UI and expose the saved item via its
+provider. Keep short-lived per-attempt credentials on the existing renewable
+credential callback: a stored item does not replace expiry/renewal, Git/MCP
+transport bindings or cleanup. See the product's external-vault and credential
+provider documentation before implementing either path.

package/src/bundled_secret_skills/opengeni-secrets/SKILL.md

@@ -5,10 +5,8 @@ description: Use when signing in, creating accounts, storing or using passwords,
 
 # Secrets: sign in and use credentials yourself
 
-You are trusted with the user's vaults. Act on your own: sign in, create
-accounts when the task allows it, enroll your own 2FA, fetch email and SMS
-codes, and solve CAPTCHAs. You never need to see a value: write a reference and
-it resolves where it runs.
+Use references instead of viewing values. Sign in, create accounts when the
+task allows it, enroll 2FA, fetch codes and solve CAPTCHAs yourself.
 
 ## References
 
@@ -30,16 +28,15 @@ The `secret_*` tools take references as names and never resolve them.
 
 ## Tools
 
-- `secret_search {query?, website?, type?, vault?, cursor?}`: items and
-  references, never values; no filters lists all, page one lists vaults.
-  Repeat with `cursor` while `nextCursor` is set.
-- `secret_save {item, vault?, saveTo?, type?, websites?, username?, fields?, mode?}`:
-  each field takes one of `value`, `generate`, `fromReference` or
-  `restoreVersion`. Use `generate` for new passwords.
-- `secret_move {reference, toVault, mode, newName?}`: move or copy an item.
-- `secret_delete {reference}`: archive an item.
-- `secret_get {reference}`: plaintext, only with `secrets:read`. Use it only
-  when a tool cannot take a reference.
+- `secret_search`: metadata and references, never values. No filters lists all;
+  page one lists vaults. Follow `nextCursor` with unchanged filters. Check
+  `complete` and freshness before inferring absence. `refresh: true` requests
+  fresh inventory without bypassing rate limits.
+- `secret_save`: each field takes `value`, `generate`, `fromReference` or
+  `restoreVersion`. Generate new passwords.
+- `secret_move`: move or copy to another vault.
+- `secret_delete`: archive an item.
+- `secret_get`: plaintext with `secrets:read`, only if references cannot work.
 
 ## Login ladder
 
@@ -65,9 +62,9 @@ after one failure.
 
 - `saveTo`: `user` (Only me, reused later), `task` (throwaway, shared with this
   task's sessions) or `workspace` (team keys, schedules that run without you).
-- Name items after the service and account ("GitHub", "GitHub ops bot") and
-  record `websites` and `username`.
-- Move an item with `secret_move` when a schedule or teammate needs it.
+- Name items by service/account; record `websites` and `username`.
+- Respect provider capabilities. Ask cards save to hosted vaults only.
+  Provider write and move limits: `references/troubleshooting.md`.
 
 ## Missing secrets and errors
 
@@ -75,12 +72,16 @@ A tool result with `secret_reference_error` ran nothing. For a missing secret
 it includes `askCard`: call `request_human_input` with it, changing only
 `saveTo` or `prompt`, then retry with the returned reference.
 
+An unavailable or incomplete provider is not a missing secret: respect retry
+times or reconnect/unlock it. Inspect unknown write outcomes before retrying;
+never repeat a create just because its inventory refresh failed.
+
 ## Playbooks
 
-- `references/login-playbook.md`: browser sign-in, codes, CAPTCHAs.
-- `references/account-creation.md`: sign-ups and generated passwords.
-- `references/2fa-enrollment.md`: enroll and use your own TOTP.
-- `references/api-keys.md`: CLIs, env vars, config files, `secretfile`.
-- `references/ask-card.md`: the `kind: "secret"` question.
-- `references/troubleshooting.md`: every error code and what to do.
-- `references/codemode-and-scripts.md`: escaping in `ogtool` and scripts.
+- Login: `references/login-playbook.md`.
+- Sign-up: `references/account-creation.md`.
+- TOTP: `references/2fa-enrollment.md`.
+- CLI/files: `references/api-keys.md`.
+- Secret card: `references/ask-card.md`.
+- Errors: `references/troubleshooting.md`.
+- Escaping: `references/codemode-and-scripts.md`.

package/src/bundled_secret_skills/opengeni-secrets/references/troubleshooting.md

@@ -23,6 +23,21 @@ and a `hint`. Fix the reference and retry the same action.
 
 ## Save and vault errors
 
+Connected providers advertise their supported operations. Do not work around a
+read-only or unsupported operation by exposing values in logs or process
+arguments. A move requires recoverable removal at the source; a copy may still
+be supported without it. Ask cards save to hosted vaults only.
+
+An offline, locked, rate-limited or incomplete source is not proof that a secret
+is missing. Check search `complete` and source freshness, preserve filters while
+paging, and request `refresh: true` deliberately. It respects rate limits. Report
+the reconnect or unlock action rather than asking for the secret again.
+
+For `provider_outcome_unknown`, inspect the provider before retrying: a write
+may already have succeeded. `provider_inventory_incomplete` with `saved: true`
+means the write succeeded but the subsequent inventory refresh failed. Refresh
+the inventory; never automatically repeat the create.
+
 | Error | What to do |
 |---|---|
 | `vault_read_only` | A connected vault is read-only. Save to an Opengeni vault (`saveTo` without `vault`) or ask the user to make it writable. |

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;