@idleware/ringi 0.0.0-stage → 0.1.0

package/target/esm/app/room.js

@@ -0,0 +1,127 @@
+// room: what any participant (the operator or an agent) does in a room: write messages and read them, follow work,
+// check signals. Each operation takes who acts and typed input, and returns data; interfaces print it.
+import * as D from '../domain/decisions.js';
+import { isOpen, tasksIn } from '../domain/profiles.js';
+import * as Signals from '../domain/signals.js';
+import { OPERATOR } from '../home/index.js';
+import { HIDDEN, append } from '../hub/index.js';
+import * as HubSignals from '../hub/signals.js';
+import { fail, note, short } from '../lib/index.js';
+import { checkCollisions } from '../protocol/files.js';
+import { ID_RE, TOKEN_RE, checkOutgoing, compose, link, lookup, ordered, rootOf, under } from '../protocol/index.js';
+import { linked, loadRoomUnlocked, loadState, readerLock, saveState } from '../runtime/reader.js';
+import { taskView } from './view.js';
+export const isRef = (R) => (x) => R.hub.store.isRef(x);
+// A message from the actor. The operator may omit `to`: the room, or the assignees when there are any.
+export const send = ({ R, me }, x) => {
+    const P = R.profile;
+    const { all } = linked(R, me);
+    const re = x.re ? lookup(all, x.re) : null;
+    let to = [...new Set(x.to ?? [])];
+    const assign = x.assign ? [...new Set(x.assign)] : null;
+    if (!to.length && x.reply && re)
+        to = re.from === me ? re.to : [re.from, ...(x.all ? re.to.filter(t => t !== me) : [])];
+    if (!to.length && assign)
+        to = assign;
+    if (!to.length && me === OPERATOR)
+        to = ['*'];
+    if (!to.length)
+        fail('--to is required: agent ids, comma-separated, or *');
+    for (const t of to)
+        if (t !== '*' && !ID_RE.test(t))
+            fail(`bad recipient ${t}`);
+    if (x.state && !P.states.includes(x.state))
+        fail(`--state must be one of profile ${P.name}: ${P.states.join(', ')}`);
+    if (x.state && !re)
+        fail('--state belongs to a reply inside a piece of work; pass --re <message>');
+    for (const a of assign ?? [])
+        if (!ID_RE.test(a))
+            fail(`bad assignee ${a}`);
+    if (x.roles && !x.roles.split(',').every(r => {
+        const parts = r.split('=').map(v => v.trim());
+        return parts.length === 2 && ID_RE.test(parts[0]) && TOKEN_RE.test(parts[1]);
+    }))
+        fail('--roles takes "<id>=<label>, …"; labels mean what the room profile says');
+    let grant = null;
+    if (x.grant) {
+        const d = lookup(all, x.grant);
+        const g = D.grantOf(all, R.authorityAt, d.id) ?? fail(`${short(d.id)} is not an approved decision with a budget`);
+        if (g.revoked)
+            fail(`grant ${short(g.id)} was revoked`);
+        grant = g.id;
+    }
+    const entries = x.files ?? [];
+    checkCollisions(entries.map(e => e.path));
+    const text = compose(x.text, [
+        ['To', to.join(', ')], ['Re', re?.id], ['Kind', x.task && P.opens], ['State', x.state], ['Assign', assign?.join(', ')],
+        ['Roles', x.roles], ['Grant', grant], ['Hop', re && String(re.hopEff + 1)],
+    ]);
+    checkOutgoing(text, isRef(R));
+    const id = append(R, me, text, entries);
+    if (to.length === 1 && to[0] === '*')
+        note(`addressed to the whole room: this ${x.task ? P.opens : 'message'} wakes nobody; name recipients (--to or --assign) to start work`);
+    return { id, to, files: entries.length };
+};
+// --- reading ---
+// Who marked a message how (read, taken), from the marks that pass their check.
+export const marks = (R, all) => Signals.marksOn(Signals.check(R, all, R.hub.store.signals(R.s)));
+export const message = ({ R, me }, ref) => {
+    const { all } = linked(R, me);
+    const m = lookup(all, ref);
+    return { all, m, replies: [...all.values()].filter(x => x.reId === m.id), marks: marks(R, all).get(m.id) };
+};
+export const thread = ({ R, me }, ref) => {
+    const { all } = linked(R, me);
+    return { all, msgs: under(all, rootOf(all, lookup(all, ref))) };
+};
+// Open work that concerns the actor (the operator: all open work); with `all`, every piece of work.
+export const tasks = ({ R, me }, { all: everything = false } = {}) => {
+    const P = R.profile;
+    const { all } = linked(R, me);
+    let ts = tasksIn(all, P);
+    if (!everything)
+        ts = ts.filter(t => isOpen(t, P) && (me === OPERATOR || t.requester === me || t.assignees.includes(me) || (!t.assignees.length && (t.root.to.includes(me) || t.root.to.includes('*')))));
+    ts.sort((a, b) => a.at - b.at);
+    const m = marks(R, all);
+    return { tasks: ts, views: ts.map(t => taskView(t, m.get(t.root.id)?.taken ?? [])) };
+};
+export const log = ({ R, me }, { agent, all: everything = false, n = 20 } = {}) => {
+    const { all } = linked(R, me);
+    return ordered([...all.values()].filter(m => (!agent || m.from === agent) && (everything || !(m.kind && HIDDEN.has(m.kind))))).slice(-n);
+};
+// The files of a message: one named path, or all of them.
+export const files = ({ R, me }, ref, path) => {
+    const { all } = linked(R, me);
+    const m = lookup(all, ref);
+    if (path && !m.files.some(f => f.path === path))
+        fail(`no ${path} in ${short(m.id)}`);
+    return { m, files: m.files.filter(f => !path || f.path === path).map(f => ({ path: f.path, content: R.hub.store.file(m.id, f.path) })) };
+};
+export const members = ({ R, me }) => {
+    const { logs, all } = linked(R, me);
+    const cards = new Map(ordered([...all.values()].filter(m => m.kind === 'card' && !m.bad)).map(m => [m.from, m]));
+    return Object.entries(R.members).map(([id, info]) => ({ id, role: info.role ?? 'member',
+        messages: (logs.get(id) ?? []).filter(m => !(m.kind && HIDDEN.has(m.kind))).length, card: cards.get(id)?.subject ?? null }));
+};
+// --- signals ---
+// The room's signals, each checked against its message and against what this reader accepted before; `repair` first
+// restores the missing signals of the actor's own messages.
+export const signals = ({ R, me }, { repair = false } = {}) => readerLock(R, me, () => {
+    const { logs, st } = loadRoomUnlocked(R, me);
+    const all = link(logs);
+    let repaired = null;
+    if (repair) {
+        repaired = 0;
+        for (const m of logs.get(me) ?? [])
+            repaired += HubSignals.emit(R, me, all, m);
+    }
+    const records = R.hub.store.signals(R.s);
+    const checked = Signals.check(R, all, records);
+    const p = Signals.pins(records, checked, st.signals);
+    saveState(R, me, { ...loadState(R, me), signals: p.accepted });
+    return { all, checked, alarms: [...p.alarms, ...checked.filter(c => !c.ok).map(c => `signal ${c.ref}: ${c.why}`)], repaired };
+});
+// What interfaces need to show and store a message's files: their sizes, and a path safe to write under.
+export { withSizes } from '../hub/index.js';
+export { checkPath } from '../protocol/files.js';
+//# sourceMappingURL=room.js.map

