NOTT

1// The plugin's one hooks module: the engine loads a single module per plugin.
2import type { Register } from "claude-code";
3
4import { register as idleHandoff } from "./idle-handoff.ts";
5
6export const register: Register = (on, options) => {
7  idleHandoff(on, options);
8};
9

1import type { Register } from "claude-code";
2
3const MIN = 60_000;
4const IDLE_DEFAULT = 50 * MIN;
5const MAX_PINGS = 3;
6const RETRY_MS = 30_000;
7const MAX_RETRIES = 3;
8const SELF = "nott";
9//: The owner's own channels, and a follow-up to his UI action; `unclassified` is not
10//: one: it carries the engine's idle notices and delivery receipts.
11const OWNER = new Set(["composer", "bridge", "slack-ping", "channel", "auto-continuation"]);
12
13const PING = "Reply with the single word: ok.";
14const COMPACT_INSTRUCTIONS =
15  "Keep the last state line (RUNNING/STOPPED/DELIVERED), the nMEMORY handoff capsule id " +
16  "and the next valid action verbatim; keep open decisions and their options.";
17
18function handoffPrompt(nonce: string): string {
19  return [
20    "The session has been idle and the prompt cache is about to expire.",
21    "Load /nott:handoff and record the cold-readable continuation in nMEMORY",
22    "(nmemory_session_finish or nmemory_capsule_ingest), then write the state line with",
23    "`~/.nott/bin/state.sh set \"STOPPED: <reason> · next action: <x>\"`.",
24    "Your whole answer is this exact line:",
25    `HANDOFF-DONE ${nonce}`,
26  ].join("\n");
27}
28
29//: Born in `register`, so each load (a session, a reload, a test) starts afresh.
30type State = {
31  timer: { cancel(): void } | null;
32  background: Set<string>;
33  pings: number;
34  dormant: boolean;
35  headless: boolean;
36  nonce: string | null;
37  handoffStarted: boolean;
38  ownerSeq: number;
39  seqAtFire: number;
40  compactOwed: boolean;
41  retries: number;
42  turnOpen: boolean;
43};
44
45function fresh(): State {
46  return {
47    timer: null,
48    background: new Set(),
49    pings: 0,
50    dormant: false,
51    headless: false,
52    nonce: null,
53    handoffStarted: false,
54    ownerSeq: 0,
55    seqAtFire: 0,
56    compactOwed: false,
57    retries: 0,
58    turnOpen: false,
59  };
60}
61
62function cancel(s: State): void {
63  s.timer?.cancel();
64  s.timer = null;
65}
66
67async function arm($: any, s: State): Promise<void> {
68  cancel(s);
69  const raw = Number(await $.env.get("NOTT_IDLE_HANDOFF_MS"));
70  const ms = Number.isFinite(raw) && raw > 0 ? raw : IDLE_DEFAULT;
71  s.timer = $.clock.after(ms, () => void fire($, s));
72}
73
74function compact($: any, s: State): void {
75  $.clock.after(0, () => void tryCompact($, s));
76}
77
78// ponytail: the owner check runs before the await; an owner prompt queued (not yet a
79// running turn) while the summarizer works is not seen. The engine offers no lock.
80async function tryCompact($: any, s: State): Promise<void> {
81  if (s.ownerSeq !== s.seqAtFire) {
82    s.compactOwed = false;
83    return;
84  }
85  try {
86    const result = await $.session.compact({ instructions: COMPACT_INSTRUCTIONS });
87    s.compactOwed = false;
88    if (result && "skip" in result && result.skip) {
89      $.ui.log("idle-handoff: a hook skipped the compaction", { to: "transcript" });
90    }
91  } catch (err) {
92    s.compactOwed = true;
93    $.ui.log(`idle-handoff: compaction refused (${String(err)}); retrying`, { to: "transcript" });
94    if (s.retries < MAX_RETRIES) {
95      s.retries += 1;
96      $.clock.after(RETRY_MS, () => void retryCompact($, s));
97    }
98  }
99}
100
101async function retryCompact($: any, s: State): Promise<void> {
102  if (s.compactOwed && !s.turnOpen) await tryCompact($, s);
103}
104
105function handedOff($: any, s: State): void {
106  s.nonce = null;
107  s.handoffStarted = false;
108  s.dormant = true;
109  cancel(s);
110  s.retries = 0;
111  compact($, s);
112}
113
114async function fire($: any, s: State): Promise<void> {
115  s.timer = null;
116  if (s.nonce !== null) {
117    //: The last handoff never ended with its marker: one per absence, so sleep until a
118    //: message not its own rather than ask again.
119    s.nonce = null;
120    s.handoffStarted = false;
121    s.dormant = true;
122    return;
123  }
124  if (s.background.size > 0 && s.pings < MAX_PINGS) {
125    s.pings += 1;
126    try {
127      const r = await $.model.fork({ prompt: PING });
128      $.ui.log(
129        r?.isAnswered
130          ? `idle-handoff: keep-warm ping ${s.pings}, cache read ${r.usage.cache_read_input_tokens}`
131          : `idle-handoff: keep-warm ping ${s.pings} not answered (${r?.reason ?? "no result"})`,
132        { to: "debug" },
133      );
134    } catch (err) {
135      //: A refused fork (a blocked model) must not stop the clock.
136      $.ui.log(`idle-handoff: keep-warm ping ${s.pings} refused (${String(err)})`, { to: "debug" });
137    }
138    await arm($, s);
139    return;
140  }
141  s.pings = 0;
142  s.nonce = crypto.randomUUID();
143  s.seqAtFire = s.ownerSeq;
144  await $.prompt.submit({ text: handoffPrompt(s.nonce) });
145}
146
147//: The marker is the message's last line, as the prompt asks: a message that only
148//: announces it mid-sentence does not end the handoff.
149function marked(s: State, text: unknown): boolean {
150  if (s.nonce === null || typeof text !== "string") return false;
151  const body = text.trimEnd();
152  const line = `HANDOFF-DONE ${s.nonce}`;
153  return body === line || body.endsWith(`\n${line}`);
154}
155
156//: A blocking Stop hook continues the same turn, and its final answer then loses the
157//: marker an earlier message of the turn carried. The prompt quotes the marker too,
158//: so only the assistant's messages count.
159async function answered($: any, s: State, e: any): Promise<boolean> {
160  if (e.reason !== "answer") return false;
161  if (marked(s, e.answer)) return true;
162  const messages = await $.session.messages();
163  return messages.some((m: any) => m.role === "assistant" && marked(s, m.text));
164}
165
166//: The id a launch left running in the background, per built-in tool; null when it
167//: ran in the foreground.
168function launched(tool: unknown, r: any): string | null {
169  const x = r?.result;
170  if (x === null || typeof x !== "object") return null;
171  switch (tool) {
172    case "Bash":
173      return x.backgroundTaskId ?? null;
174    case "Monitor":
175    case "Workflow":
176      return x.taskId ?? null;
177    case "Agent":
178      if (x.status === "async_launched") return x.agentId ?? null;
179      if (x.status === "remote_launched") return x.taskId ?? null;
180      return null;
181    default:
182      return null;
183  }
184}
185
186async function onSubmit($: any, e: any, next: any, s: State) {
187  const kind = e.origin?.kind;
188  if (kind === "sdk") s.headless = true;
189  if (kind === "task-notification" && typeof e.text === "string") {
190    for (const id of s.background) if (e.text.includes(`<task-id>${id}</task-id>`)) s.background.delete(id);
191  }
192  if (!(kind === "plugin" && e.origin?.name === SELF)) {
193    s.dormant = false;
194    s.pings = 0;
195  }
196  if (OWNER.has(kind)) {
197    s.ownerSeq += 1;
198    s.nonce = null;
199    s.handoffStarted = false;
200    s.compactOwed = false;
201  }
202  return next(e);
203}
204
205async function onStart($: any, e: any, next: any, s: State) {
206  cancel(s);
207  s.turnOpen = true;
208  //: The handoff turn starts with its own prompt: a notification ahead of it does not.
209  if (s.nonce !== null && typeof e.text === "string" && e.text.includes(s.nonce)) s.handoffStarted = true;
210  return next(e);
211}
212
213// ponytail: a task that ends without a notification stays recorded; MAX_PINGS bounds
214// what it costs, and the next handoff runs anyway.
215async function onTool($: any, e: any, next: any, s: State) {
216  const r = await next(e);
217  const id = launched(e.tool, r);
218  if (id !== null) s.background.add(id);
219  return r;
220}
221
222async function onSessionStart($: any, e: any, next: any, s: State) {
223  cancel(s);
224  Object.assign(s, fresh(), { headless: e.isInteractive === false });
225  return next(e);
226}
227
228async function onComplete($: any, e: any, next: any, s: State) {
229  if (e.agentId) return next(e);
230  s.turnOpen = false;
231  if (s.nonce !== null && (await answered($, s, e))) {
232    handedOff($, s);
233  } else if (s.handoffStarted) {
234    //: The handoff ran and ended without its marker (refused, aborted, failed, or the
235    //: line left out): one per absence, so sleep until a message not its own.
236    s.nonce = null;
237    s.handoffStarted = false;
238    s.dormant = true;
239  } else if (s.compactOwed && s.ownerSeq === s.seqAtFire) {
240    compact($, s);
241  } else if (!s.dormant && !s.headless) {
242    //: Also with a handoff pending: if it never ends with its marker (a hook rewrote its
243    //: prompt), the next fire finds the stale nonce and gives up instead of waiting forever.
244    await arm($, s);
245  }
246  return next(e);
247}
248
249export const register: Register = (on) => {
250  const s = fresh();
251  on("prompt.submit", ($: any, e: any, next: any) => onSubmit($, e, next, s));
252  on("turn.start", ($: any, e: any, next: any) => onStart($, e, next, s));
253  on("tool.call", ($: any, e: any, next: any) => onTool($, e, next, s));
254  on("turn.complete", ($: any, e: any, next: any) => onComplete($, e, next, s));
255  on("session.start", ($: any, e: any, next: any) => onSessionStart($, e, next, s));
256};
257

