kasaterm-bridge

1import type { EngineInterface, Register } from 'claude-code'
2
3import {
4  activityLabel,
5  askKey,
6  clip,
7  launchedTask,
8  mergeTasks,
9  permissionPreview,
10  running,
11  stopTasks,
12  taskNotification,
13  usageEvent,
14} from './bridge'
15import type { BridgeEvent, Task } from './bridge'
16
17const MOD_VERSION = '0.1.0'
18const QUEUE_CAP = 500
19// 긴 폴링 한 번의 한도(앱이 이보다 오래 쥐지 않는다). 승인 요청은 앱의 만료(10분)를 넘겨 다시 열지 않는다.
20const POLL_WAIT_MS = 20000
21const PERMISSION_ROUNDS = 26
22const SAY_CAP = 2000
23const RESULT_CAP = 600
24// 보낸 쪽지가 버려졌다는 한 줄 — 칸을 보는 사람이 놓치지 않을 만큼 둔다. 포인터를 올리면 더 머문다.
25const NOTICE_TOAST_MS = 20000
26
27type Ask = { id: string; tool: string; agent?: string }
28
29// 모듈 변수는 다시 실릴 때 처음으로 돌아간다 — 정본은 앱이 쥐고, 여기는 보낼 줄과 지금 일의 짐작만 쥔다.
30const io = {
31  base: '',
32  surface: '',
33  session: '',
34  pid: 0,
35  queue: [] as BridgeEvent[],
36  flushing: false,
37  turnOpen: false,
38  asks: new Map<string, Ask>(),
39  permissions: new Set<string>(),
40  question: '',
41  others: [] as Task[],
42  lastTasks: '',
43  listening: false,
44  // 다음 턴을 연 프롬프트가 사람·다른 세션의 말이 아니면(백그라운드 끝남 알림) 활동에 「시킴」으로 안 싣는다.
45  quiet: false,
46}
47
48function send($: EngineInterface, event: Omit<BridgeEvent, 'at'>) {
49  if (!io.base) return
50  if (io.queue.length >= QUEUE_CAP) io.queue.shift()
51  io.queue.push({ ...event, at: Date.now() } as BridgeEvent)
52  void flush($)
53}
54
55// 한 번에 하나만 보낸다 — 차례가 곧 뜻이다(턴 시작 → 도구 → 턴 끝).
56async function flush($: EngineInterface) {
57  if (io.flushing) return
58  io.flushing = true
59  try {
60    while (io.queue.length > 0 && io.base) {
61      const events = io.queue.splice(0, io.queue.length)
62      try {
63        await post($, '/claude-mod/event', { v: 1, surface: io.surface, session: io.session, events })
64      } catch {
65        // 앱이 없거나 재시작 중이다 — 보낸 줄은 버린다. 다시 뜬 앱은 다음 인사로 이 칸을 다시 안다.
66      }
67    }
68  } finally {
69    io.flushing = false
70  }
71}
72
73async function post($: EngineInterface, path: string, body: unknown) {
74  return $.http.fetch(`${io.base}${path}`, {
75    method: 'POST',
76    headers: { 'content-type': 'application/json' },
77    body: JSON.stringify(body),
78  })
79}
80
81// claude 프로세스의 pid — 앱은 이것이 그 칸에 지금 도는 claude 와 같을 때만 이 mod 를 정본으로 친다.
82async function claudePid($: EngineInterface): Promise<number> {
83  try {
84    const run = await $.process.run(['/bin/sh', '-c', 'echo $PPID'], { timeoutMs: 5000 })
85    const pid = Number(run.stdout.trim())
86    return Number.isInteger(pid) && pid > 1 ? pid : 0
87  } catch {
88    return 0
89  }
90}
91
92async function hello($: EngineInterface) {
93  if (!io.base) return
94  io.session = await $.session.id()
95  const version = await $.session.version()
96  send($, { kind: 'hello', mod: MOD_VERSION, claude: version.version, pid: io.pid, cwd: await $.session.cwd() })
97  await measure($)
98  await reportTasks($)
99}
100
101async function boot($: EngineInterface) {
102  const port = await $.env.get('KASASPACE_MCP_PORT')
103  const surface = await $.env.get('KASATERM_PANE_ID')
104  if (!port || !surface || !/^\d+$/.test(port)) return
105  io.base = `http://127.0.0.1:${port}`
106  io.surface = surface
107  // 이 claude 가 낳는 settings 훅·명령이 「mod 가 알린다」를 안다 — 같은 일을 하던 옛 훅이 쉰다.
108  await $.env.set('KASATERM_MOD_BRIDGE', '1')
109  io.pid = await claudePid($)
110  await hello($)
111  $.clock.every(1000, () => void listen($))
112}
113
114async function measure($: EngineInterface) {
115  const usage = await $.session.usage()
116  send($, usageEvent(usage, Date.now()))
117}
118
119async function reportTasks($: EngineInterface) {
120  const agents = await $.agent.list()
121  const tasks = running(mergeTasks(agents, io.others))
122  const key = JSON.stringify(tasks)
123  if (key === io.lastTasks) return
124  io.lastTasks = key
125  send($, { kind: 'background', tasks })
126}
127
128// 보낸 칸 알림 — 앱이 맡긴 한 줄(보낸 쪽지가 버려짐)을 토스트로만 띄운다. 프롬프트로 넣으면 이 칸의 턴을
129// 깨워 일을 끊는다 — 토스트는 대화에도 모델에도 안 들어간다. 그래서 일하는 중에도 받는다.
130async function listen($: EngineInterface) {
131  if (io.listening || !io.base) return
132  io.listening = true
133  try {
134    const query = `surface=${encodeURIComponent(io.surface)}&wait_ms=${POLL_WAIT_MS}`
135    const res = await $.http.fetch(`${io.base}/claude-mod/notices?${query}`)
136    if (!res.ok) return
137    const { notices } = JSON.parse(res.text) as { notices?: string[] }
138    for (const text of notices ?? []) $.ui.toast(text, { timeoutMs: NOTICE_TOAST_MS })
139  } catch {
140    // 앱이 없으면 다음 박자에 다시 연다.
141  } finally {
142    io.listening = false
143  }
144}
145
146async function askRemote(
147  $: EngineInterface,
148  request: Record<string, unknown>,
149): Promise<{ decision: 'allow' | 'deny'; message: string } | null> {
150  for (let round = 0; round < PERMISSION_ROUNDS; round++) {
151    const res = await post($, '/claude-mod/permission', { v: 1, surface: io.surface, session: io.session, request })
152    if (!res.ok) return null
153    const answer = JSON.parse(res.text) as { decision?: string; message?: string; pending?: boolean }
154    if (answer.decision === 'allow' || answer.decision === 'deny') {
155      return { decision: answer.decision, message: answer.message ?? '' }
156    }
157    if (!answer.pending) return null
158  }
159  return null
160}
161
162export const register: Register = on => {
163  on('session.start', async ($, e, next) => {
164    const result = await next(e)
165    await boot($)
166    return result
167  })
168
169  // /clear·/resume 는 같은 프로세스에서 세션 id 만 바꾸고 session.start 를 다시 안 낸다.
170  on('session.end', async ($, e, next) => {
171    const result = await next(e)
172    if (e.reason === 'clear' || e.reason === 'resume') {
173      io.turnOpen = false
174      io.permissions.clear()
175      io.question = ''
176      io.others = []
177      $.clock.after(300, () => void hello($))
178    } else {
179      send($, { kind: 'bye', reason: e.reason })
180      await flush($)
181    }
182    return result
183  })
184
185  on('turn.start', async ($, e, next) => {
186    io.turnOpen = true
187    send($, { kind: 'turn', phase: 'start', turn: e.turnId, text: io.quiet ? '' : clip(e.text, SAY_CAP) })
188    io.quiet = false
189    return next(e)
190  })
191
192  on('turn.complete', async ($, e, next) => {
193    const result = await next(e)
194    if (e.agentId === undefined) {
195      io.turnOpen = false
196      io.question = ''
197      send($, { kind: 'turn', phase: 'end', turn: e.turnId, reason: e.reason, answer: clip(result.text, SAY_CAP) })
198    }
199    void reportTasks($)
200    return result
201  })
202
203  on('session.compact', async ($, e, next) => {
204    if (e.agentId !== undefined || e.trigger === 'precompute') return next(e)
205    send($, { kind: 'compact', phase: 'start', trigger: e.trigger })
206    try {
207      return await next(e)
208    } finally {
209      send($, { kind: 'compact', phase: 'end', trigger: e.trigger })
210    }
211  })
212
213  // 압축의 끝을 한 번 더 — 다시 실린 mod 는 그 앞 압축의 finally 를 잃는다.
214  on('classic.PostCompact', async ($, e, next) => {
215    send($, { kind: 'compact', phase: 'end', trigger: e.trigger })
216    return next(e)
217  })
218
219  on('session.measure', async ($, e, next) => {
220    send($, usageEvent(e, Date.now()))
221    return next(e)
222  })
223
224  on('tool.check', async ($, e, next) => {
225    const verdict = await next(e)
226    if (verdict.decision === 'ask' && e.tool_use_id) {
227      io.asks.set(askKey(e.tool, e.input), { id: e.tool_use_id, tool: e.tool })
228    }
229    return verdict
230  })
231
232  // 엔진의 승인 창은 이 훅과 함께 뜬다 — 여기서 기다리는 동안에도 자리의 사람은 그 창으로 답한다. 원격 결정이
233  // 먼저 오면 그것으로, 아니면 엔진 몫으로 돌려준다(사람이 먼저 답하면 엔진이 이 훅의 늦은 답을 버린다).
234  on('classic.PermissionRequest', async ($, e, next) => {
235    const below = await next(e)
236    if (below.decision || below.block || !io.base) return below
237    const key = askKey(e.tool_name, e.tool_input)
238    const ask = io.asks.get(key)
239    io.asks.delete(key)
240    const id = ask?.id ?? `perm-${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`
241    io.permissions.add(id)
242    const request = {
243      id,
244      tool: e.tool_name,
245      input: e.tool_input,
246      preview: permissionPreview(e.tool_name, e.tool_input),
247      cwd: e.cwd,
248      agent: ask?.agent ?? null,
249      suggestions: e.permission_suggestions ?? [],
250      created_at_ms: Date.now(),
251    }
252    try {
253      const remote = await askRemote($, request)
254      if (remote?.decision === 'allow') return { ...below, decision: { behavior: 'allow' } }
255      if (remote?.decision === 'deny') {
256        return { ...below, decision: { behavior: 'deny', message: remote.message || '원격에서 거절했어요' } }
257      }
258    } catch {
259      // 앱에 못 닿으면 엔진 창 혼자 묻는다.
260    }
261    return below
262  })
263
264  on('tool.call', async ($, e, next) => {
265    const id = e.tool_use_id ?? ''
266    const main = e.agentId === undefined
267    send($, { kind: 'tool', phase: 'start', id, tool: e.tool, label: activityLabel(e.tool, e), agent: e.agentId ?? null })
268    if (main && e.tool === 'AskUserQuestion') {
269      io.question = id
270      send($, { kind: 'question', phase: 'start', id })
271    }
272    let failed = true
273    let text = ''
274    try {
275      const result = await next(e)
276      failed = 'deny' in result && result.deny !== undefined ? true : result.isError === true
277      text = clip(result.deny ?? result.text ?? '', RESULT_CAP)
278      if (!failed) {
279        const task = launchedTask(e.tool, e, result.result)
280        if (task) {
281          io.others = [...io.others.filter(t => t.id !== task.id), task]
282          void reportTasks($)
283        }
284      }
285      // Task·KillShell 은 다른 판의 이름이다 — 이 판의 도구 표에 없어 글자로 견준다.
286      if (['Agent', 'Task', 'TaskStop', 'KillShell'].includes(String(e.tool))) void reportTasks($)
287      return result
288    } finally {
289      if (io.permissions.delete(id)) {
290        send($, { kind: 'permission', phase: 'resolved', id, outcome: failed ? 'denied' : 'ran' })
291      }
292      if (main && io.question === id) {
293        io.question = ''
294        send($, { kind: 'question', phase: 'end', id })
295      }
296      send($, { kind: 'tool', phase: 'end', id, tool: e.tool, error: failed, text, agent: e.agentId ?? null })
297    }
298  })
299
300  // Enter 순간이다 — turn.start 는 UserPromptSubmit 훅이 다 돈 뒤(실측 2초 남짓)라, 쉬던 칸은 여기서 먼저 「일함」을
301  // 알린다. 훅이 프롬프트를 버리면 되돌린다. 백그라운드 끝남 알림이면 그 작업을 목록에서 내린다.
302  on('prompt.submit', async ($, e, next) => {
303    if (e.origin.kind === 'task-notification') {
304      const done = taskNotification(e.text)
305      if (done) {
306        io.others = io.others.filter(t => t.id !== done.id)
307        void reportTasks($)
308      }
309    }
310    const early = e.turnId === undefined && !io.turnOpen
311    if (early) {
312      io.turnOpen = true
313      io.quiet = e.origin.kind === 'task-notification'
314      send($, { kind: 'turn', phase: 'start', turn: '', text: io.quiet ? '' : clip(e.text, SAY_CAP) })
315    }
316    const result = await next(e)
317    if (early && 'drop' in result && result.drop !== undefined) {
318      io.turnOpen = false
319      send($, { kind: 'turn', phase: 'end', turn: '', reason: 'dropped' })
320    }
321    return result
322  })
323
324  // 턴이 멈출 때 엔진이 주는 지금 도는 작업 목록이 정본이다 — 놓친 끝남을 여기서 바로잡는다.
325  on('classic.Stop', async ($, e, next) => {
326    io.others = stopTasks(e.background_tasks).filter(t => t.type !== 'subagent')
327    void reportTasks($)
328    return next(e)
329  })
330
331  // 대화 행이 쌓였다 — 대화 보기(폰·데스크톱)가 기록 파일을 다시 읽을 때다. 내용은 파일이 정본이라 싣지 않는다.
332  on('session.append', async ($, e, next) => {
333    const stored = await next(e)
334    if (e.agentId === undefined && io.base && e.message.type !== 'attachment') {
335      send($, { kind: 'row', uuid: stored.uuid ?? e.uuid, door: e.door })
336    }
337    return stored
338  })
339}
340

