statusline-runtime

1/** Passive observations only: every hook passes its original event/result on. */
2import type { EngineInterface, Register, PluginOptions } from 'claude-code';
3import { Queue, confirmedResponse } from '../lib/queue.ts';
4import { PROTOCOL_VERSION } from '../lib/generated-contracts.ts';
5import { checklist } from '../lib/checklists.ts';
6import { tapStream, usage } from '../lib/streams.ts';
7import { cost } from '../lib/costs.ts';
8import { promptLink, reportAgent } from '../lib/identity.ts';
9import { WaitCoverage } from '../lib/timing.ts';
10import { binding } from '../lib/launch.ts';
11
12type State = { queue: Queue; ready: boolean; busy: boolean; executable: string; args: readonly string[]; directory: string; hostVersion: string; turns: Record<string, string>; agentTypes: string[] };
13
14async function bind($: EngineInterface, options: PluginOptions, state: State): Promise<void> {
15  const queue = state.queue;
16  const session = await $.session.id();
17  if (state.ready && queue.session === session) return;
18  const launch = binding(options, await $.env.get('CLAUDE_STATUSLINE_RUNTIME_EXECUTABLE') || undefined);
19  state.executable = launch.executable;
20  state.args = launch.args;
21  state.directory = (await $.env.get('CLAUDE_CONFIG_DIR')) ||
22    (typeof options.configDir === 'string' ? options.configDir : '');
23  state.hostVersion = (await $.session.version()).version;
24  const now = await $.clock.now();
25  queue.bind(session, now);
26  state.turns = {};
27  state.agentTypes = [];
28  queue.push('heartbeat', { host_version: state.hostVersion, loaded_at_ms: now }, now);
29  state.ready = true;
30}
31
32async function flush($: EngineInterface, options: PluginOptions, state: State): Promise<void> {
33  const queue = state.queue;
34  if (state.busy || !queue.pending.length) return;
35  state.busy = true;
36  const batch = queue.batch();
37  try {
38    const argv = [state.executable, ...state.args, 'runtime', ...(state.directory ? ['--config-dir', state.directory] : [])];
39    const result = await $.process.run(argv, {
40      stdin: JSON.stringify({ protocol_version: PROTOCOL_VERSION, operation: 'observe', payload: { observations: batch } }),
41      timeoutMs: 2000,
42    });
43    const expected = typeof options.backendVersion === 'string' ? options.backendVersion : '';
44    if (result.exitCode === 0 && confirmedResponse(result.stdout, expected, batch.length)) queue.acknowledge(batch);
45  } catch { /* Keep exact identities for an idempotent retry. */ }
46  finally { state.busy = false; }
47}
48
49
50export const register: Register = (on, options: PluginOptions) => {
51  const state: State = { queue: new Queue(), ready: false, busy: false, executable: '', args: [], directory: '', hostVersion: '', turns: {}, agentTypes: [] };
52  const queue = state.queue;
53  queue.timing = options.nativeTiming !== false;
54  queue.metrics = options.liveMetrics === true;
55  const waitCoverage = new WaitCoverage();
56  const unknownWait = (reason: string, at: number, agent?: string) => {
57    for (const [loop, turn] of Object.entries(state.turns)) {
58      if (agent && loop !== agent) continue;
59      waitCoverage.mark(loop, turn);
60      queue.push('wait_unknown', { reason }, at, { turn_id: turn, agent_id: loop === 'main' ? null : loop });
61    }
62  };
63  on('session.start', async ($, e, next) => {
64    try {
65      await bind($, options, state);
66      await flush($, options, state);
67      $.clock.every(1000, async () => { try { await bind($, options, state); await flush($, options, state); } catch {} });
68      $.clock.every(5000, async () => {
69        try {
70          await bind($, options, state);
71          const now = await $.clock.now();
72          queue.push('heartbeat', { host_version: state.hostVersion, loaded_at_ms: queue.loadedAt }, now);
73          const agents = await $.agent.list();
74          queue.push('agents', { agents: agents.slice(0, 256).map(agent => ({
75            id: agent.id, parent_id: agent.parentId ?? null, status: agent.status,
76            local: !agent.teammateId || Boolean(state.turns[agent.id]),
77          })) }, now);
78          await flush($, options, state);
79        } catch {}
80      });
81    } catch { /* A refused API cannot change the session start. */ }
82    return next(e);
83  });
84
85  on('classic.UserPromptSubmit', async ($, e, next) => {
86    try {
87      await bind($, options, state);
88      const now = await $.clock.now();
89      const report = reportAgent(e.prompt);
90      if (report && e.prompt_id)
91        queue.push('prompt_alias', { agent_id: report }, now, { prompt_id: e.prompt_id }, 'classic_hook');
92      if (e.prompt_id && !e.agent_id && !report && !/^\s*<(?:command-|local-command-|bash-)/.test(e.prompt))
93        queue.push('prompt', {}, now, { prompt_id: e.prompt_id }, 'classic_hook');
94      if (e.prompt_id && e.agent_id)
95        queue.push('prompt_alias', { agent_id: e.agent_id }, now, { prompt_id: e.prompt_id, agent_id: e.agent_id }, 'classic_hook');
96      if (e.permission_mode)
97        queue.push('permission', { mode: e.permission_mode, live: false }, now,
98                   { prompt_id: e.prompt_id ?? null, agent_id: e.agent_id ?? null }, 'classic_hook');
99    } catch {}
100    return next(e);
101  });
102
103  on('classic.SubagentStart', async ($, e, next) => {
104    try {
105      await bind($, options, state);
106      const now = await $.clock.now();
107      queue.push('agent_start', { started_at_ms: now }, now,
108                 { prompt_id: e.prompt_id ?? null, agent_id: e.agent_id }, 'classic_hook');
109    } catch {}
110    return next(e);
111  });
112
113  on('classic.SubagentStop', async ($, e, next) => {
114    try {
115      await bind($, options, state);
116      const now = await $.clock.now();
117      queue.push('agent_end', { ended_at_ms: now, status: 'completed' }, now,
118                 { prompt_id: e.prompt_id ?? null, agent_id: e.agent_id }, 'classic_hook');
119    } catch {}
120    return next(e);
121  });
122
123  on('turn.start', async ($, e, next) => {
124    try {
125      await bind($, options, state);
126      state.turns.main = e.turnId;
127      queue.push('turn_start', {}, await $.clock.now(), { turn_id: e.turnId });
128    } catch {}
129    return next(e);
130  });
131
132  on('session.append', { door: 'prompt' }, async ($, e, next) => {
133    try {
134      await bind($, options, state);
135      const now = await $.clock.now();
136      if (e.agentId) {
137        queue.push('prompt_alias', { agent_id: e.agentId }, now, { prompt_id: e.uuid, agent_id: e.agentId });
138      } else if (e.message.type === 'user' && ['composer', 'bridge', 'sdk'].includes(e.origin.kind)) {
139        queue.push('prompt', {}, now, { prompt_id: e.uuid });
140      }
141    } catch {}
142    return next(e);
143  });
144
145  on('agent.spawn', async ($, e, next) => {
146    const loop = e.parentAgentId ?? 'main';
147    const turn = state.turns[loop];
148    const epoch = queue.epoch;
149    const result = await next(e);
150    try {
151      if (result.agentId && epoch === queue.epoch) {
152        if (!state.agentTypes.includes(e.subagentType)) state.agentTypes.push(e.subagentType);
153        const now = await $.clock.now();
154        queue.push('agent_start', { started_at_ms: now }, now, {
155          agent_id: result.agentId, parent_agent_id: e.parentAgentId ?? null, turn_id: turn ?? null,
156        });
157      }
158    } catch {}
159    return result;
160  });
161
162  on('turn.complete', async ($, e, next) => {
163    try {
164      await bind($, options, state);
165      const now = await $.clock.now();
166      const status = e.isAborted ? 'interrupted' : e.reason === 'error' || e.reason === 'refusal' ? 'failed' : 'completed';
167      queue.push('turn_end', { status, duration_ms: e.durationMs, wait_coverage: waitCoverage.finish(e.agentId ?? 'main', e.turnId) }, now, { agent_id: e.agentId ?? null, turn_id: e.turnId });
168      queue.push('turn_usage', { usage: usage(e.usage) }, now, { agent_id: e.agentId ?? null, turn_id: e.turnId });
169      if (e.agentId)
170        queue.push('agent_end', { ended_at_ms: now, status }, now, { agent_id: e.agentId, turn_id: e.turnId });
171    } catch {}
172    delete state.turns[e.agentId ?? 'main'];
173    return next(e);
174  });
175
176  on('turn.step', async function* ($, e, next) {
177    const identity = { agent_id: e.agentId ?? null, turn_id: e.turnId, request_id: (e.agentId ?? 'main') + ':' + e.turnId + ':' + String(e.index) };
178    let epoch = queue.epoch;
179    let first = false;
180    let native = false;
181    let counted: Record<string, number> | null = null;
182    let status = 'interrupted';
183    try {
184      await bind($, options, state);
185      epoch = queue.epoch;
186      state.turns[e.agentId ?? 'main'] = e.turnId;
187      const now = await $.clock.now();
188      queue.push('turn_start', {}, now, identity);
189      queue.push('request_start', {}, now, identity);
190    } catch {}
191    if (!queue.metrics) return yield* next(e);
192    const observed = tapStream(next(e), async (item, operation) => {
193      if (epoch !== queue.epoch) return;
194      if (item.done) { if (operation !== 'return') status = 'completed'; return; }
195      const chunk = item.value;
196      if (typeof chunk.ref === 'number') {
197        native = true;
198        const content = chunk.kind === 'tool' || ((chunk.kind === 'text' || chunk.kind === 'thinking') && chunk.text.length > 0);
199        if (content && !first) {
200          first = true;
201          queue.push('request_first', {}, await $.clock.now(), identity);
202        }
203        if (chunk.kind === 'stop') counted = usage(chunk.usage);
204      }
205    });
206    try {
207      return yield* observed;
208    } catch (error) {
209      status = next.signal.aborted ? 'interrupted' : 'failed';
210      throw error;
211    } finally {
212      try {
213        if (epoch === queue.epoch)
214          queue.push('request_end', { native, usage: native ? counted : null, status }, await $.clock.now(), identity);
215      } catch {}
216    }
217  });
218
219  on('telemetry.log', { to: 'collector' }, async ($, e, next) => {
220    try {
221      const link = promptLink(e, queue.session);
222      if (link) queue.push('prompt_link', link.payload, await $.clock.now(), link.identity, 'otel');
223      const row = queue.metrics ? cost(e, queue.session, state.agentTypes) : null;
224      if (row) queue.push('request_cost', row.payload, await $.clock.now(), row.identity, 'otel');
225    } catch {}
226    return next(e);
227  });
228
229  // A declarative 'ask' does not expose when the actual approval dialog
230  // opens/closes. Preserve that uncertainty instead of subtracting tool time.
231  on('tool.check', async ($, e, next) => {
232    const result = await next(e);
233    if (e.tool_use_id && result.decision === 'ask') {
234      try { unknownWait('permission_wait_unobserved', await $.clock.now()); } catch {}
235    }
236    return result;
237  });
238  on('classic.Elicitation', async ($, e, next) => {
239    try { unknownWait('mcp_wait_unobserved', await $.clock.now()); } catch {}
240    return next(e);
241  });
242  on('tool.call', async ($, e, next) => {
243    const identity = { agent_id: e.agentId ?? null, turn_id: state.turns[e.agentId ?? 'main'] ?? null, request_id: e.tool_use_id };
244    const epoch = queue.epoch;
245    if (e.tool === 'AskUserQuestion' || e.tool.startsWith('mcp__')) {
246      try { unknownWait('question_wait_unobserved', await $.clock.now(), e.agentId); } catch {}
247    }
248    try { queue.push('tool_start', { name: e.tool }, await $.clock.now(), identity); } catch {}
249    try {
250      const result = await next(e);
251      try {
252        if (epoch === queue.epoch) {
253          const now = await $.clock.now();
254          queue.push('tool_end', { name: e.tool, status: result.deny !== undefined ? 'denied' : result.isError ? 'error' : 'success' }, now, identity);
255          if (queue.metrics && result.deny === undefined && !result.isError) {
256            const change = checklist(e.tool, e, result.result);
257            if (change) queue.push(change.kind, change.payload, now, identity);
258          }
259        }
260      } catch {}
261      return result;
262    } catch (error) {
263      try {
264        if (epoch === queue.epoch)
265          queue.push('tool_end', { name: e.tool, status: next.signal.aborted ? 'interrupted' : 'error' }, await $.clock.now(), identity);
266      } catch {}
267      throw error;
268    }
269  });
270
271  on('session.end', async ($, e, next) => {
272    try {
273      queue.push('invalidate', { reason: 'session_' + e.reason }, await $.clock.now());
274      await flush($, options, state);
275    } catch {}
276    state.ready = false;
277    return next(e);
278  });
279};
280