package/target/esm/app/rooms.js

@@ -0,0 +1,120 @@
+// rooms: the operator's rooms in a hub: list, create, switch, admit and remove members, archive, delete, move to a
+// newer contract, and accept a new baseline for a log after reviewing an alarm.
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULT_PROFILE, parseProfile } from '../domain/profiles.js';
+import { HOME, OPERATOR, config, guard, locked, setConfig } from '../home/index.js';
+import { RESERVED_ROOMS, ROOM_MD, controlChange, profileText, room as roomOf, roomNames } from '../hub/index.js';
+import { Fail, fail, note } from '../lib/index.js';
+import { ID_RE, compose } from '../protocol/index.js';
+import { loadState, readerLock, saveState } from '../runtime/reader.js';
+import { allSessions, liveness } from '../runtime/session.js';
+// The operator's terminal context picks the room unless one is named.
+export const roomIn = (H, name) => roomOf(H, name ?? config().room);
+// A room the store offers but that does not open (a history under another name) is an alarm, not a row.
+const opens = (H, n) => {
+    try {
+        return roomOf(H, n);
+    }
+    catch (e) {
+        if (!(e instanceof Fail))
+            throw e;
+        note(`ALARM ${e.message}`);
+        return null;
+    }
+};
+export const rooms = (H, { archived = false } = {}) => {
+    const cur = config().room;
+    const view = (n, R) => {
+        const ss = allSessions().filter(s => s.hub === H.name && s.genesis === R.genesis);
+        return { name: n, current: n === cur && !R.archived, archived: R.archived, members: Object.keys(R.members).length,
+            active: ss.filter(s => liveness(s) === 'active').length, profile: R.profile.name, genesis: R.genesis };
+    };
+    const live = roomNames(H).flatMap(n => { const R = opens(H, n); return R ? [view(n, R)] : []; });
+    const gone = archived ? roomNames(H, true).flatMap(n => { const R = opens(H, n); return R ? [view(n, R)] : []; }) : [];
+    return [...live, ...gone];
+};
+// A room carries its profile from the start: later changes to the hub's profiles do not reach it.
+export const create = (H, name, { profile } = {}) => {
+    if (!ID_RE.test(name) || RESERVED_ROOMS.has(name))
+        fail(`usage: ringi room create <id> [--profile <name>] (an id like fix-badge; not ${[...RESERVED_ROOMS].join(', ')})`);
+    const p = profile ?? H.contract.profile ?? DEFAULT_PROFILE;
+    const text = profileText(H, p) ?? fail(`hub ${H.name} carries no profile ${p}; add it with ringi hub amend -m "<why>" --attach <file>:profiles/${p}.json`);
+    parseProfile(text, `profile ${p}`);
+    locked(`hub-${H.name}`, () => {
+        const files = { 'ROOM.md': ROOM_MD(name), 'members.json': JSON.stringify({ [OPERATOR]: { role: 'root' } }, null, 2) + '\n', 'profile.json': text };
+        // A signed room's roster: who may sign its logs, starting with the root.
+        if (H.signed)
+            files.allowed_signers = H.store.rootRoster?.() ?? fail(`hub ${H.name}: its store cannot start a signed roster`);
+        // The genesis names the room; a random id makes it unique, so a room deleted and created again is a different room.
+        H.store.createRoom(name, OPERATOR, compose(`room ${name}`, [['To', '*'], ['Kind', 'room'], ['Room-Id', crypto.randomBytes(16).toString('hex')]]), files);
+    });
+    setConfig({ hub: H.name, room: name });
+    return { profile: p };
+};
+export const use = (H, name) => {
+    const R = roomOf(H, name);
+    setConfig({ hub: H.name, room: R.name });
+    return R;
+};
+// Removing, archiving or deleting in a signed hub needs revocation published to every replica: not in this version.
+const notSigned = (H, what) => { if (H.signed)
+    fail(`room ${what} is not supported on signed hubs yet: a local change would come back with the next fetch`); };
+export const admit = (H, R, who, key) => {
+    if (!H.signed || !H.store.admit)
+        fail('room admit is for signed hubs; on a local hub the operator\'s join adds members');
+    locked(`hub-${H.name}`, () => H.store.admit(R.s, who, key));
+};
+export const remove = (H, R, who) => {
+    notSigned(H, 'remove');
+    if (!R.members[who])
+        fail(`${who} is not a member of ${R.name}`);
+    if (who === OPERATOR)
+        fail('the operator stays in every room');
+    controlChange(R, OPERATOR, `remove ${who}`, m => { delete m[who]; });
+};
+export const archive = (H, R) => {
+    notSigned(H, 'archive');
+    if (R.archived)
+        fail(`${R.name} is already archived`);
+    const name = `${R.name}@${R.genesis.slice(0, 8)}`;
+    locked(`hub-${H.name}`, () => H.store.archiveRoom(R.s, name));
+    if (config().room === R.name)
+        setConfig({ room: null });
+    return name;
+};
+export const erase = (H, R) => {
+    notSigned(H, 'delete');
+    locked(`hub-${H.name}`, () => H.store.deleteRoom(R.s));
+    guard(() => fs.rmSync(path.join(HOME, 'readers', H.name, R.genesis), { recursive: true, force: true }));
+    if (config().room === R.name)
+        setConfig({ room: null });
+};
+// The room follows the hub's current contract from now on; nothing written before is reinterpreted.
+export const rebase = (H, R) => controlChange(R, OPERATOR, `contract ${H.contract.version}`, () => { }, [['Contract', H.main]]);
+// The operator accepts a new baseline for one log, for every reader of the room, after reviewing an alarm. A signed
+// store resets its transport pin too, keeping the displaced head as evidence; signatures are never waived.
+export const forgetLog = (H, R, id) => {
+    if (!ID_RE.test(id))
+        fail('usage: ringi forget <room>/<log>');
+    if (H.signed)
+        H.store.forgetLog?.(R.s, id);
+    const dir = path.join(HOME, 'readers', H.name, R.genesis);
+    let n = 0;
+    for (const f of fs.existsSync(dir) ? fs.readdirSync(dir).filter(f => f.endsWith('.json')) : []) {
+        const reader = f.slice(0, -5);
+        readerLock(R, reader, () => {
+            const st = loadState(R, reader);
+            if (st.heads?.[id]) {
+                delete st.heads[id];
+                st.alarms = (st.alarms ?? []).filter(a => !a.startsWith(`log ${id} `) && !a.startsWith(`log ${id}:`));
+                saveState(R, reader, st);
+                n++;
+            }
+            H.store.unpin(R.s, reader, id);
+        });
+    }
+    return n;
+};
+//# sourceMappingURL=rooms.js.map

