@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/method-refusal.d.ts

@@ -0,0 +1,64 @@
+import * as z from "zod";
+import type { WhistleJsonValue } from "@fungi.computer/whistle";
+/**
+ * The closed vocabulary an App method may refuse with. Each code names one
+ * caller-visible outcome; the host owns how it is presented (see
+ * {@link appMethodRefusalStatus}).
+ */
+export declare const appMethodRefusalCodes: readonly ["invalid", "forbidden", "not_found", "conflict", "unavailable"];
+/** One of {@link appMethodRefusalCodes}. */
+export type AppMethodRefusalCode = (typeof appMethodRefusalCodes)[number];
+/** HTTP status for each refusal code, shared by every host and App route. */
+export declare const appMethodRefusalStatus: {
+    readonly invalid: 400;
+    readonly forbidden: 403;
+    readonly not_found: 404;
+    readonly conflict: 409;
+    readonly unavailable: 503;
+};
+/** Bound on the App-authored refusal message that reaches callers. */
+export declare const maxAppMethodRefusalMessage = 500;
+/**
+ * An App method's declared domain refusal. A handler throws it to decline a
+ * call; the generated method boundary returns it as a typed
+ * {@link AppMethodReply} instead of an execution failure. Its message is
+ * caller-facing App copy, so it must not carry private data.
+ */
+export declare class AppMethodRefusal extends Error {
+    readonly code: AppMethodRefusalCode;
+    constructor(code: AppMethodRefusalCode, message: string);
+}
+/** A refused call as it crosses the generated method boundary. */
+export declare const appMethodRefusedReplySchema: z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    code: z.ZodEnum<{
+        unavailable: "unavailable";
+        invalid: "invalid";
+        conflict: "conflict";
+        forbidden: "forbidden";
+        not_found: "not_found";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>;
+/** A decoded {@link appMethodRefusedReplySchema} value. */
+export type AppMethodRefusedReply = z.output<typeof appMethodRefusedReplySchema>;
+/** Every generated App method RPC answers with exactly one of these. */
+export declare const appMethodReplySchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    kind: z.ZodLiteral<"ok">;
+    value: z.ZodJSONSchema;
+}, z.core.$strict>, z.ZodObject<{
+    kind: z.ZodLiteral<"refused">;
+    code: z.ZodEnum<{
+        unavailable: "unavailable";
+        invalid: "invalid";
+        conflict: "conflict";
+        forbidden: "forbidden";
+        not_found: "not_found";
+    }>;
+    message: z.ZodString;
+}, z.core.$strict>], "kind">;
+/** A decoded {@link appMethodReplySchema} value; the result is read-only JSON. */
+export type AppMethodReply = Readonly<{
+    kind: "ok";
+    value: WhistleJsonValue;
+}> | AppMethodRefusedReply;

package/dist/method-refusal.js

@@ -0,0 +1,48 @@
+import * as z from "zod";
+/**
+ * The closed vocabulary an App method may refuse with. Each code names one
+ * caller-visible outcome; the host owns how it is presented (see
+ * {@link appMethodRefusalStatus}).
+ */
+export const appMethodRefusalCodes = [
+    "invalid",
+    "forbidden",
+    "not_found",
+    "conflict",
+    "unavailable",
+];
+/** HTTP status for each refusal code, shared by every host and App route. */
+export const appMethodRefusalStatus = {
+    invalid: 400,
+    forbidden: 403,
+    not_found: 404,
+    conflict: 409,
+    unavailable: 503,
+};
+/** Bound on the App-authored refusal message that reaches callers. */
+export const maxAppMethodRefusalMessage = 500;
+/**
+ * An App method's declared domain refusal. A handler throws it to decline a
+ * call; the generated method boundary returns it as a typed
+ * {@link AppMethodReply} instead of an execution failure. Its message is
+ * caller-facing App copy, so it must not carry private data.
+ */
+export class AppMethodRefusal extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = "AppMethodRefusal";
+        this.code = code;
+    }
+}
+/** A refused call as it crosses the generated method boundary. */
+export const appMethodRefusedReplySchema = z.strictObject({
+    kind: z.literal("refused"),
+    code: z.enum(appMethodRefusalCodes),
+    message: z.string().min(1).max(maxAppMethodRefusalMessage),
+});
+/** Every generated App method RPC answers with exactly one of these. */
+export const appMethodReplySchema = z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("ok"), value: z.json() }),
+    appMethodRefusedReplySchema,
+]);

