@dcasegr/skein 0.0.0-stage → 0.1.2

package/dist/client/client.d.ts

@@ -0,0 +1,161 @@
+import { CID } from "multiformats/cid";
+import { type WalletInterface } from "../wallet.ts";
+import { type ScanOptions } from "../dev/scan.ts";
+import { type Rec } from "./bundle.ts";
+import type { ClientConfig } from "./config.ts";
+import { RawBox } from "./raw.ts";
+import { type Conversation } from "./conversation.ts";
+export declare const BOX: {
+    readonly objects: "objects";
+    readonly run: "shell/run";
+    readonly head: "head";
+    readonly dispatch: "dispatch";
+    readonly results: "results";
+    readonly chat: "chat";
+};
+/** The boxes David reads, in this order: `run` results, then `chat` (the instance's replies, and chats from others). */
+export declare const INBOX: readonly ["results", "chat"];
+/** A dispatch table change for a mailbox row: (sender — anyone when absent, else an identity key in hex —, box) → handler. */
+export interface DispatchArgs {
+    op: "add" | "remove"; /** gone (#143): refused */
+    sender?: string;
+    box: string;
+    handler: string;
+    fn?: string;
+}
+/**
+ * A handler: a program record's CID, or the name of one in `programs` (an
+ * instance's genesis `programs`: name → record CID, as skein-host reads it
+ * from the store; the client has no store, so it takes CIDs).
+ */
+export declare function handlerCid(s: string, programs?: Record<string, CID>): CID;
+/**
+ * The kernel's `dispatch` operation's body (box `dispatch`, from root):
+ * {op, row} with row a mailbox route {transport, address: box, program, fn?};
+ * a handler named from `programs` (handlerCid). No sender (#143: a route has
+ * none — roles gate functions, granted by root).
+ */
+export declare function dispatchBody(a: DispatchArgs, programs?: Record<string, CID>): {
+    op: "add" | "remove";
+    row: Record<string, unknown>;
+};
+/** A directory as git objects held in memory: [root, records]. `opts.ignore` as scan's. */
+export declare function hashDir(dir: string, opts?: ScanOptions): Promise<{
+    root: CID;
+    records: Rec[];
+}>;
+/**
+ * A directory as the `objects` box takes it: ≤ 1 MiB bundles, blobs before
+ * trees and the root tree last, so a receiver storing in order never holds a
+ * tree whose children have not arrived yet; the last bundle names the root.
+ * `skip` drops records the receiver already has; if it has the root tree it
+ * has everything (trees arrive after their children), and nothing is sent.
+ */
+export declare function dirBundles(dir: string, o?: ScanOptions & {
+    limit?: number;
+    skip?: (cid: CID) => Promise<boolean>;
+}): Promise<{
+    root: CID;
+    records: number;
+    bundles: Uint8Array[];
+}>;
+/** dirBundles for records already in hand (every object of the tree `root`). */
+export declare function recordBundles(root: CID, all: Rec[], o?: {
+    limit?: number;
+    skip?: (cid: CID) => Promise<boolean>;
+}): Promise<{
+    root: CID;
+    records: number;
+    bundles: Uint8Array[];
+}>;
+export interface Sent {
+    cid: string;
+    box: string;
+    messageId: string;
+    at: string;
+    tree?: string;
+    cmd?: string;
+    text?: string;
+    replyTo?: string;
+}
+export interface Result {
+    box: string;
+    messageId: string;
+    /** The message's id as a CID (the instance's `chat` reply's is the next chat's replyTo). */
+    cid?: string;
+    sender: string;
+    /** Always true: the sender is the BRC-104 session's identity, which the mailbox checked. */
+    verified: boolean;
+    created?: string;
+    body?: Record<string, unknown>;
+    error?: string;
+}
+/** A verified `chat` from the instance that is a reply (`replyTo` set): what the next chat continues from. */
+export declare function isInstanceReply(r: Result, instance: string): boolean;
+export declare class SkeinClient {
+    readonly cfg: ClientConfig;
+    readonly wallet: WalletInterface;
+    /** The instance's front door. */
+    readonly toInstance: RawBox;
+    /** David's mailbox (instance). */
+    readonly mailbox: RawBox;
+    constructor(cfg: ClientConfig, wallet?: WalletInterface, o?: {
+        fetch?: typeof fetch;
+    });
+    identityKey(): Promise<string>;
+    /** Send `body` (dag-cbor encoded here) to the instance's `box`. */
+    send(box: string, body: unknown, note?: Partial<Sent>): Promise<Sent>;
+    importDir(dir: string, onBundle?: (i: number, n: number, bytes: number) => void): Promise<{
+        root: CID;
+        records: number;
+        bundles: Sent[];
+    }>;
+    /** Send already-encoded body bytes (dag-cbor) to the instance's `box`: its front door's sendMessage. */
+    sendBytes(box: string, body: Uint8Array, note?: Partial<Sent>): Promise<Sent>;
+    /** Run a command (box `run`). No tree: the instance's `main` head, else the empty tree. */
+    run(args: {
+        tree?: string;
+        cmd: string;
+        cwd?: string;
+        env?: Record<string, string>;
+    }): Promise<Sent>;
+    /** Move a named head to a tree the instance holds (box `head`): "`name` is now `tree`". */
+    head(name: string, tree: string): Promise<Sent>;
+    /** Change the instance's dispatch table (box `dispatch`, a kernel operation): add or remove the mailbox row (sender, box) → handler. No reply. */
+    dispatch(a: DispatchArgs): Promise<Sent>;
+    /**
+     * Chat with the instance (box `chat`). Continues the conversation in
+     * conversation.json (replyTo = the instance's last reply, tree defaults to its tree)
+     * unless `fresh`.
+     */
+    chat(args: {
+        text: string;
+        tree?: string;
+        model?: string;
+        fresh?: boolean;
+    }): Promise<Sent>;
+    conversation(): Conversation | undefined;
+    /**
+     * Read (and by default acknowledge) David's boxes, `results` then `chat`.
+     * The newest well-formed, verified `chat` reply from the instance becomes
+     * the conversation state.
+     */
+    inbox(opts?: {
+        ack?: boolean;
+    }): Promise<Result[]>;
+    /**
+     * Poll the inbox every `intervalMs` until a message in one of `want`'s boxes
+     * answers (replyTo) the paired CID; every message read goes to `onResult`.
+     * Resolves the matching result, or undefined at the deadline.
+     */
+    waitFor(want: {
+        box: string;
+        replyTo: string;
+    }[], opts: {
+        timeoutMs: number;
+        intervalMs?: number;
+        ack?: boolean;
+        onResult?: (r: Result) => void;
+    }): Promise<Result | undefined>;
+    lastSent(box?: string): Sent | undefined;
+}

