@fungi.computer/agar 0.0.0-stage → 0.0.1

package/dist/connect.js

@@ -0,0 +1,211 @@
+import { reportCatchFailure } from "./failure.js";
+import * as Schema from "effect/Schema";
+import * as Predicate from "effect/Predicate";
+/**
+ * WHY: the iframe owns one authenticated page epoch; this door validates the
+ * host before handing transport ownership to the internal session (2026-08-27).
+ */
+import { AppError } from "./errors.js";
+import { connectAppPort } from "./internal/app-session.js";
+import { APP_CONNECT_TYPE, APP_PROTOCOL_VERSION, APP_READY_TYPE, } from "./internal/protocol.js";
+import { parseConnect } from "./internal/schemas.js";
+let liveConnection = false;
+/** Owns the pending handshake and its one-way transition into a live epoch. */
+class PendingAppConnection {
+    options;
+    #appWindow;
+    #origin;
+    #port;
+    #settled = false;
+    #readyRetry;
+    #deadline;
+    constructor(options) {
+        this.options = options;
+        this.#origin = expectedOrigin(options.expectedHostOrigin);
+        this.#appWindow = globalThis.window;
+    }
+    start() {
+        performance.mark("fungi.app-open.agar-connect-start");
+        const origin = this.#origin;
+        if (!origin)
+            return Promise.reject(invalidOrigin());
+        const error = this.#startError();
+        if (error)
+            return Promise.reject(error);
+        liveConnection = true;
+        return this.#awaitConnection(origin);
+    }
+    #awaitConnection(origin) {
+        return new Promise((resolve, reject) => {
+            const finish = (error, root) => {
+                this.#finish(error, root, onMessage, onAbort, resolve, reject);
+            };
+            const onAbort = () => {
+                finish(cancelled());
+            };
+            const onMessage = (event) => {
+                this.#onMessage(event, origin, finish, onMessage);
+            };
+            this.#appWindow.addEventListener("message", onMessage);
+            this.options.signal?.addEventListener("abort", onAbort, { once: true });
+            const notify = () => {
+                try {
+                    performance.mark("fungi.app-open.agar-ready-sent");
+                    this.#appWindow.parent.postMessage({ protocolVersion: APP_PROTOCOL_VERSION, type: APP_READY_TYPE }, origin);
+                }
+                catch (cause) {
+                    reportCatchFailure("connect.notify-host", cause);
+                    finish(notifyError(cause));
+                }
+            };
+            // A remounted document can announce itself before its host sees load.
+            // Retry only the handshake, never an admitted App operation.
+            this.#readyRetry = setInterval(notify, 200);
+            this.#deadline = setTimeout(() => {
+                finish(disconnected());
+            }, 10_000);
+            notify();
+        });
+    }
+    #finish(error, root, onMessage, onAbort, resolve, reject) {
+        if (this.#settled)
+            return;
+        this.#settled = true;
+        this.#stopReady();
+        this.#appWindow.removeEventListener("message", onMessage);
+        this.options.signal?.removeEventListener("abort", onAbort);
+        if (error || !root) {
+            this.#port?.close();
+            liveConnection = false;
+            reject(error ?? disconnected());
+            return;
+        }
+        resolve(root);
+    }
+    #onMessage(event, origin, finish, onMessage) {
+        if (!isConnectMessage(event.data))
+            return;
+        performance.mark("fungi.app-open.agar-connect-received");
+        if (event.source !== this.#appWindow.parent || event.origin !== origin) {
+            finish(identityError());
+            return;
+        }
+        const message = parseConnection(event, finish);
+        if (!message)
+            return;
+        const port = event.ports.length === 1 ? event.ports[0] : undefined;
+        if (!port) {
+            finish(protocolError("The app host did not transfer exactly one port"));
+            return;
+        }
+        this.#port = port;
+        this.#stopReady();
+        this.#appWindow.removeEventListener("message", onMessage);
+        void connectAppPort({
+            epoch: message.epoch,
+            isActive: () => !this.#settled,
+            onDisposed: () => {
+                liveConnection = false;
+            },
+            port,
+            window: this.#appWindow,
+        }).then((root) => {
+            performance.mark("fungi.app-open.agar-root-ready");
+            finish(undefined, root);
+        }, (cause) => {
+            finish(connectionError(cause));
+        });
+    }
+    #stopReady() {
+        clearInterval(this.#readyRetry);
+        clearTimeout(this.#deadline);
+        this.#readyRetry = undefined;
+        this.#deadline = undefined;
+    }
+    #startError() {
+        if (this.options.signal?.aborted)
+            return cancelled();
+        if (liveConnection)
+            return new AppError("An app connection is already live", {
+                code: "IDENTITY",
+                retryable: false,
+            });
+        if (Predicate.isUndefined(globalThis.window) ||
+            this.#appWindow.parent === this.#appWindow)
+            return new AppError("The app host is unavailable", {
+                code: "DISCONNECTED",
+                retryable: true,
+            });
+        return undefined;
+    }
+}
+/** Connects this iframe page to its authenticated host. */
+export function connectApp(options) {
+    return new PendingAppConnection(options).start();
+}
+function cancelled() {
+    return new AppError("App connection was cancelled", {
+        code: "CANCELLED",
+        retryable: false,
+    });
+}
+function connectionError(cause) {
+    return cause instanceof AppError
+        ? cause
+        : new AppError("Unable to connect to the app host", {
+            cause,
+            code: "PROTOCOL",
+            retryable: false,
+        });
+}
+function disconnected() {
+    return new AppError("The app host disconnected", {
+        code: "DISCONNECTED",
+        retryable: true,
+    });
+}
+function expectedOrigin(value) {
+    if (!URL.canParse(value))
+        return undefined;
+    const origin = new URL(value).origin;
+    return origin === value ? origin : undefined;
+}
+function identityError() {
+    return new AppError("The app connection identity is invalid", {
+        code: "IDENTITY",
+        retryable: false,
+    });
+}
+function invalidOrigin() {
+    return new AppError("expectedHostOrigin must be an origin", {
+        code: "INVALID_ARGUMENT",
+        retryable: false,
+    });
+}
+const isConnectMessage = Schema.is(Schema.Struct({ type: Schema.Literal(APP_CONNECT_TYPE) }));
+function notifyError(cause) {
+    return new AppError("Unable to notify the app host", {
+        cause,
+        code: "DISCONNECTED",
+        retryable: true,
+    });
+}
+function parseConnection(event, finish) {
+    try {
+        return parseConnect(event.data);
+    }
+    catch (cause) {
+        reportCatchFailure("connect.decode-message", cause);
+        finish(cause instanceof AppError
+            ? cause
+            : new AppError("Malformed app connection", {
+                cause,
+                code: "PROTOCOL",
+                retryable: false,
+            }));
+        return undefined;
+    }
+}
+function protocolError(message) {
+    return new AppError(message, { code: "PROTOCOL", retryable: false });
+}