1/** Bounded, retryable batches. Host access belongs to the hooks entry. */
2import { PROTOCOL_VERSION, type Observation, type Kind, type Source } from './generated-contracts.ts';
3
4export const TIMING_KINDS: ReadonlySet<Kind> = new Set([
5  'heartbeat', 'invalidate', 'prompt', 'prompt_alias', 'prompt_link',
6  'agent_start', 'agent_end', 'turn_start', 'turn_end', 'agents',
7  'wait_start', 'wait_end', 'wait_unknown',
8]);
9
10export type Identity = Partial<Pick<Observation,
11  'prompt_id' | 'agent_id' | 'parent_agent_id' | 'turn_id' | 'request_id'>>;
12
13export class Queue {
14  constructor(public timing = true, public metrics = true) {}
15  pending: Observation[] = [];
16  sequence = 0;
17  session = '';
18  epoch = '';
19  loadedAt = 0;
20  dropped = false;
21
22  bind(session: string, loadedAt: number): void {
23    this.session = session;
24    this.loadedAt = loadedAt;
25    this.epoch = String(loadedAt) + '-' + Math.random().toString(16).slice(2);
26    this.sequence = 0;
27    this.pending = [];
28    this.dropped = false;
29  }
30
31  push(kind: Kind, payload: Record<string, unknown>, at: number,
32       identity: Identity = {}, source: Source = 'native'): void {
33    if (!this.session || (!this.metrics && (!this.timing || !TIMING_KINDS.has(kind)))) return;
34    const record: Observation = {
35      session_id: this.session, epoch: this.epoch, seq: this.sequence++,
36      observed_at_ms: at, source, kind,
37      prompt_id: identity.prompt_id ?? null, agent_id: identity.agent_id ?? null,
38      parent_agent_id: identity.parent_agent_id ?? null, turn_id: identity.turn_id ?? null,
39      request_id: identity.request_id ?? null, payload,
40    };
41    // Preserve the initial heartbeat even when an unavailable backend fills the queue.
42    if (this.pending.length >= 1024) {
43      this.dropped = true;
44      this.pending.splice(this.pending[0]?.kind === 'heartbeat' ? 1 : 0, 1);
45    }
46    this.pending.push(record);
47  }
48
49  batch(): Observation[] { return this.pending.slice(0, 256); }
50
51  acknowledge(batch: readonly Observation[]): void {
52    const acknowledged = new Set(batch.map(row => row.epoch + ':' + row.seq));
53    this.pending = this.pending.filter(row => !acknowledged.has(row.epoch + ':' + row.seq));
54  }
55}
56
57export function confirmedResponse(stdout: string, expected: string, count?: number): boolean {
58  try {
59    const value = JSON.parse(stdout) as Record<string, unknown>;
60    const result = value.result as Record<string, unknown> | undefined;
61    return value.protocol_version === PROTOCOL_VERSION && result !== undefined &&
62      typeof result.backend_version === 'string' && (!expected || result.backend_version === expected) &&
63      typeof result.enabled === 'boolean' &&
64      typeof result.accepted === 'number' && Number.isInteger(result.accepted) && result.accepted >= 0 &&
65      typeof result.ignored === 'number' && Number.isInteger(result.ignored) && result.ignored >= 0 &&
66      (count === undefined || result.accepted + result.ignored === count);
67  } catch { return false; }
68}
69

