@idleware/ringi 0.5.0 → 0.6.1

package/target/esm/protocol/index.js

@@ -1,219 +0,0 @@
-// protocol: the message protocol, docs/spec/core-1.md (§3, §5–§7), independent of storage and of any task model. A store
-// turns its records into messages and hands them here: text, threads, inboxes and waking live in this file. What a
-// task is, which states it has and who may move it, is a profile (profile.ts), not part of the protocol.
-import { CC_RE } from './files.js';
-import { fail } from '../lib/index.js';
-export const ID_RE = /^(?=.{1,64}$)[a-z0-9]+(?:[._-][a-z0-9]+)*(?<!\.lock)$/;
-// An agent's id has no dot: it starts the name of its signals, `<agent>.<signal>.<message12>`.
-export const AGENT_RE = /^(?=.{1,64}$)[a-z0-9]+(?:[_-][a-z0-9]+)*$/;
-export const TOKEN_RE = /^[a-z][a-z0-9-]*$/;
-export const HOP_RE = /^(?:0|[1-9]\d{0,5})$/;
-export const TRAILER_RE = /^([A-Za-z][A-Za-z0-9-]*):[ \t]*(.*)$/;
-export const TEXT_MAX = 64 * 1024;
-// Trailers the protocol itself interprets; any other trailer belongs to an extension or a profile.
-export const KNOWN = new Set(['to', 're', 'kind', 'state', 'hop', 'assign', 'roles']);
-export const HEARTBEATS = new Set(['ping', 'pong']);
-// Kinds that are bookkeeping, never delivered to an inbox: heartbeats, usage receipts, cards, room records.
-export const HIDDEN = new Set(['ping', 'pong', 'usage', 'card', 'room']);
-export const one = (m, k) => m.trailers[k]?.[0] ?? null;
-// --- text (§3) ---
-const utf8 = new TextDecoder('utf-8', { fatal: true });
-// Invalid text is dangerous bytes: readers treat the message as absent.
-export const decodeText = (buf) => {
-    let s;
-    try {
-        s = utf8.decode(buf);
-    }
-    catch {
-        return { invalid: 'not valid UTF-8' };
-    }
-    s = s.replace(/\r\n/g, '\n');
-    if (/\r/.test(s))
-        return { invalid: 'a CR not followed by LF' };
-    if (CC_RE.test(s))
-        return { invalid: 'control characters in the text' };
-    return { text: s };
-};
-// Parses well-formed and malformed text alike; `bad` names why a message routes nowhere. `isRef` is the store's
-// grammar for message ids in `Re`.
-export const parse = (raw, isRef) => {
-    const text = raw.replace(/\r\n/g, '\n').trimEnd();
-    const cut = text.lastIndexOf('\n\n');
-    const tail = cut < 0 ? [] : text.slice(cut + 2).split('\n');
-    const has = tail.length > 0 && tail.every(l => TRAILER_RE.test(l));
-    const trailers = {};
-    if (has) {
-        for (const l of tail) {
-            const [, k, v] = TRAILER_RE.exec(l);
-            const key = k.toLowerCase();
-            trailers[key] = [...(trailers[key] ?? []), v.trim()];
-        }
-    }
-    const head = has ? text.slice(0, cut) : text;
-    const nl = head.indexOf('\n');
-    const subject = (nl < 0 ? head : head.slice(0, nl)).trim();
-    const bad = [...KNOWN].filter(k => (trailers[k]?.length ?? 0) > 1).map(k => `duplicate ${k}`);
-    const get = (k) => trailers[k]?.[0] ?? null;
-    const ids = (v) => v === null ? null : [...new Set(v.split(',').map(x => x.trim()))];
-    const to = get('to') === '*' ? ['*'] : ids(get('to'));
-    const assign = ids(get('assign'));
-    // Roles: `<id>=<label>, …`; the label `none` clears one.
-    const pairs = get('roles') === null ? null : get('roles').split(',').map(x => x.trim().split('=').map(y => y.trim()));
-    if (pairs && !pairs.every(p => p.length === 2 && ID_RE.test(p[0]) && TOKEN_RE.test(p[1])))
-        bad.push('malformed Roles');
-    if (!subject)
-        bad.push('empty subject');
-    if (Buffer.byteLength(raw) > TEXT_MAX)
-        bad.push('text over 64 KiB');
-    if (!has)
-        bad.push('no trailer block');
-    else if (!to)
-        bad.push('no To');
-    else if (to[0] !== '*' && !to.every(x => ID_RE.test(x)))
-        bad.push('malformed To');
-    if (assign && !assign.every(x => ID_RE.test(x)))
-        bad.push('malformed Assign');
-    if (get('re') !== null && !isRef(get('re')))
-        bad.push('malformed Re');
-    if (get('hop') !== null && !HOP_RE.test(get('hop')))
-        bad.push('malformed Hop');
-    // A state is a token; whether the room's profile knows it is the store's check.
-    if (get('state') !== null && !TOKEN_RE.test(get('state')))
-        bad.push('malformed State');
-    if (get('kind') !== null && !TOKEN_RE.test(get('kind')))
-        bad.push('malformed Kind');
-    const ok = !bad.length;
-    return {
-        subject,
-        body: nl < 0 ? '' : head.slice(nl + 1).replace(/^\n+/, '').trimEnd(),
-        // A malformed message is read as if it had no trailers.
-        to: ok ? to : [],
-        assign: ok ? assign : null,
-        roles: ok && pairs ? Object.fromEntries(pairs) : null,
-        re: ok ? get('re') : null,
-        kind: ok ? get('kind') : null,
-        state: ok ? get('state') : null,
-        hop: ok && get('hop') !== null ? Number(get('hop')) : 0,
-        bad: bad.join(', ') || null,
-        trailers,
-    };
-};
-export const compose = (text, trailers) => `${text}\n\n${trailers.filter(([, v]) => v).map(([k, v]) => `${k}: ${v}`).join('\n')}\n`;
-// A client refuses to write what readers would drop or ignore (§3).
-export const checkOutgoing = (text, isRef) => {
-    const d = decodeText(Buffer.from(text));
-    if (d.invalid !== undefined)
-        fail(`refusing to send: ${d.invalid}`);
-    const m = parse(d.text, isRef);
-    if (m.bad)
-        fail(`refusing to send a malformed message: ${m.bad}`);
-    return m;
-};
-// --- threads (§5) ---
-// Resolves Re and computes effective hops. Invalid messages are absent: a Re naming one does not resolve.
-export const link = (logs) => {
-    const all = new Map();
-    for (const msgs of logs.values())
-        for (const m of msgs)
-            if (!m.invalid)
-                all.set(m.id, m);
-    for (const m of all.values())
-        m.reId = m.re && all.has(m.re) ? m.re : null;
-    const eff = new Map();
-    for (const m of all.values()) {
-        const chain = [];
-        for (let x = m; x && !eff.has(x.id) && chain.length < 100000; x = x.reId ? all.get(x.reId) : undefined)
-            chain.push(x);
-        for (let i = chain.length - 1; i >= 0; i--) {
-            const c = chain[i];
-            eff.set(c.id, Math.max(c.hop, c.reId ? eff.get(c.reId) + 1 : c.re ? 1 : 0));
-        }
-        m.hopEff = eff.get(m.id);
-    }
-    return all;
-};
-// Kahn's order: the answered message before the answer, earlier before later within one log; among the ready ones,
-// the smallest (time, id) goes first.
-export const ordered = (list) => {
-    const byId = new Map(list.map(m => [m.id, m]));
-    const next = new Map(list.map(m => [m.id, []]));
-    const indeg = new Map(list.map(m => [m.id, 0]));
-    const edge = (a, b) => {
-        next.get(a.id).push(b);
-        indeg.set(b.id, indeg.get(b.id) + 1);
-    };
-    const last = new Map();
-    for (const m of [...list].sort((a, b) => a.seq - b.seq)) {
-        if (last.has(m.from))
-            edge(last.get(m.from), m);
-        last.set(m.from, m);
-        if (m.reId && byId.has(m.reId))
-            edge(byId.get(m.reId), m);
-    }
-    const ready = list.filter(m => !indeg.get(m.id));
-    const res = [];
-    while (ready.length) {
-        ready.sort((a, b) => a.time - b.time || (a.id < b.id ? -1 : 1));
-        const m = ready.shift();
-        res.push(m);
-        for (const n of next.get(m.id)) {
-            indeg.set(n.id, indeg.get(n.id) - 1);
-            if (!indeg.get(n.id))
-                ready.push(n);
-        }
-    }
-    return res;
-};
-export const chainHas = (all, m, top) => {
-    for (let x = m, i = 0; x && i < 10000; x = x.reId ? all.get(x.reId) : undefined, i++)
-        if (x === top)
-            return true;
-    return false;
-};
-export const rootOf = (all, m) => {
-    let x = m;
-    for (let i = 0; x.reId && all.has(x.reId) && i < 10000; i++)
-        x = all.get(x.reId);
-    return x;
-};
-export const under = (all, top) => ordered([...all.values()].filter(m => chainHas(all, m, top)));
-export const lookup = (all, ref) => {
-    const key = String(ref ?? '').toLowerCase();
-    if (all.has(key))
-        return all.get(key);
-    const hits = key.length >= 4 ? [...all.keys()].filter(k => k.startsWith(key)) : [];
-    if (hits.length === 1)
-        return all.get(hits[0]);
-    return fail(hits.length ? `ambiguous message id ${ref}` : `unknown message ${ref}`);
-};
-// --- reading (§6) and waking (§7) ---
-// Delivered: well-formed, not a hidden kind, addressed to `id` by name or `*`.
-export const visible = (m, id, hidden) => !m.invalid && !m.bad && !(m.kind && hidden.has(m.kind)) && (m.to.includes(id) || m.to.includes('*'));
-// Wakes: only a direct address. Broadcasts are read when the agent is awake for another reason.
-export const wakes = (m, id, hidden) => visible(m, id, hidden) && m.to.includes(id);
-// Messages for `id` after the per-log cursors; cursors advance only past what was shown.
-export const unread = (logs, id, cursors, limit = Infinity, hidden) => {
-    const fresh = [];
-    for (const [log, msgs] of logs) {
-        if (log === id)
-            continue;
-        const at = msgs.findIndex(m => m.id === cursors[log]);
-        fresh.push(...msgs.slice(at + 1).filter(m => visible(m, id, hidden)));
-    }
-    const queue = ordered(fresh);
-    const shown = queue.slice(0, limit);
-    const seen = new Set(shown.map(m => m.id));
-    const next = { ...cursors };
-    for (const [log, msgs] of logs) {
-        if (log === id)
-            continue;
-        const at = msgs.findIndex(m => m.id === cursors[log]);
-        for (const m of msgs.slice(at + 1)) {
-            if (visible(m, id, hidden) && !seen.has(m.id))
-                break;
-            next[log] = m.id;
-        }
-    }
-    return { msgs: shown, rest: queue.length - shown.length, cursors: next };
-};
-//# sourceMappingURL=index.js.map

