kira-glasses-bridge 2.32.0 → 2.35.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.32.0",
+  "version": "2.35.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/agents/claude-calls.mjs

@@ -58,6 +58,7 @@ export function describeAction(name, input, cwd) {
       return act('fetch', 'Fetch', short(i.url, 200))
     case 'WebSearch':
       return act('fetch', 'Search the web', short(i.query, 160))
+    case 'Agent':
     case 'Task':
       return act('delegate', 'Subtask', short(i.description ?? i.prompt, 160))
     case 'TodoWrite':

package/src/agents/claude.mjs

@@ -15,6 +15,8 @@ import { planLimits } from './claude-local.mjs'
 import { contextFrom, limitsFromEvent, rejectedWindow, stoppedBy } from './claude-usage.mjs'
 import { sdkOptionsFor } from './settings.mjs'
 import { kiraPluginOptions } from '../kira-plugin.mjs'
+import { git } from '../git.mjs'
+import { isAgentCall, subagentFeed } from './subagents.mjs'
 
 /** Kira's MCP server as Claude Code connects to it: Streamable HTTP, the token as the bearer. */
 const kiraServer = ({ url, token }) => ({ type: 'http', url, headers: { Authorization: `Bearer ${token}` } })
@@ -100,6 +102,9 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   const env = { ...process.env, CLAUDE_CODE_DISABLE_BACKGROUND_TASKS: '1', ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
   /** Background tasks the model still managed to start (an older CLI ignoring the flag): tool_use id -> description. */
   const orphans = new Map()
+  /** The agents it starts, each with where it works (subagents.mjs). */
+  const branchOf = async path => (await git(path, ['branch', '--show-current']))?.trim() || null
+  const agents = subagentFeed(e => io.emit(e), branchOf)
 
   try {
     const q = query({
@@ -144,6 +149,9 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
         if (m.is_backgrounded && m.tool_use_id) orphans.set(m.tool_use_id, m.description ?? m.subagent_type ?? 'task')
       } else if (m.type === 'system' && m.subtype === 'task_notification') {
         if (m.tool_use_id) orphans.delete(m.tool_use_id)
+        if (m.tool_use_id) agents.ended(m.tool_use_id, m.status, m.summary)
+      } else if (m.type === 'system' && m.subtype === 'task_progress') {
+        if (m.tool_use_id) agents.progress(m.tool_use_id, m.summary)
       } else if (m.type === 'assistant') {
         // A new turn of the main thread: how full the context is now, as /context counts it (no model call).
         if (!nested && m.message?.id && m.message.id !== turn) {
@@ -153,7 +161,13 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
         for (const b of m.message?.content ?? []) {
           // A subagent's narration is for its parent, not the user; its actions still show what is going on while the Subtask runs.
           if (b.type === 'text' && b.text?.trim() && !nested) 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 (b.type === 'tool_use') {
+            // A step inside an agent says whose it is.
+            const whose = nested ? { agent: m.parent_tool_use_id } : {}
+            io.emit({ kind: 'action', id: b.id, tool: b.name, ...describeAction(b.name, b.input, cwd), ...whose })
+            if (isAgentCall(b.name)) agents.called(b.id, b.input, m.parent_tool_use_id)
+            if (nested) agents.touched(m.parent_tool_use_id, b.input)
+          }
         }
       } else if (m.type === 'user') {
         for (const b of m.message?.content ?? []) {
@@ -161,10 +175,12 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
             const t = typeof b.content === 'string' ? b.content : Array.isArray(b.content) ? b.content.map(c => (c.type === 'text' ? c.text : '')).join('\n') : ''
             if (/^Async agent launched successfully/.test(t.trim()) && !orphans.has(b.tool_use_id)) orphans.set(b.tool_use_id, 'subagent')
             io.emit({ kind: 'action_result', id: b.tool_use_id, ok: !b.is_error, preview: short(t.trim(), 240) })
+            if (agents.has(b.tool_use_id)) agents.returned(b.tool_use_id, m.tool_use_result, b.is_error)
           }
         }
       } else if (m.type === 'result') {
         session = m.session_id ?? session
+        agents.stopAll()
         // A turn that ended on an API error (a usage limit among them) is a success carrying the error.
         const limit = { limits: usage.known, rejected, limitPrefixes: USAGE_LIMIT_ERROR_PREFIXES }
         if (m.subtype === 'success' && !m.is_error) text = String(m.result ?? '')

package/src/agents/codex-items.mjs

@@ -79,6 +79,8 @@ export function itemAction(item, cwd) {
     case 'plan':
       return act('plan', 'Plan', short(item.text, 160), { tool: 'Plan' })
     case 'collabAgentToolCall':
+      // Spawning one is a step; waiting on or messaging its agents moves the agent's row (codex-subagents.mjs).
+      if (item.tool !== 'spawnAgent') return null
       return act('delegate', 'Subtask', short(item.prompt ?? '', 160), { tool: 'Subtask' })
     case 'enteredReviewMode':
       return act('read', 'Review', short(item.review ?? '', 160), { tool: 'Review' })

package/src/agents/codex-subagents.mjs

@@ -0,0 +1,60 @@
+// The agents Codex spawns inside a turn (its collab tools), as protocol `agent` events, the way
+// subagents.mjs does Claude Code's. A spawn is a collabAgentToolCall naming the new agent's thread;
+// that thread's items then arrive on the same app server, so each one says whose it is (`whose`), and
+// later collab calls and subAgentActivity items say how each agent stands. Codex's agents work in the
+// turn's own folder.
+import { short } from './claude-calls.mjs'
+
+const STATES = {
+  completed: 'done',
+  errored: 'failed',
+  interrupted: 'stopped',
+  shutdown: 'stopped',
+  notFound: 'stopped',
+}
+const ACTIVITY = { completed: 'done', interrupted: 'stopped' }
+
+/** The last part of an agent's path ("/root/explorer" → "explorer"): the name Codex gave it. */
+const nameOf = path => String(path ?? '').split('/').filter(Boolean).pop() || null
+
+export function codexAgentFeed(emit) {
+  const agents = new Map()
+  /** Each agent's thread, to the spawn call that made it. */
+  const threads = new Map()
+  const send = a => {
+    agents.set(a.id, a)
+    emit(a)
+  }
+  const settle = (threadId, status, name) => {
+    const a = agents.get(threads.get(threadId))
+    if (!a) return
+    const named = name && !a.name ? { name } : {}
+    if (status && a.status === 'running') send({ ...a, status, ...named })
+    else if (named.name) send({ ...a, ...named })
+  }
+  return {
+    /** The agent a thread's items belong to, if the thread is one Codex spawned. */
+    whose: threadId => threads.get(threadId) ?? null,
+    started(item) {
+      if (item.type !== 'collabAgentToolCall' || item.tool !== 'spawnAgent') return
+      const description = short(item.prompt ?? '', 200)
+      send({ kind: 'agent', id: item.id, type: 'agent', description, status: 'running' })
+    },
+    completed(item) {
+      if (item.type === 'subAgentActivity') {
+        return settle(item.agentThreadId, ACTIVITY[item.kind], nameOf(item.agentPath))
+      }
+      if (item.type !== 'collabAgentToolCall') return
+      if (item.tool === 'spawnAgent') {
+        for (const t of item.receiverThreadIds ?? []) threads.set(t, item.id)
+        const a = agents.get(item.id)
+        if (a && item.status === 'failed') send({ ...a, status: 'failed' })
+      }
+      for (const [t, state] of Object.entries(item.agentsStates ?? {})) settle(t, STATES[state?.status])
+    },
+    /** The turn ended: what still runs ended with it (`status`: done, or stopped when it was cut short). */
+    endAll(status) {
+      for (const a of agents.values()) if (a.status === 'running') send({ ...a, status })
+    },
+  }
+}

package/src/agents/codex.mjs

@@ -9,6 +9,7 @@ import { codexBin, openCodex } from './codex-rpc.mjs'
 import { codexInput } from './codex-input.mjs'
 import { turnSteering } from './codex-steer.mjs'
 import { codexStream } from './codex-live.mjs'
+import { codexAgentFeed } from './codex-subagents.mjs'
 import { liveEmitter } from './live.mjs'
 import { kiraDecides } from './checks.mjs'
 import { CODEX_ASKS, askPerson, refusedByPolicy, said } from './codex-ask.mjs'
@@ -51,6 +52,8 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
   /** What is still being written (live.mjs): sent as it comes, the final form of each kept. */
   const live = liveEmitter(io.emit)
   const stream = codexStream()
+  /** The agents it spawns, and which thread is whose (codex-subagents.mjs). */
+  const agents = codexAgentFeed(e => io.emit(e))
   let finished
   const ended = new Promise(resolve => (finished = resolve))
   // What the person says while a turn runs goes into it (`codex` is the app server, opened below).
@@ -86,16 +89,22 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
   }
 
   const onNotify = (method, p) => {
+    // An item from a thread Codex spawned is its agent's: its steps say so, and what it says is for Codex.
+    const whose = p?.threadId ? agents.whose(p.threadId) : null
     const update = stream.update(method, p)
-    if (update) return live.update(update)
+    if (update) return whose ? undefined : live.update(update)
     if (method === 'item/started') {
       if (p.item.type === 'fileChange') changes.set(p.item.id, p.item.changes ?? [])
+      agents.started(p.item)
       const action = itemAction(p.item, cwd)
-      if (action) io.emit({ kind: 'action', id: p.item.id, ...action })
+      if (action) io.emit({ kind: 'action', id: p.item.id, ...action, ...(whose ? { agent: whose } : {}) })
     } else if (method === 'item/completed') {
+      agents.completed(p.item)
       const reviewed = review.completed(p.item)
       if (reviewed) io.emit(reviewed)
-      if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
+      if (whose && p.item.type === 'agentMessage') {
+        // Its agent's answer goes to Codex, not the person.
+      } else if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
         text = p.item.text
         if (!review.repeats(text)) live.final({ kind: 'message', id: p.item.id, text: short(p.item.text, TEXT_CAP) })
       } else if (itemAction(p.item, cwd)) {
@@ -117,6 +126,7 @@ async function run({ prompt, attachments, sessionId, cwd, persona, settings, abo
       steering.ended()
       if (t.status === 'failed') error = usage.stopped(stoppedBy(t.error ?? { message: 'failed' }, usage.limits))
       if (t.status === 'interrupted') error = 'Stopped by the user.'
+      agents.endAll(t.status === 'completed' ? 'done' : 'stopped')
       finished({ durationMs: t.durationMs ?? undefined })
     }
   }

package/src/agents/protocol.mjs

@@ -10,7 +10,13 @@
 //   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 }
+//                      agent: the id of the agent (below) whose step it is, when an agent the turn started took it
 //   action_result    { kind, id, ok, preview? }
+//   agent            { kind, id, type, description, status, name?, isolated?, background?, summary?,
+//                      worktree?: { path, branch? }, stats?: { tools?, ms?, adds?, dels? }, agent? }
+//                      an agent the turn started (Claude Code's Agent tool, Codex's spawnAgent), sent again whole
+//                      each time it changes; status: running | done | failed | stopped; worktree: its own, when it
+//                      has one (subagents.mjs, codex-subagents.mjs)
 //   request          { kind, request: AgentRequest }        needs a person; the job waits
 //   request_resolved { kind, id, answer, by }              by: voice | lens | phone | portal | timeout | policy
 //   usage            { kind, context: {used,window} | null, limits: AgentLimits | null }   how full the thread

package/src/agents/subagents.mjs

@@ -0,0 +1,121 @@
+// The agents Claude Code starts inside a turn (its Agent tool, once called Task), as protocol `agent`
+// events: what kind each is, what it was asked, how it's going, and where it works: the job's folder,
+// or a worktree of its own (`isolation: "worktree"`, under <repo>/.claude/worktrees/<name>). Its own
+// steps carry its id as `agent` (claude.mjs); the worktree shows up in the first path one of them
+// touches, and the finished call names it too. Each change of an agent is the whole event again, so
+// the last one with an id is where it stands.
+import { display } from '../git.mjs'
+
+/** Claude Code's tool for starting an agent, by its current name and its old one. */
+export const isAgentCall = name => name === 'Agent' || name === 'Task'
+
+const WORKTREE = /^(.*\/\.claude\/worktrees\/[^/]+)(?:\/|$)/
+
+/** The agent worktree a path is inside, if any. */
+export function worktreeOf(path) {
+  const m = WORKTREE.exec(String(path ?? ''))
+  return m ? m[1] : null
+}
+
+/** Every absolute path a tool call names, for finding where an agent works. */
+export function pathsIn(input) {
+  const i = input ?? {}
+  const named = [i.file_path, i.notebook_path, i.path].filter(p => typeof p === 'string')
+  const cd = /(?:^|&&|;)\s*cd\s+("[^"]+"|'[^']+'|\S+)/.exec(String(i.command ?? ''))
+  if (cd) named.push(cd[1].replace(/^["']|["']$/g, ''))
+  return named.filter(p => p.startsWith('/'))
+}
+
+/** An Agent call as the agent it starts. */
+export function agentFrom(id, input, parent) {
+  const i = input ?? {}
+  return {
+    kind: 'agent',
+    id,
+    type: String(i.subagent_type || 'general-purpose'),
+    description: String(i.description || i.prompt || '').slice(0, 200),
+    status: 'running',
+    ...(i.name ? { name: String(i.name) } : {}),
+    ...(i.isolation === 'worktree' ? { isolated: true } : {}),
+    ...(parent ? { agent: parent } : {}),
+  }
+}
+
+/** A finished Agent call's result (the SDK's tool_use_result): how it went, where, and what it did. */
+export function finished(agent, result, failed) {
+  const r = result && typeof result === 'object' ? result : {}
+  if (r.status === 'async_launched') return { ...agent, background: true }
+  const s = r.toolStats
+  const stats = {
+    ...(typeof r.totalToolUseCount === 'number' ? { tools: r.totalToolUseCount } : {}),
+    ...(typeof r.totalDurationMs === 'number' ? { ms: r.totalDurationMs } : {}),
+    ...(s ? { adds: s.linesAdded ?? 0, dels: s.linesRemoved ?? 0 } : {}),
+  }
+  // Claude Code removes an agent's worktree when it changed nothing, and then doesn't name it.
+  const removed = r.status === 'completed' && agent.isolated
+  const worktree = r.worktreePath
+    ? { path: display(r.worktreePath), ...(r.worktreeBranch ? { branch: r.worktreeBranch } : {}) }
+    : removed
+      ? null
+      : agent.worktree
+  const { worktree: _, ...rest } = agent
+  return {
+    ...rest,
+    status: failed ? 'failed' : 'done',
+    ...(worktree ? { worktree } : {}),
+    ...(Object.keys(stats).length ? { stats } : {}),
+  }
+}
+
+const ENDED = { completed: 'done', failed: 'failed', stopped: 'stopped' }
+
+/**
+ * A turn's agents as they go. `emit` sends each change; `branchOf(path)` reads a worktree's branch
+ * (git, or a stand-in in tests).
+ */
+export function subagentFeed(emit, branchOf) {
+  const agents = new Map()
+  const send = (a, more = {}) => {
+    agents.set(a.id, a)
+    emit({ ...a, ...more })
+  }
+  return {
+    has: id => agents.has(id),
+    /** The Agent call: it starts. */
+    called(id, input, parent) {
+      send(agentFrom(id, input, parent))
+    },
+    /** One of its own calls: the first path inside a worktree says which one it works in. */
+    touched(id, input) {
+      const a = agents.get(id)
+      if (!a || a.worktree) return
+      const path = pathsIn(input).map(worktreeOf).find(Boolean)
+      if (!path) return
+      send({ ...a, worktree: { path: display(path) } })
+      void Promise.resolve(branchOf(path)).then(branch => {
+        const now = agents.get(id)
+        if (branch && now?.worktree && !now.worktree.branch) send({ ...now, worktree: { ...now.worktree, branch } })
+      })
+    },
+    /** A one-line summary of where it's at, while it works: shown live, never stored. */
+    progress(id, summary) {
+      const a = agents.get(id)
+      if (a && summary) emit({ ...a, summary: String(summary).slice(0, 200), transient: true })
+    },
+    /** Its call's result: done, or still going in the background. */
+    returned(id, result, failed) {
+      const a = agents.get(id)
+      if (a) send(finished(a, result, failed))
+    },
+    /** A background agent ended (task_notification). */
+    ended(id, status, summary) {
+      const a = agents.get(id)
+      if (a?.status !== 'running') return
+      send({ ...a, status: ENDED[status] ?? 'done', ...(summary ? { summary: String(summary).slice(0, 200) } : {}) })
+    },
+    /** The turn ended: whatever still runs stops with it. */
+    stopAll() {
+      for (const a of agents.values()) if (a.status === 'running') send({ ...a, status: 'stopped' })
+    },
+  }
+}

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/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')