context-handoff

1// The mod's name, as toasts, log lines and the hand-off prompts carry it
2const NAME = 'context-handoff'
3// A tag every prompt this mod submits carries, so its own turn can be told apart
4const MARK = '[context-handoff]'
5// The store key that survives the desktop app's clear, which ends the process
6const RESUME_KEY = 'pendingResume'
7// How long the app gets to clear the conversation once the hand-off turn has ended
8const CLEAR_WAIT_MS = 8000
9// When the compaction is tried after the hand-off turn: it is refused while a turn still runs
10const COMPACT_TRIES_MS = [300, 1000, 2000, 4000, 8000]
11// How long the /compact command gets to compact the conversation where it stands in for the call
12const COMPACT_COMMAND_WAIT_MS = 5 * 60 * 1000
13// How long after the compaction the resume prompt is submitted
14const RESUME_AFTER_COMPACT_MS = 1000
15// What the summarizer is told when the conversation is compacted after a hand-off
16const COMPACT_INSTRUCTIONS =
17  'A hand-off for a fresh start was just recorded in the project notes. Keep only: where the notes are (file and section), ' +
18  'the exact next step, and any question still waiting for the user. Leave out everything else; it is in the notes.'
19
20// Where the hand-off stands:
21//   idle        nothing in progress
22//   closing     the hand-off prompt is submitted; waiting for its turn to run and finish
23//   clearing    (clear) the app was asked to clear; waiting for the conversation to end with it
24//   compacting  (compact) the hand-off turn has ended; compacting the conversation
25//   resuming    the conversation was reset; waiting to submit the resume prompt
26let phase = 'idle'
27// The hand-off prompt as submitted, and the id of the turn running it
28let closeText = null
29let closeTurnId = null
30// The context percent at which the last hand-off began; the next waits for `step` more
31let triggeredAt = null
32// The fallback that submits the resume prompt when no SessionStart follows the clear
33let resumeTimer = null
34// Gives up when the app has not cleared the conversation soon after the hand-off turn ended
35let clearWatchdog = null
36// The compaction attempt waiting to run
37let compactTimer = null
38// How the conversation is being compacted: the engine's call, or the /compact command where
39// the session has no such call (a headless one, as the desktop app runs)
40let compactVia = null
41// Gives up when the /compact command has not compacted the conversation in time
42let compactWatchdog = null
43// True while Remote Control is turned off for the clear, to be turned on again after the resume
44let remoteControlPaused = false
45// The last thing that happened, for /handoff-status
46let lastOutcome = 'nothing yet'
47
48// A number option, or its default when unset or out of range
49function numberOf(value, fallback, min, max) {
50  const n = typeof value === 'string' ? Number(value) : value
51  return typeof n === 'number' && Number.isFinite(n) && n >= min && n <= max ? n : fallback
52}
53
54// The settings, from the options plugin.json declares
55function settingsOf(options) {
56  return {
57    enabled: options.enabled !== false,
58    threshold: numberOf(options.threshold, 40, 1, 100),
59    step: numberOf(options.retriggerStep, 5, 1, 100),
60    reset: options.reset === 'clear' ? 'clear' : 'compact',
61    compaction: options.compaction === 'call' || options.compaction === 'command' ? options.compaction : 'auto',
62    closeCommand: String(options.closeCommand ?? 'session-close').trim().replace(/^\//, ''),
63    closePrompt: String(options.closePrompt ?? '').trim(),
64    resumePrompt: String(options.resumePrompt ?? '').trim(),
65    pauseRemoteControl: options.pauseRemoteControl !== false,
66  }
67}
68
69function fillIn(text, percent, cfg) {
70  return text
71    .replaceAll('{percent}', String(Math.round(percent)))
72    .replaceAll('{threshold}', String(cfg.threshold))
73}
74
75// The prompt that records the hand-off: the project's own close skill when it has one,
76// a custom prompt when configured, or the built-in instructions. It opens with why the
77// hand-off is made: the threshold passed, or /handoff-now asked for it, whatever the context holds
78function closePromptFor(cfg, percent, hasClose, asked) {
79  const fill = `The context window is ${Math.round(percent)}% full`
80  const level = asked
81    ? `${fill}; a hand-off was asked for with /handoff-now.`
82    : `${fill}, past the ${cfg.threshold}% hand-off threshold.`
83  const pending =
84    'If the previous turn stopped to ask the user something, put that question in the notes instead of answering it.'
85  const then = 'the context is then reset automatically and the work continues from the notes.'
86  if (cfg.closePrompt) return `${MARK} ${fillIn(cfg.closePrompt, percent, cfg)}`
87  // A prompt may not begin with a slash, so the skill is named for the model to invoke
88  if (hasClose) {
89    return (
90      `${MARK} ${level} Run this project's /${cfg.closeCommand} skill now (invoke it with the Skill tool) to record the hand-off, ` +
91      `and make the next starting point exact. ${pending} When the notes are written, stop: ${then}`
92    )
93  }
94  return (
95    `${MARK} ${level} Do not start new work. Record a hand-off for a fresh start: ` +
96    "if this project's CLAUDE.md defines a session-close or progress-logging procedure, follow it; " +
97    'otherwise update PROGRESS.md if the project has one, or else write HANDOFF.md at the project root. ' +
98    'Cover what was done this session, the current state, measured facts worth not measuring again, open questions, ' +
99    `and the exact next step. ${pending} When the notes are written, stop: ${then}`
100  )
101}
102
103// The prompt that continues the work after the reset
104function resumePromptFor(cfg) {
105  if (cfg.resumePrompt) return `${MARK} ${cfg.resumePrompt}`
106  return (
107    `${MARK} The context was reset after a hand-off. Read this project's hand-off notes: ` +
108    'the progress file CLAUDE.md names, else PROGRESS.md, else HANDOFF.md at the project root. ' +
109    'Say in one line what you are picking up, then continue from the recorded next step without redoing work the notes mark as done. ' +
110    'If the notes hold a question for the user, ask it and wait.'
111  )
112}
113
114function messageOf(error) {
115  return error instanceof Error ? error.message : String(error)
116}
117
118// The text blocks of an MCP result, joined
119function textOf(result) {
120  return (result.content ?? [])
121    .map((block) => (block.type === 'text' ? block.text : ''))
122    .join(' ')
123    .trim()
124}
125
126// Whether the engine answered that this session has no compaction call: a headless (SDK)
127// session, as the desktop app runs, where a compaction runs as a /compact prompt
128function hasNoCompactCall(message) {
129  return /headless|SDK|\/compact prompt/i.test(message)
130}
131
132// The sizes a compaction reports, for the transcript line
133function sizesOf(result) {
134  return typeof result?.tokensBefore === 'number' && typeof result?.tokensAfter === 'number'
135    ? ` (${result.tokensBefore} to ${result.tokensAfter} tokens)`
136    : ''
137}
138
139// Keep what happened: a dim line in the transcript, and the answer of /handoff-status
140function note($, text) {
141  lastOutcome = text
142  $.ui.log(`${NAME}: ${text}`)
143}
144
145// How full the context window is, in percent; null before the first reading
146async function readPercent($) {
147  try {
148    const { context } = await $.session.usage()
149    if (typeof context.percent === 'number') return context.percent
150    if (typeof context.tokens === 'number' && context.window > 0) return (context.tokens / context.window) * 100
151  } catch {
152    // Keep going without a reading
153  }
154  return null
155}
156
157// Whether the project offers the close command: listed as a command, or a skill folder of the project
158async function hasCommand($, name) {
159  if (!name) return false
160  try {
161    if ((await $.command.list()).some((command) => command.name === name)) return true
162  } catch {
163    // Not listable here; look at the folder
164  }
165  try {
166    const root = await $.session.root()
167    return await $.fs.exists(`${root}/.claude/skills/${name}/SKILL.md`)
168  } catch {
169    return false
170  }
171}
172
173// One call on the desktop app's session server. Resolves to null when it succeeded, else to why not.
174async function callApp($, tool, args) {
175  try {
176    const result = await $.mcp.call('ccd_session_mgmt', tool, args)
177    return result.isError ? textOf(result) || 'no reason given' : null
178  } catch (error) {
179    return messageOf(error)
180  }
181}
182
183// The desktop app's id of this session, which outlives the process; null outside the app
184async function appSessionId($) {
185  try {
186    const result = await $.mcp.call('ccd_session_mgmt', 'get_session', { session_id: 'self' })
187    if (result.isError) return null
188    const id = JSON.parse(textOf(result)).sessionId
189    return typeof id === 'string' ? id : null
190  } catch {
191    return null
192  }
193}
194
195// Turn Remote Control on again after it was turned off for the clear
196async function restoreRemoteControl($) {
197  if (!remoteControlPaused) return
198  remoteControlPaused = false
199  const failed = await callApp($, 'set_remote_control', { session_id: 'self', enabled: true })
200  note($, failed ? `Remote Control could not be turned on again: ${failed}` : 'Remote Control turned on again')
201}
202
203function cancelTimers() {
204  if (resumeTimer) resumeTimer.cancel()
205  if (clearWatchdog) clearWatchdog.cancel()
206  if (compactTimer) compactTimer.cancel()
207  if (compactWatchdog) compactWatchdog.cancel()
208  resumeTimer = clearWatchdog = compactTimer = compactWatchdog = null
209}
210
211function forgetPendingResume($) {
212  $.store.delete(RESUME_KEY).catch(() => {})
213}
214
215// Give up the hand-off in progress and say why; the next tries once the context grew by the step
216function abandon($, reason) {
217  phase = 'idle'
218  closeText = null
219  closeTurnId = null
220  compactVia = null
221  cancelTimers()
222  forgetPendingResume($)
223  note($, `gave up: ${reason}`)
224  $.ui.toast(`${NAME}: ${reason}. /handoff-now retries.`, { timeoutMs: 8000 })
225  void restoreRemoteControl($)
226}
227
228// Submit the hand-off prompt; its turn is found by the tag at turn.start
229async function begin($, cfg, percent, why, asked = false) {
230  phase = 'closing'
231  closeTurnId = null
232  triggeredAt = percent
233  cancelTimers()
234  const text = closePromptFor(cfg, percent, await hasCommand($, cfg.closeCommand), asked)
235  closeText = text
236  note($, `hand-off started: ${why}`)
237  $.ui.toast(`${NAME}: ${why}, recording the hand-off`)
238  $.prompt
239    .submit({ text, asUser: true })
240    .then((result) => {
241      if (result && result.drop && phase === 'closing' && closeText === text) {
242        abandon($, `the hand-off prompt was refused: ${result.drop}`)
243      }
244    })
245    .catch((error) => {
246      if (phase === 'closing' && closeText === text) abandon($, `the hand-off prompt failed: ${messageOf(error)}`)
247    })
248}
249
250// Ask the desktop app to clear this conversation once the running turn ends. The app keeps
251// the request only while the turn runs and acts on it as the turn's result arrives, so it is
252// made as the hand-off turn starts. A session started from another device (Remote Control)
253// cannot be cleared, so Remote Control is turned off for it when allowed.
254async function requestClear($, cfg) {
255  phase = 'clearing'
256  let refused = await callApp($, 'clear_session', { session_id: 'self' })
257  if (refused && cfg.pauseRemoteControl && /remote control/i.test(refused)) {
258    const failed = await callApp($, 'set_remote_control', { session_id: 'self', enabled: false })
259    if (failed) {
260      return abandon($, `the app refused to clear the context: ${refused}; Remote Control could not be turned off: ${failed}`)
261    }
262    remoteControlPaused = true
263    note($, 'Remote Control turned off for the clear; it is turned on again after the resume')
264    refused = await callApp($, 'clear_session', { session_id: 'self' })
265  }
266  if (refused) return abandon($, `the app refused to clear the context: ${refused}`)
267  // The clear ends this process; the next one finds the resume to make in the store
268  try {
269    await $.store.set(RESUME_KEY, {
270      appSessionId: await appSessionId($),
271      cwd: await $.session.cwd(),
272      askedAt: await $.clock.now(),
273    })
274  } catch (error) {
275    note($, `the resume could not be stored for the next process: ${messageOf(error)}`)
276  }
277  note($, 'the app will clear the conversation when the hand-off turn ends')
278}
279
280// The hand-off turn has ended: the app clears the conversation now, or the hand-off is given up
281function awaitClear($) {
282  note($, 'hand-off recorded, waiting for the app to clear the conversation')
283  $.ui.toast(`${NAME}: hand-off recorded, clearing the context`)
284  if (clearWatchdog) clearWatchdog.cancel()
285  clearWatchdog = $.clock.after(CLEAR_WAIT_MS, () => {
286    clearWatchdog = null
287    if (phase === 'clearing') {
288      abandon($, `the app did not clear the conversation within ${CLEAR_WAIT_MS / 1000} s of the hand-off turn ending`)
289    }
290  })
291}
292
293// The hand-off turn has ended: compact the conversation down to the notes, then resume.
294// A compaction is refused while a turn still runs, so it is tried a few times. A session
295// with no compaction call of its own (the desktop app's) compacts through /compact instead,
296// as does one configured to.
297function startCompaction($, cfg) {
298  phase = 'compacting'
299  compactVia = 'call'
300  note($, 'hand-off recorded, compacting the conversation')
301  $.ui.toast(`${NAME}: hand-off recorded, compacting the conversation`)
302  const attempt = (i) => {
303    compactTimer = $.clock.after(COMPACT_TRIES_MS[i], async () => {
304      compactTimer = null
305      if (phase !== 'compacting') return
306      if (cfg.compaction === 'command') return compactByCommand($, cfg, 'compacting through /compact, as configured')
307      let result
308      try {
309        result = await $.session.compact({ instructions: COMPACT_INSTRUCTIONS })
310      } catch (error) {
311        const message = messageOf(error)
312        if (cfg.compaction === 'auto' && hasNoCompactCall(message)) {
313          return compactByCommand($, cfg, 'this session has no compaction call; compacting through /compact')
314        }
315        if (i + 1 < COMPACT_TRIES_MS.length) return attempt(i + 1)
316        return abandon($, `the conversation could not be compacted: ${message}`)
317      }
318      if (result && result.skip) return abandon($, `the compaction was skipped: ${result.skip}`)
319      compacted($, cfg, `compacted the conversation${sizesOf(result)}`, 0)
320    })
321  }
322  attempt(0)
323}
324
325// Compact through the /compact command, queued as if typed, with the same instructions.
326// The compaction is seen as it runs, by the session.compact hook; the command's own answer,
327// which may come later or never, stands in when the hook saw nothing.
328function compactByCommand($, cfg, why) {
329  compactVia = 'command'
330  note($, why)
331  if (compactWatchdog) compactWatchdog.cancel()
332  compactWatchdog = $.clock.after(COMPACT_COMMAND_WAIT_MS, () => {
333    compactWatchdog = null
334    if (phase === 'compacting') {
335      abandon($, `the /compact command did not compact the conversation within ${COMPACT_COMMAND_WAIT_MS / 60000} min`)
336    }
337  })
338  $.command
339    .run({ command: 'compact', args: COMPACT_INSTRUCTIONS })
340    .then(async (result) => {
341      if (phase !== 'compacting') return
342      // The hook saw no compaction: the context says whether the command made one
343      const percent = await readPercent($)
344      const answer = typeof result?.text === 'string' && result.text.trim() ? `: ${result.text.trim().slice(0, 160)}` : ''
345      if (percent !== null && triggeredAt && percent >= triggeredAt) {
346        return abandon($, `the /compact command ran, but the context is still at ${Math.round(percent)}%${answer}`)
347      }
348      compacted($, cfg, `the /compact command finished${percent === null ? '' : `, the context at ${Math.round(percent)}%`}`)
349    })
350    .catch((error) => {
351      if (phase === 'compacting') abandon($, `the /compact command failed: ${messageOf(error)}`)
352    })
353}
354
355// The conversation is compacted: the resume prompt follows, once. From the engine's call it
356// follows at once (the call resolves between turns, the compaction installed); from /compact
357// a moment later, as the hook sees the compaction while the command's turn still runs.
358function compacted($, cfg, what, afterMs = RESUME_AFTER_COMPACT_MS) {
359  if (phase !== 'compacting') return
360  phase = 'resuming'
361  cancelTimers()
362  note($, what)
363  if (afterMs === 0) submitResume($, cfg)
364  else resumeTimer = $.clock.after(afterMs, () => submitResume($, cfg))
365}
366
367// Submit the resume prompt into the fresh conversation, once
368function submitResume($, cfg) {
369  if (phase !== 'resuming') return
370  phase = 'idle'
371  closeText = null
372  closeTurnId = null
373  triggeredAt = null
374  compactVia = null
375  cancelTimers()
376  forgetPendingResume($)
377  note($, 'continuing in a fresh context')
378  $.ui.toast(`${NAME}: continuing in a fresh context`)
379  $.prompt.submit({ text: resumePromptFor(cfg), asUser: true }).catch(() => {})
380}
381
382// A fresh process after the app's clear: when the store says this session's hand-off asked
383// for a resume, and no prompt has run yet, continue from the notes. The app starts that process
384// at the user's next message, however long after the clear, so the resume keeps until then
385async function resumeIfPending($, cfg) {
386  let pending
387  try {
388    pending = await $.store.get(RESUME_KEY)
389  } catch {
390    return
391  }
392  if (!pending || typeof pending !== 'object') return
393  const forget = () => forgetPendingResume($)
394  if ((await $.session.turns()) !== 0) return forget()
395  const id = await appSessionId($)
396  const isThisSession =
397    id && pending.appSessionId ? id === pending.appSessionId : (await $.session.cwd()) === pending.cwd
398  // Another session's hand-off: leave its resume to it
399  if (!isThisSession) return
400  forget()
401  phase = 'resuming'
402  note($, 'a fresh process after the clear; continuing from the notes')
403  resumeTimer = $.clock.after(1000, () => submitResume($, cfg))
404}
405
406export function register(on, options) {
407  const cfg = settingsOf(options)
408
409  // Runs before your first prompt, and again after a reload
410  on('session.start', async ($, e, next) => {
411    await $.command.register({
412      name: 'handoff-now',
413      description: 'Record a hand-off now, reset the context, and continue from the notes',
414    })
415    await $.command.register({
416      name: 'handoff-status',
417      description: 'Show where the automatic hand-off stands and what it did last',
418    })
419    await resumeIfPending($, cfg)
420    return next(e)
421  })
422
423  // The turn that runs the hand-off prompt is the one whose text carries the tag. With the
424  // clear, the app is asked as it starts, so the conversation is cleared as this turn ends.
425  on('turn.start', async ($, e, next) => {
426    if (phase === 'closing' && closeTurnId === null && typeof e.text === 'string' && e.text.includes(MARK)) {
427      closeTurnId = e.turnId
428      note($, 'the hand-off turn is running')
429      if (cfg.reset === 'clear') await requestClear($, cfg)
430    }
431    return next(e)
432  })
433
434  on('turn.complete', async ($, e, next) => {
435    const out = await next(e)
436    // A subagent's turn is not the conversation's
437    if (e.agentId !== undefined) return out
438    const ended = e.reason ?? (e.isAborted ? 'aborted' : 'answer')
439
440    if (phase === 'closing') {
441      // The hand-off prompt is still queued, behind the turn that just ran
442      if (e.turnId !== closeTurnId) return out
443      if (ended === 'aborted') abandon($, 'the hand-off turn was interrupted')
444      else startCompaction($, cfg)
445      return out
446    }
447    if (phase === 'clearing') {
448      if (e.turnId === closeTurnId) {
449        // An interrupted hand-off turn takes the app's queued clear with it
450        if (ended === 'aborted') abandon($, 'the hand-off turn was interrupted')
451        else awaitClear($)
452      } else if (ended === 'answer') {
453        // A turn ran after the hand-off, so the app dropped the clear: record again
454        const percent = (await readPercent($)) ?? triggeredAt ?? cfg.threshold
455        await begin($, cfg, percent, 'a turn ran before the clear')
456      }
457      return out
458    }
459    if (phase !== 'idle') return out
460    // The resume turn has run: the session may serve Remote Control again
461    await restoreRemoteControl($)
462    if (!cfg.enabled || ended !== 'answer') return out
463
464    const percent = await readPercent($)
465    if (percent === null || percent < cfg.threshold) return out
466    if (triggeredAt !== null && percent < triggeredAt + cfg.step) return out
467    await begin($, cfg, percent, `context at ${Math.round(percent)}%, past ${cfg.threshold}%`)
468    return out
469  })
470
471  // A compaction run through /compact passes here as it runs: once it stands, the resume
472  // follows; a compaction the engine makes on its own meanwhile serves as well
473  on('session.compact', async ($, e, next) => {
474    const watching = phase === 'compacting' && compactVia === 'command' && e.agentId === undefined
475    let out
476    try {
477      out = await next(e)
478    } catch (error) {
479      if (watching && phase === 'compacting') abandon($, `the compaction failed: ${messageOf(error)}`)
480      throw error
481    }
482    if (watching && phase === 'compacting') {
483      if (out && out.skip !== undefined) abandon($, `the compaction was skipped: ${out.skip}`)
484      else compacted($, cfg, `compacted the conversation${sizesOf(out)}`)
485    }
486    return out
487  })
488
489  // A /clear ends the conversation; where the process goes on, it continues with a fresh one
490  on('session.end', async ($, e, next) => {
491    if (e.reason === 'clear' && phase === 'clearing') {
492      phase = 'resuming'
493      cancelTimers()
494      resumeTimer = $.clock.after(3000, () => submitResume($, cfg))
495    } else if (e.reason !== 'clear') {
496      phase = 'idle'
497      cancelTimers()
498    }
499    return next(e)
500  })
501
502  // The fresh conversation's SessionStart is the moment to continue
503  on('classic.SessionStart', async ($, e, next) => {
504    const out = await next(e)
505    if (e.source === 'clear' && phase === 'resuming') submitResume($, cfg)
506    return out
507  }).catch(($, e, next) => next(e)) // A failure here never holds up the session
508
509  // Hand off on request, whatever the context holds. A prompt cannot be submitted from
510  // inside a command's own run, so the hand-off begins a moment later, from a timer.
511  on('command.run', { command: 'handoff-now' }, async ($) => {
512    if (phase !== 'idle') return { text: `A hand-off is already in progress (${phase})` }
513    const percent = (await readPercent($)) ?? 0
514    phase = 'closing'
515    $.clock.after(50, () => {
516      phase = 'idle'
517      void begin($, cfg, percent, 'asked by /handoff-now', true)
518    })
519    return {
520      text:
521        `Recording the hand-off at ${Math.round(percent)}% context. ` +
522        `Once it is written the context is reset (${cfg.reset}) and the work continues from the notes.`,
523    }
524  })
525
526  on('command.run', { command: 'handoff-status' }, async ($) => {
527    const percent = await readPercent($)
528    const fill = percent === null ? 'no reading yet' : `${Math.round(percent)}%`
529    return {
530      text:
531        `Phase: ${phase}. Context: ${fill} (threshold ${cfg.threshold}%). ` +
532        `Automatic hand-off: ${cfg.enabled ? 'on' : 'off'}. Reset: ${cfg.reset}. Last: ${lastOutcome}.`,
533    }
534  })
535}
536