package/target/esm/runtime/reader.js

@@ -1,65 +0,0 @@
-// reader: what one reader on this machine accepted of a room: heads, signals, cursors, alarms. Only history that
-// extends what it accepted before, verified by the store, is delivered (docs/spec/hub-1.md, Trust).
-import path from 'node:path';
-import * as Signals from '../domain/signals.js';
-import { HOME, locked, readJson, writeJson } from '../home/index.js';
-import { toMessage } from '../hub/index.js';
-import { fail, note, short } from '../lib/index.js';
-import { link } from '../protocol/index.js';
-export const readerFile = (R, reader) => path.join(HOME, 'readers', R.hub.name, R.genesis, `${reader}.json`);
-export const readerLock = (R, reader, fn) => locked(`reader-${R.hub.name}-${R.genesis.slice(0, 12)}-${reader}`, fn);
-export const loadState = (R, reader) => readJson(readerFile(R, reader), {});
-export const saveState = (R, reader, st) => writeJson(readerFile(R, reader), st);
-// Every log must keep extending what this reader accepted, and the store must verify it (a signed store: every entry
-// signed by the key the room admitted). A log that lost, rewrote or forked accepted history, or fails verification,
-// is quarantined: withheld, its accepted head pinned as evidence. Only `ringi forget` by the operator accepts a new
-// baseline.
-export const loadRoomUnlocked = (R, reader) => {
-    const st = loadState(R, reader);
-    const store = R.hub.store;
-    if (st.control && !store.extends(st.control, R.head)) {
-        fail(`ALARM room ${R.name}: its control history was rewritten (accepted ${short(st.control)}, now ${short(R.head)}). Nothing is delivered; the operator decides`);
-    }
-    st.control = R.head;
-    st.heads ??= {};
-    const alarms = [...store.alarms?.(R.s) ?? []];
-    const logs = new Map();
-    for (const id of new Set([...store.logIds(R.s), ...Object.keys(st.heads)])) {
-        const cur = store.logHead(R.s, id);
-        const acc = st.heads[id];
-        const why = !cur ? `log ${id} was deleted after ${short(acc)}`
-            : acc && !store.extends(acc, cur) ? `log ${id} was rewritten: ${short(cur)} does not extend the accepted ${short(acc)}`
-                : !store.extends(R.genesis, cur) ? `log ${id} does not descend from the room's genesis`
-                    : store.verifyLog(R.s, id, cur);
-        if (why) {
-            alarms.push(why.startsWith('log ') ? why : `log ${id}: ${why}`);
-            continue;
-        }
-        if (acc !== cur) {
-            st.heads[id] = cur;
-            store.pin(R.s, reader, id, cur);
-        }
-        logs.set(id, store.messages(R.s, id, cur).map((x, seq) => toMessage(R, id, x, seq)));
-    }
-    const records = store.signals(R.s);
-    const checked = Signals.check(R, link(logs), records);
-    const signalPins = Signals.pins(records, checked, st.signals);
-    st.signals = signalPins.accepted;
-    alarms.push(...signalPins.alarms, ...checked.filter(x => !x.ok).map(x => `signal ${x.ref}: ${x.why}`));
-    const reported = new Set(st.alarms ?? []);
-    for (const a of alarms)
-        if (!reported.has(a))
-            note(`ALARM ${a}; ${a.startsWith('signal ')
-                ? 'the messages stay the truth; the author restores a missing signal with ringi agent signals --repair'
-                : a.startsWith('commit ') ? 'it is skipped; the room reads on without it'
-                    : `it is quarantined and withheld. Restore it, or the operator runs ringi forget ${R.name}/<log>`}`);
-    st.alarms = alarms;
-    saveState(R, reader, st);
-    return { logs, st };
-};
-export const loadRoom = (R, reader) => readerLock(R, reader, () => loadRoomUnlocked(R, reader));
-export const linked = (R, reader) => {
-    const { logs } = loadRoom(R, reader);
-    return { logs, all: link(logs) };
-};
-//# sourceMappingURL=reader.js.map

