turn-limits

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { Invocation } from '../types'
5import { applyNotice, type Notice, parseLimit, parseNotification, reportText, statusText, summarize } from './tally'
6
7const PANE = 'turn-limits'
8
9const calls = atom({ plugin: 'turn-limits', key: 'calls' } as const, {})
10const agents = atom({ plugin: 'turn-limits', key: 'agents' } as const, {})
11
12export const register: Register = on => {
13  on('session.start', async ($, e, next) => {
14    await $.command.register({
15      name: 'turn-limits',
16      description: 'Agent invocations that stopped at their turn limit, per agent type (args: reset)',
17      argumentHint: '[reset]',
18    })
19    await $.tool.register({
20      name: 'turn_limits',
21      description:
22        'Read-only: how many agent invocations of this session stopped at their turn limit, per agent type (hits/runs, %, the limits seen).',
23      inputSchema: { type: 'object', properties: {} },
24    })
25    await refreshStatus($)
26
27    return next(e)
28  })
29
30  on('tool.call', { tool: 'mcp__turn-limits__turn_limits' }, async $ => ({ result: reportText(summarize(await read($, calls))) }))
31
32  on('tool.call', { tool: 'Agent' }, async ($, e, next) => {
33    const id = e.tool_use_id
34    const type = e.subagent_type?.trim() || 'general-purpose'
35    await update($, calls, all => ({ ...all, [id]: { type } }))
36
37    const ran = await next(e)
38    if (ran.deny !== undefined) {
39      await update($, calls, ({ [id]: _, ...rest }) => rest)
40      return ran
41    }
42    const record = ran.result as { agentId?: unknown; agentType?: unknown } | undefined
43    const agentId = typeof record?.agentId === 'string' ? record.agentId : undefined
44    const limit = parseLimit(ran.text ?? '')
45    await update($, calls, all => {
46      const call = all[id] ?? { type }
47      return { ...all, [id]: { ...call, ...(agentId ? { agentId } : {}), ...hit(call, limit) } }
48    })
49    await refreshStatus($)
50
51    return ran
52  })
53
54  on('classic.SubagentStart', async ($, e, next) => {
55    await update($, agents, all => ({ ...all, [e.agent_id]: e.agent_type }))
56    return next(e)
57  })
58
59  on('session.append', async ($, e, next) => {
60    const isUserRow = e.message.type === 'user' && e.message.role === 'user'
61    if (isUserRow) {
62      for (const block of e.message.content) {
63        if (block.type !== 'text' || typeof block.text !== 'string') continue
64        const notice = parseNotification(block.text)
65        if (notice !== undefined) await recordNotice($, notice)
66      }
67    }
68    return next(e)
69  })
70
71  on('command.run', { command: 'turn-limits' }, async ($, e) => {
72    if (e.args.trim() === 'reset') {
73      await update($, calls, () => ({}))
74      await refreshStatus($)
75      return { text: 'Turn-limit counters reset.' }
76    }
77    await $.ui.open({ id: PANE, title: 'Turn limits' })
78    return { text: 'Turn-limits pane opened.' }
79  })
80
81  on('ui.render', { component: 'Pane', requestId: PANE }, async ($, e) => {
82    const { Box, Text } = $.ui.resolve(e)
83    const sum = summarize(await read($, calls))
84    if (sum.calls === 0) return <Text dimColor>No agent invocations in this session yet.</Text>
85
86    const width = Math.max(...sum.rows.map(r => r.type.length), 10)
87    return (
88      <Box flexDirection="column">
89        <Text bold color={sum.hits > 0 ? 'warning' : 'success'}>
90          {sum.hits}/{sum.calls} invocations stopped at their turn limit ({sum.pct}%)
91        </Text>
92        <Text> </Text>
93        <Text dimColor>
94          {'type'.padEnd(width)}   hits/runs     %   limit
95        </Text>
96        {sum.rows.map(r => (
97          <Text color={r.hits > 0 ? 'warning' : undefined} dimColor={r.hits === 0} wrap="truncate-end">
98            {r.type.padEnd(width)}   {`${r.hits}/${r.calls}`.padStart(9)}  {`${r.pct}%`.padStart(4)}   {r.limits.join(', ') || '—'}
99          </Text>
100        ))}
101      </Box>
102    )
103  })
104}
105
106function hit(call: Invocation, limit: number | undefined): Partial<Invocation> {
107  return limit !== undefined && call.hitLimit === undefined ? { hitLimit: limit } : {}
108}
109
110async function recordNotice($: EngineInterface, notice: Notice) {
111  const known = await read($, agents)
112  await update($, calls, all => applyNotice(all, known, notice))
113  await refreshStatus($)
114}
115
116async function refreshStatus($: EngineInterface) {
117  $.ui.status(statusText(summarize(await read($, calls))))
118}
119

