@fungi.computer/oyster 0.2.0 → 0.3.0

package/dist/page/app-access.js

@@ -0,0 +1,75 @@
+import { grantRequestFor, appPermissionPageSchema, } from "../apps/permissions.js";
+/**
+ * Keep standalone consent in the Oyster host: the picked shell draws the
+ * prompt, while Oyster bounds the request and commits through its owner CAS.
+ */
+export function createShellAppAccess(directory) {
+    return async (target, input, dialog) => {
+        const { surfaceId, computerId } = target;
+        const current = await directory();
+        const app = current.apps.find((row) => row.surfaceId === surfaceId);
+        const installationId = app?.installationId ?? null;
+        const customize = () => dialog.customize(installationId);
+        if (installationId === null)
+            return customize();
+        const path = `/api/installations/${encodeURIComponent(installationId)}/grants`;
+        const response = await fetch(path, {
+            headers: { Accept: "application/json" },
+            credentials: "same-origin",
+            cache: "no-store",
+            redirect: "error",
+        });
+        if (!response.ok)
+            return "declined";
+        const view = appPermissionPageSchema.parse(await response.json());
+        const { permissions } = view;
+        const decision = grantRequestFor(permissions.authority, {
+            declaration: {
+                capabilities: permissions.declaredOperations.capabilities.map((row) => row.capability),
+            },
+            declaredOperations: permissions.declaredOperations,
+        }, input, { computerId });
+        if (decision.kind === "covered")
+            return "granted";
+        if (decision.kind === "refused") {
+            if (decision.code !== "window_scope_unavailable")
+                return "declined";
+            const outcome = await dialog.ask({
+                appName: view.appName,
+                agents: input.agents ?? [],
+                computers: input.computers ?? [],
+                refusal: {
+                    code: decision.code,
+                    message: "Allow for this window is unavailable on this Oyster. No access was changed. Use Customize to review Computer permissions explicitly.",
+                },
+                allow: () => Promise.resolve(false),
+            });
+            return outcome === "customize" ? customize() : outcome;
+        }
+        if (decision.kind === "customize")
+            return customize();
+        const outcome = await dialog.ask({
+            appName: view.appName,
+            agents: input.agents ?? [],
+            computers: input.computers ?? [],
+            allow: async () => {
+                const saved = await fetch(path, {
+                    method: "PUT",
+                    headers: { "Content-Type": "application/json" },
+                    credentials: "same-origin",
+                    cache: "no-store",
+                    redirect: "error",
+                    body: JSON.stringify({
+                        storeGeneration: view.storeGeneration,
+                        authorityVersion: permissions.authority.authorityVersion,
+                        artifactDigest: view.artifactDigest,
+                        command: decision.command,
+                    }),
+                });
+                return saved.ok;
+            },
+        });
+        // False saves settle declined; rejected saves leave the shell open for retry.
+        return outcome === "customize" ? customize() : outcome;
+    };
+}

package/dist/page/boot-host.js