package/dist/errors.d.ts

@@ -0,0 +1,34 @@
+/** The closed set of reasons an AppError can state; every SDK and
+ * host-reported failure is tagged with exactly one of these codes. */
+export type AppErrorCode = "CANCELLED" | "CAPABILITY_DENIED" | "CAPABILITY_REVOKED" | "COMMAND_NOT_DECLARED" | "CONFLICT" | "DISCONNECTED" | "FILE_TOO_LARGE" | "HOST_FAILURE" | "IDENTITY" | "INSUFFICIENT_CREDIT" | "INVALID_ARGUMENT" | "PROTOCOL" | "SAFETY_FILTER_REFUSED" | "SELECTION_CHANGED" | "TIMEOUT";
+/** Required construction options for an AppError. */
+export type AppErrorOptions = {
+    readonly cause?: unknown;
+    readonly code: AppErrorCode;
+    /** Every error states retry truth explicitly; absence is not a verdict. */
+    readonly retryable: boolean;
+};
+/** The SDK's one typed failure. Carries a closed `code` naming the failure
+ * kind and an explicit `retryable` verdict, instead of leaving callers to
+ * guess either from the message or exception shape. */
+export declare class AppError extends Error {
+    readonly code: AppErrorCode;
+    readonly retryable: boolean;
+    constructor(message: string, options: AppErrorOptions);
+}
+/** Trusted presentation copy; overrides never change recovery or retry policy. */
+export type ErrorCopy = Readonly<{
+    title: string;
+    message: string;
+}>;
+/** Recovery hints are for the caller's UI, never an instruction to retry automatically. */
+export type ErrorDescription = ErrorCopy & Readonly<{
+    retryable: boolean;
+    action?: "grant" | "retry" | "reconnect" | "billing";
+}>;
+/**
+ * Describe an SDK-decoded failure without exposing exception or request data.
+ * The error owner retains retry truth. Grant and reconnect hints describe
+ * prerequisites, so they can accompany a non-retryable operation.
+ */
+export declare function describeAppError(cause: unknown, overrides?: Partial<Record<AppErrorCode, ErrorCopy>>): ErrorDescription;