package/target/esm/app/session.js

@@ -0,0 +1,97 @@
+// Session use cases preserve the operator's identity, seat and delegated scope.
+import { OPERATOR, ensureHome, locked } from '../home/index.js';
+import { controlChange, openHub, room as roomOf } from '../hub/index.js';
+import { ID_RE } from '../protocol/index.js';
+import { allSessions, bound, dropSession, liveness, ownSession, parseSelector, pidAlive, readSession, saveSession, seatHolder, whoAmI } from '../runtime/session.js';
+import { fail, note, stamp } from '../lib/index.js';
+import { inbox } from './agent.js';
+import { tasks } from './room.js';
+export { bound } from '../runtime/session.js';
+export const briefing = (s) => {
+    const actor = bound();
+    return { session: s, actor, tasks: tasks(actor).views, inbox: inbox(actor) };
+};
+export const join = ({ hub, room, agent: id, scope }) => {
+    const me = whoAmI();
+    const agent = id ?? me.product ?? fail('--as <id> is required: this session\'s product is unknown');
+    if (!ID_RE.test(agent) || agent === OPERATOR)
+        fail(`bad agent id ${agent}`);
+    const H = openHub(hub), R = roomOf(H, room);
+    if (R.archived)
+        fail(`${room} is archived`);
+    if (H.signed) {
+        if (!H.store.joinKey)
+            fail(`hub ${H.name}: its store cannot make keys`);
+        const key = H.store.joinKey(R.s, agent);
+        if (!key.admitted)
+            return { agent, hub: H.name, room: R.name, session: null, key };
+    }
+    locked('sessions', () => {
+        const holder = seatHolder(H.name, R.genesis, agent, me.handle);
+        if (holder)
+            fail(`${room}/${agent} is held by another session (${holder.handle}, ${liveness(holder)}). A seat ends only with leave, or the operator's takeover: "continue ${room}/${agent}" in this chat`);
+        const mine = ownSession(me.handle);
+        if (mine?.product === 'watch' && mine.pid && pidAlive(mine.pid))
+            fail('this chat handed its seat to a live watcher; stop or leave it before joining another room');
+        if (mine && mine.handle !== me.handle)
+            dropSession(mine.handle);
+        const same = !!mine && mine.hub === H.name && mine.genesis === R.genesis && mine.agent === agent;
+        if (!R.members[agent]) {
+            if (H.signed)
+                fail(`${agent} is not in the roster of ${room}; the root admits its key first`);
+            controlChange(R, OPERATOR, `join ${agent}`, m => { m[agent] = { role: 'member', since: stamp() }; });
+        }
+        if (mine && !same)
+            note(`left ${mine.hub}/${mine.room} as ${mine.agent}: one room per session`);
+        saveSession({ handle: me.handle, product: me.product, hub: H.name, room: R.name, genesis: R.genesis, agent,
+            scope: scope ?? (same ? mine.scope : null), state: 'active', since: same ? mine.since : stamp(), lastSeen: stamp(), pid: me.pid });
+    });
+    return { agent, hub: H.name, room: R.name, session: readSession(me.handle), key: null };
+};
+export const resume = (selector) => {
+    const me = whoAmI();
+    ensureHome();
+    return locked('sessions', () => {
+        let target;
+        if (!selector) {
+            const mine = ownSession(me.handle);
+            if (!mine) {
+                const cands = allSessions().filter(s => liveness(s) !== 'active').sort((a, b) => Number(b.product === me.product) - Number(a.product === me.product));
+                if (!cands.length)
+                    fail('nothing to continue: this chat was never joined, and no paused or gone session waits. The operator says "join <room> as <id>"');
+                fail(`this chat has no binding of its own. Say which one to take over:\n${cands.map(s => `  ringi continue ${s.hub}:${s.room}/${s.agent}   (${liveness(s)}, ${s.product ?? '?'}, ${s.handle}${s.scope ? `, scope: ${s.scope}` : ''})`).join('\n')}`);
+            }
+            target = mine;
+        }
+        else {
+            const sel = parseSelector(selector);
+            const hits = allSessions().filter(s => s.room === sel.room && s.agent === sel.agent && (!sel.hub || s.hub === sel.hub));
+            if (hits.length > 1)
+                fail(`several hubs have ${sel.room}/${sel.agent}; name one: <hub>:${sel.room}/${sel.agent}`);
+            target = hits[0] ?? fail(`no session holds ${selector}; the operator joins this chat with ringi join`);
+        }
+        if (target.handle !== me.handle) {
+            if (liveness(target) === 'active' || (target.product === 'watch' && target.pid && pidAlive(target.pid)))
+                fail(`${target.room}/${target.agent} is held by a live session (${target.handle}); it is not taken over`);
+            dropSession(target.handle);
+            note(`took over ${target.hub}/${target.room}/${target.agent} from ${target.handle}`);
+        }
+        const session = { ...target, handle: me.handle, product: target.handle === me.handle ? target.product : me.product, state: 'active',
+            since: target.handle === me.handle ? target.since : stamp(), lastSeen: stamp(), pid: me.pid ?? (target.handle === me.handle ? target.pid : null),
+            takenFrom: target.handle === me.handle ? target.takenFrom : undefined };
+        saveSession(session);
+        return session;
+    });
+};
+export const stop = () => locked('sessions', () => {
+    const s = ownSession(whoAmI().handle) ?? fail('this session is in no room');
+    const stopped = { ...s, state: 'stopped', lastSeen: stamp() };
+    saveSession(stopped);
+    return stopped;
+});
+export const leave = () => locked('sessions', () => {
+    const s = ownSession(whoAmI().handle) ?? fail('this session is in no room');
+    dropSession(s.handle);
+    return s;
+});
+//# sourceMappingURL=session.js.map

