@idleware/ringi 0.5.0 → 0.6.1

package/target/esm/{app → core/agents/sessions}/agent.js

@@ -1,13 +1,14 @@
-// Agent operations return data; the runtime owns readers, seats and headless turns.
-import { HIDDEN, append, pongText, start, withSizes } from '../hub/index.js';
-import * as Signals from '../hub/signals.js';
-import { fail, sleep } from '../lib/index.js';
-import { ID_RE, checkOutgoing, compose, link, lookup, unread } from '../protocol/index.js';
-import { linked, loadRoom, loadRoomUnlocked, loadState, readerLock, saveState } from '../runtime/reader.js';
-import { bound } from '../runtime/session.js';
-import { isRef } from './room.js';
-export { bound } from '../runtime/session.js';
-export { watch } from '../runtime/watch.js';
+// agent: what an agent does in its room as itself: read its inbox (marking what it read), take a piece of work, show
+// who it is, leave its card, wait and ping; the headless watcher is turns/.
+import { HIDDEN, append, start, withSizes } from '../../hub/rooms/index.js';
+import * as Signals from '../../hub/signals/write.js';
+import { fail } from '../../../lib/index.js';
+import { ID_RE, checkOutgoing, compose, link, lookup, unread } from '../../hub/protocol/index.js';
+import { linked, loadRoomUnlocked, loadState, readerLock, saveState } from '../../hub/history/index.js';
+import { isRef } from '../../hub/usecases/room.js';
+export { wait } from './wait.js';
+export { bound } from './index.js';
+export { watch } from '../turns/index.js';
 // Whether the agent's room has its quorum and started its work; a room that has not is not read.
 export const started = ({ R }) => start(R);
 export const inbox = ({ R, me }, { peek = false, limit = 20 } = {}) => {
@@ -50,37 +51,4 @@ export const ping = ({ R, me }, { to, text = 'ping: still working', next = 600,
     checkOutgoing(message, isRef(R));
     return { id: append(R, me, message), to, previous: mine ? { id: mine.id, answeredAt: pong?.time ?? null } : null };
 };
-export const wait = async (a, { max = 120, ...options } = {}) => {
-    if (!Number.isFinite(max) || max < 0)
-        fail('wait max must be nonnegative seconds');
-    const start = Date.now(), ponged = new Set();
-    let last = start, silence = Math.min(max, 110);
-    for (;;) {
-        // Each poll renews the lease and checks stop, takeover, membership and the room's identity.
-        const current = bound();
-        if (current.R.genesis !== a.R.genesis || current.me !== a.me)
-            fail('the waiting session changed its binding');
-        const { R, me } = current;
-        const { logs, st } = loadRoom(R, me);
-        if (unread(logs, me, st.seen ?? {}, Infinity, HIDDEN).msgs.length)
-            return { inbox: inbox(current, options), seconds: (Date.now() - start) / 1000 };
-        link(logs);
-        for (const m of logs.get(me) ?? [])
-            if (m.kind === 'pong' && m.reId)
-                ponged.add(m.reId);
-        for (const msgs of logs.values())
-            for (const m of msgs) {
-                if (m.kind !== 'ping' || m.bad || !m.to.includes(me) || ponged.has(m.id))
-                    continue;
-                ponged.add(m.id);
-                last = Date.now();
-                silence = Math.max(silence, Number(m.trailers.next?.[0]) || 600);
-                append(R, me, pongText(me, m, 'is waiting'));
-            }
-        const now = Date.now();
-        if (now - last >= silence * 1000 || now - start >= max * 1000)
-            return { inbox: null, seconds: (now - start) / 1000 };
-        await sleep(Math.min(1000, max * 1000 - (now - start)));
-    }
-};
 //# sourceMappingURL=agent.js.map

package/target/esm/core/agents/sessions/binding.js

@@ -0,0 +1,43 @@
+// binding: the seat a chat holds, checked on every agent command: joined, not stopped, its room alive and the same
+// room, still a member; a chat whose room is gone leaves it on its own.
+import { locked } from '../../hub/ports/index.js';
+import { openHub, openRoom, roomNames } from '../../hub/rooms/index.js';
+import { fail, stamp } from '../../../lib/index.js';
+import { dropSession, readSession, saveSession, whoAmI } from './index.js';
+// 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 });
+    checkRoomIdentity(me, s, H, R);
+    if (!R.members[s.agent])
+        fail(`${s.agent} was removed from room ${s.room}; returning needs a fresh join by the operator`);
+    renewSession(me, s);
+    return { s, H, R: R, me: s.agent };
+};
+const checkRoomIdentity = (me, s, H, R) => {
+    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`);
+    }
+};
+const renewSession = (me, s) => {
+    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 });
+    });
+};
+//# sourceMappingURL=binding.js.map

package/target/esm/core/agents/sessions/context.js

@@ -0,0 +1,11 @@
+// context: who acts as an agent — the agent this session is bound to — and what the agent tools this machine
+// knows need from an interface: where they read skills, and what lets their sandboxes write.
+import { agentPorts } from '../ports/index.js';
+import { bound } from './index.js';
+// The agent this session is bound to; refuses when it is not joined, is stopped, or its room is gone.
+export const agent = () => bound();
+// Where the agent tools this machine knows read skills, under a base directory (the user's home or a project).
+export const skillDirs = (base) => agentPorts().tools.flatMap(t => t.skillDirs?.(base) ?? []);
+// What lets each tool's sandbox write a path.
+export const sandboxHints = (where) => agentPorts().tools.flatMap(t => t.sandboxHint ? [t.sandboxHint(where)] : []);
+//# sourceMappingURL=context.js.map

package/target/esm/core/agents/sessions/index.js

@@ -0,0 +1,59 @@
+// sessions: the chats on this machine that hold a seat in a room: who this chat is (its handle, from the agent tool
+// it runs in), the session records, and whether each is active, stopped or gone.
+import crypto from 'node:crypto';
+import { hubPorts } from '../../hub/ports/index.js';
+import { agentPorts } from '../ports/index.js';
+import { fail } from '../../../lib/index.js';
+export { bound } from './binding.js';
+const LEASE = 60 * 60 * 1000;
+// The tool this process runs in, by its environment (core/agents/ports/tools.ts).
+const detectProduct = () => agentPorts().tools.find(t => t.detect(process.env))?.id ?? null;
+// The tool's process among this process's ancestors, by its name.
+const ancestry = () => {
+    for (const { pid, name } of agentPorts().host.ancestors(process.ppid)) {
+        const tool = agentPorts().tools.find(t => t.processes?.includes(name));
+        if (tool)
+            return { pid, product: tool.id };
+    }
+    return null;
+};
+// A chat is known by a stable handle: RINGI_SESSION, else the session id its tool exposes, else the tool's 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 };
+    for (const t of agentPorts().tools) {
+        const s = t.session?.(env);
+        if (s)
+            return { ...s, product: t.id };
+    }
+    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 };
+};
+// Each session is a record of the machine's state under `sessions`, named after its handle.
+const sessionKey = (handle) => ['sessions', `${handle.replace(/[^A-Za-z0-9._-]/g, '_').slice(0, 100)}-${crypto.createHash('sha256').update(handle).digest('hex').slice(0, 10)}`];
+export const allSessions = () => hubPorts().state.list(['sessions']).map(n => hubPorts().state.read(['sessions', n], null)).filter((s) => !!s?.handle);
+export const readSession = (handle) => {
+    const s = hubPorts().state.read(sessionKey(handle), null);
+    return s?.handle === handle ? s : null;
+};
+export const saveSession = (s) => hubPorts().state.write(sessionKey(s.handle), s);
+export const dropSession = (handle) => hubPorts().state.remove(sessionKey(handle));
+export const pidAlive = (pid) => agentPorts().host.alive(pid);
+// 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;
+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=index.js.map

package/target/esm/core/agents/sessions/join.js

@@ -0,0 +1,55 @@
+// join: a chat takes a seat in a room as an agent, one room per chat; on a signed hub its key must be admitted first.
+import { locked } from '../../hub/ports/index.js';
+import { OPERATOR, controlChange, openHub, room as roomOf } from '../../hub/rooms/index.js';
+import { fail, note, stamp } from '../../../lib/index.js';
+import { AGENT_RE } from '../../hub/protocol/index.js';
+import { dropSession, liveness, ownSession, pidAlive, readSession, saveSession, seatHolder, whoAmI } from './index.js';
+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 (!AGENT_RE.test(agent) || agent === OPERATOR)
+        fail(`bad agent id ${agent}: lowercase letters, digits, - and _, no dot`);
+    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', () => claimSession({ me, H, R, agent, room, scope }));
+    return { agent, hub: H.name, room: R.name, session: readSession(me.handle), key: null };
+};
+const claimSession = (c) => {
+    const { me, H, R, agent, scope } = c;
+    const mine = previousSession(c);
+    const same = !!mine && mine.hub === H.name && mine.genesis === R.genesis && mine.agent === agent;
+    ensureMember(c);
+    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
+    });
+};
+const previousSession = ({ me, H, R, agent, room }) => {
+    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);
+    return mine;
+};
+const ensureMember = ({ H, R, agent, room }) => {
+    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() }; });
+    }
+};
+//# sourceMappingURL=join.js.map

package/target/esm/core/agents/sessions/resume.js

@@ -0,0 +1,54 @@
+// resume: a chat continues its own seat after a restart, or takes over one the operator names.
+import { hubPorts, locked } from '../../hub/ports/index.js';
+import { fail, note, stamp } from '../../../lib/index.js';
+import { allSessions, dropSession, liveness, ownSession, parseSelector, pidAlive, saveSession, whoAmI } from './index.js';
+export const resume = (selector) => {
+    const me = whoAmI();
+    hubPorts().state.ensure();
+    return locked('sessions', () => {
+        const target = selectTarget(me, selector);
+        takeOver(me, target);
+        const session = resumed(me, target);
+        saveSession(session);
+        return session;
+    });
+};
+const selectTarget = (me, selector) => {
+    if (!selector) {
+        return ownTarget(me);
+    }
+    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}`);
+        return hits[0] ?? fail(`no session holds ${selector}; the operator joins this chat with ringi join`);
+    }
+};
+const ownTarget = (me) => {
+    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')}`);
+    }
+    return mine;
+};
+const takeOver = (me, target) => {
+    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 resumed = (me, target) => {
+    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
+    };
+    return session;
+};
+//# sourceMappingURL=resume.js.map

