@quo-systems/dock 0.1.0

package/cli/quo.ts

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// `quo`: the one command of the estate. Thin on purpose: each subcommand
+// picks a folder, reaches the daemon or the disk, and hands off. Logic that
+// appears here was missing from a being or a side, and moves there.
+//
+//   quo init   [--dir D] [--ward W]          mint a seed, boot a ward over a disk store, write both
+//   quo serve  [--dir D] [--http PORT] [--dial URL]  the daemon: harbor from disk, the two sockets, the HTTP door on loopback, a socket held to URL
+//   quo census [--dir D] [--ward W] [--via S]        the empty ask: pk and every being
+//   quo boot   [--dir D] [--ward W] [--via S] <json> { key, class, public? }
+//   quo invite [--dir D] [--ward W] [--via S] <json> { being, id }
+//   quo knock  [--dir D] [--ward W] [--via S] <json> { being | { boot, key }, id, invitation, method?, args?, wanted? }
+//   quo remove [--dir D] [--ward W] [--via S] <json> { being, id }: a relation out of a being; on the ward pk, an owner
+//   quo side   [--dir D] [--ward W] --as NAME  an avatar over stdio for a local MCP client; NAME is the client identity
+//   quo run    [--dir D] [--ward W] --as NAME --url URL --model NAME [--turns N]  a human at a terminal talking to a model through an avatar: a line in, the model's final text out
+//   quo pilot  [--dir D] [--ward W] [--via S]        the owner pilot over stdio: census, boot, invite, knock, remove
+//   quo reach  [--dir D] <pk> <url>          a hint for the harbor's directory: that ward pk lives at that quo. route
+//
+// D defaults to $QUO_DIR, then ~/.quo. W defaults to main. init takes
+// --user NAME for the user being, defaulting to the device's user. run
+// takes the model's base URL as --url or $QUO_MODEL_URL, its name as
+// --model or $QUO_MODEL, a bearer from $QUO_MODEL_KEY, read here and never
+// kept, and --turns as the ceiling of model calls in one turn. S is a
+// standing the user being holds at another ward, one the root there invited
+// as an owner: with --via, the owner asks go to that ward's door, sealed,
+// and the answers are its. Without it they are the root's, on the pointer.
+import { homedir, userInfo } from 'node:os';
+import { join } from 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { DiskHarbor } from '../harbor/disk.ts';
+import { serve } from './daemon.ts';
+import { ask, side, reach, type Run } from './client.ts';
+import { pilotSide } from '../mcp/pilot.ts';
+
+const OWNER_ASKS = new Set(['boot', 'invite', 'knock', 'remove']);
+
+function parse(argv: string[]) {
+  const flags: Record<string, string> = {};
+  const rest: string[] = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i] ?? '';
+    if (a.startsWith('--')) flags[a.slice(2)] = argv[++i] ?? '';
+    else rest.push(a);
+  }
+  const [cmd, json, more] = rest;
+  return { cmd, json, more, flags, dir: flags.dir ?? process.env.QUO_DIR ?? join(homedir(), '.quo'), ward: flags.ward ?? 'main', via: flags.via };
+}
+
+const print = (v: unknown) => console.log(JSON.stringify(v, null, 2));
+
+async function main(argv: string[]): Promise<number> {
+  const { cmd, json, more, flags, dir, ward, via } = parse(argv);
+  if (cmd === 'init') {
+    print(await DiskHarbor.init(dir, ward, flags.user ?? userInfo().username));
+    return 0;
+  }
+  if (cmd === 'side' || cmd === 'run') {
+    if (!flags.as) {
+      console.error(`quo ${cmd} needs --as NAME`);
+      return 2;
+    }
+    let run: Run | undefined;
+    if (cmd === 'run') {
+      const url = flags.url ?? process.env.QUO_MODEL_URL;
+      const model = flags.model ?? process.env.QUO_MODEL;
+      if (!url || !model) {
+        console.error('quo run needs --url URL and --model NAME, or QUO_MODEL_URL and QUO_MODEL');
+        return 2;
+      }
+      const key = process.env.QUO_MODEL_KEY;
+      const turns = flags.turns !== undefined ? Number(flags.turns) : undefined;
+      if (turns !== undefined && !(Number.isInteger(turns) && turns > 0)) {
+        console.error('--turns is a positive integer');
+        return 2;
+      }
+      run = { url, model, ...(key ? { key } : {}), ...(turns !== undefined ? { turns } : {}) };
+    }
+    await side(dir, flags.as, ward, run); // stdio to the daemon, until one end closes
+    return -1;
+  }
+  if (cmd === 'pilot') {
+    await ask(dir, undefined, {}, ward); // no daemon is a clear word now, not at the first tool call
+    const serving = await pilotSide(dir, ward, new StdioServerTransport(), (line) => console.error(`pilot ${line}`), via);
+    process.stdin.once('end', () => void serving.close().then(() => process.exit(0)));
+    return -1;
+  }
+  if (cmd === 'serve') {
+    const port = flags.http ?? process.env.QUO_HTTP;
+    const s = await serve(dir, { ...(port !== undefined ? { http: { port: Number(port) } } : {}), ...(flags.dial ? { dial: [flags.dial] } : {}) });
+    print({ dir: s.harbor.dir, sock: s.sock, side: s.side, http: s.http ? `http://${s.http.host}:${s.http.port}` : null, dial: s.quo.dialers.map((d) => d.url), wards: Object.fromEntries([...s.harbor.wards].map(([n, h]) => [n, h.pk])) });
+    const stop = () => void s.close().then(() => process.exit(0));
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    return -1; // stays up
+  }
+  if (cmd === 'reach') {
+    if (!json || !more) {
+      console.error('quo reach needs <pk> <url>');
+      return 2;
+    }
+    const out = await reach(dir, json, more);
+    print('error' in out ? { error: out.error } : out.result);
+    return 'error' in out ? 1 : 0;
+  }
+  if (cmd === 'census' || (cmd !== undefined && OWNER_ASKS.has(cmd))) {
+    const args = json ? (JSON.parse(json) as Record<string, unknown>) : {};
+    const out = await ask(dir, cmd === 'census' ? undefined : cmd, args, ward, via);
+    print('error' in out ? { error: out.error } : out.result);
+    // an error object the ward answered is an ordinary answer, and still a
+    // non-zero exit, so a script can tell a boot that happened from one that did not.
+    const failed = 'error' in out || (typeof out.result === 'object' && out.result !== null && 'error' in out.result);
+    return failed ? 1 : 0;
+  }
+  console.error('usage: quo init|serve|census|boot|invite|knock|remove|side|run|pilot|reach [--dir D] [--ward W] [--via S] [--as NAME] [--url URL --model NAME] [--dial URL] [json]');
+  return 2;
+}
+
+main(process.argv.slice(2)).then(
+  (code) => {
+    if (code >= 0) process.exit(code);
+  },
+  (e: unknown) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(1);
+  },
+);

