prompt-nav

1import type { EngineInterface, Register } from 'claude-code'
2
3import { append, freshRequest, metrics, observe, parseCommand, parseItems, promptLine, target } from './nav'
4import type { Item, Kind, Model, Op, Seen } from './nav'
5
6// 턴을 여는 줄은 누가 보냈든 프롬프트다(사람·tell·다른 세션·예약). 이것들만 아니다 — 배경 작업
7// 알림, 다른 세션의 SendMessage 전달, 관찰자 보고, UI 동작의 뒤잇기. bin/transcript-items.py 와 같은 표.
8const NOT_PROMPT = new Set(['task-notification', 'peer-send-message', 'observer', 'observer-activity', 'auto-continuation'])
9// 이동 명령 자신은 턴이 아니다 — 눈금이 되면 「앞 프롬프트」가 먼저 그 줄로 간다.
10const NAV_COMMAND = '/prompt-nav'
11
12const model: Model = { items: [], heights: new Map(), onScreen: new Map(), notPrompt: new Set(), cols: 80, top: null }
13const index = new Map<string, number>()
14const io = {
15  state: '',
16  request: '',
17  session: '',
18  done: 0,
19  seq: 0,
20  last: '',
21  pending: false,
22  armed: null as (Op & { seq: number }) | null,
23  armedAt: 0,
24  loaded: false,
25  fullscreen: false,
26  agentView: false,
27  ask: null as (Op & { seq: number; at: number }) | null,
28}
29
30// 세션이 바뀌면(/clear·/resume) 줄 차례도 잰 높이도 그 세션 것이 아니다.
31function reset() {
32  io.loaded = false
33  model.items = []
34  index.clear()
35  model.heights.clear()
36  model.onScreen.clear()
37  model.notPrompt.clear()
38  model.top = null
39}
40
41function replace(items: Item[]) {
42  model.items = items
43  index.clear()
44  items.forEach((item, i) => index.set(item.id, i))
45  io.loaded = true
46}
47
48// 기록 도우미가 모르는 줄은 그 뒤에 새로 생긴 줄이다(이번 턴의 질문·답).
49function remember(id: string, k: Kind, text: string) {
50  if (!io.loaded || io.agentView || index.has(id)) return
51  const lines = text.split('\n')
52  append(model, index, {
53    id,
54    k,
55    l: lines.length,
56    c: lines.reduce((n, line) => n + line.length, 0),
57    t: k === 'u' ? promptLine(text) : '',
58  })
59}
60
61function see(
62  $: EngineInterface,
63  id: string,
64  k: Kind,
65  text: string,
66  on: Seen | null | undefined,
67  viewport: { columns: number; isFullscreen?: boolean } | undefined,
68) {
69  if (io.agentView) return
70  if (viewport) {
71    if (viewport.columns !== model.cols) {
72      // 폭이 바뀌면 잰 높이가 모두 틀린다 — 다시 보일 때 새로 잰다.
73      model.cols = viewport.columns
74      model.heights.clear()
75    }
76    if (viewport.isFullscreen !== undefined) io.fullscreen = viewport.isFullscreen
77  }
78  remember(id, k, text)
79  if (on !== undefined) observe(model, id, on, other => index.get(other))
80  schedule($)
81}
82
83function schedule($: EngineInterface) {
84  if (io.pending || !io.state) return
85  io.pending = true
86  $.clock.after(200, () => {
87    io.pending = false
88    void flush($)
89  })
90}
91
92async function flush($: EngineInterface) {
93  const m = metrics(model)
94  const body = {
95    session: io.session,
96    armed: io.armed?.seq ?? 0,
97    done: io.done,
98    fullscreen: io.fullscreen,
99    cols: model.cols,
100    total: m.total,
101    top: m.top,
102    current: m.current,
103    prompts: m.prompts.map(p => [p.row, p.text]),
104    ask: io.ask,
105  }
106  const key = JSON.stringify(body)
107  if (key === io.last) return
108  io.last = key
109  io.seq += 1
110  await $.fs.write(io.state, JSON.stringify({ v: 1, seq: io.seq, at: await $.clock.now(), ...body }))
111}
112
113// 점프하면 화면을 떠난 줄은 다시 보고되지 않으므로 지금까지의 보고를 비우고 새 보고로만 맨
114// 윗줄을 정한다. 스크롤이 끝날 때까지 보고가 하나도 없으면(이미 그 자리) 목표를 맨 윗줄로 둔다.
115async function go($: EngineInterface, op: Op): Promise<string | undefined> {
116  if (!io.fullscreen) return ask($, op)
117  const to = target(model, op)
118  if (!to) return 'no prompt there'
119  const before = { onScreen: new Map(model.onScreen), top: model.top }
120  model.onScreen.clear()
121  model.top = null
122  const result = await $.ui.scroll({ to: { requestId: to.id }, block: to.block })
123  if (result.deny) {
124    model.onScreen = before.onScreen
125    model.top = before.top
126  } else if (model.top === null && to.block === 'start') {
127    model.top = { id: to.id, first: 0 }
128  }
129  return result.deny
130}
131
132// classic 렌더러는 대화가 터미널 스크롤백에 쌓여 엔진이 그 줄을 스크롤하지 못한다. kasaterm 칸이면
133// 상태 파일의 ask 로 맡기고, kasaterm 이 자기 스크롤백의 프롬프트 줄로 옮긴다.
134async function ask($: EngineInterface, op: Op): Promise<string | undefined> {
135  if (!io.state) return 'the classic renderer keeps the transcript in terminal scrollback'
136  io.ask = { ...op, seq: (io.ask?.seq ?? 0) + 1, at: await $.clock.now() }
137  await flush($)
138  return undefined
139}
140
141async function readRequest($: EngineInterface): Promise<(Op & { seq: number }) | null> {
142  if (!io.request) return null
143  try {
144    return freshRequest(await $.fs.read(io.request), io.done, await $.clock.now())
145  } catch {
146    return null
147  }
148}
149
150// 대화 줄 스크롤은 누름 처리에서 파일 읽기 같은 기다림보다 먼저 와야 사람의 입력으로 인정된다
151// (읽고 나서 부르면, 다른 누름이 읽던 것을 기다려도 not person-initiated). 그래서 두 번 누른다:
152// kasaterm 이 요청 파일을 쓰고 장전 화음(ctrl+x b)을 보내면 여기서 읽어 쥐고 상태 파일의 armed 로
153// 알린다. 그것을 본 kasaterm 이 앞 단추 단축키를 보내면 쥔 요청으로 곧장 스크롤한다.
154async function arm($: EngineInterface) {
155  const request = await readRequest($)
156  if (!request) return
157  io.armed = request
158  io.armedAt = Date.now()
159  await flush($)
160}
161
162async function press($: EngineInterface, fallback: Op) {
163  // 장전하고 2초 안에 안 쏜 요청은 버린다 — 사람이 나중에 같은 단축키를 눌렀을 때 실리면 안 된다.
164  const request = io.armed && Date.now() - io.armedAt < 2000 ? io.armed : null
165  io.armed = null
166  await go($, request ?? fallback)
167  if (!request) return schedule($)
168  // kasaterm 은 done 을 보고 다음 요청(끄는 중의 다음 자리)을 보낸다 — 묶어 쓰기를 기다리지 않는다.
169  io.done = request.seq
170  await flush($)
171}
172
173async function load($: EngineInterface, path: string) {
174  const script = `${$.plugin.root}/bin/transcript-items.py`
175  for (const python of ['python3', 'python']) {
176    try {
177      const run = await $.process.run([python, script, path], { timeoutMs: 20000 })
178      if (run.exitCode === 0 && !run.isStdoutTruncated) {
179        replace(parseItems(run.stdout))
180        schedule($)
181        return
182      }
183    } catch {
184      // 다음 이름으로 다시 찾는다.
185    }
186  }
187  replace([])
188  schedule($)
189}
190
191async function boot($: EngineInterface) {
192  const dir = await $.env.get('KASATERM_PROMPT_NAV_DIR')
193  const pane = await $.env.get('KASATERM_PANE_ID')
194  if (dir && pane) {
195    io.state = `${dir}/${pane}.json`
196    io.request = `${dir}/${pane}.req.json`
197  }
198  io.session = await $.session.id()
199  await $.command.register({
200    name: 'prompt-nav',
201    description: '내 프롬프트로 이동 (prev·next·first·last·번호)',
202    argumentHint: '[prev|next|first|last|N]',
203    immediate: true,
204  })
205}
206
207export const register: Register = on => {
208  on('session.start', async ($, e, next) => {
209    const result = await next(e)
210    await boot($)
211    return result
212  })
213
214  on('classic.SessionStart', async ($, e, next) => {
215    const result = await next(e)
216    io.session = e.session_id
217    // 압축 뒤에도 화면은 지난 줄을 그대로 둔다(2026-10-06 실측). 기록은 압축 경계에서 끊기니 다시
218    // 읽으면 화면에 있는 줄을 잃는다 — 가진 차례에 새 줄(경계·요약)을 그려지는 대로 붙인다.
219    if (e.source === 'compact') return result
220    reset()
221    void load($, e.transcript_path)
222    return result
223  })
224
225  on('command.run', { command: 'prompt-nav' }, async ($, e) => {
226    io.fullscreen = e.presentation.isFullscreen
227    const op = parseCommand(e.args)
228    const deny = op ? await go($, op) : 'prev · next · first · last · 번호 중 하나'
229    return deny ? { text: `prompt-nav: ${deny}` } : {}
230  })
231
232  on('ui.render', { component: 'UserMessage' }, ($, e, next) => {
233    const prompt = !NOT_PROMPT.has(e.props.origin.kind) && !e.props.text.startsWith(NAV_COMMAND)
234    if (!prompt) model.notPrompt.add(e.requestId)
235    see($, e.requestId, prompt ? 'u' : 'n', e.props.text, e.props.onScreen, e.viewport)
236    return next(e)
237  })
238
239  on('ui.render', { component: 'AssistantMessage' }, ($, e, next) => {
240    see($, e.requestId, 'a', e.props.text, e.props.onScreen, e.viewport)
241    return next(e)
242  })
243
244  on('ui.render', { component: 'ToolUse' }, ($, e, next) => {
245    see($, e.requestId, 't', '', e.props.onScreen, e.viewport)
246    return next(e)
247  })
248
249  // 단추는 보이지 않는다. 엔진 단축키 동작(diff 창의 파일 목록 위·아래, diff 기준 바꾸기)에 걸어
250  // 그 창이 없는 평소 화면에서 Ctrl·Option+↑↓ 와 ctrl+x b 가 누른다 — 사람의 입력이라 대화 줄을
251  // 스크롤할 수 있다.
252  on('ui.render', { component: 'AbovePrompt' }, async ($, e, next) => {
253    io.agentView = e.props.view.agentId !== undefined
254    if (e.viewport?.isFullscreen !== undefined) io.fullscreen = e.viewport.isFullscreen
255    const below = await next(e)
256    if (e.surface !== 'terminal' || e.props.hasSurvey) return below
257    const { Box, Button } = $.ui.resolve(e)
258    return (
259      <Box flexDirection="column">
260        {below}
261        <Box display="none">
262          <Button key="prompt-nav-prev" label="prev" action="app:diffFileListUp" onPress={() => void press($, { op: 'prev' })} />
263          <Button key="prompt-nav-next" label="next" action="app:diffFileListDown" onPress={() => void press($, { op: 'next' })} />
264          <Button key="prompt-nav-arm" label="arm" action="app:cycleDiffBase" onPress={() => void arm($)} />
265        </Box>
266      </Box>
267    )
268  })
269}
270

