kira-glasses-bridge 2.11.0 → 2.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.11.0",
+  "version": "2.13.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": {

package/src/index.mjs

@@ -9,6 +9,7 @@ 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'
+import { initTerminals, terminalCall, terminalMessage, terminalsOffline } from './terminals.mjs'
 import { prepareWorktree, worktreeStatus, pushWorktree, removeWorktree, repoOfFolder, stageFiles, listOutputs, uploadOutputs } from './worktrees.mjs'
 
 import { createRequire } from 'node:module'
@@ -40,6 +41,9 @@ const ANSWER_TIMEOUT_MS = 3 * 60 * 1000
  * token is rejected); an app embedding it (the Kira desktop app) passes its own:
  *   log(line)               every log line
  *   onStatus(status)        'connecting' | 'connected' | 'disconnected' | 'rejected'
+ *   openTerminal({ cwd, command })   open_terminal in the app's own terminal (a Kira tab), not
+ *                           Terminal.app; resolves to what to report, or null to fall back
+ *   terminals               the app's shells, for remote devices (terminals.mjs)
  */
 let hooks = {}
 let stopped = false
@@ -55,6 +59,8 @@ export function startBridge(config, hostHooks = {}) {
     throw new Error('No token. Run: npx kira-glasses-bridge --token <token>  (from the Kira portal → Connections → Claude Code)')
   }
   stopped = false
+  // Terminal output is live or nothing: never queued for later like job events.
+  initTerminals(() => hooks.terminals ?? null, obj => live?.readyState === WebSocket.OPEN && live.send(JSON.stringify(obj)))
   log(`kira-bridge ${BRIDGE_VERSION} · agents: ${Object.keys(AGENTS).join(', ')}`)
   connect()
 }
@@ -185,10 +191,18 @@ const tools = {
     return setupProjectFolder({ dir, name: args.name, description: args.description, sshUrl: args.ssh_url, httpsUrl: args.https_url })
   },
 