1// 엔진 이벤트를 kasaterm 에 보낼 모양으로 바꾸는 순수 셈. `$` 를 모르므로 시험이 그대로 부른다.
2// 계약은 레포의 docs/claude-mod-bridge.md.
3
4export type Task = { id: string; type: string; status: string; label: string }
5
6export type BridgeEvent = { kind: string; at: number; [field: string]: unknown }
7
8const PREVIEW_CAP = 400
9const LABEL_CAP = 160
10
11function one(text: string, cap: number): string {
12  const flat = text.replace(/\s+/g, ' ').trim()
13  return flat.length > cap ? `${flat.slice(0, cap - 1)}…` : flat
14}
15
16function field(input: unknown, key: string): string {
17  if (typeof input !== 'object' || input === null) return ''
18  const value = (input as Record<string, unknown>)[key]
19  return typeof value === 'string' ? value : ''
20}
21
22// 보드 활동에 싣는 글 — 줄바꿈은 살리고 길이만 줄인다.
23export function clip(text: string, cap: number): string {
24  return text.length > cap ? `${text.slice(0, cap - 1)}…` : text
25}
26
27// 승인 창이 무엇을 묻는지 한 줄로 — 원격 화면의 제목줄. 원문은 따로 실린다.
28export function permissionPreview(tool: string, input: unknown): string {
29  const pick = ['command', 'file_path', 'notebook_path', 'url', 'path', 'pattern', 'prompt', 'description']
30    .map(key => field(input, key))
31    .find(text => text !== '')
32  return one(pick ?? (input === undefined ? '' : JSON.stringify(input)) ?? '', PREVIEW_CAP) || tool
33}
34
35// 보드 활동 한 줄 — 무엇을 했나. 옛 기록 판독(`activity_from_tail`)이 쓰던 모양과 같은 정도의 짧은 말.
36export function activityLabel(tool: string, input: unknown): string {
37  const text = field(input, 'description') || permissionPreview(tool, input)
38  return one(text === tool ? '' : text, LABEL_CAP)
39}
40
41// tool.check 가 본 호출과 PermissionRequest 가 묻는 호출을 잇는 열쇠 — 후자는 tool_use_id 를 안 싣는다.
42export function askKey(tool: string, input: unknown): string {
43  return `${tool}\u0000${JSON.stringify(input ?? null)}`
44}
45
46// 백그라운드 알림 줄에서 끝난 작업의 id 와 상태를 읽는다(엔진이 쓰는 봉투 그대로).
47export function taskNotification(text: string): { id: string; status: string } | null {
48  const id = /<task-id>([^<]+)<\/task-id>/.exec(text)?.[1]?.trim()
49  if (!id) return null
50  const status = /<status>([^<]+)<\/status>/.exec(text)?.[1]?.trim() ?? 'completed'
51  return { id, status }
52}
53
54// 도구 결과가 백그라운드로 넘긴 작업. Bash 의 run_in_background·Ctrl+B 와 Monitor.
55export function launchedTask(tool: string, input: unknown, result: unknown): Task | null {
56  if (typeof result !== 'object' || result === null) return null
57  const r = result as Record<string, unknown>
58  const id = typeof r.backgroundTaskId === 'string' ? r.backgroundTaskId : typeof r.taskId === 'string' ? r.taskId : ''
59  if (!id) return null
60  const type = tool === 'Bash' ? 'shell' : tool === 'Monitor' ? 'monitor' : tool.toLowerCase()
61  return { id, type, status: 'running', label: activityLabel(tool, input) }
62}
63
64type StopTask = { id: string; type: string; status: string; description?: string; command?: string }
65
66// classic.Stop 이 주는 지금 도는 백그라운드 목록 — 그 순간의 정본.
67export function stopTasks(tasks: readonly StopTask[] | undefined): Task[] {
68  return (tasks ?? []).map(t => ({
69    id: t.id,
70    type: t.type,
71    status: t.status,
72    label: one(t.description || t.command || t.type, LABEL_CAP),
73  }))
74}
75
76type AgentRow = { id: string; description: string; type: string; status: string }
77
78// 서브에이전트(`$.agent.list()`)와 그 밖의 작업을 하나로 — 서브에이전트는 엔진 목록이 정본이다.
79export function mergeTasks(agents: readonly AgentRow[], others: readonly Task[]): Task[] {
80  const merged: Task[] = agents
81    .filter(a => a.type !== 'teammate')
82    .map(a => ({ id: a.id, type: 'subagent', status: a.status, label: one(a.description || a.type, LABEL_CAP) }))
83  for (const task of others) {
84    if (task.type !== 'subagent' && !merged.some(t => t.id === task.id)) merged.push(task)
85  }
86  return merged
87}
88
89export function running(tasks: readonly Task[]): Task[] {
90  return tasks.filter(t => t.status === 'running' || t.status === 'pending')
91}
92
93type Measure = {
94  context: { tokens?: number; window: number; percent?: number }
95  rateLimits: readonly { kind: string; percentUsed: number; resetsAt?: string }[]
96  cost?: { usd: number }
97}
98
99export function usageEvent(m: Measure, at: number): BridgeEvent {
100  return {
101    kind: 'usage',
102    at,
103    context: { tokens: m.context.tokens ?? null, window: m.context.window, percent: m.context.percent ?? null },
104    limits: m.rateLimits.map(l => ({ kind: l.kind, percent: l.percentUsed, resets_at: l.resetsAt ?? null })),
105    cost_usd: m.cost?.usd ?? null,
106  }
107}
108