1// Generated by tools/generation/resources.ts; do not edit.
2export const PROTOCOL_VERSION = 2 as const;
3export type Source = "native" | "classic_hook" | "otel";
4export type Kind = "heartbeat" | "invalidate" | "prompt" | "prompt_alias" | "permission" | "agent_start" | "agent_end" | "turn_start" | "turn_end" | "wait_start" | "wait_end" | "wait_unknown" | "agents" | "tool_start" | "tool_end" | "task_snapshot" | "task_update" | "request_start" | "request_first" | "request_end" | "request_cost" | "turn_usage" | "prompt_link";
5export interface Observation {
6  session_id: string;
7  epoch: string;
8  seq: number;
9  observed_at_ms: number;
10  source: "native" | "classic_hook" | "otel";
11  kind: "heartbeat" | "invalidate" | "prompt" | "prompt_alias" | "permission" | "agent_start" | "agent_end" | "turn_start" | "turn_end" | "wait_start" | "wait_end" | "wait_unknown" | "agents" | "tool_start" | "tool_end" | "task_snapshot" | "task_update" | "request_start" | "request_first" | "request_end" | "request_cost" | "turn_usage" | "prompt_link";
12  prompt_id: string | null;
13  turn_id: string | null;
14  agent_id: string | null;
15  parent_agent_id: string | null;
16  request_id: string | null;
17  payload: Record<string, unknown>;
18}
19