package/dist/beings/avatar.d.ts

@@ -0,0 +1,32 @@
+import { Being } from '@quo-systems/quo';
+import type { Answer, Blueprint, Invitation, JsonObject, OccupantRecord, Wanted } from '@quo-systems/quo';
+export declare const USER = "user";
+export declare const PUSHER = "user:push";
+export declare class Avatar extends Being {
+    static cells: {
+        inbox: JsonObject[];
+    };
+    static asks: {
+        notify: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: (occ: OccupantRecord | undefined) => boolean;
+        };
+    };
+    readonly ears: Set<(object: JsonObject) => void>;
+    notify(args: JsonObject): {
+        notified: boolean;
+    };
+    enter(desk: Invitation, proof: JsonObject): Promise<Blueprint | {
+        error: string;
+    }>;
+    join(invitation: Invitation): Promise<Blueprint | {
+        error: string;
+    }>;
+    tools(): Promise<Blueprint | {
+        error: string;
+    }>;
+    call(name: string, args?: JsonObject, wanted?: Wanted): Promise<Answer>;
+}

package/dist/beings/avatar.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+// The avatar. Someone outside Quo's voice: a human at a screen, a model at
+// an MCP client, a model in an API loop. One class for every side. She holds
+// exactly one standing, `user`, and everything her side asks goes through
+// it; the user being reaches her only to push, and she hands the push to
+// every side she has. A side is in-process with her, holds the object, and
+// calls the three methods below. Nothing of a side is in her cells.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+// Her one standing, and the id under which the user being pushes to her.
+// Two ids for one far being, because standings and occupants share one
+// namespace and a record holds one or the other.
+export const USER = 'user';
+export const PUSHER = 'user:push';
+export class Avatar extends Being {
+    static cells = { inbox: [] };
+    static asks = {
+        notify: { description: 'a push from the user being', input: { type: 'object' }, for: (occ) => occ?.id === PUSHER },
+    };
+    // Her sides' ears. One identity is one avatar for life, and two sessions
+    // of that identity are two sides on her at once, so a push goes to every
+    // ear present; each side adds its own on open and removes it on close.
+    // Dropped if there is none.
+    ears = new Set();
+    // ---- what the user being may ask her
+    notify(args) {
+        this.cells.inbox.push(args);
+        for (const ear of this.ears)
+            ear(args);
+        return { notified: true };
+    }
+    // ---- what her side calls. Not asks: nobody reaches these through a door.
+    // The credential exchange's last step. `desk` is the desk's public
+    // invitation, `proof` is what the route produced. She knocks the desk as a
+    // stranger, gets an invitation the user being minted, and joins with it. A
+    // knock on a public invitation births nothing, so she holds no standing at
+    // the desk afterwards. If she already holds `user`, this is a reconnect and
+    // nothing is minted.
+    async enter(desk, proof) {
+        if (this.standings[USER])
+            return this.tools();
+        const inv = await this.knock(desk, 'device', { proof });
+        if (isSilence(inv))
+            return { error: 'silence' };
+        if (isWord(inv))
+            return { error: wordOf(inv) };
+        if (!inv || typeof inv !== 'object' || Array.isArray(inv) || 'error' in inv)
+            return inv ?? { error: 'no invitation' };
+        return this.join(inv);
+    }
+    // Knock with an invitation, hand the user being one back so she can push,
+    // and take her as `user`. The only moment a standing is born here.
+    async join(invitation) {
+        if (this.standings[USER])
+            return this.tools();
+        const mine = await this.invite(PUSHER);
+        if (mine === null)
+            return { error: 'user is taken' };
+        const out = await this.knock(invitation, 'hello', { invitation: mine });
+        if (isSilence(out) || isWord(out)) {
+            this.occupants.remove(PUSHER);
+            return { error: isSilence(out) ? 'silence' : wordOf(out) };
+        }
+        await this.take(USER, invitation);
+        return this.tools();
+    }
+    // Her describe, as the user being shows it to her. This is the tool list.
+    async tools() {
+        const st = this.standings[USER];
+        if (!st)
+            return { error: 'not joined' };
+        const bp = await st.ask();
+        if (isSilence(bp) || isWord(bp))
+            return { error: isSilence(bp) ? 'silence' : wordOf(bp) };
+        return bp;
+    }
+    // One call from the side, one ask on the standing. The three words pass
+    // through untouched; the side renders them.
+    call(name, args = {}, wanted) {
+        const st = this.standings[USER];
+        return st ? st.ask(name, args, wanted) : Promise.resolve({ error: 'not joined' });
+    }
+}