package/target/esm/app/view.js

@@ -0,0 +1,52 @@
+// view: how messages, work, proposals and grants are shown: as text framed for people and models, and as the JSON
+// shapes every interface (the CLI's --json, a control panel) returns.
+import { bytes, when } from '../lib/index.js';
+import { KNOWN } from '../protocol/index.js';
+const id12 = (x) => x.slice(0, 12);
+// Trailers a store writes about its own records (the git store's list of attached paths): shown as `Files:`, not again.
+const STORED = new Set(['ringi-files']);
+// Frames a message for a model: sender and how it is known, id, addressing, hop; the body is the peer's content.
+export const render = (all, m, { max = 0, files = () => m.files } = {}) => {
+    const lines = [`=== ${id12(m.id)} · ${m.from} (${m.trust}) → ${m.to.join(', ') || '(nobody)'} · ${when(m.time)}`];
+    if (m.re || m.trailers.re) {
+        const p = m.reId ? all.get(m.reId) : undefined;
+        lines.push(`Re: ${id12(m.reId ?? m.re ?? m.trailers.re[0])}${p ? ` (${p.from}) ${p.subject}` : ' (not available)'}`);
+    }
+    if (m.bad)
+        lines.push(`Malformed: ${m.bad} (not delivered, not part of tasks)`);
+    if (m.kind)
+        lines.push(`Kind: ${m.kind}`);
+    if (m.state)
+        lines.push(`State: ${m.state}`);
+    if (m.assign)
+        lines.push(`Assign: ${m.assign.join(', ')}`);
+    if (m.roles)
+        lines.push(`Roles: ${Object.entries(m.roles).map(([k, v]) => `${k}=${v}`).join(', ')}`);
+    if (m.hopEff)
+        lines.push(`Hop: ${m.hop}${m.hopEff !== m.hop ? ` (effective ${m.hopEff})` : ''}`);
+    for (const [k, v] of Object.entries(m.trailers))
+        if (!KNOWN.has(k) && !STORED.has(k))
+            lines.push(`${k[0].toUpperCase()}${k.slice(1)}: ${v.join(', ')}`);
+    const fl = files();
+    if (fl.length)
+        lines.push(`Files: ${fl.map(f => `${f.path} (${bytes(f.size ?? 0)})`).join(', ')}`);
+    if (m.refused.length)
+        lines.push(`Refused: ${m.refused.map(f => `${f.path} (${f.why ?? `mode ${f.mode}`})`).join(', ')}`);
+    lines.push(`Subject: ${m.subject}`);
+    const body = max && m.body.length > max ? `${m.body.slice(0, max)}\n[… ${m.body.length - max} more chars: read ${id12(m.id)}]` : m.body;
+    if (body)
+        lines.push('', body);
+    lines.push(`=== end ${id12(m.id)}`);
+    return lines.join('\n');
+};
+export const oneLine = (m) => `${id12(m.id)}  ${when(m.time).slice(5)}  ${m.from} → ${m.to.join(',') || '-'}  ${[m.kind, m.state].filter(Boolean).map(x => `[${x}] `).join('')}${m.subject}`;
+export const asJson = (m) => ({ id: m.id, from: m.from, trust: m.trust, to: m.to, re: m.re, kind: m.kind, state: m.state,
+    assign: m.assign, roles: m.roles, hop: m.hop, hopEff: m.hopEff, bad: m.bad, time: new Date(m.time * 1000).toISOString(), subject: m.subject,
+    body: m.body, files: m.files.map(f => ({ path: f.path, size: f.size })), refused: m.refused, trailers: m.trailers });
+export const taskView = (t, taken) => ({ id: t.root.id, subject: t.root.subject, requester: t.requester,
+    assignees: t.assignees, roles: t.roles, taken, grant: t.grant, state: t.state, by: t.by, at: new Date(t.at * 1000).toISOString() });
+export const proposalView = (x) => ({ id: x.proposal.id, subject: x.proposal.subject, from: x.proposal.from,
+    decider: x.decider, state: x.state, budget: x.budget, stamps: x.stamps, missing: x.missing });
+export const grantView = (x, usage) => ({ grant: x.grant.id, proposal: x.proposal.id,
+    subject: x.proposal.subject, budget: x.grant.budget, revoked: x.grant.revoked, usage });
+//# sourceMappingURL=view.js.map