package/dist/errors.js

@@ -0,0 +1,106 @@
+/** The SDK's one typed failure. Carries a closed `code` naming the failure
+ * kind and an explicit `retryable` verdict, instead of leaving callers to
+ * guess either from the message or exception shape. */
+export class AppError extends Error {
+    code;
+    retryable;
+    constructor(message, options) {
+        super(message, { cause: options.cause });
+        this.name = "AppError";
+        this.code = options.code;
+        this.retryable = options.retryable;
+    }
+}
+// User-facing wording approved by Levi; keep it in one reviewable table.
+const errorCopy = {
+    CANCELLED: {
+        title: "Request cancelled",
+        message: "This request was cancelled.",
+    },
+    CAPABILITY_DENIED: {
+        title: "Access needed",
+        message: "This App needs permission to do that.",
+        action: "grant",
+    },
+    CAPABILITY_REVOKED: {
+        title: "Access changed",
+        message: "This App no longer has permission to do that.",
+        action: "grant",
+    },
+    COMMAND_NOT_DECLARED: {
+        title: "Action unavailable",
+        message: "This action isn't available in this App.",
+    },
+    CONFLICT: {
+        title: "File changed",
+        message: "This file changed elsewhere. Review it before saving again.",
+    },
+    DISCONNECTED: {
+        title: "Connection lost",
+        message: "Reopen the App to connect again.",
+        action: "reconnect",
+    },
+    HOST_FAILURE: {
+        title: "Couldn't complete the request",
+        message: "The service couldn't complete this request.",
+    },
+    FILE_TOO_LARGE: {
+        title: "File too large",
+        message: "Choose a file within the supported size limit.",
+    },
+    IDENTITY: {
+        title: "Couldn't connect",
+        message: "Reopen the App to connect again.",
+        action: "reconnect",
+    },
+    INSUFFICIENT_CREDIT: {
+        title: "Something went wrong",
+        message: "The App couldn't complete this request.",
+        action: "billing",
+    },
+    INVALID_ARGUMENT: {
+        title: "Request not accepted",
+        message: "The App couldn't use the details in this request.",
+    },
+    PROTOCOL: {
+        title: "Couldn't read the response",
+        message: "The App received a response it couldn't use.",
+    },
+    SAFETY_FILTER_REFUSED: {
+        title: "Safety filter refused this prompt",
+        message: "The model's safety filter refused this prompt — try rewording.",
+    },
+    SELECTION_CHANGED: {
+        title: "Selection changed",
+        message: "The selection changed during this request. Reopen the App to continue.",
+        action: "reconnect",
+    },
+    TIMEOUT: {
+        title: "Still waiting",
+        message: "The request didn't respond in time. Its outcome isn't known yet.",
+    },
+    UNKNOWN: {
+        title: "Something went wrong",
+        message: "The App couldn't complete this request.",
+    },
+};
+/**
+ * Describe an SDK-decoded failure without exposing exception or request data.
+ * The error owner retains retry truth. Grant and reconnect hints describe
+ * prerequisites, so they can accompany a non-retryable operation.
+ */
+export function describeAppError(cause, overrides) {
+    if (!(cause instanceof AppError))
+        return { ...errorCopy.UNKNOWN, retryable: false };
+    const entry = errorCopy[cause.code];
+    const copy = overrides?.[cause.code] ?? entry;
+    const action = entry.action ?? (cause.retryable ? "retry" : undefined);
+    const description = {
+        title: copy.title,
+        message: copy.message,
+        retryable: cause.retryable,
+    };
+    if (action)
+        return { ...description, action };
+    return description;
+}

package/dist/failure.d.ts

@@ -0,0 +1,2 @@
+/** Retain the original Agar failure without printing exception or request data. */
+export declare function reportCatchFailure(operation: string, cause: unknown): void;

package/dist/failure.js

