@idleware/ringi 0.5.0 → 0.6.1

package/target/esm/{cli → clients/cli/agent}/session.js

@@ -1,10 +1,10 @@
-// Session interface: the operator's words become typed app requests.
-import * as Heartbeat from '../app/heartbeat.js';
-import * as Session from '../app/session.js';
-import { fail } from '../lib/index.js';
-import { opt, out } from './args.js';
-import { showInbox } from './agent.js';
-import { scopeLine, taskLine, waiting } from './shared.js';
+// session: what the operator says in an agent's chat (join, continue, stop, leave) becomes the session's requests.
+import * as Heartbeat from '../../../core/agents/heartbeat/pulse.js';
+import * as Session from '../../../core/agents/sessions/session.js';
+import { fail } from '../../../lib/index.js';
+import { opt, out } from '../args.js';
+import { showInbox } from './index.js';
+import { scopeLine, taskLine, waiting } from '../shared/index.js';
 export const briefing = (s) => {
     const r = Session.briefing(s);
     const auto = r.start.quorum !== null;

package/target/esm/clients/cli/arg-parse.js

@@ -0,0 +1,41 @@
+// Parse one option at a time, keeping positional arguments and repeated values in order.
+import { fail } from '../../lib/index.js';
+const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff', 'clear', 'published']);
+const MULTI = new Set(['m', 'attach', 'set', 'drop']);
+const SHORT = { m: 'm', F: 'file', n: 'n', o: 'out', h: 'help' };
+const option = (a) => {
+    if (a.startsWith('--')) {
+        const [key, val] = a.slice(2).split(/=(.*)/s);
+        return { key, val };
+    }
+    if (/^-[a-zA-Z]$/.test(a))
+        return { key: SHORT[a[1]] ?? fail(`unknown option ${a}`) };
+    return null;
+};
+const consume = (argv, o, i) => {
+    const parsed = option(argv[i]);
+    if (!parsed) {
+        o._.push(argv[i]);
+        return 1;
+    }
+    const { key, val } = parsed;
+    if (BOOLS.has(key)) {
+        o[key] = true;
+        return 1;
+    }
+    const value = val ?? argv[i + 1] ?? fail(`--${key} needs a value`);
+    o[key] = MULTI.has(key) ? [...(o[key] ?? []), value] : value;
+    return val === undefined ? 2 : 1;
+};
+export const parseArgs = (argv) => {
+    const o = { _: [] };
+    for (let i = 0; i < argv.length;) {
+        if (argv[i] === '--') {
+            o._.push(...argv.slice(i + 1));
+            break;
+        }
+        i += consume(argv, o, i);
+    }
+    return o;
+};
+//# sourceMappingURL=arg-parse.js.map

package/target/esm/{cli → clients/cli}/args.js

@@ -1,44 +1,11 @@
 // args: the command line: options, message text, files to attach, and printing to stdout.
 import fs from 'node:fs';
 import path from 'node:path';
-import { fail } from '../lib/index.js';
-import { checkPath } from '../app/room.js';
+import { checkPath } from '../../core/hub/usecases/room.js';
+import { fail } from '../../lib/index.js';
 export const out = (s = '') => { process.stdout.write(s.endsWith('\n') ? s : `${s}\n`); };
 export const dump = (v) => out(JSON.stringify(v, null, 2));
-const BOOLS = new Set(['task', 'peek', 'all', 'json', 'help', 'once', 'project', 'follow', 'short', 'yes', 'require-grant', 'md', 'archived', 'signed', 'repair', 'handoff', 'clear', 'published']);
-const MULTI = new Set(['m', 'attach', 'set', 'drop']);
-const SHORT = { m: 'm', F: 'file', n: 'n', o: 'out', h: 'help' };
-export const parseArgs = (argv) => {
-    const o = { _: [] };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        let key;
-        let val;
-        if (a === '--') {
-            o._.push(...argv.slice(i + 1));
-            break;
-        }
-        if (a.startsWith('--'))
-            [key, val] = a.slice(2).split(/=(.*)/s);
-        else if (/^-[a-zA-Z]$/.test(a))
-            key = SHORT[a[1]] ?? fail(`unknown option ${a}`);
-        else {
-            o._.push(a);
-            continue;
-        }
-        if (BOOLS.has(key)) {
-            o[key] = true;
-            continue;
-        }
-        if (val === undefined)
-            val = argv[++i] ?? fail(`--${key} needs a value`);
-        if (MULTI.has(key))
-            o[key] = [...(o[key] ?? []), val];
-        else
-            o[key] = val;
-    }
-    return o;
-};
+export { parseArgs } from './arg-parse.js';
 export const opt = (o, key) => typeof o[key] === 'string' ? o[key] : undefined;
 export const list = (o, key) => Array.isArray(o[key]) ? o[key] : [];
 export const flag = (o, key) => o[key] === true;

