kira-glasses-bridge 2.34.0 → 2.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.34.0",
+  "version": "2.36.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": {
@@ -19,8 +19,10 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "smol-toml": "1.9.0",
-    "ws": "^8.18.0"
+    "ws": "^8.18.0",
+    "zod": "^4.6.5"
   },
   "keywords": [
     "even-realities",

package/src/claude-sessions.mjs

@@ -5,29 +5,22 @@ import { getSessionInfo, getSessionMessages, listSessions as sdkListSessions } f
 import { open, readdir, stat } from 'node:fs/promises'
 import { homedir } from 'node:os'
 import { basename, join } from 'node:path'
+import { doingOf, itemsOf, lastTurns, turnsOf } from './claude-transcript.mjs'
 
 const ACTIVE_WINDOW_MS = 3 * 60 * 1000
+const TEXT_CAP = 2000
 
-function textOf(message) {
-  const c = message?.content
-  if (typeof c === 'string') return c
-  if (Array.isArray(c)) return c.filter(b => b?.type === 'text').map(b => b.text).join('\n')
-  return ''
-}
-
-/** The conversation as said: user and Claude text, without tool results, system blocks or subagents. */
-async function turnsOf(sessionId, dir) {
+/** The session as it happened: its turns and the tool calls between them (claude-transcript.mjs). */
+async function itemsFor(sessionId, dir) {
   const messages = await getSessionMessages(sessionId, dir ? { dir } : undefined)
-  const turns = []
-  for (const m of messages) {
-    if (m.parent_tool_use_id) continue
-    const text = textOf(m.message).trim()
-    if (!text || text.startsWith('<')) continue // tool results / system blocks
-    turns.push({ role: m.type === 'user' ? 'user' : 'claude', text, at: m.timestamp ?? null })
-  }
-  return turns
+  return itemsOf(messages, dir ?? homedir())
 }
 
+/** The branch, unless the checkout is detached ("HEAD"). */
+const branchOf = s => (s.gitBranch && s.gitBranch !== 'HEAD' ? s.gitBranch : null)
+
+const capText = item => (item.kind === 'turn' ? { ...item, text: item.text.slice(0, TEXT_CAP) } : item)
+
 /**
  * The SDK reads a session's folder from the start of its transcript, and misses it when the
  * transcript opens with large snapshot entries. Then: the first "cwd" in the first MB of the file.
@@ -59,18 +52,22 @@ export async function listSessions(max = 10) {
   for (const s of await sdkListSessions({ limit: n })) {
     try {
       const cwd = await cwdOf(s)
-      const turns = await turnsOf(s.sessionId, cwd)
-      const lastUser = [...turns].reverse().find(t => t.role === 'user')
-      const lastClaude = [...turns].reverse().find(t => t.role === 'claude')
+      const items = await itemsFor(s.sessionId, cwd)
+      const turns = turnsOf(items)
+      const lastUser = turns.findLast(t => t.role === 'user')
+      const lastClaude = turns.findLast(t => t.role === 'claude')
+      const active = activeOf(s)
       sessions.push({
         session_id: s.sessionId,
         title: titleOf(s) ?? (lastUser ? lastUser.text.slice(0, 60) : '(untitled)'),
         project: cwd ? cwd.split('/').slice(-2).join('/') : null,
         cwd,
-        active: activeOf(s),
+        active,
         last_active_at: new Date(s.lastModified).toISOString(),
         last_user_message: lastUser ? lastUser.text.slice(0, 200) : null,
         last_claude_message: lastClaude ? lastClaude.text.slice(0, 200) : null,
+        branch: branchOf(s),
+        doing: active ? doingOf(items) : null,
       })
     } catch {
       /* unreadable transcript */
@@ -79,13 +76,28 @@ export async function listSessions(max = 10) {
   return { count: sessions.length, sessions }
 }
 
-export async function readSession(sessionId, turns = 6) {
+/**
+ * A session's last `turns` turns; with `items`, the tool calls between them too (the phone asks for
+ * them; Kira's own reads don't, to keep them short).
+ */
+export async function readSession(sessionId, turns = 6, { items: withItems = false } = {}) {
   const info = await getSessionInfo(sessionId).catch(() => undefined)
   if (!info) return { error: `No session ${sessionId} on this machine` }
   const cwd = await cwdOf(info)
-  const all = await turnsOf(sessionId, cwd)
+  const items = await itemsFor(sessionId, cwd)
   const n = Math.min(Math.max(Number(turns) || 6, 1), 30)
-  return { session_id: info.sessionId, title: titleOf(info), cwd, active: activeOf(info), last_active_at: new Date(info.lastModified).toISOString(), turns: all.slice(-n).map(t => ({ ...t, text: t.text.slice(0, 2000) })) }
+  const recent = lastTurns(items, n).map(capText)
+  return {
+    session_id: info.sessionId,
+    title: titleOf(info),
+    cwd,
+    active: activeOf(info),
+    last_active_at: new Date(info.lastModified).toISOString(),
+    turns: turnsOf(recent),
+    ...(withItems ? { items: recent } : {}),
+    branch: branchOf(info),
+    doing: activeOf(info) ? doingOf(items) : null,
+  }
 }
 
 /** Project folders Claude Code has been used in (that still exist), newest first. */

package/src/claude-transcript.mjs

@@ -0,0 +1,114 @@
+// A Claude Code transcript (the Agent SDK's session messages) as the conversation shows it: what was
+// said and, between the turns, the tool calls Claude made, described the way its jobs describe them
+// (agents/claude-calls.mjs). The shape is @kira/genui's claudeSessionItems.ts.
+import { describeAction, short } from './agents/claude-calls.mjs'
+
+/** How much of an edit, a write or a command a call carries for its detail. */
+const DETAIL_CAP = 1500
+
+function textOf(message) {
+  const c = message?.content
+  if (typeof c === 'string') return c
+  if (Array.isArray(c)) return c.filter(b => b?.type === 'text').map(b => b.text).join('\n')
+  return ''
+}
+
+/** An edit's lines: the old and new text without the lines they share at the start and the end. */
+function diffCounts(old, now) {
+  const a = String(old ?? '').split('\n')
+  const b = String(now ?? '').split('\n')
+  let start = 0
+  while (start < a.length && start < b.length && a[start] === b[start]) start++
+  let end = 0
+  while (end < a.length - start && end < b.length - start && a[a.length - 1 - end] === b[b.length - 1 - end]) end++
+  return { adds: b.length - start - end, dels: a.length - start - end }
+}
+
+/** Lines an edit or a write adds and takes out; null for any other call. */
+export function lineCounts(name, input) {
+  const i = input ?? {}
+  if (name === 'Write') return { adds: i.content ? String(i.content).split('\n').length : 0, dels: 0 }
+  if (name === 'Edit') return diffCounts(i.old_string, i.new_string)
+  if (name !== 'MultiEdit') return null
+  const each = (i.edits ?? []).map(e => diffCounts(e.old_string, e.new_string))
+  return { adds: each.reduce((n, c) => n + c.adds, 0), dels: each.reduce((n, c) => n + c.dels, 0) }
+}
+
+/**
+ * A change's detail, shorter than a job's: the conversation polls it every few seconds. A command
+ * has none (its target is the command).
+ */
+function shortDetail(d) {
+  const cut = e => ({ ...e, old: short(e.old, DETAIL_CAP), new: short(e.new, DETAIL_CAP) })
+  if (d.edit) return { edit: cut(d.edit) }
+  if (d.edits) return { edits: d.edits.slice(0, 5).map(cut) }
+  return d.content !== undefined ? { content: short(d.content, DETAIL_CAP) } : undefined
+}
+
+/** One tool_use block as a call. */
+function toolCall(block, cwd) {
+  const act = describeAction(block.name, block.input, cwd)
+  const detail = act.detail ? shortDetail(act.detail) : undefined
+  return {
+    id: block.id,
+    type: act.type,
+    label: act.label,
+    target: act.target,
+    ...(lineCounts(block.name, block.input) ?? {}),
+    ...(detail ? { detail } : {}),
+  }
+}
+
+/**
+ * Everything said and done, in order: the user's and Claude's turns, and each run of tool calls
+ * between them as one item. Subagents' own messages and system blocks (text starting "<") are left out.
+ */
+export function itemsOf(messages, cwd) {
+  const items = []
+  const calls = new Map()
+  let group = null
+  const say = (role, text, at) => {
+    group = null
+    if (text && !text.startsWith('<')) items.push({ kind: 'turn', role, text, at })
+  }
+  for (const m of messages) {
+    if (m.parent_tool_use_id) continue
+    const at = m.timestamp ?? null
+    const content = Array.isArray(m.message?.content) ? m.message.content : []
+    if (m.type === 'assistant') {
+      for (const b of content) {
+        if (b?.type === 'text') say('claude', String(b.text ?? '').trim(), at)
+        if (b?.type !== 'tool_use') continue
+        if (!group) items.push((group = { kind: 'tools', at, calls: [] }))
+        const call = toolCall(b, cwd)
+        calls.set(call.id, call)
+        group.calls.push(call)
+      }
+    } else if (m.type === 'user') {
+      for (const b of content) {
+        if (b?.type === 'tool_result' && b.is_error && calls.has(b.tool_use_id)) calls.get(b.tool_use_id).failed = true
+      }
+      const text = textOf(m.message).trim()
+      if (text) say('user', text, at)
+    }
+  }
+  return items
+}
+
+/** Just the turns (what read_claude_session has always returned). */
+export const turnsOf = items => items.filter(i => i.kind === 'turn').map(({ kind, ...turn }) => turn)
+
+/** The last `n` turns and the tool calls among and after them. */
+export function lastTurns(items, n) {
+  let seen = 0
+  for (let i = items.length - 1; i >= 0; i--) if (items[i].kind === 'turn' && ++seen === n) return items.slice(i)
+  return items
+}
+
+/** The last call when nothing was said after it: what the session is doing (or did last). */
+export function doingOf(items) {
+  const last = items.at(-1)
+  if (last?.kind !== 'tools') return null
+  const { detail, ...call } = last.calls.at(-1)
+  return call
+}

package/src/cli.mjs

@@ -4,14 +4,11 @@
 //   npx kira-glasses-bridge --token <token>     save the token and install the background service
 //   kira-bridge run                              run in the foreground (what the service runs)
 //   kira-bridge install | uninstall | status | logs
-import { createRequire } from 'node:module'
 import { spawnSync } from 'node:child_process'
 import { resolve as resolveConfig, writeConfig, readConfig, configExists, LOG_PATH, DEFAULT_URL } from './config.mjs'
 import { install, uninstall, status } from './service.mjs'
 import { startBridge } from './index.mjs'
-
-const require = createRequire(import.meta.url)
-const { version } = require('../package.json')
+import { BRIDGE_VERSION as version } from './version.mjs'
 
 const args = process.argv.slice(2)
 const flags = {}
@@ -68,7 +65,9 @@ async function main() {
     case 'run':
       return startBridge(resolveConfig(flags))
     case 'install': {
-      if (!resolveConfig(flags).token) throw new Error('no token saved yet; run: npx kira-glasses-bridge --token <token>')
+      if (!resolveConfig(flags).token) {
+        throw new Error('no token saved yet; run: npx kira-glasses-bridge --token <token>')
+      }
       const r = install()
       console.log(`Installed and started (${r.plist}). Log: ${r.log}`)
       return
@@ -81,8 +80,13 @@ async function main() {
       const c = resolveConfig(flags)
       console.log(`token:   ${c.token ? 'saved' : 'missing'}`)
       console.log(`server:  ${c.url}`)
-      if (!s.installed) console.log('service: not installed (run `kira-bridge install`, or `kira-bridge run` for the foreground)')
-      else console.log(`service: ${s.running ? 'running' : 'installed but not running'}\nlog:     ${s.log}${s.lastLog ? '\n\n' + s.lastLog : ''}`)
+      if (!s.installed) {
+        console.log('service: not installed (run `kira-bridge install`, or `kira-bridge run` for the foreground)')
+        return
+      }
+      console.log(`service: ${s.running ? 'running' : 'installed but not running'}`)
+      console.log(`log:     ${s.log}`)
+      if (s.lastLog) console.log(`\n${s.lastLog}`)
       return
     }
     case 'logs':

package/src/index.mjs

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
 // Kira bridge. Connects outbound to the Kira API and runs tools on this
 // machine on the user's behalf. Env: KIRA_BRIDGE_URL, KIRA_BRIDGE_TOKEN.
-import { createRequire } from 'node:module'
 import { agentTools } from './agent-files.mjs'
 import { appolloBridgeTools } from './appollo/index.mjs'
 import { AGENTS } from './agents/index.mjs'
@@ -15,9 +14,10 @@ import { jobTools, runningJobIds } from './job-tools.mjs'
 import { macTools } from './mac-tools.mjs'
 import { sessionTools } from './session-tools.mjs'
 import { skillTools } from './skill-files.mjs'
+import { closeAll as closeMcpServers } from './mcp/servers.mjs'
+import { mcpTools } from './mcp/tools.mjs'
 import { initTerminals } from './terminals.mjs'
-
-const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
+import { BRIDGE_VERSION } from './version.mjs'
 
 const tools = {
   ...fileTools,
@@ -30,6 +30,7 @@ const tools = {
   ...skillTools,
   ...agentTools,
   ...appolloBridgeTools,
+  ...mcpTools,
 }
 
 /** What this bridge build implements, told to the API after its hello. */
@@ -61,6 +62,7 @@ export function startBridge(config, hostHooks = {}) {
 /** Disconnect and stop reconnecting (the app calls this on sign-out or a token change). */
 export function stopBridge() {
   disconnect()
+  closeMcpServers()
 }
 
 export const bridgeVersion = BRIDGE_VERSION

package/src/mcp/launch.mjs

@@ -0,0 +1,61 @@
+// How a local MCP server is launched: its arguments checked, its command found, the environment it
+// gets and the key its warm process is kept under. Pure, so the decisions are tested (mcp-launch.test).
+import { createHash } from 'node:crypto'
+import { delimiter, isAbsolute, join } from 'node:path'
+
+/** Where installers put command-line tools; launchd gives the bridge a PATH without most of them. */
+const INSTALL_DIRS = ['.cargo/bin', '.local/bin']
+const SYSTEM_DIRS = ['/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin']
+
+/** `{ server: { command, args }, env }` from a tool call, or a plain-English error. */
+export function parseServerArgs(args) {
+  const server = args?.server
+  const command = typeof server?.command === 'string' ? server.command.trim() : ''
+  if (!command) throw new Error('server.command is required')
+  const list = server.args ?? []
+  if (!Array.isArray(list) || list.some(a => typeof a !== 'string')) {
+    throw new Error('server.args must be a list of strings')
+  }
+  const env = args.env ?? {}
+  const envOk = typeof env === 'object' && !Array.isArray(env) && Object.values(env).every(v => typeof v === 'string')
+  if (!envOk) throw new Error('env must map names to strings')
+  return { server: { command, args: list }, env }
+}
+
+/** `{ command }` from mcp_installed, or a plain-English error. */
+export function parseCommandArg(args) {
+  const command = typeof args?.command === 'string' ? args.command.trim() : ''
+  if (!command) throw new Error('command is required')
+  return command
+}
+
+/** The directories searched for a command, in order: the bridge's PATH, then the usual install places. */
+export function searchDirs(pathEnv, home) {
+  const fromPath = String(pathEnv ?? '').split(delimiter)
+  const installs = home ? INSTALL_DIRS.map(dir => join(home, dir)) : []
+  const all = [...fromPath, ...installs, ...SYSTEM_DIRS].filter(Boolean)
+  return [...new Set(all)]
+}
+
+/** The command's full path (the first executable match), or null when it isn't installed. */
+export function resolveCommand(command, dirs, isExecutable) {
+  if (command.includes('/')) return isAbsolute(command) && isExecutable(command) ? command : null
+  return dirs.map(dir => join(dir, command)).find(isExecutable) ?? null
+}
+
+/** The child's environment: a safe base plus what the caller passed, never the bridge's own secrets. */
+export function childEnv(base, passed) {
+  return { PATH: base.path, HOME: base.home, LANG: base.lang || 'en_US.UTF-8', ...passed }
+}
+
+/** The pool key: same command, args and env share a process; any change starts a fresh one. */
+export function serverKey(server, env) {
+  const entries = Object.entries(env).sort(([a], [b]) => a.localeCompare(b))
+  const identity = JSON.stringify([server.command, server.args, entries])
+  return createHash('sha256').update(identity).digest('hex')
+}
+
+/** The same server under another key (its env changed): the old process is replaced. */
+export function serverId(server) {
+  return JSON.stringify([server.command, server.args])
+}

package/src/mcp/messages.mjs

@@ -0,0 +1,49 @@
+// What a local MCP server's failures say, and when a warm one is closed. Pure (mcp-messages.test).
+// Its environment carries the person's keys, so every message passes through redact() first.
+import { basename } from 'node:path'
+
+/** Shorter values ("1", "yes") would blank out ordinary words; real secrets are longer. */
+const MIN_SECRET_LENGTH = 4
+const TAIL_LINES = 5
+
+/** The command's name as people know it ("kraken", not "/Users/…/.cargo/bin/kraken"). */
+export function commandName(command) {
+  return basename(command)
+}
+
+export function notInstalledMessage(command) {
+  return `not_installed: ${commandName(command)} isn't installed on this Mac`
+}
+
+/** `text` with every env value replaced, longest first so one secret inside another goes whole. */
+export function redact(text, env) {
+  const secrets = Object.values(env)
+    .filter(v => v.length >= MIN_SECRET_LENGTH)
+    .sort((a, b) => b.length - a.length)
+  return secrets.reduce((out, secret) => out.split(secret).join('***'), String(text))
+}
+
+/** The last few non-empty lines of what the server wrote to stderr. */
+export function lastLines(text, count = TAIL_LINES) {
+  const lines = String(text)
+    .split('\n')
+    .map(line => line.trimEnd())
+    .filter(Boolean)
+  return lines.slice(-count).join('\n')
+}
+
+/** A server that stopped or never finished its handshake: why, and what it last said. */
+export function stoppedMessage(command, { reason, stderr }, env) {
+  const tail = lastLines(stderr)
+  const said = tail ? `. It said:\n${tail}` : ''
+  return redact(`${commandName(command)} stopped (${reason})${said}`, env)
+}
+
+export function timeoutMessage(command, ms) {
+  return `${commandName(command)} didn't answer within ${Math.round(ms / 1000)}s`
+}
+
+/** The warm servers to close: no call running or waiting (`busy` counts them) and unused for `idleMs`. */
+export function idleKeys(entries, now, idleMs) {
+  return entries.filter(e => !e.busy && now - e.lastUsed >= idleMs).map(e => e.key)
+}

package/src/mcp/servers.mjs

@@ -0,0 +1,141 @@
+// Local (stdio) MCP servers, kept warm: one process per command, args and env, reached through the
+// official MCP client. Calls to one server take turns; an idle one closes, a crashed one restarts on
+// next use. What the API's broker reaches through the bridge for servers that only run locally.
+import { accessSync, constants } from 'node:fs'
+import { homedir } from 'node:os'
+import { delimiter } from 'node:path'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { log } from '../host.mjs'
+import { BRIDGE_VERSION } from '../version.mjs'
+import { childEnv, resolveCommand, searchDirs, serverId, serverKey } from './launch.mjs'
+import { commandName, idleKeys, notInstalledMessage, redact, stoppedMessage, timeoutMessage } from './messages.mjs'
+
+/** Under the API's 25-second wait for a bridge call, so the person hears why rather than a timeout. */
+const CALL_TIMEOUT_MS = 20_000
+const IDLE_MS = 5 * 60_000
+const SWEEP_MS = 60_000
+const STDERR_KEEP = 4000
+const TIMEOUT_CODE = -32001
+
+const pool = new Map()
+let sweeper = null
+
+/** Where this Mac has `command` (null when it doesn't), and the directories that were searched. */
+export function locate(command) {
+  const dirs = searchDirs(process.env.PATH, homedir())
+  return { path: resolveCommand(command, dirs, isExecutable), dirs }
+}
+
+function isExecutable(file) {
+  try {
+    accessSync(file, constants.X_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Run `work(client, options)` on the server's warm process, after any call already waiting on it. */
+export function withServer(server, env, work) {
+  const entry = acquire(server, env)
+  // Counts calls waiting as well as running, so a server with work queued is never closed under it.
+  entry.busy++
+  const run = entry.queue.then(() => use(entry, work))
+  entry.queue = run.catch(() => {})
+  return run
+}
+
+/** Close every server (the bridge is stopping). */
+export function closeAll() {
+  for (const entry of [...pool.values()]) close(entry, 'bridge stopped')
+}
+
+async function use(entry, work) {
+  try {
+    await entry.ready
+    return await work(entry.client, { timeout: CALL_TIMEOUT_MS })
+  } catch (err) {
+    throw failure(entry, err)
+  } finally {
+    entry.busy--
+    entry.lastUsed = Date.now()
+  }
+}
+
+/** A stopped or wedged server is dropped (the next call starts it again); a refused call is just reported. */
+function failure(entry, err) {
+  const { command, env } = entry
+  if (err?.code === TIMEOUT_CODE) {
+    close(entry, 'timed out')
+    return new Error(timeoutMessage(command, CALL_TIMEOUT_MS))
+  }
+  if (entry.closed || !entry.connected) {
+    // "Connection closed" is the SDK's way of saying the process ended; anything else is its own reason.
+    const reason = entry.closed ? 'it exited' : (err?.message ?? 'it failed to start')
+    close(entry, 'failed')
+    return new Error(stoppedMessage(command, { reason, stderr: entry.stderr }, env))
+  }
+  return new Error(redact(err?.message ?? String(err), env))
+}
+
+function acquire(server, env) {
+  const key = serverKey(server, env)
+  const warm = pool.get(key)
+  if (warm && !warm.closed) return warm
+  const { path: command, dirs } = locate(server.command)
+  if (!command) throw new Error(notInstalledMessage(server.command))
+  replaceOlder(server)
+  const entry = start(key, server, command, childEnv({ path: dirs.join(delimiter), home: homedir() }, env), env)
+  pool.set(key, entry)
+  sweeper ??= setInterval(sweep, SWEEP_MS).unref()
+  return entry
+}
+
+/** The same server under an old env (a key was changed): closed unless it's mid-call (then it idles out). */
+function replaceOlder(server) {
+  const id = serverId(server)
+  for (const entry of pool.values()) if (entry.id === id && !entry.busy) close(entry, 'replaced')
+}
+
+function start(key, server, command, childEnvironment, env) {
+  // The SDK adds a few harmless variables of its own (USER, SHELL, TERM); nothing else of the bridge's.
+  const transport = new StdioClientTransport({ command, args: server.args, env: childEnvironment, stderr: 'pipe' })
+  const client = new Client({ name: 'kira-bridge', version: BRIDGE_VERSION })
+  const entry = { key, id: serverId(server), command, env, client, stderr: '', busy: 0, lastUsed: Date.now() }
+  entry.queue = Promise.resolve()
+  entry.closed = false
+  entry.connected = false
+  transport.stderr?.on('data', chunk => {
+    entry.stderr = (entry.stderr + chunk).slice(-STDERR_KEEP)
+  })
+  client.onclose = () => {
+    if (!entry.closed) log(`local MCP ${commandName(command)} exited`)
+    forget(entry)
+  }
+  entry.ready = client.connect(transport, { timeout: CALL_TIMEOUT_MS }).then(() => {
+    entry.connected = true
+  })
+  entry.ready.catch(() => {}) // a failed start is reported to the call waiting on it
+  log(`local MCP ${commandName(command)} started`)
+  return entry
+}
+
+function close(entry, why) {
+  if (entry.closed) return
+  log(`local MCP ${commandName(entry.command)} closed (${why})`)
+  forget(entry)
+  entry.client.close().catch(() => {})
+}
+
+function forget(entry) {
+  entry.closed = true
+  if (pool.get(entry.key) === entry) pool.delete(entry.key)
+  if (pool.size || !sweeper) return
+  clearInterval(sweeper)
+  sweeper = null
+}
+
+function sweep() {
+  for (const key of idleKeys([...pool.values()], Date.now(), IDLE_MS)) close(pool.get(key), 'idle')
+}

package/src/mcp/tools.mjs

@@ -0,0 +1,53 @@
+// The bridge's tools for local MCP servers: whether one is installed (mcp_installed), what it offers
+// (mcp_list) and calling one of its tools (mcp_call). Results are the server's own MCP shapes; Kira's
+// broker reads them as it would a hosted one's.
+import { parseCommandArg, parseServerArgs } from './launch.mjs'
+import { locate, withServer } from './servers.mjs'
+
+/** Every page of the server's tools, as the API needs them. */
+async function allTools(client, options) {
+  const tools = []
+  let cursor
+  do {
+    const page = await client.listTools(cursor ? { cursor } : undefined, options)
+    tools.push(
+      ...page.tools.map(({ name, description, inputSchema, annotations }) => ({
+        name,
+        description,
+        inputSchema,
+        annotations,
+      })),
+    )
+    cursor = page.nextCursor
+  } while (cursor)
+  return tools
+}
+
+export const mcpTools = {
+  /** `{ command }` → `{ installed, path? }`: found the way mcp_list and mcp_call find it, nothing started. */
+  async mcp_installed(args) {
+    const { path } = locate(parseCommandArg(args))
+    return path ? { installed: true, path } : { installed: false }
+  },
+
+  /** `{ server: { command, args }, env }` → `{ tools, instructions? }`. */
+  async mcp_list(args) {
+    const { server, env } = parseServerArgs(args)
+    return withServer(server, env, async (client, options) => {
+      const tools = await allTools(client, options)
+      const instructions = client.getInstructions()
+      return instructions ? { tools, instructions } : { tools }
+    })
+  },
+
+  /** `{ server, env, tool, arguments }` → the server's CallToolResult, as it returned it. */
+  async mcp_call(args) {
+    const { server, env } = parseServerArgs(args)
+    const name = typeof args.tool === 'string' ? args.tool : ''
+    if (!name) throw new Error('tool is required')
+    const toolArgs = args.arguments ?? {}
+    return withServer(server, env, (client, options) =>
+      client.callTool({ name, arguments: toolArgs }, undefined, options),
+    )
+  },
+}

package/src/session-tools.mjs

@@ -15,6 +15,6 @@ export const sessionTools = {
     return listSessions(args.max)
   },
   async read_claude_session(args) {
-    return readSession(String(args.session_id ?? ''), args.turns)
+    return readSession(String(args.session_id ?? ''), args.turns, { items: args.items === true })
   },
 }

package/src/version.mjs

@@ -0,0 +1,4 @@
+// This bridge build's version (from its package.json), for the API, the CLI and the MCP servers it starts.
+import { createRequire } from 'node:module'
+
+export const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')