package/dist/pending.d.ts

@@ -0,0 +1,10 @@
+import * as z from "zod";
+/** An opted-in App method is still working; poll again after this bounded delay. */
+export declare const pendingSchema: z.ZodObject<{
+    kind: z.ZodLiteral<"pending">;
+    retryAfterMs: z.ZodNumber;
+}, z.core.$strict>;
+/** The shared polling result, owned by the App contract. */
+export type Pending = Readonly<z.output<typeof pendingSchema>>;
+/** Return Pending with a polling delay between one and sixty seconds. */
+export declare function pending(retryAfterMs: number): Pending;

package/dist/pending.js

@@ -0,0 +1,10 @@
+import * as z from "zod";
+/** An opted-in App method is still working; poll again after this bounded delay. */
+export const pendingSchema = z.strictObject({
+    kind: z.literal("pending"),
+    retryAfterMs: z.number().int().min(1000).max(60_000),
+});
+/** Return Pending with a polling delay between one and sixty seconds. */
+export function pending(retryAfterMs) {
+    return Object.freeze(pendingSchema.parse({ kind: "pending", retryAfterMs }));
+}

package/dist/query.d.ts

@@ -0,0 +1,76 @@
+import { QueryClient, type MutationFunction, type QueryKey } from "@tanstack/react-query";
+import type { CapabilityContract } from "./capabilities.js";
+import { AppError } from "./errors.js";
+import type { AppRoot } from "./root.js";
+export { useFeedQuery } from "./internal/query-feed.js";
+export type { FeedSnapshot, FeedWatch } from "./internal/query-feed.js";
+/** The App-owned identity and grants needed by the query integration. */
+export type QueryApp = Pick<AppRoot, "identity" | "context" | "capabilities">;
+/** Cache identity belongs to an App surface and its selected Computer. */
+export declare const queryKeys: {
+    /** Build a cache key scoped to this App's surface and its currently
+     * selected Computer, followed by the given key parts. */
+    of(app: QueryApp | null, ...parts: QueryKey): readonly [string | null, string | null, ...unknown[]];
+};
+/** App defaults and grant lifetime binding, using the host's ordinary cache. */
+export declare function createQueryClient(): QueryClient;
+/** Decode capabilities through their owner; Query owns cancellation and retries. */
+export declare function capabilityQuery<H, T>(app: QueryApp | null, contract: CapabilityContract<H>, queryKey: QueryKey, run: (handle: H, signal: AbortSignal) => Promise<T>): import("@tanstack/react-query").OmitKeyof<import("@tanstack/react-query").UseQueryOptions<T, AppError, T, readonly unknown[]>, "queryFn"> & {
+    queryFn?: import("@tanstack/react-query").QueryFunction<T, readonly unknown[], never> | undefined;
+} & import("@tanstack/react-query").QueryKeyWithDataTag<readonly unknown[], T, AppError>;
+/**
+ * Optimistic writes for one cache entry, followed by owner reconciliation.
+ * Apply must return new data. Concurrent writes to this key run in order;
+ * queued writes wait for reconciliation instead of stacking rollback snapshots.
+ */
+export declare function optimisticMutation<TData, TVars, TResult = unknown>(options: {
+    queryKey: QueryKey;
+    mutationFn: MutationFunction<TResult, TVars>;
+    apply: (previous: TData, variables: TVars) => TData;
+}): import("@tanstack/react-query").WithRequired<import("@tanstack/react-query").UseMutationOptions<TResult, AppError, TVars, {
+    previous: TData;
+    optimistic: TData | undefined;
+} | undefined>, "mutationKey">;
+/** One shared inbox watch; reloads and stream failures retain the last live rows. */
+export declare function useMemberInbox(app: QueryApp | null): {
+    items: readonly ({
+        readonly agentId: string;
+        readonly sessionId: string;
+        readonly title: string;
+        readonly state: "running" | "done" | "needs_you" | "errored";
+        readonly createdAt: number;
+        readonly lastActivityAt: number;
+        readonly triggerId?: string | undefined;
+        readonly settledAt?: number | undefined;
+        readonly visitedAt?: number | undefined;
+    } | {
+        readonly agentId: string;
+        readonly sessionId: string;
+        readonly state: "unavailable";
+    } | {
+        readonly kind: "workflow-review";
+        readonly key: {
+            readonly runId: string;
+            readonly nodeId: string;
+            readonly iteration: string;
+        };
+        readonly state: "pending" | "closed" | "answered" | "delivered" | "timed_out";
+        readonly workflowId: string | null;
+        readonly expiresAt: number;
+        readonly installationId: string;
+        readonly workflowTitle: string;
+        readonly reviewTitle: string;
+        readonly reviewers: "runner" | "owners";
+        readonly show: readonly import("effect/Schema").Json[];
+        readonly openedAt: number;
+        readonly choices?: readonly string[] | undefined;
+    })[];
+    status: "error" | "loading" | "live";
+    error: AppError | null;
+    /** Restart the inbox watch; use after a change that the live feed
+     * would not otherwise observe. */
+    refresh: () => void;
+    /** Record that the member visited one agent session, so the inbox
+     * can clear its unread state for it. */
+    visit: (agentId: string, sessionId: string) => Promise<void>;
+};

