kira-glasses-bridge 1.1.0 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "Connects your Mac to Kira, the assistant for Even G2 glasses: Claude Code sessions, files, folders and apps, by voice.",
   "type": "module",
   "bin": {
@@ -17,6 +17,7 @@
     "start": "node src/cli.mjs run"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.3.278",
     "ws": "^8.18.0"
   },
   "keywords": [

package/src/agents/claude.mjs

@@ -0,0 +1,231 @@
+// Claude Code as an agent, through the Agent SDK. Runs in this process on the
+// user's Mac with their own Claude login; files never leave the machine.
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { homedir } from 'node:os'
+import { relative, resolve, sep } from 'node:path'
+import { PERMISSION_OPTIONS, PLAN_OPTIONS, requestId } from './protocol.mjs'
+
+const TEXT_CAP = 4000
+const DIFF_CAP = 6000
+
+const READ_ONLY = new Set(['Read', 'Glob', 'Grep', 'LS', 'WebFetch', 'WebSearch', 'TodoWrite', 'TodoRead', 'NotebookRead', 'Task', 'Skill'])
+const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+const SAFE_SHELL = /^(?:ls|pwd|cat|head|tail|wc|echo|which|type|env|printenv|date|whoami|tree|find|grep|rg|awk|sort|uniq|diff|stat|file|du|df|git (?:status|diff|log|show|branch|rev-parse|remote|ls-files|blame|describe|stash list)|node (?:-v|--version)|npm (?:-v|--version|ls|list|view|test|run (?:test|lint|typecheck|check|build))|pnpm (?:-v|--version|ls|list|test|typecheck|lint|build|run (?:test|lint|typecheck|check|build))|yarn (?:-v|--version|test|lint|typecheck|build)|cargo (?:check|test|build|fmt|clippy)|go (?:test|build|vet|version)|python3? -m pytest|pytest|make (?:test|check|lint|build))(?:\s|$)/
+
+const short = (s, n = 160) => (String(s ?? '').length > n ? `${String(s).slice(0, n)}…` : String(s ?? ''))
+
+function displayPath(p, cwd) {
+  if (!p) return ''
+  const rel = relative(cwd, resolve(cwd, p))
+  if (rel && !rel.startsWith('..') && !rel.startsWith(sep)) return rel
+  const home = relative(homedir(), resolve(cwd, p))
+  return home && !home.startsWith('..') ? `~/${home}` : p
+}
+const inside = (cwd, p) => {
+  const rel = relative(cwd, resolve(cwd, String(p ?? '')))
+  return !!rel && !rel.startsWith('..') && !rel.startsWith(sep)
+}
+
+/** Claude's tool call as a protocol action. */
+export function describeAction(name, input, cwd) {
+  const i = input ?? {}
+  switch (name) {
+    case 'Read':
+      return { type: 'read', label: 'Read', target: displayPath(i.file_path, cwd) }
+    case 'Glob':
+      return { type: 'search', label: 'Find', target: i.pattern }
+    case 'Grep':
+      return { type: 'search', label: 'Search', target: `${i.pattern}${i.path ? ` in ${displayPath(i.path, cwd)}` : ''}` }
+    case 'LS':
+      return { type: 'read', label: 'List', target: displayPath(i.path, cwd) || '.' }
+    case 'Edit':
+      return { type: 'edit', label: 'Edit', target: displayPath(i.file_path, cwd), detail: { edit: { old: short(i.old_string, DIFF_CAP), new: short(i.new_string, DIFF_CAP), all: !!i.replace_all } } }
+    case 'MultiEdit':
+      return { type: 'edit', label: 'Edit', target: displayPath(i.file_path, cwd), detail: { edits: (i.edits ?? []).slice(0, 20).map(e => ({ old: short(e.old_string, 1500), new: short(e.new_string, 1500) })) } }
+    case 'Write':
+      return { type: 'write', label: 'Write', target: displayPath(i.file_path, cwd), detail: { content: short(i.content, DIFF_CAP) } }
+    case 'NotebookEdit':
+      return { type: 'edit', label: 'Edit notebook', target: displayPath(i.notebook_path, cwd) }
+    case 'Bash':
+      return { type: 'run', label: 'Run', target: short(i.command, 400), note: i.description ? short(i.description, 120) : undefined, detail: { command: short(i.command, 2000) } }
+    case 'WebFetch':
+      return { type: 'fetch', label: 'Fetch', target: short(i.url, 200) }
+    case 'WebSearch':
+      return { type: 'fetch', label: 'Search the web', target: short(i.query, 160) }
+    case 'Task':
+      return { type: 'delegate', label: 'Subtask', target: short(i.description ?? i.prompt, 160) }
+    case 'TodoWrite':
+      return { type: 'plan', label: 'Plan', target: `${(i.todos ?? []).length} steps` }
+    case 'ExitPlanMode':
+      return { type: 'plan', label: 'Plan ready', target: 'asks to go ahead' }
+    case 'AskUserQuestion':
+      return { type: 'other', label: 'Question', target: short((i.questions ?? []).map(q => q.question).join(' / '), 200) }
+    default:
+      return { type: 'other', label: name, target: short(JSON.stringify(i), 200) }
+  }
+}
+
+/** Claude's tool call as a request, when a person has to decide. */
+function toRequest(name, input, cwd, suggestions) {
+  const act = describeAction(name, input, cwd)
+  if (name === 'AskUserQuestion') {
+    const questions = (input.questions ?? []).map((q, n) => ({
+      id: `q${n + 1}`,
+      question: q.question,
+      header: q.header,
+      multi: !!q.multiSelect,
+      options: (q.options ?? []).map((o, k) => ({ id: `o${k + 1}`, label: o.label, description: o.description })),
+    }))
+    const first = questions[0]
+    return {
+      id: requestId(),
+      type: 'choice',
+      title: questions.length === 1 ? first.question : `${questions.length} questions`,
+      options: first?.options ?? [],
+      multi: !!first?.multi,
+      allowText: true,
+      questions,
+      action: { tool: name, label: act.label, target: act.target },
+    }
+  }
+  if (name === 'ExitPlanMode') {
+    return { id: requestId(), type: 'plan', title: 'Claude has a plan and asks to go ahead', detail: short(input.plan ?? '', 6000), options: PLAN_OPTIONS, allowText: true, action: { tool: name, label: act.label, target: act.target } }
+  }
+  const detail = act.detail?.command ?? act.detail?.content ?? (act.detail?.edit ? `- ${act.detail.edit.old}\n+ ${act.detail.edit.new}` : undefined)
+  return {
+    id: requestId(),
+    type: 'permission',
+    title: `Claude wants to ${act.label.toLowerCase()} ${act.target}`.trim(),
+    detail: detail ? short(detail, 2000) : undefined,
+    options: PERMISSION_OPTIONS,
+    allowText: false,
+    action: { tool: name, label: act.label, target: act.target },
+  }
+}
+
+/** Turn a protocol answer back into what the SDK expects. */
+function applyAnswer(name, input, request, answer, suggestions) {
+  const chosen = answer.optionIds ?? []
+  if (request.type === 'choice') {
+    const answers = {}
+    for (const q of request.questions ?? []) {
+      const per = answer.answers?.[q.id]
+      const ids = per?.optionIds ?? (q.id === 'q1' ? chosen : [])
+      const labels = ids.map(id => q.options.find(o => o.id === id)?.label).filter(Boolean)
+      const text = per?.text ?? (q.id === 'q1' ? answer.text : undefined)
+      answers[q.question] = labels.length ? labels.join(', ') : text ?? ''
+    }
+    const filled = Object.values(answers).some(Boolean)
+    if (!filled) return { behavior: 'deny', message: 'The user did not answer the question. Stop and say what you need to know.' }
+    return { behavior: 'allow', updatedInput: { ...input, answers, ...(answer.text ? { response: answer.text } : {}) } }
+  }
+  if (request.type === 'plan') {
+    if (chosen.includes('approve')) return { behavior: 'allow', updatedInput: input }
+    return { behavior: 'deny', message: answer.text ? `The user wants the plan changed: ${answer.text}` : 'The user asked you to revise the plan before going ahead.' }
+  }
+  if (chosen.includes('always') || chosen.includes('allow')) return { behavior: 'allow', updatedInput: input, ...(chosen.includes('always') && suggestions?.length ? { updatedPermissions: suggestions } : {}) }
+  return { behavior: 'deny', message: `The user declined this${answer.text ? ` ("${answer.text}")` : ''}. Do not achieve the same effect another way; if the task cannot proceed without it, stop and say what you could not do.` }
+}
+
+/**
+ * Run one instruction in a Claude session.
+ * @param io.emit(event)       a protocol event
+ * @param io.ask(request)      resolves to { answer, by } when a person answers (the caller times it out)
+ * @returns { ok, text, error, sessionId, stats }
+ */
+/** "Always allow" answers, remembered for the rest of the process per session: `${sessionId}` -> Set of rule keys. */
+const sessionAllows = new Map()
+function ruleKey(toolName, input) {
+  if (toolName === 'Bash') return `Bash:${String(input.command ?? '').trim().split(/\s+/)[0]}`
+  return toolName
+}
+
+/**
+ * The bridge's own policy, applied to every tool call regardless of what the
+ * user's local Claude Code settings would do. Returns 'allow' or 'ask'.
+ */
+function policy(toolName, input, cwd, session) {
+  if (READ_ONLY.has(toolName)) return 'allow'
+  if (EDITS.has(toolName) && inside(cwd, input.file_path ?? input.notebook_path)) return 'allow'
+  if (toolName === 'Bash' && SAFE_SHELL.test(String(input.command ?? '').trim())) return 'allow'
+  if (session && sessionAllows.get(session)?.has(ruleKey(toolName, input))) return 'allow'
+  return 'ask'
+}
+
+export async function run({ prompt, sessionId, cwd }, io) {
+  let session = sessionId ?? null
+  let text = ''
+  let error = null
+
+  // Pre-tool hook: force the prompt for anything the policy does not allow, so
+  // a permissive local config (e.g. Bash(*) allowed) cannot bypass the person.
+  const preToolUse = async input => {
+    if (input.hook_event_name !== 'PreToolUse') return {}
+    const decision = policy(input.tool_name, input.tool_input ?? {}, cwd, session)
+    return { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: decision === 'ask' ? 'Kira asks the user' : 'Kira policy' } }
+  }
+
+  const canUseTool = async (toolName, input, { signal, suggestions }) => {
+    if (policy(toolName, input, cwd, session) === 'allow') return { behavior: 'allow', updatedInput: input }
+    const request = toRequest(toolName, input, cwd, suggestions)
+    io.emit({ kind: 'request', request })
+    let resolved
+    try {
+      resolved = await io.ask(request, signal)
+    } catch (err) {
+      resolved = { answer: { optionIds: [], text: err.message }, by: 'timeout' }
+    }
+    io.emit({ kind: 'request_resolved', id: request.id, answer: resolved.answer, by: resolved.by })
+    if ((resolved.answer.optionIds ?? []).includes('always') && session) {
+      if (!sessionAllows.has(session)) sessionAllows.set(session, new Set())
+      sessionAllows.get(session).add(ruleKey(toolName, input))
+    }
+    return applyAnswer(toolName, input, request, resolved.answer, suggestions)
+  }
+
+  try {
+    const q = query({
+      prompt,
+      options: {
+        cwd,
+        ...(sessionId ? { resume: sessionId } : {}),
+        permissionMode: 'default',
+        canUseTool,
+        hooks: { PreToolUse: [{ hooks: [preToolUse] }] },
+        ...(process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}),
+      },
+    })
+    for await (const m of q) {
+      if (m.type === 'system' && m.subtype === 'init') {
+        session = m.session_id ?? session
+        io.emit({ kind: 'session', sessionId: session, model: m.model ?? null })
+      } else if (m.type === 'assistant') {
+        for (const b of m.message?.content ?? []) {
+          if (b.type === 'text' && b.text?.trim()) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
+          else if (b.type === 'tool_use') io.emit({ kind: 'action', id: b.id, tool: b.name, ...describeAction(b.name, b.input, cwd) })
+        }
+      } else if (m.type === 'user') {
+        for (const b of m.message?.content ?? []) {
+          if (b?.type === 'tool_result') {
+            const t = typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.map(c => (c.type === 'text' ? c.text : '')).join('\n') : ''
+            io.emit({ kind: 'action_result', id: b.tool_use_id, ok: !b.is_error, preview: short(t.trim(), 240) })
+          }
+        }
+      } else if (m.type === 'result') {
+        session = m.session_id ?? session
+        if (m.subtype === 'success') text = String(m.result ?? '')
+        else error = `Claude stopped: ${m.subtype}${Array.isArray(m.errors) && m.errors.length ? ` (${m.errors.join('; ').slice(0, 300)})` : ''}`
+        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd }
+        io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: session, stats })
+        return { ok: !error, text, error, sessionId: session, stats }
+      }
+    }
+    return { ok: !error, text, error, sessionId: session }
+  } catch (err) {
+    const message = `could not run Claude: ${err.message}`
+    io.emit({ kind: 'result', ok: false, error: message, sessionId: session })
+    return { ok: false, error: message, sessionId: session }
+  }
+}
+
+export const claude = { id: 'claude', name: 'Claude Code', run, capabilities: { resume: true, requests: ['permission', 'choice', 'text', 'plan'] } }