package/dist/beings/desk.d.ts

@@ -0,0 +1,42 @@
+import { Being } from '@quo-systems/quo';
+import type { Asker, Json, JsonObject } from '@quo-systems/quo';
+export type Proof = {
+    kind: string;
+    [more: string]: Json;
+};
+export type Verified = {
+    user: string;
+    client: string;
+    wake?: boolean;
+};
+export type Verifier = (proof: Proof) => Promise<Verified | null> | Verified | null;
+export declare class Desk extends Being {
+    static verifiers: Record<string, Verifier>;
+    static asks: {
+        hello: {
+            description: string;
+            input: {
+                type: string;
+            };
+        };
+        device: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    proof: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+        };
+    };
+    hello(_args: JsonObject, asker: Asker): {
+        desk: boolean;
+        asker: string | null;
+        kinds: string[];
+        users: string[];
+    };
+    device(args: JsonObject): Promise<Json>;
+}

package/dist/beings/desk.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: Apache-2.0
+// The front desk. The one public being of a world, and public for the first
+// hello only: everything after is behind an invitation. It holds a standing
+// to every user being, placed by the root, and trades a proof for a device
+// invitation that the user being mints herself. The desk never mints one.
+//
+// A proof is what a route produced after authenticating by its own means. A
+// verifier turns a proof of one kind into who it is for: which user, which
+// client identity. Verifiers are the device's, set on the class before boot
+// the way an envoy reads a secret from the device: never through cells.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+export class Desk extends Being {
+    // proof kind -> verifier. The route that makes a proof kind registers the
+    // verifier for it; the desk knows no kind by itself.
+    static verifiers = {};
+    static asks = {
+        hello: { description: 'how to get in', input: { type: 'object' } },
+        device: { description: 'trade a proof for a device invitation', input: { type: 'object', properties: { proof: { type: 'object' } }, required: ['proof'] } },
+    };
+    hello(_args, asker) {
+        return { desk: true, asker: asker.id ?? null, kinds: Object.keys(Desk.verifiers), users: Object.keys(this.cells.standings).filter((k) => k.startsWith('user:')).map((k) => k.slice(5)) };
+    }
+    async device(args) {
+        const proof = args.proof;
+        if (!proof || typeof proof !== 'object' || Array.isArray(proof) || typeof proof.kind !== 'string')
+            return { error: 'proof has a kind' };
+        const verify = Object.hasOwn(Desk.verifiers, proof.kind) ? Desk.verifiers[proof.kind] : undefined;
+        if (typeof verify !== 'function')
+            return { error: 'no such proof kind' };
+        const who = await verify(proof);
+        if (!who)
+            return { error: 'refused' };
+        const user = this.standings[`user:${who.user}`];
+        if (!user)
+            return { error: 'no such user' };
+        const inv = await user.ask('device', who.wake === true ? { client: who.client, wake: true } : { client: who.client });
+        if (isSilence(inv))
+            return { error: 'silence' };
+        if (isWord(inv))
+            return { error: wordOf(inv) };
+        return inv;
+    }
+}