1import type { Invocation } from '../types'
2
3const LIMIT = /stopped at its (\d+)-turn limit/
4
5/** The turn limit a text says an agent stopped at, if it says so. */
6export function parseLimit(text: string): number | undefined {
7  const m = LIMIT.exec(text)
8  return m?.[1] === undefined ? undefined : Number(m[1])
9}
10
11export type Notice = { toolUseId?: string; taskId?: string; limit: number }
12
13/**
14 * A task notification that reports a turn-limit stop. Only a row that IS a
15 * notification counts: the text must open with the tag, so a tool result
16 * quoting one (a grep over transcripts) never does.
17 */
18export function parseNotification(text: string): Notice | undefined {
19  const body = text.trimStart()
20  if (!body.startsWith('<task-notification>')) return undefined
21  const limit = parseLimit(body)
22  if (limit === undefined) return undefined
23  const tag = (name: string) => new RegExp(`<${name}>([^<]+)</${name}>`).exec(body)?.[1]?.trim()
24  return { toolUseId: tag('tool-use-id'), taskId: tag('task-id'), limit }
25}
26
27/** Marks the invocation a notice names, once; one never seen starts with SubagentStart's type, or unknown. */
28export function applyNotice(
29  calls: Record<string, Invocation>,
30  agents: Record<string, string>,
31  notice: Notice,
32): Record<string, Invocation> {
33  const byAgent = notice.taskId ? Object.entries(calls).find(([, c]) => c.agentId === notice.taskId)?.[0] : undefined
34  const id = (notice.toolUseId && calls[notice.toolUseId] ? notice.toolUseId : byAgent) ?? notice.toolUseId ?? `task:${notice.taskId ?? '?'}`
35  const call = calls[id] ?? {
36    type: (notice.taskId && agents[notice.taskId]) || 'unknown',
37    ...(notice.taskId ? { agentId: notice.taskId } : {}),
38  }
39  return call.hitLimit === undefined ? { ...calls, [id]: { ...call, hitLimit: notice.limit } } : { ...calls, [id]: call }
40}
41
42export type Row = { type: string; calls: number; hits: number; pct: number; limits: number[] }
43export type Summary = { rows: Row[]; calls: number; hits: number; pct: number }
44
45const pct = (hits: number, calls: number) => (calls === 0 ? 0 : Math.round((100 * hits) / calls))
46
47/** Rows by hit percentage, then invocations, then name. */
48export function summarize(calls: Record<string, Invocation>): Summary {
49  const byType = new Map<string, Row>()
50  for (const call of Object.values(calls)) {
51    const row = byType.get(call.type) ?? { type: call.type, calls: 0, hits: 0, pct: 0, limits: [] }
52    row.calls += 1
53    if (call.hitLimit !== undefined) {
54      row.hits += 1
55      if (!row.limits.includes(call.hitLimit)) row.limits.push(call.hitLimit)
56    }
57    byType.set(call.type, row)
58  }
59  const rows = [...byType.values()]
60    .map(r => ({ ...r, pct: pct(r.hits, r.calls), limits: [...r.limits].sort((a, b) => a - b) }))
61    .sort((a, b) => b.pct - a.pct || b.calls - a.calls || a.type.localeCompare(b.type))
62  const total = rows.reduce((t, r) => ({ calls: t.calls + r.calls, hits: t.hits + r.hits }), { calls: 0, hits: 0 })
63  return { rows, ...total, pct: pct(total.hits, total.calls) }
64}
65
66/** The status-line entry; undefined until the first hit, so a clean session stays quiet. */
67export function statusText(sum: Summary, maxLen = 80): string | undefined {
68  if (sum.hits === 0) return undefined
69  let text = `turn limits ${sum.hits}/${sum.calls} (${sum.pct}%)`
70  const hit = [...sum.rows].filter(r => r.hits > 0).sort((a, b) => b.hits - a.hits || a.type.localeCompare(b.type))
71  for (const [i, r] of hit.entries()) {
72    const part = ` · ${r.type} ${r.hits}`
73    const rest = hit.length - i - 1
74    if ((text + part).length > maxLen - (rest > 0 ? 4 : 0)) return `${text} · …`
75    text += part
76  }
77  return text
78}
79
80/** The summary as plain text: the read-only tool's answer. */
81export function reportText(sum: Summary): string {
82  if (sum.calls === 0) return 'No agent invocations in this session yet.'
83  return [
84    `${sum.hits}/${sum.calls} invocations stopped at their turn limit (${sum.pct}%).`,
85    ...sum.rows.map(r => `  ${r.type}: ${r.hits}/${r.calls} (${r.pct}%)${r.limits.length ? `, limit ${r.limits.join(', ')}` : ''}`),
86  ].join('\n')
87}
88

1export type Invocation = {
2  /** The agent type, from the Agent call's subagent_type (or SubagentStart). */
3  type: string
4  agentId?: string
5  /** The turn limit it stopped at; set once, on the first notice. */
6  hitLimit?: number
7}
8
9declare module 'claude-code' {
10  interface PluginState {
11    'turn-limits': {
12      /** Keyed by the Agent call's tool_use_id. */
13      calls: Record<string, Invocation>
14      /** agent_id -> agent_type, from classic.SubagentStart: the fallback join. */
15      agents: Record<string, string>
16    }
17  }
18}
19