@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/internal/app-session.js

@@ -0,0 +1,551 @@
+import * as Schema from "effect/Schema";
+/**
+ * WHY: one session owns stores, callbacks, transport, and terminal teardown;
+ * versioned host facts are applied only at this seam (2026-08-27).
+ */
+import { newMessagePortRpcSession, RpcStub, RpcTarget, } from "@fungi.computer/capnweb";
+import { statusActionAllowed } from "../status.js";
+import { AppError } from "../errors.js";
+import { reportCatchFailure } from "../failure.js";
+import { createLocalBindingState, createReservedChordState, installBrowserBridge, } from "./browser-bridge.js";
+import { installBackInputs, macHistoryKeys } from "./back-inputs.js";
+import { createCapabilityDirectory, disposeRpcValue, } from "./capabilities.js";
+import { createAppCommands } from "./commands.js";
+import { APP_PROTOCOL_VERSION, } from "./protocol.js";
+import { callRpc, rpcFailure, rpcSuccess, unwrapRpcResult } from "./result.js";
+import { parseBrowserAction, parseBrowserActionOutcomeResult, parseBootstrapResult, parseHostReconfiguration, parseContext, parseErrorData, parseFact, parseAgentSessionSelection, parseIdentity, parseLifecycle, parseNavigation, parseStatusAction, parseStatusItems, parseNavigationStateInput, parsePermissionOutcomeResult, parsePermissionRequest, parseReservedChords, parseTheme, parseToast, parseVoidResult, } from "./schemas.js";
+const rpcStubSchema = Schema.declare((value) => value instanceof RpcStub);
+import { createReadonlyStore } from "./store.js";
+class AppClientTarget extends RpcTarget {
+    #disposed = false;
+    #state;
+    constructor(state) {
+        super();
+        this.#state = state;
+    }
+    disconnect(error) {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const cause = error === undefined ? undefined : parseErrorData(error);
+            // The RPC result is the graceful-disconnect acknowledgement. Closing the
+            // port on a later turn lets Cap'n Web send that acknowledgement first.
+            setTimeout(() => this.#state.disconnect?.(cause ?? gracefulDisconnect()), 0);
+            return Promise.resolve(rpcSuccess(undefined));
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    async requestClose() {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            return rpcSuccess(await (this.#state.beforeClose?.() ?? true));
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
+    async requestBack() {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            return rpcSuccess(await (this.#state.back?.() ?? false));
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
+    async activateStatus(value) {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const action = parseStatusAction(value);
+            // A shell's stale copy can still send an item the App has since
+            // dropped or disabled; only what it declares now reaches the App.
+            if (!statusActionAllowed(this.#state.statusItems, action))
+                return rpcSuccess(false);
+            return rpcSuccess(await (this.#state.statusAction?.(action) ?? false));
+        }
+        catch (cause) {
+            return rpcFailure(cause);
+        }
+    }
+    [Symbol.dispose]() {
+        this.#disposed = true;
+    }
+    async updateContext(value) {
+        if (this.#disposed)
+            return rpcFailure(disconnected());
+        return this.#update(value, "context", parseContext, (next) => {
+            this.#state.context.update(next);
+        });
+    }
+    reconfigure(value) {
+        let retained = [];
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const next = parseHostReconfiguration(value);
+            if (next.context.version <= this.#state.versions.context) {
+                return Promise.resolve(rpcSuccess(undefined));
+            }
+            // RPC argument handles are disposed when this call returns. The directory
+            // owns duplicates until the next replacement or App disposal.
+            for (const grant of next.capabilities)
+                retained.push({
+                    ...grant,
+                    handle: Schema.decodeUnknownSync(rpcStubSchema)(grant.handle).dup(),
+                });
+            if (!this.#state.capabilities)
+                throw disconnected();
+            this.#state.capabilities.replace(retained);
+            retained = [];
+            this.#state.versions.context = next.context.version;
+            this.#state.context.update(next.context.value);
+            return Promise.resolve(rpcSuccess(undefined));
+        }
+        catch (cause) {
+            for (const grant of retained)
+                disposeRpcValue(grant.handle);
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    updateLifecycle(value) {
+        try {
+            if (this.#disposed)
+                throw disconnected();
+            const fact = parseFact(parseLifecycle)(value);
+            if (fact.version <= this.#state.versions.lifecycle)
+                return Promise.resolve(rpcSuccess(undefined));
+            const current = this.#state.lifecycle.get();
+            if (!isHostLifecycleTransition(current, fact.value)) {
+                throw new AppError("The host sent an invalid lifecycle transition", {
+                    code: "PROTOCOL",
+                    retryable: false,
+                });
+            }
+            this.#state.versions.lifecycle = fact.version;
+            this.#state.lifecycle.update(fact.value);
+            return Promise.resolve(rpcSuccess(undefined));
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+    async updateReservedChords(value) {
+        if (this.#disposed)
+            return rpcFailure(disconnected());
+        return this.#update(value, "chords", parseReservedChords, (next) => {
+            this.#state.chords.update(next);
+        });
+    }
+    async updateTheme(value) {
+        if (this.#disposed)
+            return rpcFailure(disconnected());
+        return this.#update(value, "theme", parseTheme, (next) => {
+            this.#state.theme.update(next);
+        });
+    }
+    #update(value, key, parse, apply) {
+        try {
+            const fact = parseFact(parse)(value);
+            if (fact.version > this.#state.versions[key]) {
+                this.#state.versions[key] = fact.version;
+                apply(fact.value);
+            }
+            return Promise.resolve(rpcSuccess(undefined));
+        }
+        catch (cause) {
+            return Promise.resolve(rpcFailure(cause));
+        }
+    }
+}
+export async function connectAppPort(options) {
+    const state = createClientState();
+    const target = new AppClientTarget(state);
+    const remote = newMessagePortRpcSession(options.port, target);
+    let bootstrapOwner;
+    const brokenPromise = createBrokenPromise(remote);
+    try {
+        performance.mark("fungi.app-open.agar-rpc-connect-start");
+        const result = await Promise.race([
+            remote.connect({
+                epoch: options.epoch,
+                protocolVersion: APP_PROTOCOL_VERSION,
+            }),
+            brokenPromise,
+        ]);
+        performance.mark("fungi.app-open.agar-rpc-connect-ready");
+        bootstrapOwner = result;
+        const bootstrap = unwrapRpcResult(parseBootstrapResult(result));
+        if (!options.isActive())
+            throw cancelled();
+        const root = createRoot({
+            bootstrap,
+            bootstrapOwner,
+            options,
+            remote,
+            state,
+            target,
+        });
+        performance.mark("fungi.app-open.agar-root-created");
+        bootstrapOwner = undefined;
+        return root;
+    }
+    catch (cause) {
+        return rejectConnection(cause, options, target, remote, bootstrapOwner);
+    }
+}
+function applyBootstrapFacts(state, facts) {
+    state.context.update(facts.context.value);
+    state.theme.update(facts.theme.value);
+    state.lifecycle.update(facts.lifecycle.value);
+    state.chords.update(facts.chords.value);
+    state.versions.context = facts.context.version;
+    state.versions.theme = facts.theme.version;
+    state.versions.lifecycle = facts.lifecycle.version;
+    state.versions.chords = facts.chords.version;
+}
+function cancelled() {
+    return new AppError("App connection was cancelled", {
+        code: "CANCELLED",
+        retryable: false,
+    });
+}
+function createBrokenPromise(remote) {
+    let broken;
+    const promise = new Promise((_, reject) => {
+        broken = reject;
+    });
+    promise.catch((cause) => {
+        reportCatchFailure("app-session.rpc-disconnect", cause);
+    });
+    remote.onRpcBroken(() => broken?.(new AppError("The app host disconnected", {
+        code: "DISCONNECTED",
+        retryable: true,
+    })));
+    return promise;
+}
+function createClientState() {
+    return {
+        statusItems: [],
+        bindings: createLocalBindingState(),
+        chords: createReservedChordState([]),
+        context: createReadonlyStore({
+            computerId: null,
+            focus: { editing: false, surface: null },
+            openRequest: null,
+            visibility: "hidden",
+        }),
+        lifecycle: createReadonlyStore("connecting"),
+        theme: createReadonlyStore("default"),
+        canGoBack: false,
+        versions: { chords: -1, context: -1, lifecycle: -1, theme: -1 },
+    };
+}
+function createRoot(options) {
+    const identity = parseIdentity(options.bootstrap.identity);
+    const facts = parseBootstrapFacts(options.bootstrap);
+    applyBootstrapFacts(options.state, facts);
+    const capabilities = createCapabilityDirectory(options.bootstrap.capabilities);
+    options.state.capabilities = capabilities;
+    return createRootRuntime(options, identity, capabilities);
+}
+function createRootBridge(options, identity, dispose) {
+    return installBrowserBridge({
+        bindings: options.state.bindings,
+        chords: options.state.chords,
+        identity,
+        onBroken: (cause) => {
+            dispose({
+                code: "DISCONNECTED",
+                message: cause instanceof AppError
+                    ? cause.message
+                    : "The app host rejected a browser bridge operation",
+                retryable: true,
+            });
+        },
+        remote: options.remote,
+        window: options.options.window,
+    });
+}
+function createRootRuntime(options, identity, capabilities) {
+    let disposed = false;
+    const dispose = (error) => {
+        if (disposed)
+            return;
+        disposed = true;
+        exhaustCleanup([
+            () => {
+                if (error)
+                    options.state.lifecycle.update("disconnected");
+            },
+            () => {
+                options.state.lifecycle.update("disposing");
+            },
+            removeBrowserBridge,
+            removeBackInputs,
+            () => {
+                commands.dispose();
+            },
+            () => {
+                options.state.beforeClose = undefined;
+                options.state.back = undefined;
+                options.state.statusAction = undefined;
+            },
+            () => {
+                capabilities.disconnect();
+            },
+            () => {
+                options.target[Symbol.dispose]();
+            },
+            () => {
+                disposeRpcValue(options.bootstrapOwner);
+            },
+            () => {
+                disposeRpcValue(options.remote);
+            },
+            () => {
+                options.options.port.close();
+            },
+            () => {
+                options.state.lifecycle.update("disposed");
+            },
+            options.options.onDisposed,
+        ], "app connection disposal");
+    };
+    const assertConnected = () => {
+        if (disposed)
+            throw new AppError("The app connection is disposed", {
+                code: "DISCONNECTED",
+                retryable: true,
+            });
+    };
+    const commands = createAppCommands(options.remote, assertConnected, () => {
+        dispose({
+            code: "DISCONNECTED",
+            message: "The app host rejected a terminal command operation",
+            retryable: true,
+        });
+    }, options.state.bindings);
+    const ui = createRootUi(options.remote, assertConnected, options.state);
+    const appWindow = createAppWindow(options.state, options.remote, assertConnected);
+    const removeBrowserBridge = createRootBridge(options, identity, dispose);
+    const removeBackInputs = installBackInputs({
+        window: options.options.window,
+        mac: macHistoryKeys(),
+        canGoBack: () => options.state.canGoBack && options.state.back !== undefined,
+        back: () => {
+            const back = options.state.back;
+            if (!back)
+                return;
+            void Promise.resolve()
+                .then(back)
+                .catch((cause) => {
+                reportCatchFailure("app-window.back-input", cause);
+            });
+        },
+    });
+    options.state.disconnect = dispose;
+    options.remote.onRpcBroken(() => {
+        disposeRemoteSession(dispose);
+    });
+    return exposeRoot({
+        capabilities: capabilities.directory,
+        commands: commands.commands,
+        context: options.state.context,
+        dispose,
+        identity,
+        lifecycle: options.state.lifecycle,
+        theme: options.state.theme,
+        ui,
+        window: appWindow,
+    });
+}
+function createAppWindow(state, remote, assertConnected) {
+    const navigation = Object.freeze({
+        async publish(input) {
+            assertConnected();
+            const wire = parseNavigationStateInput(input);
+            state.canGoBack = wire.canGoBack;
+            await callRpc(remote.reportNavigation(wire), parseVoidResult);
+        },
+        onBack(handler) {
+            assertConnected();
+            if (state.back !== undefined)
+                throw new AppError("The App already owns Back requests", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            state.back = handler;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (state.back === handler)
+                    state.back = undefined;
+            };
+        },
+    });
+    return Object.freeze({
+        navigation,
+        onBeforeClose(handler) {
+            assertConnected();
+            if (state.beforeClose !== undefined)
+                throw new AppError("The App already owns a close consultation", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            state.beforeClose = handler;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (state.beforeClose === handler)
+                    state.beforeClose = undefined;
+            };
+        },
+    });
+}
+function createRootUi(remote, assertConnected, state) {
+    return Object.freeze({
+        async requestComputerChoice() {
+            assertConnected();
+            await callRpc(remote.requestComputerChoice(), parseVoidResult);
+        },
+        async requestBrowserAction(input) {
+            assertConnected();
+            const parsed = parseBrowserAction(input);
+            if (parsed.kind === "refused")
+                return parsed;
+            return await callRpc(remote.requestBrowserAction(parsed), parseBrowserActionOutcomeResult);
+        },
+        onStatusAction(handler) {
+            assertConnected();
+            if (state.statusAction !== undefined)
+                throw new AppError("The App already owns its status actions", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                });
+            state.statusAction = handler;
+            let released = false;
+            return () => {
+                if (released)
+                    return;
+                released = true;
+                if (state.statusAction === handler)
+                    state.statusAction = undefined;
+            };
+        },
+        async requestAppPermissions(input) {
+            assertConnected();
+            return await callRpc(remote.requestAppPermissions(parsePermissionRequest(input)), parsePermissionOutcomeResult);
+        },
+        async openDesktopSettings() {
+            assertConnected();
+            await callRpc(remote.openDesktopSettings(), parseVoidResult);
+        },
+        async openTeamBilling() {
+            assertConnected();
+            await callRpc(remote.openTeamBilling(), parseVoidResult);
+        },
+        async openNavigation(input) {
+            assertConnected();
+            await callRpc(remote.openNavigation(parseNavigation(input)), parseVoidResult);
+        },
+        async reportStatus(items) {
+            assertConnected();
+            const parsed = parseStatusItems(items);
+            // Actions are checked against this as soon as the App declares it.
+            state.statusItems = parsed;
+            await callRpc(remote.reportStatus(parsed), parseVoidResult);
+        },
+        async reportAgentSessionSelection(selection) {
+            assertConnected();
+            await callRpc(remote.reportAgentSessionSelection(parseAgentSessionSelection(selection)), parseVoidResult);
+        },
+        async showToast(input) {
+            assertConnected();
+            await callRpc(remote.showToast(parseToast(input)), parseVoidResult);
+        },
+    });
+}
+function disconnected() {
+    return new AppError("The app connection is disposed", {
+        code: "DISCONNECTED",
+        retryable: true,
+    });
+}
+function disposeRemoteSession(dispose) {
+    dispose({
+        code: "DISCONNECTED",
+        message: "The app host disconnected",
+        retryable: true,
+    });
+}
+function exhaustCleanup(cleanups, label) {
+    for (const cleanup of cleanups) {
+        try {
+            cleanup();
+        }
+        catch (cause) {
+            console.warn(`${label} cleanup failed`, cause);
+        }
+    }
+}
+function exposeRoot(value) {
+    return Object.freeze(value);
+}
+function gracefulDisconnect() {
+    return {
+        code: "DISCONNECTED",
+        message: "The app host disconnected",
+        retryable: false,
+    };
+}
+function isHostLifecycleTransition(current, next) {
+    return (current === next ||
+        (current === "connected" && next === "suspended") ||
+        (current === "suspended" && next === "connected"));
+}
+function parseBootstrapFacts(bootstrap) {
+    const context = parseFact(parseContext)(bootstrap.context);
+    const theme = parseFact(parseTheme)(bootstrap.theme);
+    const lifecycle = parseFact(parseLifecycle)(bootstrap.lifecycle);
+    const chords = parseFact(parseReservedChords)(bootstrap.reservedChords);
+    if (lifecycle.value !== "connected" && lifecycle.value !== "suspended")
+        throw new AppError("The bootstrap lifecycle is invalid", {
+            code: "PROTOCOL",
+            retryable: false,
+        });
+    return { chords, context, lifecycle, theme };
+}
+function rejectConnection(cause, options, target, remote, bootstrapOwner) {
+    exhaustCleanup([
+        () => {
+            target[Symbol.dispose]();
+        },
+        () => {
+            if (bootstrapOwner)
+                disposeRpcValue(bootstrapOwner);
+        },
+        () => {
+            disposeRpcValue(remote);
+        },
+        () => {
+            options.port.close();
+        },
+        options.onDisposed,
+    ], "app connection rejection");
+    throw cause instanceof AppError
+        ? cause
+        : new AppError("Unable to establish the app RPC session", {
+            cause,
+            code: "PROTOCOL",
+            retryable: false,
+        });
+}

package/dist/internal/back-inputs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * WHY: an App iframe shares the tab's history with the Hub page, so the
+ * browser's own back inputs pressed inside an App would navigate the whole
+ * workspace away. They mean App Back here, or nothing (Levi, 2026-10-07).
+ */
+export type BackInputOptions = Readonly<{
+    window: Pick<Window, "addEventListener" | "removeEventListener">;
+    /** macOS uses ⌘[ and ⌘←; other platforms use Alt+←. */
+    mac: boolean;
+    /** Whether the App last reported it can go back. */
+    canGoBack: () => boolean;
+    /** Ask the App's own Back handler to move. */
+    back: () => void;
+}>;
+/**
+ * Turn the browser's back keys and mouse back button into App Back while the
+ * App can go back, and keep every back or forward input from leaving the
+ * page. Input the App already handled (`defaultPrevented`) is left alone.
+ */
+export declare function installBackInputs(options: BackInputOptions): () => void;
+/** Whether this browser uses the macOS history keys. */
+export declare function macHistoryKeys(): boolean;

package/dist/internal/back-inputs.js

@@ -0,0 +1,93 @@
+/**
+ * WHY: an App iframe shares the tab's history with the Hub page, so the
+ * browser's own back inputs pressed inside an App would navigate the whole
+ * workspace away. They mean App Back here, or nothing (Levi, 2026-10-07).
+ */
+import * as Predicate from "effect/Predicate";
+/**
+ * Turn the browser's back keys and mouse back button into App Back while the
+ * App can go back, and keep every back or forward input from leaving the
+ * page. Input the App already handled (`defaultPrevented`) is left alone.
+ */
+export function installBackInputs(options) {
+    const onKeyDown = (event) => {
+        if (event.defaultPrevented || event.isComposing)
+            return;
+        const direction = keyDirection(event, options.mac);
+        if (direction === null)
+            return;
+        event.preventDefault();
+        if (direction === "back" && !event.repeat && options.canGoBack())
+            options.back();
+    };
+    const onMouse = (event) => {
+        const direction = mouseDirection(event.button);
+        if (direction === null)
+            return;
+        const handled = event.defaultPrevented;
+        event.preventDefault();
+        if (event.type === "mouseup" &&
+            direction === "back" &&
+            !handled &&
+            options.canGoBack())
+            options.back();
+    };
+    options.window.addEventListener("keydown", onKeyDown);
+    for (const type of mouseEvents)
+        options.window.addEventListener(type, onMouse);
+    return () => {
+        options.window.removeEventListener("keydown", onKeyDown);
+        for (const type of mouseEvents)
+            options.window.removeEventListener(type, onMouse);
+    };
+}
+/** Browsers navigate on one of these; all are cancelled, Back runs once. */
+const mouseEvents = ["mousedown", "mouseup", "auxclick"];
+function mouseDirection(button) {
+    if (button === 3)
+        return "back";
+    if (button === 4)
+        return "forward";
+    return null;
+}
+function keyDirection(event, mac) {
+    if (event.shiftKey || event.ctrlKey)
+        return null;
+    if (mac) {
+        if (!event.metaKey || event.altKey)
+            return null;
+        if (event.key === "[")
+            return "back";
+        if (event.key === "]")
+            return "forward";
+        // ⌘← and ⌘→ move the caret in text; only elsewhere are they history keys.
+        if (editable(event.target))
+            return null;
+        if (event.key === "ArrowLeft")
+            return "back";
+        if (event.key === "ArrowRight")
+            return "forward";
+        return null;
+    }
+    if (!event.altKey || event.metaKey)
+        return null;
+    if (event.key === "ArrowLeft")
+        return "back";
+    if (event.key === "ArrowRight")
+        return "forward";
+    return null;
+}
+// Only a DOM keyboard event reaches this, so the DOM classes exist.
+function editable(target) {
+    if (!(target instanceof HTMLElement))
+        return false;
+    return (target.isContentEditable ||
+        target instanceof HTMLInputElement ||
+        target instanceof HTMLTextAreaElement ||
+        target instanceof HTMLSelectElement);
+}
+/** Whether this browser uses the macOS history keys. */
+export function macHistoryKeys() {
+    return (!Predicate.isUndefined(globalThis.navigator) &&
+        /Mac|iPhone|iPad/u.test(globalThis.navigator.userAgent));
+}

package/dist/internal/browser-bridge.d.ts

@@ -0,0 +1,30 @@
+import type { AppIdentity } from "../lifecycle.js";
+import type { AppHostRpc, ReservedChord } from "./protocol.js";
+export type ReservedChordState = {
+    get(): readonly Readonly<ReservedChord>[];
+    subscribe(listener: () => void): () => void;
+    update(value: readonly ReservedChord[]): void;
+};
+/** One of the App's own command bindings, run locally inside the iframe. */
+export type LocalBinding = Readonly<{
+    /** Keymap binding string, e.g. `mod+s`. */
+    key: string;
+    /** Run the command's own handler with keyboard origin. */
+    run: () => void;
+}>;
+/** The App's current single-chord command bindings. */
+export type LocalBindingState = {
+    get(): readonly LocalBinding[];
+    subscribe(listener: () => void): () => void;
+    update(value: readonly LocalBinding[]): void;
+};
+export declare function createLocalBindingState(): LocalBindingState;
+export declare function createReservedChordState(initial: readonly ReservedChord[]): ReservedChordState;
+export declare function installBrowserBridge(options: {
+    readonly bindings?: LocalBindingState;
+    readonly chords: ReservedChordState;
+    readonly identity: AppIdentity;
+    readonly onBroken: (cause?: unknown) => void;
+    readonly remote: Pick<AppHostRpc, "reportFocus" | "invokeReservedChord">;
+    readonly window: Window;
+}): () => void;