package/dist/query.js

@@ -0,0 +1,195 @@
+import { QueryClient, hashKey, mutationOptions, queryOptions, useQueryClient, } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { useStore } from "./react.js";
+import { openAppInbox } from "./agents.js";
+import { AppError } from "./errors.js";
+import { watchInbox, useFeedQuery, queryError, } from "./internal/query-feed.js";
+export { useFeedQuery } from "./internal/query-feed.js";
+const scopes = new WeakMap();
+/** Cache identity belongs to an App surface and its selected Computer. */
+export const queryKeys = {
+    /** Build a cache key scoped to this App's surface and its currently
+     * selected Computer, followed by the given key parts. */
+    of(app, ...parts) {
+        return [
+            app?.identity.surfaceId ?? null,
+            app?.context.get().computerId ?? null,
+            ...parts,
+        ];
+    },
+};
+function scopeMeta(app) {
+    const meta = {};
+    if (app)
+        scopes.set(meta, app);
+    return meta;
+}
+/** App defaults and grant lifetime binding, using the host's ordinary cache. */
+export function createQueryClient() {
+    const client = new QueryClient({
+        defaultOptions: {
+            queries: { retry: false, staleTime: 30_000, refetchOnWindowFocus: false },
+            mutations: { retry: false },
+        },
+    });
+    const bindings = new Map();
+    client.getQueryCache().subscribe((event) => {
+        const query = event.query;
+        if (event.type === "removed") {
+            bindings.get(query.queryHash)?.release();
+            bindings.delete(query.queryHash);
+            return;
+        }
+        const app = query.meta && scopes.get(query.meta);
+        const previous = bindings.get(query.queryHash);
+        if (previous?.app === app)
+            return;
+        previous?.release();
+        bindings.delete(query.queryHash);
+        if (!app)
+            return;
+        const reset = () => {
+            // The host publishes new grants before the accompanying Computer context.
+            // Clear revoked data and cancel old reads only after that atomic RPC turn.
+            queueMicrotask(() => {
+                if (client.getQueryCache().get(query.queryHash) !== query ||
+                    bindings.get(query.queryHash)?.app !== app)
+                    return;
+                void client.resetQueries({
+                    predicate: (candidate) => candidate === query,
+                });
+            });
+        };
+        const release = app.capabilities.subscribe(reset);
+        bindings.set(query.queryHash, { app, release });
+        // Reconnecting the same logical surface replaces its remote handles too.
+        if (previous)
+            reset();
+    });
+    return client;
+}
+/** Decode capabilities through their owner; Query owns cancellation and retries. */
+export function capabilityQuery(app, contract, queryKey, run) {
+    const computerId = app?.context.get().computerId;
+    return queryOptions({
+        queryKey,
+        meta: scopeMeta(app),
+        enabled: app !== null,
+        retry: false,
+        queryFn: async ({ signal }) => {
+            try {
+                if (!app)
+                    throw new AppError("No App connection", {
+                        code: "DISCONNECTED",
+                        retryable: true,
+                    });
+                if (app.context.get().computerId !== computerId)
+                    throw new AppError("The selected Computer changed", {
+                        code: "SELECTION_CHANGED",
+                        retryable: false,
+                    });
+                return await run(app.capabilities.require(contract), signal);
+            }
+            catch (cause) {
+                throw queryError(cause);
+            }
+        },
+    });
+}
+/**
+ * Optimistic writes for one cache entry, followed by owner reconciliation.
+ * Apply must return new data. Concurrent writes to this key run in order;
+ * queued writes wait for reconciliation instead of stacking rollback snapshots.
+ */
+export function optimisticMutation(options) {
+    return mutationOptions({
+        mutationKey: options.queryKey,
+        scope: { id: hashKey(options.queryKey) },
+        mutationFn: async (variables, context) => {
+            try {
+                return await options.mutationFn(variables, context);
+            }
+            catch (cause) {
+                throw queryError(cause);
+            }
+        },
+        onMutate: async (variables, { client }) => {
+            if (client.isMutating({ mutationKey: options.queryKey, exact: true }) > 1)
+                return undefined;
+            await client.cancelQueries({ queryKey: options.queryKey, exact: true });
+            const previous = client.getQueryData(options.queryKey);
+            if (previous === undefined)
+                return undefined;
+            client.setQueryData(options.queryKey, options.apply(previous, variables));
+            return {
+                previous,
+                optimistic: client.getQueryData(options.queryKey),
+            };
+        },
+        onError: (_error, _variables, snapshot, { client }) => {
+            if (snapshot &&
+                client.getQueryData(options.queryKey) === snapshot.optimistic)
+                client.setQueryData(options.queryKey, snapshot.previous);
+        },
+        onSettled: (_data, _error, _variables, _snapshot, { client }) => client.invalidateQueries({ queryKey: options.queryKey, exact: true }),
+    });
+}
+/** One shared inbox watch; reloads and stream failures retain the last live rows. */
+export function useMemberInbox(app) {
+    useStore(app?.context);
+    const client = useQueryClient();
+    const computerId = app?.context.get().computerId;
+    const queryKey = useMemo(() => queryKeys.of(app, "member-inbox"), [app, computerId]);
+    const watch = useCallback((onChange, signal) => {
+        if (app?.context.get().computerId !== computerId)
+            throw new AppError("The selected Computer changed", {
+                code: "SELECTION_CHANGED",
+                retryable: false,
+            });
+        return watchInbox(app, onChange, signal);
+    }, [app, computerId]);
+    const query = useFeedQuery(queryKey, watch, {
+        enabled: app !== null,
+        meta: scopeMeta(app),
+    });
+    // A watch has no completion promise; refreshing restarts it in the cache.
+    const refresh = useCallback(() => {
+        void client.invalidateQueries({ queryKey, exact: true });
+    }, [client, queryKey]);
+    const visit = useCallback(async (agentId, sessionId) => {
+        if (!app)
+            throw new AppError("No App connection", {
+                code: "DISCONNECTED",
+                retryable: true,
+            });
+        const transport = await openAppInbox(app.capabilities);
+        try {
+            const response = await transport.fetch(`${transport.baseUrl}/inbox/visits`, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ agentId, sessionId }),
+            });
+            if (!response.ok && response.status !== 404)
+                throw new AppError("Visit was not recorded", {
+                    code: "HOST_FAILURE",
+                    retryable: true,
+                });
+        }
+        finally {
+            await transport.close();
+        }
+    }, [app]);
+    return {
+        items: query.data?.data ?? [],
+        status: query.isError
+            ? "error"
+            : (query.data?.status ?? "loading"),
+        error: query.error,
+        /** Restart the inbox watch; use after a change that the live feed
+         * would not otherwise observe. */
+        refresh,
+        /** Record that the member visited one agent session, so the inbox
+         * can clear its unread state for it. */
+        visit,
+    };
+}