1// The values the nott plugin's hooks modules keep in `$.state`, read while drawing.
2
3//: One nSPAWN run as the fleet pane draws it.
4export type FleetRun = {
5  runId: string;
6  lane: string;
7  route: string;
8  phase: string;
9  updatedAt: number;
10  //: The child's last output, ms; silence is measured from it.
11  outputAt: number;
12  isLive: boolean;
13};
14
15//: The fleet as last read: when it was last looked at, when it last answered, and the
16//: runs worth showing.
17export type Fleet = { observedAt: number; readAt: number; runs: FleetRun[] };
18
19//: An agent of this session that is still at work.
20export type AgentRow = { id: string; type: string; description: string; status: string; parentId?: string };
21
22//: A workflow this session launched and whose task has not reported its end.
23export type WorkflowRow = { id: string; name: string; startedAt: number };
24
25//: The pull request of the session's branch, reduced to what the band draws.
26export type CampaignPr = {
27  number: number;
28  ok: number;
29  running: number;
30  failed: string[];
31  review: string;
32  merge: string;
33};
34
35//: The band's last reading and, when the latest gh call failed, why: the reading is then
36//: an older one, or null when gh has never answered.
37export type PrReading = { pr: CampaignPr | null; error: string | null };
38
39declare module "claude-code" {
40  interface PluginState {
41    nott: {
42      fleet: Fleet | null;
43      agents: AgentRow[];
44      workflows: WorkflowRow[];
45      pr: PrReading | null;
46    };
47  }
48}
49