package/src/agents/index.mjs

@@ -0,0 +1,9 @@
+// Coding agents this bridge can run. Each adapter speaks agents/protocol.mjs;
+// adding Codex or another agent is a new file here and nothing else.
+import { claude } from './claude.mjs'
+
+export const AGENTS = { claude }
+
+export function agentById(id) {
+  return AGENTS[id ?? 'claude'] ?? null
+}

package/src/agents/protocol.mjs

@@ -0,0 +1,41 @@
+// The agent protocol: what every coding agent adapter emits, whatever the
+// agent. The API, the portal and the glasses only ever see these shapes.
+//
+//   session          { kind, sessionId, model? }
+//   message          { kind, text }                        the agent said something
+//   action           { kind, id, type, tool, label, target, note?, detail? }
+//                      type: read | search | edit | write | run | fetch | delegate | plan | other
+//                      detail: { edit: {old,new,all} | edits: [...] | content | command }
+//   action_result    { kind, id, ok, preview? }
+//   request          { kind, request: AgentRequest }        needs a person; the job waits
+//   request_resolved { kind, id, answer, by }              by: voice | lens | phone | portal | timeout | policy
+//   result           { kind, ok, text?, error?, sessionId?, stats? }
+//
+// AgentRequest:
+//   { id, type: permission | choice | text | plan, title, detail?, options: [{id,label,description?}],
+//     multi?, allowText?, action?: {tool,label,target}, questions?: [{id, question, header, options, multi}] }
+// RequestAnswer:
+//   { optionIds?: string[], text?: string, answers?: { [questionId]: { optionIds?, text? } } }
+
+let requestSeq = 0
+export function requestId() {
+  return `r${++requestSeq}-${Date.now().toString(36)}`
+}
+
+export const PERMISSION_OPTIONS = [
+  { id: 'allow', label: 'Allow', description: 'Let it do this once' },
+  { id: 'always', label: 'Always allow', description: 'Let it do this for the rest of the session' },
+  { id: 'deny', label: 'Deny', description: 'Do not do this' },
+]
+
+export const PLAN_OPTIONS = [
+  { id: 'approve', label: 'Approve', description: 'Go ahead with this plan' },
+  { id: 'revise', label: 'Revise', description: 'Change the plan first; say what to change' },
+]
+
+/** Normalize the many ways an answer can arrive into option ids and text. */
+export function normalizeAnswer(answer) {
+  const a = answer ?? {}
+  const optionIds = Array.isArray(a.optionIds) ? a.optionIds.map(String) : a.optionId ? [String(a.optionId)] : a.option ? [String(a.option)] : []
+  return { optionIds, text: typeof a.text === 'string' && a.text.trim() ? a.text.trim() : undefined, answers: a.answers && typeof a.answers === 'object' ? a.answers : undefined }
+}