@@ -0,0 +1,9 @@
+import * as Redacted from "effect/Redacted";
+/** Retain the original Agar failure without printing exception or request data. */
+export function reportCatchFailure(operation, cause) {
+    console.error(JSON.stringify({
+        source: "agar",
+        operation,
+        failureKind: cause instanceof Error ? "Error" : "NonErrorThrown",
+    }), Redacted.make(cause));
+}

package/dist/files.d.ts

@@ -0,0 +1,25 @@
+/** A parent-owned read. Closing it aborts the parent HTTP operation. */
+export type AppFileRead = Disposable & {
+    /** Resolve with the underlying Response once it is available. */
+    response(): Promise<Response>;
+    /** Release the parent's open read, aborting it if still in flight. */
+    close(): Promise<void>;
+};
+/** Native Response crosses RPC; File is constructed only in the receiving App. */
+export declare function readAppFile(read: AppFileRead, options: {
+    name: string;
+    signal?: AbortSignal;
+}): Promise<File>;
+/** A parent-owned upload; close requests transport abort, never promises rollback. */
+export type AppFileWrite = Disposable & {
+    /** Stream the upload's content to the parent-owned destination. */
+    write(content: ReadableStream<Uint8Array>): Promise<void>;
+    /** Request that the parent abort or finalize the upload transport. */
+    close(): Promise<void>;
+};
+/** Stream a Blob's bytes to a parent-owned upload. Aborting `signal` closes
+ * the upload early; a close failure after a successful write is reported,
+ * never thrown, since it cannot change an already-acknowledged commit. */
+export declare function writeAppFile(write: AppFileWrite, content: Blob, options: {
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/files.js

@@ -0,0 +1,84 @@
+import { disposeRpcValue } from "./internal/capabilities.js";
+import * as Schema from "effect/Schema";
+import { reportCatchFailure } from "./failure.js";
+import { AppError } from "./errors.js";
+const decodeTooLarge = Schema.decodeUnknownOption(Schema.fromJsonString(Schema.Struct({ error: Schema.Literal("too_large") })));
+/** Native Response crosses RPC; File is constructed only in the receiving App. */
+export async function readAppFile(read, options) {
+    let closing;
+    const close = () => (closing ??= read.close());
+    const abort = () => {
+        // The finalizer awaits this same close; the event callback cannot await it.
+        void close().catch((cause) => {
+            reportCatchFailure("files.read.abort-close", cause);
+        });
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        options.signal?.throwIfAborted();
+        const result = await read.response();
+        try {
+            const response = Schema.decodeUnknownSync(Schema.instanceOf(Response))(result);
+            if (response.status === 413) {
+                const failure = decodeTooLarge(await response.text());
+                throw new AppError("App file exceeds the read bound", {
+                    code: failure._tag === "Some" ? "FILE_TOO_LARGE" : "PROTOCOL",
+                    retryable: false,
+                });
+            }
+            if (!response.ok)
+                throw new Error(`App file unavailable (${String(response.status)})`);
+            const blob = await response.blob();
+            options.signal?.throwIfAborted();
+            return new File([blob], options.name, {
+                type: blob.type,
+                lastModified: 0,
+            });
+        }
+        finally {
+            disposeRpcValue(result);
+        }
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abort);
+        try {
+            await close();
+        }
+        finally {
+            read[Symbol.dispose]();
+        }
+    }
+}
+/** Stream a Blob's bytes to a parent-owned upload. Aborting `signal` closes
+ * the upload early; a close failure after a successful write is reported,
+ * never thrown, since it cannot change an already-acknowledged commit. */
+export async function writeAppFile(write, content, options) {
+    let closing;
+    const close = () => (closing ??= write.close());
+    const abort = () => {
+        void close().catch((cause) => {
+            reportCatchFailure("files.write.abort-close", cause);
+        });
+    };
+    options.signal?.addEventListener("abort", abort, { once: true });
+    try {
+        options.signal?.throwIfAborted();
+        await write.write(content.stream());
+    }
+    finally {
+        options.signal?.removeEventListener("abort", abort);
+        // Cleanup cannot change an acknowledged commit or replace the primary write error.
+        try {
+            await close();
+        }
+        catch (cause) {
+            reportCatchFailure("files.write.remote-close", cause);
+        }
+        try {
+            write[Symbol.dispose]();
+        }
+        catch (cause) {
+            reportCatchFailure("files.write.local-dispose", cause);
+        }
+    }
+}