1/** Only successful structured tool records contribute; no text heuristics. */
2type Task = { id: string; status: string };
3type Change = { kind: 'task_snapshot' | 'task_update'; payload: Record<string, unknown> };
4const statuses = new Set(['pending', 'in_progress', 'completed', 'deleted']);
5
6function record(value: unknown): Record<string, unknown> | null {
7  return value !== null && typeof value === 'object' && !Array.isArray(value)
8    ? value as Record<string, unknown> : null;
9}
10
11function task(value: unknown): Task | null {
12  const row = record(value);
13  if (!row || (typeof row.id !== 'string' && typeof row.id !== 'number') ||
14      typeof row.status !== 'string' || !statuses.has(row.status)) return null;
15  return { id: String(row.id), status: row.status };
16}
17
18export function checklist(tool: string, input: unknown, result: unknown): Change | null {
19  const args = record(input);
20  const output = record(result);
21  if (!args || !output) return null;
22  if (tool === 'TodoWrite' || tool === 'TaskList') {
23    const rows = tool === 'TodoWrite' ? output.newTodos : output.tasks;
24    if (!Array.isArray(rows) || rows.length > 1000) return null;
25    const tasks: Task[] = [];
26    for (let i = 0; i < rows.length; i++) {
27      const row = record(rows[i]);
28      const parsed = task(tool === 'TodoWrite' && row ? { ...row, id: String(i) } : row);
29      if (!parsed) return null;
30      tasks.push(parsed);
31    }
32    if (new Set(tasks.map(row => row.id)).size !== tasks.length) return null;
33    return { kind: 'task_snapshot', payload: { provider: tool === 'TodoWrite' ? 'todos' : 'tasks', tasks } };
34  }
35  if (tool === 'TaskCreate') {
36    const created = task(output.task);
37    return created ? { kind: 'task_update', payload: { provider: 'tasks', ...created } } : null;
38  }
39  if (tool === 'TaskUpdate' && output.success === true &&
40      (typeof args.taskId === 'string' || typeof args.taskId === 'number') &&
41      typeof args.status === 'string' && statuses.has(args.status)) {
42    return { kind: 'task_update', payload: { provider: 'tasks', id: String(args.taskId), status: args.status } };
43  }
44  return null;
45}
46