package/src/claude-run.mjs

@@ -1,27 +1,7 @@
-// Runs Claude Code headless: `claude -p --resume <id> --output-format json`.
-import { spawn } from 'node:child_process'
+// Folder resolution shared by the agents and the file tools.
 import { existsSync } from 'node:fs'
 import { homedir } from 'node:os'
-import { isAbsolute, join, resolve } from 'node:path'
-
-/**
- * Find the claude binary. The bridge may be started from a shell whose PATH
- * lacks ~/.local/bin (launchd, a minimal terminal, a different shell), so
- * check the usual install locations before giving up.
- */
-export function findClaude() {
-  if (process.env.KIRA_CLAUDE_BIN && existsSync(process.env.KIRA_CLAUDE_BIN)) return process.env.KIRA_CLAUDE_BIN
-  const candidates = [
-    join(homedir(), '.local', 'bin', 'claude'),
-    join(homedir(), '.claude', 'local', 'claude'),
-    '/opt/homebrew/bin/claude',
-    '/usr/local/bin/claude',
-  ]
-  for (const c of candidates) if (existsSync(c)) return c
-  return 'claude' // rely on PATH
-}
-
-const MAX_MS = 15 * 60 * 1000
+import { isAbsolute, resolve } from 'node:path'
 
 /** Kira's paths are relative to home unless absolute, like the file tools. */
 export function resolveCwd(cwd) {
@@ -30,35 +10,7 @@ export function resolveCwd(cwd) {
   return isAbsolute(s) ? resolve(s) : resolve(homedir(), s)
 }
 
-export function runClaude({ prompt, sessionId, cwd }) {
-  return new Promise(done => {
-    const dir = resolveCwd(cwd)
-    if (!existsSync(dir)) return done({ error: `folder not found: ${dir}` })
-    const args = ['-p', '--output-format', 'json', '--permission-mode', 'acceptEdits']
-    if (sessionId) args.push('--resume', sessionId)
-    args.push(prompt)
-    const child = spawn(findClaude(), args, { cwd: dir, env: process.env, stdio: ['ignore', 'pipe', 'pipe'] })
-    let out = ''
-    let err = ''
-    const timer = setTimeout(() => {
-      child.kill('SIGTERM')
-      done({ error: `Claude did not finish within ${MAX_MS / 60000} minutes` })
-    }, MAX_MS)
-    child.stdout.on('data', d => (out += d))
-    child.stderr.on('data', d => (err += d))
-    child.on('error', e => {
-      clearTimeout(timer)
-      const hint = e.code === 'ENOENT' ? 'Claude Code is not installed or not on the bridge\'s PATH. Install it, or set KIRA_CLAUDE_BIN=/path/to/claude when starting the bridge.' : e.message
-      done({ error: `could not start claude: ${hint}` })
-    })
-    child.on('close', code => {
-      clearTimeout(timer)
-      try {
-        const j = JSON.parse(out)
-        done({ session_id: j.session_id, result: j.result, is_error: !!j.is_error, cost_usd: j.total_cost_usd, duration_ms: j.duration_ms, num_turns: j.num_turns })
-      } catch {
-        done({ error: `claude exited with code ${code}: ${(err || out).slice(0, 500)}` })
-      }
-    })
-  })
+
+export function folderExists(dir) {
+  return existsSync(dir)
 }

package/src/git.mjs

@@ -2,16 +2,17 @@
 // difference after it. Everything is read-only; the working tree is never
 // touched. Missing git or a folder outside a repo simply yields null.
 import { execFile } from 'node:child_process'
-import { homedir } from 'node:os'
-import { relative } from 'node:path'
+import { homedir, tmpdir } from 'node:os'
+import { join, relative } from 'node:path'
+import { unlink } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
 
 const DIFF_CAP = 400 * 1024 // bytes of unified diff kept per change
-const UNTRACKED_CAP = 30 // new files whose content is included
 const COMMIT_CAP = 20
 
-function git(cwd, args, { ok = [0] } = {}) {
+function git(cwd, args, { ok = [0], env = {} } = {}) {
   return new Promise(resolve => {
-    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0' } }, (err, stdout) => {
+    execFile('git', args, { cwd, maxBuffer: 16 * 1024 * 1024, env: { ...process.env, GIT_OPTIONAL_LOCKS: '0', ...env } }, (err, stdout) => {
       if (err && !ok.includes(err.code)) return resolve(null)
       resolve(String(stdout ?? ''))
     })
@@ -23,15 +24,35 @@ export function display(full) {
   return rel && !rel.startsWith('..') ? `~/${rel}` : full
 }
 
-/** Repo identity plus the head and dirty files right now; null when not a git repo. */
+/**
+ * The whole working tree (tracked and untracked, .gitignore respected) as a
+ * git tree object, built through a throwaway index so the real index, the
+ * working tree and the reflog are untouched. Two of these diff to exactly
+ * what happened in between.
+ */
+async function treeOfWorkingCopy(root) {
+  const index = join(tmpdir(), `kira-index-${randomUUID()}`)
+  const env = { GIT_INDEX_FILE: index }
+  try {
+    const added = await git(root, ['add', '-A', '--', '.'], { env })
+    if (added === null) return null
+    const tree = await git(root, ['write-tree'], { env })
+    return tree?.trim() || null
+  } finally {
+    await unlink(index).catch(() => undefined)
+  }
+}
+
+/** Repo identity plus the head, dirty files and a tree of the working copy right now; null when not a git repo. */
 export async function snapshot(dir) {
   const root = (await git(dir, ['rev-parse', '--show-toplevel']))?.trim()
   if (!root) return null
-  const [head, branch, remote, status] = await Promise.all([
+  const [head, branch, remote, status, tree] = await Promise.all([
     git(root, ['rev-parse', 'HEAD']),
     git(root, ['rev-parse', '--abbrev-ref', 'HEAD']),
     git(root, ['remote', 'get-url', 'origin']),
     git(root, ['status', '--porcelain=v1', '--untracked-files=all']),
+    treeOfWorkingCopy(root),
   ])
   return {
     root,
@@ -40,6 +61,7 @@ export async function snapshot(dir) {
     branch: branch?.trim() || null,
     repo: remoteToRepo(remote?.trim()),
     dirty: parseStatus(status ?? ''),
+    tree,
   }
 }
 
@@ -57,80 +79,77 @@ function parseStatus(out) {
 }
 
 /**
- * Everything different between the pre-job head and the working tree now:
- * commits made since, per-file stats, and one unified diff (committed and
- * uncommitted alike, new files included). Files that were already dirty
- * before the job are flagged so a reader can discount them.
+ * Exactly what happened between the snapshot and now: the working copy then
+ * versus the working copy now (committed or not, new files included), plus
+ * any commits made in between. Files that were already dirty before are
+ * flagged so a reader can discount hunks that were in flight.
  */
 export async function changesSince(before) {
   const { root } = before
-  const base = before.head
+  const after = await treeOfWorkingCopy(root)
+  if (!before.tree || !after) return null
+  if (before.tree === after) {
+    // Nothing on disk moved; a commit alone (e.g. Claude committed pending work) still counts.
+    const commits = await commitsSince(root, before.head)
+    return commits.length ? summary(before, root, [], '', false, commits, after) : null
+  }
   const dirtyBefore = new Set(before.dirty.map(d => d.path))
-  const [headNow, numstat, nameStatus, diff, untrackedOut] = await Promise.all([
-    git(root, ['rev-parse', 'HEAD']),
-    base ? git(root, ['diff', '--numstat', '-M', base]) : Promise.resolve(''),
-    base ? git(root, ['diff', '--name-status', '-M', base]) : Promise.resolve(''),
-    base ? git(root, ['diff', '-M', '--no-color', base]) : Promise.resolve(''),
-    git(root, ['ls-files', '--others', '--exclude-standard']),
+  const [numstat, nameStatus, diff] = await Promise.all([
+    git(root, ['diff', '--numstat', '-M', before.tree, after]),
+    git(root, ['diff', '--name-status', '-M', before.tree, after]),
+    git(root, ['diff', '-M', '--no-color', before.tree, after]),
   ])
   const files = new Map()
   for (const line of (numstat ?? '').split('\n').filter(Boolean)) {
     const [a, d, ...rest] = line.split('\t')
-    const path = rest.join('\t').replace(/^.*\{(.*) => (.*)\}.*$/, (m, o, n) => m.replace(`{${o} => ${n}}`, n)).replace(/^(.*) => (.*)$/, '$2')
-    files.set(path, { path, adds: a === '-' ? 0 : Number(a), dels: d === '-' ? 0 : Number(d), binary: a === '-', status: 'M' })
+    const path = rest[rest.length - 1]
+    files.set(path, { path, adds: a === '-' ? 0 : Number(a), dels: d === '-' ? 0 : Number(d), binary: a === '-', status: 'M', preexisting: dirtyBefore.has(path) })
   }
   for (const line of (nameStatus ?? '').split('\n').filter(Boolean)) {
     const [st, ...rest] = line.split('\t')
-    const path = rest[rest.length - 1]
-    const f = files.get(path)
+    const f = files.get(rest[rest.length - 1])
     if (f) f.status = st[0]
   }
   let text = diff ?? ''
-  const untracked = (untrackedOut ?? '').split('\n').filter(Boolean)
-  let shown = 0
-  for (const path of untracked) {
-    const isNew = !dirtyBefore.has(path)
-    const content = shown < UNTRACKED_CAP ? await git(root, ['diff', '--no-index', '--no-color', '--', '/dev/null', path], { ok: [0, 1] }) : null
-    let adds = 0
-    if (content) {
-      adds = (content.match(/^\+(?!\+\+)/gm) ?? []).length
-      if (text.length < DIFF_CAP) text += content
-      shown++
-    }
-    files.set(path, { path, adds, dels: 0, binary: content === null && shown < UNTRACKED_CAP, status: 'A', untracked: true, preexisting: !isNew })
-  }
-  for (const f of files.values()) if (dirtyBefore.has(f.path)) f.preexisting = true
   const truncated = text.length > DIFF_CAP
   if (truncated) text = text.slice(0, DIFF_CAP) + '\n… diff truncated …\n'
+  const commits = await commitsSince(root, before.head)
+  return summary(before, root, [...files.values()], text, truncated, commits, after)
+}
 
+async function commitsSince(root, base) {
+  const headNow = (await git(root, ['rev-parse', 'HEAD']))?.trim()
+  if (!base || !headNow || headNow === base) return []
   const commits = []
-  if (base && headNow && headNow.trim() !== base) {
-    const log = await git(root, ['log', '--format=%H%x1f%s%x1f%cI', `${base}..HEAD`, `--max-count=${COMMIT_CAP}`])
-    for (const line of (log ?? '').split('\n').filter(Boolean)) {
-      const [sha, title, at] = line.split('\x1f')
-      const ns = await git(root, ['show', '--numstat', '--format=', sha])
-      let adds = 0, dels = 0, n = 0
-      for (const l of (ns ?? '').split('\n').filter(Boolean)) {
-        const [a, d] = l.split('\t')
-        if (a !== '-') adds += Number(a)
-        if (d !== '-') dels += Number(d)
-        n++
-      }
-      commits.push({ sha, short: sha.slice(0, 7), title, at, files: n, adds, dels })
+  const log = await git(root, ['log', '--format=%H%x1f%s%x1f%cI', `${base}..HEAD`, `--max-count=${COMMIT_CAP}`])
+  for (const line of (log ?? '').split('\n').filter(Boolean)) {
+    const [sha, title, at] = line.split('\x1f')
+    const ns = await git(root, ['show', '--numstat', '--format=', sha])
+    let adds = 0, dels = 0, n = 0
+    for (const l of (ns ?? '').split('\n').filter(Boolean)) {
+      const [a, d] = l.split('\t')
+      if (a !== '-') adds += Number(a)
+      if (d !== '-') dels += Number(d)
+      n++
     }
+    commits.push({ sha, short: sha.slice(0, 7), title, at, files: n, adds, dels })
   }
-  const list = [...files.values()]
-  if (list.length === 0 && commits.length === 0) return null
+  return commits
+}
+
+async function summary(before, root, files, diff, truncated, commits, treeAfter) {
   return {
     cwd: before.cwd,
     repo: before.repo,
     branch: (await git(root, ['rev-parse', '--abbrev-ref', 'HEAD']))?.trim() || before.branch,
-    head_before: base,
-    head_after: headNow?.trim() || null,
+    head_before: before.head,
+    head_after: (await git(root, ['rev-parse', 'HEAD']))?.trim() || null,
+    tree_before: before.tree,
+    tree_after: treeAfter,
     commits,
-    files: list,
-    stats: { files: list.length, adds: list.reduce((s, f) => s + f.adds, 0), dels: list.reduce((s, f) => s + f.dels, 0) },
-    diff: text,
+    files,
+    stats: { files: files.length, adds: files.reduce((s, f) => s + f.adds, 0), dels: files.reduce((s, f) => s + f.dels, 0) },
+    diff,
     truncated,
   }
 }

package/src/index.mjs

@@ -4,7 +4,9 @@
 import WebSocket from 'ws'
 import { listProjects, listSessions, readSession } from './claude-sessions.mjs'
 import { snapshot, changesSince, display } from './git.mjs'
-import { runClaude, findClaude, resolveCwd } from './claude-run.mjs'
+import { resolveCwd } from './claude-run.mjs'
+import { agentById, AGENTS } from './agents/index.mjs'
+import { normalizeAnswer } from './agents/protocol.mjs'
 import { openApp, installedApps } from './apps.mjs'
 import { listFiles, readUserFile, createFolder, writeUserFile, trashPath, resolveUserPath } from './files.mjs'
 
@@ -13,6 +15,9 @@ const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.j
 
 let URL_ = ''
 let TOKEN = ''
+/** Requests waiting on a person: `${jobId}:${requestId}` -> resolve({ answer, by }). */
+const answerWaits = new Map()
+const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
 
 /** Start the bridge with resolved settings. Runs until the process exits. */
 export function startBridge(config) {
@@ -23,7 +28,7 @@ export function startBridge(config) {
     console.error('No token. Run: npx kira-glasses-bridge --token <token>  (from the Kira portal → Connections → Claude Code)')
     process.exit(1)
   }
-  log(`kira-bridge ${BRIDGE_VERSION} · claude binary: ${findClaude()}`)
+  log(`kira-bridge ${BRIDGE_VERSION} · agents: ${Object.keys(AGENTS).join(', ')}`)
   connect()
 }
 
@@ -58,28 +63,59 @@ const tools = {
   async read_claude_session(args) {
     return readSession(String(args.session_id ?? ''), args.turns)
   },
-  // Acknowledge now, report the result as a job when Claude finishes.
-  async ask_claude(args, ws) {
+  /**
+   * Run an instruction with a coding agent. Acknowledges at once, streams every
+   * protocol event as `job.event`, and reports the outcome as `job` when done.
+   * Requests that need a person park the job until `job.answer` arrives.
+   */
+  async run_agent(args, ws) {
     const jobId = String(args.job_id ?? '')
+    const agent = agentById(args.agent)
+    if (!agent) return { error: `unknown agent ${args.agent}` }
     const prompt = String(args.prompt ?? args.message ?? args.text ?? args.instruction ?? '').trim()
     if (!prompt) return { error: 'prompt is required' }
-    // A resumed session runs in its own folder even when the caller did not say which.
     let cwd = args.cwd
     if (!cwd && args.session_id) {
       const s = await readSession(String(args.session_id), 1)
       if (s?.cwd) cwd = s.cwd
     }
     const dir = resolveCwd(cwd)
-    log(`ask_claude job=${jobId.slice(0, 8)} session=${args.session_id ?? 'new'} in ${display(dir)}: ${prompt.slice(0, 80)}`)
-    // Git before and after, so the API can show exactly what this job changed.
+    log(`${agent.id} job=${jobId.slice(0, 8)} session=${args.session_id ?? 'new'} in ${display(dir)}: ${prompt.slice(0, 80)}`)
     const before = await snapshot(dir).catch(() => null)
-    void runClaude({ prompt, sessionId: args.session_id, cwd: dir }).then(async result => {
+    let seq = 0
+    const io = {
+      emit: event => send(ws, { type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
+      ask: (request, signal) =>
+        new Promise((resolve, reject) => {
+          const key = `${jobId}:${request.id}`
+          const timer = setTimeout(() => {
+            answerWaits.delete(key)
+            reject(new Error('No answer within 3 minutes'))
+          }, ANSWER_TIMEOUT_MS)
+          answerWaits.set(key, resolved => {
+            clearTimeout(timer)
+            resolve(resolved)
+          })
+          signal?.addEventListener('abort', () => {
+            clearTimeout(timer)
+            answerWaits.delete(key)
+            reject(new Error('The job was stopped'))
+          }, { once: true })
+        }),
+    }
+    void agent.run({ prompt, sessionId: args.session_id, cwd: dir }, io).then(async outcome => {
+      for (const key of [...answerWaits.keys()]) if (key.startsWith(`${jobId}:`)) answerWaits.delete(key)
       let change = null
       if (before) change = await changesSince(before).catch(err => (log(`git after job failed: ${err.message}`), null))
-      log(`job ${jobId.slice(0, 8)} ${result.error ? 'error' : 'done'}${change ? ` · ${change.stats.files} files +${change.stats.adds} -${change.stats.dels}, ${change.commits.length} commits` : ''}`)
-      send(ws, { type: 'job', jobId, status: result.error ? 'error' : 'done', result: { ...result, cwd: display(dir), change }, error: result.error })
+      log(`job ${jobId.slice(0, 8)} ${outcome.ok ? 'done' : 'error'}${change ? ` · ${change.stats.files} files +${change.stats.adds} -${change.stats.dels}, ${change.commits.length} commits` : ''}`)
+      const result = { session_id: outcome.sessionId, result: outcome.text ?? '', stats: outcome.stats, cwd: display(dir), change, agent: agent.id }
+      send(ws, { type: 'job', jobId, status: outcome.ok ? 'done' : 'error', result, error: outcome.error })
     })
-    return { started: true, cwd: display(dir), git: before ? { repo: before.repo, branch: before.branch, head: before.head?.slice(0, 7) ?? null } : null }
+    return { started: true, agent: agent.id, cwd: display(dir), git: before ? { repo: before.repo, branch: before.branch, head: before.head?.slice(0, 7) ?? null } : null }
+  },
+  /** Older API builds still call ask_claude. */
+  ask_claude(args, ws) {
+    return tools.run_agent({ ...args, agent: 'claude' }, ws)
   },
 
   /** Read-only git facts for a folder: repo, branch, head, dirty files. */
@@ -130,9 +166,19 @@ function connect() {
     if (msg.type === 'hello') {
       // Tell the API which tools this bridge build implements, so a stale
       // bridge is reported as such instead of "unknown tool".
-      send(ws, { type: 'capabilities', tools: Object.keys(tools), version: BRIDGE_VERSION, platform: process.platform })
+      send(ws, { type: 'capabilities', tools: Object.keys(tools), version: BRIDGE_VERSION, platform: process.platform, agents: Object.values(AGENTS).map(a => ({ id: a.id, name: a.name, capabilities: a.capabilities })) })
       return log(`registered as bridge ${msg.bridgeId} (${Object.keys(tools).length} tools)`)
     }
+    if (msg.type === 'job.answer') {
+      const key = `${msg.jobId}:${msg.requestId}`
+      const resolve = answerWaits.get(key)
+      if (resolve) {
+        answerWaits.delete(key)
+        resolve({ answer: normalizeAnswer(msg.answer), by: msg.by ?? 'portal' })
+        log(`request ${msg.requestId} for job ${String(msg.jobId).slice(0, 8)} answered by ${msg.by ?? 'portal'}`)
+      }
+      return
+    }
     if (msg.type !== 'call') return
     const fn = tools[msg.tool]
     if (!fn) return send(ws, { type: 'error', id: msg.id, error: `unknown tool ${msg.tool}` })

package/src/service.mjs

@@ -1,4 +1,5 @@
 // launchd integration: run the bridge at login and keep it alive.
+import { execSync } from 'node:child_process'
 import { execFileSync } from 'node:child_process'
 import { mkdirSync, writeFileSync, existsSync, unlinkSync, readFileSync, cpSync, rmSync } from 'node:fs'
 import { homedir } from 'node:os'
@@ -19,16 +20,22 @@ function packageRoot() {
   return dirname(new URL('.', import.meta.url).pathname.replace(/\/$/, ''))
 }
 
-/** Copy this package (src + package.json + node_modules/ws) into ~/.kira/app. */
+/**
+ * Stage this package under ~/.kira/app and install its dependencies there with
+ * npm. The Agent SDK brings a per-platform native package, so a plain copy of
+ * node_modules is not enough; a real install is.
+ */
 function stageApp() {
   const root = packageRoot()
   rmSync(APP_DIR, { recursive: true, force: true })
   mkdirSync(APP_DIR, { recursive: true })
   cpSync(join(root, 'src'), join(APP_DIR, 'src'), { recursive: true })
   cpSync(join(root, 'package.json'), join(APP_DIR, 'package.json'))
-  // ws is the only dependency; resolve it from wherever npm put it.
-  const wsPkg = dirname(new URL(import.meta.resolve('ws/package.json')).pathname)
-  cpSync(wsPkg, join(APP_DIR, 'node_modules', 'ws'), { recursive: true })
+  try {
+    execSync('npm install --omit=dev --no-audit --no-fund --loglevel=error', { cwd: APP_DIR, stdio: 'inherit' })
+  } catch (err) {
+    throw new Error(`could not install the bridge's dependencies in ${APP_DIR}: ${err.message}`)
+  }
   return join(APP_DIR, 'src', 'cli.mjs')
 }