@fungi.computer/oyster 0.0.0-stage → 0.0.1

package/dist/shell/workbench-contract.d.ts

@@ -0,0 +1,68 @@
+import type { AgentSessionSelection } from "@fungi.computer/agar";
+import type { GillReply } from "@fungi.computer/gills";
+import type { AppOpenInput } from "@fungi.computer/agar/apps";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import type { WorkbenchChildEvents, WorkbenchChildHandle, WorkbenchChildLaunch, WorkbenchGillRequest, WorkbenchGillWatch, WorkbenchPlatformDestination, WorkbenchDesktopSettings, WorkbenchDesktopRegistration } from "./workbench-model.js";
+/** Team dashboards additionally relay the selected Agent Session to the Hub. */
+export type TeamWorkbenchChildEvents = WorkbenchChildEvents & Readonly<{
+    /** Relay a child's explicit Agent Session selection to its host. */
+    onAgentSessionSelection: (selection: AgentSessionSelection | null) => Promise<void>;
+}>;
+/**
+ * Team/Computer/App-directory reads and child-App hosting for the trusted
+ * shell. The host composes the shell into its own top-level document, so the
+ * shell runs with the host's escalated permissions; each child App still runs
+ * in its own sandboxed frame with its own separately resolved approvals.
+ */
+export type TeamWorkbenchHostHandle = {
+    /** The authenticated Team hosting this dashboard; the caller parses it. */
+    team(): Promise<WhistleJsonValue>;
+    /** A page of the Team's Computer inventory; the caller parses it. */
+    computers(input: Readonly<{
+        limit: number;
+        offset: number;
+    }>): Promise<WhistleJsonValue>;
+    /** The Team's effective App directory and role choices; the caller parses it. */
+    directory(): Promise<WhistleJsonValue>;
+    /** Invoke a declared Gill of an admitted App in this Team. No caller-provided resource data. */
+    requestGill(input: WorkbenchGillRequest): Promise<GillReply>;
+    /** Observe resource changes; only the host owns the authenticated stream. Close while covered. */
+    watchGillChanges(input: WorkbenchGillRequest, onChanged: () => Promise<void>): Promise<WorkbenchGillWatch>;
+    /**
+     * Resolve, authorize and mount one child App inside `container`, the
+     * shell's own slot in that App's window. The host never moves the child:
+     * the shell keeps `container` attached and moves its window instead.
+     */
+    mount(container: HTMLElement, input: WorkbenchChildLaunch, events: TeamWorkbenchChildEvents): Promise<WorkbenchChildHandle>;
+    /** Bind one mounted child's explicit Agent Session selection to the host. */
+    reportAgentSessionSelection(windowId: string, selection: AgentSessionSelection | null): Promise<void>;
+    /** The platform destinations the host currently offers. */
+    platformDestinations(): Promise<readonly WorkbenchPlatformDestination[]>;
+    /** Offered Settings categories, or null for unrestricted host controls. */
+    settingsSections(): Promise<readonly string[] | null>;
+    /** Ask the host to navigate to one offered platform destination. */
+    openPlatformDestination(id: string): Promise<void>;
+    /**
+     * Take, once, the App-open handoff the visitor's Hub address carried (for
+     * example `?open=inbox&intent=compose`). The host consumes it from its own
+     * address; the dashboard opens it like any other `apps.open` request.
+     */
+    takeAppOpenRequest(): Promise<AppOpenInput | null>;
+    /**
+     * Open the host's own Team settings at a dashboard-defined location (the
+     * host parses it). Administration there runs with the signed-in person's
+     * own authority in host-rendered UI, never through the dashboard.
+     * Resolves when Settings close, so the dashboard restores its own focus.
+     */
+    openSettings(location: WhistleJsonValue): Promise<void>;
+    /** Bind the admitted dashboard's arranger to the host's member-consent UI.
+     * Only the host invokes it; ordinary Apps can only open their own Settings. */
+    registerDesktopSettings(handler: WorkbenchDesktopSettings): Promise<WorkbenchDesktopRegistration>;
+    /**
+     * Hear when host-rendered settings or App access consent changed the
+     * Team's Apps or the person's settings, so the dashboard refreshes.
+     */
+    watchSettingsChanges(onChanged: () => Promise<void>): Promise<void>;
+    /** The signed-in person's own avatar preference; the caller parses it. */
+    memberAvatar(): Promise<WhistleJsonValue>;
+};