package/dist/react-mount.d.ts

@@ -0,0 +1,23 @@
+import { type QueryClient } from "@tanstack/react-query";
+import { type ReactNode } from "react";
+import type { AppRoot } from "./root.js";
+import type { Disposer } from "./store.js";
+/** The App connection state passed to `mountApp`'s `render` callback:
+ * `live` once connected, or `connecting`/`standalone`/`ended` while there
+ * is no usable App. */
+export type AppMountState = Readonly<{
+    app: AppRoot;
+    status: "live";
+} | {
+    app: null;
+    status: "connecting" | "standalone" | "ended";
+}>;
+/** Options passed to `mountApp`. */
+export type AppMountOptions = Readonly<{
+    /** App name used when reporting a failed host connection. */
+    name: string;
+    /** The caller owns the cache and its query policy. */
+    queryClient?: QueryClient;
+}>;
+/** Own this page's React root, authenticated App connection and host theme. */
+export declare function mountApp(element: HTMLElement, options: AppMountOptions, render: (state: AppMountState) => ReactNode): Disposer;

package/dist/react-mount.js

@@ -0,0 +1,108 @@
+import { applyTheme, getTheme } from "@fungi.computer/stipe/theme";
+import { QueryClientProvider } from "@tanstack/react-query";
+import { createElement, useLayoutEffect } from "react";
+import { createRoot } from "react-dom/client";
+import { connectApp } from "./connect.js";
+import { AppError } from "./errors.js";
+/** Own this page's React root, authenticated App connection and host theme. */
+export function mountApp(element, options, render) {
+    element.style.isolation = "isolate";
+    const root = createRoot(element);
+    const controller = new AbortController();
+    const themeRoot = element.ownerDocument.documentElement;
+    const previousTheme = getTheme(themeRoot);
+    let mounted;
+    let releaseTheme;
+    let releaseLifecycle;
+    let themed = false;
+    const publish = (state) => {
+        const view = createElement(AppView, { state, render });
+        root.render(options.queryClient
+            ? createElement(QueryClientProvider, { client: options.queryClient }, view)
+            : view);
+    };
+    const releaseConnection = () => {
+        releaseLifecycle?.();
+        releaseLifecycle = undefined;
+        releaseTheme?.();
+        releaseTheme = undefined;
+        const connection = mounted;
+        mounted = undefined;
+        connection?.dispose();
+        if (themed) {
+            if (previousTheme === null)
+                themeRoot.removeAttribute("data-theme");
+            else
+                applyTheme(previousTheme, themeRoot);
+            themed = false;
+        }
+    };
+    const { referrer, defaultView } = element.ownerDocument;
+    performance.mark("fungi.app-open.react-root-render-start");
+    if (!defaultView ||
+        defaultView.parent === defaultView ||
+        !URL.canParse(referrer)) {
+        publish({ app: null, status: "standalone" });
+    }
+    else {
+        publish({ app: null, status: "connecting" });
+        void connectApp({
+            expectedHostOrigin: new URL(referrer).origin,
+            signal: controller.signal,
+        })
+            .then((app) => {
+            if (controller.signal.aborted) {
+                app.dispose();
+                return;
+            }
+            mounted = app;
+            const onLifecycle = () => {
+                const state = app.lifecycle.get();
+                if (state === "disposing" ||
+                    state === "disconnected" ||
+                    state === "disposed") {
+                    releaseConnection();
+                    publish({ app: null, status: "ended" });
+                    return true;
+                }
+                return false;
+            };
+            releaseLifecycle = app.lifecycle.subscribe(onLifecycle);
+            if (onLifecycle())
+                return;
+            themed = true;
+            applyTheme(app.theme.get(), themeRoot);
+            releaseTheme = app.theme.subscribe((theme) => {
+                applyTheme(theme, themeRoot);
+            });
+            publish({ app, status: "live" });
+        })
+            .catch((cause) => {
+            if (controller.signal.aborted &&
+                cause instanceof AppError &&
+                cause.code === "CANCELLED")
+                return;
+            console.error(`${options.name} host connection failed`, cause);
+            releaseConnection();
+            if (!controller.signal.aborted)
+                publish({ app: null, status: "ended" });
+        });
+    }
+    return () => {
+        if (controller.signal.aborted)
+            return;
+        controller.abort();
+        root.unmount();
+        releaseConnection();
+    };
+}
+function AppView({ state, render, }) {
+    useLayoutEffect(() => {
+        performance.mark("fungi.app-open.react-initial-commit");
+    }, []);
+    useLayoutEffect(() => {
+        if (state.app)
+            performance.mark("fungi.app-open.react-connected-commit");
+    }, [state.app]);
+    return render(state);
+}

