@dcasegr/skein 0.0.0-stage → 0.1.1

package/dist/client/admin.js

@@ -0,0 +1,256 @@
+// Root's admin messages (#124, #142, #143): building them is a library — installing an app, removing it,
+// a route, a read route, an address-book entry, the host row, a directory into `main`, a grant — each a
+// few messages from root to the kernel's admin boxes (docs/MESSAGES.md "The dispatch table and the
+// kernel's operations": objects, head, dispatch, peers, grant) and the app's own box (start/stop). The
+// management page builds the same messages with the same code (src/host/plan.ts) and sends them with the
+// browser's wallet. The client `skein` (admin-cli.ts) signs them with the operator's key and delivers them
+// (target.ts): over the host's control socket on the host machine, else on one BRC-104 session.
+//
+// A message is a box and a body (a record value: what the kernel's operation takes). `messageJson` is its
+// BRC-33 `/sendMessage` JSON form (what `--dry-run` prints):
+//
+//   {"message": {"recipient": "<the instance's identity key, hex>", "messageBox": "<box>", "body": <the body, DAG-JSON>}}
+import * as dagCbor from "@ipld/dag-cbor";
+import * as dagJson from "@ipld/dag-json";
+import {} from "./bundle.js";
+import { handlerCid, hashDir, recordBundles } from "./client.js";
+import { dispatchOrigin, fold } from "../runtime/dispatch.js";
+import { MAIN } from "../runtime/heads.js";
+import { DEFAULT_ONLY, onlyIgnore } from "../host/deploy.js";
+import { appHead, describe, mergeConfig, planInstall, planRootRoute, planUninstall, sendInstall, sendUninstall } from "../host/plan.js";
+import { lookup, readBlob } from "../runtime/tree.js";
+const isKey = (s) => /^0[23][0-9a-f]{64}$/.test(s);
+const keyBytes = (hex) => Uint8Array.from(Buffer.from(hex, "hex"));
+/** A message as the `/sendMessage` JSON body. */
+export function messageJson(recipient, m) {
+    return new TextDecoder().decode(dagJson.encode({ message: { recipient, messageBox: m.box, body: m.body } }));
+}
+/** Messages as `send(box, bytes)` calls make them (plan.ts sendInstall, sendUninstall), collected. */
+async function collect(run) {
+    const out = [];
+    await run(async (box, body) => { out.push({ box, body: dagCbor.decode(body) }); });
+    return out;
+}
+/**
+ * Install (or upgrade) the app `tree` into the instance `view` reads (docs/APPS.md §3): objects (≤ 1 MiB
+ * bundles), the head `<app>/app`, a dispatch message per row that changes, the start. `config` is merged
+ * over the manifest's (one level deep per program). `modules`: where a `bin/<x>.cid` module the instance
+ * lacks is found (this repo's wasm/ directory, boot.ts wasmDirObjects).
+ */
+export async function planInstallApp(tree, view, o = {}) {
+    if (o.config)
+        tree.checked.manifest.config = mergeConfig(tree.checked.manifest.config, o.config);
+    const plan = await planInstall(tree, view, { modules: o.modules ?? { get: async () => undefined } });
+    const messages = await collect((send) => sendInstall(plan, send));
+    return { prompt: describe(plan), recipient: view.identity, messages, app: plan.app, version: plan.version, recordCid: plan.recordCid, record: plan.record };
+}
+/** Uninstall: the app's `stop`, then every route the table holds for it removed; its heads are left. */
+export async function planUninstallApp(name, view) {
+    const p = await planUninstall(name, view);
+    const messages = await collect((send) => sendUninstall(p, send));
+    const prompt = [`uninstall ${name} ${p.record.version}${p.stop ? ` · stop ${JSON.stringify(p.stop)}` : ""} · dispatch remove ×${p.rows.length} · head ${name}/app left`, ...p.rows.map((r) => `    dispatch remove ${r.row.transport} ${r.row.address}${r.row.prefix ? " prefix" : ""}`)];
+    return { prompt, recipient: view.identity, messages };
+}
+/** The fields of a route that are not a handler's settings. */
+const ROW_FIELDS = ["transport", "address", "prefix", "filters", "sender", "program", "fn", "app", "optional"];
+/**
+ * Root's own route (#125, #143; `skein routes`): one `dispatch` add or remove of a route with no `app` —
+ * an app's upgrade or uninstall leaves it. A mailbox or event route at a box, an http route at a path
+ * (with `filters` and a handler's `fn`, or filters only: a read route — the site at `/`: filters
+ * ["site.get"], settings {root: "www"}), a libp2p route at a topic. No sender (#143). A remove names the
+ * key (transport, address, prefix) only.
+ */
+export async function planRoute(view, a, programs = {}) {
+    const transport = a.transport ?? (a.address.startsWith("/") ? "http" : "mailbox");
+    if (!["mailbox", "event", "http", "libp2p"].includes(transport))
+        throw new Error(`--transport ${transport}: mailbox, event, http or libp2p`);
+    if (transport === "http" && (!a.address.startsWith("/") || /[\\\0?#]/.test(a.address) || a.address.split("/").some((x) => x === "." || x === "..")))
+        throw new Error(`http address ${JSON.stringify(a.address)}: a path (from /, no ".", "..", query or fragment)`);
+    if (transport !== "http" && a.prefix)
+        throw new Error("--prefix: an http route's");
+    const settings = a.settings ?? {};
+    const bad = Object.keys(settings).filter((k) => ROW_FIELDS.includes(k));
+    if (bad.length)
+        throw new Error(`--settings: ${bad.join(", ")} ${bad.length > 1 ? "are" : "is"} the route's own, not a setting`);
+    let row = { transport, address: a.address, ...(a.prefix ? { prefix: true } : {}) };
+    if (a.op === "add") {
+        if (a.handler === undefined) {
+            if (!(transport === "http" || (transport === "libp2p" && a.address.startsWith("/"))) || !a.filters?.length)
+                throw new Error("a route names its handler; only an http or libp2p protocol (/…) read route (--filters, no handler) has none");
+            if (a.fn)
+                throw new Error("--fn: a read route has no handler");
+        }
+        else if (transport === "http" || transport === "libp2p") {
+            if (!a.fn)
+                throw new Error(`an ${transport} route names its handler's function (--fn)`);
+        }
+        row = { ...settings, ...row, ...(a.filters?.length ? { filters: a.filters } : {}), ...(a.handler !== undefined ? { program: handlerCid(a.handler, programs), ...(a.fn ? { fn: a.fn } : {}) } : {}) };
+    }
+    const p = await planRootRoute(view, a.op, row);
+    return { prompt: p.prompt, recipient: view.identity, messages: p.rows.map((r) => ({ box: "dispatch", body: { op: r.op, row: r.row } })) };
+}
+/**
+ * The claim (#89, #127, #143): one message in box `claim` to an image (its claim route takes anyone) —
+ * its sender (the wallet that sends it) is granted root; the body carries only the claimant's
+ * mailbox entry, if any.
+ */
+export function planClaim(recipient, o = {}) {
+    const body = { ...(o.messagebox ? { messagebox: o.messagebox } : {}), ...(o.handle ? { handle: o.handle, ...(o.domain ? { domain: o.domain } : {}) } : {}) };
+    return { prompt: [`claim ${recipient}: root to the key that sends this${o.messagebox ? ` · messagebox ${o.messagebox}` : ""}${o.handle ? ` (@${o.handle}${o.domain ? `@${o.domain}` : ""})` : ""}`], recipient, messages: [{ box: "claim", body }] };
+}
+/**
+ * The host row (#130): root's choice of a host and its rates — one `dispatch` message adding (or
+ * removing) the kernel route {mailbox, billing, host: <the host's key>, kernel, tick, x, rates} (#143:
+ * the host's key a setting, no sender). The first such route is the host's; the kernel bills by it,
+ * the host ticks it. Removing it ends billing.
+ */
+export function planHost(recipient, op, t) {
+    if (!isKey(t.key))
+        throw new Error(`${t.key}: not the host's key (hex)`);
+    if (op === "add" && (!Number.isSafeInteger(t.x) || t.x < 1))
+        throw new Error("x: the sats the skein prepays at a time (a whole number ≥ 1)");
+    const rates = Object.fromEntries(Object.entries(t.rates ?? {}).map(([k, v]) => {
+        if (!Number.isSafeInteger(v) || v < 0)
+            throw new Error(`rates.${k}: a whole number of sats`);
+        return [k, v];
+    }));
+    const row = { transport: "mailbox", address: "billing", host: keyBytes(t.key), program: "kernel", fn: "tick", ...(op === "add" ? { x: t.x, ...(Object.keys(rates).length ? { rates } : {}) } : {}) };
+    const shown = Object.entries(rates).map(([k, v]) => `${k} ${v}`).join(", ");
+    return {
+        prompt: [op === "add" ? `host ${t.key}: bills this skein — x ${t.x} sats a block${shown ? `, rates ${shown}` : ""} (#130: the skein pays it from its own wallet, ahead)` : `host ${t.key}: removed (nothing is billed)`],
+        recipient, messages: [{ box: "dispatch", body: { op, row } }],
+    };
+}
+/** Address-book changes (#40, #70): one message to `peers` each. */
+export function planPeers(recipient, changes) {
+    const messages = [];
+    const prompt = [];
+    for (const c of changes) {
+        if (!isKey(c.key))
+            throw new Error(`${c.key}: not an identity key (hex)`);
+        if (c.op === "remove") {
+            messages.push({ box: "peers", body: { op: "remove", key: keyBytes(c.key) } });
+            prompt.push(`peers remove ${c.key}`);
+            continue;
+        }
+        messages.push({ box: "peers", body: { op: "add", key: keyBytes(c.key), transport: c.transport, address: c.address, ...(c.handle ? { handle: c.handle } : {}), ...(c.domain ? { domain: c.domain } : {}) } });
+        prompt.push(`peers add ${c.key} → ${c.transport} ${c.address}${c.handle ? ` (@${c.handle}${c.domain ? `@${c.domain}` : ""})` : ""}`);
+    }
+    return { prompt, recipient, messages };
+}
+/**
+ * A directory into the instance's `main` (#23): its git objects in ≤ 1 MiB bundles to `objects`, the root
+ * on the last (the kernel sets `main` when there is none), then `head {name: "main", tree}` when `main` is
+ * another tree. `only` filters the directory (deploy.ts onlyIgnore; default DEFAULT_ONLY; [] for all of it).
+ * Records the view's store has are not sent. With no view (`recipient` alone) everything is sent, and the head.
+ */
+export async function planDeploy(dir, target, o = {}) {
+    const only = o.only ?? DEFAULT_ONLY;
+    const { root, records } = await hashDir(dir, only.length ? { ignore: onlyIgnore(dir, only) } : {});
+    const view = "store" in target ? target : undefined;
+    const { records: n, bundles } = await recordBundles(root, records, view ? { skip: (c) => view.store.has(c) } : {});
+    const main = view?.heads.find((h) => h.name === MAIN)?.root;
+    const head = !view || (main !== undefined && !main.equals(root));
+    const messages = bundles.map((b) => ({ box: "objects", body: dagCbor.decode(b) }));
+    if (head)
+        messages.push({ box: "head", body: { name: MAIN, tree: root } });
+    const prompt = [`deploy ${dir} → main ${root}${main?.equals(root) ? " (main is this tree already)" : ""}`, `  messages  objects ×${bundles.length} (${n} records)${head ? " · head main" : ""}`];
+    return { prompt, recipient: target.identity, messages, root };
+}
+/**
+ * The instance as the install plan reads it (plan.ts InstanceView), from its explorer: heads, the genesis
+ * (identity, programs), the address book, the route table, and the store by CID —
+ * what the management page's view reads (shruggr/skein-site www/app.js `Skein.view`).
+ */
+export async function explorerView(read) {
+    const records = new Map();
+    const record = async (cid) => {
+        const k = cid.toString();
+        if (!records.has(k))
+            records.set(k, await read(`/record/${k}`));
+        return records.get(k);
+    };
+    const top = await read("");
+    if (!top)
+        throw new Error("the explorer answered nothing (is it a skein?)");
+    const heads = Object.entries(top.heads ?? {}).map(([name, root]) => ({ name, root }));
+    const head = (name) => heads.find((x) => x.name === name)?.root;
+    const first = (await read("/log?before=1&limit=1"))?.entries?.[0]?.record;
+    const genesis = (first?.genesis ? await record(first.genesis) : {});
+    const hex = (k) => (k instanceof Uint8Array ? Buffer.from(k).toString("hex") : typeof k === "string" ? k : "");
+    const book = [];
+    if (head("peers")) {
+        for (const e of (await record(head("peers")))?.peers ?? []) {
+            const p = await record(e.peer);
+            book.push({ key: hex(p.key ?? e.key), transport: p.transport ?? "mailbox", address: p.address ?? "", ...(p.handle ? { handle: p.handle } : {}), ...(p.domain ? { domain: p.domain } : {}), ...(p.source ? { source: p.source } : {}) });
+        }
+    }
+    const chain = await read(`/thread/${dispatchOrigin()}`);
+    const dispatch = fold((chain?.updates ?? []).map((u) => u.record).filter((u) => u && u.row));
+    const store = {
+        get: async (cid) => { const v = await record(cid); if (v === undefined)
+            throw new Error(`not found: ${cid}`); return v; },
+        has: async (cid) => (await record(cid)) !== undefined,
+        bytes: async (cid) => { const v = await record(cid); if (!(v instanceof Uint8Array))
+            throw new Error(`not found: ${cid}`); return v; },
+        putBlock: async () => { },
+    };
+    return {
+        store, heads, dispatch, addressBook: book,
+        identity: hex(genesis.identity), programs: genesis.programs ?? {},
+    };
+}
+/**
+ * A grant (#142, #143; `skein-host grant`): the kernel's `grant` operation — `role` (root by default,
+ * or an app's `<app>.<role>`) to `key`, or with `remove` from it. One message to box `grant`, sent by
+ * root. Nothing is sent when the grants already say so.
+ */
+export async function planGrant(view, key, o = {}) {
+    if (!isKey(key))
+        throw new Error(`${key}: not an identity key (hex)`);
+    const role = o.role ?? "root";
+    if (role !== "root" && !/^[a-z0-9][a-z0-9._-]*\.[a-z0-9][a-z0-9_-]*$/.test(role))
+        throw new Error(`${role}: a role is root or <app>.<role> (user is any principal: never granted)`);
+    const op = o.remove ? "remove" : "add";
+    const root = view.heads.find((h) => h.name === "grants")?.root;
+    const g = root ? await view.store.get(root).catch(() => undefined) : undefined;
+    const holds = (g?.roles?.[role] ?? []).some((k) => (k instanceof Uint8Array ? Buffer.from(k).toString("hex") : String(k)) === key);
+    if (holds === (op === "add"))
+        return { prompt: [`grant ${op} ${role} ${key}: the grants say so already`], recipient: view.identity, messages: [] };
+    return { prompt: [`grant ${op} ${role} ${key}`], recipient: view.identity, messages: [{ box: "grant", body: { op, role, principal: keyBytes(key) } }] };
+}
+/** The catalog in the instance's own site tree (its app `site`: www/catalog.json), and the names in it. */
+export async function catalogOf(view) {
+    const head = view.heads.find((h) => h.name === appHead("site"))?.root;
+    const rec = head ? await view.store.get(head).catch(() => undefined) : undefined;
+    if (rec?.kind !== "app")
+        throw new Error("the instance has no site app (site/app): no catalog to name an app from; give <url>#<commit>");
+    const leaf = await lookup(view.store, rec.tree, "www/catalog.json");
+    if (!leaf)
+        throw new Error(`the site app ${rec.version} has no www/catalog.json`);
+    const c = JSON.parse(new TextDecoder().decode(await readBlob(view.store, leaf.cid)));
+    return (c.apps ?? []).filter((e) => e && typeof e.name === "string" && typeof e.url === "string" && /^[0-9a-f]{40}$/i.test(e.hash ?? ""));
+}
+/**
+ * The kernel's gate (#143, kernel-zig/src/grants.zig), read from the instance's view: the roles that
+ * gate a route's handler (its app's `roles` for its fn; a kernel admin box's is root) and whether
+ * `key` passes them. Root passes anything; `user` passes any key; no gating roles: open.
+ */
+export async function gatePasses(view, row, key) {
+    const root = view.heads.find((h) => h.name === "grants")?.root;
+    const g = root ? await view.store.get(root).catch(() => undefined) : undefined;
+    const holds = (role) => (g?.roles?.[role] ?? []).some((k) => (k instanceof Uint8Array ? Buffer.from(k).toString("hex") : String(k)) === key);
+    const r = row;
+    let roles = [];
+    if (r.op)
+        roles = ["root"];
+    else if (r.app && r.fn) {
+        const { appRecordIn } = await import("../host/plan.js");
+        const rec = await appRecordIn(view, r.app);
+        const map = rec?.record?.roles ?? {};
+        roles = Object.entries(map).filter(([, fns]) => fns.includes(r.fn)).map(([role]) => role === "root" || role === "user" ? role : `${r.app}.${role}`);
+    }
+    if (!roles.length || holds("root") || roles.includes("user") || roles.some((x) => x !== "root" && holds(x)))
+        return { pass: true, roles };
+    return { pass: false, roles };
+}

package/dist/client/bundle.d.ts

@@ -0,0 +1,9 @@
+import type { CID } from "multiformats/cid";
+export declare const BUNDLE_LIMIT: number;
+export interface Rec {
+    cid: CID;
+    bytes: Uint8Array;
+}
+export declare function chunk(records: Iterable<Rec>, limit?: number, root?: CID): Generator<Uint8Array>;
+export declare function encodeBundle(records: Rec[], root?: CID): Uint8Array;
+export declare function decodeBundle(bytes: Uint8Array): Rec[];

package/dist/client/bundle.js

@@ -0,0 +1,34 @@
+// Records into ≤1 MiB dag-cbor bundles: { records: [{ cid, bytes }], root? }; `root`
+// (the imported tree) rides on the last bundle only. A record
+// that alone exceeds the limit travels alone in an oversized bundle (the
+// messagebox takes up to its body limit; 1sat serve: 30 MB of JSON).
+import * as dagCbor from "@ipld/dag-cbor";
+export const BUNDLE_LIMIT = 1 << 20;
+// dag-cbor overhead per record: map header, two keys, a tag-42 CID (<=~45 bytes) and a byte-string header.
+const PER_RECORD = 64;
+const HEADER = 16;
+export function* chunk(records, limit = BUNDLE_LIMIT, root) {
+    let batch = [];
+    let size = HEADER;
+    for (const r of records) {
+        const n = r.bytes.length + PER_RECORD;
+        if (batch.length && size + n > limit) {
+            yield encodeBundle(batch);
+            batch = [];
+            size = HEADER;
+        }
+        batch.push(r);
+        size += n;
+    }
+    if (batch.length)
+        yield encodeBundle(batch, root);
+}
+export function encodeBundle(records, root) {
+    return dagCbor.encode({ records: records.map((r) => ({ cid: r.cid, bytes: r.bytes })), ...(root && { root }) });
+}
+export function decodeBundle(bytes) {
+    const v = dagCbor.decode(bytes);
+    if (!v || !Array.isArray(v.records))
+        throw new Error("not a bundle");
+    return v.records;
+}

package/dist/client/cli.d.ts

@@ -0,0 +1,44 @@
+export type Command = {
+    cmd: "whoami";
+} | {
+    cmd: "import";
+    dir: string;
+} | {
+    cmd: "run";
+    tree?: string;
+    cwd?: string;
+    env?: Record<string, string>;
+    line: string;
+} | {
+    cmd: "head";
+    name: string;
+    tree: string;
+} | {
+    cmd: "inbox";
+    wait: boolean;
+    timeout: number;
+    ack: boolean;
+    json: boolean;
+} | {
+    cmd: "chat";
+    text: string;
+    tree?: string;
+    model?: string;
+    fresh: boolean;
+    wait: boolean;
+    timeout: number;
+} | {
+    cmd: "talk";
+    tree?: string;
+    model?: string;
+    fresh: boolean;
+    timeout: number;
+} | {
+    cmd: "help";
+};
+export declare const USAGE = "usage:\n  skein whoami\n  skein import <dir>\n  skein run [--tree <cid>] [--cwd <path>] [--env K=V]... -- '<cmd>'\n  skein head <name> <tree-cid>\n  skein inbox [--wait] [--timeout <seconds>] [--no-ack] [--json]\n  skein chat \"<text>\" [--tree <cid>] [--model <m>] [--new] [--wait] [--timeout <seconds>]\n  skein talk [--tree <cid>] [--model <m>] [--new] [--timeout <seconds>]\n  skein install|uninstall|routes|grant|peers|host|claim|deploy \u2026   the operator's admin messages, signed with its key\n                                                        and sent (skein install --help)";
+export declare const DEFAULT_TIMEOUT = 120;
+export declare function parseCli(argv: string[]): Command;
+/** A `chat` reply as text: the text line, the page (markdown, as is), then tree/thread. */
+export declare function formatReply(body: Record<string, unknown> | undefined): string;
+export declare function main(argv: string[]): Promise<number>;

package/dist/client/cli.js

@@ -0,0 +1,306 @@
+// skein — David's client. Signs as David through his wallet-api; raw BRC-33 on
+// a BRC-104 session (#40): sends to the instance's front door
+// (SKEIN_INSTANCE_URL, default $SKEIN_HOST_URL/@<handle>), reads David's
+// mailbox instance (SKEIN_MAILBOX_URL, ~/.skein/mailbox.url, default
+// $SKEIN_HOST_URL/@david). See scripts/host/README.md for the processes it expects.
+//
+//   skein whoami
+//   skein import <dir>
+//   skein run [--tree <cid>] [--cwd <path>] [--env K=V]... -- '<cmd>'
+//   skein head <name> <tree-cid>
+//   skein inbox [--wait] [--timeout <s>] [--no-ack] [--json]
+//   skein chat "<text>" [--tree <cid>] [--model <m>] [--new] [--wait] [--timeout <s>]
+//   skein talk [--tree <cid>] [--model <m>] [--new] [--timeout <s>]
+//   skein install|uninstall|routes|grant|peers|host|claim|deploy …   the operator's admin messages,
+//                                              signed here with the operator's key and sent (#142: src/client/admin-cli.ts)
+import { parseArgs } from "node:util";
+import { createInterface } from "node:readline/promises";
+import { loadConfig } from "./config.js";
+import { BOX, SkeinClient } from "./client.js";
+import { parseReplLine, parseReply, short } from "./conversation.js";
+export const USAGE = `usage:
+  skein whoami
+  skein import <dir>
+  skein run [--tree <cid>] [--cwd <path>] [--env K=V]... -- '<cmd>'
+  skein head <name> <tree-cid>
+  skein inbox [--wait] [--timeout <seconds>] [--no-ack] [--json]
+  skein chat "<text>" [--tree <cid>] [--model <m>] [--new] [--wait] [--timeout <seconds>]
+  skein talk [--tree <cid>] [--model <m>] [--new] [--timeout <seconds>]
+  skein install|uninstall|routes|grant|peers|host|claim|deploy …   the operator's admin messages, signed with its key
+                                                        and sent (skein install --help)`;
+export const DEFAULT_TIMEOUT = 120;
+function timeoutOf(cmd, v) {
+    const t = v === undefined ? DEFAULT_TIMEOUT : Number(v);
+    if (!Number.isFinite(t) || t <= 0)
+        throw new Error(`${cmd}: bad --timeout ${v}`);
+    return t;
+}
+const convOptions = { tree: { type: "string" }, model: { type: "string" }, new: { type: "boolean" }, timeout: { type: "string" } };
+export function parseCli(argv) {
+    const [sub, ...rest] = argv;
+    switch (sub) {
+        case undefined:
+        case "help":
+        case "-h":
+        case "--help":
+            return { cmd: "help" };
+        case "whoami":
+            parseArgs({ args: rest, options: {}, allowPositionals: false });
+            return { cmd: "whoami" };
+        case "import": {
+            const { positionals } = parseArgs({ args: rest, options: {}, allowPositionals: true });
+            if (positionals.length !== 1)
+                throw new Error("import: expected exactly one <dir>");
+            return { cmd: "import", dir: positionals[0] };
+        }
+        case "run": {
+            const dd = rest.indexOf("--");
+            if (dd < 0)
+                throw new Error("run: the command goes after `--`");
+            const line = rest.slice(dd + 1).join(" ");
+            if (!line.trim())
+                throw new Error("run: empty command");
+            const { values, positionals } = parseArgs({
+                args: rest.slice(0, dd),
+                options: { tree: { type: "string" }, cwd: { type: "string" }, env: { type: "string", multiple: true } },
+                allowPositionals: true,
+            });
+            if (positionals.length)
+                throw new Error(`run: unexpected ${positionals.join(" ")} (the command goes after \`--\`)`);
+            let env;
+            for (const kv of values.env ?? []) {
+                const i = kv.indexOf("=");
+                if (i <= 0)
+                    throw new Error(`run: --env wants K=V, got ${kv}`);
+                (env ??= {})[kv.slice(0, i)] = kv.slice(i + 1);
+            }
+            return { cmd: "run", line, ...(values.tree !== undefined && { tree: values.tree }), ...(values.cwd !== undefined && { cwd: values.cwd }), ...(env && { env }) };
+        }
+        case "head": {
+            const { positionals } = parseArgs({ args: rest, options: {}, allowPositionals: true });
+            if (positionals.length !== 2)
+                throw new Error("head: expected <name> <tree-cid>");
+            return { cmd: "head", name: positionals[0], tree: positionals[1] };
+        }
+        case "inbox": {
+            const { values } = parseArgs({
+                args: rest,
+                options: { wait: { type: "boolean" }, timeout: { type: "string" }, "no-ack": { type: "boolean" }, json: { type: "boolean" } },
+                allowPositionals: false,
+            });
+            return { cmd: "inbox", wait: !!values.wait, timeout: timeoutOf("inbox", values.timeout), ack: !values["no-ack"], json: !!values.json };
+        }
+        case "chat": {
+            const { values, positionals } = parseArgs({ args: rest, options: { ...convOptions, wait: { type: "boolean" } }, allowPositionals: true });
+            const text = positionals.join(" ");
+            if (!text.trim())
+                throw new Error('chat: expected "<text>"');
+            return {
+                cmd: "chat", text, fresh: !!values.new, wait: !!values.wait, timeout: timeoutOf("chat", values.timeout),
+                ...(values.tree !== undefined && { tree: values.tree }), ...(values.model !== undefined && { model: values.model }),
+            };
+        }
+        case "talk": {
+            const { values } = parseArgs({ args: rest, options: convOptions, allowPositionals: false });
+            return {
+                cmd: "talk", fresh: !!values.new, timeout: timeoutOf("talk", values.timeout),
+                ...(values.tree !== undefined && { tree: values.tree }), ...(values.model !== undefined && { model: values.model }),
+            };
+        }
+        default:
+            throw new Error(`unknown command: ${sub}`);
+    }
+}
+// ---------------------------------------------------------------- printing
+function text(v) {
+    if (v instanceof Uint8Array)
+        return new TextDecoder().decode(v);
+    return v === undefined || v === null ? "" : String(v);
+}
+/** A `chat` reply as text: the text line, the page (markdown, as is), then tree/thread. */
+export function formatReply(body) {
+    const s = parseReply(body);
+    const out = [s.text];
+    if (s.page)
+        out.push("", s.page.replace(/\s+$/, ""), "");
+    const ids = [s.tree && `tree ${short(s.tree.toString())}`, s.thread && `thread ${short(s.thread.toString())}`].filter(Boolean);
+    if (ids.length)
+        out.push(`  [${ids.join("  ")}]`);
+    return out.join("\n");
+}
+function show(r, json) {
+    if (json) {
+        console.log(JSON.stringify(r, (_k, v) => (v instanceof Uint8Array ? text(v) : v)));
+        return;
+    }
+    const b = r.body ?? {};
+    console.log(`— ${r.box} ${r.created ?? "?"} from ${r.sender.slice(0, 16)}… ${r.verified ? "verified" : "UNVERIFIED"} msg ${r.messageId.slice(0, 12)}`);
+    if (r.error) {
+        console.log(`  error: ${r.error}`);
+        return;
+    }
+    if (r.box === BOX.chat && b.replyTo !== undefined) {
+        try {
+            console.log(formatReply(b));
+            return;
+        }
+        catch (e) {
+            console.log(`  malformed reply: ${e.message}`);
+        }
+    }
+    if (r.box === BOX.chat && typeof b.text === "string") {
+        console.log(`  (new conversation) ${b.text}`);
+        return;
+    }
+    if (b.replyTo !== undefined)
+        console.log(`  replyTo:  ${text(b.replyTo)}`);
+    if (b.exitCode !== undefined)
+        console.log(`  exitCode: ${text(b.exitCode)}`);
+    if (b.tree !== undefined)
+        console.log(`  tree:     ${text(b.tree)}`);
+    for (const k of ["stdout", "stderr"]) {
+        const s = text(b[k]);
+        if (s)
+            console.log(`  ${k}:\n${s.replace(/^/gm, "    ").replace(/\s+$/, "")}`);
+    }
+    const other = Object.keys(b).filter((k) => !["replyTo", "exitCode", "tree", "stdout", "stderr"].includes(k));
+    for (const k of other)
+        console.log(`  ${k}: ${JSON.stringify(b[k], (_k, v) => (v instanceof Uint8Array ? text(v) : v))}`);
+}
+// ---------------------------------------------------------------- main
+export async function main(argv) {
+    // #142: the operator's admin messages, signed in this process with its key (host.env configures where it is).
+    const { ADMIN_COMMANDS, ADMIN_USAGE, adminMain } = await import("./admin-cli.js");
+    if (ADMIN_COMMANDS.includes(argv[0] ?? "")) {
+        const { withHostEnv } = await import("../host/hostenv.js");
+        const env = { vars: withHostEnv(process.env), out: (l) => process.stdout.write(`${l}\n`), err: (l) => process.stderr.write(`${l}\n`) };
+        if (argv.includes("--help") || argv.includes("-h")) {
+            env.out(ADMIN_USAGE);
+            return 0;
+        }
+        return adminMain(argv[0], argv.slice(1), env);
+    }
+    const c = parseCli(argv);
+    if (c.cmd === "help") {
+        console.log(USAGE);
+        return 0;
+    }
+    const cfg = loadConfig();
+    const client = new SkeinClient(cfg);
+    switch (c.cmd) {
+        case "whoami": {
+            console.log(`owner (you):  ${await client.identityKey()}  via ${cfg.walletUrl} as ${cfg.originator}`);
+            console.log(`instance:     ${cfg.instance.identityKey}  ${cfg.instance.handle}@${cfg.instance.domain}`);
+            console.log(`instance url: ${cfg.instanceUrl}`);
+            console.log(`mailbox:      ${cfg.mailboxUrl}`);
+            return 0;
+        }
+        case "import": {
+            const r = await client.importDir(c.dir, (i, n, bytes) => process.stderr.write(`bundle ${i + 1}/${n} (${bytes} bytes)\n`));
+            process.stderr.write(`${r.records} objects in ${r.bundles.length} message(s) to box objects\n`);
+            console.log(r.root.toString());
+            return 0;
+        }
+        case "run": {
+            const s = await client.run({ tree: c.tree, cmd: c.line, cwd: c.cwd, env: c.env });
+            console.log(s.cid);
+            return 0;
+        }
+        case "head": {
+            const s = await client.head(c.name, c.tree);
+            console.log(s.cid);
+            return 0;
+        }
+        case "inbox": {
+            if (!c.wait) {
+                for (const r of await client.inbox({ ack: c.ack }))
+                    show(r, c.json);
+                return 0;
+            }
+            const want = [];
+            const chat = client.lastSent(BOX.chat), run = client.lastSent(BOX.run);
+            if (chat)
+                want.push({ box: BOX.chat, replyTo: chat.cid });
+            if (run)
+                want.push({ box: BOX.results, replyTo: run.cid });
+            if (!want.length)
+                throw new Error("inbox --wait: no chat or run sent from this machine yet (~/.skein/client/sent.jsonl)");
+            return wait(client, want, c.timeout, (r) => show(r, c.json), c.ack);
+        }
+        case "chat": {
+            const s = await client.chat(c);
+            if (!c.wait) {
+                console.log(s.cid);
+                return 0;
+            }
+            process.stderr.write(`sent ${short(s.cid)}${s.replyTo ? ` (reply to ${short(s.replyTo)})` : " (new conversation)"}\n`);
+            return wait(client, [{ box: BOX.chat, replyTo: s.cid }], c.timeout, (r) => show(r, false));
+        }
+        case "talk":
+            return talk(client, c);
+    }
+}
+async function wait(client, want, timeout, onResult, ack = true) {
+    const hit = await client.waitFor(want, { timeoutMs: timeout * 1000, ack, onResult });
+    if (hit)
+        return 0;
+    console.error(`no answer to ${want.map((w) => `${w.box}←${short(w.replyTo)}`).join(" or ")} within ${timeout}s`);
+    return 1;
+}
+/** The REPL: each line is a chat continuing the last reply; waits for the reply to it. */
+async function talk(client, c) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    let fresh = c.fresh, tree = c.tree;
+    console.log("talk: /new, /tree <cid>, /quit");
+    try {
+        for (;;) {
+            let line;
+            try {
+                line = await rl.question("> ");
+            }
+            catch {
+                return 0;
+            } // stdin closed
+            const cmd = parseReplLine(line);
+            switch (cmd.kind) {
+                case "empty": continue;
+                case "quit": return 0;
+                case "error":
+                    console.log(cmd.message);
+                    continue;
+                case "new":
+                    fresh = true;
+                    tree = undefined;
+                    console.log("(new conversation)");
+                    continue;
+                case "tree":
+                    tree = cmd.cid;
+                    console.log(`(tree ${short(cmd.cid)} for the next message)`);
+                    continue;
+                case "chat": {
+                    const s = await client.chat({ text: cmd.text, fresh, tree, model: c.model });
+                    fresh = false;
+                    tree = undefined; // after this, the reply's tree carries the conversation
+                    const hit = await client.waitFor([{ box: BOX.chat, replyTo: s.cid }], {
+                        timeoutMs: c.timeout * 1000,
+                        onResult: (r) => { if (r.box === BOX.chat && String(r.body?.replyTo) === s.cid && !r.error)
+                            console.log(formatReply(r.body));
+                        else
+                            show(r, false); },
+                    });
+                    if (!hit)
+                        console.log(`(no answer within ${c.timeout}s; \`skein inbox\` picks it up later)`);
+                }
+            }
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+if (import.meta.main) {
+    main(process.argv.slice(2)).then((code) => process.exit(code), (e) => {
+        console.error(`skein: ${e.message}`);
+        process.exit(1);
+    });
+}