package/dist/shell/workbench-contract.js

@@ -0,0 +1 @@
+export {};

package/dist/shell/workbench-host-types.d.ts

@@ -0,0 +1,96 @@
+import type { TeamWorkbenchChildEvents, TeamWorkbenchHostHandle } from "./workbench-contract.js";
+import type { AgentSessionSelection, AppPermissionOutcome, AppPermissionRequest } from "@fungi.computer/agar";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import type { AppCommandDeclaration, AppSurfaceCommandMount } from "./command-host.js";
+import type { WorkbenchChildHandle, WorkbenchChildLaunch, WorkbenchDesktopSettings, WorkbenchPlatformDestination } from "./workbench-model.js";
+/** A launch checked against the embedding host's own installation authority. */
+export type WorkbenchResolvedChild = Readonly<{
+    launch: Omit<WorkbenchChildLaunch, "title">;
+    title?: string;
+}>;
+/** The host's real mounted App; selection and lease replacement stay with it. */
+export type WorkbenchChildSurface = Pick<WorkbenchChildHandle, "setVisibility" | "requestClose" | "requestBack" | "activateStatus"> & {
+    /** Release the mounted child or host-owned observations. */
+    dispose(): void;
+    /** Replace the host-admitted selection while retaining the child document. */
+    reconfigure(launch: WorkbenchResolvedChild["launch"]): Promise<void>;
+};
+/** Inputs shared child-window mechanics supply to the host's admitted mount. */
+export type WorkbenchChildMountOptions = Readonly<{
+    container: HTMLElement;
+    hostWindow: Window;
+    title?: string;
+    events: TeamWorkbenchChildEvents;
+    commands: AppSurfaceCommandMount;
+    /** Suggest the child's admitted surface in host-rendered Settings. */
+    onDesktopSettings: (surfaceId: string) => Promise<void>;
+    /** Ask the host to obtain the person's approval for the child. */
+    onPermissionRequest: (input: AppPermissionRequest) => Promise<AppPermissionOutcome>;
+}>;
+/** Host-owned admission and lifetime of one prepared child. */
+export type WorkbenchPreparedChild = Readonly<{
+    commands: readonly AppCommandDeclaration[];
+    /** Connect the prepared App using the shared window callbacks and commands. */
+    mount(options: WorkbenchChildMountOptions): Promise<WorkbenchChildSurface>;
+    /** Release preparation and lease resources, including a failed mount. */
+    dispose(): Promise<void>;
+}>;
+/** Host services retain their own Team, account, Gill and consent authority. */
+export type WorkbenchHostServices = Pick<TeamWorkbenchHostHandle, "team" | "computers" | "directory" | "requestGill" | "watchGillChanges" | "memberAvatar"> & Readonly<{
+    /** Offer host-owned desktop Settings for this currently admitted surface. */
+    suggestDesktopSettings(surfaceId: string): Promise<void>;
+    /** Release the mounted child or host-owned observations. */
+    dispose(): void;
+}>;
+/** Controls offered by the real embedding host, never grants lent by the App. */
+export type WorkbenchHostControls = Readonly<{
+    /** Implemented Settings categories; omission means the retained unrestricted controls. */
+    sections?: readonly string[] | undefined;
+    /** Validate a location against the Settings this host actually offers. */
+    parseSettings(location: WhistleJsonValue): WhistleJsonValue;
+    /** Open validated host-rendered Settings without racing dashboard focus. */
+    openSettings(location: WhistleJsonValue, options: Readonly<{
+        restoreFocus: boolean;
+    }>): void;
+    /** Notify when the host dialog has closed; return its unsubscribe action. */
+    subscribeSettingsClosed(listener: () => void): () => void;
+    /** Observe host Settings changes until the returned unsubscribe is called. */
+    subscribeChanges(listener: () => void): () => void;
+    /** Attach the dashboard arranger; return the host registration cleanup. */
+    attachDesktopSettings(handler: WorkbenchDesktopSettings): () => void;
+    /** Ask the person for the child's own access, never through the dashboard. */
+    requestAppAccess(target: Readonly<{
+        surfaceId: string;
+        title: string;
+    }>, input: AppPermissionRequest): Promise<AppPermissionOutcome>;
+}>;
+/** Retained host warning identifiers; adapters own their diagnostic sink. */
+export type WorkbenchWarningEvent = "team_workbench_commands_failed" | "team_workbench_settings_notification_failed" | "team_workbench_focus_notification_failed";
+/** Fields of a retained child/settings notification failure. */
+export type WorkbenchWarningFields = Readonly<{
+    cause: unknown;
+}> | Readonly<{
+    stage: "update" | "dispose";
+    cause: unknown;
+}>;
+/** One workbench's child mechanics over host-owned admission and services. */
+export type WorkbenchHostOptions = Readonly<{
+    hostWindow: Window;
+    /** Check identity and launch address against this host's installation scope. */
+    resolveLaunch(input: WorkbenchChildLaunch): WorkbenchResolvedChild;
+    /** Prepare the child using its own current grants and lease owner. */
+    prepareChild(launch: WorkbenchResolvedChild["launch"]): Promise<WorkbenchPreparedChild>;
+    services: WorkbenchHostServices;
+    /** Report a mounted child's explicit selection to the embedding host. */
+    reportAgentSessionSelection(windowId: string, selection: AgentSessionSelection | null): void;
+    platform: Readonly<{
+        controls: WorkbenchHostControls;
+        /** List only destinations the host currently implements. */
+        destinations(): Promise<readonly WorkbenchPlatformDestination[]>;
+        /** Follow a destination that the shared host verified was offered. */
+        open(id: string): void;
+        takeAppOpenRequest: TeamWorkbenchHostHandle["takeAppOpenRequest"];
+    }>;
+    /** Surface retained callback failures through the host's diagnostic sink. */
+    log(event: WorkbenchWarningEvent, fields: WorkbenchWarningFields): void;
+}>;

