compact-helper

1import type { Register } from 'claude-code'
2
3// Temporary mod for the darkroom campaign (2026-10-10). The main session runs a long
4// /common:strategic-advance campaign with many background agents; a compaction that drops the
5// HQ packet (which fronts are active, which agents and schedules are live, what the user decided)
6// costs a full reconstruction. This mod watches the context fill and steers every compaction.
7const WARN_PERCENT = 70
8const URGENT_PERCENT = 85
9
10const KEEP = [
11  'This is a long darkroom campaign run with /common:strategic-advance. The summary MUST keep, verbatim where possible:',
12  '1. Where truth lives: D:/Code/darkroom/.strategic-advance/darkroom-alpha/state.json (rebuild the HQ packet from it after compaction, never from chat memory), the ledger run-ledger.jsonl next to it, the map .claude/wayfinder/darkroom/map.md, the contracts in .claude/contract/, CONTEXT.md, AGENTS.md, and the memory folder C:/Users/powde/.claude/projects/D--Code-darkroom/memory/.',
13  '2. Every background agent still running: its id, what it was asked to do, its model, and whether it works on main or in a worktree (with the worktree path and branch).',
14  '3. Every scheduled job (cron id, what it fires, when it ends) and every one-shot schedule still pending.',
15  '4. The active fronts and their state (sealed / in progress / deferred / needs the user), and the next move.',
16  '5. Every decision the user made in this session, in their words, with the date: scope additions, product core (讓人省心), model policy, privacy rules, what must never be written or published.',
17  '6. Open findings not yet fixed, with file:line, and anything the user is waiting on from the agent or the agent from the user.',
18  'Drop raw tool output, file dumps, and resolved back-and-forth.',
19].join('\n')
20
21let percent: number | undefined
22let warnedAt = 0
23
24const statusText = () => (percent === undefined ? undefined : `ctx ${percent}%`)
25
26export const register: Register = on => {
27  on('session.start', async ($, e, next) => {
28    const r = await next(e)
29    await $.command.register({
30      name: 'hq-compact',
31      description: 'Compact now, keeping the darkroom campaign HQ packet (fronts, agents, schedules, user decisions)',
32    })
33    try { percent = (await $.session.usage()).context.percent } catch { /* no reading yet */ }
34    $.ui.status(statusText())
35    return r
36  })
37
38  on('session.measure', ($, e, next) => {
39    percent = e.context.percent
40    $.ui.status(statusText())
41    if (percent !== undefined) {
42      const level = percent >= URGENT_PERCENT ? URGENT_PERCENT : percent >= WARN_PERCENT ? WARN_PERCENT : 0
43      if (level > warnedAt) {
44        warnedAt = level
45        $.ui.toast(level === URGENT_PERCENT
46          ? `compact-helper：context ${percent}%，建議現在就 /hq-compact`
47          : `compact-helper：context ${percent}%，找個空檔 /hq-compact`)
48      }
49      if (percent < WARN_PERCENT) warnedAt = 0
50    }
51    return next(e)
52  })
53
54  on('command.run', { command: 'hq-compact' }, async $ => {
55    await $.session.compact({ instructions: KEEP })
56    return { text: '已壓縮（保留戰役 HQ 封包）。' }
57  })
58
59  // Every compaction of the main conversation (manual, threshold, or ahead of time) keeps the packet.
60  on('session.compact', ($, e, next) => {
61    if (e.agentId) return next(e)
62    const instructions = e.instructions ? `${e.instructions}\n\n${KEEP}` : KEEP
63    return next({ ...e, instructions })
64  }).catch(($, e, next) => next(e))
65}
66