package/target/esm/clients/cli/commands.js

@@ -0,0 +1,45 @@
+// commands: one table for the one command line: the operator's commands (operator/), `ringi agent …` for an agent
+// (agent/), and the shared ones (shared/) under both; aliases kept together.
+import { about } from '../../core/hub/usecases/context.js';
+import { agent } from '../../core/agents/sessions/context.js';
+import { fail } from '../../lib/index.js';
+import { card, inbox, ping, take, wait, whoami } from './agent/index.js';
+import { flag, out, parseArgs } from './args.js';
+import { operatorCtx } from './context.js';
+import { helpMarkdown, helpText } from './help.js';
+import { forget, heartbeats, hub, pulse, roomCmd, sessions, where } from './operator/index.js';
+import { join, leave, resume, stop } from './agent/session.js';
+import { add, cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared/index.js';
+import { skill } from './skill/index.js';
+import { watchCommand } from './operator/watch.js';
+const SHARED = { add, send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
+const AGENT = { ...SHARED, inbox, whoami, status: whoami, card, ping, wait, take };
+const agentCommand = (_, rest) => {
+    const [sub = 'whoami', ...more] = rest;
+    const fn = AGENT[sub] ?? fail(`unknown: ringi agent ${sub}; see ringi help`);
+    return fn(agent(), parseArgs(more));
+};
+const version = () => {
+    const b = about();
+    out(`ringi ${b.version}; hub contract ${b.contract}; capabilities ${b.capabilities.join(' ')}`);
+};
+const help = (o) => flag(o, 'md') ? void process.stdout.write(helpMarkdown()) : out(helpText());
+const DIRECT = new Map([
+    ['--version', version], ['-v', version], ['version', version],
+    ['help', help], ['--help', help], ['-h', help], ['skill', skill], ['agent', agentCommand],
+    ['hub', hub], ['room', roomCmd], ['where', where], ['sessions', sessions], ['heartbeats', heartbeats],
+    ['pulse', pulse], ['forget', forget], ['watch', watchCommand], ['join', join], ['continue', resume], ['stop', stop], ['leave', leave]
+]);
+const unknown = (cmd) => {
+    if (['inbox', 'whoami', 'ping', 'wait', 'card'].includes(cmd))
+        fail(`${cmd} is an agent command: ringi agent ${cmd}`);
+    return fail(`unknown command ${cmd}; see ringi help`);
+};
+export const dispatch = (cmd, o, rest) => {
+    const direct = DIRECT.get(cmd);
+    if (direct)
+        return direct(o, rest);
+    const shared = SHARED[cmd] ?? unknown(cmd);
+    return shared(operatorCtx(o), o);
+};
+//# sourceMappingURL=commands.js.map

package/target/esm/clients/cli/context.js

@@ -0,0 +1,6 @@
+// context: who runs a command and in which room, from the command line.
+import * as Context from '../../core/hub/usecases/context.js';
+import { opt } from './args.js';
+export { isRef } from '../../core/hub/usecases/room.js';
+export const operatorCtx = (o) => Context.operator({ hub: opt(o, 'hub'), room: opt(o, 'room') });
+//# sourceMappingURL=context.js.map

package/target/esm/{cli/index.js → clients/cli/help.js}

@@ -1,15 +1,5 @@
-// ringi: a distributed agent coordinator (docs/spec/hub-1.md). This file is the command surface: what the operator, a session
-// and an agent may run, and how each command maps onto hubs, rooms, sessions and the watcher.
-import { about, agent } from '../app/context.js';
-import { fail, words } from '../lib/index.js';
-import { flag, opt, out, parseArgs } from './args.js';
-import { watch } from '../app/agent.js';
-import { card, inbox, ping, take, wait, whoami } from './agent.js';
-import { operatorCtx } from './context.js';
-import { forget, heartbeats, hub, pulse, roomCmd, sessions, where } from './operator.js';
-import { join, leave, resume, stop } from './session.js';
-import { add, cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
-import { skill } from './skill.js';
+// help: the command table — every command, who runs it and what it does — as text, and as COMMANDS.md.
+import { about } from '../../core/hub/usecases/context.js';
 // --- commands ---
 // [command, who runs it, what it does]: the one table behind `ringi help` and COMMANDS.md.
 export const TABLE = [
@@ -20,7 +10,6 @@ export const TABLE = [
     ['hub amend -m <subject> [--set <key>=<value>]... [--authority <file>] [--attach <file>:profiles/<name>.json]...', 'operator', 'refine the shared contract: version, capabilities, default profile, authority table, profiles'],
     ['room list [--archived]', 'operator', 'rooms of the current hub'],
     ['room create <id> [--profile <name>] [--quorum <agents>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room; --quorum: its work starts by itself once that many agents joined (1: at once)'],
-    ['room migrate <id>', 'operator', 'local hubs: join the old room branches without changing message ids or sessions'],
     ['room switch <id>', 'operator', 'change the terminal\'s current room; agents stay where they are'],
     ['room admit <agent> <public key|file>', 'operator', 'signed hubs: admit the key an agent made on its own machine'],
     ['room remove <agent>', 'operator', 'local hubs: take an agent out of the current room'],
@@ -55,7 +44,7 @@ export const TABLE = [
     ['agent tasks | log | read | thread | cat | get | who | signals | profile', 'agent', 'reading, as the joined agent'],
     ['agent ping <id> [-m <note>] [--next <s>] | agent wait [--max <s>] | agent card -m <text>', 'agent', 'heartbeats; hold the line only when the operator asks; who you are'],
 ];
-const helpText = () => {
+export const helpText = () => {
     const groups = [['operator', 'operator: in a terminal, in the current hub and room'], ['session', 'session: in a chat, on the operator\'s words'], ['agent', 'agent: during a turn, in the session\'s own room'], ['both', 'operator in a terminal, or an agent as ringi agent …']];
     const width = 56;
     const line = ([cmd, , what]) => cmd.length > width ? `  ringi ${cmd}\n  ${' '.repeat(width + 6)} ${what}` : `  ringi ${cmd.padEnd(width)} ${what}`;
@@ -68,66 +57,4 @@ export const helpMarkdown = () => ['# ringi commands', '',
     '| command | who | what |', '|---|---|---|',
     ...TABLE.map(([cmd, w, what]) => `| \`ringi ${cmd.replace(/\|/g, '\\|')}\` | ${w} | ${what} |`), '',
     'Message ids are store revisions (git: commit shas), any unique prefix of 4+ characters. States and roles come from the room\'s profile (`ringi profile`).', ''].join('\n');
-const SHARED = { add, send, reply, read, thread, tasks, log, cat, get, who, signals, profile: profileCmd, propose, stamp: stamp_, decide, proposals, grants };
-const AGENT = { ...SHARED, inbox, whoami, status: whoami, card, ping, wait, take };
-// A reader that stops early (`ringi log | head`) closes the pipe: that ends the output, not the command's work.
-const quietPipe = (e) => { if (e.code === 'EPIPE')
-    process.exit(process.exitCode ?? 0);
-else
-    throw e; };
-export const main = async (argv = process.argv.slice(2)) => {
-    if (!process.stdout.listeners('error').includes(quietPipe))
-        process.stdout.on('error', quietPipe);
-    const [cmd = 'help', ...rest] = argv;
-    const o = cmd === 'agent' ? { _: [] } : parseArgs(rest);
-    if (['--version', '-v', 'version'].includes(cmd)) {
-        const b = about();
-        return out(`ringi ${b.version}; hub contract ${b.contract}; capabilities ${b.capabilities.join(' ')}`);
-    }
-    if (['help', '--help', '-h'].includes(cmd))
-        return flag(o, 'md') ? void process.stdout.write(helpMarkdown()) : out(helpText());
-    if (cmd === 'skill')
-        return skill(o);
-    if (cmd === 'agent') {
-        const [sub = 'whoami', ...more] = rest;
-        const fn = AGENT[sub] ?? fail(`unknown: ringi agent ${sub}; see ringi help`);
-        return fn(agent(), parseArgs(more));
-    }
-    if (cmd === 'hub')
-        return hub(o);
-    if (cmd === 'room')
-        return roomCmd(o);
-    if (cmd === 'where')
-        return where(o);
-    if (cmd === 'sessions')
-        return sessions(o);
-    if (cmd === 'heartbeats')
-        return heartbeats(o);
-    if (cmd === 'pulse')
-        return pulse(o);
-    if (cmd === 'forget')
-        return forget(o);
-    if (cmd === 'watch') {
-        const num = (k) => opt(o, k) === undefined ? undefined : Number(opt(o, k));
-        process.exitCode = await watch({ seat: o._[0] ?? fail('usage: ringi watch <room>/<agent> --exec <cmd> [--scope <text>] [--once] [--require-grant] …'),
-            exec: opt(o, 'exec') ?? fail('--exec <cmd> is required: the command that starts a headless turn'),
-            hub: opt(o, 'hub'), scope: opt(o, 'scope'), once: flag(o, 'once'), requireGrant: flag(o, 'require-grant'), handoff: flag(o, 'handoff'),
-            interval: num('interval'), from: opt(o, 'from') ? words(opt(o, 'from')) : undefined, maxHop: num('max-hop'),
-            maxRuns: num('max-runs'), window: num('window') }, out);
-        return;
-    }
-    if (cmd === 'join')
-        return join(o);
-    if (cmd === 'continue')
-        return resume(o);
-    if (cmd === 'stop')
-        return stop();
-    if (cmd === 'leave')
-        return leave();
-    if (SHARED[cmd])
-        return SHARED[cmd](operatorCtx(o), o);
-    if (['inbox', 'whoami', 'ping', 'wait', 'card'].includes(cmd))
-        fail(`${cmd} is an agent command: ringi agent ${cmd}`);
-    fail(`unknown command ${cmd}; see ringi help`);
-};
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=help.js.map

package/target/esm/clients/cli/index.js

@@ -0,0 +1,27 @@
+import { parseArgs } from './args.js';
+import { dispatch } from './commands.js';
+import { sandboxHints } from '../../core/agents/sessions/context.js';
+import { Fail, WriteDenied } from '../../lib/index.js';
+export { helpMarkdown, TABLE } from './help.js';
+// A reader that stops early (`ringi log | head`) closes the pipe: that ends the output, not the command's work.
+const quietPipe = (e) => {
+    if (e.code === 'EPIPE')
+        process.exit(process.exitCode ?? 0);
+    else
+        throw e;
+};
+// What a failed command says: a refusal as it is (a write the host denied, with what each tool's sandbox needs to
+// allow it), anything else with its stack.
+export const failure = (e) => {
+    if (e instanceof WriteDenied)
+        return [e.message, ...sandboxHints(e.where).map(h => `  ${h}`)].join('\n');
+    return e instanceof Fail ? e.message : e.stack ?? String(e);
+};
+export const main = async (argv = process.argv.slice(2)) => {
+    if (!process.stdout.listeners('error').includes(quietPipe))
+        process.stdout.on('error', quietPipe);
+    const [cmd = 'help', ...rest] = argv;
+    const o = cmd === 'agent' ? { _: [] } : parseArgs(rest);
+    await dispatch(cmd, o, rest);
+};
+//# sourceMappingURL=index.js.map

package/target/esm/clients/cli/operator/heartbeat-format.js

@@ -0,0 +1,8 @@
+// heartbeat-format: one line per heartbeat, as this machine judges it or as the room publishes it.
+import { short } from '../../../lib/index.js';
+export const publishedLine = (h) => `${h.agent.padEnd(12)} ${(h.waits ? `${h.state} (${h.waits})` : h.state).padEnd(22)} ${h.age}s ago${h.overdue ? ', overdue' : ''}  on ${short(h.target)}`;
+export const pulseLine = ({ session: s, tool, beat: b }) => {
+    const state = b.waits ? `${b.state} (${b.waits})` : b.state;
+    return `${s.agent.padEnd(12)} ${`${s.hub}/${s.room}`.padEnd(24)} ${state.padEnd(22)} alive ${b.alive === null ? '?' : b.alive ? 'yes' : 'no'}  quiet ${b.quiet}s${b.cpu === null ? '' : `  cpu ${b.cpu.toFixed(1)}s`}  ${tool}  ${s.handle}`;
+};
+//# sourceMappingURL=heartbeat-format.js.map

package/target/esm/clients/cli/operator/heartbeat.js

@@ -0,0 +1,35 @@
+// heartbeat: `ringi heartbeats` (this machine's sessions, or what a room publishes) and `ringi pulse`.
+import * as Heartbeat from '../../../core/agents/heartbeat/pulse.js';
+import * as Hubs from '../../../core/hub/usecases/hubs.js';
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { dump, flag, opt, out } from '../args.js';
+import { publishedLine, pulseLine } from './heartbeat-format.js';
+const published = (o) => {
+    const R = Rooms.roomIn(Hubs.hubOf(opt(o, 'hub')), opt(o, 'room'));
+    const hs = Heartbeat.published(R);
+    if (flag(o, 'json'))
+        return dump(hs);
+    if (!hs.length)
+        return out(`no heartbeats in ${R.name}`);
+    for (const h of hs)
+        out(publishedLine(h));
+};
+const local = async (o) => {
+    const ps = await Heartbeat.heartbeats();
+    if (flag(o, 'json'))
+        return dump(ps);
+    if (!ps.length)
+        return out('no sessions');
+    for (const p of ps)
+        out(pulseLine(p));
+};
+export const heartbeats = async (o) => {
+    if (flag(o, 'published'))
+        published(o);
+    else
+        await local(o);
+};
+export const pulse = async (o) => {
+    process.exitCode = await Heartbeat.pulse({ every: Number(opt(o, 'beat') ?? 30), once: flag(o, 'once'), log: s => process.stderr.write(`ringi: ${s}\n`) });
+};
+//# sourceMappingURL=heartbeat.js.map

package/target/esm/clients/cli/operator/hub-commands.js

@@ -0,0 +1,37 @@
+// hub-commands: `ringi hub list | create | switch | add | amend`.
+import fs from 'node:fs';
+import * as Hubs from '../../../core/hub/usecases/hubs.js';
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { fail } from '../../../lib/index.js';
+import { attachments, flag, list, opt, out, textOf } from '../args.js';
+export const listHub = (_) => {
+    for (const h of Hubs.hubs())
+        out(`${h.current ? '*' : ' '} ${h.name.padEnd(12)} ${h.store}, ${h.trust}, contract ${h.contract}, ${h.rooms} room(s)${h.remote ? `  remote ${h.remote}` : ''}  ${h.dir}`);
+    return;
+};
+export const createHub = (o) => {
+    const [, arg] = o._;
+    const r = Hubs.create(arg ?? '', { signed: flag(o, 'signed'), url: opt(o, 'url') });
+    if (!r.add)
+        return out(`created hub ${arg} (${r.H.dir})`);
+    return out(`created signed hub ${arg}${r.H.d.store.remote ? `, published to ${r.H.d.store.remote}` : ''}. Its root key stays on this machine (${r.rootKey}).
+Give every machine that joins it, out of band:
+  ${r.add}`);
+};
+export const switchHub = (o) => {
+    const [, arg] = o._;
+    Hubs.use(arg ?? fail('usage: ringi hub switch <name>'));
+    return out(`current hub: ${arg}; agents keep their own rooms`);
+};
+export const addHub = (o) => {
+    const [, arg] = o._;
+    const H = Hubs.add(arg ?? '', o._[2] ?? '', { root: opt(o, 'root'), genesis: opt(o, 'genesis') });
+    return out(`added signed hub ${arg} from ${o._[2]}: contract ${H.contract.version}, ${Rooms.rooms(H).length} room(s), root pinned`);
+};
+export const amendHub = (o) => {
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const files = list(o, 'attach').flatMap(attachments).map(e => ({ path: e.path, content: fs.readFileSync(e.file) }));
+    const r = Hubs.amend(H, { text: textOf(o), set: list(o, 'set'), authority: opt(o, 'authority'), files });
+    return out(`amended hub ${H.name}: contract ${r.version}; rooms keep their base until ringi room rebase-contract <room>`);
+};
+//# sourceMappingURL=hub-commands.js.map

package/target/esm/clients/cli/operator/hub.js

@@ -0,0 +1,10 @@
+// hub: `ringi hub <subcommand>`, by its table (hub-commands.ts).
+import { fail } from '../../../lib/index.js';
+import { addHub, amendHub, createHub, listHub, switchHub } from './hub-commands.js';
+const COMMANDS = new Map([['list', listHub], ['create', createHub], ['switch', switchHub], ['add', addHub], ['amend', amendHub]]);
+export const hub = (o) => {
+    const [sub] = o._;
+    const run = COMMANDS.get(sub || 'list') ?? fail(`unknown: hub ${sub}`);
+    run(o);
+};
+//# sourceMappingURL=hub.js.map

package/target/esm/clients/cli/operator/index.js

@@ -0,0 +1,8 @@
+// operator: the commands only the operator runs, as the operator of this machine in its terminal context: hubs, rooms,
+// where things stand, sessions, heartbeats, the pulse and the watcher.
+export { heartbeats, pulse } from './heartbeat.js';
+export { hub } from './hub.js';
+export { roomCmd } from './room.js';
+export { forget, sessionLine, sessions } from './sessions.js';
+export { where } from './where.js';
+//# sourceMappingURL=index.js.map

package/target/esm/clients/cli/operator/room-lifecycle.js

@@ -0,0 +1,23 @@
+// room-lifecycle: `ringi room archive | delete | rebase-contract`.
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { fail, short } from '../../../lib/index.js';
+import { flag, opt, out } from '../args.js';
+export const archiveRoom = (H, arg, o) => {
+    // Without an id, the room of the current context.
+    const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
+    const name = Rooms.archive(H, R);
+    return out(`archived ${R.name} as ${name}: read-only, wakes nobody; its sessions end. Read it with --room ${name}`);
+};
+export const deleteRoom = (H, arg, o) => {
+    const R = Rooms.roomIn(H, arg ?? opt(o, 'room'));
+    if (!flag(o, 'yes'))
+        fail(`deleting ${R.name} in hub ${H.name} erases it and everything kept for it, for good. Run again with --yes, or archive it instead`);
+    Rooms.erase(H, R);
+    return out(`deleted room ${R.name}: its branch, signals, pins, evidence and readers' state. Sessions bound to it leave it on their next turn`);
+};
+export const rebaseRoomContract = (H, arg, o) => {
+    const R = Rooms.roomIn(H, arg ?? fail('usage: ringi room rebase-contract <id>'));
+    Rooms.rebase(H, R);
+    return out(`room ${R.name} now follows the hub contract at ${short(H.main)} (${H.contract.version})`);
+};
+//# sourceMappingURL=room-lifecycle.js.map

package/target/esm/clients/cli/operator/room-list.js

@@ -0,0 +1,27 @@
+// room-list: `ringi room list | create | switch`.
+import { roomsActive } from '../../../core/agents/overview.js';
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { fail, short } from '../../../lib/index.js';
+import { flag, opt, out } from '../args.js';
+export const listRoom = (H, arg, o) => {
+    const rs = roomsActive(H, { archived: flag(o, 'archived') });
+    for (const r of rs.filter(r => !r.archived))
+        out(`${r.current ? '*' : ' '} ${r.name.padEnd(16)} ${r.members} member(s), ${r.active} active session(s), profile ${r.profile}  genesis ${short(r.genesis)}`);
+    for (const r of rs.filter(r => r.archived))
+        out(`  ${r.name.padEnd(16)} archived, read-only`);
+    if (!rs.length && !flag(o, 'archived'))
+        out(`no rooms in hub ${H.name}: ringi room create <id>`);
+    return;
+};
+export const createRoom = (H, arg, o) => {
+    const quorum = opt(o, 'quorum');
+    const r = Rooms.create(H, arg ?? '', { profile: opt(o, 'profile'), quorum: quorum === undefined ? undefined : Number(quorum) });
+    if (quorum !== undefined)
+        return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. Its work starts by itself at a quorum of ${quorum} agent(s): in each chat that should take part, say "join ${arg} as <id>"`);
+    return out(`created room ${arg} in hub ${H.name} with profile ${r.profile}; it is the current room. In each chat that should take part, say: "join ${arg} as <id>; <what to accept>"`);
+};
+export const switchRoom = (H, arg, o) => {
+    const R = Rooms.use(H, arg ?? fail('usage: ringi room switch <id>'));
+    return out(`current room: ${H.name}/${R.name}; agents keep their own rooms`);
+};
+//# sourceMappingURL=room-list.js.map

package/target/esm/clients/cli/operator/room-members.js

@@ -0,0 +1,15 @@
+// room-members: `ringi room admit | remove`.
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { fail } from '../../../lib/index.js';
+import { opt, out } from '../args.js';
+export const admitRoom = (H, arg, o) => {
+    const R = Rooms.roomIn(H, opt(o, 'room'));
+    Rooms.admit(H, R, arg ?? fail('usage: ringi room admit <agent> <public key|file>'), o._[2] ?? fail('usage: ringi room admit <agent> <public key|file>'));
+    return out(`admitted ${arg} to ${H.name}/${R.name}: its signed messages are accepted from now on; it can join`);
+};
+export const removeRoom = (H, arg, o) => {
+    const R = Rooms.roomIn(H, opt(o, 'room'));
+    Rooms.remove(H, R, arg ?? fail('usage: ringi room remove <agent>'));
+    return out(`removed ${arg} from ${R.name}: it can no longer write or be woken there; returning needs a fresh join`);
+};
+//# sourceMappingURL=room-members.js.map

package/target/esm/clients/cli/operator/room.js

@@ -0,0 +1,15 @@
+// room: `ringi room <subcommand>`, by its table (room-list, room-members, room-lifecycle).
+import * as Hubs from '../../../core/hub/usecases/hubs.js';
+import { fail } from '../../../lib/index.js';
+import { opt } from '../args.js';
+import { archiveRoom, deleteRoom, rebaseRoomContract } from './room-lifecycle.js';
+import { createRoom, listRoom, switchRoom } from './room-list.js';
+import { admitRoom, removeRoom } from './room-members.js';
+const COMMANDS = new Map([['list', listRoom], ['create', createRoom], ['switch', switchRoom], ['admit', admitRoom], ['remove', removeRoom], ['archive', archiveRoom], ['delete', deleteRoom], ['rebase-contract', rebaseRoomContract]]);
+export const roomCmd = (o) => {
+    const [sub, arg] = o._;
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const run = COMMANDS.get(sub || 'list') ?? fail(`unknown: room ${sub}`);
+    run(H, arg, o);
+};
+//# sourceMappingURL=room.js.map

package/target/esm/clients/cli/operator/sessions.js

@@ -0,0 +1,32 @@
+// sessions: `ringi sessions` (the seats this machine holds; `forget <handle>` frees one) and `ringi forget <room>/<log>`
+// (a new baseline for a log after an alarm).
+import * as Hubs from '../../../core/hub/usecases/hubs.js';
+import * as Overview from '../../../core/agents/overview.js';
+import * as Rooms from '../../../core/hub/usecases/rooms.js';
+import { fail } from '../../../lib/index.js';
+import { dump, flag, opt, out } from '../args.js';
+// --- where things stand, sessions, forget ---
+export const sessionLine = (s) => `${s.agent.padEnd(12)} ${s.liveness.padEnd(8)} ${(s.product ?? '?').padEnd(7)} ${s.handle}${s.scope ? `  scope: ${s.scope}` : ''}`;
+export const sessions = (o) => {
+    if (o._[0] === 'forget') {
+        const handle = o._[1] ?? fail('usage: ringi sessions forget <handle>');
+        Overview.forgetSession(handle);
+        return out(`forgot session ${handle}; its seat is free`);
+    }
+    const ss = Overview.sessions();
+    if (flag(o, 'json'))
+        return dump(ss);
+    if (!ss.length)
+        return out('no sessions');
+    for (const s of ss)
+        out(`${s.hub}/${s.room}  ${sessionLine(s)}`);
+};
+export const forget = (o) => {
+    const [name, id] = (o._[0] ?? '').split('/');
+    if (!name || !id)
+        fail('usage: ringi forget <room>/<log>');
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const n = Rooms.forgetLog(H, Rooms.roomIn(H, name), id);
+    out(`forgot the accepted history of ${name}/${id} for ${n} reader(s); the next read accepts what is there now`);
+};
+//# sourceMappingURL=sessions.js.map

package/target/esm/clients/cli/operator/watch.js

@@ -0,0 +1,15 @@
+// watch: the headless watcher the operator starts for an agent's seat (`ringi watch <room>/<agent> --exec …`).
+import { watch } from '../../../core/agents/sessions/agent.js';
+import { fail, words } from '../../../lib/index.js';
+import { flag, opt, out } from '../args.js';
+const numberOption = (o, k) => opt(o, k) === undefined ? undefined : Number(opt(o, k));
+export const watchCommand = async (o) => {
+    process.exitCode = await watch({
+        seat: o._[0] ?? fail('usage: ringi watch <room>/<agent> --exec <cmd> [--scope <text>] [--once] [--require-grant] …'),
+        exec: opt(o, 'exec') ?? fail('--exec <cmd> is required: the command that starts a headless turn'),
+        hub: opt(o, 'hub'), scope: opt(o, 'scope'), once: flag(o, 'once'), requireGrant: flag(o, 'require-grant'), handoff: flag(o, 'handoff'),
+        interval: numberOption(o, 'interval'), from: opt(o, 'from') ? words(opt(o, 'from')) : undefined, maxHop: numberOption(o, 'max-hop'),
+        maxRuns: numberOption(o, 'max-runs'), window: numberOption(o, 'window')
+    }, out);
+};
+//# sourceMappingURL=watch.js.map

package/target/esm/clients/cli/operator/where-format.js

@@ -0,0 +1,24 @@
+// where-format: how `ringi where` shows the hub, the room, who is in, open work and the latest messages.
+import { withSizes } from '../../../core/hub/usecases/room.js';
+import { oneLine, render } from '../../../core/hub/usecases/view.js';
+import { short } from '../../../lib/index.js';
+import { flag, out } from '../args.js';
+import { taskLine } from '../shared/index.js';
+import { sessionLine } from './sessions.js';
+export const hubLine = (H) => `hub ${H.name}: ${H.d.store.type} store, ${H.contract.trust} senders, contract ${H.contract.version}, protocol ${H.contract.protocol}${H.contract.capabilities?.length ? `, ${H.contract.capabilities.join(' ')}` : ''}`;
+const quorumLine = (R) => {
+    if (R.quorum === null)
+        return '';
+    const agents = Object.values(R.members).filter(m => m.role !== 'root').length;
+    return agents >= R.quorum ? `; started at its quorum of ${R.quorum} agents` : `; waiting for a quorum of ${R.quorum} agents, has ${agents}`;
+};
+const roomLine = (R) => `room ${R.name}${R.archived ? ' (archived, read-only)' : ''}, genesis ${short(R.genesis)}, profile ${R.profile.name}; members: ${Object.entries(R.members).map(([id, i]) => i.role === 'root' ? `${id} (root)` : id).join(', ')}` + quorumLine(R);
+export const printOverview = (w, R) => {
+    out(roomLine(R));
+    out(w.sessions.length ? `sessions:\n${w.sessions.map(s => `  ${sessionLine(s)}`).join('\n')}` : 'sessions: none joined');
+    out(w.work.length ? `open work:\n${w.work.map(t => `  ${taskLine(t)}`).join('\n')}` : 'open work: none');
+    if (w.proposals.length)
+        out(`open proposals:\n${w.proposals.map(x => `  ${short(x.proposal.id)} ${x.state} → ${x.decider}  ${x.proposal.subject}`).join('\n')}`);
+};
+export const showMessage = (R, o, all, m) => out(flag(o, 'short') ? `  ${oneLine(m)}` : `\n${render(all, m, { max: 2000, files: () => withSizes(R, m) })}`);
+//# sourceMappingURL=where-format.js.map

package/target/esm/clients/cli/operator/where.js

@@ -0,0 +1,32 @@
+// where: `ringi where`, where things stand for the operator, and `--follow` for what lands next.
+import { config } from '../../../core/hub/usecases/context.js';
+import * as Hubs from '../../../core/hub/usecases/hubs.js';
+import * as Overview from '../../../core/agents/overview.js';
+import { sleep } from '../../../lib/index.js';
+import { flag, opt, out } from '../args.js';
+import { hubLine, printOverview, showMessage } from './where-format.js';
+const follow = async (H, R, o, seen) => {
+    out('following; new messages appear as they land (Ctrl-C to stop)');
+    for (;;) {
+        await sleep(Number(opt(o, 'interval') ?? 2) * 1000);
+        const now = Overview.arrived(H, R, seen);
+        for (const m of now.messages)
+            showMessage(R, o, now.all, m);
+    }
+};
+export const where = async (o) => {
+    const H = Hubs.hubOf(opt(o, 'hub'));
+    const w = Overview.where(H, opt(o, 'room') ?? config().room);
+    out(hubLine(H));
+    const R = w.room;
+    if (!R)
+        return out('no current room: ringi room create <id> | ringi room switch <id>');
+    printOverview(w, R);
+    const n = Number(opt(o, 'n') ?? (flag(o, 'short') ? 10 : 5));
+    out(`last ${Math.min(n, w.messages.length)} of ${w.messages.length} messages:`);
+    for (const m of w.messages.slice(-n))
+        showMessage(R, o, w.all, m);
+    if (flag(o, 'follow'))
+        await follow(H, R, o, new Set(w.all.keys()));
+};
+//# sourceMappingURL=where.js.map