rrspawn

1// §16.5 spawn sites (spec §7.2, §10.3; research/spawn-sites.md "Not checked"). One -p session that stream-json input
2// keeps open. installMod fills __LOG__. Four sites, each spawning one `reviewer` (tool Glob):
3//   step  the main turn.step hook at index >= 1, awaited before the hook returns (a live frame);
4//   tool  the tool.call hook of the main loop's Read, awaited before the hook returns (a live frame);
5//   busy  a $.clock.after callback armed at main step 0, so it spawns and submits while that turn runs;
6//   idle  a $.clock.after callback 3 s after the last main turn.complete, while -p is idle but still open.
7// The `on('*')` registration is the witness: it counts each agent's events that reach this module through another
8// registration than the spawning one. `stepHook`, `toolHook` and `completeHook` count what the turn.step, tool.call
9// and turn.complete registrations themselves saw of each agent. Result: __LOG__/rr-spawn.json.
10const FILE = '__LOG__/rr-spawn.json';
11const PLUGIN = 'rrspawn';
12const BUSY_MS = 400;
13const IDLE_MS = 3000;
14const IDLE_TRIES = 20;
15const SUBMITS = { busy: 'Reply with the single word CLOCKED.', idle: 'Reply with the single word IDLED.' };
16
17const state = {
18  phase: 'idle',
19  turnRunning: false,
20  mainStarts: 0,
21  mainCompletes: 0,
22  sites: {},
23  ends: {},
24  witness: {},
25  stepHook: {},
26  toolHook: {},
27  completeHook: {},
28};
29let idleTimer = null;
30let idleTries = 0;
31let writing = Promise.resolve();
32
33const errOf = (err) => ({ name: err?.name ?? 'Error', message: String(err?.message ?? err).slice(0, 800) });
34
35const write = ($) => {
36  writing = writing.then(() => $.fs.write(FILE, JSON.stringify(state))).catch(() => undefined);
37  return writing;
38};
39
40const bump = (map, agentId, key = 'count') => {
41  map[agentId] = map[agentId] ?? {};
42  map[agentId][key] = (map[agentId][key] ?? 0) + 1;
43};
44
45const spawn = async ($, tag) => {
46  const at = Date.now();
47  try {
48    const resolved = await $.agent.spawn({
49      subagentType: `${PLUGIN}:reviewer`,
50      description: `probe ${tag}`,
51      prompt: `Call the Glob tool once with pattern "*.txt". Then reply with exactly DONE-${tag}.`,
52    });
53    return { tag, at, agentId: resolved?.agentId ?? null, resolved };
54  } catch (err) {
55    return { tag, at, agentId: null, rejected: errOf(err) };
56  }
57};
58
59// The busy and idle sites: a bare frame (§7.2), so no hook of this plugin sees what these calls cause.
60const clockSite = async ($, tag) => {
61  const duringTurn = state.turnRunning;
62  const spawned = await spawn($, tag);
63  let submit;
64  try {
65    submit = { resolved: await $.prompt.submit({ text: SUBMITS[tag] }) };
66  } catch (err) {
67    submit = { rejected: errOf(err) };
68  }
69  state.sites[tag] = { ...spawned, duringTurn, submit, doneAt: Date.now() };
70  await write($);
71};
72
73// §10.3: the -p idle case. Re-armed while a main turn runs (the busy submit can start one), at most IDLE_TRIES times.
74const onIdle = async ($) => {
75  if (state.sites.idle) {
76    return;
77  }
78  if (state.turnRunning && idleTries < IDLE_TRIES) {
79    idleTries += 1;
80    idleTimer = $.clock.after(IDLE_MS, () => onIdle($));
81    return;
82  }
83  await clockSite($, 'idle');
84};
85
86const armIdle = ($) => {
87  if (state.sites.idle) {
88    return;
89  }
90  idleTimer?.cancel();
91  idleTimer = $.clock.after(IDLE_MS, () => onIdle($));
92};
93
94export const register = (on) => {
95  on('session.start', async ($, e, next) => {
96    try {
97      await $.agent.register({
98        name: 'reviewer',
99        description: 'Spawn-site probe agent. The probe spawns it; do not delegate to it.',
100        prompt: 'Do the task in as few steps as it says. Use only the tool it names.',
101        tools: ['Glob'],
102        model: 'haiku',
103        omitClaudeMd: true,
104        background: true,
105        maxTurns: 3,
106      });
107    } catch (err) {
108      state.registerError = errOf(err);
109    }
110    await write($);
111    return next(e);
112  });
113
114  on('agent.offer', async ($, e, next) =>
115    String(e.agent ?? '').startsWith(`${PLUGIN}:`) ? { isOffered: false } : next(e)
116  );
117
118  // The witness: every event that carries an agent's id and reaches this registration.
119  on('*', async ($, e, next) => {
120    if (typeof e?.agentId === 'string' && e.agentId !== '') {
121      bump(state.witness, e.agentId, next.event);
122    }
123    return next(e);
124  });
125
126  on('turn.start', async ($, e, next) => {
127    if (!e.agentId) {
128      state.turnRunning = true;
129      state.mainStarts += 1;
130    }
131    return next(e);
132  });
133
134  // §7.2: the step site spawns after its step's stream ended, before the hook returns.
135  on('turn.step', async function* ($, e, next) {
136    if (e.agentId) {
137      bump(state.stepHook, e.agentId);
138      return yield* next(e);
139    }
140    const result = yield* next(e);
141    if (e.index === 0 && !state.busyArmed) {
142      state.busyArmed = true;
143      $.clock.after(BUSY_MS, () => clockSite($, 'busy'));
144    }
145    if (e.index >= 1 && !state.sites.step) {
146      state.sites.step = { ...(await spawn($, 'step')), index: e.index };
147      await write($);
148    }
149    return result;
150  });
151
152  // The tool site: the main loop's Read, after its result, before the hook returns.
153  on('tool.call', async ($, e, next) => {
154    if (e.agentId) {
155      bump(state.toolHook, e.agentId);
156      return next(e);
157    }
158    const result = await next(e);
159    if (e.tool === 'Read' && !state.sites.tool) {
160      state.sites.tool = await spawn($, 'tool');
161      await write($);
162    }
163    return result;
164  });
165
166  on('turn.complete', async ($, e, next) => {
167    const result = await next(e);
168    if (e.agentId) {
169      bump(state.completeHook, e.agentId);
170      const answer = String(e.answer ?? '').slice(0, 200);
171      state.ends[e.agentId] = { reason: e.reason ?? null, answer, at: Date.now() };
172    } else {
173      state.turnRunning = false;
174      state.mainCompletes += 1;
175      armIdle($);
176    }
177    await write($);
178    return result;
179  });
180};
181