context-handoff

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register, SessionContextUsage, SessionRateLimit } from 'claude-code'
3
4import type { Handoff } from '../types'
5import {
6  HANDOFF_FILE,
7  SUMMARY_PROMPT,
8  commitMessage,
9  formatStatus,
10  handoffMarkdown,
11  limitReason,
12  resumePrompt,
13  resumeQuestion,
14  storeKey,
15  wrapUpNote,
16} from './logic'
17
18const pending = atom({ plugin: 'context-handoff', key: 'pending' } as const, null)
19const hasSavedThisSession = atom({ plugin: 'context-handoff', key: 'hasSavedThisSession' } as const, false)
20
21const FALLBACK_PROMPTS = 3
22
23async function git($: EngineInterface, args: string[], cwd: string): Promise<{ isOk: boolean; out: string }> {
24  try {
25    const ran = await $.process.run(['git', ...args], { cwd })
26    return { isOk: ran.exitCode === 0, out: ran.stdout.trim() }
27  } catch (error) {
28    $.ui.log(`context-handoff: git ${args[0]} failed: ${String(error)}`)
29    return { isOk: false, out: '' }
30  }
31}
32
33async function repoRootOf($: EngineInterface): Promise<string> {
34  const cwd = await $.session.cwd()
35  const root = await git($, ['rev-parse', '--show-toplevel'], cwd)
36
37  return root.isOk && root.out !== '' ? root.out : cwd
38}
39
40/** Asks the session itself what it was doing; falls back to the last prompts typed. */
41async function summarize($: EngineInterface): Promise<string> {
42  const reply = await $.model.fork({ prompt: SUMMARY_PROMPT })
43  if (reply.isAnswered && reply.text.trim() !== '') {
44    return reply.text.trim()
45  }
46  $.ui.log(`context-handoff: summary fork gave no text (${reply.isAnswered ? 'empty' : reply.reason}), using recent prompts`)
47  const messages = await $.session.messages()
48  const prompts = messages
49    .filter(message => message.role === 'user' && message.text.trim() !== '')
50    .slice(-FALLBACK_PROMPTS)
51    .map(message => `- ${message.text.trim().slice(0, 500)}`)
52
53  return ['## 直近の依頼 (自動要約に失敗したため原文)', ...prompts].join('\n')
54}
55
56/** Stages everything .gitignore allows and commits it; answers the short sha, or '' when nothing was committed. */
57async function commitAll($: EngineInterface, repoRoot: string, reason: string): Promise<string> {
58  const isRepo = (await git($, ['rev-parse', '--is-inside-work-tree'], repoRoot)).isOk
59  if (!isRepo) {
60    return ''
61  }
62  await git($, ['add', '-A'], repoRoot)
63  const hasStaged = !(await git($, ['diff', '--cached', '--quiet'], repoRoot)).isOk
64  if (!hasStaged) {
65    return ''
66  }
67  const committed = await git($, ['commit', '-m', commitMessage(reason)], repoRoot)
68  if (!committed.isOk) {
69    $.ui.toast('context-handoff: チェックポイントのコミットに失敗しました (pre-commit hook 等)。変更はステージ済みです')
70    return ''
71  }
72
73  return (await git($, ['rev-parse', '--short', 'HEAD'], repoRoot)).out
74}
75
76async function checkpoint($: EngineInterface, reason: string): Promise<Handoff> {
77  await update($, hasSavedThisSession, () => true)
78  $.ui.toast(`${reason}。作業を記録してコミットします…`)
79
80  const repoRoot = await repoRootOf($)
81  const branch = (await git($, ['rev-parse', '--abbrev-ref', 'HEAD'], repoRoot)).out || '(なし)'
82  const createdAt = new Date(await $.clock.now()).toISOString()
83  const summary = await summarize($)
84  const draft: Handoff = { repoRoot, branch, commit: '', reason, summary, createdAt }
85
86  await $.fs.write(`${repoRoot}/${HANDOFF_FILE}`, handoffMarkdown(draft))
87  const handoff: Handoff = { ...draft, commit: await commitAll($, repoRoot, reason) }
88  await $.store.set(storeKey(repoRoot), handoff)
89
90  await $.session.append({ message: { type: 'user', content: [{ type: 'text', text: wrapUpNote(handoff) }] } })
91  $.ui.toast(`引き継ぎを保存しました (${handoff.commit || 'コミットなし'})。次回起動時に続行を確認します`)
92
93  return handoff
94}
95
96function showUsage($: EngineInterface, context: SessionContextUsage, rateLimits: readonly SessionRateLimit[]) {
97  $.ui.status(formatStatus(context, rateLimits))
98}
99
100async function settle($: EngineInterface, handoff: Handoff) {
101  await $.store.delete(storeKey(handoff.repoRoot))
102  await update($, pending, () => null)
103}
104
105export const register: Register = on => {
106  on('session.start', async ($, e, next) => {
107    await $.command.register({
108      name: 'handoff',
109      description: '今の作業を記録・コミットし、次のセッションへ引き継ぐ',
110    })
111    const usage = await $.session.usage()
112    showUsage($, usage.context, usage.rateLimits)
113
114    // A hot reload fires session.start again: never offer this session's own handoff back to it.
115    const isOwnHandoff = await read($, hasSavedThisSession)
116    if (e.isInteractive && !isOwnHandoff) {
117      const saved = (await $.store.get(storeKey(await repoRootOf($)))) as Handoff | undefined
118      if (saved !== undefined) {
119        await update($, pending, () => saved)
120        $.ui.toast(resumeQuestion(saved))
121      }
122    }
123
124    return next(e)
125  })
126
127  on('session.measure', async ($, e, next) => {
128    showUsage($, e.context, e.rateLimits)
129    const reason = limitReason(e.context, e.rateLimits)
130    if (reason !== null && !(await read($, hasSavedThisSession))) {
131      await checkpoint($, reason)
132    }
133
134    return next(e)
135  })
136
137  on('command.run', { command: 'handoff' }, async $ => {
138    const handoff = await checkpoint($, '手動で引き継ぎを要求')
139
140    return { text: `引き継ぎを ${handoff.repoRoot}/${HANDOFF_FILE} に保存しました (${handoff.commit || 'コミットなし'})。` }
141  })
142
143  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
144    const handoff = await read($, pending)
145    if (handoff === null) {
146      return next(e)
147    }
148    const { Box, Button, Text } = $.ui.resolve(e)
149
150    return (
151      <Box flexDirection="column" borderStyle="round" paddingX={1}>
152        <Text bold>{resumeQuestion(handoff)}</Text>
153        <Text dimColor>
154          {handoff.reason} · {handoff.branch} · {handoff.commit || 'コミットなし'} · {handoff.createdAt}
155        </Text>
156        <Box>
157          <Button
158            key="resume"
159            label="続行する"
160            hotkey="y"
161            variant="primary"
162            onPress={async () => {
163              await settle($, handoff)
164              await $.prompt.submit({ text: resumePrompt(handoff), asUser: true })
165            }}
166          />
167          <Button key="discard" label="破棄する" hotkey="n" onPress={() => settle($, handoff)} />
168        </Box>
169      </Box>
170    )
171  })
172}
173