1/** Forward generator next/return/throw exactly, including downstream results. */
2export function tapStream<C, R>(source: AsyncGenerator<C, R, void>,
3    inspect: (item: IteratorResult<C, R>, operation: 'next' | 'return' | 'throw') => Promise<void>): AsyncGenerator<C, R, void> {
4  async function tap(result: Promise<IteratorResult<C, R>>, operation: 'next' | 'return' | 'throw'): Promise<IteratorResult<C, R>> {
5    const item = await result;
6    try { await inspect(item, operation); } catch { /* Observation never changes the stream. */ }
7    return item;
8  }
9  return {
10    next: (...args: [] | [void]) => tap(source.next(...args), 'next'),
11    return: (value: R | PromiseLike<R>) => tap(source.return(value), 'return'),
12    throw: (error: unknown) => tap(source.throw(error), 'throw'),
13    [Symbol.asyncIterator]() { return this; },
14  };
15}
16
17const fields = ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens'] as const;
18export function usage(value: unknown): Record<string, number> | null {
19  if (!value || typeof value !== 'object') return null;
20  const row = value as Record<string, unknown>;
21  const result: Record<string, number> = {};
22  for (const field of fields) {
23    const count = row[field];
24    if (typeof count !== 'number' || !Number.isSafeInteger(count) || count < 0) return null;
25    result[field] = count;
26  }
27  return result;
28}
29

