rrstop

1// §16.5 review stop and spawn caps (spec §7.8, §12.2; research/stop-caps-probe.md "What I did not check").
2// installMod fills __LOG__, __MODE__ (`headless` or `tui`) and __HOLD__, the proxy's agentMark: each request of a
3// `holder` agent gets a 529 from the proxy, so the agent waits on the model until it is stopped, at no token cost.
4// Each phase runs in the main turn.complete hook (a live frame) of the prompt whose text carries its marker.
5// Result: one JSON object at __LOG__/rr-stop.json.
6//
7// headless, default caps (no CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS):
8//   RRSTOP1  TaskStop on an unknown id; holders until the per-plugin cap refuses one; TaskStop on the first holder
9//            while it waits on the model, then once more at once.
10//   RRSTOP2  TaskStop on that stopped holder; a spawn into the slot it freed (`ender`, a real model call); TaskStop
11//            on the other holders.
12//   RRSTOP3  TaskStop on `ender`, which ended by itself.
13// tui, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=1:
14//   RRHOLD   one holder, then a spawn that the per-plugin cap refuses.
15//   RRPEER   the rr-peer plugin (inner, so it acts first) meets the session cap; then the holder stops.
16//   RRCAP    a `capper` agent with maxTurns 2 in the slot the stop freed.
17const FILE = '__LOG__/rr-stop.json';
18const PEER_FILE = '__LOG__/rr-peer.json';
19const MODE = '__MODE__';
20const HOLD = '__HOLD__';
21const PLUGIN = 'rrstop';
22// Shaped like an agent id (`a` + 16 hex), but no task has it.
23const UNKNOWN_ID = 'a0123456789abcdef';
24const MAX_HOLDERS = 25;
25const CAPPER_TASK =
26  'In every reply, write one line that starts with "ROUND <n>:" and call the Glob tool with pattern "*.txt". ' +
27  'Do 5 rounds.';
28
29const state = { mode: MODE, phase: 'idle', pending: null };
30let lastText = '';
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
40// One awaited step; `pending` names it until it settles, so a call that never settles shows in the result.
41const step = async ($, key, fn) => {
42  state.pending = key;
43  await write($);
44  state[key] = await fn();
45  state.pending = null;
46  await write($);
47  return state[key];
48};
49
50const spawn = async ($, tag, type, prompt) => {
51  const at = Date.now();
52  try {
53    const resolved = await $.agent.spawn({ subagentType: `${PLUGIN}:${type}`, description: `probe ${tag}`, prompt });
54    return { tag, at, agentId: resolved?.agentId ?? null, resolved };
55  } catch (err) {
56    return { tag, at, agentId: null, rejected: errOf(err) };
57  }
58};
59
60// §7.8: the stop route; the task id is the agentId.
61const taskStop = async ($, agentId) => {
62  const at = Date.now();
63  try {
64    const resolved = await $.tool.call({ tool: 'TaskStop', task_id: agentId });
65    return { agentId, at, ms: Date.now() - at, resolved };
66  } catch (err) {
67    return { agentId, at, ms: Date.now() - at, rejected: errOf(err) };
68  }
69};
70
71const statusOf = async ($, agentId) => {
72  try {
73    const list = await $.agent.list();
74    const row = (Array.isArray(list) ? list : []).find((agent) => agent.id === agentId);
75    return row?.status ?? 'absent';
76  } catch (err) {
77    return `list-error: ${String(err?.message ?? err).slice(0, 200)}`;
78  }
79};
80
81// §12.2: holders until the per-plugin cap refuses one (`over`); `running` is how many held then.
82const holdUntilCap = async ($) => {
83  state.holders = [];
84  for (let i = 1; i <= MAX_HOLDERS && !state.over; i += 1) {
85    const spawned = await spawn($, `holder ${i}`, 'holder', `Reply with exactly HELD${i}.`);
86    if (spawned.agentId) {
87      state.holders.push(spawned.agentId);
88    } else {
89      state.over = { ...spawned, running: state.holders.length };
90    }
91  }
92  await write($);
93};
94
95// RRSTOP1. The 1.5 s sleep lets the first holder's request reach the proxy and get its 529 (retry-after 20 s).
96const stopFirst = async ($) => {
97  await step($, 'unknown', () => taskStop($, UNKNOWN_ID));
98  await holdUntilCap($);
99  const first = state.holders[0];
100  if (first) {
101    await $.clock.sleep(1500);
102    state.stopAt = Date.now();
103    await step($, 'stopLive', () => taskStop($, first));
104    await step($, 'stopTwice', () => taskStop($, first));
105  }
106  state.phase = 'stopped';
107};
108
109// RRSTOP2: a later dispatch, after the stopped holder's turn.complete, so its slot had time to free.
110const stopEnded = async ($) => {
111  const first = state.holders?.[0];
112  if (first) {
113    state.killedStatus = await statusOf($, first);
114    await step($, 'stopEnded', () => taskStop($, first));
115    await step($, 'slot', () => spawn($, 'ender', 'ender', 'Reply with exactly ENDED.'));
116  }
117  state.cleanup = [];
118  for (const agentId of (state.holders ?? []).slice(1)) {
119    const stopped = await taskStop($, agentId);
120    state.cleanup.push({ agentId, isStopped: String(stopped.resolved?.text ?? '').includes('Successfully stopped') });
121  }
122  state.ender = state.slot?.agentId ? state.slot : await spawn($, 'ender', 'ender', 'Reply with exactly ENDED.');
123  state.phase = state.ender.agentId ? 'ender' : 'done';
124};
125
126// RRSTOP3: `ender` answered and ended on its own before this prompt.
127const stopComplete = async ($) => {
128  state.enderStatus = await statusOf($, state.ender.agentId);
129  await step($, 'stopComplete', () => taskStop($, state.ender.agentId));
130  state.phase = 'done';
131};
132
133const tuiHold = async ($) => {
134  await holdUntilCap($);
135  state.phase = 'held';
136};
137
138// RRPEER: rr-peer's hook is inner, so its spawn settled already; wait up to 3 s for its file all the same.
139const tuiPeer = async ($) => {
140  for (let i = 0; i < 15 && !(await $.fs.exists(PEER_FILE).catch(() => false)); i += 1) {
141    await $.clock.sleep(200);
142  }
143  const first = state.holders?.[0];
144  if (first) {
145    state.stopAt = Date.now();
146    await step($, 'stopLive', () => taskStop($, first));
147  }
148  state.phase = 'stopped';
149};
150
151const tuiCap = async ($) => {
152  await step($, 'capper', () => spawn($, 'capper', 'capper', CAPPER_TASK));
153  state.phase = 'done';
154};
155
156// [marker, phase it starts from, action]
157const PHASES =
158  MODE === 'tui'
159    ? [
160        ['RRHOLD', 'idle', 'hold'],
161        ['RRPEER', 'held', 'peer'],
162        ['RRCAP', 'stopped', 'cap'],
163      ]
164    : [
165        ['RRSTOP1', 'idle', 'first'],
166        ['RRSTOP2', 'stopped', 'ended'],
167        ['RRSTOP3', 'ender', 'complete'],
168      ];
169
170// Each action is called by name: `claude plugin validate` refuses `$` passed through a dynamic call.
171const act = async ($, action) => {
172  if (action === 'hold') {
173    await tuiHold($);
174  } else if (action === 'peer') {
175    await tuiPeer($);
176  } else if (action === 'cap') {
177    await tuiCap($);
178  } else if (action === 'first') {
179    await stopFirst($);
180  } else if (action === 'ended') {
181    await stopEnded($);
182  } else {
183    await stopComplete($);
184  }
185};
186
187const onMainComplete = async ($) => {
188  const phase = PHASES.find(([marker, from]) => lastText.includes(marker) && state.phase === from);
189  if (!phase) {
190    return;
191  }
192  state.phase = 'acting';
193  try {
194    await act($, phase[2]);
195  } catch (err) {
196    state.error = errOf(err);
197    state.phase = 'error';
198  }
199  await write($);
200};
201
202const AGENTS = [
203  {
204    name: 'holder',
205    description: 'Stop probe agent, held by the proxy. The probe spawns it; do not delegate to it.',
206    prompt: `${HOLD}. Reply with the exact word the task asks for. Do not call tools.`,
207    tools: [],
208    maxTurns: 1,
209  },
210  {
211    name: 'ender',
212    description: 'Stop probe agent that ends by itself. The probe spawns it; do not delegate to it.',
213    prompt: 'Reply with the exact word the task asks for. Do not call tools.',
214    tools: [],
215    maxTurns: 1,
216  },
217  {
218    name: 'capper',
219    description: 'maxTurns probe agent. The probe spawns it; do not delegate to it.',
220    prompt: 'Follow the task. Call Glob when it says to.',
221    tools: ['Glob'],
222    maxTurns: 2,
223  },
224];
225
226export const register = (on) => {
227  on('session.start', async ($, e, next) => {
228    for (const agent of AGENTS) {
229      try {
230        await $.agent.register({ ...agent, model: 'haiku', omitClaudeMd: true, background: true });
231      } catch (err) {
232        state.registerError = errOf(err);
233      }
234    }
235    await write($);
236    return next(e);
237  });
238
239  on('agent.offer', async ($, e, next) =>
240    String(e.agent ?? '').startsWith(`${PLUGIN}:`) ? { isOffered: false } : next(e)
241  );
242
243  on('turn.start', async ($, e, next) => {
244    if (!e.agentId) {
245      lastText = String(e.text ?? '');
246    }
247    return next(e);
248  });
249
250  on('turn.complete', async ($, e, next) => {
251    const result = await next(e);
252    if (!e.agentId) {
253      await onMainComplete($);
254    }
255    return result;
256  });
257};
258