@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/host.js

@@ -0,0 +1,732 @@
+import * as Predicate from "effect/Predicate";
+import * as Schema from "effect/Schema";
+/**
+ * WHY: the host adapter is the sole authority for iframe identity, epochs,
+ * and Cap'n Web resource lifetime; apps never authorize themselves (2026-08-27).
+ */
+import { newMessagePortRpcSession, RpcStub, RpcTarget, } from "@fungi.computer/capnweb";
+import { WhistleActionError } from "@fungi.computer/whistle";
+import { AppError } from "./errors.js";
+import { reportCatchFailure } from "./failure.js";
+import { disposeRpcValue } from "./internal/capabilities.js";
+import { disconnectHost } from "./internal/disconnect-host.js";
+import { APP_CONNECT_TYPE, APP_PROTOCOL_VERSION, APP_READY_TYPE, } from "./internal/protocol.js";
+import { callRpc, rpcFailure, rpcSuccess, } from "./internal/result.js";
+import { parseBrowserAction, parseChordInvocation, parseCommandResultRpc, parseBackDecisionResult, parseCloseDecisionResult, parseCommand, parseCommandId, parseConnectRequest, parseContextFact, parseFocus, parseAgentSessionSelection, parseLocalHostBootstrap, parseHostLifecycleFact, parseNavigation, parseNavigationState, parseStatusAction, parseStatusItems, parsePermissionRequest, parseReady, parseReservedChordsFact, parseThemeFact, parseToast, parseVoidResult, } from "./internal/schemas.js";
+import { createTerminalGate, } from "./internal/terminal-gate.js";
+/** One pending or live mount belongs to each iframe WindowProxy. */
+const liveMounts = new WeakMap();
+const retainedCommandHandlerSchema = Schema.declare((value) => value instanceof RpcStub);
+class MountedHost extends RpcTarget {
+    epoch;
+    #commands = new Map();
+    #pendingCommands = new Map();
+    #pendingUnregistrations = new Set();
+    #contribution;
+    #sync = Promise.resolve();
+    #connected = false;
+    #disposed = false;
+    #handlers;
+    #launch;
+    #onConnected;
+    #onFatal;
+    constructor(launch, handlers, epoch) {
+        super();
+        this.epoch = epoch;
+        this.#launch = parseLocalHostBootstrap(launch);
+        this.#handlers = handlers;
+    }
+    connect(value) {
+        try {
+            this.#assertLive();
+            const request = parseConnectRequest(value);
+            if (this.#connected || request.epoch !== this.epoch)
+                throw identityError();
+            this.#connected = true;
+            this.#onConnected?.();
+            return Promise.resolve(rpcSuccess(this.#launch));
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    async invokeReservedChord(id, repeat) {
+        return this.#call(() => this.#handlers.invokeReservedChord(parseChordInvocation({ id, repeat })));
+    }
+    isConnected() {
+        return this.#connected;
+    }
+    onConnected(callback) {
+        this.#onConnected = callback;
+    }
+    onFatal(callback) {
+        this.#onFatal = callback;
+    }
+    async requestComputerChoice() {
+        return this.#call(() => {
+            if (this.#handlers.requestComputerChoice === undefined)
+                throw new AppError("Computer choice is unavailable in this host", {
+                    code: "CAPABILITY_DENIED",
+                    retryable: false,
+                });
+            return this.#handlers.requestComputerChoice();
+        });
+    }
+    async requestBrowserAction(value) {
+        return this.#answer(async () => {
+            const parsed = parseBrowserAction(value);
+            if (parsed.kind === "refused")
+                return parsed;
+            return (this.#handlers.requestBrowserAction?.(parsed) ?? {
+                kind: "refused",
+                reason: "unavailable",
+            });
+        });
+    }
+    async openNavigation(value) {
+        return this.#call(() => this.#handlers.openNavigation(parseNavigation(value)));
+    }
+    async openTeamBilling() {
+        return this.#call(() => {
+            if (this.#handlers.openTeamBilling === undefined)
+                throw new AppError("Billing is unavailable in this host", {
+                    code: "CAPABILITY_DENIED",
+                    retryable: false,
+                });
+            return this.#handlers.openTeamBilling();
+        });
+    }
+    async openDesktopSettings() {
+        return this.#call(() => {
+            if (this.#handlers.openDesktopSettings === undefined)
+                throw new AppError("Desktop settings are unavailable in this host", {
+                    code: "CAPABILITY_DENIED",
+                    retryable: false,
+                });
+            return this.#handlers.openDesktopSettings();
+        });
+    }
+    async requestAppPermissions(value) {
+        return this.#answer(() => {
+            if (this.#handlers.requestAppPermissions === undefined)
+                throw new AppError("App permissions are unavailable in this host", {
+                    code: "CAPABILITY_DENIED",
+                    retryable: false,
+                });
+            return this.#handlers.requestAppPermissions(parsePermissionRequest(value));
+        });
+    }
+    async registerCommand(value, handler) {
+        let registration;
+        try {
+            registration = this.#admitCommand(value, handler);
+            await this.#registerPendingCommand(registration);
+            return rpcSuccess(Object.freeze({ commandId: registration.commandId }));
+        }
+        catch (cause) {
+            if (registration)
+                this.#discardPending(registration);
+            return rpcFailure(cause);
+        }
+    }
+    async reportFocus(value) {
+        return this.#call(() => this.#handlers.reportFocus(parseFocus(value)));
+    }
+    async reportStatus(value) {
+        return this.#call(() => {
+            const items = parseStatusItems(value);
+            return this.#handlers.reportStatus?.(items) ?? Promise.resolve();
+        });
+    }
+    async reportNavigation(value) {
+        return this.#call(() => {
+            const state = parseNavigationState(value);
+            return this.#handlers.reportNavigation?.(state) ?? Promise.resolve();
+        });
+    }
+    async reportAgentSessionSelection(value) {
+        return this.#call(() => this.#handlers.reportAgentSessionSelection(parseAgentSessionSelection(value)));
+    }
+    async showToast(value) {
+        return this.#call(() => this.#handlers.showToast(parseToast(value)));
+    }
+    [Symbol.dispose]() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        for (const command of this.#commands.values()) {
+            try {
+                this.#release(command);
+            }
+            catch (cause) {
+                console.warn("App host command cleanup failed", cause);
+            }
+        }
+        this.#commands.clear();
+        for (const command of this.#pendingCommands.values()) {
+            try {
+                this.#release(command);
+            }
+            catch (cause) {
+                console.warn("App host pending command cleanup failed", cause);
+            }
+        }
+        this.#pendingCommands.clear();
+        this.#pendingUnregistrations.clear();
+        this.#releaseContribution();
+    }
+    unregisterCommand(value) {
+        try {
+            this.#assertConnected();
+            const commandId = parseCommandId(value);
+            const command = this.#commands.get(commandId);
+            if (!command)
+                throw new AppError("Unknown command", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            if (this.#pendingUnregistrations.has(commandId))
+                throw new AppError("Command is already unregistering", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            this.#pendingUnregistrations.add(commandId);
+            return this.#syncUnregistration(commandId, command)
+                .then(() => {
+                this.#pendingUnregistrations.delete(commandId);
+                if (this.#commands.get(commandId) === command) {
+                    this.#commands.delete(commandId);
+                    this.#release(command);
+                }
+                return rpcSuccess(undefined);
+            })
+                .catch((cause) => {
+                this.#pendingUnregistrations.delete(commandId);
+                return rpcFailure(cause);
+            });
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    #assertConnected() {
+        this.#assertLive();
+        if (!this.#connected)
+            throw disconnected();
+    }
+    #assertLive() {
+        if (this.#disposed)
+            throw disconnected();
+    }
+    #admitCommand(value, handler) {
+        this.#assertConnected();
+        const command = parseCommand(value);
+        const commandId = `${this.#launch.identity.appId}/${command.id}`;
+        if (this.#commands.size + this.#pendingCommands.size >= 128 ||
+            this.#commands.has(commandId) ||
+            this.#pendingCommands.has(commandId))
+            throw new AppError("Command already registered", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        const retainedCommand = {
+            callback: duplicateHandler(handler),
+            requests: new Set(),
+            command,
+        };
+        this.#pendingCommands.set(commandId, retainedCommand);
+        return { commandId, command: retainedCommand };
+    }
+    #discardPending(registration) {
+        const { commandId, command } = registration;
+        if (this.#pendingCommands.get(commandId) !== command)
+            return;
+        this.#pendingCommands.delete(commandId);
+        this.#release(command);
+    }
+    async #call(operation) {
+        return this.#answer(async () => {
+            await operation();
+            return undefined;
+        });
+    }
+    async #answer(operation) {
+        try {
+            this.#assertConnected();
+            return rpcSuccess(await operation());
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
+    #registerPendingCommand(registration) {
+        return this.#enqueueSync(async () => {
+            const { commandId, command } = registration;
+            this.#assertConnected();
+            if (this.#pendingCommands.get(commandId) !== command)
+                throw disconnected();
+            const next = new Map(this.#commands);
+            next.set(commandId, command);
+            try {
+                await this.#applyCommands(next);
+            }
+            catch (cause) {
+                this.#discardPending(registration);
+                throw cause;
+            }
+            if (this.#disposed || this.#pendingCommands.get(commandId) !== command)
+                throw disconnected();
+            this.#pendingCommands.delete(commandId);
+            this.#commands.set(commandId, command);
+        });
+    }
+    #syncUnregistration(commandId, command) {
+        return this.#enqueueSync(async () => {
+            this.#assertConnected();
+            if (this.#commands.get(commandId) !== command)
+                throw disconnected();
+            const next = new Map(this.#commands);
+            next.delete(commandId);
+            try {
+                await this.#applyCommands(next, next);
+            }
+            catch (cause) {
+                if (this.#commands.get(commandId) === command) {
+                    this.#commands.delete(commandId);
+                    this.#release(command);
+                }
+                throw cause;
+            }
+        });
+    }
+    #enqueueSync(operation) {
+        const queued = this.#sync.then(operation);
+        this.#sync = queued.catch((cause) => {
+            reportCatchFailure("host.command-sync", cause);
+        });
+        return queued;
+    }
+    async #applyCommands(next, recovery = this.#commands) {
+        const commands = [...next.values()].map((retained) => retained.command);
+        if (this.#contribution === undefined) {
+            if (commands.length === 0)
+                return;
+            await this.#registerContribution(commands);
+            return;
+        }
+        const contribution = this.#contribution;
+        try {
+            contribution.update(commands);
+            if (this.#disposed || this.#contribution !== contribution)
+                throw disconnected();
+        }
+        catch (cause) {
+            this.#releaseContribution();
+            try {
+                await this.#registerContribution([...recovery.values()].map((retained) => retained.command));
+            }
+            catch (recoveryCause) {
+                this.#abandonCommands();
+                this.#onFatal?.();
+                throw recoveryCause;
+            }
+            throw cause;
+        }
+    }
+    async #registerContribution(commands) {
+        if (commands.length === 0)
+            return;
+        const contribution = await this.#handlers.registerCommands({
+            commands,
+            invoke: (id, input) => {
+                const commandId = `${this.#launch.identity.appId}/${id}`;
+                const command = this.#commands.get(commandId);
+                if (command === undefined)
+                    throw disconnected();
+                return this.#invoke(command.callback, commandId, input);
+            },
+        });
+        if (!Predicate.isObject(contribution))
+            throw new AppError("Host command registration returned no lease", {
+                code: "HOST_FAILURE",
+                retryable: false,
+            });
+        if (!Predicate.isFunction(contribution.update) ||
+            !Predicate.isFunction(contribution.dispose)) {
+            throw new AppError("Host command registration returned an invalid lease", {
+                code: "HOST_FAILURE",
+                retryable: false,
+            });
+        }
+        if (this.#disposed || !this.#connected) {
+            contribution.dispose();
+            throw disconnected();
+        }
+        this.#contribution = contribution;
+    }
+    #abandonCommands() {
+        for (const command of this.#commands.values())
+            this.#release(command);
+        this.#commands.clear();
+        for (const command of this.#pendingCommands.values())
+            this.#release(command);
+        this.#pendingCommands.clear();
+        this.#pendingUnregistrations.clear();
+    }
+    #cancel(callback, requestId) {
+        try {
+            void callRpc(callback.cancel(requestId), parseVoidResult).catch((cause) => {
+                console.warn("App host command cancellation failed", cause);
+                this.#onFatal?.();
+            });
+        }
+        catch (cause) {
+            console.warn("App host command cancellation failed", cause);
+            this.#onFatal?.();
+        }
+    }
+    async #invoke(callback, commandId, input) {
+        this.#assertConnected();
+        const command = this.#commands.get(commandId);
+        if (command?.callback !== callback)
+            throw disconnected();
+        if (command.requests.size >= 64) {
+            throw new AppError("Too many command requests", {
+                code: "HOST_FAILURE",
+                retryable: true,
+            });
+        }
+        if (input.signal?.aborted)
+            throw cancelled();
+        const requestId = newRequestId();
+        command.requests.add(requestId);
+        const cancel = () => {
+            this.#cancel(callback, requestId);
+        };
+        input.signal?.addEventListener("abort", cancel, { once: true });
+        try {
+            const invocation = {
+                commandId,
+                origin: input.origin,
+                requestId,
+            };
+            if (input.arguments !== undefined)
+                Object.assign(invocation, { arguments: input.arguments });
+            const outcome = await callRpc(callback.invoke(invocation), parseCommandResultRpc);
+            if (outcome.status === "failed")
+                throw new WhistleActionError(outcome.error.code, outcome.error.message, outcome.error.details);
+            return outcome.result;
+        }
+        finally {
+            input.signal?.removeEventListener("abort", cancel);
+            command.requests.delete(requestId);
+        }
+    }
+    #release(command) {
+        for (const requestId of command.requests)
+            this.#cancel(command.callback, requestId);
+        command.requests.clear();
+        disposeRpcValue(command.callback);
+    }
+    #releaseContribution() {
+        const contribution = this.#contribution;
+        this.#contribution = undefined;
+        if (contribution === undefined)
+            return;
+        try {
+            contribution.dispose();
+        }
+        catch (cause) {
+            console.warn("App host command contribution cleanup failed", cause);
+        }
+    }
+}
+class PendingHostMount {
+    options;
+    origin;
+    #gate;
+    #host;
+    #reject;
+    #resolve;
+    constructor(options, origin) {
+        this.options = options;
+        this.origin = origin;
+        this.#gate = createTerminalGate({
+            dispose: () => {
+                this.#disposeHost();
+            },
+            onDisconnect: options.handlers.onDisconnect,
+            reject: (error) => this.#reject?.(error),
+            release: () => {
+                this.#releaseMount();
+            },
+        });
+    }
+    start() {
+        return new Promise((resolve, reject) => {
+            this.#resolve = resolve;
+            this.#reject = reject;
+            this.options.hostWindow.addEventListener("message", this.#onMessage);
+            this.options.signal?.addEventListener("abort", this.#onAbort, {
+                once: true,
+            });
+        });
+    }
+    #disposeHost() {
+        try {
+            this.#host?.dispose();
+        }
+        finally {
+            this.#releaseMount();
+        }
+    }
+    #fail(error) {
+        this.#stopWaiting();
+        // Publication is a one-way door. A failure after it must use the
+        // terminal path so disposal and notification remain exactly-once.
+        if (this.#gate.isPublished())
+            this.#gate.unexpected();
+        else
+            this.#gate.failBeforePublication(error);
+    }
+    #onAbort = () => {
+        this.#fail(cancelled());
+    };
+    #onMessage = (event) => {
+        if (!isReadyMessage(event.data))
+            return;
+        performance.mark("fungi.app-open.host-ready-received");
+        if (event.source !== this.options.appWindow)
+            return;
+        if (event.origin !== this.origin) {
+            this.#fail(identityError());
+            return;
+        }
+        if (event.ports.length !== 0) {
+            this.#fail(protocolError("The app ready message transferred a port"));
+            return;
+        }
+        try {
+            parseReady(event.data);
+            this.#stopReady();
+            performance.mark("fungi.app-open.host-connect-sent");
+            const session = this.#openSession();
+            this.#postConnect(session.target.epoch, session.transfer);
+            this.#probe(session.client);
+        }
+        catch (cause) {
+            this.#fail(toProtocolError(cause));
+        }
+    };
+    #openSession() {
+        const channel = new MessageChannel();
+        const target = new MountedHost(this.options.launch, this.options.handlers, newEpoch());
+        const client = newMessagePortRpcSession(channel.port1, target);
+        this.#host = createHost({
+            client,
+            onBroken: () => {
+                this.#gate.unexpected();
+            },
+            onDisposed: () => {
+                this.#gate.release();
+                this.#releaseMount();
+            },
+            onGracefulDisconnect: () => this.#gate.graceful(),
+            port: channel.port1,
+            target,
+        });
+        target.onConnected(() => {
+            this.#publish();
+        });
+        return { client, port: channel.port1, target, transfer: channel.port2 };
+    }
+    #postConnect(epoch, transfer) {
+        this.options.appWindow.postMessage({
+            epoch,
+            protocolVersion: APP_PROTOCOL_VERSION,
+            type: APP_CONNECT_TYPE,
+        }, 
+        // Opaque sandbox origins cannot be named as a postMessage target. The
+        // ready door above still binds this transfer to the exact iframe Window.
+        this.origin === "null" ? "*" : this.origin, [transfer]);
+    }
+    #probe(client) {
+        void callRpc(client.updateContext(this.options.launch.context), parseVoidResult).catch((cause) => {
+            if (this.#gate.isPublished())
+                this.#gate.unexpected();
+            else
+                this.#fail(cause instanceof AppError ? cause : disconnected());
+        });
+    }
+    #publish() {
+        if (!this.#host || !this.#gate.publish())
+            return;
+        performance.mark("fungi.app-open.host-connected");
+        this.#stopWaiting();
+        this.#resolve?.(this.#host);
+    }
+    #releaseMount() {
+        if (liveMounts.get(this.options.appWindow) === this)
+            liveMounts.delete(this.options.appWindow);
+    }
+    #stopReady() {
+        this.options.hostWindow.removeEventListener("message", this.#onMessage);
+    }
+    #stopWaiting() {
+        this.#stopReady();
+        this.options.signal?.removeEventListener("abort", this.#onAbort);
+    }
+}
+/** The host-only adapter owns iframe authentication and the hidden Cap'n Web epoch. */
+export function connectAppHost(options) {
+    const origin = expectedOrigin(options.expectedAppOrigin);
+    if (!origin)
+        return Promise.reject(invalidOrigin());
+    if (options.signal?.aborted)
+        return Promise.reject(cancelled());
+    if (liveMounts.has(options.appWindow))
+        return Promise.reject(alreadyMounted());
+    const mount = new PendingHostMount(options, origin);
+    liveMounts.set(options.appWindow, mount);
+    return mount.start();
+}
+function alreadyMounted() {
+    return new AppError("An app host is already live for this iframe", {
+        code: "IDENTITY",
+        retryable: false,
+    });
+}
+function cancelled() {
+    return new AppError("App host connection was cancelled", {
+        code: "CANCELLED",
+        retryable: false,
+    });
+}
+function createFactUpdater(assertLive) {
+    return async (send, fact, parse) => {
+        assertLive();
+        await callRpc(send(parse(fact)), parseVoidResult);
+    };
+}
+function createHost(options) {
+    let disposed = false;
+    const assertLive = () => {
+        if (disposed)
+            throw disconnected();
+    };
+    const dispose = createHostDisposer(options, () => disposed, (value) => {
+        disposed = value;
+    });
+    const onBroken = () => {
+        try {
+            options.onBroken();
+        }
+        finally {
+            dispose();
+        }
+    };
+    options.target.onFatal(onBroken);
+    options.client.onRpcBroken(onBroken);
+    const update = createFactUpdater(assertLive);
+    return Object.freeze({
+        disconnect: (error) => disconnectHost(error, assertLive, options, dispose),
+        dispose,
+        requestClose: async () => {
+            assertLive();
+            return await callRpc(options.client.requestClose(), parseCloseDecisionResult);
+        },
+        requestBack: async () => {
+            assertLive();
+            return await callRpc(options.client.requestBack(), parseBackDecisionResult);
+        },
+        activateStatus: async (action) => {
+            assertLive();
+            return await callRpc(options.client.activateStatus(parseStatusAction(action)), parseBackDecisionResult);
+        },
+        updateContext: (fact) => update((fact) => options.client.updateContext(fact), fact, parseContextFact),
+        reconfigure: async (value) => {
+            assertLive();
+            const context = parseContextFact(value.context);
+            const capabilities = {
+                capabilities: value.capabilities,
+                context,
+            };
+            await callRpc(options.client.reconfigure(capabilities), parseVoidResult);
+        },
+        updateLifecycle: (fact) => update((fact) => options.client.updateLifecycle(fact), fact, parseHostLifecycleFact),
+        updateReservedChords: (fact) => update((fact) => options.client.updateReservedChords(fact), fact, parseReservedChordsFact),
+        updateTheme: (fact) => update((fact) => options.client.updateTheme(fact), fact, parseThemeFact),
+    });
+}
+function createHostDisposer(options, isDisposed, setDisposed) {
+    return () => {
+        if (isDisposed())
+            return;
+        setDisposed(true);
+        // Mark the private epoch terminal before closing transport; Cap'n Web may
+        // synchronously report the close as a break.
+        options.onDisposed();
+        try {
+            options.target[Symbol.dispose]();
+        }
+        finally {
+            disposeRpcValue(options.client);
+            options.port.close();
+        }
+    };
+}
+function disconnected() {
+    return new AppError("The app host is disconnected", {
+        code: "DISCONNECTED",
+        retryable: true,
+    });
+}
+function duplicateHandler(value) {
+    if (!Schema.is(retainedCommandHandlerSchema)(value)) {
+        throw new AppError("Command callback is invalid", {
+            code: "PROTOCOL",
+            retryable: false,
+        });
+    }
+    return value.dup();
+}
+function expectedOrigin(value) {
+    if (value === "null")
+        return value;
+    if (!URL.canParse(value))
+        return undefined;
+    const origin = new URL(value).origin;
+    return origin === value ? origin : undefined;
+}
+const isReadyMessage = Schema.is(Schema.Struct({ type: Schema.Literal(APP_READY_TYPE) }));
+function identityError() {
+    return new AppError("The app connection identity is invalid", {
+        code: "IDENTITY",
+        retryable: false,
+    });
+}
+function invalidOrigin() {
+    return new AppError("expectedAppOrigin must be an origin", {
+        code: "INVALID_ARGUMENT",
+        retryable: false,
+    });
+}
+function newEpoch() {
+    return randomToken(24);
+}
+function newRequestId() {
+    return randomToken(18);
+}
+function protocolError(message) {
+    return new AppError(message, { code: "PROTOCOL", retryable: false });
+}
+function randomToken(bytesLength) {
+    const bytes = new Uint8Array(bytesLength);
+    crypto.getRandomValues(bytes);
+    return Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function toProtocolError(cause) {
+    return cause instanceof AppError
+        ? cause
+        : protocolError("Unable to establish the app host");
+}