package/dist/client/client.js

@@ -0,0 +1,237 @@
+// David's client: a peer that signs as David through his wallet-api (docs/ARCH.md
+// "Everything outside is a peer"; docs/MESSAGES.md). It speaks raw BRC-33 on a
+// BRC-104 session (#40, raw.ts): a message is sent to the instance's own front
+// door (its URL: the instance is an HTTP server), and David's boxes are read
+// from his mailbox — the mailbox instance the instance delivers to (the one
+// peer its genesis names, etc/config.json `owner.messagebox`). No envelope: the
+// session proves who sends; a message's id is its record's CID, which a reply's
+// `replyTo` names.
+import { appendFileSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import * as dagCbor from "@ipld/dag-cbor";
+import { CID } from "multiformats/cid";
+import { remoteWallet } from "../wallet.js";
+import { scan } from "../dev/scan.js";
+import { chunk } from "./bundle.js";
+import { RawBox } from "./raw.js";
+import { chatBody, conversationFrom, loadConversation, parseReply, saveConversation } from "./conversation.js";
+export const BOX = { objects: "objects", run: "shell/run", head: "head", dispatch: "dispatch", results: "results", chat: "chat" };
+/** The boxes David reads, in this order: `run` results, then `chat` (the instance's replies, and chats from others). */
+export const INBOX = [BOX.results, BOX.chat];
+/**
+ * A handler: a program record's CID, or the name of one in `programs` (an
+ * instance's genesis `programs`: name → record CID, as skein-host reads it
+ * from the store; the client has no store, so it takes CIDs).
+ */
+export function handlerCid(s, programs = {}) {
+    const named = programs[s];
+    if (named)
+        return named;
+    try {
+        return CID.parse(s);
+    }
+    catch {
+        const names = Object.keys(programs);
+        throw new Error(`handler ${JSON.stringify(s)}: not a CID${names.length ? ` or a program name (${names.join(", ")})` : " (a program by name needs the instance's genesis: skein routes --instance or an origin)"}`);
+    }
+}
+/**
+ * The kernel's `dispatch` operation's body (box `dispatch`, from root):
+ * {op, row} with row a mailbox route {transport, address: box, program, fn?};
+ * a handler named from `programs` (handlerCid). No sender (#143: a route has
+ * none — roles gate functions, granted by root).
+ */
+export function dispatchBody(a, programs = {}) {
+    if (a.sender !== undefined)
+        throw new Error("sender: gone (#143) — a route has no sender; gate the function with a role and grant it (skein grant)");
+    return { op: a.op, row: { transport: "mailbox", address: a.box, program: handlerCid(a.handler, programs), ...(a.fn ? { fn: a.fn } : {}) } };
+}
+/** A directory as git objects held in memory: [root, records]. `opts.ignore` as scan's. */
+export async function hashDir(dir, opts = {}) {
+    const m = new Map();
+    const blocks = {
+        has: async (cid) => m.has(cid.toString()),
+        bytes: async (cid) => { const r = m.get(cid.toString()); if (!r)
+            throw new Error(`missing ${cid}`); return r.bytes; },
+        putBlock: async (cid, bytes) => { m.set(cid.toString(), { cid, bytes }); },
+    };
+    const root = await scan(blocks, dir, opts);
+    return { root, records: [...m.values()] };
+}
+/**
+ * A directory as the `objects` box takes it: ≤ 1 MiB bundles, blobs before
+ * trees and the root tree last, so a receiver storing in order never holds a
+ * tree whose children have not arrived yet; the last bundle names the root.
+ * `skip` drops records the receiver already has; if it has the root tree it
+ * has everything (trees arrive after their children), and nothing is sent.
+ */
+export async function dirBundles(dir, o = {}) {
+    const { root, records: all } = await hashDir(dir, o);
+    return recordBundles(root, all, o);
+}
+/** dirBundles for records already in hand (every object of the tree `root`). */
+export async function recordBundles(root, all, o = {}) {
+    const rootKey = root.toString();
+    const records = [];
+    if (!(await o.skip?.(root)))
+        for (const r of all)
+            if (r.cid.toString() === rootKey || !(await o.skip?.(r.cid)))
+                records.push(r);
+    const rank = (r) => (r.cid.toString() === rootKey ? 2 : new TextDecoder().decode(r.bytes.subarray(0, 5)) === "tree " ? 1 : 0);
+    records.sort((a, b) => rank(a) - rank(b));
+    return { root, records: records.length, bundles: [...chunk(records, o.limit, root)] };
+}
+/** A verified `chat` from the instance that is a reply (`replyTo` set): what the next chat continues from. */
+export function isInstanceReply(r, instance) {
+    return r.box === BOX.chat && !r.error && !!r.cid && r.sender === instance && r.body?.replyTo !== undefined;
+}
+export class SkeinClient {
+    cfg;
+    wallet;
+    /** The instance's front door. */
+    toInstance;
+    /** David's mailbox (instance). */
+    mailbox;
+    constructor(cfg, wallet, o = {}) {
+        this.cfg = cfg;
+        this.wallet = wallet ?? remoteWallet(cfg.walletUrl, cfg.originator);
+        this.toInstance = new RawBox(this.wallet, cfg.instanceUrl, { originator: cfg.originator, fetch: o.fetch });
+        this.mailbox = new RawBox(this.wallet, cfg.mailboxUrl, { originator: cfg.originator, fetch: o.fetch });
+    }
+    async identityKey() {
+        return (await this.wallet.getPublicKey({ identityKey: true })).publicKey;
+    }
+    /** Send `body` (dag-cbor encoded here) to the instance's `box`. */
+    send(box, body, note = {}) {
+        return this.sendBytes(box, dagCbor.encode(body), note);
+    }
+    async importDir(dir, onBundle) {
+        const { root, records, bundles } = await dirBundles(dir);
+        const rootKey = root.toString();
+        const sent = [];
+        for (const [i, bytes] of bundles.entries()) {
+            onBundle?.(i, bundles.length, bytes.length);
+            // The bundle is already dag-cbor; send it as the body bytes, not re-wrapped.
+            sent.push(await this.sendBytes(BOX.objects, bytes, { tree: rootKey }));
+        }
+        return { root, records, bundles: sent };
+    }
+    /** Send already-encoded body bytes (dag-cbor) to the instance's `box`: its front door's sendMessage. */
+    async sendBytes(box, body, note = {}) {
+        const { id } = await this.toInstance.send(this.cfg.instance.identityKey, box, body);
+        const cid = id.toString();
+        const sent = { cid, box, messageId: cid, at: new Date().toISOString(), ...note };
+        mkdirSync(this.cfg.stateDir, { recursive: true });
+        appendFileSync(join(this.cfg.stateDir, "sent.jsonl"), JSON.stringify(sent) + "\n");
+        return sent;
+    }
+    /** Run a command (box `run`). No tree: the instance's `main` head, else the empty tree. */
+    async run(args) {
+        const body = { cmd: args.cmd };
+        if (args.tree !== undefined)
+            body.tree = CID.parse(args.tree);
+        if (args.cwd !== undefined)
+            body.cwd = args.cwd;
+        if (args.env !== undefined)
+            body.env = args.env;
+        return this.send(BOX.run, body, { tree: args.tree, cmd: args.cmd });
+    }
+    /** Move a named head to a tree the instance holds (box `head`): "`name` is now `tree`". */
+    head(name, tree) {
+        return this.send(BOX.head, { name, tree: CID.parse(tree) }, { tree });
+    }
+    /** Change the instance's dispatch table (box `dispatch`, a kernel operation): add or remove the mailbox row (sender, box) → handler. No reply. */
+    dispatch(a) {
+        return this.send(BOX.dispatch, dispatchBody(a));
+    }
+    /**
+     * Chat with the instance (box `chat`). Continues the conversation in
+     * conversation.json (replyTo = the instance's last reply, tree defaults to its tree)
+     * unless `fresh`.
+     */
+    chat(args) {
+        const body = chatBody(args, this.conversation());
+        return this.send(BOX.chat, body, {
+            text: args.text,
+            ...(body.tree && { tree: body.tree.toString() }),
+            ...(body.replyTo && { replyTo: body.replyTo.toString() }),
+        });
+    }
+    conversation() {
+        return loadConversation(this.cfg.stateDir);
+    }
+    /**
+     * Read (and by default acknowledge) David's boxes, `results` then `chat`.
+     * The newest well-formed, verified `chat` reply from the instance becomes
+     * the conversation state.
+     */
+    async inbox(opts = {}) {
+        const out = [];
+        for (const box of INBOX) {
+            const msgs = await this.mailbox.list(box);
+            for (const m of msgs) {
+                const r = { box, messageId: m.messageId, cid: m.messageId, sender: m.sender, verified: true };
+                if (m.value && typeof m.value === "object" && !Array.isArray(m.value) && !(m.value instanceof Uint8Array))
+                    r.body = m.value;
+                else
+                    r.error = "the body is not a record";
+                out.push(r);
+            }
+            if ((opts.ack ?? true) && msgs.length)
+                await this.mailbox.ack(msgs.map((m) => m.messageId));
+        }
+        const prev = this.conversation();
+        let newest;
+        for (const r of out) {
+            if (!isInstanceReply(r, this.cfg.instance.identityKey))
+                continue;
+            try {
+                const c = conversationFrom(r.cid, parseReply(r.body), r.created, newest ?? prev);
+                if (!newest || c.at >= newest.at)
+                    newest = c;
+            }
+            catch (e) {
+                r.error = e.message;
+            }
+        }
+        if (newest)
+            saveConversation(this.cfg.stateDir, newest);
+        return out;
+    }
+    /**
+     * Poll the inbox every `intervalMs` until a message in one of `want`'s boxes
+     * answers (replyTo) the paired CID; every message read goes to `onResult`.
+     * Resolves the matching result, or undefined at the deadline.
+     */
+    async waitFor(want, opts) {
+        const deadline = Date.now() + opts.timeoutMs;
+        for (;;) {
+            let hit;
+            for (const r of await this.inbox({ ack: opts.ack })) {
+                opts.onResult?.(r);
+                if (!hit && r.body && want.some((w) => w.box === r.box && String(r.body.replyTo) === w.replyTo))
+                    hit = r;
+            }
+            if (hit)
+                return hit;
+            if (Date.now() > deadline)
+                return undefined;
+            await new Promise((res) => setTimeout(res, opts.intervalMs ?? 1000));
+        }
+    }
+    lastSent(box) {
+        let lines;
+        try {
+            lines = readFileSync(join(this.cfg.stateDir, "sent.jsonl"), "utf8").trim().split("\n");
+        }
+        catch {
+            return undefined;
+        }
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const s = JSON.parse(lines[i]);
+            if (!box || s.box === box)
+                return s;
+        }
+        return undefined;
+    }
+}