package/dist/beings/index.d.ts

@@ -0,0 +1,3 @@
+export { User, DESK } from './user.ts';
+export { Desk, type Proof, type Verified, type Verifier } from './desk.ts';
+export { Avatar, USER, PUSHER } from './avatar.ts';

package/dist/beings/index.js

@@ -0,0 +1,5 @@
+// SPDX-License-Identifier: Apache-2.0
+// The beings every side shares. See quo-estate.md, the trunk.
+export { User, DESK } from './user.js';
+export { Desk } from './desk.js';
+export { Avatar, USER, PUSHER } from './avatar.js';

package/dist/beings/setup.d.ts

@@ -0,0 +1,2 @@
+import type { Hosted } from '@quo-systems/quo/harbor';
+export declare function setup(hosted: Hosted, user: string): Promise<void>;

package/dist/beings/setup.js

@@ -0,0 +1,16 @@
+import { DESK } from './user.js';
+export async function setup(hosted, user) {
+    if (!/^[\w.-]+$/.test(user) || user === 'desk')
+        throw new Error(`a user is a word, and not desk: ${user}`);
+    const boot = async (args) => {
+        const out = (await hosted.ask('boot', args));
+        if (out.error)
+            throw new Error(`init: ${out.error}`);
+    };
+    await boot({ key: 'desk', class: 'Desk', public: true });
+    await boot({ key: user, class: 'User' });
+    const inv = (await hosted.ask('invite', { being: user, id: DESK }));
+    const placed = (await hosted.ask('knock', { being: 'desk', id: `user:${user}`, invitation: inv, method: 'hello' }));
+    if (placed.taken !== `user:${user}`)
+        throw new Error('init: the desk could not reach the user being');
+}

package/dist/beings/side.d.ts

@@ -0,0 +1,25 @@
+import type { Answer, Json, JsonObject, WordName } from '@quo-systems/quo';
+import type { Avatar } from './avatar.ts';
+export type Serving = {
+    close(): Promise<void>;
+};
+export type Side = (avatar: Avatar) => Promise<Serving>;
+export type Word = {
+    word: 'object';
+    value: Json;
+} | {
+    word: 'error';
+    value: JsonObject;
+} | {
+    word: 'silence';
+} | {
+    word: 'unreached';
+} | {
+    word: 'quo';
+    name: WordName;
+};
+export declare function word(answer: Answer): Word;
+export declare const SILENCE_TEXT = "silence: the work may have happened, and no answer came back";
+export declare const UNREACHED_TEXT = "unreached: nothing was delivered; asking again is safe";
+export declare const WORD_TEXT: Record<WordName, string>;
+export declare const wordText: (name: WordName) => string;

