bead-stale-nudge

1import type { Register } from 'claude-code'
2
3import { startSessionWithRun } from './hosts/start-run'
4import { rule as beadStaleNudge } from './rules/bead-stale-nudge'
5
6export const register: Register = on => {
7  const rules = [beadStaleNudge]
8  startSessionWithRun(on, rules)
9}
10

1import type { On } from 'claude-code'
2
3import { START_RUN_TIMEOUT_MS, sessionStart } from '../engine'
4import type { LifecycleRule, StartTools } from '../engine'
5
6// As the session starts, for rules that run a program and show a toast. Not
7// awaited: the session does not wait on a program.
8export const startSessionWithRun = (on: On, rules: readonly LifecycleRule[]): void => {
9  on('session.start', async ($, e, next) => {
10    const tools: StartTools = {
11      run: (argv, cwd) => $.process.run(argv, { cwd, timeoutMs: START_RUN_TIMEOUT_MS }),
12      toast: text => $.ui.toast(text),
13    }
14    void sessionStart(rules, tools, text => $.ui.log(text), { cwd: e.cwd })
15    return next(e)
16  })
17}
18

1import type { LifecycleRule } from '../engine'
2
3export const STALE_DAYS = 7
4const LISTED = 5
5const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/
6
7// The ids in `bd stale --json`, or none for anything that is not a list of
8// beads. Ids are checked, so a strange id never reaches the toast.
9export const staleIds = (stdout: string): readonly string[] => {
10  const parsed: unknown = JSON.parse(stdout)
11  if (!Array.isArray(parsed)) return []
12  return parsed.flatMap((item: unknown) => {
13    const id = typeof item === 'object' && item !== null && 'id' in item ? item.id : undefined
14    return typeof id === 'string' && ID.test(id) ? [id] : []
15  })
16}
17
18export const toastText = (ids: readonly string[]): string => {
19  const shown = ids.slice(0, LISTED).join(', ')
20  const more = ids.length > LISTED ? ` and ${ids.length - LISTED} more` : ''
21  const subject = ids.length === 1 ? '1 bead in progress has' : `${ids.length} beads in progress have`
22  return `${subject} had no update for ${STALE_DAYS} days: ${shown}${more}`
23}
24
25// At session start, one toast when beads in progress have had no update for 7
26// days. Reads with `bd stale`; without bd, without a beads project or on any
27// odd answer it says nothing.
28export const rule: LifecycleRule = {
29  id: 'bead-stale-nudge',
30  onSessionStart: async (e, tools) => {
31    const done = await tools
32      .run(['bd', 'stale', '--days', String(STALE_DAYS), '--status', 'in_progress', '--limit', '500', '--json'], e.cwd)
33      .catch(() => undefined)
34    if (done === undefined || done.exitCode !== 0 || done.stdout.trim() === '') return
35    let ids: readonly string[]
36    try {
37      ids = staleIds(done.stdout)
38    } catch {
39      return
40    }
41    if (ids.length > 0) await tools.toast(toastText(ids))
42  },
43}
44