package/target/esm/cli/agent.js

@@ -0,0 +1,40 @@
+// Agent interface: parse options, call the app, render its result.
+import * as Agent from '../app/agent.js';
+import { asJson, render } from '../app/view.js';
+import { fail, short, when } from '../lib/index.js';
+import { dump, flag, list, opt, out, textOf } from './args.js';
+const options = (o) => ({ peek: flag(o, 'peek'), limit: opt(o, 'limit') ? Number(opt(o, 'limit')) : undefined });
+export const showInbox = ({ R, me, s }, res, o) => {
+    if (flag(o, 'json'))
+        return dump(res.msgs.map(asJson));
+    if (!res.msgs.length)
+        return out('inbox: nothing new');
+    out(`inbox: ${res.msgs.length} new for ${me} in ${R.hub.name}/${R.name} (senders ${R.hub.signed ? 'verified by signature' : 'asserted, not verified'})${s?.scope ? `\nyour scope: ${s.scope}` : ''}`);
+    for (const m of res.msgs)
+        out(`\n${render(res.all, m, { max: 4000 })}`);
+    if (res.rest)
+        out(`\n(${res.rest} more: run ringi agent inbox again)`);
+};
+export const inbox = (a, o) => showInbox(a, Agent.inbox(a, options(o)), o);
+export const take = (a, o) => {
+    const { m, made } = Agent.take(a, o._[0] ?? fail('usage: ringi agent take <work>'));
+    out(`${made ? 'took' : 'already took'} ${short(m.id)}: ${m.subject}`);
+};
+export const whoami = (a) => {
+    const { session: s, profile, members } = Agent.whoami(a);
+    out(`${s.agent} in ${s.hub}/${s.room} (genesis ${short(s.genesis)}, profile ${profile}), session ${s.handle}, ${s.state}\nscope: ${s.scope ?? 'none recorded; ask the operator what to accept'}\nmembers: ${members.join(', ')}`);
+};
+export const card = (a, o) => out(`card ${short(Agent.card(a, textOf(o)))}`);
+export const ping = (a, o) => {
+    const r = Agent.ping(a, { to: o._[0] ?? fail('usage: ringi agent ping <id> [-m <note>] [--next <s>] [--re <msg>]'),
+        text: list(o, 'm').length ? list(o, 'm').join('\n\n') : undefined, next: opt(o, 'next') ? Number(opt(o, 'next')) : undefined, re: opt(o, 're') });
+    out(`ping ${short(r.id)} to ${r.to}${r.previous ? (r.previous.answeredAt !== null ? `; ${r.to} answered the previous one at ${when(r.previous.answeredAt)}` : `; no pong to the previous one (${short(r.previous.id)})`) : ''}`);
+};
+export const wait = async (a, o) => {
+    const r = await Agent.wait(a, { ...options(o), max: opt(o, 'max') === undefined ? undefined : Number(opt(o, 'max')) });
+    if (r.inbox)
+        return showInbox(a, r.inbox, o);
+    out(`wait: nothing for ${a.me} in ${Math.round(r.seconds)}s`);
+    process.exitCode = 3;
+};
+//# sourceMappingURL=agent.js.map