package/dist/shell/workbench-host-types.js

@@ -0,0 +1 @@
+export {};

package/dist/shell/workbench-host.d.ts

@@ -0,0 +1,34 @@
+import type { TeamWorkbenchHostHandle, TeamWorkbenchChildEvents } from "./workbench-contract.js";
+import type { AgentSessionSelection } from "@fungi.computer/agar";
+import type { AppOpenInput } from "@fungi.computer/agar/apps";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+import { type WorkbenchDesktopRegistration, type WorkbenchChildHandle, type WorkbenchChildLaunch, type WorkbenchPlatformDestination } from "./workbench-model.js";
+import type { WorkbenchHostOptions } from "./workbench-host-types.js";
+/**
+ * Child-window, command and callback lifetime for the trusted shell the host
+ * composes into its own document. Each child mounts inside the window slot
+ * the shell hands it, so the browser moves, clips and stacks it with that
+ * window; the host never positions a child itself.
+ */
+export declare class WorkbenchHost implements TeamWorkbenchHostHandle {
+    #private;
+    constructor(options: WorkbenchHostOptions);
+    team(): ReturnType<TeamWorkbenchHostHandle["team"]>;
+    computers(input: Parameters<TeamWorkbenchHostHandle["computers"]>[0]): ReturnType<TeamWorkbenchHostHandle["computers"]>;
+    directory(): ReturnType<TeamWorkbenchHostHandle["directory"]>;
+    requestGill(input: Parameters<TeamWorkbenchHostHandle["requestGill"]>[0]): ReturnType<TeamWorkbenchHostHandle["requestGill"]>;
+    watchGillChanges(...input: Parameters<TeamWorkbenchHostHandle["watchGillChanges"]>): ReturnType<TeamWorkbenchHostHandle["watchGillChanges"]>;
+    platformDestinations(): Promise<readonly WorkbenchPlatformDestination[]>;
+    openPlatformDestination(id: string): Promise<void>;
+    /** Describe the actual controls without offering unsupported Settings. */
+    settingsSections(): Promise<readonly string[] | null>;
+    takeAppOpenRequest(): Promise<AppOpenInput | null>;
+    registerDesktopSettings(handler: unknown): Promise<WorkbenchDesktopRegistration>;
+    openSettings(location: WhistleJsonValue): Promise<void>;
+    memberAvatar(): ReturnType<TeamWorkbenchHostHandle["memberAvatar"]>;
+    watchSettingsChanges(onChanged: () => Promise<void>): Promise<void>;
+    /** The shell unmounted: stop notifying its callbacks. */
+    [Symbol.dispose](): void;
+    mount(container: HTMLElement, input: WorkbenchChildLaunch, events: TeamWorkbenchChildEvents): Promise<WorkbenchChildHandle>;
+    reportAgentSessionSelection(windowId: string, selection: AgentSessionSelection | null): Promise<void>;
+}