package/target/esm/runtime/session.js

@@ -1,116 +0,0 @@
-// session: which chat is which, and which seat it holds. A seat is one (hub, room genesis, agent); it ends only with
-// leave or the operator's explicit takeover. Every agent command passes `bound()` first.
-import fs from 'node:fs';
-import path from 'node:path';
-import crypto from 'node:crypto';
-import { spawnSync } from 'node:child_process';
-import { HOME, guard, locked, readJson, writeJson } from '../home/index.js';
-import { openHub, openRoom, roomNames } from '../hub/index.js';
-import { errno, fail, stamp } from '../lib/index.js';
-export const LEASE = 60 * 60 * 1000;
-const detectProduct = () => {
-    const env = process.env;
-    if (env.CLAUDECODE === '1' || env.CLAUDE_CODE_SESSION_ID)
-        return 'claude';
-    if (Object.keys(env).some(k => k.startsWith('CODEX_')))
-        return 'codex';
-    if (Object.keys(env).some(k => k.startsWith('CURSOR_')))
-        return 'cursor';
-    return null;
-};
-const ancestry = () => {
-    let pid = process.ppid;
-    for (let i = 0; i < 12 && pid > 1; i++) {
-        const r = spawnSync('ps', ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8' });
-        const m = r.status === 0 ? /^\s*(\d+)\s+(.*)$/.exec(String(r.stdout ?? '').trim()) : null;
-        if (!m)
-            return null;
-        const comm = path.basename(m[2].trim()).toLowerCase();
-        if (/^(claude|codex|cursor|cursor-agent)$/.test(comm))
-            return { pid, product: comm.replace('-agent', '') };
-        pid = Number(m[1]);
-    }
-    return null;
-};
-// A chat is known by a stable handle: RINGI_SESSION, else the chat id the UI exposes, else the UI process as a last
-// resort (ps may be denied in a sandbox; then RINGI_SESSION is required).
-export const whoAmI = () => {
-    const env = process.env;
-    const product = detectProduct();
-    if (env.RINGI_SESSION)
-        return { handle: `env:${env.RINGI_SESSION}`, product, pid: null };
-    if (env.CLAUDE_CODE_SESSION_ID)
-        return { handle: `claude:${env.CLAUDE_CODE_SESSION_ID}`, product: 'claude', pid: Number(env.CLAUDE_PID) || null };
-    const a = ancestry() ?? fail('cannot tell which session this is: set RINGI_SESSION to a stable id of this chat (for Codex: its thread id) on every ringi command');
-    return { handle: `pid:${a.pid}`, product: product ?? a.product, pid: a.pid };
-};
-const sessionsDir = () => path.join(HOME, 'sessions');
-const sessionFile = (handle) => path.join(sessionsDir(), `${handle.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 100)}-${crypto.createHash('sha256').update(handle).digest('hex').slice(0, 10)}.json`);
-export const allSessions = () => {
-    let files = [];
-    try {
-        files = fs.readdirSync(sessionsDir()).filter(f => f.endsWith('.json'));
-    }
-    catch { }
-    return files.map(f => readJson(path.join(sessionsDir(), f), null)).filter((s) => !!s?.handle);
-};
-export const readSession = (handle) => {
-    const s = readJson(sessionFile(handle), null);
-    return s?.handle === handle ? s : null;
-};
-export const saveSession = (s) => writeJson(sessionFile(s.handle), s);
-export const dropSession = (handle) => { guard(() => fs.rmSync(sessionFile(handle), { force: true })); };
-export const pidAlive = (pid) => {
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (e) {
-        return errno(e) === 'EPERM';
-    }
-};
-// active: in use within the lease by a living process; stopped: paused by the operator; gone: neither. A gone or
-// stopped binding keeps its seat and scope. A watcher is alive exactly while its process is: a run may outlast any
-// lease.
-export const liveness = (s) => s.state === 'stopped' ? 'stopped'
-    : s.product === 'watch' ? (s.pid && pidAlive(s.pid) ? 'active' : 'gone')
-        : Date.now() - Date.parse(s.lastSeen) < LEASE && (!s.pid || pidAlive(s.pid)) ? 'active' : 'gone';
-export const seatHolder = (hub, genesis, agent, except) => allSessions().find(s => s.hub === hub && s.genesis === genesis && s.agent === agent && s.handle !== except);
-// An explicit chat-to-watch handoff remembers only that chat; it never selects another chat's seat.
-export const ownSession = (handle) => readSession(handle)
-    ?? allSessions().find(s => s.product === 'watch' && s.takenFrom === handle) ?? null;
-// The binding, checked on every agent command: joined, not stopped, room alive and the same room, still a member.
-export const bound = () => {
-    const me = whoAmI();
-    const s = readSession(me.handle) ?? fail(`this session is not in a room. Take part only when the operator says so in this chat:
-  "join <room> as <id>" runs ringi join local <room> --as <id> --scope "<what they delegate>";
-  after a restart, "continue" runs ringi continue.`);
-    if (s.state === 'stopped')
-        fail('this session is stopped: the operator paused it. It reacts to nothing until the operator says "continue" (ringi continue)');
-    const H = openHub(s.hub);
-    const R = openRoom(H, s.room, { quiet: true });
-    if (!R || R.genesis !== s.genesis) {
-        // The room's branch is gone (deleted, archived, or deleted and made anew): the session leaves it on its own. A hub
-        // that cannot be reached fails above and leaves nothing.
-        locked('sessions', () => { if (readSession(me.handle)?.genesis === s.genesis)
-            dropSession(me.handle); });
-        const gone = roomNames(H, true).find(a => a === `${s.room}@${s.genesis.slice(0, 8)}`);
-        fail(gone ? `room ${s.room} was archived as ${gone}; this session left it`
-            : R ? `room ${s.room} was deleted and created again; this session left the old room. The operator joins it anew`
-                : `room ${s.room} is gone from hub ${s.hub}; this session left it`);
-    }
-    if (!R.members[s.agent])
-        fail(`${s.agent} was removed from room ${s.room}; returning needs a fresh join by the operator`);
-    locked('sessions', () => {
-        const cur = readSession(me.handle) ?? fail('this session lost its seat');
-        if (cur.state !== 'active' || cur.genesis !== s.genesis || cur.agent !== s.agent)
-            fail('this session was stopped or its seat changed');
-        saveSession({ ...cur, lastSeen: stamp(), pid: me.pid ?? cur.pid });
-    });
-    return { s, H, R: R, me: s.agent };
-};
-export const parseSelector = (sel) => {
-    const m = /^(?:([a-z0-9._-]+):)?([^/]+)\/([^/]+)$/.exec(sel ?? '');
-    return m ? { hub: m[1] ?? null, room: m[2], agent: m[3] } : fail('a session is named <room>/<agent> or <hub>:<room>/<agent>');
-};
-//# sourceMappingURL=session.js.map