@@ -0,0 +1,57 @@
+import { connectAppHost } from "@fungi.computer/agar/host";
+import { z } from "zod";
+import { bootUiSchema } from "../boot-gate.js";
+/**
+ * Trusted, zero-grant parent for a candidate entry. App readiness messages
+ * establish the ordinary Agar connection, never the boot-gate verdict.
+ */
+async function bootHost() {
+    const element = document.getElementById("boot-config");
+    if (element === null)
+        throw new Error("Host boot configuration unavailable");
+    const config = bootUiSchema
+        .pick({ identity: true })
+        .extend({ entry: z.url() })
+        .parse(JSON.parse(element.textContent));
+    const frame = document.getElementById("candidate");
+    if (!(frame instanceof HTMLIFrameElement) || frame.contentWindow === null)
+        throw new Error("Host candidate frame unavailable");
+    const denied = () => Promise.reject(new Error("No grants during host boot"));
+    const connection = connectAppHost({
+        appWindow: frame.contentWindow,
+        expectedAppOrigin: "null",
+        hostWindow: window,
+        launch: {
+            identity: config.identity,
+            capabilities: [],
+            context: {
+                version: 1,
+                value: {
+                    computerId: null,
+                    focus: { editing: false, surface: null },
+                    openRequest: null,
+                    visibility: "visible",
+                },
+            },
+            lifecycle: { version: 1, value: "connected" },
+            reservedChords: { version: 1, value: [] },
+            theme: { version: 1, value: "light" },
+        },
+        handlers: {
+            invokeReservedChord: denied,
+            onDisconnect: () => Promise.resolve(),
+            openNavigation: denied,
+            registerCommands: () => Promise.resolve({
+                update: () => undefined,
+                dispose: () => undefined,
+            }),
+            reportFocus: () => Promise.resolve(),
+            reportAgentSessionSelection: () => Promise.resolve(),
+            showToast: () => Promise.resolve(),
+        },
+    });
+    // Install the host connection listener before the candidate can announce ready.
+    frame.src = config.entry;
+    await connection;
+}
+await bootHost();

package/dist/page/capabilities.d.ts

@@ -5,7 +5,7 @@ import type { CapabilityDescriptor } from "../capability-descriptor.js";
 /** Agar's opaque host handle, shared by the page's exported factory contracts. */
 export type HostCapabilityHandle = AppHostLaunch["capabilities"][number]["handle"];
 /** Bind a page-local JSON caller; cancellation never enters serialized input. */
