session

1// The session plugin's hooks module (design/mod-r1.md §6 S1, packet M1): one read-only band
2// above the prompt. At session.start it runs `agentik-session mod start` (5 s), which writes
3// mod.json and prints the session's directory; the band reads meter.json and respawn.json
4// there and draws one line, and admission's band.json a second (packet S27b). It writes no
5// file, keeps no figure a decision reads, and needs no sibling plugin. The classic hooks in
6// hooks.json decide everything; this only shows.
7//
8// It is the plugin's one module (2.1.296 loads one per plugin and one unmatched hook per
9// event), and it carries admission's code too, under its own heading below (packet S25
10// ruling 1: the engine follows `$` into a function of this same file only, never across an
11// import, so admission's handlers cannot live in a sibling file). Its session.start and
12// turn.complete run the band's part and admission's, each part's failure caught so neither
13// skips the other or `next`; admission's other four hooks are registered once. Its one
14// session.measure handler runs the measure's part (packet M2, below admission's heading) and
15// admission's reading, each bounded and caught, after `next`.
16import type { EngineInterface, Register } from 'claude-code'
17
18const STALE_S = 120
19const EVERY_MS = 5000
20const MAX_TRIES = 24      // `mod start` retried while the dir is unknown: 2 min of ticks
21const NO_METER = 'session: no meter · agentik-session doctor'
22// agentik-r1 §6.3 c11 (packet ruling 7): the tool by its new name; when that is not on PATH
23// (the run rejects, not found), its old name, the alias until r2.
24const TOOL = 'agentik-session'
25const OLD_TOOL = 'claude-session'
26const notFound = (err: any): boolean => /ENOENT|not found/i.test(String(err?.message ?? err))
27async function runTool($: EngineInterface, argv: string[], opts: any): Promise<any> {
28  try {
29    return await $.process.run(argv, opts)
30  } catch (err) {
31    if (argv[0] !== TOOL || !notFound(err)) throw err
32    return await $.process.run([OLD_TOOL, ...argv.slice(1)], opts)
33  }
34}
35
36const clip = (line: string, columns: number): string =>
37  columns > 0 && line.length > columns ? line.slice(0, Math.max(1, columns - 1)) + '…' : line
38
39const pct = (n: unknown): string => `${Math.round(Number(n))}%`
40
41// Packet S34 ruling 6: a turn the model's rate limit ended (limited.json, the StopFailure
42// hook's) and no later turn end (turn-ended.json) names /model, in place of the zone word,
43// or of `no meter` before the first meter. The twin of mod.py's limit_note (one fixture in
44// session.test.ts pins both).
45export const LIMIT_NOTE = "limit: the model's limit ended the last turn; /model to switch"
46const stampAt = (text: string | null): number | null => {
47  try {
48    const at = text === null ? null : JSON.parse(text)?.at
49    return typeof at === 'number' && Number.isFinite(at) ? at : null
50  } catch { return null }
51}
52export const limitNote = (limited: string | null, turnEnded: string | null): string | null => {
53  let d: any = null
54  try { d = limited === null ? null : JSON.parse(limited) } catch { d = null }
55  if (!d || typeof d !== 'object' || Array.isArray(d) || d.error !== 'rate_limit') return null
56  const at = stampAt(limited)
57  const ended = stampAt(turnEnded)
58  return at === null || (ended !== null && at <= ended) ? null : LIMIT_NOTE
59}
60
61export const bandLine = (meter: string | null, respawn: boolean, nowMs: number,
62                         limited: string | null = null, turnEnded: string | null = null): string => {
63  let m: any = null
64  try { m = meter === null ? null : JSON.parse(meter) } catch { m = null }
65  const note = limitNote(limited, turnEnded)
66  if (!m || typeof m !== 'object' || m.zone === undefined) return note ? `session: ${note}` : NO_METER
67  let line = `session: ctx ${pct(m.pct_context)} · turns ${pct(m.pct_turns)} · ${note ?? m.zone}`
68  if (respawn) line += ' · respawn marked'
69  const age = Math.floor((nowMs - Date.parse(String(m.ts))) / 1000)
70  if (Number.isFinite(age) && age > STALE_S) line += ` · ${age}s old`
71  return line
72}
73
74// ---- Admission's line (design/admission-r1.md §3.5, packet S27b): it shows. ----
75// `agentik-session admission` rewrites <state>/admission/band.json inside the ledger's lock at
76// every record and admit; the band draws it under the session's line. This is the twin of
77// Python's band_line (one fixture in session.test.ts pins both): a part with no figure is
78// left out, `observe` is last while the mode is, and the age past 120 s follows it; the
79// reset reads `week resets HH:MM (h:mm), 5h HH:MM` when band.json's bound is the seven-day
80// one: `until` the weekly reset, resetsAt the five-hour one.
81const ISO = /^\d{4}-\d{2}-\d{2}T(\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:\d{2})$/
82const fig = (v: unknown): number | null => typeof v === 'number' && Number.isFinite(v) ? v : null
83const whole = (n: number): string => String(Math.round(n))
84
85// A band time, as written: HH and MM from the string's own digits (band.json's resetsAt is
86// local with its offset), and its instant; null unless a strict zoned ISO string.
87const wall = (v: unknown): [string, string, number] | null => {
88  const m = typeof v === 'string' ? ISO.exec(v) : null
89  const t = m ? Date.parse(String(v)) : NaN
90  return m && Number.isFinite(t) ? [m[1], m[2], t] : null
91}
92
93// band.json beside the sessions: `<state>/sessions/<id>` is what `mod start` prints.
94const bandPath = (d: string): string => {
95  const m = /^(.*)\/sessions\/[^/]+\/?$/.exec(d)
96  return m ? `${m[1]}/admission/band.json` : ''
97}
98
99// The band this session draws (packet S35 ruling 5), the twin of Python's session_band:
100// band.json's accounts[sessions[id]] when both are there and it is an object; else the top
101// level, which is all a band.json from before S35, or with one account, holds.
102const own = (o: any, k: unknown): any =>
103  o && typeof o === 'object' && !Array.isArray(o) && typeof k === 'string'
104    && Object.prototype.hasOwnProperty.call(o, k) ? o[k] : undefined
105export const sessionBand = (b: any, id: string): any => {
106  const a = own(b.accounts, own(b.sessions, id))
107  return a && typeof a === 'object' && !Array.isArray(a) ? a : b
108}
109
110export const admissionLine = (band: string | null, nowMs: number, id = ''): string | null => {
111  let b: any = null
112  try { b = band === null ? null : JSON.parse(band) } catch { b = null }
113  if (!b || typeof b !== 'object' || Array.isArray(b)) return null
114  b = sessionBand(b, id)
115  const P = fig(b.P), peak = fig(b.peak), c = fig(b.ceiling)
116  const parts = [P === null ? '5h no reading' : `5h ${whole(P)}%` + (peak !== null ? ` → ${whole(peak)}%` : '')]
117  if (c !== null) parts.push(`ceiling ${String(c)}`)
118  const w = wall(b.resetsAt), u = wall(b.until)
119  const left = (x: [string, string, number]): string => {
120    const n = Math.max(0, Math.floor((x[2] - nowMs) / 60000))
121    return `(${Math.floor(n / 60)}h${String(n % 60).padStart(2, '0')})`
122  }
123  if (b.bound === 'seven_day' && u) parts.push(`week resets ${u[0]}:${u[1]} ${left(u)}` + (w ? `, 5h ${w[0]}:${w[1]}` : ''))
124  else if (w) parts.push(`resets ${w[0]}:${w[1]} ${left(w)}`)
125  const running = fig(b.running), room = fig(b.room)
126  const helpers: string[] = []
127  if (running !== null) helpers.push(`${whole(running)} ${whole(running) === '1' ? 'helper' : 'helpers'}`)
128  if (room !== null) helpers.push(`room for ${whole(room)}`)
129  if (helpers.length) parts.push(helpers.join(', '))
130  const d = fig(b.deferred), p7 = fig(b.P7)
131  if (d !== null) parts.push(`${whole(d)} deferred`)
132  if (p7 !== null) parts.push(`7d ${whole(p7)}%`)
133  if (b.mode === 'observe') parts.push('observe')
134  const a = wall(b.at)
135  const age = a ? Math.floor((nowMs - a[2]) / 1000) : NaN
136  if (Number.isFinite(age) && age > STALE_S) parts.push(`${age}s old`)
137  return parts.join(' · ')
138}
139
140// ---- Admission (design/admission-r1.md §3.1, packet S25): it observes. ----
141// Six hooks hand what they see to `agentik-session admission record` through runTool
142// (5 s), which keeps one line per event on the machine's admission ledger; the policy lives
143// in the tool, this is glue. They never refuse and never rewrite: every hook returns what
144// `next` settled to, a failed record is one debug line, and a spawn's prompt and a
145// message's text are never sent. They write no file and need no sibling plugin.
146const LIMIT_MS = 5000
147const BOUND_MS = 1000
148const DEBUG = { to: 'debug' as const }
149const LATE = Symbol('late')
150
151const str = (v: unknown): string | null => (typeof v === 'string' ? v : null)
152const bool = (v: unknown): boolean | null => (typeof v === 'boolean' ? v : null)
153const num = (v: unknown): number | null => (typeof v === 'number' && Number.isFinite(v) ? v : null)
154const list = (v: unknown): unknown[] => (Array.isArray(v) ? v : [])
155// One reading per window, by the fields the types name (SessionRateLimit), read defensively.
156const limits = (v: unknown): unknown[] =>
157  list(v).map((r: any) => ({ kind: str(r?.kind), percentUsed: num(r?.percentUsed),
158    resetsAt: str(r?.resetsAt) }))
159
160const admissionArgv = (id: unknown): string[] =>
161  [TOOL, 'admission', 'record', '--session', String(id)]
162const exited = (fields: Record<string, unknown>, r: any): string | null =>
163  Number(r?.exitCode) === 0 ? null
164    : `admission: record ${fields.kind}: exit ${r?.exitCode}: ${String(r?.stderr ?? '').trim()}`.slice(0, 300)
165const failed = (fields: Record<string, unknown>, err: any): string =>
166  `admission: record ${fields.kind}: ${String(err?.message ?? err)}`.slice(0, 300)
167
168// A host call raced against a short wait (fix round 1, F2): one that never answers leaves
169// LATE after BOUND_MS, never a hung hook. A refused clock leaves the call unbounded.
170async function within<T>($: EngineInterface, call: () => Promise<T>,
171  ms = BOUND_MS): Promise<T | typeof LATE> {
172  let wait: Promise<typeof LATE>
173  try { wait = $.clock.sleep(ms).then(() => LATE, () => new Promise<typeof LATE>(() => {})) }
174  catch { wait = new Promise<typeof LATE>(() => {}) }
175  return Promise.race([(async () => call())(), wait])
176}
177
178// One record call, under `id` or the session's own id; it never throws: a non-zero exit, a
179// rejection or a timeout is one debug line, and the id read and the log are each bounded.
180async function record($: EngineInterface, fields: Record<string, unknown>, id: string | null = null,
181  timeoutMs = LIMIT_MS): Promise<void> {
182  try {
183    const who = id ?? await within($, () => $.session.id())
184    if (who === LATE) throw new Error(`no session id in ${BOUND_MS} ms`)
185    const r = await runTool($, admissionArgv(who), { stdin: JSON.stringify(fields), timeoutMs })
186    const line = exited(fields, r)
187    if (line) await within($, () => $.ui.log(line, DEBUG))
188  } catch (err) { try { await within($, () => $.ui.log(failed(fields, err), DEBUG)) } catch { /* nothing */ } }
189}
190
191// session.start's part, after `next`: `start`, and whether the session is interactive.
192async function admitStart($: EngineInterface, e: unknown): Promise<void> {
193  await record($, { kind: 'start', interactive: bool((e as any)?.isInteractive) })
194}
195
196// turn.complete's part, after `next`: a helper's turn (it carries agentId) is `done`.
197async function admitDone($: EngineInterface, e: unknown): Promise<void> {
198  const x: any = e
199  if (!str(x?.agentId)) return
200  await record($, { kind: 'done', agentId: str(x.agentId), durationMs: num(x.durationMs),
201    usage: x.usage && typeof x.usage === 'object' ? x.usage : null })
202}
203
204// The verdict, observed (design/admission-r1.md §3.3, packet S26 ruling 6): before `next`,
205// `agentik-session admission admit` decides the spawn or the resume and appends its verdict
206// line. In observe the answer is one debug line and `next(e)` always follows, whatever it
207// says: a refusal, an exit, a rejection or a late answer is a debug line too. The whole call
208// (the id read, the run and the answer's log) is raced against ADMIT_MS, the lock waiting at
209// most 2 s, so the usage read, admit and a late line keep `next` within about 5 s (fix round
210// 1, F4). S27a makes it refuse.
211const ADMIT_MS = 3000
212const admitArgv = (id: unknown): string[] =>
213  [TOOL, 'admission', 'admit', '--session', String(id)]
214
215async function admitCall($: EngineInterface, fields: Record<string, unknown>,
216  say: (line: string) => Promise<void>): Promise<void> {
217  const who = await within($, () => $.session.id())
218  if (who === LATE) throw new Error(`no session id in ${BOUND_MS} ms`)
219  const r: any = await runTool($, admitArgv(who), { stdin: JSON.stringify(fields), timeoutMs: ADMIT_MS })
220  if (Number(r?.exitCode) !== 0) {
221    await say(`admission: admit: exit ${r?.exitCode}: ${String(r?.stderr ?? '').trim()}`)
222    return
223  }
224  let a: any = null
225  try { a = JSON.parse(String(r?.stdout ?? '')) } catch { a = null }
226  const text = str(a?.text)
227  await say(`admission: admit ${str(a?.verdict) ?? 'unreadable'} (${str(a?.mode) ?? '?'}, peak `
228    + `${num(a?.peak) ?? '-'})${text ? `: ${text}` : ''}`)
229}
230
231async function admit($: EngineInterface, fields: Record<string, unknown>): Promise<void> {
232  const say = async (line: string): Promise<void> => {
233    try { await within($, () => $.ui.log(line.slice(0, 300), DEBUG)) } catch { /* nothing */ }
234  }
235  try {
236    const r = await within($, () => admitCall($, fields, say), ADMIT_MS)
237    if (r === LATE) await say(`admission: admit: no answer in ${ADMIT_MS} ms`)
238  } catch (err: any) { await say(`admission: admit: ${String(err?.message ?? err)}`) }
239}
240
241// The usage read before `next`, bounded: a late or refused read is no reading.
242async function usageNow($: EngineInterface): Promise<any> {
243  try { const u = await within($, () => $.session.usage()); return u === LATE ? null : u } catch { return null }
244}
245
246// ---- The measure (design/mod-r1.md §2 row M2, §6 S2; packet M2): it records. ----
247// Every session.measure hands the engine's figures to `agentik-session measure record`
248// (5 s), which writes measure.json beside meter.json; `status` and `doctor` print the drift.
249// Nothing that decides reads it. Only the four figures are sent, never a message's text.
250const measureArgv = (id: unknown): string[] =>
251  [TOOL, 'measure', 'record', '--session', String(id)]
252
253const measureFields = (e: unknown): Record<string, unknown> => {
254  const x: any = e
255  const c: any = x?.context && typeof x.context === 'object' ? x.context : null
256  return {
257    context: c ? { tokens: num(c.tokens), window: num(c.window), percent: num(c.percent) } : null,
258    rateLimits: limits(x?.rateLimits),
259    cost: x?.cost && typeof x.cost === 'object' ? { usd: num(x.cost.usd) } : null,
260    changed: list(x?.changed).map(str),
261  }
262}
263
264// One measure call; it never throws: a non-zero exit, a rejection or a late answer is one
265// debug line, and the id read, the call and the log are each bounded.
266async function measured($: EngineInterface, e: unknown): Promise<void> {
267  const say = async (line: string): Promise<void> => {
268    try { await within($, () => $.ui.log(line.slice(0, 300), DEBUG)) } catch { /* nothing */ }
269  }
270  try {
271    const who = await within($, () => $.session.id())
272    if (who === LATE) throw new Error(`no session id in ${BOUND_MS} ms`)
273    const r: any = await within($, () => runTool($, measureArgv(who),
274      { stdin: JSON.stringify(measureFields(e)), timeoutMs: LIMIT_MS }), LIMIT_MS + BOUND_MS)
275    if (r === LATE) throw new Error(`no answer in ${LIMIT_MS + BOUND_MS} ms`)
276    if (Number(r?.exitCode) !== 0) await say(`measure: record: exit ${r?.exitCode}: ${String(r?.stderr ?? '').trim()}`)
277  } catch (err: any) { await say(`measure: record: ${String(err?.message ?? err)}`) }
278}
279
280// ---- The band ----
281// The session's id and directory live here, not in $.state (no declared state contract);
282// session.start sets them afresh, at a session's start and at every reload of the module.
283let sid = ''
284let dir = ''
285let tries = 0
286
287export const register: Register = on => {
288  on('session.start', async ($, e, next) => {
289    const r = await next(e)
290    dir = ''
291    tries = 0
292    try {
293      try { sid = String(await $.session.id()) } catch { sid = '' }
294      // The classic SessionStart hook may make the session dir after this hook has run (fix
295      // round 1): a failed `mod start` leaves dir unknown, and each 5 s tick tries again.
296      const start = async (): Promise<void> => {
297        if (dir || !sid || tries >= MAX_TRIES) return
298        tries += 1
299        try {
300          const p: any = await runTool($, [TOOL, 'mod', 'start', '--session', sid],
301            { timeoutMs: EVERY_MS })
302          dir = String(JSON.parse(String(p?.stdout ?? '')).dir ?? '')
303        } catch { dir = '' }
304      }
305      await start()
306      await $.ui.invalidate('ui.render')
307      void (async () => {
308        for (;;) { await $.clock.sleep(EVERY_MS); await start(); await $.ui.invalidate('ui.render') }
309      })()
310    } catch { /* the band's failure skips neither admission's part nor the answer */ }
311    try { await admitStart($, e) } catch { /* admission never throws; nor does this */ }
312    return r
313  })
314  on('turn.complete', async ($, e, next) => {
315    const r = await next(e)
316    try {
317      if (!dir && sid && tries < MAX_TRIES) {
318        tries += 1
319        try {
320          const p: any = await runTool($, [TOOL, 'mod', 'start', '--session', sid],
321            { timeoutMs: EVERY_MS })
322          dir = String(JSON.parse(String(p?.stdout ?? '')).dir ?? '')
323        } catch { dir = '' }
324      }
325      await $.ui.invalidate('ui.render')
326    } catch { /* the band's failure skips neither admission's part nor the answer */ }
327    try { await admitDone($, e) } catch { /* admission never throws; nor does this */ }
328    return r
329  })
330  // Two lines, the session's and admission's, in one column (packet S27b ruling 3). While a
331  // survey holds the band it draws neither and gives what `next` gives; otherwise it adds
332  // to that: another mod's tree is kept under the two, and only core's own (an `engine`
333  // ref, which draws nothing here without a survey) is left out, as M1's band left it.
334  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
335    const props: any = (e as any).props ?? {}
336    if (props.hasSurvey === true) return next(e)
337    let below: any = null
338    try { below = await next(e) } catch { below = null }
339    const columns = Number(props.bodyColumns ?? 0)
340    const rows: string[] = []
341    if (!dir) rows.push(NO_METER)
342    else {
343      let meter: string | null = null
344      let respawn = false
345      let band: string | null = null
346      try { meter = String(await $.fs.read(`${dir}/meter.json`)) } catch { meter = null }
347      try { await $.fs.read(`${dir}/respawn.json`); respawn = true } catch { respawn = false }
348      let limited: string | null = null
349      let ended: string | null = null
350      try { limited = String(await $.fs.read(`${dir}/limited.json`)) } catch { limited = null }
351      if (limited !== null) {
352        try { ended = String(await $.fs.read(`${dir}/turn-ended.json`)) } catch { ended = null }
353      }
354      const at = bandPath(dir)
355      if (at) { try { band = String(await $.fs.read(at)) } catch { band = null } }
356      const now = Number(await $.clock.now())
357      rows.push(bandLine(meter, respawn, now, limited, ended))
358      const line = admissionLine(band, now, /\/sessions\/([^/]+)\/?$/.exec(dir)?.[1] ?? '')
359      if (line !== null) rows.push(line)
360    }
361    const kids: any[] = rows.map(l => ({ type: 'Text', props: {}, children: [clip(l, columns)] }))
362    if (below && typeof below === 'object' && below.type !== 'engine') kids.push(below)
363    return { type: 'Box', props: { flexDirection: 'column' }, children: kids }
364  })
365
366  // ---- Admission's other four hooks (above: its part of session.start and turn.complete) ----
367  // session.measure carries the measure's part too (packet M2): every measure is recorded,
368  // and admission's reading only when a window moved. The two run side by side after `next`,
369  // each raced against its bound and caught, so neither waits on or skips the other.
370  on('session.measure', async ($, e, next) => {
371    const r = await next(e)
372    const parts: Array<() => Promise<void>> = [() => measured($, e)]
373    if (list((e as any)?.changed).includes('rateLimits')) {
374      parts.push(() => record($, { kind: 'reading', rateLimits: limits((e as any).rateLimits) }))
375    }
376    await Promise.all(parts.map(async part => {
377      try { await within($, part, LIMIT_MS + 2 * BOUND_MS) } catch { /* each part never throws */ }
378    }))
379    return r
380  })
381  // agentId comes from the spawn's result, so the spawn is recorded after `next`; a usage
382  // read past its bound records the spawn without readings. A spawn refused beneath started
383  // nothing (next's answer has no model), so it is not recorded (fix round 1, F1).
384  // Packet S26: the spawn is admitted (observed) before `next`, from the same usage read.
385  on('agent.spawn', async ($, e, next) => {
386    const x: any = e
387    const usage: any = await usageNow($)
388    await admit($, {
389      subagentType: str(x.subagentType), model: str(x.model), parentModel: str(x.parentModel),
390      background: bool(x.background), fork: bool(x.fork), tool_use_id: str(x.tool_use_id),
391      rateLimits: limits(usage?.rateLimits), resume: false,
392    })
393    const r: any = await next(e)
394    if (str(r?.model) === null) return r
395    await record($, {
396      kind: 'spawn', subagentType: str(x.subagentType), model: str(x.model),
397      parentModel: str(x.parentModel), background: bool(x.background), fork: bool(x.fork),
398      description: str(x.description), tool_use_id: str(x.tool_use_id), agentId: str(r?.agentId),
399      context: usage?.context ? { tokens: num(usage.context.tokens),
400        window: num(usage.context.window), percent: num(usage.context.percent) } : null,
401      rateLimits: limits(usage?.rateLimits),
402    })
403    return r
404  }).catch(($, e, next) => next(e))
405  // A resume reaches a helper through SendMessage and raises no agent.spawn: its target only.
406  // Packet S26: it is admitted (observed) before `next` with `resume: true`, the call's id and
407  // the window's readings only (the message is never sent).
408  on('tool.call', { tool: 'SendMessage' }, async ($, e, next) => {
409    const usage: any = await usageNow($)
410    await admit($, { subagentType: null, model: null, parentModel: null, background: null,
411      fork: null, tool_use_id: str((e as any).tool_use_id), rateLimits: limits(usage?.rateLimits),
412      resume: true })
413    const r = await next(e)
414    await record($, { kind: 'resume', to: str((e as any).to) })
415    return r
416  }).catch(($, e, next) => next(e))
417  // The end runs first, inside session.end's one short bound, under the ending session's
418  // id (a /clear goes on under another); the tool sweeps its open spawns in the same lock.
419  on('session.end', async ($, e, next) => {
420    const left = Number((next as any).budget?.remainingMs)
421    const ms = Number.isFinite(left) && left > 0 ? Math.min(LIMIT_MS, left) : LIMIT_MS
422    await record($, { kind: 'end', reason: str((e as any).reason) }, str((e as any).sessionId), ms)
423    return next(e)
424  })
425}
426