1import type { SessionContextUsage, SessionRateLimit } from 'claude-code'
2
3import type { Handoff } from '../types'
4
5export const CONTEXT_THRESHOLD = 90
6export const RATE_LIMIT_THRESHOLD = 90
7export const HANDOFF_FILE = '.claude/handoff.md'
8
9const LIMIT_LABELS: Record<string, string> = {
10  five_hour: '5h',
11  seven_day: '7d',
12  spend_limit: 'spend',
13}
14
15export const SUMMARY_PROMPT = [
16  'トークン制限が近いため、この作業を次のエージェントに引き継ぎます。',
17  '次のエージェントが会話履歴なしで作業を再開できるよう、日本語のMarkdownで以下を簡潔にまとめてください。',
18  '見出しは「## 目的」「## 完了したこと」「## 残っていること」「## 次の一手」「## 関連ファイル」の5つ。',
19  '推測は推測と明記し、まとめ以外の前置きは書かないでください。',
20].join('\n')
21
22const formatTokens = (n: number): string => (n >= 1000 ? `${Math.round(n / 1000)}k` : String(n))
23
24export const limitLabel = (kind: string): string => LIMIT_LABELS[kind] ?? kind
25
26export function formatStatus(context: SessionContextUsage, rateLimits: readonly SessionRateLimit[]): string {
27  const ctx =
28    context.percent === undefined || context.tokens === undefined
29      ? `ctx --/${formatTokens(context.window)}`
30      : `ctx ${context.percent}% (${formatTokens(context.tokens)}/${formatTokens(context.window)})`
31  const limits = rateLimits.map(limit => `${limitLabel(limit.kind)} ${limit.percentUsed}%`)
32
33  return [ctx, ...limits].join(' · ')
34}
35
36/** Why a handoff is due, or null while every figure is under its threshold. */
37export function limitReason(context: SessionContextUsage, rateLimits: readonly SessionRateLimit[]): string | null {
38  const hot = rateLimits.find(limit => limit.percentUsed >= RATE_LIMIT_THRESHOLD)
39  if (hot !== undefined) {
40    return `レート制限 ${limitLabel(hot.kind)} が ${hot.percentUsed}% に到達`
41  }
42  if (context.percent !== undefined && context.percent >= CONTEXT_THRESHOLD) {
43    return `コンテキストが ${context.percent}% に到達`
44  }
45
46  return null
47}
48
49export const storeKey = (repoRoot: string): string => `handoff:${repoRoot}`
50
51export const commitMessage = (reason: string): string =>
52  `chore: handoff checkpoint before token limit\n\n${reason}. Work in progress, see ${HANDOFF_FILE}.`
53
54export function handoffMarkdown(handoff: Handoff): string {
55  return [
56    '# 作業引き継ぎ (context-handoff)',
57    '',
58    `- リポジトリ: ${handoff.repoRoot}`,
59    `- ブランチ: ${handoff.branch}`,
60    `- 理由: ${handoff.reason}`,
61    `- 記録日時: ${handoff.createdAt}`,
62    '',
63    handoff.summary,
64    '',
65  ].join('\n')
66}
67
68export const resumeQuestion = (handoff: Handoff): string =>
69  `このリポジトリ (${handoff.repoRoot}) でこの作業をやっていましたがトークン切れで作業を一時中断しました、続行しますか`
70
71export function resumePrompt(handoff: Handoff): string {
72  const commitLine =
73    handoff.commit === '' ? 'チェックポイントのコミットはありません。' : `チェックポイントのコミット: ${handoff.commit}`
74
75  return [
76    '前のセッションがトークン制限で中断した作業の続きをお願いします。',
77    `ブランチ ${handoff.branch}。${commitLine}`,
78    `引き継ぎメモ (${HANDOFF_FILE} と同じ内容):`,
79    '',
80    handoff.summary,
81    '',
82    `まず git log と git status で状態を確認してから「次の一手」から再開してください。作業が終わったら ${HANDOFF_FILE} を削除してください。`,
83  ].join('\n')
84}
85
86export const wrapUpNote = (handoff: Handoff): string =>
87  [
88    `[context-handoff] ${handoff.reason}。作業内容を ${HANDOFF_FILE} に記録し、チェックポイントをコミットしました (${handoff.commit || 'コミットなし'})。`,
89    '新しい大きな作業は始めず、今のステップを区切りのよいところで終え、ユーザーに中断を報告してください。',
90  ].join('\n')
91

1export type Handoff = {
2  repoRoot: string
3  branch: string
4  commit: string
5  reason: string
6  summary: string
7  createdAt: string
8}
9
10declare module 'claude-code' {
11  interface PluginState {
12    'context-handoff': {
13      pending: Handoff | null
14      hasSavedThisSession: boolean
15    }
16  }
17}
18