@trylight/app 0.1.8 → 0.2.0

package/dist/client.js

@@ -5,26 +5,128 @@
 // `app.table(companies)` reads and writes that table's rows through the
 // entities route; its hooks keep TanStack Query's cache in step, so an edit
 // shows at once and never snaps back. `app.contracts` asks the org's agents.
-import { keepPreviousData, skipToken, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { createInvoker } from "@shubh90/app-runtime/invoke";
-import { getTableName } from "drizzle-orm";
+import { hashKey, keepPreviousData, skipToken, useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useMemo, useState } from "react";
+import { createInvoker } from "./invoke/index.js";
+import { getTableColumns, getTableName } from "drizzle-orm";
 import { z } from "zod/v4";
-import { ENTITIES_PATH, EntityError } from "./entities.js";
+import { ENTITIES_PATH, EntityError, LIST_LIMIT } from "./entities.js";
 export { EntityError, LIST_LIMIT } from "./entities.js";
 export { siteOf } from "./schema.js";
 export { imageSrc } from "./images.js";
-export { InvocationError } from "@shubh90/app-runtime/invoke";
+export { InvocationError } from "./invoke/index.js";
 export function createApp() {
     return { table: tableClient, contracts: createInvoker() };
 }
 /** Every list's rows before its first answer: one array, so they never change identity while pending. */
 const NO_ROWS = [];
+/** Rows one page of `useInfiniteList` asks for; scrolling near the end asks for the next. */
+export const PAGE_SIZE = 100;
+/** How long after a list settles its sibling views' first pages are fetched: the page's own work goes first. */
+const PREFETCH_AFTER_MS = 300;
+/** A prefetched first page counts as fresh this long, so settling again doesn't fetch it again. */
+const PREFETCH_FRESH_MS = 30_000;
+/** A cached row as any query under a table's key holds it: an object with the row's id. */
+const cachedRow = z.looseObject({ id: z.string() });
+/** A cached useInfiniteList: its pages of rows. */
+const cachedPages = z.looseObject({ pages: z.array(z.array(z.unknown())) });
+const cachedSources = z.record(z.string(), z.unknown());
+/** The rows a cached query holds: a list's, each of a useInfiniteList's pages, or useGet's one row. */
+function rowsOf(data) {
+    if (Array.isArray(data))
+        return [data];
+    const paged = cachedPages.safeParse(data);
+    if (paged.success)
+        return paged.data.pages;
+    return cachedRow.safeParse(data).success ? [[data]] : [];
+}
+/** The same query with its rows replaced, page by page, in the shape it came in. */
+function withRows(data, rows) {
+    if (Array.isArray(data))
+        return rows[0];
+    const paged = cachedPages.safeParse(data);
+    if (paged.success)
+        return { ...paged.data, pages: rows };
+    // One row (useGet): kept as it was when the change takes it out (an open panel's row stays while it closes).
+    const [[row = data] = []] = rows;
+    return row;
+}
+const isRow = (item, id) => {
+    const row = cachedRow.safeParse(item);
+    return row.success && row.data.id === id;
+};
+/**
+ * Every query under a table's key with one row changed (null takes it out):
+ * useList's, useInfiniteList's, useGet's, and a page's own server-function
+ * list keyed under the table, so a write shows everywhere at once. Returns
+ * where the row was, so a write that fails puts back just that row, never
+ * another write's change made since. A query holding anything else is left alone.
+ */
+function changeRow(client, key, id, fields, change) {
+    const before = [];
+    for (const [queryKey, data] of client.getQueriesData({ queryKey: key })) {
+        const pages = rowsOf(data);
+        pages.forEach((rows, page) => {
+            const index = rows.findIndex((item) => isRow(item, id));
+            if (index >= 0)
+                before.push({ key: queryKey, page, index, row: rows[index], fields });
+        });
+        if (!pages.some((rows) => rows.some((item) => isRow(item, id))))
+            continue;
+        client.setQueryData(queryKey, withRows(data, pages.map((rows) => rows.flatMap((item) => {
+            const row = cachedRow.safeParse(item);
+            if (!row.success || row.data.id !== id)
+                return [item];
+            const next = change(row.data);
+            return next === null ? [] : [next];
+        }))));
+    }
+    return before;
+}
+/** The queries under a table's key that hold one row: the only ones a write to it touches (or cancels). */
+function holding(client, key, id) {
+    return client
+        .getQueriesData({ queryKey: key })
+        .filter(([, data]) => rowsOf(data).some((rows) => rows.some((item) => isRow(item, id))))
+        .map(([queryKey]) => queryKey);
+}
+/** A failed write taken back: its fields of the row as they were (a delete: the row, where it was); everything else as it is now. */
+function putBack(client, id, before) {
+    for (const { key, page, index, row, fields } of before) {
+        client.setQueryData(key, (data) => {
+            const pages = rowsOf(data);
+            const rows = pages[page];
+            if (rows === undefined)
+                return data;
+            const was = cachedRow.safeParse(row);
+            const there = rows.some((item) => isRow(item, id));
+            // An update's row gone meanwhile (deleted) stays gone; only a delete puts its row back.
+            if (!there && fields !== null)
+                return data;
+            const back = there
+                ? rows.map((item) => {
+                    if (!isRow(item, id))
+                        return item;
+                    const now = cachedRow.safeParse(item);
+                    if (fields === null || !now.success || !was.success)
+                        return row;
+                    // Each field as it was, and gone if it wasn't there (a slim list the patch added a column to).
+                    const kept = Object.entries(now.data).filter(([field]) => !fields.includes(field));
+                    const restored = fields.filter((field) => Object.hasOwn(was.data, field)).map((field) => [field, was.data[field]]);
+                    return Object.fromEntries([...kept, ...restored]);
+                })
+                : [...rows.slice(0, index), row, ...rows.slice(index)];
+            return withRows(data, pages.map((each, at) => (at === page ? back : each)));
+        });
+    }
+}
 /** One entity table's rows: plain calls, and TanStack Query hooks over them. */
 function tableClient(entity) {
     const base = `${ENTITIES_PATH}/${getTableName(entity)}`;
     const keys = {
         all: ["light", base],
         list: (options) => ["light", base, "list", options],
+        pages: (options) => ["light", base, "pages", options],
         get: (id) => ["light", base, "get", id],
         write: ["light", base, "write"]
     };
@@ -35,18 +137,41 @@ function tableClient(entity) {
     const remove = async (id) => {
         await call("DELETE", `${base}/${id}`);
     };
+    const columns = new Set(Object.keys(getTableColumns(entity)));
+    const isColumn = (column) => columns.has(column);
+    /** A header's sort as the server takes it. DataTable sorts only columns `canSort` allows, so any other is a bug. */
+    const sortBy = ({ column, desc }) => {
+        if (!isColumn(column))
+            throw new Error(`${getTableName(entity)} has no column ${column} to sort by.`);
+        return desc ? `-${column}` : column;
+    };
+    const pagesQuery = (options) => {
+        const { pageSize = PAGE_SIZE, ...rest } = options;
+        return {
+            queryKey: keys.pages(options),
+            queryFn: ({ pageParam }) => list({ ...rest, limit: pageSize, offset: pageParam }),
+            initialPageParam: 0,
+            // A full page may have more after it; a short one is the end (or one an optimistic delete shortened, until the write's refetch).
+            getNextPageParam: (last, all) => last.length < pageSize ? undefined : all.reduce((sum, page) => sum + page.length, 0)
+        };
+    };
     /**
      * After a write, refetch the table once the last write in flight settles.
-     * Returning the refetch keeps the mutation pending until it lands, so an
-     * edit never flickers back to its old value; a failed write is corrected
-     * by the same refetch.
+     * A saved write stays pending until the refetch lands, so an edit never
+     * flickers back to its old value. A failed one is already taken back, so
+     * its error reaches the page (the toast saying so) without waiting.
      */
     const useSettle = () => {
         const client = useQueryClient();
-        return async () => {
+        const refetch = async () => {
             if (client.isMutating({ mutationKey: keys.write }) === 1)
                 await client.invalidateQueries({ queryKey: keys.all });
         };
+        return (_data, error) => {
+            if (error === null)
+                return refetch();
+            void refetch();
+        };
     };
     return {
         /**
@@ -69,9 +194,77 @@ function tableClient(entity) {
         useList: (options = {}) => {
             const query = useQuery({ queryKey: keys.list(options), queryFn: () => list(options) });
             const { data: rows = NO_ROWS } = query;
+            const view = {
+                rows,
+                isPending: query.isPending,
+                loadError: query.isLoadingError ? query.error : null,
+                refetch: query.refetch,
+                // Stopped at the server's limit (not one the page chose): DataTable says it shows only the first ones, never drops the rest silently.
+                hasMore: options.limit === undefined && rows.length >= LIST_LIMIT,
+                loadMore: null,
+                isLoadingMore: false,
+                moreFailed: false,
+                isSwitching: false,
+                serverSort: null
+            };
             // A spread reads every field, so the page re-renders on any of them (isFetching
             // too); a list page shows those states anyway, and it keeps the result plain.
-            return { ...query, rows };
+            return { ...query, ...view };
+        },
+        /**
+         * A list of any size, a page at a time: `loadMore` (DataTable calls it as
+         * the end scrolls into view) fetches the next. New options (a tab, a
+         * filter, a search) keep the last rows on screen with `isSwitching` until
+         * theirs land, so a click never blanks the table. `prefetch` names the
+         * sibling views (the other tabs): their first pages load once this one
+         * settles, so switching to one is instant. Sorting is the server's, over
+         * every row; `sort` is where it starts.
+         *
+         *   const list = app.table(leads).useInfiniteList({ where: { status: tab } }, { prefetch: TABS.map((t) => ({ where: { status: t } })) });
+         *   <DataTable list={list} … />
+         */
+        useInfiniteList: (options = {}, { prefetch = [] } = {}) => {
+            const client = useQueryClient();
+            const [sorting, setSorting] = useState(null);
+            const asked = sorting === null ? options : { ...options, sort: sortBy(sorting) };
+            const query = useInfiniteQuery({ ...pagesQuery(asked), placeholderData: keepPreviousData });
+            // Pages are by offset: a row added above the fold mid-scroll shifts the next page by one, so a row can come twice. The first stays.
+            const rows = useMemo(() => (query.data === undefined ? NO_ROWS : firstOfEach(query.data.pages.flat(), (row) => row.id)), [query.data]);
+            const settled = query.isSuccess && !query.isPlaceholderData;
+            // The sibling views as this one is sorted, less this one; keyed by their hash, so a page passing a new array each render changes nothing.
+            const siblings = prefetch.map((sibling) => (asked.sort === undefined ? sibling : { ...sibling, sort: asked.sort })).filter((sibling) => hashKey([sibling]) !== hashKey([asked]));
+            const siblingsKey = hashKey(siblings);
+            useEffect(() => {
+                if (!settled)
+                    return;
+                const later = setTimeout(() => {
+                    for (const sibling of siblings)
+                        void client.prefetchInfiniteQuery({ ...pagesQuery(sibling), staleTime: PREFETCH_FRESH_MS });
+                }, PREFETCH_AFTER_MS);
+                return () => clearTimeout(later);
+                // `siblingsKey` stands for `siblings`, by value.
+            }, [settled, siblingsKey, client]);
+            const view = {
+                rows,
+                isPending: query.isPending,
+                loadError: query.isLoadingError ? query.error : null,
+                refetch: query.refetch,
+                hasMore: query.hasNextPage,
+                loadMore: () => {
+                    if (query.hasNextPage && !query.isFetchingNextPage && !query.isPlaceholderData)
+                        void query.fetchNextPage();
+                },
+                isLoadingMore: query.isFetchingNextPage,
+                moreFailed: query.isFetchNextPageError,
+                isSwitching: query.isPlaceholderData,
+                serverSort: {
+                    // A header's choice, or the page's own `sort` until one is clicked.
+                    sorting: sorting === null ? sortingOf(options.sort) : sorting,
+                    setSorting,
+                    canSort: isColumn
+                }
+            };
+            return { ...query, ...view };
         },
         /** One row; `null` waits (nothing open yet). */
         useGet: (id) => useQuery({
@@ -88,7 +281,11 @@ function tableClient(entity) {
                 onSettled: settle
             });
         },
-        /** Shows the patch at once in every cached list and row. */
+        /**
+         * Shows the patch at once in every cached list, page and row under the
+         * table's key; a save that fails takes it back at once (and the mutation's
+         * error says why), then the table refetches.
+         */
         useUpdate: () => {
             const client = useQueryClient();
             const settle = useSettle();
@@ -96,22 +293,26 @@ function tableClient(entity) {
                 mutationKey: keys.write,
                 mutationFn: ({ id, patch }) => update(id, patch),
                 onMutate: async ({ id, patch }) => {
-                    await client.cancelQueries({ queryKey: keys.all });
+                    // Only the queries holding this row: a tab switching meanwhile keeps loading.
+                    await Promise.all(holding(client, keys.all, id).map((queryKey) => client.cancelQueries({ queryKey, exact: true })));
                     // A value set here loses its old source until the server answers with who set it; sources sent merge in.
-                    const patched = (row) => row.id === id
-                        ? {
-                            ...row,
-                            ...patch,
-                            field_sources: Object.assign(Object.fromEntries(Object.entries(row.field_sources).filter(([column]) => !(column in patch))), patch.field_sources)
-                        }
-                        : row;
-                    client.setQueriesData({ queryKey: [...keys.all, "list"] }, (rows) => rows && rows.map(patched));
-                    client.setQueryData(keys.get(id), (row) => row && patched(row));
+                    // A row cached without its sources (a page's slim list) just takes the patch.
+                    const patched = (row) => {
+                        const sources = cachedSources.safeParse(row.field_sources);
+                        if (!sources.success)
+                            return { ...row, ...patch };
+                        const kept = Object.fromEntries(Object.entries(sources.data).filter(([column]) => !(column in patch)));
+                        return { ...row, ...patch, field_sources: Object.assign(kept, patch.field_sources) };
+                    };
+                    // Its sources change with its values (an edited value loses its old source), so they go back with them.
+                    return changeRow(client, keys.all, id, [...Object.keys(patch), "field_sources"], patched);
                 },
+                // No context when onMutate itself threw: nothing was changed to put back.
+                onError: (_error, { id }, before = []) => putBack(client, id, before),
                 onSettled: settle
             });
         },
-        /** Takes the row out of every cached list at once. */
+        /** Takes the row out of every cached list at once; a delete that fails puts it back. */
         useDelete: () => {
             const client = useQueryClient();
             const settle = useSettle();
@@ -119,14 +320,33 @@ function tableClient(entity) {
                 mutationKey: keys.write,
                 mutationFn: remove,
                 onMutate: async (id) => {
-                    await client.cancelQueries({ queryKey: keys.all });
-                    client.setQueriesData({ queryKey: [...keys.all, "list"] }, (rows) => rows && rows.filter((row) => row.id !== id));
+                    await Promise.all(holding(client, keys.all, id).map((queryKey) => client.cancelQueries({ queryKey, exact: true })));
+                    return changeRow(client, keys.all, id, null, () => null);
                 },
+                onError: (_error, id, before = []) => putBack(client, id, before),
                 onSettled: settle
             });
         }
     };
 }
+/** A page's `sort` ("name", "-created_at") as a header shows it. */
+function sortingOf(sort) {
+    if (sort === undefined)
+        return null;
+    return sort.startsWith("-") ? { column: sort.slice(1), desc: true } : { column: sort, desc: false };
+}
+/** Each row once, where it first came. */
+function firstOfEach(rows, idOf) {
+    const seen = new Set();
+    const once = [];
+    for (const row of rows) {
+        if (seen.has(idOf(row)))
+            continue;
+        seen.add(idOf(row));
+        once.push(row);
+    }
+    return once;
+}
 function json(body) {
     return { headers: { "Content-Type": "application/json" }, body: JSON.stringify(body) };
 }

package/dist/db/cli.js

@@ -1,6 +1,5 @@
 // `light-db sync`, `light-db migrate`, `light-db check`: the
-// app's `pnpm db:*` scripts; `light-db baseline` moves an older app's tables
-// under db/schema, once. Run from the app's root.
+// app's `pnpm db:*` scripts. Run from the app's root.
 import { existsSync } from "node:fs";
 import { request } from "node:http";
 import { userInfo } from "node:os";
@@ -11,7 +10,6 @@ import { migrate } from "drizzle-orm/postgres-js/migrator";
 import postgres from "postgres";
 import { z } from "zod/v4";
 import { archiveNotices, entityTables, prepareAudit, trackTables } from "./audit.js";
-import { BaselineRefused, baseline as writeBaseline } from "./baseline.js";
 import { MIGRATIONS_DIR, SCHEMA_ENTRY, plan, unwriteMigration, writeMigration } from "./migrations.js";
 import { env } from "../server/env.js";
 /**
@@ -127,42 +125,7 @@ async function migrateThroughPlatform() {
     process.stdout.write(reply.output);
     return reply.code;
 }
-/** Writes db/schema and a first migration from the live tables of an app made before db/schema. */
-async function baseline() {
-    const { databaseUrl } = env();
-    if (databaseUrl === undefined)
-        throw new Error("DATABASE_URL is not set: baseline reads the app's database.");
-    let written;
-    try {
-        written = await writeBaseline(root, databaseUrl);
-    }
-    catch (error) {
-        if (!(error instanceof BaselineRefused))
-            throw error;
-        console.error(error.message);
-        return 1;
-    }
-    console.log(`Wrote db/schema from the database, and ${MIGRATIONS_DIR}/0000_baseline.sql recording its tables as they are:`);
-    for (const table of written.tables) {
-        const lacks = table.lacks.length > 0 ? ` (lacks ${table.lacks.join(", ")}; the first sync adds them)` : "";
-        console.log(`  db/schema/${table.name}.ts${lacks}`);
-    }
-    console.log('Every entity is { read: "door", write: "door" }; make one `write: "agents"` if only agents fill it.');
-    if (written.plain.length > 0) {
-        console.log("Plain tables (no sync changes them; app.table can't serve them):");
-        for (const table of written.plain)
-            console.log(`  db/schema/${table.name}.ts: ${table.why}`);
-    }
-    if (written.skipped.length > 0)
-        console.log(`Skipped, the platform's own tables: ${written.skipped.join(", ")}.`);
-    if (written.leftOut.length > 0)
-        console.log(`Left in the database, not in db/schema: ${written.leftOut.join(", ")}.`);
-    console.log(written.pending.length === 0
-        ? "`pnpm db:sync` has nothing to change."
-        : `\`pnpm db:sync\` will only add this; nothing already there changes:\n${written.pending.join("\n")}`);
-    return 0;
-}
 // Last, so every const above is initialized before a command reads it.
-const commands = { sync, migrate: applyMigrations, check, baseline };
-const usage = z.enum(["sync", "migrate", "check", "baseline"], { error: "Usage: light-db sync | migrate | check | baseline" });
+const commands = { sync, migrate: applyMigrations, check };
+const usage = z.enum(["sync", "migrate", "check"], { error: "Usage: light-db sync | migrate | check" });
 process.exit(await commands[usage.parse(command)]());

package/dist/db/migrations.d.ts

@@ -10,7 +10,7 @@ export type Plan = {
     snapshot: Snapshot;
 };
 /** The parts of a drizzle-kit snapshot a removal touches; the rest passes through. */
-export declare const snapshotSchema: z.ZodObject<{
+declare const snapshotSchema: z.ZodObject<{
     id: z.ZodString;
     tables: z.ZodRecord<z.ZodString, z.ZodObject<{
         columns: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -37,7 +37,6 @@ export type Snapshot = z.infer<typeof snapshotSchema>;
  * after the columns that used them have changed.
  */
 export declare function plan(root: string, schema: Record<string, unknown>): Promise<Plan>;
-export declare const EMPTY_SNAPSHOT: Snapshot;
 /**
  * Writes the plan as the next migration, in drizzle-kit's own layout (the
  * SQL, its snapshot, the journal entry), so drizzle's migrator applies it.
@@ -45,3 +44,4 @@ export declare const EMPTY_SNAPSHOT: Snapshot;
 export declare function writeMigration(root: string, planned: Plan, name?: string): string;
 /** Takes back the newest migration, one that didn't apply, so the schema's change is pending again. */
 export declare function unwriteMigration(root: string, tag: string): void;
+export {};

package/dist/db/migrations.js

@@ -12,7 +12,7 @@ export const SCHEMA_ENTRY = "db/schema/index.ts";
 export const MIGRATIONS_DIR = "db/migrations";
 const entries = z.record(z.string(), z.unknown());
 /** The parts of a drizzle-kit snapshot a removal touches; the rest passes through. */
-export const snapshotSchema = z.looseObject({
+const snapshotSchema = z.looseObject({
     id: z.string(),
     tables: z.record(z.string(), z.looseObject({
         columns: entries,
@@ -102,7 +102,7 @@ const journalSchema = z.object({
         breakpoints: z.boolean()
     }))
 });
-export const EMPTY_SNAPSHOT = {
+const EMPTY_SNAPSHOT = {
     version: "7",
     dialect: "postgresql",
     id: "00000000-0000-0000-0000-000000000000",

package/dist/entities.d.ts

@@ -1,6 +1,6 @@
 import type { Entity, PlatformColumn } from "./schema.js";
 export declare const ENTITIES_PATH = "/api/light/entities";
-/** The most rows one list returns; page past it with `offset`. */
+/** The most rows one list returns; page past it with `offset` (useInfiniteList does). */
 export declare const LIST_LIMIT = 1000;
 /** A value as JSON carries it: a Date column arrives as its ISO string. */
 type Wire<T> = {
@@ -19,6 +19,8 @@ export type Where<R> = {
 export type Sort<R> = (keyof R & string) | `-${keyof R & string}`;
 export type ListOptions<R> = {
     where?: Where<R>;
+    /** Rows with every one of these words in some text column of their own, case-insensitively: the server searches, so a paged list finds rows not loaded yet. */
+    search?: string;
     sort?: Sort<R>;
     /** At most LIST_LIMIT, which is also the default. */
     limit?: number;

package/dist/entities.js

@@ -1,5 +1,5 @@
 export const ENTITIES_PATH = "/api/light/entities";
-/** The most rows one list returns; page past it with `offset`. */
+/** The most rows one list returns; page past it with `offset` (useInfiniteList does). */
 export const LIST_LIMIT = 1000;
 /** A refused or failed entities call, with the route's own reason. */
 export class EntityError extends Error {

package/dist/invoke/contracts.d.ts

@@ -0,0 +1,28 @@
+import type { z } from "zod/v4";
+type ObjectSchema = z.ZodType<Record<string, unknown>, Record<string, unknown>>;
+export type Contract = {
+    /** The id `mii contract create` printed. */
+    readonly id: string;
+    readonly input: ObjectSchema;
+    readonly output: ObjectSchema;
+};
+export type Contracts = Readonly<Record<string, Contract>>;
+export type ContractInput<C extends Contracts, K extends keyof C> = z.input<C[K]["input"]>;
+export type ContractOutput<C extends Contracts, K extends keyof C> = z.output<C[K]["output"]>;
+export type InvocationState = "pending" | "succeeded" | "failed";
+/** What the app's invoke routes answer with; `Output` is a contract's, once the app's schema has parsed it. */
+export type Invocation<Output = Record<string, unknown>> = {
+    readonly id: string;
+    /** The input the run was started with: the JSON of the app's schema's parse at the start. */
+    readonly input: Record<string, unknown>;
+    readonly lastError: string | null;
+    readonly createdAt: string;
+    readonly finishedAt: string | null;
+} & ({
+    readonly state: "pending" | "failed";
+    readonly result: null;
+} | {
+    readonly state: "succeeded";
+    readonly result: Output;
+});
+export {};

package/dist/invoke/contracts.js

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

package/dist/invoke/error.d.ts

@@ -0,0 +1,11 @@
+import { RequestError } from "../request-error.js";
+/**
+ * Why an invocation did not produce a result. `code` is the server's
+ * (`not_signed_in`, `invalid_input`, `unknown_contract`, `result_mismatch`, …),
+ * or `failed` when the agents could not produce a result matching the schema.
+ * `status` is 0 when no HTTP refusal is behind it: `failed`, or no answer at all.
+ */
+export declare class InvocationError extends RequestError {
+}
+/** A run the agents closed without a result that matches its schema. */
+export declare function failedRun(lastError: string | null): InvocationError;

package/dist/invoke/error.js

@@ -0,0 +1,13 @@
+import { RequestError } from "../request-error.js";
+/**
+ * Why an invocation did not produce a result. `code` is the server's
+ * (`not_signed_in`, `invalid_input`, `unknown_contract`, `result_mismatch`, …),
+ * or `failed` when the agents could not produce a result matching the schema.
+ * `status` is 0 when no HTTP refusal is behind it: `failed`, or no answer at all.
+ */
+export class InvocationError extends RequestError {
+}
+/** A run the agents closed without a result that matches its schema. */
+export function failedRun(lastError) {
+    return new InvocationError(0, "failed", `The agents could not produce a valid result.${lastError === null ? "" : `\n${lastError}`}`);
+}

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;
+};