package/dist/shell/workbench-host.js

@@ -0,0 +1,347 @@
+import * as Schema from "effect/Schema";
+import { AppError, parseAppStatusAction } from "@fungi.computer/agar";
+import { parseJsonValue } from "@fungi.computer/whistle/wire";
+import { desktopSettingsHandlerSchema, } from "./workbench-model.js";
+import { createAppSurfaceCommandHost, } from "./command-host.js";
+/** A dashboard may keep this many child Apps mounted at once. */
+const maxChildren = 32;
+const nonBlank = Schema.String.pipe(Schema.check(Schema.isMinLength(1)), Schema.check(Schema.isMaxLength(2_048)));
+const visibilitySchema = Schema.Literals(["hidden", "visible"]);
+// A dashboard presents a child's commands to people; it never acts as the
+// child's Agent.
+const commandInvocationSchema = Schema.Struct({
+    commandId: nonBlank,
+    origin: Schema.Literals([
+        "keyboard",
+        "palette",
+        "menu",
+        "browser",
+        "programmatic",
+        "slash",
+        "terminal",
+    ]),
+});
+/**
+ * Forward a child's Release-validated commands and reserved chords to the
+ * dashboard that presents them. Validation stays here, against the child's
+ * own Release declaration, so the dashboard can never widen them.
+ */
+function forwardCommands(log, validated, events, current) {
+    const present = (commands) => events.onCommands?.(commands) ?? Promise.resolve();
+    const handlers = {
+        registerCommands: async (input) => {
+            const contribution = await validated.handlers.registerCommands(input);
+            current.invoke = input.invoke;
+            await present(input.commands);
+            return {
+                update: (commands) => {
+                    contribution.update(commands);
+                    void present(commands).catch((cause) => {
+                        log("team_workbench_commands_failed", {
+                            stage: "update",
+                            cause,
+                        });
+                    });
+                },
+                dispose: () => {
+                    contribution.dispose();
+                    if (current.invoke === input.invoke)
+                        current.invoke = undefined;
+                    void present([]).catch((cause) => {
+                        log("team_workbench_commands_failed", {
+                            stage: "dispose",
+                            cause,
+                        });
+                    });
+                },
+            };
+        },
+        invokeReservedChord: async (input) => {
+            if (events.onReservedChord === undefined)
+                throw new Error("App reserved chord is unavailable");
+            await events.onReservedChord(input);
+        },
+    };
+    return Object.freeze({
+        handlers: Object.freeze(handlers),
+        dispose: validated.dispose,
+    });
+}
+/**
+ * One mounted child App, proxying to its real host-owned mount. The shell
+ * holds this bounded handle; the host's lease machinery stays behind it.
+ */
+class MountedChildHandle {
+    surface;
+    commands;
+    reconfigureCurrent;
+    release;
+    #disposed = false;
+    constructor(surface, commands, reconfigureCurrent, release) {
+        this.surface = surface;
+        this.commands = commands;
+        this.reconfigureCurrent = reconfigureCurrent;
+        this.release = release;
+    }
+    async setVisibility(visibility) {
+        if (this.#disposed)
+            return;
+        await this.surface.setVisibility(Schema.decodeUnknownSync(visibilitySchema)(visibility));
+    }
+    async reconfigure(launch) {
+        if (this.#disposed)
+            return;
+        await this.reconfigureCurrent(launch);
+    }
+    async requestClose() {
+        if (this.#disposed)
+            return true;
+        return this.surface.requestClose();
+    }
+    async requestBack() {
+        if (this.#disposed)
+            return false;
+        return this.surface.requestBack();
+    }
+    async activateStatus(action) {
+        if (this.#disposed)
+            return false;
+        // The shell relays the person's click; parse it at the host's edge.
+        return this.surface.activateStatus(parseAppStatusAction(action));
+    }
+    async invokeCommand(commandId, input) {
+        const invoke = this.commands.invoke;
+        if (this.#disposed || invoke === undefined)
+            throw new AppError("That App command is unavailable", {
+                code: "CAPABILITY_DENIED",
+                retryable: false,
+            });
+        const parsed = Schema.decodeUnknownSync(commandInvocationSchema)({
+            commandId,
+            origin: input.origin,
+        });
+        return invoke(parsed.commandId, input.arguments === undefined
+            ? { origin: parsed.origin }
+            : { arguments: parseJsonValue(input.arguments), origin: parsed.origin });
+    }
+    async dispose() {
+        if (this.#disposed)
+            return;
+        this.#disposed = true;
+        await this.release();
+    }
+    [Symbol.dispose]() {
+        void this.dispose();
+    }
+}
+class DesktopSettingsRegistration {
+    detach;
+    constructor(detach) {
+        this.detach = detach;
+    }
+    close() {
+        this.detach();
+        return Promise.resolve();
+    }
+    [Symbol.dispose]() {
+        this.detach();
+    }
+}
+/**
+ * Child-window, command and callback lifetime for the trusted shell the host
+ * composes into its own document. Each child mounts inside the window slot
+ * the shell hands it, so the browser moves, clips and stacks it with that
+ * window; the host never positions a child itself.
+ */
+export class WorkbenchHost {
+    #hostWindow;
+    #options;
+    #commands = createAppSurfaceCommandHost();
+    #children = new Set();
+    #releases = [];
+    #desktopSettingsClose;
+    #settingsClose;
+    #finishSettings;
+    constructor(options) {
+        this.#hostWindow = options.hostWindow;
+        this.#options = options;
+    }
+    team() {
+        return this.#options.services.team();
+    }
+    computers(input) {
+        return this.#options.services.computers(input);
+    }
+    directory() {
+        return this.#options.services.directory();
+    }
+    requestGill(input) {
+        return this.#options.services.requestGill(input);
+    }
+    watchGillChanges(...input) {
+        return this.#options.services.watchGillChanges(...input);
+    }
+    async platformDestinations() {
+        return (await this.#options.platform.destinations()).map(({ id, label }) => ({ id, label }));
+    }
+    async openPlatformDestination(id) {
+        const parsed = Schema.decodeUnknownSync(nonBlank)(id);
+        const offered = await this.#options.platform.destinations();
+        if (!offered.some((destination) => destination.id === parsed))
+            throw new AppError("That destination is unavailable", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        this.#options.platform.open(parsed);
+    }
+    /** Describe the actual controls without offering unsupported Settings. */
+    settingsSections() {
+        const controls = this.#options.platform.controls;
+        return Promise.resolve(controls.sections?.slice() ?? null);
+    }
+    takeAppOpenRequest() {
+        return Promise.resolve(this.#options.platform.takeAppOpenRequest());
+    }
+    registerDesktopSettings(handler) {
+        return Promise.resolve().then(() => {
+            let parsed;
+            try {
+                parsed = desktopSettingsHandlerSchema.parse(handler);
+            }
+            catch (cause) {
+                throw new AppError("Desktop settings registration is invalid", {
+                    code: "INVALID_ARGUMENT",
+                    retryable: false,
+                    cause,
+                });
+            }
+            this.#desktopSettingsClose?.();
+            const detach = this.#options.platform.controls.attachDesktopSettings(parsed);
+            let closed = false;
+            const close = () => {
+                if (closed)
+                    return;
+                closed = true;
+                detach();
+                if (this.#desktopSettingsClose === close)
+                    this.#desktopSettingsClose = undefined;
+            };
+            this.#desktopSettingsClose = close;
+            return new DesktopSettingsRegistration(close);
+        });
+    }
+    async openSettings(location) {
+        const parsed = this.#options.platform.controls.parseSettings(location);
+        const controls = this.#options.platform.controls;
+        if (this.#settingsClose !== undefined) {
+            const closed = this.#settingsClose;
+            controls.openSettings(parsed, { restoreFocus: false });
+            return closed;
+        }
+        const closed = new Promise((resolve) => {
+            const unsubscribe = controls.subscribeSettingsClosed(() => this.#finishSettings?.());
+            this.#finishSettings = () => {
+                unsubscribe();
+                this.#settingsClose = undefined;
+                this.#finishSettings = undefined;
+                resolve();
+            };
+        });
+        this.#settingsClose = closed;
+        // The shell restores its own invoker once Settings close; returning
+        // focus here would race that restoration.
+        controls.openSettings(parsed, { restoreFocus: false });
+        return closed;
+    }
+    memberAvatar() {
+        return this.#options.services.memberAvatar();
+    }
+    watchSettingsChanges(onChanged) {
+        const unsubscribe = this.#options.platform.controls.subscribeChanges(() => {
+            void onChanged().catch((cause) => {
+                this.#options.log("team_workbench_settings_notification_failed", {
+                    cause,
+                });
+            });
+        });
+        this.#releases.push(unsubscribe);
+        return Promise.resolve();
+    }
+    /** The shell unmounted: stop notifying its callbacks. */
+    [Symbol.dispose]() {
+        this.#finishSettings?.();
+        this.#desktopSettingsClose?.();
+        this.#options.services.dispose();
+        for (const release of this.#releases.splice(0))
+            release();
+    }
+    async mount(container, input, events) {
+        const request = this.#options.resolveLaunch(input);
+        const mountId = request.launch.windowId;
+        if (this.#children.has(mountId))
+            throw new AppError("That App window is already open", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        if (this.#children.size >= maxChildren)
+            throw new AppError("Too many Apps are open", {
+                code: "INVALID_ARGUMENT",
+                retryable: false,
+            });
+        this.#children.add(mountId);
+        let prepared;
+        let commandMount;
+        const childCommands = { invoke: undefined };
+        const release = async () => {
+            try {
+                commandMount?.dispose();
+                if (prepared)
+                    await prepared.dispose();
+            }
+            finally {
+                this.#children.delete(mountId);
+            }
+        };
+        try {
+            prepared = await this.#options.prepareChild(request.launch);
+            commandMount = forwardCommands(this.#options.log, this.#commands.mount(mountId, prepared.commands), events, childCommands);
+            const surface = await prepared.mount({
+                container,
+                hostWindow: this.#hostWindow,
+                ...(request.title === undefined ? undefined : { title: request.title }),
+                commands: commandMount,
+                events,
+                onDesktopSettings: (surfaceId) => this.#options.services.suggestDesktopSettings(surfaceId),
+                onPermissionRequest: (permission) => this.#options.platform.controls.requestAppAccess({
+                    surfaceId: request.launch.surfaceId,
+                    title: request.title ?? request.launch.appId,
+                }, permission),
+            });
+            const reconfigureCurrent = async (next) => {
+                const nextRequest = this.#options.resolveLaunch(next);
+                if (nextRequest.launch.appId !== request.launch.appId ||
+                    nextRequest.launch.releaseId !== request.launch.releaseId ||
+                    nextRequest.launch.surfaceId !== request.launch.surfaceId)
+                    throw new Error("App identity cannot change during reconfiguration");
+                await surface.reconfigure(nextRequest.launch);
+            };
+            return new MountedChildHandle(surface, childCommands, reconfigureCurrent, async () => {
+                try {
+                    surface.dispose();
+                }
+                finally {
+                    await release();
+                }
+            });
+        }
+        catch (error) {
+            await release();
+            throw error;
+        }
+    }
+    reportAgentSessionSelection(windowId, selection) {
+        const parsed = Schema.decodeUnknownSync(nonBlank)(windowId);
+        this.#options.reportAgentSessionSelection(parsed, selection);
+        return Promise.resolve();
+    }
+}