package/target/esm/core/agents/sessions/session.js

@@ -0,0 +1,28 @@
+// session: what the operator says in an agent's chat: join, continue (with a briefing of the room), stop, leave.
+import { locked } from '../../hub/ports/index.js';
+import { start } from '../../hub/rooms/index.js';
+import { fail, stamp } from '../../../lib/index.js';
+import { bound, dropSession, ownSession, saveSession, whoAmI } from './index.js';
+import { inbox } from './agent.js';
+import { tasks } from '../../hub/usecases/room.js';
+export { resume } from './resume.js';
+export { join } from './join.js';
+export { bound } from './index.js';
+// A room still waiting for its agents is not read: nothing is marked seen before its work starts.
+export const briefing = (s) => {
+    const actor = bound();
+    const st = start(actor.R);
+    return { session: s, actor, start: st, tasks: st.started ? tasks(actor).views : [], inbox: st.started ? inbox(actor) : null };
+};
+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/core/agents/sessions/wait.js

@@ -0,0 +1,47 @@
+// wait: an agent holds the line until something new arrives for it or the room falls silent, answering pings.
+import { HIDDEN, append, pongText } from '../../hub/rooms/index.js';
+import { fail, sleep } from '../../../lib/index.js';
+import { link, unread } from '../../hub/protocol/index.js';
+import { loadRoom } from '../../hub/history/index.js';
+import { bound } from './index.js';
+import { inbox } from './agent.js';
+export const wait = async (a, { max = 120, ...options } = {}) => {
+    if (!Number.isFinite(max) || max < 0)
+        fail('wait max must be nonnegative seconds');
+    const start = Date.now(), ponged = new Set();
+    let last = start, silence = Math.min(max, 110);
+    for (;;) {
+        // Each poll renews the lease and checks stop, takeover, membership and the room's identity.
+        const current = bound();
+        if (current.R.genesis !== a.R.genesis || current.me !== a.me)
+            fail('the waiting session changed its binding');
+        const { R, me } = current;
+        const { logs, st } = loadRoom(R, me);
+        if (unread(logs, me, st.seen ?? {}, Infinity, HIDDEN).msgs.length)
+            return { inbox: inbox(current, options), seconds: (Date.now() - start) / 1000 };
+        link(logs);
+        const state = { last, silence, ponged };
+        answerPings(current, logs, state);
+        last = state.last;
+        silence = state.silence;
+        const now = Date.now();
+        if (now - last >= silence * 1000 || now - start >= max * 1000)
+            return { inbox: null, seconds: (now - start) / 1000 };
+        await sleep(Math.min(1000, max * 1000 - (now - start)));
+    }
+};
+const answerPings = (a, logs, state) => {
+    for (const m of logs.get(a.me) ?? [])
+        if (m.kind === 'pong' && m.reId)
+            state.ponged.add(m.reId);
+    for (const msgs of logs.values())
+        for (const m of msgs) {
+            if (m.kind !== 'ping' || m.bad || !m.to.includes(a.me) || state.ponged.has(m.id))
+                continue;
+            state.ponged.add(m.id);
+            state.last = Date.now();
+            state.silence = Math.max(state.silence, Number(m.trailers.next?.[0]) || 600);
+            append(a.R, a.me, pongText(a.me, m, 'is waiting'));
+        }
+};
+//# sourceMappingURL=wait.js.map