package/target/esm/cli/args.js

@@ -0,0 +1,61 @@
+// 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';
+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']);
+const MULTI = new Set(['m', 'attach', 'set']);
+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 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;
+export const textOf = (o) => {
+    const file = opt(o, 'file');
+    const text = list(o, 'm').length ? list(o, 'm').join('\n\n') : file ? fs.readFileSync(file === '-' ? 0 : file, 'utf8') : '';
+    return text.replace(/\r\n/g, '\n').trim() || fail('empty message: pass -m "<subject>" [-m "<body>"] or -F <file>');
+};
+const walk = (d) => fs.readdirSync(d, { withFileTypes: true }).flatMap(e => e.name === '.git' ? [] : e.isDirectory() ? walk(path.join(d, e.name)) : e.isFile() ? [path.join(d, e.name)] : []);
+// `<src>[:<dest>]` → entries; a directory source expands to its regular files.
+export const attachments = (spec) => {
+    const i = spec.indexOf(':');
+    const src = path.resolve(i < 0 ? spec : spec.slice(0, i));
+    const dest = checkPath((i < 0 ? `files/${path.basename(src)}` : spec.slice(i + 1)).replace(/^\/+|\/+$/g, ''));
+    const mode = (f) => fs.statSync(f).mode & 0o111 ? '100755' : '100644';
+    if (!fs.statSync(src).isDirectory())
+        return [{ path: dest, file: src, mode: mode(src) }];
+    return walk(src).map(f => ({ path: checkPath(`${dest}/${path.relative(src, f).split(path.sep).join('/')}`), file: f, mode: mode(f) }));
+};
+//# sourceMappingURL=args.js.map