1// 대화 줄의 차례·높이에서 스크롤 위치와 프롬프트 자리를 셈한다. `$` 를 모르는 순수 셈이라
2// 시험이 그대로 부른다.
3
4// u=프롬프트, n=그려지되 프롬프트가 아닌 사람 줄(배경 작업 알림·명령 출력), a=답 글, t=도구 줄, s=압축 요약.
5export type Kind = 'u' | 'n' | 'a' | 't' | 's'
6
7export type Item = { id: string; k: Kind; l: number; c: number; t: string }
8
9export type Seen = { first: number; last: number; of: number }
10
11export type Model = {
12  items: Item[]
13  heights: Map<string, number>
14  onScreen: Map<string, Seen>
15  notPrompt: Set<string>
16  cols: number
17  // 화면 맨 윗줄이 걸린 줄과 그 줄 안의 몇째 행인가. 엔진은 스크롤 때 **가장자리** 줄만 다시
18  // 알려 주므로, 큰 점프로 화면을 벗어난 줄은 낡은 보고가 남는다 — 그것들 중 맨 위를 맨 윗줄로
19  // 치면 틀린다. 그래서 확실한 신호(위가 잘린 줄, 더 위에서 보인 줄, 내가 보낸 스크롤)로만 옮긴다.
20  top: { id: string; first: number } | null
21}
22
23export type Prompt = { id: string; row: number; text: string }
24
25export type Metrics = {
26  total: number
27  top: number | null
28  current: number
29  prompts: Prompt[]
30}
31
32export type Op =
33  | { op: 'prev' }
34  | { op: 'next' }
35  | { op: 'first' }
36  | { op: 'last' }
37  | { op: 'prompt'; index: number }
38  | { op: 'row'; row: number }
39  | { op: 'bottom' }
40
41export type Target = { id: string; block: 'start' | 'end' }
42
43// 그린 적 없는 줄의 높이 짐작. 엔진이 줄마다 위에 빈 줄 하나를 두므로 +1 이다.
44export function estimate(item: Item, cols: number): number {
45  if (item.k === 't' || item.k === 's') return 3
46  if (item.k === 'n') return 2
47  const width = Math.max(20, cols - 4)
48  return Math.max(item.l, Math.ceil(item.c / width)) + 1
49}
50
51function positions(m: Model): { pos: number[]; total: number } {
52  const pos: number[] = []
53  let total = 0
54  for (const item of m.items) {
55    pos.push(total)
56    total += m.heights.get(item.id) ?? estimate(item, m.cols)
57  }
58  return { pos, total }
59}
60
61function isPrompt(m: Model, item: Item): boolean {
62  return item.k === 'u' && !m.notPrompt.has(item.id)
63}
64
65// 보고 하나를 받아 맨 윗줄을 옮긴다. 위가 잘렸으면(first > 0) 그 줄이 곧 맨 윗줄이고, 온전히
66// 보이는 줄이 지금 맨 윗줄보다 위에 있으면 맨 윗줄이 거기까지 올라온 것이다. 맨 윗줄이던 줄이
67// 화면을 벗어나면 남은 보고 가운데 맨 위로 짐작한다.
68export function observe(m: Model, id: string, on: Seen | null, index: (id: string) => number | undefined) {
69  if (on) {
70    m.onScreen.set(id, on)
71    m.heights.set(id, on.of)
72    const at = index(id)
73    const was = m.top ? index(m.top.id) : undefined
74    if (on.first > 0 || was === undefined || (at !== undefined && at < was)) m.top = { id, first: on.first }
75    else if (m.top?.id === id) m.top = { id, first: on.first }
76    return
77  }
78  m.onScreen.delete(id)
79  if (m.top?.id !== id) return
80  m.top = null
81  let best: number | undefined
82  for (const [other, seen] of m.onScreen) {
83    const at = index(other)
84    if (at !== undefined && (best === undefined || at < best)) {
85      best = at
86      m.top = { id: other, first: seen.first }
87    }
88  }
89}
90
91// plugin·다른 세션이 보낸 줄은 엔진의 머리말을 달고 그려진다. 눈금 글은 그 뒤 본문의 첫 줄이다 —
92// bin/transcript-items.py 의 FRAMING 과 같은 규칙.
93const FRAMING = [' plugin sent a message:', 'Another Claude session sent a message:']
94
95export function promptLine(text: string): string {
96  const lines = text.trim().split('\n')
97  const head = lines[0] ?? ''
98  const body = lines.length > 1 && FRAMING.some(f => head.endsWith(f)) ? lines.slice(1).join('\n').trim() : text.trim()
99  return (body.split('\n')[0] ?? '').slice(0, 80)
100}
101
102// 기록에 없던 줄(이번 턴의 질문·답)을 그려진 차례로 붙인다. 바로 앞의 같은 글 사람 줄이 새 id 로
103// 다시 그려진 것이면 그 자리를 바꿔 낀다 — /compact 는 친 줄을 압축 뒤 명령 줄로, tell 은 대기 줄을
104// 자리표시 줄·머리말 붙은 실제 줄로 갈아 그린다(2026-10-06 실측).
105export function append(m: Model, index: Map<string, number>, item: Item) {
106  const at = m.items.length - 1
107  const last = m.items[at]
108  if (item.k === 'u' && last?.k === 'u' && last.t === item.t) {
109    index.delete(last.id)
110    m.heights.delete(last.id)
111    m.onScreen.delete(last.id)
112    if (m.top?.id === last.id) m.top = { id: item.id, first: m.top.first }
113    m.items[at] = item
114    index.set(item.id, at)
115    return
116  }
117  index.set(item.id, m.items.length)
118  m.items.push(item)
119}
120
121export function metrics(m: Model): Metrics {
122  const { pos, total } = positions(m)
123  const prompts: Prompt[] = []
124  let topRow: number | null = null
125  m.items.forEach((item, i) => {
126    if (isPrompt(m, item)) prompts.push({ id: item.id, row: pos[i] ?? 0, text: item.t })
127    if (m.top?.id === item.id) topRow = (pos[i] ?? 0) + m.top.first
128  })
129  let current = -1
130  if (topRow !== null) {
131    const top: number = topRow
132    prompts.forEach((p, i) => {
133      if (p.row <= top) current = i
134    })
135  }
136  return { total, top: topRow, current, prompts }
137}
138
139// 「앞 프롬프트」는 지금 턴의 머리가 화면 맨 위에 없으면 그 머리로, 있으면 하나 앞으로 —
140// 터미널의 표식 오가기와 같은 규칙이다.
141export function target(m: Model, op: Op): Target | null {
142  const at = metrics(m)
143  const { prompts } = at
144  const pick = (i: number): Target | null => {
145    const p = prompts[i]
146    return p ? { id: p.id, block: 'start' } : null
147  }
148  switch (op.op) {
149    case 'first':
150      return pick(0)
151    case 'last':
152      return pick(prompts.length - 1)
153    case 'prompt':
154      return pick(op.index)
155    case 'prev': {
156      if (at.top === null) return pick(prompts.length - 1)
157      const cur = prompts[at.current]
158      if (cur && cur.row < at.top) return pick(at.current)
159      return pick(at.current - 1)
160    }
161    // 마지막 프롬프트 다음은 대화 끝이다 — 터미널 스크롤백 쪽(kasaterm)도 같은 키로 맨 아래에 선다.
162    case 'next':
163      return pick(at.current + 1) ?? target(m, { op: 'bottom' })
164    case 'bottom': {
165      const last = m.items[m.items.length - 1]
166      return last ? { id: last.id, block: 'end' } : null
167    }
168    case 'row': {
169      const { pos } = positions(m)
170      let found = -1
171      pos.forEach((start, i) => {
172        if (start <= op.row) found = i
173      })
174      const item = m.items[Math.max(0, found)]
175      return item ? { id: item.id, block: 'start' } : null
176    }
177  }
178}
179
180export function parseItems(stdout: string): Item[] {
181  const raw: unknown = JSON.parse(stdout)
182  if (!Array.isArray(raw)) return []
183  const out: Item[] = []
184  for (const row of raw) {
185    if (!Array.isArray(row)) continue
186    const [id, k, l, c, t] = row as unknown[]
187    if (typeof id !== 'string' || (k !== 'u' && k !== 'n' && k !== 'a' && k !== 't' && k !== 's')) continue
188    out.push({ id, k, l: Number(l) || 1, c: Number(c) || 0, t: typeof t === 'string' ? t : '' })
189  }
190  return out
191}
192
193// kasaterm 이 남긴 요청 — 오래된 것(이미 한 번호, 5초 넘은 것)은 버린다. 사람이 같은 단축키를
194// 직접 눌렀을 때 지난 요청이 다시 실리면 안 된다.
195export function freshRequest(text: string, done: number, now: number): (Op & { seq: number }) | null {
196  let raw: unknown
197  try {
198    raw = JSON.parse(text)
199  } catch {
200    return null
201  }
202  if (typeof raw !== 'object' || raw === null) return null
203  const r = raw as Record<string, unknown>
204  const seq = Number(r.seq)
205  const at = Number(r.at)
206  if (!Number.isFinite(seq) || seq <= done || !Number.isFinite(at) || Math.abs(now - at) > 5000) return null
207  switch (r.op) {
208    case 'prev':
209    case 'next':
210    case 'first':
211    case 'last':
212    case 'bottom':
213      return { op: r.op, seq }
214    case 'prompt':
215      return Number.isInteger(r.index) ? { op: 'prompt', index: Number(r.index), seq } : null
216    case 'row':
217      return Number.isFinite(Number(r.row)) ? { op: 'row', row: Number(r.row), seq } : null
218    default:
219      return null
220  }
221}
222
223export function parseCommand(args: string): Op | null {
224  const a = args.trim().toLowerCase()
225  if (a === '' || a === 'prev' || a === 'up' || a === '이전') return { op: 'prev' }
226  if (a === 'next' || a === 'down' || a === '다음') return { op: 'next' }
227  if (a === 'first' || a === '처음') return { op: 'first' }
228  if (a === 'last' || a === '마지막') return { op: 'last' }
229  if (a === 'bottom' || a === '끝') return { op: 'bottom' }
230  const n = Number(a)
231  return Number.isInteger(n) && n >= 1 ? { op: 'prompt', index: n - 1 } : null
232}
233