@idleware/ringi 0.4.0 → 0.6.0

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

package/target/esm/runtime/watch.js

@@ -1,321 +0,0 @@
-// watch: headless turns for one agent of one room (core-1 §7). It holds that agent's seat, answers heartbeats in
-// code, and spends only within a grant (decisions-1) or its own run budget. Usage receipts are written here, by the
-// runner, never by the model.
-import { spawn } from 'node:child_process';
-import * as D from '../domain/decisions.js';
-import { HOME, OPERATOR, config, locked } from '../home/index.js';
-import { HIDDEN, append, openHub, openRoom, pongText, start } from '../hub/index.js';
-import { loadRoomUnlocked, loadState, readerLock, saveState } from './reader.js';
-import { isOpen, taskFor, taskOf } from '../domain/profiles.js';
-import { compose, link, unread, wakes } from '../protocol/index.js';
-import { dropSession, liveness, parseSelector, pidAlive, readSession, saveSession, seatHolder, whoAmI } from './session.js';
-import { fail, note, short, sleep, stamp } from '../lib/index.js';
-// One turn: the command runs in a process group of its own (POSIX). At the deadline, or when the command itself
-// ends, whatever is left of the group is asked to stop and, after a grace, killed; the turn ends when the group is
-// empty, so no descendant outlives the run it was counted as.
-const GRACE = 5000;
-const groupAlive = (pid) => {
-    try {
-        process.kill(-pid, 0);
-        return true;
-    }
-    catch (e) {
-        return e.code === 'EPERM';
-    }
-};
-const signalGroup = (pid, sig) => {
-    try {
-        process.kill(-pid, sig);
-    }
-    catch { }
-};
-const turn = (cmd, seconds, env) => new Promise(resolve => {
-    const t0 = Date.now();
-    const child = spawn('sh', ['-c', cmd], { stdio: 'inherit', env, detached: true });
-    const pid = child.pid;
-    let timedOut = false;
-    let exit = null;
-    const end = async () => {
-        signalGroup(pid, 'SIGTERM');
-        const until = Date.now() + GRACE;
-        while (groupAlive(pid) && Date.now() < until)
-            await sleep(50);
-        if (groupAlive(pid))
-            signalGroup(pid, 'SIGKILL');
-        while (groupAlive(pid))
-            await sleep(50);
-        resolve({ code: exit?.code ?? null, signal: exit?.signal ?? null, timedOut, seconds: Math.round((Date.now() - t0) / 1000) });
-    };
-    // At the deadline: SIGTERM to the group, and SIGKILL after the grace even if the shell ignores it.
-    let hard;
-    const timer = seconds ? setTimeout(() => {
-        timedOut = true;
-        signalGroup(pid, 'SIGTERM');
-        hard = setTimeout(() => signalGroup(pid, 'SIGKILL'), GRACE);
-    }, seconds * 1000) : undefined;
-    const stopAll = () => signalGroup(pid, 'SIGTERM');
-    process.once('SIGINT', stopAll);
-    process.once('SIGTERM', stopAll);
-    child.on('exit', (code, signal) => {
-        exit = { code, signal };
-        clearTimeout(timer);
-        clearTimeout(hard);
-        process.removeListener('SIGINT', stopAll);
-        process.removeListener('SIGTERM', stopAll);
-        void end();
-    });
-});
-export const watch = async (w, log = note) => {
-    for (const [name, value] of [['interval', w.interval], ['window', w.window]])
-        if (value !== undefined && (!Number.isFinite(value) || value <= 0))
-            fail(`watch ${name} must be positive seconds`);
-    for (const [name, value] of [['max-runs', w.maxRuns], ['max-hop', w.maxHop]])
-        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0))
-            fail(`watch ${name} must be a nonnegative integer`);
-    const sel = parseSelector(w.seat);
-    const cmd = w.exec;
-    const H0 = openHub(sel.hub ?? w.hub ?? config().hub);
-    const R0 = openRoom(H0, sel.room);
-    const me = sel.agent;
-    if (R0.archived)
-        fail(`${R0.name} is archived`);
-    if (!R0.members[me])
-        fail(`${me} is not a member of ${R0.name}; the operator adds it with a join, or watch another agent`);
-    // Each watcher process is its own session, so two of them can never share one seat record.
-    const raw = `watch-${H0.name}-${R0.genesis.slice(0, 8)}-${me}-${process.pid}`;
-    const handle = `env:${raw}`;
-    locked('sessions', () => {
-        const holder = seatHolder(H0.name, R0.genesis, me, handle);
-        const handoff = w.handoff && holder?.product !== 'watch' && holder?.handle === whoAmI().handle;
-        if (w.handoff && !handoff)
-            fail('watch --handoff needs the invoking chat to own this seat');
-        if (handoff && holder.state === 'stopped')
-            fail('this chat is stopped; continue it before a handoff');
-        if (holder && !handoff && (holder.product !== 'watch' || (holder.pid && pidAlive(holder.pid))))
-            fail(`${R0.name}/${me} is held by session ${holder.handle} (${liveness(holder)}); one seat per agent. Its chat may use watch --handoff`);
-        if (holder)
-            dropSession(holder.handle);
-        saveSession({ handle, product: 'watch', hub: H0.name, room: R0.name, genesis: R0.genesis, agent: me, scope: w.scope ?? holder?.scope ?? null,
-            state: holder?.state === 'stopped' ? 'stopped' : 'active', since: stamp(), lastSeen: stamp(), pid: process.pid,
-            takenFrom: handoff ? holder.handle : holder?.takenFrom });
-    });
-    const interval = (w.interval ?? 5) * 1000;
-    const allow = w.from ? new Set(w.from) : null;
-    const maxHop = w.maxHop ?? 8;
-    const maxRuns = w.maxRuns ?? 10;
-    const span = w.window ?? 86400;
-    let runSeq = 0;
-    for (;;) {
-        const s = locked('sessions', () => {
-            const cur = readSession(handle);
-            if (cur?.state === 'active')
-                saveSession({ ...cur, lastSeen: stamp(), pid: process.pid });
-            return cur;
-        });
-        if (!s) {
-            log(`watch: the seat of ${me} was released or taken over; stopping`);
-            return 0;
-        }
-        if (s.state === 'stopped') {
-            if (w.once) {
-                log('watch: stopped by the operator');
-                return 0;
-            }
-            await sleep(interval);
-            continue;
-        }
-        const H = openHub(H0.name, { refresh: true });
-        const R = openRoom(H, R0.name, { quiet: true });
-        if (!R || R.genesis !== R0.genesis) {
-            // The room's branch is gone: the watcher leaves its seat (a hub it cannot reach fails above and leaves nothing).
-            locked('sessions', () => { if (readSession(handle)?.genesis === R0.genesis)
-                dropSession(handle); });
-            log(`watch: ${R0.name} is gone, recreated or archived; ${me} left it`);
-            return 0;
-        }
-        if (!R.members[me]) {
-            log(`watch: ${me} was removed from ${R0.name}; stopping`);
-            return 0;
-        }
-        // A room waiting for its quorum runs no turn yet.
-        const st = start(R);
-        if (!st.started) {
-            if (w.once) {
-                log(`watch: ${R0.name} waits for a quorum of ${st.quorum} agents and has ${st.agents}; nothing to do yet`);
-                return 0;
-            }
-            await sleep(interval);
-            continue;
-        }
-        const P = R.profile;
-        // Lock order throughout planning and dispatch: grant, reader, sessions (then the store's own writes).
-        const plan = locked(`grant-${H.name}`, () => readerLock(R, me, () => {
-            const { logs, st } = loadRoomUnlocked(R, me);
-            if (st.inflight) {
-                st.seen = st.inflight.seen;
-                st.inflight = undefined;
-                saveState(R, me, st);
-            }
-            const all = link(logs);
-            // Heartbeats: one pong per allowed ping, in code; a separate durable cursor, never a model run.
-            const heartbeatSeen = { ...st.heartbeatSeen };
-            const answered = new Set((logs.get(me) ?? []).filter(m => m.kind === 'pong').map(m => m.reId));
-            for (const [id, msgs] of logs) {
-                if (id === me)
-                    continue;
-                const at = msgs.findIndex(m => m.id === heartbeatSeen[id]);
-                for (const m of msgs.slice(at + 1)) {
-                    if (m.bad || m.kind !== 'ping' || !m.to.includes(me) || answered.has(m.id) || m.hopEff >= maxHop || (allow && !allow.has(m.from)))
-                        continue;
-                    append(R, me, pongText(me, m, 'has a watcher'));
-                    note(`watch: answered heartbeat ${short(m.id)} from ${m.from}`);
-                }
-                if (msgs.length)
-                    heartbeatSeen[id] = msgs.at(-1).id;
-            }
-            const { msgs: fresh, cursors } = unread(logs, me, st.watched ?? st.seen ?? {}, Infinity, HIDDEN);
-            const retry = (st.pending ?? []).flatMap(id => {
-                const m = all.get(id);
-                if (!m)
-                    return [];
-                const task = taskFor(all, m, P);
-                return !task || isOpen(taskOf(all, task, P), P) ? [m] : [];
-            });
-            const msgs = [...new Map([...retry, ...fresh].map(m => [m.id, m])).values()];
-            const go = msgs.filter(m => wakes(m, me, HIDDEN) && m.hopEff < maxHop && (!allow || allow.has(m.from)));
-            for (const m of msgs)
-                if (!go.includes(m))
-                    note(`watch: not waking for ${short(m.id)} from ${m.from} (to ${m.to.join(',')}, hop ${m.hopEff})`);
-            // Group by the grant of each message's work; a message outside a grant spends the watcher's own budget.
-            const groups = new Map();
-            for (const m of go) {
-                const task = taskFor(all, m, P);
-                const g = task ? taskOf(all, task, P).grant : null;
-                if (!groups.has(g))
-                    groups.set(g, { grant: g, msgs: [], task });
-                groups.get(g).msgs.push(m);
-            }
-            const runs = [];
-            let hold = false;
-            const now = Date.now() / 1000;
-            let ownRuns = (st.runs ?? []).filter(t => t > now - span);
-            const exhausted = { ...st.exhausted };
-            for (const grp of groups.values()) {
-                if (!grp.grant) {
-                    if (w.requireGrant) {
-                        for (const m of grp.msgs)
-                            note(`watch: ${short(m.id)} is outside any grant; --require-grant: not starting a turn`);
-                        continue;
-                    }
-                    if (ownRuns.length >= maxRuns) {
-                        hold = true;
-                        note(`watch: own run budget spent (${maxRuns} per ${span}s); ${grp.msgs.length} message(s) wait`);
-                        continue;
-                    }
-                    ownRuns = [...ownRuns, now];
-                    runs.push({ ...grp, timeout: null });
-                    continue;
-                }
-                // The grant lock covers reservation and decisions on this machine.
-                const r = (() => {
-                    // Fence: only the watcher that holds the seat reserves.
-                    if (readSession(handle)?.pid !== process.pid)
-                        return { why: 'this watcher no longer holds the seat', lost: true };
-                    const gr = D.grantOf(all, R.authorityAt, grp.grant);
-                    if (!gr)
-                        return { why: `grant ${short(grp.grant)} is not an approved decision with a budget` };
-                    if (gr.revoked)
-                        return { why: `grant ${short(gr.id)} was revoked`, exhausted: true, gr };
-                    const u = D.usageOf(all, gr);
-                    if (u.left <= 0)
-                        return { why: `grant ${short(gr.id)} is spent: ${u.runs}/${gr.budget.runs} runs`, exhausted: true, gr };
-                    if (u.open >= gr.budget.concurrency)
-                        return { why: `grant ${short(gr.id)} has ${u.open} run(s) open, concurrency ${gr.budget.concurrency}`, wait: true };
-                    const run = `${raw}.${process.pid}.${Date.now().toString(36)}.${runSeq++}`;
-                    append(R, me, compose(`usage: reserve a run of ${me}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', gr.id], ['Usage', 'reserve'], ['Run', run]]));
-                    return { gr, run };
-                })();
-                if (r.lost)
-                    return { runs: [], hold: true, lost: true };
-                if (r.wait) {
-                    hold = true;
-                    note(`watch: ${r.why}; waiting`);
-                    continue;
-                }
-                if (r.why) {
-                    note(`watch: ${r.why}`);
-                    const key = `${grp.task?.id}/${grp.grant}`;
-                    if (r.exhausted && grp.task && !exhausted[key]) {
-                        exhausted[key] = true;
-                        const t = taskOf(all, grp.task, P);
-                        const last = grp.msgs.at(-1);
-                        // The profile names its waiting state, if it has one; otherwise the answer carries no state.
-                        if (isOpen(t, P))
-                            append(R, me, compose(`${r.why}; waiting for a new grant`, [['To', [...new Set([t.requester, OPERATOR])].join(', ')], ['Re', last.id], ['State', P.waiting], ['Hop', String(last.hopEff + 1)]]));
-                    }
-                    continue;
-                }
-                runs.push({ ...grp, run: r.run, timeout: r.gr.budget['run-seconds'] });
-            }
-            const pending = [...new Set([...retry.map(m => m.id), ...runs.flatMap(r => r.msgs.map(m => m.id))])];
-            saveState(R, me, { ...loadState(R, me), heartbeatSeen, exhausted, pending, runs: ownRuns,
-                ...(hold ? {} : { watched: cursors }) });
-            return { runs, hold, lost: false };
-        }));
-        if (plan.lost) {
-            log(`watch: the seat of ${me} was taken over; stopping`);
-            return 0;
-        }
-        let exitCode = 0;
-        const settle = (run, seconds, exit, why) => append(R, me, compose(`usage: settle a run of ${me}${why ? ` (${why})` : ''}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', run.grant], ['Usage', 'settle'], ['Run', run.run], ['Seconds', String(seconds)], ['Exit', String(exit)]]));
-        for (const run of plan.runs) {
-            // Spawn under the same locks as revocation and stop; wait for the turn after releasing them.
-            const next = locked(`grant-${H.name}`, () => {
-                if (run.grant) {
-                    const { logs } = readerLock(R, me, () => loadRoomUnlocked(R, me));
-                    const gr = D.grantOf(link(logs), R.authorityAt, run.grant);
-                    if (!gr || gr.revoked)
-                        return { why: !gr ? 'its grant is no longer valid' : 'its grant was revoked' };
-                }
-                readerLock(R, me, () => {
-                    const st = loadState(R, me);
-                    saveState(R, me, { ...st, inflight: { seen: st.seen ?? {} } });
-                });
-                return locked('sessions', () => {
-                    const cur = readSession(handle);
-                    if (!cur || cur.pid !== process.pid)
-                        return { why: 'the seat was taken over' };
-                    if (cur.state !== 'active')
-                        return { why: 'the watcher was stopped' };
-                    note(`watch: ${run.msgs.length} new${run.grant ? ` under grant ${short(run.grant)}` : ''}: ${cmd}`);
-                    return { done: turn(cmd, run.timeout, { ...process.env, RINGI_HOME: HOME, RINGI_SESSION: raw, RINGI_MSGS: run.msgs.map(m => m.id).join('\n'), RINGI_GRANT: run.grant ?? '' }) };
-                });
-            });
-            if (next.why) {
-                note(`watch: not starting the next turn: ${next.why}`);
-                if (run.run)
-                    settle(run, 0, 125, `not started: ${next.why}`);
-                continue;
-            }
-            const r = await next.done;
-            note(`watch: exit ${r.code ?? r.signal}${r.timedOut ? ' (stopped at the grant\'s run-seconds)' : ''} after ${r.seconds}s`);
-            // Settled only once the whole turn, descendants included, has ended.
-            if (run.run)
-                settle(run, r.seconds, r.code ?? 128);
-            readerLock(R, me, () => {
-                const st = loadState(R, me), delivered = new Set(run.msgs.map(m => m.id));
-                // A deadline is an intentional budget stop, not a delivery failure to spend another run on.
-                const deliveredTurn = r.code === 0 || r.timedOut;
-                saveState(R, me, { ...st, inflight: undefined, ...(deliveredTurn
-                        ? { pending: (st.pending ?? []).filter(id => !delivered.has(id)) }
-                        : { seen: st.inflight?.seen ?? st.seen }) });
-            });
-            if (r.code !== 0 || r.timedOut)
-                exitCode ||= r.code || 128;
-        }
-        if (w.once)
-            return exitCode || (plan.hold ? 4 : 0);
-        await sleep(interval);
-    }
-};
-//# sourceMappingURL=watch.js.map