@fungi.computer/oyster 0.5.0 → 0.7.0

package/dist/mcp.js

@@ -1,7 +1,5 @@
 import { z } from "zod";
-import { describeModule, invokeModuleOperation, } from "@fungi.computer/mycelium/remote";
 import { PendingApprovalSchema, ApprovalRefusalSchema, } from "@fungi.computer/approvals";
-import { jsonSchemaToZod } from "@fungi.computer/forage";
 import { admits } from "./apps/gate.js";
 import { createMcpWorkflowControl, WORKFLOW_CONTROL_MODULE_ID, } from "./workflows.js";
 import { causeClass } from "./cause-class.js";
@@ -11,15 +9,24 @@ import { emptyAppDeclaration } from "@fungi.computer/puffball/app";
 import { admittedMethodCallerFacts, invocationCallerContext, } from "./invocation.js";
 import { guestLimits } from "./guest-policy.js";
 import { Mycelium, } from "@fungi.computer/mycelium";
-import { appToolSchemas, appToolFamilySchemas } from "@fungi.computer/forage";
+import { appJsonSchema, appToolFamilySchemas } from "@fungi.computer/forage";
+import { forageDiscoveryInstructions } from "@fungi.computer/mycelium/effect";
 import { Knapsack } from "@fungi.computer/knapsack";
 import * as Schema from "effect/Schema";
 import { defineIdFamily } from "@fungi.computer/cairn/id";
 import { computerCreateRequestSchema, computerPageSchema, } from "@fungi.computer/computer/fleet/inventory-wire";
 import { computerStateSchema } from "@fungi.computer/computer/fleet/wire";
 import { teamComputerDirectorySchema } from "@fungi.computer/nacre/workbench";
-import { keyAppAccess } from "./keys.js";
+import { appToolAccess, authorityOf, hostAuthorityPorts, } from "./authorization.js";
 import { defaultAssetPolicy, sha256, verifyRelease, } from "./release.js";