package/dist/react.d.ts

@@ -0,0 +1,41 @@
+import { type WhistleContribution, type WhistleRuntime } from "@fungi.computer/whistle";
+import type { AppBackHandler, HostNavigation } from "./window.js";
+import type { AppContext } from "./lifecycle.js";
+import type { AppStatusActionHandler, AppStatusItem } from "./ui.js";
+import type { AppRoot } from "./root.js";
+import type { ReadonlyStore } from "./store.js";
+export { mountApp } from "./react-mount.js";
+export type { AppMountOptions, AppMountState } from "./react-mount.js";
+/** Read an SDK snapshot and release its subscription when the store changes. */
+export declare function useStore<T>(store: ReadonlyStore<T> | undefined): T | undefined;
+/** Read the App's live context (focus, visibility, Computer selection, any
+ * pending open request), or null while there is no connected App. */
+export declare function useAppContext(app: AppRoot | null | undefined): AppContext | null;
+/** Read the id of the Computer currently selected for this App, or null
+ * when no App is connected or no Computer is selected yet. */
+export declare function useComputerId(app: AppRoot | null | undefined): string | null;
+/**
+ * Keep this window's status bar items current in the host while mounted, and
+ * hear the person use them. Items compare by value; the bar clears on unmount.
+ */
+export declare function useWindowStatus(app: Pick<AppRoot, "ui"> | null | undefined, items: readonly AppStatusItem[], onAction?: AppStatusActionHandler, 
+/** Hear a report the host refused, so the App can say so. */
+onReportFailure?: (cause: unknown) => void): void;
+/**
+ * Own one catalog's local slash runtime and host registrations. Memoize `build`
+ * with useCallback; changing it replaces the catalog and its availability.
+ */
+export declare function useAppCommandCatalog(app: AppRoot | null | undefined, { sourceId, namespace }: Pick<WhistleContribution, "sourceId" | "namespace">, build: () => WhistleContribution["commands"]): WhistleRuntime;
+/** What an App's router can do now, and how it goes back. */
+export type HostNavigationOptions = Readonly<{
+    canGoBack: boolean;
+    /** The current page's title, shown after the App name in window chrome. */
+    title?: string | undefined;
+    onBack: AppBackHandler;
+}>;
+/**
+ * Publish an App's navigation state to its host and own the host's Back
+ * requests while mounted. Pass `app?.window.navigation`; with no connected
+ * App it does nothing. Unmounting withdraws Back from the host chrome.
+ */
+export declare function useHostNavigation(navigation: HostNavigation | null | undefined, { canGoBack, title, onBack }: HostNavigationOptions): void;