-export declare function capabilityJsonCaller(descriptor: CapabilityDescriptor, installationId: string): (method: string, raw?: unknown, options?: {
+export declare function capabilityJsonCaller(descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): (method: string, raw?: unknown, options?: {
     readonly signal?: AbortSignal;
 }) => Promise<import("zod").JSONType | undefined>;
 /** Local JSON calls carry cancellation separately from their serialized input. */
@@ -13,11 +13,11 @@ export type CapabilityJsonCaller = ReturnType<typeof capabilityJsonCaller>;
 /** Local factories may open only transports present in their descriptor. */
 export type CapabilityTransportOpener = (method: string, input?: Schema.Json) => WebSocket;
 /** Build the App's RPC handle from its admitted descriptor and installation. */
-export declare function capabilityHandle(descriptor: CapabilityDescriptor, installationId: string): HostCapabilityHandle;
+export declare function capabilityHandle(descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): HostCapabilityHandle;
 /** A supported contract may adapt local JSON calls into its App-facing handle. */
 export type CapabilityRegistration = Readonly<{
     contract: CapabilityContract<unknown>;
     createHandle?: (call: CapabilityJsonCaller, transport: CapabilityTransportOpener) => HostCapabilityHandle | Promise<HostCapabilityHandle>;
 }>;
 /** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
-export declare function registeredCapabilityHandle(registration: CapabilityRegistration, descriptor: CapabilityDescriptor, installationId: string): Promise<HostCapabilityHandle>;
+export declare function registeredCapabilityHandle(registration: CapabilityRegistration, descriptor: CapabilityDescriptor, installationId: string, computerTarget?: string): Promise<HostCapabilityHandle>;

package/dist/page/capabilities.js

@@ -3,6 +3,7 @@ import { compile, parse, pathToRegexp } from "path-to-regexp";
 import * as Schema from "effect/Schema";
 import { AppError } from "@fungi.computer/agar";
 import { parseJsonValue } from "@fungi.computer/whistle/wire";
+import { computerTargetUrl } from "./computer-target.js";
 const queryInput = Schema.Record(Schema.String, Schema.Union([Schema.String, Schema.Number, Schema.Boolean]));
 const capabilityInputSchema = Schema.Union([Schema.Json, Schema.Undefined]);
 function resolveRoute(path, input) {
@@ -163,7 +164,7 @@ class TransportHandle extends RpcTarget {
         return Promise.resolve();
     }
 }
-function capabilityRequest(descriptor, installationId, route, raw) {
+function capabilityRequest(descriptor, installationId, route, raw, computerTarget) {
     const resolved = resolveRoute(route.path, raw);
     const input = resolved.input;
     const headers = new Headers({ "X-Oyster-Installation": installationId });
@@ -184,9 +185,12 @@ function capabilityRequest(descriptor, installationId, route, raw) {
     if (route.kind === "json" && route.method !== "GET") {
         headers.set("Content-Type", "application/json");
         init.body = JSON.stringify(input);
-        return { url, init };
+        return { url: computerTargetUrl(url, computerTarget), init };
     }
-    return { url: `${url}${query(input)}`, init };
+    return {
+        url: computerTargetUrl(`${url}${query(input)}`, computerTarget),
+        init,
+    };
 }
 async function jsonReply(url, init) {
     const response = await fetch(url, init);
@@ -196,7 +200,7 @@ async function jsonReply(url, init) {
     return parseJsonValue(await response.json());
 }
 /** Bind a page-local JSON caller; cancellation never enters serialized input. */
-export function capabilityJsonCaller(descriptor, installationId) {
+export function capabilityJsonCaller(descriptor, installationId, computerTarget) {
     return async (method, raw, options) => {
         const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
         const route = descriptor.methods[method];
@@ -205,12 +209,12 @@ export function capabilityJsonCaller(descriptor, installationId) {
                 code: "INVALID_ARGUMENT",
                 retryable: false,
             });
-        const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+        const { url, init } = capabilityRequest(descriptor, installationId, route, input, computerTarget);
         return jsonReply(url, { ...init, signal: options?.signal });
     };
 }
 /** Open a browser transport using the page's admitted installation. */
-function capabilityTransportOpener(descriptor, installationId) {
+function capabilityTransportOpener(descriptor, installationId, computerTarget) {
     return (method, raw) => {
         const route = descriptor.methods[method];
         if (route?.kind !== "transport" ||
@@ -219,7 +223,7 @@ function capabilityTransportOpener(descriptor, installationId) {
                 code: "INVALID_ARGUMENT",
                 retryable: false,
             });
-        const { url } = capabilityRequest(descriptor, installationId, route, Schema.decodeUnknownSync(capabilityInputSchema)(raw));
+        const { url } = capabilityRequest(descriptor, installationId, route, Schema.decodeUnknownSync(capabilityInputSchema)(raw), computerTarget);
         const target = new URL(url, "https://oyster.invalid");
         // Browser WebSockets cannot send the installation header used by Fetch.
         target.searchParams.set("oysterInstallation", installationId);
@@ -227,7 +231,7 @@ function capabilityTransportOpener(descriptor, installationId) {
     };
 }
 /** Build the App's RPC handle from its admitted descriptor and installation. */
-export function capabilityHandle(descriptor, installationId) {
+export function capabilityHandle(descriptor, installationId, computerTarget) {
     // Cap'n Web exposes prototype methods, never an instance's own properties.
     // Only input crosses RPC; AbortSignal options belong to the local caller.
     class CapabilityHandle extends RpcTarget {
@@ -236,7 +240,7 @@ export function capabilityHandle(descriptor, installationId) {
         name,
         async (raw) => {
             const input = Schema.decodeUnknownSync(capabilityInputSchema)(raw);
-            const { url, init } = capabilityRequest(descriptor, installationId, route, input);
+            const { url, init } = capabilityRequest(descriptor, installationId, route, input, computerTarget);
             if (route.kind === "read")
                 return new ReadHandle(url, init);
             if (route.kind === "write")
@@ -249,8 +253,8 @@ export function capabilityHandle(descriptor, installationId) {
     return new CapabilityHandle();
 }
 /** Create a registered handle, using the descriptor's ordinary RPC handle by default. */
-export async function registeredCapabilityHandle(registration, descriptor, installationId) {
+export async function registeredCapabilityHandle(registration, descriptor, installationId, computerTarget) {
     if (registration.createHandle === undefined)
-        return capabilityHandle(descriptor, installationId);
-    return await registration.createHandle(capabilityJsonCaller(descriptor, installationId), capabilityTransportOpener(descriptor, installationId));
+        return capabilityHandle(descriptor, installationId, computerTarget);
+    return await registration.createHandle(capabilityJsonCaller(descriptor, installationId, computerTarget), capabilityTransportOpener(descriptor, installationId, computerTarget));
 }

package/dist/page/computer-handles.d.ts

@@ -46,7 +46,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
         readonly startedAt: number;
         readonly state: "running" | "exited" | "uncertain";
         readonly exitCode: number | null;
-        readonly sync: "synced" | "pending" | "unknown";
+        readonly sync: "unknown" | "pending" | "synced";
         readonly endedAt: number | null;
     }>;
     list(): Promise<{
@@ -58,7 +58,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
             readonly startedAt: number;
             readonly state: "running" | "exited" | "uncertain";
             readonly exitCode: number | null;
-            readonly sync: "synced" | "pending" | "unknown";
+            readonly sync: "unknown" | "pending" | "synced";
             readonly endedAt: number | null;
         }[];
     }>;
@@ -71,7 +71,7 @@ export declare class ComputerProcessesHandle extends RpcTarget implements Handle
             readonly startedAt: number;
             readonly state: "running" | "exited" | "uncertain";
             readonly exitCode: number | null;
-            readonly sync: "synced" | "pending" | "unknown";
+            readonly sync: "unknown" | "pending" | "synced";
             readonly endedAt: number | null;
         };
         readonly signalled: boolean;

package/dist/page/computer-target.d.ts

@@ -0,0 +1,3 @@
+/** Serialize a window's routing hint. The server must admit it through the live
+ * owner and fleet before constructing that request's workspace. */
+export declare function computerTargetUrl(path: string, computerId?: string): string;

package/dist/page/computer-target.js

@@ -0,0 +1,9 @@
+/** Serialize a window's routing hint. The server must admit it through the live
+ * owner and fleet before constructing that request's workspace. */
+export function computerTargetUrl(path, computerId) {
+    if (computerId === undefined)
+        return path;
+    const url = new URL(path, "https://oyster.invalid");
+    url.searchParams.set("computerId", computerId);
+    return url.pathname + url.search;
+}

package/dist/page/mount.d.ts

@@ -1,7 +1,21 @@
 import { type AppOpenInput, type AppRoleChoice } from "@fungi.computer/agar/apps";
+import type { WhistleRuntime } from "@fungi.computer/whistle";
 import * as Schema from "effect/Schema";
+import { type CapabilityDirectory, type AgentSessionSelection } from "@fungi.computer/agar";
 import { type AppHost, type AppHostLaunch, type AppHostHandlers } from "@fungi.computer/agar/host";
 import type { WhistleJsonValue } from "@fungi.computer/whistle";
+/** One page-wide selected Session, using only its reporting App's admitted view. */
+export declare class OysterAgentBrowserHost {
+    #private;
+    /** End the selected connection with the page's own lifetime. */
+    constructor(signal: AbortSignal);
+    /** A departing or deselecting mount cannot close a different active mount. */
+    release(frame: HTMLIFrameElement): void;
+    /** Release the page's current selection; later reports cannot reconnect it. */
+    dispose(): void;
+    /** Bind the reporting mount's current command view to its explicitly selected Session. */
+    report(frame: HTMLIFrameElement, selection: AgentSessionSelection | null, capabilities: CapabilityDirectory, whistle: Pick<WhistleRuntime, "snapshot" | "execute">): Promise<void>;
+}
 /** Current server-admitted configuration for one installed App page. */
 export declare const oysterAppConfigSchema: Schema.Struct<{
     readonly workbench: Schema.Boolean;
@@ -32,7 +46,7 @@ export declare const oysterAppConfigSchema: Schema.Struct<{
             help?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
-            menu? /** Which App that role's open would reach, or null when none fills it. */: Readonly<{
+            menu?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
             palette?: Readonly<{
@@ -64,7 +78,7 @@ export declare const oysterAppConfigSchema: Schema.Struct<{
             help?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
-            menu? /** Which App that role's open would reach, or null when none fills it. */: Readonly<{
+            menu?: Readonly<{
                 order?: number | undefined;
             }> | undefined;
             palette?: Readonly<{
@@ -141,6 +155,12 @@ export type OysterAppConfig = typeof oysterAppConfigSchema.Type;
 /** One isolated App connection, with the slots this host admitted for it. */
 export type OysterAppConnectionOptions = Readonly<{
     config: OysterAppConfig;
+    /** The page-wide selected Session owner shared by all child mounts. */
+    agentBrowser: OysterAgentBrowserHost;
+    /** The existing command owner's live, mount-scoped Agent view. */
+    agentCommands: Pick<WhistleRuntime, "snapshot" | "execute">;
+    /** An independently admitted per-window target; absent on fixed/default hosts. */
+    computerTarget?: string | undefined;
     frame: HTMLIFrameElement;
     signal: AbortSignal;
     handlers: AppHostHandlers;
@@ -156,4 +176,4 @@ export declare function connectOysterApp(options: OysterAppConnectionOptions): P
 export { oysterStorageHandle } from "./storage.js";
 export { appSandbox } from "../app-sandbox.js";
 /** Resolve only the slots admitted for this installation by its current host. */
-export declare function oysterAppCapabilities(options: Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen">): Promise<AppHostLaunch["capabilities"]>;
+export declare function oysterAppCapabilities(options: Pick<OysterAppConnectionOptions, "config" | "signal" | "appOpen" | "computerTarget">): Promise<AppHostLaunch["capabilities"]>;

package/dist/page/mount.js

@@ -1,19 +1,23 @@
 import { appOpenInputSchema, appsCall, appsOpen, } from "@fungi.computer/agar/apps";
 import { appApiMethodNameSchema } from "@fungi.computer/puffball/app";
 import { appIdSchema } from "@fungi.computer/puffball/effect";
-import { createBrowserActionHandler } from "../shell/browser-actions.js";
-import { createAppSurfaceCommandHost } from "../shell/command-host.js";
+import { createBrowserActionHandler } from "@fungi.computer/nacre";
+import { createAppSurfaceCommandHost } from "@fungi.computer/nacre/command-host";
 // App page: mounts one installed App's sandboxed frame and gives it the
 // capabilities this Oyster host provides. Bundled into `shellScript`.
-import { RpcTarget } from "@fungi.computer/capnweb";
+import { RpcTarget, RpcStub } from "@fungi.computer/capnweb";
+import { EventSource } from "eventsource";
+import { connectBrowser, UiBrowserError, } from "@fungi.computer/knapsack/ui/browser";
 import { createPageLifetime } from "./lifetime.js";
+import { computerTargetUrl } from "./computer-target.js";
 import * as Schema from "effect/Schema";
-import { AppError } from "@fungi.computer/agar";
+import { AppError, createCapabilityRegistry, } from "@fungi.computer/agar";
 import { appStorage } from "@fungi.computer/agar/storage";
+import { approvals } from "@fungi.computer/agar/approvals";
 import { oysterStorageHandle } from "./storage.js";
 import { appBackend, appMethods } from "@fungi.computer/agar/backend";
 import { computerList, computerPorts, computerProcesses, computerReadFile, computerTerminal, computerWriteFile, } from "@fungi.computer/agar/computer";
-import { agentList, agentManage, agentSessionRead, agentSessionWrite, } from "@fungi.computer/agar/agents";
+import { agentList, agentManage, agentSessionRead, agentSessionWrite, openAppAgent, } from "@fungi.computer/agar/agents";
 import { mediaGeneration } from "@fungi.computer/agar/media";
 import { MediaGeneration, mediaGenerationDescriptionSchema, } from "@fungi.computer/agar/media-json";
 import { registeredCapabilityHandle, } from "./capabilities.js";
@@ -23,6 +27,105 @@ import { parseJsonValue } from "@fungi.computer/whistle/wire";
 import { appDeclaredCommandSchema } from "@fungi.computer/puffball/app";
 import { TerminalCapability } from "./terminal.js";
 import { ComputerPortsHandle, ComputerProcessesHandle, } from "./computer-handles.js";
+/** One page-wide selected Session, using only its reporting App's admitted view. */
+export class OysterAgentBrowserHost {
+    #active;
+    #disposed = false;
+    /** End the selected connection with the page's own lifetime. */
+    constructor(signal) {
+        if (signal.aborted)
+            this.dispose();
+        else
+            signal.addEventListener("abort", () => {
+                this.dispose();
+            }, { once: true });
+    }
+    /** A departing or deselecting mount cannot close a different active mount. */
+    release(frame) {
+        if (this.#active?.frame !== frame)
+            return;
+        const previous = this.#active;
+        this.#active = undefined;
+        previous.close();
+    }
+    /** Release the page's current selection; later reports cannot reconnect it. */
+    dispose() {
+        this.#disposed = true;
+        if (this.#active !== undefined)
+            this.release(this.#active.frame);
+    }
+    /** Bind the reporting mount's current command view to its explicitly selected Session. */
+    async report(frame, selection, capabilities, whistle) {
+        if (this.#disposed)
+            return;
+        if (selection === null) {
+            this.release(frame);
+            return;
+        }
+        if (this.#active !== undefined)
+            this.release(this.#active.frame);
+        // Read-only Apps may observe Sessions, but cannot claim or settle UI work.
+        if (!capabilities.has(agentSessionWrite) && !capabilities.has(agentManage))
+            return;
+        let transport;
+        let connection;
+        const failure = () => {
+            console.warn("Oyster Agent browser connection failed");
+        };
+        const active = {
+            frame,
+            close: () => {
+                connection?.close();
+                if (transport !== undefined)
+                    void transport.close().catch(failure);
+            },
+        };
+        this.#active = active;
+        try {
+            transport = await openAppAgent(capabilities, {
+                agentId: selection.agentId,
+            });
+            if (this.#active !== active) {
+                await transport.close();
+                return;
+            }
+            const admitted = transport;
+            connection = connectBrowser({
+                baseUrl: `${admitted.baseUrl}/browser/sessions/${encodeURIComponent(selection.sessionId)}`,
+                whistle,
+                transport: {
+                    fetch: admitted.fetch,
+                    openEvents: (url) => new EventSource(url, { fetch: admitted.fetch }),
+                },
+            });
+            void connection.closed.catch((cause) => {
+                if (this.#active === active)
+                    this.release(frame);
+                console.warn("Oyster Agent browser connection failed", cause instanceof UiBrowserError
+                    ? cause.message
+                    : "Transport unavailable");
+            });
+        }
+        catch (cause) {
+            if (this.#active === active)
+                this.release(frame);
+            throw cause;
+        }
+    }
+}
+function agentDirectory(capabilities) {
+    const directory = createCapabilityRegistry();
+    const read = capabilities.find(({ id, version }) => id === agentSessionRead.id && version === agentSessionRead.version);
+    const write = capabilities.find(({ id, version }) => id === agentSessionWrite.id && version === agentSessionWrite.version);
+    const manage = capabilities.find(({ id, version }) => id === agentManage.id && version === agentManage.version);
+    if (read !== undefined)
+        directory.provide(agentSessionRead, agentSessionRead.schema.parse(new RpcStub(read.handle)));
+    if (write !== undefined)
+        directory.provide(agentSessionWrite, agentSessionWrite.schema.parse(new RpcStub(write.handle)));
+    if (manage !== undefined)
+        directory.provide(agentManage, agentManage.schema.parse(new RpcStub(manage.handle)));
+    return directory;
+}
 /** Current server-admitted configuration for one installed App page. */
 export const oysterAppConfigSchema = Schema.Struct({
     workbench: Schema.Boolean,
@@ -59,15 +162,17 @@ async function answer(response) {
 }
 /** The App's typed methods, reached through this host's method route. */
 class Methods extends RpcTarget {
+    computerTarget;
     #url;
-    constructor(url) {
+    constructor(url, computerTarget) {
         super();
+        this.computerTarget = computerTarget;
         this.#url = url;
     }
     async call(method, input) {
         const name = Schema.decodeUnknownSync(Schema.String.check(Schema.isPattern(/^[A-Za-z][A-Za-z0-9_.]{0,79}$/u)))(method);
         const body = Schema.decodeUnknownSync(Schema.String)(input);
-        return answer(await fetch(`${this.#url}${name}`, {
+        return answer(await fetch(computerTargetUrl(`${this.#url}${name}`, this.computerTarget), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body,
@@ -81,10 +186,12 @@ class Methods extends RpcTarget {
 class Calls extends RpcTarget {
     base;
     signal;
-    constructor(base, signal) {
+    computerTarget;
+    constructor(base, signal, computerTarget) {
         super();
         this.base = base;
         this.signal = signal;
+        this.computerTarget = computerTarget;
     }
     async call(appId, method, input) {
         const target = Schema.decodeUnknownSync(appIdSchema)(appId);
@@ -96,7 +203,7 @@ class Calls extends RpcTarget {
                 retryable: false,
             });
         Schema.decodeUnknownSync(Schema.fromJsonString(Schema.Json))(body);
-        return answer(await fetch(`${this.base}${encodeURIComponent(target)}/${encodeURIComponent(name)}`, {
+        return answer(await fetch(computerTargetUrl(`${this.base}${encodeURIComponent(target)}/${encodeURIComponent(name)}`, this.computerTarget), {
             method: "POST",
             headers: { "Content-Type": "application/json" },
             body,
@@ -205,11 +312,14 @@ export async function mountOysterPage() {
     // The App's commands are still admitted against its Release declaration.
     const commands = createAppSurfaceCommandHost();
     const mount = commands.mount(config.installationId, config.commands);
+    const agentBrowser = new OysterAgentBrowserHost(lifetime.signal);
     lifetime.own(() => {
         commands.dispose();
     });
     return connectOysterApp({
         config,
+        agentBrowser,
+        agentCommands: mount.agentCommands,
         frame,
         signal: lifetime.signal,
         reservedChords: [],
@@ -234,6 +344,11 @@ export async function connectOysterApp(options) {
     if (frame.contentWindow === null)
         throw new Error("App frame is unavailable");
     const capabilities = await oysterAppCapabilities(options);
+    const agents = agentDirectory(capabilities);
+    const releaseBrowser = () => {
+        options.agentBrowser.release(frame);
+    };
+    options.signal.addEventListener("abort", releaseBrowser, { once: true });
     const host = await connectAppHost({
         appWindow: frame.contentWindow,
         expectedAppOrigin: "null",
@@ -261,6 +376,14 @@ export async function connectOysterApp(options) {
         },
         handlers: {
             ...options.handlers,
+            reportAgentSessionSelection: async (selection) => {
+                await options.agentBrowser.report(frame, selection, agents, options.agentCommands);
+                await options.handlers.reportAgentSessionSelection(selection);
+            },
+            onDisconnect: async () => {
+                releaseBrowser();
+                await options.handlers.onDisconnect();
+            },
             requestBrowserAction: createBrowserActionHandler({
                 frame,
                 hostWindow: window,
@@ -305,11 +428,11 @@ export async function oysterAppCapabilities(options) {
                 let leaseExpiresAt = 0;
                 return new TerminalCapability((input) => transport("open", input), {
                     computerId: config.computerId,
-                    terminalUrl: selected.terminalUrl,
+                    terminalUrl: computerTargetUrl(selected.terminalUrl, options.computerTarget),
                     hostWindow: window,
                     mountSignal: options.signal,
                     ensureAccess: Object.assign(async (signal) => {
-                        const response = await fetch(`/apps/${encodeURIComponent(config.installationId)}/`, {
+                        const response = await fetch(computerTargetUrl(`/apps/${encodeURIComponent(config.installationId)}/`, options.computerTarget), {
                             headers: { Accept: "application/json" },
                             credentials: "same-origin",
                             cache: "no-store",
@@ -325,11 +448,18 @@ export async function oysterAppCapabilities(options) {
                                 retryable: false,
                             });
                         leaseExpiresAt = Date.now() + 60_000;
-                        return terminalSelection(current);
+                        const selected = terminalSelection(current);
+                        return {
+                            ...selected,
+                            terminalUrl: selected.terminalUrl === null
+                                ? null
+                                : computerTargetUrl(selected.terminalUrl, options.computerTarget),
+                        };
                     }, { leaseExpiresAt: () => leaseExpiresAt }),
                 });
             },
         },
+        { contract: approvals },
         { contract: agentList },
         { contract: agentManage },
         { contract: agentSessionRead },
@@ -357,7 +487,7 @@ export async function oysterAppCapabilities(options) {
             return [
                 Promise.resolve({
                     ...appsCall,
-                    handle: new Calls(base, options.signal),
+                    handle: new Calls(base, options.signal, options.computerTarget),
                 }),
             ];
         }
@@ -368,14 +498,20 @@ export async function oysterAppCapabilities(options) {
             return [];
         }
         return [
-            registeredCapabilityHandle(registration, descriptor, config.installationId).then((handle) => ({ ...registration.contract, handle })),
+            registeredCapabilityHandle(registration, descriptor, config.installationId, options.computerTarget).then((handle) => ({ ...registration.contract, handle })),
         ];
     }));
     if (unknownCapabilities.length > 0)
         document.body.dataset.oysterCapability = unknownCapabilities.join(", ");
     const resolved = [
-        { ...appBackend, handle: new Backend(config.backendUrl) },
-        { ...appMethods, handle: new Methods(config.methodsUrl) },
+        {
+            ...appBackend,
+            handle: new Backend(computerTargetUrl(config.backendUrl, options.computerTarget)),
+        },
+        {
+            ...appMethods,
+            handle: new Methods(config.methodsUrl, options.computerTarget),
+        },
         ...capabilities,
         ...(config.appsOpen && options.appOpen
             ? [{ ...appsOpen, handle: new AppOpen(options.appOpen) }]

package/dist/page-assets.d.ts

@@ -0,0 +1,22 @@
+import { HTTPException } from "hono/http-exception";
+/**
+ * Project the generated module's fields without exposing its private module name.
+ * The generated module remains the sole page-source contract.
+ * @inline
+ */
+export type PageAssetSources = {
+    [Key in keyof typeof import("#page-script")]: (typeof import("#page-script"))[Key];
+};
+/**
+ * Acquire page sources only when a host page or asset request needs them.
+ */
+export type PageAssetLoader = () => Promise<PageAssetSources>;
+/** A failed acquisition refuses this request without exposing loader details. */
+export declare class PageAssetsLoadError extends HTTPException {
+    constructor(cause: unknown);
+    getResponse(): Response;
+}
+/**
+ * Missing page sources must fail the request, never produce an empty script.
+ */
+export declare const loadPageAssets: PageAssetLoader;