package/dist/beings/side.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: Apache-2.0
+// The side: the one interface an avatar speaks through to someone outside
+// Quo. A side takes the avatar object, in-process, and renders three things
+// its own way: her describe as what that someone reads, a call as an ask on
+// her one standing, and a push as a notification. Sides in this repository:
+// a screen, an MCP server, a runner, an event-driven agent. None knows
+// another exists, and none of this file names a platform.
+import { isSilence, isUnreached, isWord, wordOf } from '@quo-systems/quo';
+export function word(answer) {
+    if (isSilence(answer))
+        return { word: 'silence' };
+    if (isUnreached(answer))
+        return { word: 'unreached' };
+    if (isWord(answer))
+        return { word: 'quo', name: wordOf(answer) };
+    if (answer !== null && typeof answer === 'object' && !Array.isArray(answer) && 'error' in answer)
+        return { word: 'error', value: answer };
+    return { word: 'object', value: answer };
+}
+// What a side says about the two words that carry nothing, so that whoever
+// reads them can decide: silence promises nothing, unreached promises that
+// nothing was delivered.
+export const SILENCE_TEXT = 'silence: the work may have happened, and no answer came back';
+export const UNREACHED_TEXT = 'unreached: nothing was delivered; asking again is safe';
+// And the ward's other words, each with what a side says of it.
+export const WORD_TEXT = {
+    unreached: UNREACHED_TEXT,
+    late: 'late: the wait ran out; the work may have happened',
+    invitation: 'invitation: that is not an invitation',
+    dropped: 'dropped: the standing is gone',
+    removed: 'removed: the far being removed you',
+    absent: 'absent: the far being did not come back this run',
+    unannounced: 'unannounced: the knock announced no key of its own',
+    repeated: 'repeated: that number was already honoured',
+    threw: 'threw: the far being threw',
+};
+export const wordText = (name) => WORD_TEXT[name];

package/dist/beings/user.d.ts

@@ -0,0 +1,108 @@
+import { Being } from '@quo-systems/quo';
+import type { Asker, JsonObject, OccupantRecord } from '@quo-systems/quo';
+export declare const DESK = "desk";
+declare const isDesk: (occ: OccupantRecord | undefined) => boolean;
+declare const isDevice: (occ: OccupantRecord | undefined) => boolean;
+declare const mayWake: (occ: OccupantRecord | undefined) => boolean;
+export declare class User extends Being {
+    static cells: {
+        name: string;
+        reports: JsonObject[];
+    };
+    static asks: {
+        hello: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    invitation: {
+                        type: string;
+                    };
+                };
+            };
+        };
+        whoami: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: typeof isDevice;
+        };
+        device: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    client: {
+                        type: string;
+                    };
+                    wake: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof isDesk;
+        };
+        push: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    client: {
+                        type: string;
+                    };
+                    object: {
+                        type: string;
+                    };
+                };
+                required: string[];
+            };
+            for: typeof mayWake;
+        };
+        chores: {
+            description: string;
+            input: {
+                type: string;
+            };
+            for: (occ: OccupantRecord | undefined) => boolean;
+        };
+        report: {
+            description: string;
+            input: {
+                type: string;
+                properties: {
+                    event: {
+                        type: string;
+                    };
+                    result: {};
+                };
+                required: string[];
+            };
+            for: typeof isDevice;
+        };
+    };
+    hello(args: JsonObject, asker: Asker): Promise<{
+        welcome: string | null;
+        name: import("@quo-systems/quo").Json;
+    }>;
+    whoami(_args: JsonObject, asker: Asker): {
+        id: string | null;
+        client: string | null;
+    };
+    device(args: JsonObject): Promise<JsonObject>;
+    push(args: JsonObject): Promise<{
+        error: string;
+        pushed?: undefined;
+    } | {
+        error?: undefined;
+        pushed: import("@quo-systems/quo").Json;
+    }>;
+    chores(): {
+        chores: string[];
+    };
+    report(args: JsonObject, asker: Asker): {
+        reported: boolean;
+    };
+}
+export {};