1/** Whitelist official collector attributes; never enable or redirect exporters. */
2import type { TelemetryLogInput } from 'claude-code';
3import { usage } from './streams.ts';
4
5export { promptLink } from './identity.ts';
6
7export function cost(e: TelemetryLogInput, session: string, agentTypes: readonly string[]) {
8  if (e.to !== 'collector' || !['api_request', 'claude_code.api_request'].includes(e.event)) return null;
9  const a = e.attributes;
10  if (a['session.id'] !== session || a['workflow.run_id'] ||
11      typeof a['prompt.id'] !== 'string' || typeof a.request_id !== 'string' ||
12      !['repl_main_thread', ...agentTypes].includes(String(a.query_source))) return null;
13  const usd = typeof a.cost_usd === 'number' ? a.cost_usd :
14    typeof a.cost_usd_micros === 'number' && Number.isSafeInteger(a.cost_usd_micros) ? a.cost_usd_micros / 1000000 : null;
15  if (usd === null || !Number.isFinite(usd) || usd < 0) return null;
16  return {
17    identity: { prompt_id: a['prompt.id'], request_id: a.request_id },
18    payload: { cost_usd: usd, usage: usage({
19      input_tokens: a.input_tokens, output_tokens: a.output_tokens,
20      cache_read_input_tokens: a.cache_read_tokens, cache_creation_input_tokens: a.cache_creation_tokens,
21    }) },
22  };
23}
24

1/** Official task/message identity only; never retain prompt text. */
2import type { TelemetryLogInput } from 'claude-code';
3
4export function promptLink(e: TelemetryLogInput, session: string) {
5  if (e.to !== 'collector' || !['user_prompt', 'claude_code.user_prompt'].includes(e.event)) return null;
6  const a = e.attributes;
7  if (a['session.id'] !== session || a['workflow.run_id'] || a.command_name ||
8      typeof a['prompt.id'] !== 'string' || typeof a['message.uuid'] !== 'string') return null;
9  return { identity: { prompt_id: a['prompt.id'] }, payload: { message_id: a['message.uuid'] } };
10}
11
12export function reportAgent(prompt: string): string | null {
13  return /^\s*<task-notification>\s*<task-id>([^<>\s]+)<\/task-id>/.exec(prompt)?.[1] ?? null;
14}
15

1/** Coverage of user waits; unsupported boundaries invalidate the metric. */
2export class WaitCoverage {
3  private unknown = new Set<string>();
4  mark(loop: string, turn: string): void { this.unknown.add(loop + ':' + turn); }
5  finish(loop: string, turn: string): boolean {
6    const key = loop + ':' + turn;
7    const complete = !this.unknown.has(key);
8    this.unknown.delete(key);
9    return complete;
10  }
11}
12

1// Generated by tools/generation/resources.ts; do not edit.
2/** Host-independent argv binding, shared by Node and the sandboxed Mods. */
3export interface LaunchSpec { executable: string; args: readonly string[] }
4
5function executable(value: unknown): value is string {
6  return typeof value === 'string' && value.length > 0 && !/[\0\r\n]/u.test(value);
7}
8
9export function binding(options: { backendExecutable?: unknown; backendArgs?: unknown } = {}, override?: string): LaunchSpec {
10  if (override) {
11    if (!executable(override)) throw new TypeError('Invalid backend executable');
12    return { executable: override, args: [] };
13  }
14  const program = options.backendExecutable ?? 'claude-statusline';
15  // Official configure --values-stdin accepts strings, including multiple inputs.
16  // Defaults and SDK callers may already provide the array.
17  let args: unknown = options.backendArgs ?? [];
18  if (typeof args === 'string') {
19    try { args = JSON.parse(args); } catch { throw new TypeError('Invalid backend argument array'); }
20  }
21  if (!executable(program) || !Array.isArray(args) || !args.every(x => typeof x === 'string' && !x.includes('\0'))) {
22    throw new TypeError('Invalid backend binding');
23  }
24  return { executable: program, args: [...args] };
25}
26