@trylight/app 0.1.9 → 0.2.0

package/dist/invoke/index.d.ts

@@ -0,0 +1,73 @@
+import type { ContractInput, ContractOutput, Contracts } from "./contracts.js";
+import { InvocationError } from "./error.js";
+export { InvocationError };
+export type { Invocation, InvocationState } from "./contracts.js";
+/** How long one read asks the platform to hold a pending invocation; the platform clamps it to its own limit. */
+export declare const INVOCATION_WAIT_SECONDS = 60;
+/** The pause after a read that failed before asking again. */
+export declare const INVOCATION_RETRY_MS = 1500;
+/** How long a run started with `remember` is picked up again in this browser. */
+export declare const INVOCATION_REMEMBER_MS: number;
+type Result = Record<string, unknown>;
+/**
+ * `id` and `input` are null until the platform has the invocation. `input` is the
+ * run's input as JSON, so a page that picked a run up can show what it is
+ * for. While pending, `pollError` is why the latest read failed, or null: the
+ * wait goes on either way, and the app decides when a server that stays down
+ * is worth telling the person about.
+ */
+export type InvocationStatus<Output> = {
+    readonly state: "idle";
+} | {
+    readonly state: "pending";
+    readonly id: string | null;
+    readonly input: Result | null;
+    readonly elapsedMs: number;
+    readonly pollError: InvocationError | null;
+} | {
+    readonly state: "succeeded";
+    readonly id: string;
+    readonly input: Result;
+    readonly result: Output;
+    readonly elapsedMs: number;
+} | {
+    readonly state: "failed";
+    readonly id: string | null;
+    readonly input: Result | null;
+    readonly error: InvocationError;
+    readonly elapsedMs: number;
+};
+export type UseInvocationOptions = {
+    /**
+     * A name for what this press is for (`"fill:revenue"`, `"add-candidates"`).
+     * A run started with it is picked up again when the page reloads or the
+     * tab is reopened in this browser, finished or not, until `reset()` or
+     * INVOCATION_REMEMBER_MS after it started.
+     */
+    readonly remember?: string | null;
+};
+export type Invoker<C extends Contracts> = {
+    invoke<K extends keyof C & string>(key: K, input: ContractInput<C, K>, signal?: AbortSignal): Promise<ContractOutput<C, K>>;
+    useInvocation<K extends keyof C & string>(key: K, options?: UseInvocationOptions): {
+        readonly status: InvocationStatus<ContractOutput<C, K>>;
+        run(input: ContractInput<C, K>): void;
+        /** Follow a run already started, such as one a server function started and the app stored. */
+        resume(id: string): void;
+        /** Back to idle; a remembered run is let go of. */
+        reset(): void;
+    };
+};
+export declare function createInvoker<C extends Contracts>(): Invoker<C>;
+/**
+ * One button's invocations, outside React so it can be tested: at most one is
+ * live, and one that was replaced, reset or disposed of reports nothing more.
+ * With `remember`, `restore()` picks up the run this browser last started with it.
+ */
+export declare function createInvocationController<Output = Result>(key: string, onStatus: (status: InvocationStatus<Output>) => void, { remember }?: UseInvocationOptions): {
+    run: (input: unknown) => void;
+    resume: (id: string) => void;
+    /** With `remember`: follow the run this browser noted. */
+    restore: () => void;
+    reset: () => void;
+    dispose: () => void;
+};

package/dist/invoke/index.js

