@agentorg/cli 0.0.4 → 0.0.6

package/dist/src/gateway.d.ts

@@ -1,6 +1,6 @@
 import { type IncomingMessage, type ServerResponse } from "node:http";
 import { Hub } from "@agentorg/hub";
-import { type FirstRun, type FirstRunOptions } from "./model.js";
+import { type Programs, type ProgramsOptions } from "./programs.js";
 /** A route another part of the app adds, such as the model Actor's sign-in callback (step 5). */
 export type Route = (request: IncomingMessage, response: ServerResponse, url: URL) => void;
 export interface AppOptions {
@@ -11,10 +11,9 @@ export interface AppOptions {
     /** Where the shell's static files are; `@agentorg/shell`'s build by default. */
     shell?: string;
     /**
-     * The first run, at each start after the person's store is bound: on by default; `false` leaves
-     * the home as it is.
+     * How the first run, at each start, logs and reaches ChatGPT: the app's own by default.
      */
-    firstRun?: FirstRunOptions | false;
+    firstRun?: Pick<ProgramsOptions, "fetch" | "log">;
 }
 export interface App {
     /** The gateway's origin, `http://127.0.0.1:<port>`. */
@@ -22,8 +21,8 @@ export interface App {
     /** Where external Actors reach the Hub. */
     readonly hubUrl: string;
     readonly hub: Hub;
-    /** This start's first run: what it found or made, once it's done; none when it was off. */
-    readonly firstRun?: Promise<FirstRun | undefined>;
+    /** This start's first run: the programs it started, once it's done. */
+    readonly firstRun: Promise<Programs | undefined>;
     /** A fresh one-time sign-in address, `<url>/signin#<code>`. */
     signInUrl(): string;
     /** Serve `path` with `route`, for another part of the app. */
@@ -41,6 +40,6 @@ export interface App {
  * The app: a Hub in this process, and the person's gateway, its single running instance. The
  * gateway holds the person's one channel to the Hub. Browser tabs and the CLI are the person's UIs,
  * not channels: they reach the gateway at `/api`, and their calls run through the person's slots,
- * or as a view's Actor for a view's. The gateway exports `layout@1`, kept in the person's store.
+ * and the person's notes are the app's own file.
  */
 export declare function startApp(options: AppOptions): Promise<App>;

package/dist/src/gateway.js

@@ -3,33 +3,30 @@ import { createServer } from "node:http";
 import { createRequire } from "node:module";
 import { dirname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { Hub, listen, PERSON, STORAGE } from "@agentorg/hub";
-import { accountLogin, appRules, hubActors, hubAudit, hubBindings, hubExports, hubGrants, hubPackages, installer, kv, layout, } from "@agentorg/interfaces";
+import { Hub, listen, PERSON } from "@agentorg/hub";
+import { accountLogin, agents, connections, hubActors, hubAudit, hubBindings, hubExports, hubGrants, skills, } from "@agentorg/interfaces";
 import { Refused } from "@agentorg/sdk";
 import { connect } from "@agentorg/sdk/client";
 import { WebSocketServer } from "ws";
 import { serveSocket } from "./api.js";
-import { serveFrame } from "./frames.js";
-import { Layout } from "./layout.js";
-import { firstRun, oauthRoute } from "./model.js";
-import { Rules } from "./rules.js";
+import { Notes } from "./notes.js";
+import { oauthRoute } from "./oauth.js";
+import { closePackageActors, startPrograms, } from "./programs.js";
 import { SignIn } from "./signin.js";
-import { MAX_TRANSFER, packageArchive, pinnedHashes, readSystem, withTemporaryFile, writeSystem, } from "./transfer.js";
 /**
- * The person's slots the gateway declares: every `hub.*` it holds, its own store, and the two the
- * first run binds (either may be unbound): `installer`, and `login`, the model's account sign-in.
+ * The person's slots the gateway declares: every `hub.*` it holds, and what the first run binds
+ * (any may be unbound): `login`, the model's account sign-in, and management's three.
  */
 const SLOTS = {
-    packages: hubPackages,
     actors: hubActors,
     bindings: hubBindings,
     grants: hubGrants,
     exports: hubExports,
     audit: hubAudit,
-    store: kv,
     login: accountLogin,
-    /** The installer, bound by the app's first run: plans, installs, exports and imports. */
-    installer,
+    agents,
+    connections,
+    skills,
 };
 const STATIC = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "static");
 /** The shell's built files, `@agentorg/shell`'s `dist`. */
@@ -52,11 +49,12 @@ function writePrivate(file, text) {
  * The app: a Hub in this process, and the person's gateway, its single running instance. The
  * gateway holds the person's one channel to the Hub. Browser tabs and the CLI are the person's UIs,
  * not channels: they reach the gateway at `/api`, and their calls run through the person's slots,
- * or as a view's Actor for a view's. The gateway exports `layout@1`, kept in the person's store.
+ * and the person's notes are the app's own file.
  */
 export async function startApp(options) {
     const home = resolve(options.home);
     mkdirSync(home, { recursive: true, mode: 0o700 });
+    closePackageActors(home);
     const hub = Hub.open(home);
     const listener = await listen(hub, {}).catch((error) => {
         hub.close();
@@ -64,134 +62,39 @@ export async function startApp(options) {
     });
     writePrivate(join(home, "url"), `${listener.url}\n`);
     const signIn = new SignIn();
-    const changes = new Set();
-    /** Who hears that a rule was turned on or off. */
-    const ruleChanges = new Set();
-    let emitChanged = () => { };
-    const isView = (actorId, module) => {
-        try {
-            const actor = hub.state.actor(actorId);
-            if (actor.package === "external" || actor.package === "builtin" || actor.state === "closed")
-                return false;
-            const { modules } = hub.state.package(actor.package).manifest;
-            return Object.hasOwn(modules, module) && modules[module]?.placement === "view";
-        }
-        catch {
-            return false;
-        }
-    };
     const credential = readFileSync(join(home, "person-credential"), "utf8").trim();
-    let logic;
+    /** The app's own notes: what the shell remembers. */
+    const notes = new Notes(join(home, "app-notes.json"));
     const person = await connect({
         hubUrl: listener.url,
         actorId: PERSON,
         credential,
         slots: SLOTS,
-        exports: { layout },
-        start(ctx) {
-            logic = new Layout({
-                store: () => ({
-                    get: (key) => ctx.slots.store.call.get({ key }),
-                    set: (key, value) => ctx.slots.store.call.set({ key, value: value }),
-                }),
-                isView,
-                changed: () => emitChanged(),
-            });
-            const served = logic;
-            ctx.exports.layout.implement({
-                get: () => served.get(),
-                // Who placed it is the caller the Hub names, never the input.
-                place: (input, { caller }) => served.place(input, caller),
-                remove: (input) => served.remove(input),
-                move: (input) => served.move(input),
-            });
-            emitChanged = () => {
-                ctx.exports.layout.emit("changed", {});
-                for (const tell of [...changes])
-                    tell();
-            };
-        },
     }).catch((error) => {
         void listener.close();
         hub.close();
         throw error;
     });
-    const layoutLogic = logic;
-    // The person's store, where the layout is kept, is the built-in storage's: bound at each start,
-    // explicitly, as the Hub binds nothing by default.
-    if (!hub.state.binding(PERSON, "store"))
-        await person.slots.grants.call
-            .bind({ consumer: PERSON, slot: "store", provider: STORAGE, export: "kv" })
-            .catch((error) => {
-            person.close();
-            void listener.close();
-            hub.close();
-            throw error;
-        });
-    /** The person's side of `/api`: its slots, and `layout`, its own export, served here. */
+    /** A slot exposed to the person at run time: here exactly while it is bound. */
+    const exposedSlot = (slot) => person.exposed().find((one) => one.slot === slot);
     const personSide = {
         async call(slot, method, input) {
-            if (slot === "rules") {
-                // The person's named rules, the gateway's own, checked as a call through the Hub would be.
-                const spec = Object.hasOwn(appRules.methods, method)
-                    ? appRules.methods[method]
-                    : undefined;
-                if (!spec)
-                    throw new Refused("invalid", `rules has no method ${method}.`);
-                const parsed = spec.input.safeParse(input);
-                if (!parsed.success)
-                    throw new Refused("invalid", `rules.${method}: ${parsed.error.message}`);
-                const result = method === "set"
-                    ? await rules.set(parsed.data)
-                    : await rules.list();
-                const checked = spec.output.safeParse(result);
-                if (!checked.success)
-                    throw new Refused("bad_output", `rules.${method}: ${checked.error.message}`);
-                return checked.data;
-            }
-            if (slot === "layout") {
-                const spec = Object.hasOwn(layout.methods, method)
-                    ? layout.methods[method]
-                    : undefined;
-                if (!spec)
-                    throw new Refused("invalid", `layout has no method ${method}.`);
-                const parsed = spec.input.safeParse(input);
-                if (!parsed.success)
-                    throw new Refused("invalid", `layout.${method}: ${parsed.error.message}`);
-                // Through /api, the caller is the person.
-                const result = await layoutLogic[method](parsed.data, PERSON);
-                // Checked as a call through the Hub would be: what's stored may not fit.
-                const checked = spec.output.safeParse(result);
-                if (!checked.success)
-                    throw new Refused("bad_output", `layout.${method}: ${checked.error.message}`);
-                return checked.data;
-            }
-            if (!Object.hasOwn(SLOTS, slot))
+            if (slot === "store")
+                return notes.call(method, input);
+            const exposed = Object.hasOwn(SLOTS, slot) ? undefined : exposedSlot(slot);
+            if (!exposed && !Object.hasOwn(SLOTS, slot))
                 throw new Refused("invalid", `The person has no slot ${slot}.`);
-            const calls = person.slots[slot].call;
+            const calls = (exposed?.call ?? person.slots[slot].call);
             const call = Object.hasOwn(calls, method) ? calls[method] : undefined;
             if (!call)
                 throw new Refused("invalid", `${slot} has no method ${method}.`);
             return call(input);
         },
         subscribe(slot, event, send) {
-            if (slot === "rules") {
-                if (event !== "changed")
-                    throw new Refused("invalid", "rules has one event, changed.");
-                const tell = () => send({});
-                ruleChanges.add(tell);
-                return () => void ruleChanges.delete(tell);
-            }
-            if (slot === "layout") {
-                if (event !== "changed")
-                    throw new Refused("invalid", "layout has one event, changed.");
-                const tell = () => send({});
-                changes.add(tell);
-                return () => void changes.delete(tell);
-            }
-            if (!Object.hasOwn(SLOTS, slot))
+            const exposed = Object.hasOwn(SLOTS, slot) ? undefined : exposedSlot(slot);
+            if (!exposed && !Object.hasOwn(SLOTS, slot))
                 throw new Refused("invalid", `The person has no slot ${slot}.`);
-            const handle = person.slots[slot];
+            const handle = (exposed ?? person.slots[slot]);
             try {
                 return handle.on(event, send);
             }
@@ -200,40 +103,17 @@ export async function startApp(options) {
             }
         },
     };
-    const views = {
-        call: (view, slot, method, input) => hub.viewCall(view.actor, view.module, slot, method, input),
-        subscribe: (view, slot, event, send, end) => hub.viewSubscribe(view.actor, view.module, slot, event, send, () => end()),
-        slots: (view, onSlot) => hub.viewSlots(view.actor, view.module, onSlot),
-        log: (view, level, message, fields) => hub.viewLog(view.actor, view.module, {
-            level,
-            message,
-            ...(fields ? { data: fields } : {}),
-        }),
-    };
     // The first run, beside serving: the shell follows the person's bindings as they're made, so it
     // needn't wait. What it can't do is logged and tried at the next start.
-    const ran = options.firstRun === false
-        ? undefined
-        : firstRun(personSide, {
-            log: (message) => process.stderr.write(`${message}\n`),
-            connected: (actorId) => hub.connected(actorId),
-            ...options.firstRun,
-        }).catch((error) => {
-            process.stderr.write(`First run didn't work: ${error instanceof Error ? error.message : String(error)}\n`);
-            return undefined;
-        });
-    // The person's named rules: off until turned on; their engine starts once the first run is done.
-    const rules = new Rules({
-        person: personSide,
+    const ran = startPrograms(personSide, {
+        home,
+        hubUrl: listener.url,
         log: (message) => process.stderr.write(`${message}\n`),
-        changed: () => {
-            for (const tell of [...ruleChanges])
-                tell();
-        },
+        ...options.firstRun,
+    }).catch((error) => {
+        process.stderr.write(`First run didn't work: ${error instanceof Error ? error.message : String(error)}\n`);
+        return undefined;
     });
-    void Promise.resolve(ran)
-        .then(() => rules.start())
-        .catch((error) => process.stderr.write(`The rules didn't start: ${error instanceof Error ? error.message : String(error)}\n`));
     /** The app's own pages: scripts and styles from here only, framed by nothing. */
     const appCsp = [
         "default-src 'self'",
@@ -241,7 +121,7 @@ export async function startApp(options) {
         "style-src 'self' 'unsafe-inline'",
         "img-src 'self' data:",
         "connect-src 'self'",
-        "frame-src 'self'",
+        "frame-src 'none'",
         "object-src 'none'",
         "base-uri 'none'",
         "form-action 'self'",
@@ -266,15 +146,6 @@ export async function startApp(options) {
         const route = routes.get(url.pathname);
         if (route)
             return route(request, response, url);
-        if (url.pathname.startsWith("/frames/")) {
-            const served = request.method === "GET"
-                ? serveFrame(url.pathname, origin, bundleOf, request.headers.origin)
-                : undefined;
-            if (!served)
-                return void response.writeHead(404).end();
-            response.writeHead(served.status, served.headers).end(served.body);
-            return;
-        }
         if (url.pathname === "/api/session" && request.method === "POST") {
             // Same-origin only: a cross-site form can't trade a code it saw.
             if (request.headers.origin !== origin)
@@ -294,14 +165,6 @@ export async function startApp(options) {
             response.writeHead(200, { "Content-Type": "application/json", "Cache-Control": "no-store" });
             return void response.end(JSON.stringify({ session }));
         }
-        // A package's archive, and a system's file, both ways: for the person's UIs only, a tab by its
-        // session and the CLI by its token, as a bearer, which no other page can send.
-        if (url.pathname.startsWith("/packages") || url.pathname === "/system") {
-            const bearer = /^Bearer (\S+)$/.exec(request.headers.authorization ?? "")?.[1];
-            if (!signIn.isCli(request.headers.authorization) && !signIn.isSession(bearer))
-                return void response.writeHead(401).end();
-            return transfer(request, response, url);
-        }
         if (url.pathname === "/api/code" && request.method === "POST") {
             // The CLI's way to sign a browser in again: a fresh code, for its token only.
             if (!signIn.isCli(request.headers.authorization))
@@ -333,98 +196,6 @@ export async function startApp(options) {
         });
         response.end(request.method === "HEAD" ? undefined : body);
     };
-    /** Answer a transfer's failure as `/api` answers a call's: `{error}`, with a fitting status. */
-    const failure = (response, error) => {
-        const body = error instanceof Refused
-            ? { name: "Refused", message: error.message, code: error.code }
-            : error instanceof Error &&
-                (error.name === "NotConnected" || error.name === "OutcomeUnknown")
-                ? { name: error.name, message: error.message }
-                : { name: "Refused", message: "The gateway couldn't handle this.", code: "internal" };
-        const status = body.code === "too_large"
-            ? 413
-            : body.code === "invalid" || body.code === "unknown"
-                ? 400
-                : 409;
-        response.writeHead(status, { "Content-Type": "application/json", "Cache-Control": "no-store" });
-        response.end(JSON.stringify({ error: body }));
-    };
-    const sendFile = (response, name, bytes) => {
-        response.writeHead(200, {
-            "Content-Type": "application/octet-stream",
-            "Content-Disposition": `attachment; filename="${name.replace(/[^\w.@-]/g, "_")}"`,
-            "Cache-Control": "no-store",
-            "X-Content-Type-Options": "nosniff",
-        });
-        response.end(bytes);
-    };
-    /**
-     * `GET /packages/<hash>.agentorg`: a stored package's archive. `POST /packages`: an archive to
-     * add, verified by the Hub. `GET /system`: the system's file, its composition and every package
-     * it pins. `POST /system`: a system file, its packages added (each one's hash checked against
-     * its name), then imported with the person's authority.
-     */
-    const transfer = async (request, response, url) => {
-        try {
-            const archive = /^\/packages\/(sha256-[0-9a-f]{64})\.agentorg$/.exec(url.pathname);
-            if (archive && request.method === "GET") {
-                const hash = archive[1];
-                const bytes = packageArchive(home, hash);
-                if (!bytes)
-                    throw new Refused("unknown", `No package ${hash}.`);
-                const { manifest } = hub.state.package(hash);
-                return sendFile(response, `${manifest.name}-${manifest.version}.agentorg`, bytes);
-            }
-            if (url.pathname === "/packages" && request.method === "POST") {
-                const bytes = await readBytes(request, MAX_TRANSFER);
-                const added = await withTemporaryFile(home, "upload.agentorg", bytes, (path) => person.slots.packages.call.add({ path }));
-                response.writeHead(200, {
-                    "Content-Type": "application/json",
-                    "Cache-Control": "no-store",
-                });
-                return void response.end(JSON.stringify(added));
-            }
-            if (url.pathname === "/system" && request.method === "GET") {
-                const { composition } = await person.slots.installer.call.exportSystem({});
-                const archives = new Map();
-                for (const hash of pinnedHashes(composition)) {
-                    const bytes = packageArchive(home, hash);
-                    if (bytes)
-                        archives.set(hash, bytes);
-                }
-                return sendFile(response, "system.agentorg-system", writeSystem(composition, archives));
-            }
-            if (url.pathname === "/system" && request.method === "POST") {
-                const { composition, packages } = readSystem(await readBytes(request, MAX_TRANSFER));
-                // Named by its hash, so the Hub refuses an archive whose hash isn't its name.
-                for (const [hash, bytes] of packages)
-                    await withTemporaryFile(home, `${hash}.agentorg`, bytes, (path) => person.slots.packages.call.add({ path }));
-                const imported = await person.slots.installer.call.importSystem({ composition });
-                response.writeHead(200, {
-                    "Content-Type": "application/json",
-                    "Cache-Control": "no-store",
-                });
-                return void response.end(JSON.stringify(imported));
-            }
-            response.writeHead(405).end();
-        }
-        catch (error) {
-            failure(response, error);
-        }
-    };
-    const bundleOf = (hash, module) => {
-        try {
-            const entry = hub.state.package(hash).manifest.modules[module];
-            if (entry?.placement !== "view")
-                return undefined;
-            const dir = join(home, "packages", hash);
-            const file = resolve(dir, entry.entry);
-            return file.startsWith(dir + sep) ? file : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    };
     const sockets = new WebSocketServer({ noServer: true, maxPayload: MAX_MESSAGE });
     server.on("upgrade", (request, socket, head) => {
         // An upgraded socket has no error handler of its own: a client that resets would crash the app.
@@ -441,7 +212,7 @@ export async function startApp(options) {
         sockets.handleUpgrade(request, socket, head, (ws) => {
             let served;
             const serve = () => {
-                served = serveSocket({ send: (text) => ws.send(text), close: (code, reason) => ws.close(code, reason) }, { person: personSide, views });
+                served = serveSocket({ send: (text) => ws.send(text), close: (code, reason) => ws.close(code, reason) }, { person: personSide });
             };
             // The CLI is in by its token; a tab says its session first, or is closed.
             if (cli)
@@ -487,21 +258,21 @@ export async function startApp(options) {
     writePrivate(join(home, "app.json"), `${JSON.stringify({ url: origin, pid: process.pid })}\n`);
     let closing;
     let stopped = () => { };
+    let lost = false;
     const closed = new Promise((done) => {
-        stopped = () => done({ lost: false });
+        stopped = () => done({ lost });
         // The person's channel gone (taken over, or the Hub gone): the gateway can't serve, so it stops.
         void person.closed.then(() => {
             if (!closing) {
+                lost = true;
                 void close();
-                done({ lost: true });
             }
         });
     });
     const close = () => {
         closing ??= (async () => {
             // A first run still going finishes first, so it isn't cut off half way.
-            await ran;
-            rules.close();
+            const programs = await ran;
             const ours = (file, text) => {
                 if (file === "cli-token")
                     return text.trim() === signIn.cliToken;
@@ -531,6 +302,7 @@ export async function startApp(options) {
             const serverClosed = new Promise((done) => server.close(() => done()));
             server.closeAllConnections();
             await serverClosed;
+            await programs?.close();
             person.close();
             await person.closed;
             await listener.close();
@@ -543,7 +315,7 @@ export async function startApp(options) {
         url: origin,
         hubUrl: listener.url,
         hub,
-        ...(ran ? { firstRun: ran } : {}),
+        firstRun: ran,
         signInUrl: () => `${origin}/signin#${signIn.code()}`,
         route: (path, route) => void routes.set(path, route),
         close,
@@ -574,24 +346,6 @@ function contentType(file) {
         return "image/svg+xml";
     return "application/octet-stream";
 }
-/** A request's body as bytes, up to `max`: past it, `Refused("too_large")`. */
-function readBytes(request, max) {
-    return new Promise((done, failed) => {
-        const chunks = [];
-        let size = 0;
-        request.on("data", (chunk) => {
-            size += chunk.length;
-            if (size > max) {
-                request.destroy();
-                failed(new Refused("too_large", `A file here is ${max / 1024 / 1024} MiB at most.`));
-            }
-            else
-                chunks.push(chunk);
-        });
-        request.on("end", () => done(new Uint8Array(Buffer.concat(chunks))));
-        request.on("error", failed);
-    });
-}
 function readBody(request) {
     return new Promise((done, failed) => {
         let body = "";

package/dist/src/index.d.ts

@@ -1,7 +1,6 @@
-export { type PersonSide, type Socket, serveSocket, type View, type ViewCalls } from "./api.js";
-export { frameCsp, serveFrame, type ViewBundle } from "./frames.js";
+export { type PersonSide, type Socket, serveSocket } from "./api.js";
 export { type App, type AppOptions, type Route, startApp } from "./gateway.js";
-export { LAYOUT_KEY, Layout, type LayoutStore, type PlacementRecord } from "./layout.js";
-export { type FirstRun, type FirstRunOptions, firstRun, oauthRoute, type PersonCalls, type Target, } from "./model.js";
+export { Notes } from "./notes.js";
+export { oauthRoute, type PersonCalls } from "./oauth.js";
+export { type Programs, type ProgramsOptions, startPrograms } from "./programs.js";
 export { SignIn } from "./signin.js";
-export { MAX_TRANSFER, packageArchive, pinnedHashes, readSystem, type SystemComposition, withTemporaryFile, writeSystem, } from "./transfer.js";

package/dist/src/index.js

@@ -1,7 +1,6 @@
 export { serveSocket } from "./api.js";
-export { frameCsp, serveFrame } from "./frames.js";
 export { startApp } from "./gateway.js";
-export { LAYOUT_KEY, Layout } from "./layout.js";
-export { firstRun, oauthRoute, } from "./model.js";
+export { Notes } from "./notes.js";
+export { oauthRoute } from "./oauth.js";
+export { startPrograms } from "./programs.js";
 export { SignIn } from "./signin.js";
-export { MAX_TRANSFER, packageArchive, pinnedHashes, readSystem, withTemporaryFile, writeSystem, } from "./transfer.js";

package/dist/src/notes.d.ts

@@ -0,0 +1,11 @@
+/** A file of JSON values by key, answering as `kv@1` does. Each write replaces it whole. */
+export declare class Notes {
+    #private;
+    constructor(file: string);
+    get(key: string): {
+        value?: unknown;
+    };
+    set(key: string, value: unknown): object;
+    /** One `kv@1` call, checked as a call through the Hub would be. */
+    call(method: string, input: unknown): unknown;
+}

package/dist/src/notes.js

@@ -0,0 +1,64 @@
+// The app's own notes: what the person's pages and the gateway keep, in one private file.
+import { readFileSync, renameSync, writeFileSync } from "node:fs";
+import { kv } from "@agentorg/interfaces";
+import { Refused } from "@agentorg/sdk";
+/** Keys read at once by a `list`. */
+const PAGE = 1000;
+/** A file of JSON values by key, answering as `kv@1` does. Each write replaces it whole. */
+export class Notes {
+    #file;
+    #values;
+    constructor(file) {
+        this.#file = file;
+        let raw;
+        try {
+            raw = readFileSync(file, "utf8");
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        this.#values = raw === undefined ? {} : JSON.parse(raw);
+    }
+    get(key) {
+        return Object.hasOwn(this.#values, key) ? { value: this.#values[key] } : {};
+    }
+    set(key, value) {
+        this.#values[key] = value;
+        this.#save();
+        return {};
+    }
+    /** One `kv@1` call, checked as a call through the Hub would be. */
+    call(method, input) {
+        const spec = Object.hasOwn(kv.methods, method)
+            ? kv.methods[method]
+            : undefined;
+        if (!spec)
+            throw new Refused("invalid", `store has no method ${method}.`);
+        const parsed = spec.input.safeParse(input);
+        if (!parsed.success)
+            throw new Refused("invalid", `store.${method}: ${parsed.error.message}`);
+        const given = parsed.data;
+        if (method === "get")
+            return this.get(given.key);
+        if (method === "set")
+            return this.set(given.key, given.value);
+        if (method === "delete") {
+            const deleted = Object.hasOwn(this.#values, given.key);
+            delete this.#values[given.key];
+            if (deleted)
+                this.#save();
+            return { deleted };
+        }
+        const { prefix = "", after, limit = PAGE } = given;
+        const found = Object.keys(this.#values)
+            .filter((key) => key.startsWith(prefix) && (after === undefined || key > after))
+            .sort();
+        const keys = found.slice(0, limit);
+        return { keys, next: found.length > limit ? (keys.at(-1) ?? null) : null };
+    }
+    #save() {
+        writeFileSync(`${this.#file}.tmp`, JSON.stringify(this.#values), { mode: 0o600, flush: true });
+        renameSync(`${this.#file}.tmp`, this.#file);
+    }
+}

package/dist/src/oauth.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+/**
+ * How the app's parts reach the Hub: the person's own calls, as `/api` makes them. A call that
+ * doesn't reach its provider rejects with an error named `NotConnected`, as `/api` names it.
+ */
+export interface PersonCalls {
+    call(slot: string, method: string, input: unknown): Promise<unknown>;
+}
+/**
+ * `/oauth/chatgpt`: where ChatGPT sends the browser back. It hands the whole callback address to
+ * the person's `login.complete`, then sends the tab on to `?result=<outcome>`, an address without
+ * the sign-in's code, so the code stays out of the tab's address and history; that page says how
+ * it went and links back to the shell. The code is never logged or shown, and no page sends a
+ * referrer.
+ */
+export declare function oauthRoute(person: PersonCalls): (request: IncomingMessage, response: ServerResponse, url: URL) => void;