session-saver

1// Session Saver: pairs with unpause.
2//   - Names an untitled session after its second turn (Haiku picks 2-4 words), so `unpause`
3//     lists "ship-mods" instead of a bare id.
4//   - /park [note] saves where you left off and the next step.
5//   - A resumed session shows that note above the prompt until you type, and toasts it.
6import { atom, read, update } from 'claude-code'
7import type { EngineInterface, PromptOrigin, Register } from 'claude-code'
8
9import type { Parked } from '../types'
10import { bandsFile, parseOrder, stackBands } from './bands'
11
12const MODEL = 'haiku'
13const NAME_AFTER_TURNS = 2
14
15// Held by the host, so the resume note survives a hot reload of this file.
16const resumed = atom({ plugin: 'session-saver', key: 'resumed' } as const, null as Parked | null)
17// Whether this process showed the note yet: the session's state, so a reload does not show it twice.
18const isShown = atom({ plugin: 'session-saver', key: 'isShown' } as const, false)
19
20let bandOrder: Promise<string[]> | undefined // read once per session: restart to apply
21
22// The band order file, as the claude-code-mods checklist saves it; [] on any error.
23async function readBandOrder($: EngineInterface): Promise<string[]> {
24  const file = bandsFile(await $.env.get('CLAUDE_CONFIG_DIR'), await $.env.get('HOME'))
25  return file && (await $.fs.exists(file)) ? parseOrder(await $.fs.read(file)) : []
26}
27
28// Forgets the cached band order, for tests.
29export function resetBandOrder() {
30  bandOrder = undefined
31}
32
33export const register: Register = on => {
34  let prompt = ''
35
36  on('session.start', async ($, e, next) => {
37    const r = await next(e)
38    if ((await $.session.messages()).length > 0) void showResume($).catch(() => {})
39    await $.command.register({ name: 'park', description: 'Save where you left off and the next step, for when you resume', argumentHint: '[note]' }).catch(() => {}) // a name Claude Code already has is refused: start anyway
40    return r
41  })
42
43  // A resumed session: bring back where it was left. The engine's resume signal can fire
44  // before this mod loads, so loading into a session that already has messages counts too.
45  on('classic.SessionStart', async ($, e, next) => {
46    const r = await next(e)
47    if (e.source === 'resume') await showResume($)
48    return r
49  })
50
51  // Only what the person typed counts: task notifications, other sessions' messages and
52  // schedules arrive as prompts too, and must not become "you asked" or hide the note.
53  on('prompt.submit', async ($, e, next) => {
54    if (!isTyped(e.origin, e.text)) return next(e)
55    prompt = e.text.slice(0, 600)
56    if (await read($, resumed)) await update($, resumed, () => null) // the note has done its job
57    return next(e)
58  })
59
60  on('turn.complete', async ($, e, next) => {
61    const r = await next(e)
62    if (!e.agentId) {
63      const id = await $.session.id()
64      // Without a /park, a resume still shows the last thing asked.
65      if (prompt) {
66        const last: Parked = { leftOff: `you asked: ${oneLine(prompt, 80)}`, next: '', note: '', at: Date.now() }
67        await $.store.set(`last:${id}`, last)
68      }
69      if ((await $.session.turns()) >= NAME_AFTER_TURNS && !(await $.store.get(`named:${id}`))) {
70        await $.store.set(`named:${id}`, true) // one try per session, whatever happens
71        void autoname($, id).catch(() => {})
72      }
73    }
74    return r
75  })
76
77  on('command.run', { command: 'park' }, async ($, e) => {
78    const id = await $.session.id()
79    const { why, ...parked } = await summarize($, e.args.trim(), prompt)
80    await $.store.set(`park:${id}`, parked)
81    const lines = [`Parked. Left off: ${parked.leftOff}`, parked.next && `Next: ${parked.next}`, parked.note && `Note: ${parked.note}`, why && `(no AI summary: ${why})`, 'Resume any time with unpause.']
82    return { text: lines.filter(Boolean).join('\n') }
83  })
84
85  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
86    const rest = await next(e) // what other mods and Claude Code draw here stays
87    const p = await read($, resumed)
88    if (e.props.hasSurvey || !p) return rest
89    const { Box, Text } = $.ui.resolve(e)
90    const mine = (
91      <Box flexDirection="column">
92        <Text wrap="truncate-end">
93          <Text color="green" bold>{` ↩ Last time (${ago(p.at)}): `}</Text>
94          <Text>{p.leftOff}</Text>
95          {p.next !== '' && <Text dimColor>{'  ·  next: '}</Text>}
96          {p.next !== '' && <Text>{p.next}</Text>}
97        </Text>
98        {p.note !== '' && <Text dimColor wrap="truncate-end">{`   note: ${p.note}`}</Text>}
99      </Box>
100    )
101    bandOrder ??= readBandOrder($).catch(() => [])
102    return stackBands(rest, 'session-saver', mine, 'above', await bandOrder) // above what other mods draw, unless the band order says otherwise
103  })
104}
105
106async function showResume($: EngineInterface) {
107  if (await read($, isShown)) return
108  const id = await $.session.id()
109  const parked = ((await $.store.get(`park:${id}`)) ?? (await $.store.get(`last:${id}`))) as Parked | undefined
110  if (!parked) return
111  await update($, isShown, () => true)
112  await update($, resumed, () => parked)
113  $.ui.toast(`Last time (${ago(parked.at)}): ${parked.leftOff}${parked.next ? ` · next: ${parked.next}` : ''}`, { timeoutMs: 8000 })
114}
115
116// Names the session through unpause, only when nobody named it yet.
117async function autoname($: EngineInterface, id: string) {
118  const list = await $.process.run(['unpause', 'list', '--json'], { timeoutMs: 20_000 })
119  const row = (JSON.parse(list.stdout || '[]') as { id: string; custom_title?: string }[]).find(s => s.id === id)
120  if (!row || row.custom_title) return
121
122  const messages = (await $.session.messages()).filter(m => m.role === 'user').slice(0, 3)
123  const r = await $.model.complete({
124    model: MODEL,
125    maxTokens: 30,
126    system: 'Name a coding session in 2 to 4 lowercase words joined by hyphens (like "ship-mods" or "fix-login-ci"). Reply with the name only.',
127    prompt: messages.map(m => m.text.slice(0, 500)).join('\n---\n'),
128  })
129  if (!r.isAnswered) return
130  const name = kebab(r.text)
131  if (!name) return
132  const done = await $.process.run(['unpause', 'rename', id, name], { timeoutMs: 20_000 })
133  if (done.exitCode === 0) $.ui.toast(`Session named "${name}" (rename any time with /rename)`)
134}
135
136async function summarize($: EngineInterface, note: string, prompt: string): Promise<Parked & { why?: string }> {
137  // Only messages with words in them: tool-only turns and tool results carry no text.
138  const messages = (await $.session.messages()).filter(m => m.text.trim() !== '').slice(-12)
139  const asked = prompt || messages.filter(m => m.role === 'user' && !isWrapped(m.text)).at(-1)?.text || ''
140  const fallback = { leftOff: asked ? `you asked: ${oneLine(asked, 70)}` : 'parked', next: '', note, at: Date.now() }
141  const r = await $.model.complete({
142    model: MODEL,
143    maxTokens: 300,
144    system:
145      'Someone is pausing a coding session and will resume it later. Plain words, no em dashes. ' +
146      'Reply with JSON only, no code fence: {"leftOff": "where things stand, at most 80 characters", "next": "the next step, at most 60 characters"}.',
147    // The transcript is material to summarize, not a chat to continue: tagged, instruction last.
148    prompt: [
149      '<transcript>',
150      ...messages.map(m => `[${m.role === 'user' ? 'person' : 'assistant'}] ${m.text.slice(0, 600)}`),
151      '</transcript>',
152      '',
153      'Summarize the transcript above for when they resume. Reply with the JSON object only.',
154    ].join('\n'),
155  })
156  if (!r.isAnswered) return { ...fallback, why: r.reason }
157  try {
158    const o = JSON.parse(r.text.slice(r.text.indexOf('{'), r.text.lastIndexOf('}') + 1)) as { leftOff?: string; next?: string }
159    const leftOff = oneLine(o.leftOff ?? '', 80)
160    if (!leftOff) return { ...fallback, why: 'empty summary' }
161    return { leftOff, next: oneLine(o.next ?? '', 60), note, at: Date.now() }
162  } catch {
163    return { ...fallback, why: `reply was not JSON: ${oneLine(r.text, 60)}` }
164  }
165}
166
167// The person's own words: typed at the prompt, from the phone bridge or the SDK host, a Slack
168// ping from the owner, or a mod sending them as the person's (`asUser`). No origin counts as
169// typed (the engine leaves it out for the person's own prompt).
170const TYPED = new Set(['composer', 'bridge', 'sdk', 'slack-ping'])
171
172export function isTyped(origin: PromptOrigin | undefined, text: string) {
173  if (isWrapped(text)) return false
174  if (!origin) return true
175  return TYPED.has(origin.kind) || (origin.kind === 'plugin' && origin.asUser === true)
176}
177
178// Text the engine wraps in tags or frames, not words anyone typed: `<task-notification>`,
179// `<local-command-caveat>`, `<command-name>`, `<system-reminder>`, a peer session's message.
180export function isWrapped(text: string) {
181  const t = text.trimStart()
182  // Only the engine's own wrappers: a prompt the person starts with `<div>` is still theirs.
183  return /^<(task-notification|local-command-caveat|local-command-stdout|command-name|command-message|command-args|system-reminder)\b/.test(t) || t.startsWith('Another Claude session sent a message')
184}
185
186export function kebab(text: string) {
187  return text
188    .toLowerCase()
189    .replace(/["'`.]/g, '')
190    .replace(/[^a-z0-9]+/g, '-')
191    .replace(/^-+|-+$/g, '')
192    .split('-')
193    .slice(0, 4)
194    .join('-')
195}
196
197export function ago(at: number, now = Date.now()) {
198  const m = Math.round((now - at) / 60_000)
199  if (m < 1) return 'just now'
200  if (m < 60) return `${m}m ago`
201  const hours = Math.round(m / 60)
202  return hours < 48 ? `${hours}h ago` : `${Math.round(hours / 24)}d ago`
203}
204
205function oneLine(text: string, max: number) {
206  const t = text.replace(/\s+/g, ' ').replace(/\s*—\s*/g, ', ').trim()
207  return t.length <= max ? t : `${t.slice(0, max - 1)}…`
208}
209

1// Band order: every band mod ships this same file (canonical copy: shared/bands.ts in the repo).
2//   The order file, <configDir>/claude-code-mods/bands.json, lists mod names top to bottom
3//   (the last sits right above the prompt). Each band mod wraps its band in a Box keyed
4//   `band:<name>` and returns one column keyed `bands`; the next band mod unpacks that
5//   column, adds its own band and sorts again, so the last one to draw sorts them all.
6//   Edit shared/bands.ts, then copy it over every mod's hooks/bands.ts (a repo test checks).
7//   Reading the file needs $, which Claude Code follows only within one file, so each mod
8//   reads it in its own register file with bandsFile and parseOrder, once per session.
9import type { RenderElement, RenderNode } from 'claude-code'
10
11const COLUMN = 'bands'
12const PREFIX = 'band:'
13
14// Where the checklist saves the order: CLAUDE_CONFIG_DIR, or ~/.claude. Undefined with neither.
15export function bandsFile(configDir: string | undefined, home: string | undefined): string | undefined {
16  const dir = configDir ? configDir.replace(/\/+$/, '') : home ? `${home}/.claude` : ''
17  return dir ? `${dir}/claude-code-mods/bands.json` : undefined
18}
19
20// The names in an order file; [] when it is no JSON or not { order: string[] }.
21export function parseOrder(text: string): string[] {
22  try {
23    const order = (JSON.parse(text) as { order?: unknown } | null)?.order
24    return Array.isArray(order) && order.every(n => typeof n === 'string') ? order : []
25  } catch {
26    return []
27  }
28}
29
30/**
31 * One column of bands: `mine` wrapped in a Box keyed `band:<name>`, placed
32 * `at` (above or below) what `next(e)` returned, then sorted by `order`.
33 * With an order, items that are no band come first, then bands not in the
34 * order (in their current order), then the listed ones in file order. With
35 * no order nothing moves, so the screen looks as it did before.
36 */
37export function stackBands(rest: RenderElement | null | undefined, name: string, mine: RenderNode, at: 'above' | 'below', order: string[]): RenderElement {
38  const own: RenderElement = { type: 'Box', props: { key: PREFIX + name, flexDirection: 'column' }, children: [mine] }
39  const others = unpack(rest)
40  const items = at === 'above' ? [own, ...others] : [...others, own]
41  return { type: 'Box', props: { key: COLUMN, flexDirection: 'column' }, children: order.length ? sorted(items, order) : items }
42}
43
44// Another band mod's column gives up its items; anything else is one item.
45function unpack(rest: RenderElement | null | undefined): RenderNode[] {
46  if (!rest) return []
47  if (!isColumn(rest)) return [rest]
48  const kids = rest.children ?? []
49  const owner = rest.part?.plugin
50  // The engine stamped the column with its owner: that stamp belongs on the owner's own band.
51  return kids.map(k => (owner && typeof k !== 'string' && bandName(k) === owner && !('part' in k && k.part) ? { ...k, part: rest.part } : k))
52}
53
54function isColumn(el: RenderElement): el is RenderElement & { type: 'Box' } {
55  return el.type === 'Box' && el.props?.key === COLUMN
56}
57
58function bandName(node: RenderNode): string | undefined {
59  if (typeof node === 'string' || node.type !== 'Box') return undefined
60  const key = node.props?.key
61  return typeof key === 'string' && key.startsWith(PREFIX) ? key.slice(PREFIX.length) : undefined
62}
63
64function sorted(items: RenderNode[], order: string[]): RenderNode[] {
65  const rank = (n: RenderNode) => {
66    const name = bandName(n)
67    if (name === undefined) return -2 // not a band: first
68    const i = order.indexOf(name)
69    return i < 0 ? -1 : i // a band not in the order: on top of the listed ones
70  }
71  return items.map((n, i) => ({ n, i, r: rank(n) })).sort((a, b) => a.r - b.r || a.i - b.i).map(x => x.n)
72}
73

1export type Parked = { leftOff: string; next: string; note: string; at: number }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'session-saver': { resumed: Parked | null; isShown: boolean }
6  }
7}
8