package/dist/client/config.d.ts

@@ -0,0 +1,18 @@
+export interface ClientConfig {
+    home: string;
+    /** Owner (David) wallet-api: `1sat serve wallet-api` on its own port. */
+    walletUrl: string;
+    originator: string;
+    /** The instance's own URL (its front door): http://<handle>.localhost:8100 or http://127.0.0.1:8100/@<handle>. */
+    instanceUrl: string;
+    /** David's mailbox: the mailbox instance his instances deliver to (#40). */
+    mailboxUrl: string;
+    instance: {
+        identityKey: string;
+        handle: string;
+        domain: string;
+    };
+    /** Local client state: sent envelope cids. */
+    stateDir: string;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): ClientConfig;

package/dist/client/config.js

@@ -0,0 +1,31 @@
+// Where the client finds things on David's machine. Everything is a file under
+// ~/.skein (or $SKEIN_HOME) written by scripts/host/*.sh; env vars override.
+// No key is ever read here: the client signs through the owner's wallet-api.
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+function read(file) {
+    try {
+        return readFileSync(file, "utf8").trim() || undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function loadConfig(env = process.env) {
+    const home = env.SKEIN_HOME ?? join(homedir(), ".skein");
+    const identityKey = env.SKEIN_INSTANCE_IDENTITY ?? read(join(home, "instance.identity"));
+    if (!identityKey)
+        throw new Error(`no instance identity: write \`skein-host identity <handle>\` to ${join(home, "instance.identity")}, or set SKEIN_INSTANCE_IDENTITY`);
+    const [handle, domain] = (env.SKEIN_INSTANCE_HANDLE ?? "skein@localhost").split("@");
+    const host = (env.SKEIN_HOST_URL ?? "http://127.0.0.1:8100").replace(/\/+$/, "");
+    return {
+        home,
+        walletUrl: env.SKEIN_OWNER_WALLET ?? "http://127.0.0.1:3322",
+        originator: env.SKEIN_ORIGINATOR ?? "skein-client",
+        instanceUrl: env.SKEIN_INSTANCE_URL ?? `${host}/@${handle}`,
+        mailboxUrl: env.SKEIN_MAILBOX_URL ?? read(join(home, "mailbox.url")) ?? `${host}/@${env.SKEIN_MAILBOX_HANDLE ?? "david"}`,
+        instance: { identityKey, handle: handle, domain: domain ?? "localhost" },
+        stateDir: join(home, "client"),
+    };
+}

package/dist/client/conversation.d.ts

@@ -0,0 +1,62 @@
+import { CID } from "multiformats/cid";
+export interface Conversation {
+    /** CID of the last `chat` reply received from the instance. */
+    reply: string;
+    thread?: string;
+    tree?: string;
+    at: string;
+}
+export interface ChatBody {
+    text: string;
+    tree?: CID;
+    model?: string;
+    replyTo?: CID;
+}
+/** The instance's `chat` reply: its answer at the end of a turn names its tree and thread; a mid-turn message to David may not. */
+export interface ReplyBody {
+    text: string;
+    page?: string;
+    tree?: CID;
+    thread?: CID;
+    replyTo: CID;
+}
+export declare const conversationFile: (stateDir: string) => string;
+export declare function loadConversation(stateDir: string): Conversation | undefined;
+/** A stored conversation, or undefined. Takes the older `say` field for `reply`. */
+export declare function asConversation(x: unknown): Conversation | undefined;
+export declare function saveConversation(stateDir: string, c: Conversation): void;
+/**
+ * The `chat` body. Continuing (a conversation exists and not `fresh`): replyTo
+ * is the last reply, and the tree defaults to that reply's tree. New: neither.
+ */
+export declare function chatBody(opts: {
+    text: string;
+    tree?: string;
+    model?: string;
+    fresh?: boolean;
+}, conv?: Conversation): ChatBody;
+/** Check a decoded `chat` reply body; throws on a malformed one (or a chat that is not a reply). */
+export declare function parseReply(body: Record<string, unknown> | undefined): ReplyBody;
+/**
+ * Conversation state after receiving the reply envelope `cid`. A reply that
+ * names no tree (a message mid-turn) keeps the tree of `prev`, the state before.
+ */
+export declare function conversationFrom(cid: string, r: ReplyBody, at?: string, prev?: Conversation): Conversation;
+export declare const short: (cid: string) => string;
+export type ReplCmd = {
+    kind: "chat";
+    text: string;
+} | {
+    kind: "new";
+} | {
+    kind: "tree";
+    cid: string;
+} | {
+    kind: "quit";
+} | {
+    kind: "empty";
+} | {
+    kind: "error";
+    message: string;
+};
+export declare function parseReplLine(line: string): ReplCmd;

package/dist/client/conversation.js

@@ -0,0 +1,113 @@
+// Chat state on David's machine: the last `chat` reply the instance sent
+// (~/.skein/client/conversation.json). `chat` continues from it by setting
+// `replyTo` to that envelope's CID; `--new` (or no file) starts a fresh
+// conversation. Both directions are box `chat`: David's chat to the instance,
+// the instance's reply (`replyTo` set) to David (see src/client/README.md).
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CID } from "multiformats/cid";
+export const conversationFile = (stateDir) => join(stateDir, "conversation.json");
+export function loadConversation(stateDir) {
+    try {
+        return asConversation(JSON.parse(readFileSync(conversationFile(stateDir), "utf8")));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A stored conversation, or undefined. Takes the older `say` field for `reply`. */
+export function asConversation(x) {
+    const c = x;
+    if (!c || typeof c !== "object")
+        return undefined;
+    const reply = typeof c.reply === "string" ? c.reply : typeof c.say === "string" ? c.say : undefined;
+    if (reply === undefined)
+        return undefined;
+    const { say: _, ...rest } = c;
+    return { ...rest, reply, at: typeof c.at === "string" ? c.at : "" };
+}
+export function saveConversation(stateDir, c) {
+    mkdirSync(stateDir, { recursive: true });
+    writeFileSync(conversationFile(stateDir), JSON.stringify(c, null, 2) + "\n");
+}
+/**
+ * The `chat` body. Continuing (a conversation exists and not `fresh`): replyTo
+ * is the last reply, and the tree defaults to that reply's tree. New: neither.
+ */
+export function chatBody(opts, conv) {
+    if (!opts.text.trim())
+        throw new Error("chat: empty text");
+    const b = { text: opts.text };
+    const cont = !opts.fresh && conv ? conv : undefined;
+    const tree = opts.tree ?? cont?.tree;
+    if (tree !== undefined)
+        b.tree = CID.parse(tree);
+    if (opts.model !== undefined)
+        b.model = opts.model;
+    if (cont)
+        b.replyTo = CID.parse(cont.reply);
+    return b;
+}
+const cidOf = (v) => CID.asCID(v) ?? undefined;
+/** Check a decoded `chat` reply body; throws on a malformed one (or a chat that is not a reply). */
+export function parseReply(body) {
+    if (!body || typeof body.text !== "string")
+        throw new Error("chat: no text");
+    const replyTo = cidOf(body.replyTo);
+    if (!replyTo)
+        throw new Error("chat: not a reply (replyTo is not a CID)");
+    const s = { text: body.text, replyTo };
+    if (body.thread !== undefined) {
+        const thread = cidOf(body.thread);
+        if (!thread)
+            throw new Error("chat: thread is not a CID");
+        s.thread = thread;
+    }
+    if (body.page !== undefined) {
+        if (typeof body.page !== "string")
+            throw new Error("chat: page is not a string");
+        s.page = body.page;
+    }
+    if (body.tree !== undefined) {
+        const tree = cidOf(body.tree);
+        if (!tree)
+            throw new Error("chat: tree is not a CID");
+        s.tree = tree;
+    }
+    return s;
+}
+/**
+ * Conversation state after receiving the reply envelope `cid`. A reply that
+ * names no tree (a message mid-turn) keeps the tree of `prev`, the state before.
+ */
+export function conversationFrom(cid, r, at = new Date().toISOString(), prev) {
+    const tree = r.tree?.toString() ?? prev?.tree;
+    const thread = r.thread?.toString() ?? prev?.thread;
+    return { reply: cid, ...(thread && { thread }), ...(tree && { tree }), at };
+}
+export const short = (cid) => (cid.length > 16 ? `${cid.slice(0, 6)}…${cid.slice(-6)}` : cid);
+export function parseReplLine(line) {
+    const t = line.trim();
+    if (!t)
+        return { kind: "empty" };
+    if (!t.startsWith("/"))
+        return { kind: "chat", text: t };
+    const [cmd, ...args] = t.split(/\s+/);
+    switch (cmd) {
+        case "/new": return args.length ? { kind: "error", message: "/new takes no arguments" } : { kind: "new" };
+        case "/quit":
+        case "/exit": return { kind: "quit" };
+        case "/tree": {
+            if (args.length !== 1)
+                return { kind: "error", message: "usage: /tree <cid>" };
+            try {
+                CID.parse(args[0]);
+            }
+            catch {
+                return { kind: "error", message: `not a CID: ${args[0]}` };
+            }
+            return { kind: "tree", cid: args[0] };
+        }
+        default: return { kind: "error", message: `unknown command ${cmd} (/new, /tree <cid>, /quit)` };
+    }
+}