package/target/esm/cli/context.js

@@ -0,0 +1,8 @@
+// context: who runs a command and in which room, from the command line.
+import * as Context from '../app/context.js';
+import { words } from '../lib/index.js';
+import { opt } from './args.js';
+export { isRef } from '../app/room.js';
+export const parseTo = (v) => [...new Set(words(v))];
+export const operatorCtx = (o) => Context.operator({ hub: opt(o, 'hub'), room: opt(o, 'room') });
+//# sourceMappingURL=context.js.map

package/target/esm/cli/index.js

@@ -0,0 +1,125 @@
+// 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, hub, roomCmd, sessions, where } from './operator.js';
+import { join, leave, resume, stop } from './session.js';
+import { cat, decide, get, grants, log, profileCmd, proposals, propose, read, reply, send, signals, stamp_, tasks, thread, who } from './shared.js';
+import { skill } from './skill.js';
+// --- commands ---
+// [command, who runs it, what it does]: the one table behind `ringi help` and COMMANDS.md.
+export const TABLE = [
+    ['hub [list]', 'operator', 'the hubs; `local` exists by default; * marks the current one'],
+    ['hub create <name> [--signed [--url <git url>]]', 'operator', 'another hub: asserted senders, or signed with a root key made on this machine; --url publishes it'],
+    ['hub add <name> <git url> --root <public key|file> [--genesis <sha>]', 'operator', 'a replica of a signed hub; the root key comes from you, out of band, never from the hub'],
+    ['hub switch <name>', 'operator', 'change the terminal\'s current hub; agents stay where they are'],
+    ['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>]', 'operator', 'a room for one piece of work, following a profile; becomes the current room'],
+    ['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'],
+    ['room archive <id>', 'operator', 'local hubs: read-only from now on; wakes nobody; its sessions end'],
+    ['room delete <id> --yes', 'operator', 'local hubs: remove a room\'s history for good'],
+    ['room rebase-contract <id>', 'operator', 'move a room onto the hub\'s current contract'],
+    ['where [-n n] [--short] [--follow]', 'operator', 'hub, room, sessions (active, stopped, gone), open work and proposals, latest messages'],
+    ['send -m <subject> [-m <body>]... [--to <ids>] [--task] [--re <msg>] [--state <s>] [--assign <ids>] [--roles <id>=<label>,...] [--grant <decision>] [--attach <src>[:<dest>]]...', 'operator', 'a message as operator; without --to it goes to the room and wakes nobody; --task opens work of the room\'s profile'],
+    ['propose -m <subject> [-m <body>] --decider <id> [--reviewers <ids>] [--due 2h|<ISO>] [--budget runs=<n>,run-seconds=<n>,concurrency=<n>] [--supersedes <proposal>]', 'both', 'a proposal; it circulates to the reviewers and the decider'],
+    ['stamp <proposal> approve|object|abstain -m <reason>', 'both', 'a named reviewer\'s stamp on that exact revision'],
+    ['decide <proposal> approved|rejected|revoked -m <reason>', 'both', 'the named decider, with authority; an approval with a budget is a grant'],
+    ['proposals [--all] | grants', 'both', 'open proposals with their stamps; grants with their usage'],
+    ['tasks [--all] | log [-n n] | read <msg> | thread <msg> | cat <msg> [<path>] | get <msg> [-o <dir>] | who', 'both', 'reading the room (agents: ringi agent …)'],
+    ['signals [--all] [--repair]', 'both', 'what happened (signals) and where attention is (read and taken marks), each checked; --repair restores your missing signals'],
+    ['profile', 'both', 'the room\'s profile: what a piece of work is, its states, who may move it'],
+    ['sessions | sessions forget <handle>', 'operator', 'the chats the CLI remembers; drop a stale one'],
+    ['forget <room>/<log>', 'operator', 'after a changed-history alarm: accept a new baseline for that log'],
+    ['watch [<hub>:]<room>/<agent> --exec <cmd> [--handoff] [--scope <text>] [--once] [--require-grant] [--from <ids>] [--max-hop n] [--max-runs n] [--window s] [--interval s]', 'operator', 'headless turns for one agent: answers pings, spends grants, writes usage receipts; --handoff, run from the agent\'s own chat, moves its seat and scope to the watcher; exits with the failed turn\'s status'],
+    ['skill install [--project] | uninstall | status | show', 'operator', 'the skill for Claude Code, Codex and Cursor'],
+    ['join <hub> <room> [--as <id>] [--scope <text>]', 'session', 'bind this chat to a room as an agent, with what the operator delegates'],
+    ['continue [[<hub>:]<room>/<agent>]', 'session', 'resume this chat\'s binding, also after a restart; naming one takes over a paused or gone one'],
+    ['stop', 'session', 'pause: keep the seat, react to nothing'],
+    ['leave', 'session', 'release the seat'],
+    ['agent whoami', 'agent', 'identity, room, profile, scope'],
+    ['agent inbox [--peek] [--limit n]', 'agent', 'what is new for you; marks it seen and leaves a read mark on each (--peek: neither)'],
+    ['agent take <work>', 'agent', 'a taken mark: you are on it; others see it in tasks and read. It changes no state'],
+    ['agent send … | reply <msg> -m … [--state <s>] [--assign <ids>] [--roles …] [--grant <decision>] [--attach …] [--all]', 'agent', 'write; answer the message you act on'],
+    ['agent propose | stamp | decide | proposals | grants', 'agent', 'decisions, as the joined agent'],
+    ['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 = () => {
+    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}`;
+    return [`ringi ${about().version}: distributed agent coordinator. Home: ${about().home} (RINGI_HOME).`,
+        ...groups.flatMap(([w, title]) => ['', title, ...TABLE.filter(r => r[1] === w).map(line)]),
+        '', 'message ids are store revisions (git: commit shas); any unique prefix of 4+ characters works. States and roles come from the room\'s profile: ringi profile'].join('\n');
+};
+export const helpMarkdown = () => ['# ringi commands', '',
+    'One table. **operator**: the human in a terminal, in the current hub and room. **session**: run in a chat on the operator\'s words. **agent**: what an agent runs during a turn, as `ringi agent …`, always in its session\'s own room. **both**: the operator directly, or an agent under `ringi agent`. Generated by `ringi help --md`; a test keeps this file in sync.', '',
+    '| 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 = { 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 === '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