@nervur-org/dock 0.3.0

package/dist/cli/daemon.d.ts

@@ -0,0 +1,50 @@
+import { DiskHarbor, type Hosted } from '../harbor/disk.ts';
+import type { Harbor } from '@nervur-org/nervur/harbor';
+import type { Avatar } from '../beings/index.ts';
+export { avatarOf, letIn, find } from '../beings/join.ts';
+import { type Ring } from '../dock/index.ts';
+import { Grants } from '../dock/grants.ts';
+import { Agents } from '../dock/agents.ts';
+import type { OAuth } from '../mcp/oauth.ts';
+import { Exchange } from '../mcp/allow.ts';
+import { McpHttp } from '../mcp/http.ts';
+import { type Routes } from '../mcp/route.ts';
+import { type Apps } from '../human/web.ts';
+import { type Http, type Quo } from '../harbor/http.ts';
+export type { Routes } from '../mcp/route.ts';
+export type Serving = {
+    harbor: DiskHarbor;
+    sock: string;
+    side: string;
+    http: Http | null;
+    grants: Grants | null;
+    oauth: OAuth | null;
+    exchange: Exchange | null;
+    mcp: McpHttp | null;
+    agents: Agents | null;
+    quo: Quo;
+    tick(now: number): Promise<void>;
+    close(): Promise<void>;
+};
+export type Options = {
+    http?: {
+        port: number;
+        host?: string;
+    };
+    routes?: Routes;
+    apps?: Apps | null;
+    dial?: string[];
+    rings?: Record<string, Ring>;
+};
+export declare const sockPath: (dir: string) => string;
+export declare const sidePath: (dir: string) => string;
+export declare function admit(harbor: Harbor, hosted: Hosted, identity: string, wake?: boolean, reach?: boolean): Promise<{
+    avatar?: Avatar;
+    error?: string;
+}>;
+export declare function serve(dir: string, options?: Options): Promise<Serving>;
+export declare const DOMAIN: RegExp;
+export declare function routesFor(domain: string): Required<Routes>;
+export declare function writeRoutes(dir: string, domain: string): Promise<Required<Routes>>;
+export declare function readRoutes(dir: string): Promise<Routes | null>;
+export declare function readApps(dir: string): Promise<Apps | null>;

package/dist/cli/daemon.js