1import type { PluginOptions, ProcessRunResult, ToolCallEnvelope, ToolCallResult } from 'claude-code'
2
3// What each kind of rule may use. The engine forbids passing `$` itself, so
4// it hands over these functions instead, one set per hook.
5export type PushTools = {
6  post: (url: string, headers: Record<string, string>, body: string) => Promise<void>
7}
8
9export type RunTools = {
10  run: (argv: readonly string[]) => Promise<ProcessRunResult>
11}
12
13export type NotifyTools = PushTools & RunTools
14
15// What a rule at the session's start may use: a program run in the session's
16// folder, and a toast for the person.
17export type StartTools = {
18  run: (argv: readonly string[], cwd: string) => Promise<ProcessRunResult>
19  toast: (text: string) => unknown
20}
21
22export type ToolTools = PushTools & {
23  cwd: () => Promise<string>
24  root: () => Promise<string>
25  exists: (path: string) => Promise<boolean>
26  read: (path: string) => Promise<string>
27  list: (path: string) => Promise<readonly string[]>
28  run: (argv: readonly string[], cwd?: string) => Promise<ProcessRunResult>
29}
30
31export type JournalTools = {
32  home: () => Promise<string | undefined>
33  now: () => Promise<number>
34  exists: (path: string) => Promise<boolean>
35  read: (path: string) => Promise<string>
36  write: (path: string, text: string) => Promise<void>
37}
38
39// The plugin's userConfig values, checked.
40export type Settings = { ntfyTopic: string; longRunSecs: number; slackWebhookUrl: string; discordWebhookUrl: string }
41
42export const DEFAULT_LONG_RUN_SECS = 60
43
44const text = (value: unknown): string => (typeof value === 'string' ? value.trim() : '')
45
46export const settingsFrom = (options: PluginOptions): Settings => {
47  const secs = options['longRunSecs']
48  return {
49    ntfyTopic: text(options['ntfyTopic']),
50    longRunSecs: typeof secs === 'number' && Number.isFinite(secs) && secs > 0 ? secs : DEFAULT_LONG_RUN_SECS,
51    slackWebhookUrl: text(options['slackWebhookUrl']),
52    discordWebhookUrl: text(options['discordWebhookUrl']),
53  }
54}
55
56// A finished tool call, as the rules after a tool see it.
57export type ToolRun = { e: ToolCallEnvelope; elapsedMs: number }
58
59// A finished main-loop turn, as the rules at a turn's end see it.
60export type TurnEnd = { cwd: string; durationMs: number; isAborted: boolean }
61
62// One lifecycle rule. Each member is optional: a rule names what it does at
63// the moments it cares about. `afterTool` may return a note the model reads
64// with the tool's result; the others act on the outside world.
65export type LifecycleRule = {
66  id: string
67  afterTool?: (run: ToolRun, tools: ToolTools, settings: Settings) => Promise<string | undefined>
68  onNeedsInput?: (e: { cwd: string }, tools: NotifyTools, settings: Settings) => Promise<void>
69  onSessionStart?: (e: { cwd: string }, tools: StartTools) => Promise<void>
70  onTurnEnd?: (e: TurnEnd, tools: RunTools, settings: Settings) => Promise<void>
71  onSessionEnd?: (e: { cwd: string; reason: string }, tools: JournalTools, settings: Settings) => Promise<void>
72}
73
74const PUSH_TIMEOUT_MS = 5000
75// The Notification types that wait for the person. Others (auth_success and
76// the like) need no input, so they send nothing.
77const NEEDS_INPUT = new Set(['permission_prompt', 'idle_prompt', 'elicitation_dialog'])
78// A desktop notification or a spoken line must not hold up the session long.
79export const NOTIFY_TIMEOUT_MS = 10_000
80export const RUN_TIMEOUT_MS = 30_000
81// A read of bd at the session start must not hold anything up for long.
82export const START_RUN_TIMEOUT_MS = 10_000
83
84type Log = (text: string) => unknown
85
86const failed = (id: string, error: unknown): string =>
87  `${id}: skipped, ${error instanceof Error ? error.message : String(error)}`
88
89// A rule that throws is logged and skipped, never allowed to break the tool
90// call or the shutdown.
91const guarded = async (id: string, log: Log, work: () => Promise<void>): Promise<void> => {
92  try {
93    await work()
94  } catch (error) {
95    await log(failed(id, error))
96  }
97}
98
99// The fetch has no timeout of its own, and a stuck push must not hold up the
100// tool result. `fetch` and `sleep` are closures over the hook's `$`.
101export const push = async (fetch: () => Promise<{ ok: boolean; status: number }>, sleep: (ms: number) => Promise<void>) => {
102  const answer = await Promise.race([
103    fetch(),
104    sleep(PUSH_TIMEOUT_MS).then(() => {
105      throw new Error('the push timed out')
106    }),
107  ])
108  if (!answer.ok) throw new Error(`the push was refused (HTTP ${answer.status})`)
109}
110
111// The tools a host does not give. A rule that calls one is logged and
112// skipped, and its tests fail: name what it uses in engine.json `needs`.
113const absent = (name: string) => (): Promise<never> =>
114  Promise.reject(new Error(`${name} is not given to this mod; name it in engine.json needs`))
115
116export const NO_TOOL_TOOLS: ToolTools = {
117  cwd: absent('cwd'),
118  root: absent('root'),
119  exists: absent('exists'),
120  read: absent('read'),
121  list: absent('list'),
122  run: absent('run'),
123  post: absent('post'),
124}
125
126export const NO_NOTIFY_TOOLS: NotifyTools = { post: absent('post'), run: absent('run') }
127
128// After each tool call that ran (not denied, no error): each rule's
129// `afterTool`, and the notes they return beside the result. `now` and `log`
130// close over the hook's `$`.
131export const afterTool = async (
132  rules: readonly LifecycleRule[],
133  settings: Settings,
134  tools: ToolTools,
135  host: { now: () => Promise<number>; log: Log },
136  e: ToolCallEnvelope,
137  next: (e: ToolCallEnvelope) => Promise<ToolCallResult>,
138): Promise<ToolCallResult> => {
139  const startedAt = await host.now()
140  const ran = await next(e)
141  if (ran.deny !== undefined || ran.isError !== undefined) return ran
142  const elapsedMs = (await host.now()) - startedAt
143  let notes: readonly string[] = []
144  for (const rule of rules) {
145    await guarded(rule.id, host.log, async () => {
146      const note = await rule.afterTool?.({ e, elapsedMs }, tools, settings)
147      if (note !== undefined) notes = [...notes, note]
148    })
149  }
150  return notes.length === 0 ? ran : { ...ran, context: [...(ran.context ?? []), ...notes] }
151}
152
153// Only the Notification types that wait for the person reach the rules.
154export const needsInput = async (
155  rules: readonly LifecycleRule[],
156  settings: Settings,
157  tools: NotifyTools,
158  log: Log,
159  e: { cwd: string; notification_type: string },
160): Promise<void> => {
161  if (!NEEDS_INPUT.has(e.notification_type)) return
162  for (const rule of rules) await guarded(rule.id, log, async () => rule.onNeedsInput?.(e, tools, settings))
163}
164
165export const sessionStart = async (rules: readonly LifecycleRule[], tools: StartTools, log: Log, e: { cwd: string }): Promise<void> => {
166  for (const rule of rules) await guarded(rule.id, log, async () => rule.onSessionStart?.(e, tools))
167}
168
169export const turnEnd = async (rules: readonly LifecycleRule[], settings: Settings, tools: RunTools, log: Log, end: TurnEnd): Promise<void> => {
170  for (const rule of rules) await guarded(rule.id, log, async () => rule.onTurnEnd?.(end, tools, settings))
171}
172
173export const sessionEnd = async (
174  rules: readonly LifecycleRule[],
175  settings: Settings,
176  tools: JournalTools,
177  log: Log,
178  e: { cwd: string; reason: string },
179): Promise<void> => {
180  for (const rule of rules) await guarded(rule.id, log, async () => rule.onSessionEnd?.(e, tools, settings))
181}
182