package/target/esm/core/agents/turns/budgets.js

@@ -0,0 +1,48 @@
+// budgets: which groups of messages may start a turn now: within a grant's budget, or within the watcher's own run
+// limit when no grant covers them.
+import { note, short } from '../../../lib/index.js';
+import { reportExhausted } from './exhaustion.js';
+import { reserveGrant } from './grants.js';
+const ownRun = (c, grp, p, now) => {
+    if (c.w.requireGrant) {
+        for (const m of grp.msgs)
+            note(`watch: ${short(m.id)} is outside any grant; --require-grant: not starting a turn`);
+        return;
+    }
+    if (p.ownRuns.length >= c.maxRuns) {
+        p.hold = true;
+        note(`watch: own run budget spent (${c.maxRuns} per ${c.span}s); ${grp.msgs.length} message(s) wait`);
+        return;
+    }
+    p.ownRuns = [...p.ownRuns, now];
+    p.runs.push({ ...grp, timeout: null });
+};
+const grantedRun = ({ c, R, all, grp, r, p }) => {
+    if (r.wait) {
+        p.hold = true;
+        note(`watch: ${r.why}; waiting`);
+        return;
+    }
+    if (r.why) {
+        note(`watch: ${r.why}`);
+        reportExhausted({ c, R, all, grp, r, p });
+        return;
+    }
+    p.runs.push({ ...grp, run: r.run, timeout: r.gr.budget['run-seconds'] });
+};
+export const reserveGroups = (c, R, all, groups, st) => {
+    const now = Date.now() / 1000;
+    const p = { runs: [], hold: false, lost: false, ownRuns: (st.runs ?? []).filter(t => t > now - c.span), exhausted: { ...st.exhausted } };
+    for (const grp of groups.values()) {
+        if (!grp.grant) {
+            ownRun(c, grp, p, now);
+            continue;
+        }
+        const r = reserveGrant(c, R, all, grp);
+        if (r.lost)
+            return { ...p, runs: [], hold: true, lost: true };
+        grantedRun({ c, R, all, grp, r, p });
+    }
+    return p;
+};
+//# sourceMappingURL=budgets.js.map