@@ -0,0 +1,584 @@
+// SPDX-License-Identifier: Apache-2.0
+// The daemon: `quo serve`. One process holds the harbor and the ask pointer
+// of every ward in it. Two local doors, never mixed, each a unix socket only
+// the device's user can read:
+//
+//   quo.sock    the root. One line of JSON in, one line out.
+//               -> { id, ward?, method?, args?, via? }
+//               <- { id, result } | { id, error }
+//               With `being`, the line is the owner's `ask`, forwarded like
+//               the other six: the ward names the asker, bounds the wait and
+//               judges her answer, and the pointer saves before it returns.
+//               -> { id, ward?, being, method?, args? }
+//               A result of silence crosses as { silence: true }, because the
+//               wire has no symbol. With `via`, the line is an owner ask on
+//               another ward: `via` names a standing the user being holds
+//               at that ward, and the daemon asks on it in-process, as it
+//               drives an avatar for a side. The answer is what the far
+//               ward says to an owner at its door.
+//   side.sock   local sides. The first line names the client identity, and
+//               every line after is MCP, JSON-RPC, one message per line. The
+//               daemon runs the model side in-process with the avatar; the
+//               process on the other end of the socket is a pipe to stdio.
+//               -> { as, ward? }
+//               <- { ok: as } | { error }
+//               With `run`, the side is the runner instead: a model at a
+//               completions endpoint, driven from here. Every line after the
+//               hello is one line from the human and starts a turn; every
+//               final text the model says comes back as one line, whoever
+//               started the turn. The bearer, if any, is read from the
+//               device by the client and crosses only this socket.
+//               -> { as, ward?, run: { url, model, key?, turns? } }
+//               <- { ok: as } | { error }, then one line per final text
+//
+// The proof for a local side is that it reached side.sock: the daemon mints
+// a nonce for the connection on the `local` faculty of its dock ward, the
+// box's own way in, and the desk trades it at a standing there, once. A
+// `local` proof arriving any other way names no nonce and is refused.
+//
+// Agents have no door: the `agents` faculty of the dock ward holds each
+// agent's identity, her ward, her command and her folder, placed by the
+// root with `keep` as a schedule is placed on the clock, and the daemon
+// admits her on the local proof and runs the agent side beside her avatar
+// for as long as it serves. A push to her from the user being runs the
+// command in the folder with the event.
+//
+// One timer on the box, and she is the `timer` faculty of its dock: the only
+// thing on the device that reads its clock. She arms herself for the next
+// moment any Clock who lent her is due, and for nothing when none is, and
+// the daemon winds nothing; what it holds is `tick`, a round at a moment
+// somebody names, for a suite and an operator. A tick wakes every being
+// that asked to be woken, the Clock among them, at her own door as the
+// occupant `timer`, and she wakes everyone else through their doors, on
+// standings the root placed, so every wake is named, counted, once-only and
+// judged at a gate. What she holds is in her cells, placed by the root with
+// `keep`, and the daemon reads no schedule from anywhere. A daemon with no
+// clock booted holds a timer that finds nobody and arms nothing.
+//
+// The dock is built here and handed to the harbor, once: the timer, and the
+// push faculty with one ring per token kind this device can ring.
+//
+// The default ward is the one a caller means when naming none: the one ward
+// hosted, or the one marked in its own folder by `quo default`. A harbor is
+// not a being and has no self to be, so the one thing it can do is point at
+// one of its wards. Its agents boot there and its door answers for it when a
+// caller names no ward. Several wards and no mark is refused here, by name,
+// rather than coming up on a guess. What stands in a ward is the ward's own
+// truth, restored from its folder, and the daemon reads no recipe at boot.
+//
+// A third door, for occupants from elsewhere, is one HTTP listener on
+// localhost that a reverse proxy fronts, `harbor/http.ts`. Routes mount on it by
+// path, and each lives in the folder whose truth it is: `/web`, the worlds'
+// pages and the allow page, in `human/web.ts` and `mcp/allow.ts`; `/mcp`, the
+// model side behind its credential exchange, in `mcp/route.ts`; `/quo`, the
+// socket door, in `harbor/quo.ts`; `/api`, a public being's describe and
+// asks as plain JSON for anyone, in `api/route.ts`. It listens only when asked, and only on
+// loopback: the proxy is what faces the world, and the daemon never does.
+// With a row on the dialers faculty, placed by the root with `keep`, this
+// daemon is itself a dialer: it holds one socket to each URL, announces its
+// wards, and reconnects with backoff, so a Mac behind NAT is reached
+// through the droplet it dialed.
+import { createServer } from 'node:net';
+import { unlink, chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { createHash, randomBytes } from 'node:crypto';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { createInterface } from 'node:readline';
+import { isSilence, isWord, wordOf } from '@nervur-org/nervur';
+import { DiskHarbor, defaultWard } from '../harbor/disk.js';
+// an identity in a world: the three asks any terrain's routes make at a ward
+export { avatarOf, letIn, find } from '../beings/join.js';
+import { avatarOf, letIn, find } from '../beings/join.js';
+import { DOCK, FACULTIES, LOCAL, PUSH, TIMER, Local, Push, Timer, facultyOf, publicOf, routed, settled, webPush } from '../dock/index.js';
+import { apnsHttp2, apnsOf } from '../dock/http2.js';
+import { GRANTS, Grants } from '../dock/grants.js';
+import { AGENTS, Agents, isProcess } from '../dock/agents.js';
+import { DIALERS, Dialers } from '../dock/dialers.js';
+import { mcpSide } from '../mcp/server.js';
+import { runnerSide } from '../mcp/runner.js';
+import { agentSide, processRun } from '../mcp/agent.js';
+import { Exchange } from '../mcp/allow.js';
+import { McpHttp } from '../mcp/http.js';
+import { mcpRoute } from '../mcp/route.js';
+import { webRoute } from '../human/web.js';
+import { bundles } from './bundles.js';
+import { diskFolder } from './folder.js';
+import { danceOnDisk } from './oauth.js';
+import { quoRoute } from '../harbor/quo.js';
+import { apiRoute } from '../api/route.js';
+import { listenHttp } from '../harbor/http.js';
+// The sockets live in the harbor's folder, where the folder's own permissions
+// guard them. A unix socket path is short by law, about a hundred bytes on
+// macOS, so a deep folder gets its sockets in the temp dir under a name only
+// its path produces. Client and daemon compute the same answer.
+const socketPath = (dir, name) => {
+    const inside = join(resolve(dir), `${name}.sock`);
+    if (inside.length < 100)
+        return inside;
+    return join(tmpdir(), `quo-${createHash('sha256').update(resolve(dir)).digest('hex').slice(0, 16)}-${name}.sock`);
+};
+export const sockPath = (dir) => socketPath(dir, 'quo');
+export const sidePath = (dir) => socketPath(dir, 'side');
+// Admit a local client identity into a ward: find or boot her avatar, and
+// enter her with a nonce the box's way in honours once. On a reconnect she
+// already holds `user` and nothing is minted, so `wake` and `reach` are read
+// the first time only; to change one, remove the occupant and admit again.
+// The one path for a side on the device: agents, and sides on side.sock.
+//
+// The nonce is minted on the `local` faculty of this box's dock ward, in
+// this process, as a device fires its own timer. A box that lends no such
+// name has no local way in, and nothing here can make one up.
+export async function admit(harbor, hosted, identity, wake = false, reach = false) {
+    const local = facultyOf(harbor, LOCAL);
+    if (!local)
+        return { error: 'this box has no local way in' };
+    const found = await avatarOf(hosted, identity);
+    if (!found.avatar)
+        return found;
+    const nonce = randomBytes(16).toString('hex');
+    local.mint(nonce, { user: hosted.record.user, client: identity, ...(wake ? { wake: true } : {}), ...(reach ? { reach: true } : {}) });
+    const entered = await found.avatar.enter({ ward: hosted.pk }, { kind: LOCAL, nonce });
+    local.drop(nonce);
+    await hosted.save(); // the knock went through the ward's own door, which the harbor never sees
+    if ('error' in entered && !('asks' in entered))
+        return { error: entered.error };
+    return { avatar: found.avatar };
+}
+// One round of the box's timer. She is a being of the harbor's own ward and
+// arms her own round at birth, so nothing here winds her; this is the round
+// at a moment somebody names, which is how a suite proves a wake without
+// waiting a minute for one and how an operator fires what is due now.
+//
+// Every being who invited her is asked at her own door, as the occupant she
+// minted, with the moment in the args. A box whose timer nobody invited
+// wakes nobody.
+async function tick(harbor, now) {
+    // Whoever was born since the last round takes her standing first. A being
+    // booted a moment ago is still taking one, and a round that ran past her
+    // would be a schedule placed and a minute missed for no reason a reader
+    // could see.
+    await settled();
+    const timer = facultyOf(harbor, TIMER);
+    if (!timer)
+        return;
+    try {
+        for (const woke of await timer.fire(now)) {
+            const out = woke.out;
+            // The default clock keeps no fire log: the daemon's own output is the
+            // record, and the box that would read it is the box the work ran on. A
+            // minute with nothing due says nothing, so a journal shows the wakes and
+            // not the clock.
+            if (out && typeof out === 'object' && Array.isArray(out.fired) && out.fired.length)
+                console.log(JSON.stringify({ tick: new Date(now).toISOString(), fired: out.fired }));
+        }
+    }
+    finally {
+        for (const h of harbor.wards.values())
+            await h.save(); // the wakes went through the wards' own doors, which the harbor never sees
+    }
+}
+async function listen(path, onConnection) {
+    await unlink(path).catch(() => { }); // a socket left by a process that died holds nobody
+    const server = createServer(onConnection);
+    await new Promise((ok, no) => {
+        server.once('error', no);
+        server.listen(path, () => ok());
+    });
+    await chmod(path, 0o600);
+    return server;
+}
+export async function serve(dir, options = {}) {
+    // The box's own ward, before any other boots on it. The rings are filled
+    // in below once the routes are known, since Web Push signs under this
+    // world's own web origin; the push faculty reads the map at each ring, so
+    // it is this daemon's `Push` body and no static set on a class.
+    const rings = { ...options.rings };
+    class DaemonPush extends Push {
+        get rings() {
+            return rings;
+        }
+    }
+    const harbor = new DiskHarbor(dir, undefined, { Push: DaemonPush, Grants, Agents, Dialers });
+    // What a daemon lends beyond every box's faculties: `local`, the way in
+    // for a process it saw on its own socket, and `grants`, the bearers its
+    // routes honour. A device with no daemon has neither name, and the desk
+    // there is a world nobody walks into locally.
+    harbor.lent = { ...FACULTIES, [LOCAL]: 'Local', [GRANTS]: 'Grants', [AGENTS]: 'Agents', [DIALERS]: 'Dialers' };
+    // A store that refused a save, once per ward. Every asker whose write was
+    // refused has already been told, at the door that caused it, and none of
+    // them is this operator: a disk that has stopped taking one world's writes
+    // is the thing the journal is for. Once, because a full disk refuses every
+    // save after the first and a line per ask is a log nobody reads.
+    harbor.onFault = (name, faults) => {
+        if (faults === 1)
+            console.log(JSON.stringify({ at: new Date().toISOString(), refused: name }));
+    };
+    await harbor.boot();
+    // A ward the folder keeps and the harbor could not open stops this daemon
+    // here. The core is right to carry on without it, since a device with many
+    // worlds must not lose them all to one, but a daemon's folder is an
+    // operator's and every ward in it is meant to be served: coming up quietly
+    // with a world missing is that world gone dark with nobody told, and the
+    // form refusal the files store makes, a sealed folder and no key, would be
+    // a daemon serving nothing at all instead of saying so. The reason is the
+    // store's own, asked for again since the boot has only the name.
+    if (harbor.unbooted.length) {
+        const name = harbor.unbooted[0];
+        const why = await harbor.store.load(name).then(() => 'it would not boot', (e) => (e instanceof Error ? e.message : String(e)));
+        await harbor.close();
+        throw new Error(`the ward ${name} in ${harbor.dir}: ${why}`);
+    }
+    const sock = sockPath(harbor.dir);
+    const side = sidePath(harbor.dir);
+    const servers = [];
+    let http = null;
+    let grants = null;
+    let oauth = null;
+    let exchange = null;
+    let mcp = null;
+    let agents = null;
+    // the dialers faculty holds the lines; the route's view of them is hers
+    const dialers = facultyOf(harbor, DIALERS);
+    if (!dialers)
+        throw new Error('this box has no dialers faculty');
+    const quo = {
+        sockets: new Set(),
+        get dialers() {
+            return [...dialers.open.values()];
+        },
+    };
+    try {
+        servers.push(await listen(sock, (c) => {
+            createInterface({ input: c }).on('line', (line) => {
+                void handle(harbor, line).then((reply) => c.write(reply + '\n'));
+            });
+            c.on('error', () => { });
+        }));
+        servers.push(await listen(side, (c) => void sideConnection(harbor, c)));
+        if (options.http) {
+            const { server, ...door } = await listenHttp(harbor, options.http.host ?? '127.0.0.1', options.http.port, quo);
+            servers.push(server);
+            http = door;
+            // the sealed bytes; the sockets a dialer opens are held by the door
+            // itself, which is where this terrain's listener half lives
+            http.mount('/quo', quoRoute(harbor));
+            // The box's grants, one faculty for every route: a bearer names an
+            // identity in a world, the identity names her avatar there, and the
+            // route only says the grammar. Nothing is minted for a bearer. Her
+            // cells are the dock ward's to keep, so a token issued saves it.
+            grants = facultyOf(harbor, GRANTS) ?? null;
+            if (!grants)
+                throw new Error('this box has no grants');
+            grants.persist = () => harbor.wards.get(DOCK)?.save() ?? Promise.resolve();
+            const resolve = async (identity, ward) => {
+                const hosted = harbor.wards.get(ward);
+                return hosted ? find(hosted, identity) : { error: 'no such world' };
+            };
+            const join = async (identity, invitation, ward) => {
+                const hosted = harbor.wards.get(ward);
+                if (!hosted)
+                    return { error: 'no such world' };
+                const r = await letIn(hosted, identity, invitation);
+                return r.error ? { error: r.error } : {};
+            };
+            const routes = options.routes ?? (await readRoutes(harbor.dir));
+            const here = `http://${http.host}:${http.port}`;
+            const at = { quo: routes?.quo ?? `${here}/quo`, web: routes?.web ?? `${here}/web` };
+            // a stranger's public being as {}, or an occupant's avatar under a
+            // bearer; `web` is for its one human arrival, a redirect landing back
+            // which ward a caller who names none is at is the terrain's word, and
+            // on a disk it is the mark an operator wrote, read below at `defaultWard`
+            http.mount('/api', apiRoute({ wards: harbor.wards, here: () => harbor.defaultWard }, { grants, resolve, join, web: at.web }));
+            // The web ring, under the world's own doorbell key: the push faculty
+            // mints it the first time this box serves a web route and keeps it in
+            // her cells, so it lives with the wards and in no file. The ring is
+            // Web Push signed under it, and the subject a push service may
+            // complain to is this world's own web route, which every world has.
+            const push = facultyOf(harbor, PUSH);
+            if (!push)
+                throw new Error('this box has no push faculty');
+            const key = await push.mint();
+            rings.web ??= webPush({ key, subject: new URL(at.web).origin });
+            // The two rings the stores own. A world holds no platform key and
+            // never will, because Apple and Google sign a push only for the team
+            // that published the app, so a ring to a phone is handed to a bell
+            // service, a token and nothing else: the one the token names, which
+            // is the service of whichever app the phone runs, or the one the root
+            // kept on the push faculty for a token naming none. The dock names no
+            // address of its own, since whose service it is, is the estate's
+            // business and not this package's. A world told of none rings only
+            // the phones whose tokens say where.
+            //
+            // A box holding Apple's own key is the one exception, and it is not a
+            // world: it is a bell, whose wards are doorbells and whose whole job
+            // is to hold that key. Where it stands is a Node box, whose `fetch`
+            // speaks HTTP/1.1 and which Apple refuses, so its ring is the one
+            // over `node:http2`. A box handed no key routes, which is every box
+            // but a bell's.
+            const apple = apnsOf(process.env);
+            rings.apns ??= apple ? apnsHttp2(apple) : { ring: (t) => routed(push.service).ring(t) };
+            rings.fcm ??= { ring: (t) => routed(push.service).ring(t) };
+            // the worlds' pages: always, on the daemon's own door when no route names a public one
+            // the bundles the dock's build emitted: read here, because reading a
+            // file is the terrain's and a route is handed the code
+            const web = webRoute(harbor, { at, code: await bundles(), folder: diskFolder(harbor.dir), apps: options.apps ?? (await readApps(harbor.dir)), bell: publicOf(key), shown: (n) => DiskHarbor.isShown(harbor.dir, n) });
+            if (routes) {
+                // the worlds a client may be allowed into: every ward here but the
+                // dock, which is the box's and nobody's world, by name and pk, the device's own first
+                const worlds = () => [...harbor.wards]
+                    .filter(([ward]) => ward !== DOCK)
+                    .sort(([a], [b]) => (a === harbor.defaultWard ? -1 : b === harbor.defaultWard ? 1 : a.localeCompare(b)))
+                    .map(([ward, h]) => ({ ward, pk: h.pk, user: h.record.user }));
+                // the MCP endpoint: a bearer names an identity in a world, the identity names her avatar there, the side runs beside her
+                mcp = new McpHttp(resolve, async () => {
+                    for (const h of harbor.wards.values())
+                        await h.save();
+                });
+                const route = await mcpRoute(danceOnDisk(harbor.dir), routes, mcp, grants);
+                oauth = route.oauth;
+                http.mount('/mcp', route.handler);
+                http.mount('/.well-known', route.wellKnown); // the same discovery at the origin's root, where a client looks for an issuer that has a path
+                const g = grants;
+                mcp.gone = (identity, ward) => g.revoke(identity, ward); // removal at the ward ends the grant at the box
+                exchange = new Exchange({ oauth, worlds, join });
+            }
+            const ex = exchange;
+            http.mount('/web', async (req, rest) => 
+            // the worlds' pages first, then the exchange pages that share the
+            // prefix; both answer a `Response` and decline by answering
+            // nothing, and a path neither takes is this mount's own 404
+            (await web(req, rest)) ??
+                (ex && (await ex.handle(req, rest))) ??
+                new Response('no such page', { status: 404, headers: { 'content-type': 'text/plain' } }));
+        }
+        // the routes this box holds a socket to are rows on the dialers faculty,
+        // dialed from her cells at every boot; `dial` is a suite's way of placing one
+        for (const url of options.dial ?? []) {
+            const kept = dialers.keep({ url });
+            if ('error' in kept)
+                throw new Error(String(kept.error));
+        }
+        dialers.start(harbor);
+        // Which of its wards is the default: the agents and the ward the door
+        // answers for hang off it, and a guess failing in silence is not a way
+        // to find out.
+        harbor.defaultWard = defaultWard(await DiskHarbor.marked(harbor.dir), [...harbor.wards.keys()]);
+        // The agents faculty holds the table; this daemon is what runs a row:
+        // the identity admitted into her ward on the local proof, and the agent
+        // side over her avatar for as long as the daemon serves.
+        agents = facultyOf(harbor, AGENTS) ?? null;
+        if (!agents)
+            throw new Error('this box has no agents faculty');
+        await agents.start(async (row) => {
+            const hosted = harbor.wards.get(row.ward);
+            if (!hosted)
+                throw new Error(`agent ${row.id}: this device hosts no ward ${row.ward}`);
+            const admitted = await admit(harbor, hosted, row.id);
+            if (!admitted.avatar)
+                throw new Error(`agent ${row.id}: ${admitted.error}`);
+            // a process is the agent side, a model is the runner: both take a push as the event
+            return isProcess(row) ? agentSide(admitted.avatar, processRun(row.command, row.args, row.dir), () => hosted.save()) : runnerSide(admitted.avatar, row, () => { }, () => hosted.save());
+        });
+    }
+    catch (e) {
+        for (const s of servers)
+            s.close();
+        await agents?.close();
+        dialers.close();
+        await harbor.close(); // no daemon, no lease
+        throw e;
+    }
+    return {
+        harbor,
+        sock,
+        side,
+        http,
+        grants,
+        oauth,
+        exchange,
+        mcp,
+        agents,
+        quo,
+        // The tick the timer makes, at a moment somebody names: a suite proves a
+        // wake without waiting a minute for one, and an operator can make the
+        // daemon fire what is due right now.
+        tick: (now) => tick(harbor, now),
+        close: async () => {
+            facultyOf(harbor, TIMER)?.stop();
+            await mcp?.close();
+            await agents?.close();
+            dialers.close();
+            for (const s of quo.sockets)
+                s.close();
+            for (const s of servers)
+                await new Promise((ok) => s.close(() => ok()));
+            await unlink(sock).catch(() => { });
+            await unlink(side).catch(() => { });
+            await harbor.close();
+        },
+    };
+}
+// A side connection: hello, then MCP over the same lines, or, with `run`,
+// the human's lines in and the model's final texts out.
+async function sideConnection(harbor, c) {
+    c.on('error', () => { });
+    const lines = createInterface({ input: c });
+    const hello = await new Promise((ok) => lines.once('line', ok));
+    let as, hosted, run;
+    try {
+        const req = JSON.parse(hello);
+        hosted = harbor.wards.get(req.ward ?? harbor.defaultWard);
+        if (!hosted)
+            throw new Error('no such ward');
+        if (typeof req.as !== 'string' || !/^[\w.-]+$/.test(req.as) || req.as === hosted.record.user || req.as === 'desk')
+            throw new Error('as is a word, and not a being of the ward');
+        as = req.as;
+        if (req.run !== undefined) {
+            const r = req.run;
+            if (typeof r.url !== 'string' || typeof r.model !== 'string')
+                throw new Error('run names a model: { url, model }');
+            run = { url: r.url, model: r.model, ...(typeof r.key === 'string' ? { key: r.key } : {}), ...(typeof r.turns === 'number' ? { turns: r.turns } : {}) };
+        }
+    }
+    catch (e) {
+        c.end(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) + '\n');
+        return;
+    }
+    const admitted = await admit(harbor, hosted, as);
+    if (!admitted.avatar)
+        return void c.end(JSON.stringify({ error: admitted.error }) + '\n');
+    const avatar = admitted.avatar;
+    c.write(JSON.stringify({ ok: as }) + '\n');
+    if (run) {
+        const runner = runnerSide(avatar, run, (text) => c.write(text + '\n'), () => hosted.save());
+        lines.on('line', (line) => {
+            runner.say(line).then((text) => {
+                if (text === null)
+                    c.write('\n'); // the ceiling: a turn with no final text is an empty line
+            }, (e) => c.write(JSON.stringify({ error: e instanceof Error ? e.message : String(e) }) + '\n'));
+        });
+        c.once('close', () => void runner.close().catch(() => { }));
+        return;
+    }
+    const transport = {
+        start: async () => { },
+        send: async (m) => {
+            c.write(JSON.stringify(m) + '\n');
+        },
+        close: async () => {
+            c.end();
+        },
+    };
+    lines.on('line', (line) => {
+        try {
+            transport.onmessage?.(JSON.parse(line));
+        }
+        catch (e) {
+            transport.onerror?.(e instanceof Error ? e : new Error(String(e)));
+        }
+    });
+    const serving = await mcpSide(avatar, transport, () => hosted.save());
+    c.once('close', () => {
+        transport.onclose?.();
+        void serving.close().catch(() => { });
+    });
+}
+async function handle(harbor, line) {
+    let id = null;
+    try {
+        const req = JSON.parse(line);
+        id = req.id ?? null;
+        if (req.reach) {
+            // the directory is the harbor's, not a ward's: a hint from a link
+            if (typeof req.reach.pk !== 'string' || !/^[0-9a-f]{128}$/.test(req.reach.pk) || typeof req.reach.url !== 'string')
+                return JSON.stringify({ id, error: 'a reach is a ward pk and a URL' });
+            await harbor.remember(req.reach.pk, req.reach.url);
+            return JSON.stringify({ id, result: { reach: req.reach.pk, url: req.reach.url } });
+        }
+        const hosted = harbor.wards.get(req.ward ?? harbor.defaultWard);
+        if (!hosted)
+            return JSON.stringify({ id, error: 'no such ward' });
+        // Reaching into a being is the owner's seventh ask, so the socket forwards
+        // it like the other six and holds nothing of its own: the ward names the
+        // asker, bounds the wait, judges her answer and says it wrote, and the
+        // pointer saves before it returns.
+        if (req.being !== undefined) {
+            if (typeof req.being !== 'string')
+                return JSON.stringify({ id, error: 'a being is named by its key' });
+            const out = await hosted.ask('ask', { being: req.being, method: req.method, args: req.args ?? {} });
+            return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : out });
+        }
+        if (req.via !== undefined) {
+            // owning another ward is one of the human's standings, so her user
+            // being holds it, and the root asks on it. The keys rotate in the
+            // partition with every ask, and no door was passed, so the harbor
+            // saves here.
+            if (typeof req.via !== 'string')
+                return JSON.stringify({ id, error: 'via is a standing of the user being' });
+            const user = hosted.being(hosted.record.user);
+            const st = user?.standings[req.via];
+            if (!st)
+                return JSON.stringify({ id, error: `no standing ${req.via} at the user being` });
+            try {
+                const out = await st.ask(req.method, (req.args ?? {}));
+                return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : isWord(out) ? { word: wordOf(out) } : out });
+            }
+            finally {
+                await hosted.save();
+            }
+        }
+        const out = await hosted.ask(req.method, req.args ?? {});
+        return JSON.stringify({ id, result: isSilence(out) ? { silence: true } : out });
+    }
+    catch (e) {
+        return JSON.stringify({ id, error: e instanceof Error ? e.message : String(e) });
+    }
+}
+// The four routes by the one convention: `mcp.`, `web.`, `quo.` and `api.`
+// under one domain, over https. A domain is said once and the names follow;
+// an estate whose names break the convention edits the file it wrote.
+export const DOMAIN = /^[a-z0-9.-]+\.[a-z]{2,}$/i;
+export function routesFor(domain) {
+    if (!DOMAIN.test(domain))
+        throw new Error(`${domain} is not a domain`);
+    return { mcp: `https://mcp.${domain}`, web: `https://web.${domain}`, quo: `https://quo.${domain}`, api: `https://api.${domain}` };
+}
+export async function writeRoutes(dir, domain) {
+    const routes = routesFor(domain);
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, 'routes.json'), JSON.stringify(routes) + '\n');
+    return routes;
+}
+// `<dir>/routes.json`: { mcp, web, quo?, api? }, the public origins the proxy serves.
+export async function readRoutes(dir) {
+    const p = join(dir, 'routes.json');
+    if (!existsSync(p))
+        return null;
+    const r = JSON.parse(await readFile(p, 'utf8'));
+    if (typeof r.mcp !== 'string' || typeof r.web !== 'string')
+        return null;
+    const out = { mcp: r.mcp.replace(/\/$/, ''), web: r.web.replace(/\/$/, '') };
+    if (typeof r.quo === 'string')
+        out.quo = r.quo.replace(/\/$/, '');
+    if (typeof r.api === 'string')
+        out.api = r.api.replace(/\/$/, '');
+    return out;
+}
+// `<dir>/app.json`: { apple: [...], android: [{ package, fingerprints }] }, the
+// apps whose links this world's hostname opens, as the two platforms want
+// them named. An estate that ships no app of its own writes no such file,
+// serves no association file, and its links open the tab.
+export async function readApps(dir) {
+    const p = join(dir, 'app.json');
+    if (!existsSync(p))
+        return null;
+    const r = JSON.parse(await readFile(p, 'utf8'));
+    const apple = Array.isArray(r.apple) ? r.apple.filter((x) => typeof x === 'string') : [];
+    const android = Array.isArray(r.android)
+        ? r.android
+            .filter((a) => typeof a?.package === 'string' && Array.isArray(a.fingerprints))
+            .map((a) => ({ package: a.package, fingerprints: a.fingerprints.filter((f) => typeof f === 'string') }))
+        : [];
+    return apple.length === 0 && android.length === 0 ? null : { apple, android };
+}

package/dist/cli/estate/Caddyfile

@@ -0,0 +1,33 @@
+# Four hostnames, one daemon, one loopback port. Caddy faces the world and
+# terminates TLS; the daemon never does. Each hostname is a route, and a
+# route is a path on the daemon's HTTP door. A route says the grammar a
+# caller speaks and never who the caller is: a bearer the box granted is
+# honoured on every one of them. Replace DOMAIN.
+#
+#   mcp.   the model side: streamable HTTP MCP, with the OAuth dance in front
+#   web.   the bundle for plain tabs, and the exchange pages
+#   quo.   the socket door for other harbors: requests in, sockets held, the rendezvous
+#   api.   a describe and its asks as plain JSON, for a program
+#
+# There is no cli. route. The root owner is the unix socket, reached on the
+# device or over SSH, and never through here.
+
+mcp.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /mcp{uri}
+}
+
+web.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /web{uri}
+}
+
+quo.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /quo{uri}
+}
+
+api.DOMAIN {
+	reverse_proxy 127.0.0.1:8787
+	rewrite * /api{uri}
+}