+/** Shared host result guidance for Agent and MCP instructions, not per method. */
+export const appApprovalInstructions = [
+    "A write (including Effect: external) may instead return AppApprovalResult:",
+    "type AppApprovalResult =",
+    '  | { kind: "pending_approval"; recordId: string; description: { title: string; inputBytes: number; inputSha256: string } }',
+    '  | { kind: "refused"; reason: string; denialNote?: string };',
+    "On pending_approval, tell the person it is waiting for their approval; do not retry.",
+].join("\n");
 const fleetIds = defineIdFamily({
     family: "mcp-computer-control",
     version: 1,
@@ -128,10 +135,8 @@ function capturedAccessFor(access, installationId) {
 }
 /** Re-read one actor's current App-tool access for one installation, fresh. */
 async function freshAccessFor(host, actor, installationId) {
-    if (actor.kind === "agent")
-        return (await host.appToolPolicy?.(actor)) ?? null;
-    const key = (await host.keys?.live(actor.keyId)) ?? null;
-    return key === null ? null : keyAppAccess(key, installationId);
+    const ports = hostAuthorityPorts(host);
+    return appToolAccess(await authorityOf({ actor }, ports), installationId, ports);
 }
 /** Make one {@link AppSurfaceCache} for a host whose artifact store and capabilities stay fixed. */
 export function appSurfaceCache(host) {
@@ -144,7 +149,7 @@ export function appSurfaceCache(host) {
             release,
             api: release.api,
             declaredOperations: await deriveDeclaredOperations(installed, release.declaration ?? emptyAppDeclaration, host.capabilities ?? []),
-            toolSchemas: appToolSchemas(release.api),
+            methods: Object.fromEntries(Object.entries(release.api.methods).filter(([, method]) => method.hidden !== true)),
         };
     };
     return (installed) => {
@@ -161,17 +166,11 @@ export function appSurfaceCache(host) {
     };
 }
 /** Derive the current principal's admitted App modules and grants. */
-export async function oysterAppSnapshot(host, surfaces, principal, installations, access, sessionId, 
-/** Shares one tool-family listing per Instance across the two
- * `appModules` passes one `oysterAppMethods` call can make (the eager
- * grants/version pass, and a session-scoped re-derivation); never shared
- * across separate calls, so it never serves another request's listing. */
-familyListingCache = new Map()) {
+export async function oysterAppSnapshot(host, surfaces, principal, installations, access, sessionId, mode) {
     const limits = guestLimits(host.guestLimits);
     const generation = await host.installations.generation();
     const caller = invocationCallerContext(principal, host.computerId ?? null);
     const { actor } = principal;
-    const visitor = actor.kind === "visitor";
     const modules = {};
     const levels = {};
     const fences = {};
@@ -179,8 +178,6 @@ familyListingCache = new Map()) {
     for (const installation of installations) {
         if (installation.status !== "enabled" || installation.instanceId === null)
             continue;
-        if (visitor && installation.visibility !== "public")
-            continue;
         const captured = capturedAccessFor(access, installation.installationId);
         // A key that holds no grant for this installation never sees it listed
         // at all. An Agent's one blanket policy either covers every
@@ -191,14 +188,14 @@ familyListingCache = new Map()) {
         const surface = await surfaces(installation.release);
         if (surface === null)
             continue;
-        const { release, api, declaredOperations, toolSchemas } = surface;
+        const { release, api, declaredOperations, methods } = surface;
         const instanceId = installation.instanceId;
         const declaration = release.declaration ?? emptyAppDeclaration;
         const id = `oyster-app:${installation.installationId}`;
-        // A member/owner/visitor, or an Agent/key with no captured access,
-        // defaults to "write" here exactly as every module always did before:
-        // the deeper gate (`admits`), not this coarse Mycelium-level grant, is
-        // what actually enforces visitor/role ceilings. Only a captured
+        // A member/owner, or an Agent/key with no captured access, defaults to
+        // "write" here exactly as every module always did before: the deeper gate
+        // (`admits`), not this coarse Mycelium-level grant, is what actually
+        // enforces role ceilings. Only a captured
         // Agent/key access with its own level narrows this.
         levels[id] = captured?.level ?? "write";
         // Shared by every operation this installation exposes (ordinary methods
@@ -245,7 +242,6 @@ familyListingCache = new Map()) {
             const decision = admits({
                 installation: {
                     status: installation.status,
-                    visibility: installation.visibility,
                     instanceId: installation.instanceId,
                     authority: installation.authority,
                     artifactDigest: installation.release.artifact.artifactDigest,
@@ -268,7 +264,7 @@ familyListingCache = new Map()) {
             }, { kind: "method", name, input: json, via: "mcp" });
             if (decision.kind === "refused")
                 throw new AppMethodRefused(decision.code);
-            const result = await host.instances.get(instanceId, limits).call(await admittedMethodCallerFacts(host, installation, release, caller, decision.grants, { name, effect }, [], sessionId, actor.kind === "agent" && captured !== null
+            const result = await host.instances.get(instanceId, limits).call(await admittedMethodCallerFacts(host, installation, release, caller, decision.grants, { name, effect }, [], sessionId ?? undefined, actor.kind === "agent" && captured !== null
                 ? {
                     policyRevision: captured.revision,
                     grantorMemberId: captured.grantedBy,
@@ -283,20 +279,42 @@ familyListingCache = new Map()) {
         const operationEffects = {};
         effects[id] = operationEffects;
         let familyFacts = null;
-        const toolOperations = Object.entries(toolSchemas)
-            .filter(([, method]) => !visitor || method.effect === "read")
-            .map(([name, method]) => {
+        const outputFor = (declared, effect) => mode === "approval" && effect !== "read"
+            ? approvalOutput(declared)
+            : declared;
+        const runOperation = async (name, effect, input, context, direct) => {
+            if (mode === "direct" || effect === "read")
+                return direct();
+            if (host.approvals === undefined)
+                return { kind: "refused", reason: "not-granted" };
+            const fence = fences[id];
+            if (fence === undefined)
+                throw new Error("App snapshot has no operation authority fence");
+            const result = await host.approvals.submit({
+                actor,
+                installationId: installation.installationId,
+                sessionId,
+                operation: name,
+                access: effect,
+                authorityFence: fence,
+                idempotencyKey: await sha256(new TextEncoder().encode(JSON.stringify([
+                    context.executionId,
+                    context.toolCallId,
+                    context.operationOrdinal ?? 0,
+                ]))),
+                input,
+            });
+            return result.kind === "applied" ? result.output : result;
+        };
+        const toolOperations = Object.entries(methods).map(([name, method]) => {
             operationEffects[name] = method.effect;
             const appMethod = Mycelium.operation({
                 replay: "unsafe",
                 access: method.effect === "read" ? "read" : "write",
                 description: `${method.description}\nEffect: ${method.effect}.`,
-                input: method.input,
-                output: method.output,
-                execute: async (input, context) => {
-                    const value = await callAppMethod(name, method.effect, input, context.signal);
-                    return method.output.parse(value);
-                },
+                input: appJsonSchema(method.input),
+                output: outputFor(appJsonSchema(method.output), method.effect),
+                execute: (input, context) => runOperation(name, method.effect, input, context, () => callAppMethod(name, method.effect, input, context.signal)),
             });
             return [name, appMethod];
         });
@@ -305,20 +323,14 @@ familyListingCache = new Map()) {
         // that listing and compiles its schemas; it supplies no admission or
         // invocation arguments by design, so the host supplies both here, reusing
         // the exact same `callAppMethod` gate as every other method on this App.
-        // A visitor who cannot see non-read ordinary methods cannot see these
-        // either; a caller the App itself refuses to list for (stale authority,
-        // an unapproved App-tool policy, a missing capability grant) sees none.
+        // A caller the App itself refuses to list for (stale authority, an
+        // unapproved App-tool policy, a missing capability grant) sees none.
         const family = api.toolFamily;
-        const familyOperations = family === undefined ||
-            (visitor && api.methods[family.call]?.effect !== "read")
+        const familyOperations = family === undefined
             ? []
             : await (async () => {
                 try {
-                    let listing = familyListingCache.get(instanceId);
-                    if (listing === undefined) {
-                        listing = await callAppMethod(family.list, "read", {});
-                        familyListingCache.set(instanceId, listing);
-                    }
+                    const listing = await callAppMethod(family.list, "read", {});
                     const compiled = appToolFamilySchemas(api, listing);
                     if (compiled === null)
                         return [];
@@ -331,21 +343,20 @@ familyListingCache = new Map()) {
                             access: compiled.effect === "read" ? "read" : "write",
                             description: `${tool.description}\nEffect: ${compiled.effect}.`,
                             input: tool.input,
-                            output: tool.output,
-                            execute: async (input, context) => {
+                            output: outputFor(tool.output, compiled.effect),
+                            execute: (input, context) => runOperation(`${compiled.name}.${tool.row.tool}`, compiled.effect, input, context, () => {
                                 // The declaring App owns every field below except
                                 // `requestId` (this call's own identity) and `input`
                                 // (the caller's tool-shaped payload): `tool.row.call` is
                                 // opaque data this host never reads into or defaults.
                                 // `requestId` is last: a row whose own `call` data named
                                 // that key would otherwise replay the same run forever.
-                                const value = await callAppMethod(compiled.call, compiled.effect, {
+                                return callAppMethod(compiled.call, compiled.effect, {
                                     ...tool.row.call,
                                     input,
                                     requestId: toolFamilyCallIds.call.generate(),
                                 }, context.signal);
-                                return tool.output.parse(value);
-                            },
+                            }),
                         });
                         return [
                             `${compiled.name}.${tool.row.tool}`,
@@ -404,8 +415,7 @@ function serializableAccess(access) {
 /**
  * Capture installed App methods for MCP or agents as one principal-scoped source.
  * Enabled installations become `env.<APP>` modules using the Instance call path; a dotted method such as `repos.list` is `env.<APP>.repos.list()`.
- * Visitors see only public read methods; owners see every discoverable
- * method. A key sees only the installations its own grants admit, each at
+ * Owners see every discoverable method. A key sees only the installations its own grants admit, each at
  * the level (`read`/`write`) those grants give it; Mycelium itself refuses a
  * write call up front when the module's own grant is `read`
  * (`mycelium/src/access.ts`). Call again to capture changes to Releases,
@@ -413,11 +423,18 @@ function serializableAccess(access) {
  */
 export async function oysterAppMethods(host, principal, access, surfaces, preloadedInstallations) {
     const installations = preloadedInstallations ?? (await host.installations.list());
-    // Shared so a session-scoped re-derivation below reuses this call's tool-
-    // family listings instead of asking each Instance for them twice.
-    const familyListingCache = new Map();
-    const initial = await oysterAppSnapshot(host, surfaces, principal, installations, access, undefined, familyListingCache);
-    const modules = admittedAppModules(host, principal, initial, null);
+    // Grants need only admitted Release data, not modules, fences or listings.
+    const grants = {};
+    for (const installation of installations) {
+        if (installation.status !== "enabled" || installation.instanceId === null)
+            continue;
+        const captured = capturedAccessFor(access, installation.installationId);
+        if (access?.kind === "key" && captured === null)
+            continue;
+        if ((await surfaces(installation.release)) !== null)
+            grants[`oyster-app:${installation.installationId}`] =
+                captured?.level ?? "write";
+    }
     const version = await sha256(new TextEncoder().encode(JSON.stringify({
         access: serializableAccess(access),
         installations: [...installations]
@@ -429,20 +446,17 @@ export async function oysterAppMethods(host, principal, access, surfaces, preloa
             installation.release.artifact.artifactDigest,
             installation.authority.authorityVersion,
             installation.status,
-            installation.visibility,
         ]),
     })));
     return {
         id: "oyster-apps",
-        grants: initial.levels,
+        grants,
         acquire: async ({ signal, session }) => {
             signal.throwIfAborted();
-            const acquiredModules = session === undefined
-                ? modules
-                : admittedAppModules(host, principal, await oysterAppSnapshot(host, surfaces, principal, installations, access, session.sessionId, familyListingCache), session.sessionId);
+            const snapshot = await oysterAppSnapshot(host, surfaces, principal, installations, access, session?.sessionId ?? null, "approval");
             signal.throwIfAborted();
             return {
-                snapshot: { version, modules: acquiredModules },
+                snapshot: { version, modules: Object.values(snapshot.modules) },
                 release: () => Promise.resolve(),
             };
         },
@@ -501,14 +515,14 @@ export function oysterMcpCatalogLoad(host) {
             // expired or suspended key: that keeps every installation invisible
             // (via appModules' own `access?.kind === "key"` check) rather than
             // falling through to the member/owner default of "write" below.
-            const key = (await host.keys?.live(actor.keyId)) ?? null;
+            const ports = hostAuthorityPorts(host);
+            const authority = await authorityOf(principal, ports);
             const byInstallation = new Map();
-            if (key !== null)
-                for (const installation of installations) {
-                    const level = keyAppAccess(key, installation.installationId);
-                    if (level !== null)
-                        byInstallation.set(installation.installationId, level);
-                }
+            for (const installation of installations) {
+                const level = await appToolAccess(authority, installation.installationId, ports);
+                if (level !== null)
+                    byInstallation.set(installation.installationId, level);
+            }
             access = { kind: "key", keyId: actor.keyId, byInstallation };
         }
         const apps = await oysterAppMethods(host, principal, access, surfaces, installations);
@@ -565,12 +579,20 @@ export function oysterMcpCatalogLoad(host) {
         const workflowGrants = control == null ? {} : { [WORKFLOW_CONTROL_MODULE_ID]: "write" };
         if (computer === null)
             return {
-                instructions: "Installed Apps on this Oyster. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). Use forage.search / forage.describe to find methods.",
+                instructions: [
+                    "Installed Apps on this Oyster. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}).",
+                    forageDiscoveryInstructions,
+                    appApprovalInstructions,
+                ].join("\n"),
                 grants: { ...apps.grants, ...workflowGrants, ...fleetGrants },
                 sources: [apps, ...workflowSources, ...fleetSource],
             };
         return {
-            instructions: 'Installed Apps and this Oyster\'s Computer. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). The Computer is env.computers.workspace, e.g. env.computers.workspace.exec({command: "ls"}). Use forage.search / forage.describe to find methods.',
+            instructions: [
+                'Installed Apps and this Oyster\'s Computer. Each App is env.<APP>; dotted method names are nested properties, e.g. env.BONSAI.repos.list({}). The Computer is env.computers.workspace, e.g. env.computers.workspace.exec({command: "ls"}).',
+                forageDiscoveryInstructions,
+                appApprovalInstructions,
+            ].join("\n"),
             grants: {
                 ...apps.grants,
                 ...computer.grants,
@@ -581,88 +603,16 @@ export function oysterMcpCatalogLoad(host) {
         };
     };
 }
-function admittedAppModules(host, principal, snapshot, sessionId) {
-    return Object.entries(snapshot.modules).map(([id, raw]) => {
-        const { description: moduleDescription, ...descriptor } = describeModule(raw);
-        const installationId = id.slice("oyster-app:".length);
-        const moduleMetadata = {};
-        if (moduleDescription !== undefined)
-            moduleMetadata.description = moduleDescription;
-        return Mycelium.module({
-            ...descriptor,
-            ...moduleMetadata,
-            id,
-            name: appBindingName(installationId),
-            operations: Object.fromEntries(Object.entries(descriptor.operations).map(([path, rawOperation]) => {
-                const { description: operationDescription, ...operation } = rawOperation;
-                const effect = snapshot.effects[id]?.[path];
-                const fence = snapshot.fences[id];
-                if (effect === undefined || fence === undefined)
-                    throw new Error("App snapshot has no operation authority facts");
-                const declaredOutput = operation.output ?? true;
-                // Decode each document at its own root before composing: a nested
-                // JSON Schema document's root-relative $refs would otherwise escape.
-                const declared = jsonSchemaToZod(declaredOutput);
-                const output = effect === "read"
-                    ? declared
-                    : z.union([
-                        declared,
-                        jsonSchemaToZod(Schema.toStandardJSONSchemaV1(PendingApprovalSchema)["~standard"].jsonSchema.output({ target: "draft-2020-12" })),
-                        jsonSchemaToZod(Schema.toStandardJSONSchemaV1(ApprovalRefusalSchema)["~standard"].jsonSchema.output({ target: "draft-2020-12" })),
-                    ]);
-                const outputValidator = z.intersection(output, z.json());
-                const operationMetadata = {};
-                if (operationDescription !== undefined)
-                    operationMetadata.description = operationDescription;
-                // App methods are never replayed by the host: a write goes through
-                // its approval record, and even a read may have App-side effects.
-                const appOperation = Mycelium.operation({
-                    ...operation,
-                    ...operationMetadata,
-                    replay: "unsafe",
-                    access: effect === "read" ? "read" : "write",
-                    input: z.intersection(jsonSchemaToZod(operation.input), z.json()),
-                    output: {
-                        "~standard": {
-                            ...outputValidator["~standard"],
-                            // As appMethodSchemas does, describe the JSON contract
-                            // without nesting another redundant recursive JSON guard.
-                            jsonSchema: output["~standard"].jsonSchema,
-                        },
-                    },
-                    execute: async (input, context) => {
-                        if (effect === "read")
-                            return z
-                                .json()
-                                .parse(await invokeModuleOperation(raw, path, input, context));
-                        if (principal.actor.kind === "visitor")
-                            return { kind: "refused", reason: "not-granted" };
-                        if (host.approvals === undefined)
-                            return { kind: "refused", reason: "not-granted" };
-                        // Mycelium numbers each operation call within one execute and
-                        // replays the same sequence; a direct call is its own execution.
-                        const ordinal = context.operationOrdinal ?? 0;
-                        const result = await host.approvals.submit({
-                            actor: principal.actor,
-                            installationId,
-                            sessionId,
-                            operation: path,
-                            access: effect,
-                            authorityFence: fence,
-                            idempotencyKey: await sha256(new TextEncoder().encode(JSON.stringify([
-                                context.executionId,
-                                context.toolCallId,
-                                ordinal,
-                            ]))),
-                            input,
-                        });
-                        return z
-                            .json()
-                            .parse(result.kind === "applied" ? result.output : result);
-                    },
-                });
-                return [path, appOperation];
-            })),
-        });
-    });
+const isPendingApproval = Schema.is(PendingApprovalSchema);
+const isApprovalRefusal = Schema.is(ApprovalRefusalSchema);
+/** Approval results are a host contract, not part of each App's declaration. */
+function approvalOutput(declared) {
+    return {
+        "~standard": {
+            ...declared["~standard"],
+            validate: (value) => isPendingApproval(value) || isApprovalRefusal(value)
+                ? { value }
+                : declared["~standard"].validate(value),
+        },
+    };
 }

package/dist/page/agent-browser.d.ts

@@ -0,0 +1,15 @@
+import type { AgentSessionSelection, CapabilityDirectory } from "@fungi.computer/agar";
+import { type WhistleRuntime } from "@fungi.computer/whistle";
+/** One admitted page's live windows and selected Agent Session, never a global catalog. */
+export declare class OysterAgentBrowserHost {
+    #private;
+    constructor(signal: AbortSignal);
+    /** Borrow a Release-validated window view only for this exact frame lifetime. */
+    mount(frame: HTMLIFrameElement, commands: Pick<WhistleRuntime, "snapshot" | "execute">): () => void;
+    /** A departing or deselecting window cannot close a different selection. */
+    release(frame: HTMLIFrameElement): void;
+    /** Release this page's window registrations and selected Agent connection. */
+    dispose(): void;
+    /** Admit the selected Agent through the reporting App's existing write door. */
+    report(frame: HTMLIFrameElement, selection: AgentSessionSelection | null, capabilities: CapabilityDirectory): Promise<void>;
+}

package/dist/page/agent-browser.js

@@ -0,0 +1,162 @@
+import { agentManage, agentSessionWrite, openAppAgent, } from "@fungi.computer/agar/agents";
+import { correlationKey } from "@fungi.computer/cairn";
+import { connectBrowser, UiBrowserError, } from "@fungi.computer/knapsack/ui/browser";
+import { sameWhistleCommand, } from "@fungi.computer/whistle";
+import { EventSource } from "eventsource";
+const detachedOutcome = {
+    status: "failed",
+    error: {
+        code: "window_command_detached",
+        message: "The window or selected Session closed after dispatch; completion is unknown",
+    },
+};
+function windowCommand(window, command) {
+    return { namespace: `${command.namespace}@${window.id}`, id: command.id };
+}
+/** One admitted page's live windows and selected Agent Session, never a global catalog. */
+export class OysterAgentBrowserHost {
+    #windows = new Map();
+    #active;
+    #disposed = false;
+    constructor(signal) {
+        if (signal.aborted)
+            this.dispose();
+        else
+            signal.addEventListener("abort", () => {
+                this.dispose();
+            }, { once: true });
+    }
+    /** Borrow a Release-validated window view only for this exact frame lifetime. */
+    mount(frame, commands) {
+        if (this.#disposed)
+            return () => undefined;
+        if (this.#windows.has(frame))
+            throw new Error("Agent command window is already mounted");
+        const window = { id: correlationKey(), commands };
+        this.#windows.set(frame, window);
+        return () => {
+            if (this.#windows.get(frame) !== window)
+                return;
+            this.#windows.delete(frame);
+            this.release(frame);
+        };
+    }
+    /** A departing or deselecting window cannot close a different selection. */
+    release(frame) {
+        if (this.#active?.frame !== frame)
+            return;
+        const previous = this.#active;
+        this.#active = undefined;
+        previous.close();
+    }
+    /** Release this page's window registrations and selected Agent connection. */
+    dispose() {
+        this.#disposed = true;
+        this.#windows.clear();
+        if (this.#active !== undefined)
+            this.release(this.#active.frame);
+    }
+    #commands(selection) {
+        const live = () => this.#active === selection && !this.#disposed;
+        return {
+            snapshot: () => ({
+                bindings: [],
+                palette: [],
+                slash: [],
+                help: [],
+                menu: [],
+                agent: live()
+                    ? [...this.#windows.values()].flatMap((window) => window.commands.snapshot().agent.map((row) => ({
+                        ...row,
+                        command: windowCommand(window, row.command),
+                    })))
+                    : [],
+            }),
+            execute: async (command, input) => {
+                if (!live() || input.origin !== "agent")
+                    return { status: "missing" };
+                for (const [frame, window] of this.#windows) {
+                    const row = window.commands
+                        .snapshot()
+                        .agent.find((row) => sameWhistleCommand(windowCommand(window, row.command), command));
+                    if (row === undefined)
+                        continue;
+                    // The mounted view remains the execution owner: it checks the live
+                    // Agent projection and invokes only this frame's Agar connection.
+                    const attached = () => live() && this.#windows.get(frame) === window;
+                    try {
+                        const outcome = await window.commands.execute(row.command, input);
+                        // Closing does not promise to undo an already dispatched effect,
+                        // but its old result must never settle as a replacement window's.
+                        return attached() ? outcome : detachedOutcome;
+                    }
+                    catch (cause) {
+                        if (!attached())
+                            return detachedOutcome;
+                        throw cause;
+                    }
+                }
+                return { status: "missing" };
+            },
+        };
+    }
+    /** Admit the selected Agent through the reporting App's existing write door. */
+    async report(frame, selection, capabilities) {
+        if (this.#disposed || !this.#windows.has(frame))
+            return;
+        // A read-only Session handle cannot open or displace this connection.
+        // The server re-admits the principal on every transport request.
+        if (!capabilities.has(agentSessionWrite) && !capabilities.has(agentManage))
+            return;
+        if (selection === null) {
+            this.release(frame);
+            return;
+        }
+        if (this.#active !== undefined)
+            this.release(this.#active.frame);
+        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: this.#commands(active),
+                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;
+        }
+    }
+}

package/dist/page/app-permissions-port.d.ts

@@ -0,0 +1,3 @@
+import { type AppPermissionsPort } from "../apps/permissions.js";
+/** Owner-direct transport over Oyster's existing generation/version/digest-fenced grant routes. */
+export declare function createOysterAppPermissionsPort(): AppPermissionsPort;

package/dist/page/app-permissions-port.js

@@ -0,0 +1,43 @@
+import { appPermissionPageSchema, permissionSaveSchema, } from "../apps/permissions.js";
+/** Owner-direct transport over Oyster's existing generation/version/digest-fenced grant routes. */
+export function createOysterAppPermissionsPort() {
+    const path = (appKey) => `/api/installations/${encodeURIComponent(appKey)}/grants`;
+    const request = (url, init) => fetch(url, {
+        ...init,
+        headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+        },
+        credentials: "same-origin",
+        cache: "no-store",
+        redirect: "error",
+    });
+    return {
+        read: async (appKey) => {
+            const response = await request(path(appKey));
+            if (response.status === 404)
+                return "unavailable";
+            if (!response.ok)
+                throw new Error("Permissions could not be loaded");
+            return appPermissionPageSchema.parse(await response.json());
+        },
+        submit: async (appKey, pins, changes) => {
+            const response = await request(path(appKey), {
+                method: "PUT",
+                body: JSON.stringify(permissionSaveSchema.parse({
+                    ...pins,
+                    command: { kind: "change-grants", changes },
+                })),
+            });
+            if (response.ok)
+                return "accepted";
+            if (response.status === 409)
+                return "stale";
+            if (response.status === 404)
+                return "unavailable";
+            if (response.status >= 500)
+                return "unconfirmed";
+            return "refused";
+        },
+    };
+}