package/dist/beings/user.js

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: Apache-2.0
+// The user being. One per human, running wherever the human's world runs.
+// She holds the human's standings, and everyone who acts for the human is
+// her occupant, seeing what her gate shows. Two of her occupants are
+// special only by the id the root chose for them: `desk`, the front desk,
+// who may ask her to invite a device; and each device, whose id is the
+// client identity the desk established.
+import { Being, isSilence, isWord, wordOf } from '@quo-systems/quo';
+export const DESK = 'desk';
+const isDesk = (occ) => occ?.id === DESK;
+const isDevice = (occ) => occ !== undefined && occ.id !== DESK;
+const client = (occ) => (typeof occ?.notes.client === 'string' ? occ.notes.client : null);
+// A device the human allowed to wake her other devices: the note says so.
+const mayWake = (occ) => isDesk(occ) || occ?.notes.wake === true;
+export class User extends Being {
+    static cells = { name: '', reports: [] };
+    static asks = {
+        hello: { description: 'say hello, and hand back an invitation so she can reach you', input: { type: 'object', properties: { invitation: { type: 'object' } } } },
+        whoami: { description: 'who she thinks you are', input: { type: 'object' }, for: isDevice },
+        device: { description: 'mint an invitation for a device', input: { type: 'object', properties: { client: { type: 'string' }, wake: { type: 'boolean' } }, required: ['client'] }, for: isDesk },
+        push: { description: 'push an object to a device: wake it with an event', input: { type: 'object', properties: { client: { type: 'string' }, object: { type: 'object' } }, required: ['client', 'object'] }, for: mayWake },
+        chores: { description: 'what the agent may run', input: { type: 'object' }, for: (occ) => client(occ) === 'agent' },
+        report: { description: 'what a run of yours found', input: { type: 'object', properties: { event: { type: 'object' }, result: {} }, required: ['event', 'result'] }, for: isDevice },
+    };
+    // Anyone may say hello. A device that hands her an invitation in the args
+    // is taken as a standing under its own id, so she can push to it later.
+    async hello(args, asker) {
+        if (asker.id !== undefined && args.invitation && typeof args.invitation === 'object' && !Array.isArray(args.invitation)) {
+            const inv = args.invitation;
+            const back = await this.knock(inv);
+            if (!isSilence(back) && !isWord(back))
+                await this.take(`to:${asker.id}`, inv);
+        }
+        return { welcome: asker.id ?? null, name: this.cells.name };
+    }
+    whoami(_args, asker) {
+        return { id: asker.id ?? null, client: client(this.occupant(asker)) };
+    }
+    // The front desk asks; she mints. The client identity goes into the
+    // occupant's notes, and that is what every gate reads. `wake` is the
+    // human's word at the exchange that this device may wake her others.
+    async device(args) {
+        const c = typeof args.client === 'string' ? args.client : null;
+        if (c === null)
+            return { error: 'client is a string' };
+        const inv = await this.invite(c);
+        if (inv === null)
+            return { error: 'id taken' };
+        const rec = this.cells.occupants[c];
+        if (rec) {
+            rec.notes.client = c;
+            if (args.wake === true)
+                rec.notes.wake = true;
+        }
+        return inv;
+    }
+    async push(args) {
+        const c = typeof args.client === 'string' ? args.client : null;
+        const st = c === null ? undefined : this.standings[`to:${c}`];
+        if (!st)
+            return { error: 'no such device, or it gave no way back' };
+        const out = await st.ask('notify', args.object ?? {});
+        return isSilence(out) ? { error: 'silence' } : isWord(out) ? { error: wordOf(out) } : { pushed: out };
+    }
+    chores() {
+        return { chores: ['census', 'report'] };
+    }
+    // A device that ran something for her says what it found. Kept, so that
+    // whoever renders her can show it; the ask itself is the callback.
+    report(args, asker) {
+        this.cells.reports.push({ from: asker.id ?? null, event: args.event ?? null, result: args.result ?? null });
+        return { reported: true };
+    }
+}

package/dist/cli/client.d.ts

@@ -0,0 +1,14 @@
+export type Answer = {
+    result: unknown;
+} | {
+    error: string;
+};
+export declare function ask(dir: string, method: string | undefined, args?: Record<string, unknown>, ward?: string, via?: string): Promise<Answer>;
+export declare function reach(dir: string, pk: string, url: string): Promise<Answer>;
+export type Run = {
+    url: string;
+    model: string;
+    key?: string;
+    turns?: number;
+};
+export declare function side(dir: string, as: string, ward?: string, run?: Run): Promise<void>;