-  /** Open Terminal on this Mac in a folder and run a command there (used to hand a Claude session to the person). */
+  /** This Mac's shells for a browser elsewhere (only inside the Mac app, only when switched on there). */
+  terminal: args => terminalCall(args),
+
+  /** Open a terminal on this Mac in a folder and run a command there (used to hand a Claude session
+   *  to the person): a Kira tab when the bridge runs inside the Mac app, else Terminal.app. */
   async open_terminal(args) {
     const dir = resolveUserPath(String(args.cwd ?? ''))
     const command = String(args.command ?? '').replace(/[^\w\s./:@=-]/g, '')
+    if (hooks.openTerminal) {
+      const r = await Promise.resolve(hooks.openTerminal({ cwd: dir, command })).catch(err => ({ error: err?.message ?? String(err) }))
+      if (r) return { ...r, cwd: display(dir), command }
+    }
     if (process.platform !== 'darwin') return { error: 'opening a terminal is only supported on macOS' }
     const { execFile } = await import('node:child_process')
     const script = `tell application "Terminal"
@@ -313,6 +327,7 @@ function connect() {
       }
       return
     }
+    if (terminalMessage(msg)) 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}` })
@@ -325,6 +340,7 @@ function connect() {
   ws.on('close', (code, reason) => {
     clearInterval(ping)
     if (live === ws) live = null
+    terminalsOffline()
     if (code === 4001) {
       log('token rejected; create a new one in the portal')
       status('rejected')

package/src/terminals.mjs

@@ -0,0 +1,157 @@
+// Remote terminals: this Mac's shells for a browser at kira.glass, relayed by the API. Only when
+// the bridge runs inside the Kira Mac app (it passes a `terminals` hook: the app's own shells) and
+// only while the person has switched "terminals from other devices" on there. The npm bridge has no
+// shells to offer.
+//
+// From the API:  a `terminal` call { op, … } (list, open, attach, …), and messages
+//                term.watch { conn, on, who }   a device connected / went
+//                term.in { id, data }           keystrokes
+//                term.resize { id, cols, rows }
+//                term.layout { layout }        a browser rearranged the tabs/splits
+// To the API:    term.data { id, data, end } · term.title { id, title } · term.exit { id, code }
+//                term.layout { layout } (rearranged on any screen, the Mac's included)
+//                term.commands (the quick lists changed) · term.off / term.on (switched on the Mac)
+// Output flows only while at least one device is connected.
+
+let getHost = () => null
+let sendNow = () => {}
+/** Connected devices (conn id -> who), kept while switched off too, so switching on reaches them. */
+const conns = new Map()
+let unfollow = null
+let watchingAllowed = null
+
+/** `host()` gives the app's terminals hook (or null); `send(obj)` sends now, or drops it while offline. */
+export function initTerminals(host, send) {
+  getHost = host
+  sendNow = send
+}
+
+const ready = () => {
+  const h = getHost()
+  return h && h.allowed() ? h : null
+}
+
+function follow(h) {
+  if (unfollow) return
+  const offEvents = h.onEvents((kind, id, a, b) => {
+    if (kind === 'data') sendNow({ type: 'term.data', id, data: a, end: b })
+    else if (kind === 'title') sendNow({ type: 'term.title', id, title: a })
+    else if (kind === 'exit') sendNow({ type: 'term.exit', id, code: a })
+  })
+  const offCommands = h.onCommands?.(() => sendNow({ type: 'term.commands' })) ?? (() => {})
+  const offLayout = h.onLayout?.(layout => sendNow({ type: 'term.layout', layout })) ?? (() => {})
+  unfollow = () => {
+    offEvents()
+    offCommands()
+    offLayout()
+    unfollow = null
+  }
+}
+
+/** Switched on or off in the Mac app: tell the devices, and start or stop following the shells. */
+function watchAllowed(h) {
+  if (watchingAllowed || !h.onAllowed) return
+  watchingAllowed = h.onAllowed(on => {
+    if (on) {
+      for (const [conn, who] of conns) h.viewer?.(conn, true, who)
+      if (conns.size) follow(h)
+      sendNow({ type: 'term.on' })
+    } else {
+      unfollow?.()
+      h.viewersGone?.()
+      sendNow({ type: 'term.off' })
+    }
+  })
+}
+
+/** The connection to the API dropped: its devices are gone with it (it tells us again on reconnect). */
+export function terminalsOffline() {
+  conns.clear()
+  unfollow?.()
+  getHost()?.viewersGone?.()
+}
+
+/** Messages from the API about terminals. True when it was one. */
+export function terminalMessage(msg) {
+  if (!msg.type?.startsWith('term.')) return false
+  const h = ready()
+  if (msg.type === 'term.watch') {
+    const conn = String(msg.conn ?? '')
+    const host = getHost()
+    if (host) watchAllowed(host)
+    if (msg.on) {
+      conns.set(conn, String(msg.who ?? ''))
+      if (h) {
+        h.viewer?.(conn, true, String(msg.who ?? ''))
+        follow(h)
+      } else sendNow({ type: 'term.off' })
+    } else {
+      conns.delete(conn)
+      host?.viewer?.(conn, false)
+      if (!conns.size) unfollow?.()
+    }
+    return true
+  }
+  if (!h || !conns.size) return true
+  if (msg.type === 'term.in' && typeof msg.data === 'string' && msg.data.length <= 1_000_000) h.write(String(msg.id), msg.data)
+  else if (msg.type === 'term.resize') h.resize(String(msg.id), Number(msg.cols), Number(msg.rows))
+  else if (msg.type === 'term.layout') h.setLayout?.(msg.layout)
+  return true
+}
+
+/** The `terminal` call: one op at a time. Refused unless switched on in the Mac app. */
+export async function terminalCall(args) {
+  const h = getHost()
+  if (args.op === 'status') return { available: !!h, allowed: !!h?.allowed() }
+  if (!h) return { error: 'terminals need the Kira Mac app (this bridge has none)', reason: 'unavailable' }
+  if (!h.allowed()) return { error: 'terminals from other devices are off on this Mac (Kira for Mac → This Mac)', reason: 'off' }
+  const id = String(args.id ?? '')
+  const str = v => (typeof v === 'string' && v.length < 4096 ? v : undefined)
+  switch (args.op) {
+    case 'list':
+      return { terminals: h.list() }
+    case 'layout':
+      return { layout: h.getLayout?.() ?? null }
+    case 'open':
+      return h.open({ cwd: str(args.cwd), command: str(args.command), cols: Number(args.cols) || undefined, rows: Number(args.rows) || undefined })
+    case 'attach':
+      return h.attach(id)
+    case 'close':
+      h.close(id)
+      return { closed: true }
+    case 'busy':
+      return { program: h.busy(id) }
+    // Kira's own: typing into a shell and showing a shell she opened, without a device connected.
+    case 'write':
+      if (typeof args.data !== 'string' || args.data.length > 100_000) return { error: 'nothing to type' }
+      h.write(id, args.data)
+      return { written: true }
+    case 'place': {
+      // A new tab at the end of the shared layout, so every screen (the Mac's window too) shows it.
+      const layout = h.getLayout?.() ?? { tabs: [] }
+      const tabs = (layout.tabs ?? []).filter(t => !JSON.stringify(t.root).includes(`"${id}"`))
+      h.setLayout?.({ tabs: [...tabs, { key: Math.random().toString(36).slice(2, 10), root: { kind: 'term', id } }], from: 'kira' })
+      return { placed: true }
+    }
+    case 'cwd':
+      return { cwd: await h.cwd(id) }
+    case 'commands':
+      return { rows: h.commands({ cwd: str(args.cwd), query: str(args.query), limit: Number(args.limit) || undefined }) }
+    case 'folders':
+      return { rows: h.folders({ query: str(args.query), limit: Number(args.limit) || undefined }) }
+    case 'pinCommand':
+      h.pinCommand(String(args.cmd), !!args.on)
+      return { ok: true }
+    case 'forgetCommand':
+      h.forgetCommand(String(args.cmd))
+      return { ok: true }
+    case 'pinFolder':
+      h.pinFolder(String(args.path), !!args.on)
+      return { ok: true }
+    case 'forgetFolder':
+      h.forgetFolder(String(args.path))
+      return { ok: true }
+    default:
+      return { error: `unknown terminal op ${args.op}` }
+  }
+}

package/src/worktrees.mjs

@@ -173,15 +173,27 @@ const STAGE_MAX_BYTES = 200 * 1024 * 1024
  * Put a task's reference files into the worktree under .kira/files (excluded
  * from git through .git/info/exclude, never committed), so the agent can open
  * them like anything else on disk. Downloads from short-lived signed URLs.
+ *
+ * Handing a task to Claude in a terminal (the portal's "From Kira") uses it too, with `dir`: the
+ * files go to .kira/<dir> (e.g. tasks/52) and are kept, not wiped, and `path` needn't be a git
+ * checkout (`create` makes it, for ~/Kira/tasks/...). A file can be `text` instead of a `url` (the
+ * task's brief.md).
  */
-export async function stageFiles({ path: p, files }) {
+export async function stageFiles({ path: p, files, dir: sub, create }) {
   const path = resolveUserPath(String(p ?? ''))
-  if (!(await exists(join(path, '.git')))) return { error: 'no worktree at that path', path: display(path) }
-  const dir = join(path, STAGE_DIR)
-  await rm(dir, { recursive: true, force: true })
+  const handover = typeof sub === 'string' && sub.length > 0
+  const isGit = await exists(join(path, '.git'))
+  if (!isGit && !handover) return { error: 'no worktree at that path', path: display(path) }
+  if (!(await exists(path))) {
+    if (!create) return { error: 'that folder isn’t on this Mac', path: display(path) }
+    await mkdir(path, { recursive: true })
+  }
+  const rel = handover ? `.kira/${String(sub).replace(/\.\.+/g, '').replace(/^\/+|\/+$/g, '')}` : STAGE_DIR
+  const dir = join(path, rel)
+  if (!handover) await rm(dir, { recursive: true, force: true })
   await mkdir(dir, { recursive: true })
   // A worktree's .git is a file pointing at the real gitdir; git tells us where its exclude file lives.
-  const excl = await git(path, ['rev-parse', '--git-path', 'info/exclude'])
+  const excl = isGit ? await git(path, ['rev-parse', '--git-path', 'info/exclude']) : { ok: false }
   if (excl.ok) {
     const file = isAbsolute(excl.out) ? excl.out : join(path, excl.out)
     await mkdir(join(file, '..'), { recursive: true })
@@ -196,20 +208,24 @@ export async function stageFiles({ path: p, files }) {
     if (seen.has(name)) name = `${name.replace(/(\.[^.]+)?$/, '')}-${seen.size}${/\.[^.]+$/.exec(name)?.[0] ?? ''}`
     seen.add(name)
     try {
-      const res = await fetch(String(f.url))
-      if (!res.ok || !res.body) throw new Error(`download failed (${res.status})`)
-      const len = Number(res.headers.get('content-length') ?? 0)
-      if (total + len > STAGE_MAX_BYTES) throw new Error('over the staging size limit')
       const dest = join(dir, name)
-      await pipeline(Readable.fromWeb(res.body), createWriteStream(dest))
+      if (typeof f.text === 'string') {
+        await writeFile(dest, f.text, 'utf8')
+      } else {
+        const res = await fetch(String(f.url))
+        if (!res.ok || !res.body) throw new Error(`download failed (${res.status})`)
+        const len = Number(res.headers.get('content-length') ?? 0)
+        if (total + len > STAGE_MAX_BYTES) throw new Error('over the staging size limit')
+        await pipeline(Readable.fromWeb(res.body), createWriteStream(dest))
+      }
       const size = (await stat(dest)).size
       total += size
-      staged.push({ name, path: `${STAGE_DIR}/${name}`, bytes: size, description: f.description || undefined })
+      staged.push({ name, path: `${rel}/${name}`, abs: dest, bytes: size, description: f.description || undefined })
     } catch (err) {
       staged.push({ name, error: err.message })
     }
   }
-  return { dir: `${STAGE_DIR}/`, staged, bytes: total }
+  return { dir: `${rel}/`, abs: dir, staged, bytes: total }
 }
 
 const OUTPUT_MAX_FILES = 60
@@ -221,9 +237,17 @@ function mimeOf(name) {
 }
 
 /** Files under an output folder of a worktree (a designer's design/, a researcher's docs/research/), with sizes and types. */
-export async function listOutputs({ path: p, dir }) {
+export async function listOutputs({ path: p, dir, only }) {
   const path = resolveUserPath(String(p ?? ''))
   const base = join(path, String(dir ?? '').replace(/^\/+|\/+$/g, ''))
+  // One named file (a terminal session's task_attach) may sit anywhere in the worktree, the root too.
+  if (typeof only === 'string' && only) {
+    const full = join(base, only)
+    if (only.includes('/') || !(base === path || base.startsWith(path + '/')) || !full.startsWith(path + '/')) return { error: 'bad output file' }
+    const s = await stat(full).catch(() => null)
+    if (!s?.isFile()) return { dir, files: [], bytes: 0 }
+    return { dir, files: [{ rel: only, bytes: s.size, mime: mimeOf(only) }], bytes: s.size }
+  }
   if (!base.startsWith(path + '/')) return { error: 'bad output folder' }
   const { readdir } = await import('node:fs/promises')
   const out = []