package/target/esm/core/agents/turns/dispatch.js

@@ -0,0 +1,40 @@
+// dispatch: a planned turn is started through the process host, still holding the seat and a valid grant.
+import * as D from '../../hub/decisions/index.js';
+import { hubPorts, locked } from '../../hub/ports/index.js';
+import { fail, note, short } from '../../../lib/index.js';
+import { link } from '../../hub/protocol/index.js';
+import { loadRoomUnlocked, loadState, readerLock, saveState } from '../../hub/history/index.js';
+import { readSession } from '../sessions/index.js';
+import { agentPorts } from '../ports/index.js';
+const grantProblem = (c, R, run) => {
+    if (!run.grant)
+        return undefined;
+    const { logs } = readerLock(R, c.me, () => loadRoomUnlocked(R, c.me));
+    const gr = D.grantOf(link(logs), R.authorityAt, run.grant);
+    return !gr ? 'its grant is no longer valid' : gr.revoked ? 'its grant was revoked' : undefined;
+};
+const spawnTurn = (c, run) => locked('sessions', () => {
+    const cur = readSession(c.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)}` : ''}: ${c.cmd}`);
+    return {
+        done: agentPorts().host.awaitQuiescence(agentPorts().host.start({ shell: c.cmd, timeout: run.timeout, env: {
+                ...process.env, RINGI_HOME: hubPorts().state.root, RINGI_SESSION: c.raw,
+                RINGI_MSGS: run.msgs.map(m => m.id).join('\n'), RINGI_GRANT: run.grant ?? ''
+            } })).then(result => result ?? fail('the process host did not settle the turn'))
+    };
+});
+export const dispatch = (c, R, run) => locked(`grant-${R.hub.name}`, () => {
+    const why = grantProblem(c, R, run);
+    if (why)
+        return { why };
+    readerLock(R, c.me, () => {
+        const st = loadState(R, c.me);
+        saveState(R, c.me, { ...st, inflight: { seen: st.seen ?? {} } });
+    });
+    return spawnTurn(c, run);
+});
+//# sourceMappingURL=dispatch.js.map