@@ -0,0 +1,274 @@
+"use client";
+// Nothing here gives up on its own: an agent may take a second or an hour, so
+// the hook reports how long it has been and the app decides what that means.
+import { useEffect, useMemo, useState } from "react";
+import { z } from "zod/v4";
+import { errorBody } from "../request-error.js";
+import { failedRun, InvocationError } from "./error.js";
+import { INVOKE_BASE_PATH } from "./paths.js";
+export { InvocationError };
+/** How long one read asks the platform to hold a pending invocation; the platform clamps it to its own limit. */
+export const INVOCATION_WAIT_SECONDS = 60;
+/** The pause after a read that failed before asking again. */
+export const INVOCATION_RETRY_MS = 1500;
+/** How long a run started with `remember` is picked up again in this browser. */
+export const INVOCATION_REMEMBER_MS = 24 * 60 * 60 * 1000;
+const ELAPSED_TICK_MS = 1000;
+const REMEMBERED_PREFIX = "mii-invocation:";
+export function createInvoker() {
+    return {
+        async invoke(key, input, signal = null) {
+            const started = await startInvocation(key, input, signal);
+            return (await awaitInvocation(started, signal)).result;
+        },
+        useInvocation(key, { remember = null } = {}) {
+            return useInvocationOf(key, remember);
+        }
+    };
+}
+// `Output` is the contract's: the app's server parsed the result with its schema.
+function startInvocation(key, input, signal = null) {
+    return call("POST", "/invocations", { key, input }, signal);
+}
+const unwatched = () => undefined;
+/** One read of an invocation; the platform holds a pending one for up to `wait` seconds. */
+function readInvocation(id, options) {
+    const query = new URLSearchParams({ wait: String(options.wait) });
+    return call("GET", `/invocations/${id}?${query}`, null, options.signal);
+}
+/** Reads until one is answered. Rejects with InvocationError, or the signal's reason. */
+async function readAnswered(id, holdSeconds, signal = null, onPoll = unwatched) {
+    for (;;) {
+        try {
+            const read = await readInvocation(id, { wait: holdSeconds, signal });
+            onPoll(read, null);
+            return read;
+        }
+        catch (error) {
+            // The platform or the network having a bad minute says nothing about the
+            // invocation, which carries on either way.
+            if (!(error instanceof InvocationError) || (error.status !== 0 && error.status < 500))
+                throw error;
+            console.error("mii-invoke: a read failed; trying again", error);
+            onPoll(null, error);
+            await wait(INVOCATION_RETRY_MS, signal);
+        }
+    }
+}
+/** Follow an invocation, each read held by the platform while it is pending, to its end. */
+async function awaitInvocation(started, signal = null, onPoll = unwatched) {
+    let invocation = started;
+    while (invocation.state === "pending") {
+        invocation = await readAnswered(invocation.id, INVOCATION_WAIT_SECONDS, signal, onPoll);
+    }
+    if (invocation.state === "succeeded")
+        return invocation;
+    throw failedRun(invocation.lastError);
+}
+/** One request to the invoke routes: a POST carries `body` as JSON, a GET nothing. */
+async function call(method, path, body, signal) {
+    let response;
+    try {
+        response = await fetch(`${INVOKE_BASE_PATH}${path}`, {
+            method,
+            credentials: "same-origin",
+            ...(body === null ? {} : { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) }),
+            signal
+        });
+    }
+    catch (error) {
+        if (signal !== null && signal.aborted)
+            throw error;
+        throw new InvocationError(0, "unavailable", `Couldn't reach this app's server: ${String(error)}`);
+    }
+    const text = await response.text();
+    if (!response.ok) {
+        const refusal = errorBody(text, `The request failed (HTTP ${response.status}).`);
+        throw new InvocationError(response.status, refusal.code, refusal.detail);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        // Something answered in the handler's place, like a page the app serves for any path.
+        throw new InvocationError(response.status, "not_the_handler", "The app's invoke routes are not reachable.");
+    }
+}
+function wait(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal === null) {
+            setTimeout(resolve, ms);
+            return;
+        }
+        const abort = () => {
+            clearTimeout(timer);
+            reject(signal.reason);
+        };
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", abort);
+            resolve();
+        }, ms);
+        signal.addEventListener("abort", abort, { once: true });
+    });
+}
+// This browser's note of a remembered run. Storage can be blocked or full;
+// then the run is simply not picked up again. Whose run it is the platform decides:
+// another person's id reads as not found, and the note is let go of.
+const remembered = z.object({ id: z.string(), startedAt: z.number() });
+function recall(name) {
+    let text;
+    try {
+        text = globalThis.localStorage.getItem(name);
+    }
+    catch {
+        return null;
+    }
+    if (text === null)
+        return null;
+    const note = readNote(text);
+    if (note === null || Date.now() - note.startedAt > INVOCATION_REMEMBER_MS) {
+        keep(name, null);
+        return null;
+    }
+    return note;
+}
+/** A note this code wrote, or null for anything else. */
+function readNote(text) {
+    let note;
+    try {
+        note = JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+    const read = remembered.safeParse(note);
+    return read.success ? read.data : null;
+}
+function keep(name, remembered) {
+    try {
+        if (remembered === null)
+            globalThis.localStorage.removeItem(name);
+        else
+            globalThis.localStorage.setItem(name, JSON.stringify(remembered));
+    }
+    catch {
+        return;
+    }
+}
+const IDLE = { state: "idle" };
+/**
+ * One button's invocations, outside React so it can be tested: at most one is
+ * live, and one that was replaced, reset or disposed of reports nothing more.
+ * With `remember`, `restore()` picks up the run this browser last started with it.
+ */
+export function createInvocationController(key, onStatus, { remember = null } = {}) {
+    const name = remember === null ? null : `${REMEMBERED_PREFIX}${key}:${remember}`;
+    // The run this button follows. `note` goes false once it is replaced or
+    // reset, so a start still in flight is never noted; an unmount leaves it.
+    let current = null;
+    const stop = () => {
+        if (current !== null)
+            current.abort.abort();
+        current = null;
+    };
+    const replace = () => {
+        if (current !== null)
+            current.note = false;
+        stop();
+    };
+    const forget = () => {
+        replace();
+        if (name !== null)
+            keep(name, null);
+    };
+    const reset = () => {
+        forget();
+        onStatus(IDLE);
+    };
+    /** Follow a run from `begin`, which starts it (no `id` yet) or reads the run `id` once, to its end. */
+    const follow = (run) => {
+        const mine = { abort: new AbortController(), note: true };
+        current = mine;
+        const { startedAt } = run;
+        let id = run.id;
+        let input = null;
+        let pollError = null;
+        const report = (status) => {
+            if (current === mine)
+                onStatus(status);
+        };
+        const pending = () => report({ state: "pending", id, input, elapsedMs: Date.now() - startedAt, pollError });
+        const onPoll = (read, error) => {
+            if (read !== null)
+                input = read.input;
+            pollError = error;
+            pending();
+        };
+        pending();
+        const ticker = setInterval(pending, ELAPSED_TICK_MS);
+        run
+            .begin(mine.abort.signal, onPoll)
+            .then(async (started) => {
+            if (!mine.note)
+                throw mine.abort.signal.reason;
+            id = started.id;
+            input = started.input;
+            if (name !== null)
+                keep(name, { id: started.id, startedAt });
+            pending();
+            return awaitInvocation(started, mine.abort.signal, onPoll);
+        })
+            .then((done) => report({ state: "succeeded", id: done.id, input: done.input, result: done.result, elapsedMs: Date.now() - startedAt }), (error) => {
+            // A remembered run the platform doesn't have for this person (someone else's, in a shared browser) is let go of.
+            if (name !== null && current === mine && error instanceof InvocationError && error.code === "not_found") {
+                reset();
+                return;
+            }
+            report({
+                state: "failed",
+                id,
+                input,
+                error: error instanceof InvocationError ? error : new InvocationError(0, "unexpected", String(error)),
+                elapsedMs: Date.now() - startedAt
+            });
+        })
+            .finally(() => clearInterval(ticker));
+    };
+    // One unheld read first, so a picked-up run shows its input at once. The note
+    // is written before that read, so a reload as soon as the id shows finds it.
+    const pickUp = (id, startedAt) => {
+        replace();
+        if (name !== null)
+            keep(name, { id, startedAt });
+        follow({ begin: (signal, onPoll) => readAnswered(id, 0, signal, onPoll), id, startedAt });
+    };
+    return {
+        run: (input) => {
+            forget();
+            follow({ begin: () => startInvocation(key, input), id: null, startedAt: Date.now() });
+        },
+        // `elapsedMs` counts from here, not from when the run started.
+        resume: (id) => pickUp(id, Date.now()),
+        /** With `remember`: follow the run this browser noted. */
+        restore: () => {
+            if (name === null)
+                return;
+            const noted = recall(name);
+            if (noted !== null)
+                pickUp(noted.id, noted.startedAt);
+        },
+        reset,
+        dispose: stop
+    };
+}
+function useInvocationOf(key, remember) {
+    const [status, setStatus] = useState(IDLE);
+    const controller = useMemo(() => createInvocationController(key, setStatus, { remember }), [key, remember]);
+    useEffect(() => {
+        // Another key or `remember` is another button: its own run, or none.
+        setStatus(IDLE);
+        controller.restore();
+        return controller.dispose;
+    }, [controller]);
+    return { status, run: controller.run, resume: controller.resume, reset: controller.reset };
+}

package/dist/invoke/paths.d.ts

@@ -0,0 +1,2 @@
+/** Where an app mounts its invoke routes, and where `invoke()` calls them. */
+export declare const INVOKE_BASE_PATH = "/api/mii/invoke";

package/dist/invoke/paths.js

@@ -0,0 +1,2 @@
+/** Where an app mounts its invoke routes, and where `invoke()` calls them. */
+export const INVOKE_BASE_PATH = "/api/mii/invoke";

package/dist/invoke/server.d.ts

@@ -0,0 +1,45 @@
+import { type ChatAuth } from "../chat/server.js";
+import type { ContractInput, ContractOutput, Contracts } from "./contracts.js";
+import { InvocationError } from "./error.js";
+export { InvocationError };
+export type { Contract, Contracts, Invocation } from "./contracts.js";
+export type MiiInvokeHandlerOptions = {
+    /** Where to report failures that are ours. Defaults to console.error. */
+    readonly reportError?: (error: unknown, context: Record<string, string>) => void;
+};
+export declare function defineContracts<const C extends Contracts>(contracts: C): C;
+export type StartInvocation<C extends Contracts, K extends keyof C & string> = {
+    /** The request the server function is answering (`getRequest()`): its cookie is the person, its origin is checked. */
+    readonly request: Request;
+    readonly key: K;
+    readonly input: ContractInput<C, K>;
+    readonly signal?: AbortSignal | null;
+};
+export type MiiInvoke<C extends Contracts> = {
+    /** The invoke routes, mounted under INVOKE_BASE_PATH. */
+    readonly handler: (request: Request) => Promise<Response>;
+    /**
+     * Start a contract from a POST server function, as the person whose request
+     * it is answering, and return the run's id without waiting for it: for work
+     * that must be recorded with its run (a job row that names it). A page
+     * follows it with `resume(id)`. Refusals reject with InvocationError, with
+     * the codes a button's press gets.
+     */
+    start<K extends keyof C & string>(start: StartInvocation<C, K>): Promise<{
+        readonly id: string;
+    }>;
+    /**
+     * A finished run's result, read from a server function as the person whose
+     * request it is answering, and parsed by this app's output schema for `key`.
+     * One read, no waiting: a run still going rejects with code `pending`, one
+     * the agents failed with `failed`, one of another contract with `not_found`;
+     * refusals reject with InvocationError, with the codes a press gets.
+     */
+    result<K extends keyof C & string>(key: K, id: string, request: Request): Promise<ContractOutput<C, K>>;
+};
+/**
+ * The app's contracts, served: the invoke routes and the server's own start.
+ * Every output is converted to JSON Schema here, once, so one with no JSON
+ * Schema form stops the server starting, not someone's press of the button.
+ */
+export declare function createMiiInvoke<C extends Contracts>(auth: ChatAuth, contracts: C, { reportError }?: MiiInvokeHandlerOptions): MiiInvoke<C>;

package/dist/invoke/server.js

@@ -0,0 +1,259 @@
+// The browser never names a contract id or a schema: it sends a local key and
+// the input, and this server attaches the rest from the app's own registry.
+import { z } from "zod/v4";
+import { miiAuthConfig } from "../auth/config.js";
+import { isSameOrigin, readCookie } from "../chat/server.js";
+import { errorBody } from "../request-error.js";
+import { isUuid } from "../uuid.js";
+import { failedRun, InvocationError } from "./error.js";
+import { INVOKE_BASE_PATH } from "./paths.js";
+export { InvocationError };
+function routeOf(request) {
+    const { pathname } = new URL(request.url);
+    if (!pathname.startsWith(INVOKE_BASE_PATH))
+        return null;
+    const path = pathname.slice(INVOKE_BASE_PATH.length);
+    if (request.method === "POST" && path === "/invocations")
+        return { kind: "start" };
+    const read = request.method === "GET" ? /^\/invocations\/([^/]+)$/.exec(path) : null;
+    if (read === null)
+        return null;
+    const [, id = ""] = read;
+    return { kind: "read", id };
+}
+const invokeBody = z.object({ key: z.string(), input: z.unknown() });
+const plazaInvocation = z.object({
+    id: z.string(),
+    contractId: z.string(),
+    state: z.enum(["pending", "succeeded", "failed"]),
+    input: z.record(z.string(), z.unknown()),
+    result: z.record(z.string(), z.unknown()).nullable(),
+    lastError: z.string().nullable(),
+    createdAt: z.string(),
+    finishedAt: z.string().nullable()
+});
+// A poll finds its contract by the id the platform pinned, so an id names one key.
+export function defineContracts(contracts) {
+    const keys = new Map();
+    for (const [key, contract] of Object.entries(contracts)) {
+        const other = keys.get(contract.id);
+        // eslint-disable-next-line no-restricted-syntax -- an id not seen yet has no key; Map.get says so with undefined
+        if (other !== undefined) {
+            throw new Error(`Contracts "${other}" and "${key}" share the id ${contract.id}; each key needs its own contract.`);
+        }
+        keys.set(contract.id, key);
+    }
+    return contracts;
+}
+/** A contract with its output as the JSON Schema the platform validates an agent's result against. */
+function declare(key, contract) {
+    try {
+        return { ...contract, outputSchema: z.toJSONSchema(contract.output, { io: "input" }) };
+    }
+    catch (error) {
+        throw new Error(`Contract "${key}": ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+    }
+}
+/** What the platform is asked to start: the registry's contract id and schema, and input the app's Zod accepts. */
+function startBody(contract, key, rawInput) {
+    // eslint-disable-next-line no-restricted-syntax -- a key the app does not declare has no contract; Map.get says so with undefined
+    if (contract === undefined) {
+        throw new InvocationError(404, "unknown_contract", `This app declares no contract "${key}".`);
+    }
+    const input = contract.input.safeParse(rawInput);
+    if (!input.success) {
+        throw new InvocationError(400, "invalid_input", `Invalid input for "${key}":\n${z.prettifyError(input.error)}`);
+    }
+    return JSON.stringify({ contractId: contract.id, input: input.data, outputSchema: contract.outputSchema });
+}
+/**
+ * The person behind a request to this app: the session cookie, from one of
+ * this app's own pages. Every org app shares one site with every other
+ * (*.<domain>), so a page on another org's app can send this app's cookie along.
+ */
+async function signedIn(auth, request) {
+    if (!isSameOrigin(request, new URL(request.url))) {
+        throw new InvocationError(403, "cross_site", "Contracts can only be invoked from this app's own pages.");
+    }
+    const token = readCookie(request.headers.get("cookie"), auth.SESSION_COOKIE);
+    if (token === null)
+        throw new InvocationError(401, "not_signed_in", "Sign in to use this.");
+    const session = await auth.resolveSessionWithPlaza(token);
+    if (session === null)
+        throw new InvocationError(401, "sign_in_again", "Sign out and back in to use it here.");
+    return { token, plazaToken: session.plazaToken };
+}
+/** One call to the platform's contract API as the person; a refused token ends their session. Rejects only when the platform can't be reached. */
+async function callPlaza(auth, person, call) {
+    const answer = await fetch(call.target, {
+        method: call.method,
+        headers: {
+            Authorization: `Bearer ${person.plazaToken}`,
+            ...(call.body === null ? {} : { "Content-Type": "application/json" })
+        },
+        body: call.body,
+        cache: "no-store",
+        redirect: "manual",
+        signal: call.signal
+    });
+    if (answer.status === 401 || answer.status === 403) {
+        await auth.revokeSession(person.token, answer.status === 403 ? "not_a_member" : "token_rejected");
+    }
+    return answer;
+}
+const plazaTarget = (path) => new URL(`${miiAuthConfig().plazaUrl}/api/app-contracts/v1${path}`);
+/** One call to the platform as the person, read as JSON. A refusal, or no answer, rejects with InvocationError. */
+async function askPlaza(auth, person, call) {
+    let answer;
+    try {
+        answer = await callPlaza(auth, person, call);
+    }
+    catch (error) {
+        if (call.signal !== null && call.signal.aborted)
+            throw error;
+        throw new InvocationError(0, "unavailable", `Couldn't reach the platform: ${String(error)}`);
+    }
+    const text = await answer.text();
+    if (!answer.ok) {
+        const refusal = errorBody(text, `The platform answered ${answer.status}.`);
+        throw new InvocationError(answer.status, refusal.code, refusal.detail);
+    }
+    return JSON.parse(text);
+}
+// A result the platform accepted can still miss what this app expects: the schema
+// the platform checked is the JSON Schema form of `output`, which cannot carry a
+// refinement or a transform. The app's own Zod has the last word.
+function resultMismatch(id, error, reportError) {
+    const problem = `The result of invocation ${id} does not match this app's output schema:\n${z.prettifyError(error)}`;
+    reportError(new Error(problem), { where: "mii-invoke", step: "result" });
+    return new InvocationError(422, "result_mismatch", problem);
+}
+/**
+ * The app's contracts, served: the invoke routes and the server's own start.
+ * Every output is converted to JSON Schema here, once, so one with no JSON
+ * Schema form stops the server starting, not someone's press of the button.
+ */
+export function createMiiInvoke(auth, contracts, { reportError = (error, context) => console.error("mii-invoke error", context, error) } = {}) {
+    const declared = new Map(Object.entries(contracts).map(([key, contract]) => [key, declare(key, contract)]));
+    const handler = async (request) => {
+        const route = routeOf(request);
+        if (route === null) {
+            return refuse(404, "not_found", "There's nothing to invoke here.");
+        }
+        if (route.kind === "read" && !isUuid(route.id)) {
+            return refuse(404, "not_found", "Invocation not found.");
+        }
+        let person;
+        let body = null;
+        try {
+            person = await signedIn(auth, request);
+            if (route.kind === "start")
+                body = await readInvoke(request, declared);
+        }
+        catch (error) {
+            if (!(error instanceof InvocationError))
+                throw error;
+            return refuse(error.status, error.code, error.message);
+        }
+        const target = plazaTarget(route.kind === "start" ? "/invocations" : `/invocations/${route.id}`);
+        // How long the platform may hold a read of a pending invocation. This app's own
+        // function limit has to outlast it (see the README).
+        const wait = new URL(request.url).searchParams.get("wait");
+        if (route.kind === "read" && wait !== null)
+            target.searchParams.set("wait", wait);
+        let answer;
+        try {
+            // The browser giving up ends the platform's hold too.
+            answer = await callPlaza(auth, person, { method: request.method, target, body, signal: request.signal });
+        }
+        catch (error) {
+            if (!request.signal.aborted)
+                reportError(error, { where: "mii-invoke", step: "forward" });
+            return refuse(502, "unavailable", "Couldn't reach the platform. Try again in a moment.");
+        }
+        if (!answer.ok) {
+            if (answer.status >= 500) {
+                reportError(new Error(`Platform answered ${answer.status}: ${(await answer.clone().text()).slice(0, 300)}`), {
+                    where: "mii-invoke",
+                    step: "plaza"
+                });
+            }
+            // A refusal passes through as chat's does: the platform's body and content type.
+            const headers = new Headers({ "Cache-Control": "no-store" });
+            const contentType = answer.headers.get("content-type");
+            if (contentType !== null)
+                headers.set("Content-Type", contentType);
+            return new Response(answer.body, { status: answer.status, headers });
+        }
+        // Unlike chat, an ok body is read rather than streamed through: a succeeded
+        // result is parsed by this app's own schema before the browser sees it.
+        return respond(answer.status, plazaInvocation.parse(await answer.json()), declared, reportError);
+    };
+    const start = async ({ request, key, input, signal = null }) => {
+        const person = await signedIn(auth, request);
+        const body = startBody(declared.get(key), key, input);
+        const answer = await askPlaza(auth, person, { method: "POST", target: plazaTarget("/invocations"), body, signal });
+        return { id: plazaInvocation.parse(answer).id };
+    };
+    const result = async (key, id, request) => {
+        const person = await signedIn(auth, request);
+        const contract = contracts[key];
+        if (!isUuid(id))
+            throw new InvocationError(404, "not_found", "Invocation not found.");
+        const invocation = plazaInvocation.parse(await askPlaza(auth, person, { method: "GET", target: plazaTarget(`/invocations/${id}`), body: null, signal: null }));
+        if (invocation.contractId !== contract.id) {
+            throw new InvocationError(404, "not_found", `Invocation ${id} is not a run of "${key}".`);
+        }
+        if (invocation.state === "pending")
+            throw new InvocationError(409, "pending", `Invocation ${id} hasn't finished yet.`);
+        if (invocation.state === "failed")
+            throw failedRun(invocation.lastError);
+        const output = contract.output;
+        const parsed = output.safeParse(invocation.result);
+        if (!parsed.success)
+            throw resultMismatch(id, parsed.error, reportError);
+        return parsed.data;
+    };
+    return { handler, start, result };
+}
+async function readInvoke(request, declared) {
+    let sent;
+    try {
+        sent = await request.json();
+    }
+    catch {
+        throw new InvocationError(400, "invalid_input", "The request body is not JSON.");
+    }
+    const parsed = invokeBody.safeParse(sent);
+    if (!parsed.success) {
+        throw new InvocationError(400, "invalid_input", 'The request body must be {"key": …, "input": …}.');
+    }
+    return startBody(declared.get(parsed.data.key), parsed.data.key, parsed.data.input);
+}
+function respond(status, invocation, declared, reportError) {
+    const { id, input, lastError, createdAt, finishedAt } = invocation;
+    const send = (answer) => new Response(JSON.stringify(answer), {
+        status,
+        headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
+    });
+    if (invocation.state !== "succeeded") {
+        return send({ id, state: invocation.state, input, result: null, lastError, createdAt, finishedAt });
+    }
+    const [contract = null] = [...declared.values()].filter((candidate) => candidate.id === invocation.contractId);
+    if (contract === null) {
+        return refuse(404, "unknown_contract", `This app declares no contract with the id ${invocation.contractId}.`);
+    }
+    const parsed = contract.output.safeParse(invocation.result);
+    if (!parsed.success) {
+        const mismatch = resultMismatch(id, parsed.error, reportError);
+        return refuse(mismatch.status, mismatch.code, mismatch.message);
+    }
+    return send({ id, state: "succeeded", input, result: parsed.data, lastError, createdAt, finishedAt });
+}
+// The platform's error shape: the sentence a person reads, and the reason as a code.
+function refuse(status, code, error) {
+    return new Response(JSON.stringify({ error, code }), {
+        status,
+        headers: { "Content-Type": "application/json", "Cache-Control": "no-store" }
+    });
+}