package/target/esm/core/agents/turns/exhaustion.js

@@ -0,0 +1,16 @@
+// exhaustion: a piece of work whose grant is spent or revoked waits for a new grant, said once in its thread.
+import { isOpen, taskOf } from '../../hub/work/index.js';
+import { OPERATOR, append } from '../../hub/rooms/index.js';
+import { compose } from '../../hub/protocol/index.js';
+export const reportExhausted = ({ c, R, all, grp, r, p }) => {
+    const key = `${grp.task?.id}/${grp.grant}`;
+    if (!r.exhausted || !grp.task || p.exhausted[key])
+        return;
+    p.exhausted[key] = true;
+    const t = taskOf(all, grp.task, R.profile), last = grp.msgs.at(-1);
+    if (isOpen(t, R.profile))
+        append(R, c.me, compose(`${r.why}; waiting for a new grant`, [
+            ['To', [...new Set([t.requester, OPERATOR])].join(', ')], ['Re', last.id], ['State', R.profile.waiting], ['Hop', String(last.hopEff + 1)]
+        ]));
+};
+//# sourceMappingURL=exhaustion.js.map

package/target/esm/core/agents/turns/grants.js

@@ -0,0 +1,36 @@
+// grants: a run reserved under a grant: approved, not revoked, not spent, within its concurrency.
+import * as D from '../../hub/decisions/index.js';
+import { OPERATOR, append } from '../../hub/rooms/index.js';
+import { short } from '../../../lib/index.js';
+import { compose } from '../../hub/protocol/index.js';
+import { readSession } from '../sessions/index.js';
+const grantStatus = (gr) => {
+    if (gr.revoked)
+        return { why: `grant ${short(gr.id)} was revoked`, exhausted: true, gr };
+    return { gr };
+};
+const remaining = (all, 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 };
+    return { gr };
+};
+export const reserveGrant = (c, R, all, grp) => {
+    if (readSession(c.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` };
+    const status = grantStatus(gr);
+    if (status.why)
+        return status;
+    const balance = remaining(all, gr);
+    if (balance.why)
+        return balance;
+    const run = `${c.raw}.${process.pid}.${Date.now().toString(36)}.${c.runSeq++}`;
+    append(R, c.me, compose(`usage: reserve a run of ${c.me}`, [['To', OPERATOR], ['Kind', 'usage'], ['Grant', gr.id], ['Usage', 'reserve'], ['Run', run]]));
+    return { gr, run };
+};
+//# sourceMappingURL=grants.js.map

package/target/esm/core/agents/turns/index.js

@@ -0,0 +1,33 @@
+// turns: the headless watcher: it holds one agent's seat, wakes a command for what arrives, and charges only its own
+// reservations and receipts.
+import { note, sleep } from '../../../lib/index.js';
+import { planTurns } from './plan.js';
+import { pollWatcher } from './poll.js';
+import { runTurns } from './results.js';
+import { createWatcher } from './seat.js';
+export const watch = async (w, log = note) => {
+    const c = createWatcher(w, log);
+    for (;;) {
+        const done = await watchTick(c);
+        if (done !== undefined)
+            return done;
+        await sleep(c.interval);
+    }
+};
+const watchTick = async (c) => {
+    const poll = pollWatcher(c);
+    if (poll.done)
+        return 0;
+    if (poll.R) {
+        const plan = planTurns(c, poll.R);
+        if (plan.lost) {
+            c.log(`watch: the seat of ${c.me} was taken over; stopping`);
+            return 0;
+        }
+        const exitCode = await runTurns(c, poll.R, plan.runs);
+        if (c.w.once)
+            return exitCode || (plan.hold ? 4 : 0);
+    }
+    return undefined;
+};
+//# sourceMappingURL=index.js.map

package/target/esm/core/agents/turns/limits.js

@@ -0,0 +1,11 @@
+// limits: the watcher's options checked before it starts.
+import { fail } from '../../../lib/index.js';
+export const validateWatch = (w) => {
+    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`);
+};
+//# sourceMappingURL=limits.js.map

package/target/esm/core/agents/turns/messages.js

@@ -0,0 +1,32 @@
+// messages: what wakes the watcher: new messages for its agent and retries of failed turns, grouped by grant and work.
+import { isOpen, taskFor, taskOf } from '../../hub/work/index.js';
+import { HIDDEN } from '../../hub/rooms/index.js';
+import { note, short } from '../../../lib/index.js';
+import { unread, wakes } from '../../hub/protocol/index.js';
+export const collectMessages = (c, R, logs, st, all) => {
+    const { msgs: fresh, cursors } = unread(logs, c.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, R.profile);
+        return !task || isOpen(taskOf(all, task, R.profile), R.profile) ? [m] : [];
+    });
+    const msgs = [...new Map([...retry, ...fresh].map(m => [m.id, m])).values()];
+    const go = msgs.filter(m => wakes(m, c.me, HIDDEN) && m.hopEff < c.maxHop && (!c.allow || c.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})`);
+    return { retry, cursors, go };
+};
+export const groupMessages = (R, all, go) => {
+    const groups = new Map();
+    for (const m of go) {
+        const task = taskFor(all, m, R.profile), g = task ? taskOf(all, task, R.profile).grant : null;
+        if (!groups.has(g))
+            groups.set(g, { grant: g, msgs: [], task });
+        groups.get(g).msgs.push(m);
+    }
+    return groups;
+};
+//# sourceMappingURL=messages.js.map

package/target/esm/core/agents/turns/pings.js

@@ -0,0 +1,30 @@
+// pings: the watcher answers pings for its agent without waking a model.
+import { append, pongText } from '../../hub/rooms/index.js';
+import { note, short } from '../../../lib/index.js';
+const allowed = (c, m, answered) => {
+    const ping = !m.bad && m.kind === 'ping' && m.to.includes(c.me);
+    const wake = m.hopEff < c.maxHop && (!c.allow || c.allow.has(m.from));
+    return ping && !answered.has(m.id) && wake;
+};
+const answerAuthor = (c, R, msgs, last, answered) => {
+    const at = msgs.findIndex(m => m.id === last);
+    for (const m of msgs.slice(at + 1)) {
+        if (!allowed(c, m, answered))
+            continue;
+        append(R, c.me, pongText(c.me, m, 'has a watcher'));
+        note(`watch: answered heartbeat ${short(m.id)} from ${m.from}`);
+    }
+};
+export const answerWatchPings = (c, R, logs, st) => {
+    const heartbeatSeen = { ...st.heartbeatSeen };
+    const answered = new Set((logs.get(c.me) ?? []).filter(m => m.kind === 'pong').map(m => m.reId));
+    for (const [id, msgs] of logs) {
+        if (id === c.me)
+            continue;
+        answerAuthor(c, R, msgs, heartbeatSeen[id], answered);
+        if (msgs.length)
+            heartbeatSeen[id] = msgs.at(-1).id;
+    }
+    return heartbeatSeen;
+};
+//# sourceMappingURL=pings.js.map