kira-glasses-bridge 2.21.0 → 2.23.0

package/package.json

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

@@ -28,7 +28,7 @@ const inside = (cwd, p) => {
 const kiraServer = ({ url, token }) => ({ type: 'http', url, headers: { Authorization: `Bearer ${token}` } })
 
 /** Claude's tool call as a protocol action. */
-export function describeAction(name, input, cwd) {
+function describeAction(name, input, cwd) {
   const i = input ?? {}
   switch (name) {
     case 'Read':
@@ -137,7 +137,7 @@ function applyAnswer(name, input, request, answer, suggestions) {
 /** "Always allow" answers, kept for the rest of the process per session: sessionId -> Set of rules. */
 const sessionRules = new Map()
 
-export async function run({ prompt, sessionId, cwd, policy, persona, settings, abort }, io) {
+async function run({ prompt, sessionId, cwd, policy, persona, settings, abort }, io) {
   let session = sessionId ?? null
   let text = ''
   let error = null

package/src/agents/policy.mjs

@@ -6,12 +6,15 @@
 // Shell commands are split into their pieces (`;`, `&&`, `||`, `|`, newlines)
 // and every piece has to be safe for the whole command to be safe.
 import { relative, resolve, sep } from 'node:path'
+import { pieces, ruleFor, shellIsSafe } from './shell.mjs'
+
+export { ruleFor }
 
 /**
  * Tools that only look, or that are Claude Code's own housekeeping (ToolSearch loads the definitions
  * of tools it has but hasn't used yet; the MCP resource tools read what a server offers).
  */
-export const READ_ONLY = new Set([
+const READ_ONLY = new Set([
   'Read',
   'Glob',
   'Grep',
@@ -26,76 +29,10 @@ export const READ_ONLY = new Set([
 ])
 /** A subagent: older Claude Code calls the tool Task, newer Agent. */
 const DELEGATE = new Set(['Task', 'Agent'])
-export const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
-export const WEB = new Set(['WebFetch', 'WebSearch'])
+const EDITS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+const WEB = new Set(['WebFetch', 'WebSearch'])
 /** Claude Code's name for the tools of Kira's MCP server (mcp__<server>__<tool>). */
-export const KIRA_TOOLS = 'mcp__kira__'
-
-/**
- * Read-only commands: looking, listing, testing, type-checking, building. Nothing that writes, sends
- * or installs, nothing that runs code given inline (node -e, python -c, awk), nothing that prints
- * secrets (heroku config).
- */
-/** Plain commands that only look. */
-const LOOKERS = [
-  'ls', 'll', 'pwd', 'cat', 'head', 'tail', 'wc', 'echo', 'printf', 'which', 'type', 'env', 'printenv',
-  'date', 'whoami', 'id', 'uname', 'tree', 'find', 'fd', 'grep', 'rg', 'ag', 'cut', 'tr', 'sort', 'uniq',
-  'diff', 'comm', 'stat', 'file', 'du', 'df', 'basename', 'dirname', 'realpath', 'readlink', 'jq', 'yq',
-  'xxd', 'hexdump', 'strings', 'test', '[', 'true', 'false', 'sleep', 'md5', 'shasum', 'sha256sum',
-  'md5sum', 'column', 'nl', 'less', 'more', 'tsc', 'eslint', 'jest', 'vitest', 'pytest',
-]
-/** Tools with their read-only, test and build subcommands. */
-const SUBCOMMANDS = {
-  git: [
-    'status', 'diff', 'log', 'show', 'branch', 'rev-parse', 'remote', 'ls-files', 'ls-tree', 'blame', 'describe',
-    'stash list', 'tag', 'config --get', 'config -l', 'cat-file', 'grep', 'shortlog', 'count-objects', 'reflog',
-  ],
-  node: ['-v', '--version'],
-  npm: ['-v', '--version', 'ls', 'list', 'view', 'outdated', 'why', 'test', 'run test', 'run lint', 'run typecheck',
-    'run check', 'run build', 'run format:check'],
-  pnpm: ['-v', '--version', 'ls', 'list', 'why', 'outdated', 'test', 'typecheck', 'lint', 'build', 'run test',
-    'run lint', 'run typecheck', 'run check', 'run build'],
-  yarn: ['-v', '--version', 'list', 'test', 'lint', 'typecheck', 'build'],
-  npx: ['tsc', 'eslint', 'prettier --check', 'jest', 'vitest', 'playwright test'],
-  prettier: ['--check'],
-  cargo: ['check', 'test', 'build', 'fmt --check', 'clippy', 'tree', 'metadata'],
-  go: ['test', 'build', 'vet', 'version', 'list', 'env'],
-  python: ['-V', '--version', '-m pytest'],
-  python3: ['-V', '--version', '-m pytest'],
-  ruby: ['-v'],
-  make: ['test', 'check', 'lint', 'build'],
-  mvn: ['test', 'compile'],
-  gradle: ['test', 'build'],
-  swift: ['build', 'test'],
-  xcodebuild: ['-list'],
-  brew: ['list', 'info', '--version'],
-  docker: ['ps', 'images', 'version'],
-  gh: ['pr list', 'pr view', 'pr status', 'pr checks', 'issue list', 'issue view', 'run list', 'run view', 'repo view'],
-  heroku: ['logs', 'ps', 'releases', 'apps', 'info'],
-  open: ['-n --args'],
-  sed: ['-n', '-E -n', '-n -E'],
-}
-const escape = w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
-const withSubs = Object.entries(SUBCOMMANDS).flatMap(([tool, subs]) => subs.map(sub => `${tool} ${sub}`))
-const SAFE_PHRASES = [...LOOKERS, ...withSubs]
-const SAFE_CMD = new RegExp(`^(?:${SAFE_PHRASES.map(escape).join('|')})(?:\\s|$)`)
-
-/** Redirections that write somewhere other than nowhere. */
-const WRITES = /(^|[^&\d])>(?!&)|>>|\btee\b|\bxargs\b|\beval\b|\bexec\b|`/
-/** find and fd can run or delete what they find: then they aren't looking any more. */
-const FINDER_ACTS =
-  /^(?:find|fd)\b.*\s(?:-exec(?:dir)?|-ok(?:dir)?|-delete|-fprint\w*|-fls|-x|--exec(?:-batch)?|-X)\b/
-
-function pieces(command) {
-  // Strip quoted strings so separators inside them do not split; keep a placeholder.
-  const stripped = String(command).replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '""')
-  return stripped
-    .split(/\n|;|&&|\|\||\|/)
-    .map(p => p.trim())
-    // Shell keywords are structure, not commands: drop them, and a "for x in …" header entirely.
-    .map(p => p.replace(/^(?:if|then|else|elif|fi|do|done|while|until)\b\s*/, '').replace(/^for\s+\w+\s+in\b.*$/, '').trim())
-    .filter(Boolean)
-}
+const KIRA_TOOLS = 'mcp__kira__'
 
 function matchesRule(rules, toolName, command) {
   const c = (command ?? '').trim()
@@ -103,41 +40,20 @@ function matchesRule(rules, toolName, command) {
     const rule = String(r).trim()
     if (!rule) continue
     if (rule === toolName) return true
-    if (toolName === 'Bash' && c && (c === rule || c.startsWith(rule + ' ') || pieces(c).some(p => p === rule || p.startsWith(rule + ' ')))) return true
+    const starts = text => text === rule || text.startsWith(rule + ' ')
+    if (toolName === 'Bash' && c && (starts(c) || pieces(c).some(starts))) return true
   }
   return false
 }
 
-export function insideFolder(cwd, p) {
+const allow = reason => ({ decision: 'allow', reason })
+const ask = reason => ({ decision: 'ask', reason })
+
+function insideFolder(cwd, p) {
   const rel = relative(cwd, resolve(cwd, String(p ?? '')))
   return !!rel && !rel.startsWith('..') && !rel.startsWith(sep)
 }
 
-/** Is this shell command read-only, judged piece by piece? Command substitutions are judged by what is inside them. */
-export function shellIsSafe(command, allowRules = []) {
-  let c = String(command ?? '').trim()
-  if (!c) return false
-  // $(inner): safe only if the inner command is; then drop it so the outer check sees plain text.
-  for (let guard = 0; guard < 20; guard++) {
-    const m = /\$\(([^()]*)\)/.exec(c)
-    if (!m) break
-    if (!shellIsSafe(m[1], allowRules)) return false
-    c = c.slice(0, m.index) + '""' + c.slice(m.index + m[0].length)
-  }
-  if (WRITES.test(c.replace(/2>&1|2>\/dev\/null|>\/dev\/null|&>\/dev\/null/g, ''))) return false
-  const allowedByRule = p => allowRules.some(r => r && (p === r || p.startsWith(String(r) + ' ')))
-  return pieces(c).every(p => (SAFE_CMD.test(p) && !FINDER_ACTS.test(p)) || allowedByRule(p))
-}
-
-/** The rule key an "always allow" answer produces. */
-export function ruleFor(toolName, input) {
-  if (toolName !== 'Bash') return toolName
-  const first = pieces(String(input?.command ?? ''))[0] ?? ''
-  const words = first.split(/\s+/)
-  // Two words for package managers and git ("npm run", "git push"), one otherwise.
-  return /^(?:git|npm|pnpm|yarn|npx|cargo|go|docker|gh|heroku|make)$/.test(words[0]) && words[1] ? `${words[0]} ${words[1]}` : words[0]
-}
-
 /**
  * Decide for one tool call. Returns { decision: 'allow'|'ask'|'deny', reason }.
  * @param sessionRules rules allowed earlier in this session ("always allow")
@@ -147,20 +63,22 @@ export function decide(policy, toolName, input, cwd, sessionRules = new Set()) {
   const command = toolName === 'Bash' ? String(input?.command ?? '') : ''
   if (matchesRule(p.denyRules ?? [], toolName, command)) return { decision: 'deny', reason: 'refused by your policy' }
   if (toolName === 'AskUserQuestion') return { decision: 'ask', reason: 'a question for you' }
-  if (matchesRule(p.askRules ?? [], toolName, command)) return { decision: 'ask', reason: 'your policy always asks for this' }
-  if (matchesRule([...(p.allowRules ?? []), ...sessionRules], toolName, command)) return { decision: 'allow', reason: 'allowed by your policy' }
+  const allowRules = [...(p.allowRules ?? []), ...sessionRules]
+  if (matchesRule(p.askRules ?? [], toolName, command)) return ask('your policy always asks for this')
+  if (matchesRule(allowRules, toolName, command)) return allow('allowed by your policy')
   if (READ_ONLY.has(toolName)) return { decision: 'allow', reason: 'read-only' }
   // Kira's own tools (her MCP server, attached when Claude is the person's Kira): her server asks
   // for itself when something needs their yes (approvals), so the Mac doesn't ask a second time.
   if (toolName.startsWith(KIRA_TOOLS)) return { decision: 'allow', reason: 'Kira’s own tool' }
   if (EDITS.has(toolName)) {
     const file = input?.file_path ?? input?.notebook_path
-    if (insideFolder(cwd, file)) return { decision: p.edits === 'ask' ? 'ask' : 'allow', reason: 'edit inside the project' }
+    const inside = 'edit inside the project'
+    if (insideFolder(cwd, file)) return p.edits === 'ask' ? ask(inside) : allow(inside)
     return { decision: p.editsOutside === 'deny' ? 'deny' : 'ask', reason: 'edit outside the project folder' }
   }
   if (toolName === 'Bash') {
     if (p.shell === 'allow') return { decision: 'allow', reason: 'shell allowed by your policy' }
-    if (p.shell !== 'ask' && shellIsSafe(command, p.allowRules ?? [])) return { decision: 'allow', reason: 'read-only command' }
+    if (p.shell !== 'ask' && shellIsSafe(command, p.allowRules ?? [])) return allow('read-only command')
     return { decision: 'ask', reason: 'shell command' }
   }
   if (WEB.has(toolName)) return { decision: p.web === 'ask' ? 'ask' : 'allow', reason: 'web' }

package/src/agents/shell.mjs

@@ -0,0 +1,108 @@
+// Is a shell command only looking? The Mac lets Claude Code run it without asking only when every
+// piece of it is (agents/policy.mjs). Read-only means: no writes, no sends, no installs, no code
+// given inline (node -e, python -c, awk), nothing in the background, no secrets printed.
+
+/** Plain commands that only look (not env or printenv: they run commands, and print secrets). */
+const LOOKERS = [
+  'ls', 'll', 'pwd', 'cat', 'head', 'tail', 'wc', 'echo', 'printf', 'which', 'type',
+  'date', 'whoami', 'id', 'uname', 'tree', 'find', 'fd', 'grep', 'rg', 'ag', 'cut', 'tr', 'sort', 'uniq',
+  'diff', 'comm', 'stat', 'file', 'du', 'df', 'basename', 'dirname', 'realpath', 'readlink', 'jq', 'yq',
+  'xxd', 'hexdump', 'strings', 'test', '[', 'true', 'false', 'sleep', 'md5', 'shasum', 'sha256sum',
+  'md5sum', 'column', 'nl', 'less', 'more', 'tsc', 'eslint', 'jest', 'vitest', 'pytest',
+]
+/** Tools with their read-only, test and build subcommands. */
+const SUBCOMMANDS = {
+  git: [
+    'status', 'diff', 'log', 'show', 'rev-parse', 'ls-files', 'ls-tree', 'blame', 'describe', 'stash list',
+    'config --get', 'config -l', 'cat-file', 'grep', 'shortlog', 'count-objects', 'reflog',
+    'branch --list', 'branch -a', 'branch -r', 'branch -v', 'branch -vv', 'branch --show-current',
+    'tag -l', 'tag --list', 'remote -v', 'remote show',
+  ],
+  node: ['-v', '--version'],
+  npm: ['-v', '--version', 'ls', 'list', 'view', 'outdated', 'why', 'test', 'run test', 'run lint', 'run typecheck',
+    'run check', 'run build', 'run format:check'],
+  pnpm: ['-v', '--version', 'ls', 'list', 'why', 'outdated', 'test', 'typecheck', 'lint', 'build', 'run test',
+    'run lint', 'run typecheck', 'run check', 'run build'],
+  yarn: ['-v', '--version', 'list', 'test', 'lint', 'typecheck', 'build'],
+  npx: ['tsc', 'eslint', 'prettier --check', 'jest', 'vitest', 'playwright test'],
+  prettier: ['--check'],
+  cargo: ['check', 'test', 'build', 'fmt --check', 'clippy', 'tree', 'metadata'],
+  go: ['test', 'build', 'vet', 'version', 'list', 'env'],
+  python: ['-V', '--version', '-m pytest'],
+  python3: ['-V', '--version', '-m pytest'],
+  ruby: ['-v'],
+  make: ['test', 'check', 'lint', 'build'],
+  mvn: ['test', 'compile'],
+  gradle: ['test', 'build'],
+  swift: ['build', 'test'],
+  xcodebuild: ['-list'],
+  brew: ['list', 'info', '--version'],
+  docker: ['ps', 'images', 'version'],
+  gh: ['pr list', 'pr view', 'pr status', 'pr checks', 'issue list', 'issue view', 'run list', 'run view', 'repo view'],
+  heroku: ['logs', 'ps', 'releases', 'apps', 'info'],
+  open: ['-n --args'],
+  sed: ['-n', '-E -n', '-n -E'],
+}
+/** These list only when given nothing else ("git branch -D x" deletes, "git tag v1" creates). */
+const BARE = new Set(['git branch', 'git tag', 'git remote'])
+
+const escape = w => w.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+const withSubs = Object.entries(SUBCOMMANDS).flatMap(([tool, subs]) => subs.map(sub => `${tool} ${sub}`))
+const SAFE_CMD = new RegExp(`^(?:${[...LOOKERS, ...withSubs].map(escape).join('|')})(?:\\s|$)`)
+
+/** Redirections that write somewhere other than nowhere, and ways to run something else. */
+const WRITES = /(^|[^&\d])>(?!&)|>>|\btee\b|\bxargs\b|\beval\b|\bexec\b|`/
+/** Running in the background (a lone &), or process substitution: the rest is never judged. */
+const HIDDEN = /(^|[^&>])&(?![&>])|<\(|>\(/
+/** Flags that turn a looking command into one that writes or runs. */
+const ACTS = [
+  /^(?:find|fd)\b.*\s(?:-exec(?:dir)?|-ok(?:dir)?|-delete|-fprint\w*|-fls|-x|--exec(?:-batch)?|-X)\b/,
+  /^sort\b.*\s(?:-o|--output)(?:\s|=|$)/,
+  /^(?:npx\s+)?eslint\b.*\s--fix\b/,
+  /^(?:npx\s+)?prettier\b.*\s(?:--write|-w)(?:\s|$)/,
+  /^(?:npx\s+)?(?:jest|vitest)\b.*\s(?:-u|--update\w*)(?:\s|=|$)/,
+  /^git\s+(?:diff|log|show)\b.*\s--output(?:\s|=)/,
+  /^go\s+env\b.*\s-w(?:\s|$)/,
+]
+
+/** A command's pieces: what runs, split at ; && || | and newlines (quoted text left whole). */
+export function pieces(command) {
+  const stripped = unquoted(command)
+  return stripped
+    .split(/\n|;|&&|\|\||\|/)
+    .map(p => p.trim())
+    // Shell keywords are structure, not commands: drop them, and a "for x in …" header entirely.
+    .map(p => p.replace(/^(?:if|then|else|elif|fi|do|done|while|until)\b\s*/, '').replace(/^for\s+\w+\s+in\b.*$/, ''))
+    .map(p => p.trim())
+    .filter(Boolean)
+}
+
+/** Quoted strings blanked, so separators and symbols inside them don't count. */
+const unquoted = command => String(command).replace(/"(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*'/g, '""')
+
+const looks = piece => (SAFE_CMD.test(piece) || BARE.has(piece)) && !ACTS.some(a => a.test(piece))
+
+/** Is this shell command read-only, judged piece by piece? Command substitutions are judged by what is inside them. */
+export function shellIsSafe(command, allowRules = []) {
+  let c = String(command ?? '').trim()
+  if (!c) return false
+  // $(inner): safe only if the inner command is; then drop it so the outer check sees plain text.
+  for (let guard = 0; guard < 20; guard++) {
+    const m = /\$\(([^()]*)\)/.exec(c)
+    if (!m) break
+    if (!shellIsSafe(m[1], allowRules)) return false
+    c = c.slice(0, m.index) + '""' + c.slice(m.index + m[0].length)
+  }
+  const plain = unquoted(c).replace(/2>&1|2>\/dev\/null|>\/dev\/null|&>\/dev\/null/g, '')
+  if (WRITES.test(plain) || HIDDEN.test(plain)) return false
+  const allowedByRule = p => allowRules.some(r => r && (p === r || p.startsWith(String(r) + ' ')))
+  return pieces(c).every(p => looks(p) || allowedByRule(p))
+}
+
+/** The rule key an "always allow" answer produces: two words for package managers and git, one otherwise. */
+export function ruleFor(toolName, input) {
+  if (toolName !== 'Bash') return toolName
+  const words = (pieces(String(input?.command ?? ''))[0] ?? '').split(/\s+/)
+  const twoWords = /^(?:git|npm|pnpm|yarn|npx|cargo|go|docker|gh|heroku|make)$/.test(words[0]) && words[1]
+  return twoWords ? `${words[0]} ${words[1]}` : words[0]
+}

package/src/apps.mjs

@@ -73,7 +73,7 @@ function norm(s) {
 }
 
 /** Resolve a spoken app name to an installed bundle name, or null. */
-export async function resolveApp(name) {
+async function resolveApp(name) {
   const apps = await installedApps()
   const q = norm(name)
   if (!q) return null

package/src/claude-config.mjs

@@ -0,0 +1,153 @@
+// Claude Code's own skills on this Mac: one SKILL.md each in ~/.claude/skills/<slug>/ (or under
+// $CLAUDE_CONFIG_DIR), which Claude Code and the bridge's Agent SDK jobs load natively. Kira lists
+// all of them (hers and any other), and writes and removes the ones a person makes in Kira. Every
+// path is confined to that folder: a slug is one plain folder name, and a symlinked folder is never
+// written through.
+import { lstat, mkdir, readdir, readFile, rename, rmdir, stat, unlink, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/
+/** A SKILL.md past this isn't one: skipped when listing, refused when writing. */
+const MAX_MD = 256 * 1024
+
+/** Where Claude Code keeps personal skills. */
+function skillsRoot() {
+  return join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'skills')
+}
+
+/** The folder for a skill, after checking its slug can't name anything else. */
+function folder(root, slug) {
+  const s = String(slug ?? '')
+  if (!SLUG.test(s)) throw new Error(`“${s}” isn’t a skill folder name (lowercase letters, digits and dashes)`)
+  return join(root, s)
+}
+
+/** As people read it: under the home folder with ~. */
+function display(full) {
+  const rel = relative(homedir(), full)
+  return rel && !rel.startsWith('..') ? `~/${rel}` : full
+}
+
+/** A front-matter value: quoted or plain on its line, or a `|` / `>` block below it. */
+function field(front, key) {
+  const lines = front.split('\n')
+  const at = lines.findIndex(l => l.startsWith(`${key}:`))
+  if (at < 0) return null
+  const raw = lines[at].slice(key.length + 1).trim()
+  if (/^[|>][+-]?$/.test(raw)) {
+    const block = []
+    for (const l of lines.slice(at + 1)) {
+      if (l.trim() && !/^\s/.test(l)) break
+      block.push(l.trim())
+    }
+    return block.join(raw.startsWith('|') ? '\n' : ' ').trim() || null
+  }
+  const quoted = /^(["'])(.*)\1$/.exec(raw)
+  return (quoted ? quoted[2] : raw.replace(/\s+#.*$/, '')).trim() || null
+}
+
+/** The name and description Claude Code shows, from a SKILL.md (the folder's name when it has none). */
+export function skillSummary(md, slug) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md)
+  const front = m ? m[1].replace(/\r\n/g, '\n') : ''
+  const body = m ? md.slice(m[0].length) : md
+  const firstLine = body.split('\n').map(l => l.trim()).find(Boolean) ?? ''
+  return { name: field(front, 'name') || slug, description: field(front, 'description') || firstLine }
+}
+
+async function isSymlink(p) {
+  return lstat(p).then(
+    s => s.isSymbolicLink(),
+    () => false,
+  )
+}
+
+/** A folder that links elsewhere is changed where it really is, never through the link. */
+async function refuseLinks(root, dir, verb) {
+  if ((await isSymlink(root)) || (await isSymlink(dir))) {
+    throw new Error(`${display(dir)} is a link to somewhere else; ${verb} it there`)
+  }
+}
+
+/** Every skill in the folder: its slug, name, description, where it is, and its SKILL.md. */
+export async function listSkills(root = skillsRoot()) {
+  const entries = await readdir(root, { withFileTypes: true }).catch(e => {
+    if (e.code === 'ENOENT') return []
+    throw e
+  })
+  const skills = []
+  for (const e of entries) {
+    if (!SLUG.test(e.name) || !(e.isDirectory() || e.isSymbolicLink())) continue
+    const file = join(root, e.name, 'SKILL.md')
+    const st = await stat(file).catch(() => null)
+    if (!st?.isFile() || st.size > MAX_MD) continue
+    const md = await readFile(file, 'utf8').catch(() => null)
+    if (md === null) continue
+    skills.push({ slug: e.name, ...skillSummary(md, e.name), path: display(join(root, e.name)), md })
+  }
+  skills.sort((a, b) => a.slug.localeCompare(b.slug))
+  return { root: display(root), skills }
+}
+
+/** One skill's SKILL.md. */
+export async function readSkill({ slug } = {}, root = skillsRoot()) {
+  const dir = folder(root, slug)
+  const md = await readFile(join(dir, 'SKILL.md'), 'utf8').catch(() => null)
+  if (md === null) return { error: `No skill in ${display(dir)}` }
+  return { slug, ...skillSummary(md, slug), path: display(dir), md }
+}
+
+/**
+ * Write a skill's SKILL.md, whole: replacing the one there, or with `create` only a new one (a skill
+ * already in that folder, Kira's or not, is never overwritten by a new one of the same name).
+ */
+export async function writeSkill({ slug, md, create = false } = {}, root = skillsRoot()) {
+  const dir = folder(root, slug)
+  const text = String(md ?? '')
+  if (!/^---\r?\n/.test(text)) throw new Error('A SKILL.md starts with front matter between --- lines')
+  if (Buffer.byteLength(text) > MAX_MD) throw new Error('That SKILL.md is too large')
+  await refuseLinks(root, dir, 'edit')
+  const file = join(dir, 'SKILL.md')
+  if (create && (await stat(file).catch(() => null))) throw new Error(`A skill named ${slug} is already on your Mac`)
+  await mkdir(dir, { recursive: true })
+  const tmp = join(dir, `.SKILL.md.${process.pid}.tmp`)
+  await writeFile(tmp, text, 'utf8')
+  await rename(tmp, file)
+  return { slug, ...skillSummary(text, slug), path: display(dir) }
+}
+
+/**
+ * Remove a skill: its SKILL.md goes (so Claude Code stops loading it), and the folder too when
+ * nothing else is in it. Anything else a skill folder holds (scripts, references) stays.
+ */
+export async function removeSkill({ slug } = {}, root = skillsRoot()) {
+  const dir = folder(root, slug)
+  await refuseLinks(root, dir, 'remove')
+  const gone = await unlink(join(dir, 'SKILL.md')).then(
+    () => true,
+    e => {
+      if (e.code === 'ENOENT') return false
+      throw e
+    },
+  )
+  const left = await readdir(dir).catch(() => [])
+  if (!left.length) await rmdir(dir).catch(() => {})
+  return { slug, removed: gone, path: display(dir), kept: left.length ? left : undefined }
+}
+
+/** The bridge tools (index.mjs). */
+export const skillTools = {
+  async list_skills() {
+    return listSkills()
+  },
+  async read_skill(args) {
+    return readSkill(args)
+  },
+  async write_skill(args) {
+    return writeSkill(args)
+  },
+  async remove_skill(args) {
+    return removeSkill(args)
+  },
+}

package/src/config.mjs

@@ -5,7 +5,7 @@ import { homedir } from 'node:os'
 import { join } from 'node:path'
 
 export const KIRA_DIR = join(homedir(), '.kira')
-export const CONFIG_PATH = join(KIRA_DIR, 'bridge.json')
+const CONFIG_PATH = join(KIRA_DIR, 'bridge.json')
 export const LOG_PATH = join(KIRA_DIR, 'bridge.log')
 export const DEFAULT_URL = 'wss://kira.glass/api/bridge/ws'
 

package/src/connection.mjs

@@ -0,0 +1,137 @@
+// The socket to the Kira API: connecting, reconnecting with backoff, and routing what arrives
+// (answers to parked questions, terminal traffic, tool calls) to whoever handles it.
+import WebSocket from 'ws'
+import { normalizeAnswer } from './agents/protocol.mjs'
+import { answer } from './agents/answers.mjs'
+import { terminalMessage, terminalsOffline } from './terminals.mjs'
+import { host, log, status } from './host.mjs'
+
+/**
+ * The live connection, and what could not be sent while there was none. Jobs
+ * outlive connections (every API deploy reconnects us), so their events and
+ * results go through here rather than the socket they were started on.
+ */
+let live = null
+const outbox = []
+const OUTBOX_MAX = 2000
+
+let settings = null
+let stopped = false
+let reconnectTimer = null
+let backoff = 1000
+
+/** A job's event or result: sent now, or queued until the next connection. */
+export function sendLive(obj) {
+  if (live && live.readyState === WebSocket.OPEN) return live.send(JSON.stringify(obj))
+  if (outbox.length >= OUTBOX_MAX) outbox.shift()
+  outbox.push(obj)
+}
+
+/** Sent only if connected right now (terminal output is live or nothing). */
+export function sendIfLive(obj) {
+  return live?.readyState === WebSocket.OPEN && live.send(JSON.stringify(obj))
+}
+
+/**
+ * Connect and keep connecting until disconnect(). `tools` maps a tool name to its function;
+ * `capabilities()` is what the bridge tells the API it implements, after its hello.
+ */
+export function connect({ url, token, tools, capabilities }) {
+  settings = { url, token, tools, capabilities }
+  stopped = false
+  open()
+}
+
+/** Disconnect and stop reconnecting. */
+export function disconnect() {
+  stopped = true
+  clearTimeout(reconnectTimer)
+  const ws = live
+  live = null
+  try {
+    ws?.close(1000, 'stopped')
+  } catch {
+    /* already closed */
+  }
+  status('disconnected')
+}
+
+function open() {
+  if (stopped) return
+  status('connecting')
+  const { url, token } = settings
+  const ws = new WebSocket(`${url}?token=${encodeURIComponent(token)}`)
+  let ping
+  ws.on('open', () => {
+    backoff = 1000
+    log(`connected to ${url}`)
+    ping = setInterval(() => send(ws, { type: 'ping' }), 30_000)
+  })
+  ws.on('message', raw => onMessage(ws, raw))
+  ws.on('close', (code, reason) => {
+    clearInterval(ping)
+    onClose(ws, code, reason)
+  })
+  ws.on('error', err => log(`socket error: ${err.message}`))
+}
+
+async function onMessage(ws, raw) {
+  let msg
+  try {
+    msg = JSON.parse(raw.toString())
+  } catch {
+    return
+  }
+  if (msg.type === 'hello') return registered(ws, msg)
+  if (msg.type === 'job.answer') return answered(msg)
+  if (terminalMessage(msg)) return
+  if (msg.type !== 'call') return
+  const fn = settings.tools[msg.tool]
+  if (!fn) return send(ws, { type: 'error', id: msg.id, error: `unknown tool ${msg.tool}` })
+  try {
+    send(ws, { type: 'result', id: msg.id, result: await fn(msg.args ?? {}, ws) })
+  } catch (err) {
+    send(ws, { type: 'error', id: msg.id, error: err.message })
+  }
+}
+
+function registered(ws, msg) {
+  // 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', ...settings.capabilities() })
+  live = ws
+  // Job events and results from while we were disconnected, in order.
+  if (outbox.length) {
+    log(`sending ${outbox.length} queued job messages`)
+    for (const o of outbox.splice(0)) ws.send(JSON.stringify(o))
+  }
+  status('connected')
+  log(`registered as bridge ${msg.bridgeId} (${Object.keys(settings.tools).length} tools)`)
+}
+
+function answered(msg) {
+  const by = msg.by ?? 'portal'
+  if (answer(msg.jobId, msg.requestId, { answer: normalizeAnswer(msg.answer), by })) {
+    log(`request ${msg.requestId} for job ${String(msg.jobId).slice(0, 8)} answered by ${by}`)
+  }
+}
+
+function onClose(ws, code, reason) {
+  if (live === ws) live = null
+  terminalsOffline()
+  if (code === 4001) {
+    log('token rejected; create a new one in the portal')
+    status('rejected')
+    if (!host().onStatus) process.exit(1) // the CLI's behavior; an app decides for itself
+    return
+  }
+  if (stopped) return
+  status('disconnected')
+  log(`disconnected (${code} ${reason}); retrying in ${backoff / 1000}s`)
+  reconnectTimer = setTimeout(open, backoff)
+  backoff = Math.min(backoff * 2, 30_000)
+}
+
+function send(ws, obj) {
+  if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj))
+}

package/src/file-tools.mjs

@@ -0,0 +1,45 @@
+// The bridge's file tools: listing, reading and changing files and folders on this Mac. Tools
+// that change something report the git diff they made, like Claude jobs do.
+import { dirname } from 'node:path'
+import { stat } from 'node:fs/promises'
+import { changesSince, snapshot } from './git.mjs'
+import { createFolder, listFiles, readUserFile, resolveUserPath, trashPath, writeUserFile } from './files.mjs'
+
+export const fileTools = {
+  async list_files(args) {
+    return listFiles(args)
+  },
+  async read_file(args) {
+    return readUserFile(args)
+  },
+  async create_folder(args) {
+    return withChange(args.path, () => createFolder(args))
+  },
+  async write_file(args) {
+    return withChange(args.path, () => writeUserFile(args))
+  },
+  async delete_path(args) {
+    return withChange(args.path, () => trashPath(args))
+  },
+}
+
+/**
+ * Run a file-changing tool with a git snapshot around it, so the API can show
+ * the diff the same way it does for Claude jobs. Outside a repo: no change.
+ */
+async function withChange(pathArg, fn) {
+  let before = null
+  try {
+    const full = resolveUserPath(String(pathArg ?? ''))
+    const isDir = await stat(full)
+      .then(s => s.isDirectory())
+      .catch(() => false)
+    before = await snapshot(isDir ? full : dirname(full))
+  } catch {
+    before = null
+  }
+  const result = await fn()
+  if (!before || (result && result.error)) return result
+  const change = await changesSince(before).catch(() => null)
+  return change ? { ...result, change } : result
+}

package/src/files.mjs

@@ -10,9 +10,6 @@ const TEXT_LIMIT = 12000
 const READ_LIMIT = 2 * 1024 * 1024
 const SKIP = new Set(['node_modules', '.git', 'Library', '.Trash'])
 
-/** Common starting points, shown as the top level on the glasses. */
-export const ROOTS = ['Desktop', 'Documents', 'Downloads', 'Developer']
-
 /** Expand ~ and confine to the home folder. Throws on escape. */
 export function resolveUserPath(p) {
   const raw = String(p ?? '').trim()

package/src/host.mjs

@@ -0,0 +1,29 @@
+// How the host hears from the bridge. The CLI passes nothing (logs to stdout, exits when the
+// 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)
+//   browser({ op, … })      Kira in the app's browser dock: open, read, click, type (browser-kira.mjs)
+
+let hooks = {}
+
+export function setHooks(hostHooks) {
+  hooks = hostHooks
+}
+
+/** The current host's hooks (read at call time: startBridge may replace them). */
+export function host() {
+  return hooks
+}
+
+export function status(s) {
+  hooks.onStatus?.(s)
+}
+
+export function log(m) {
+  const line = `[kira-bridge ${new Date().toLocaleTimeString()}] ${m}`
+  if (hooks.log) hooks.log(line)
+  else console.log(line)
+}

package/src/index.mjs

@@ -1,317 +1,58 @@
 #!/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 WebSocket from 'ws'
-import { listProjects, listSessions, readSession } from './claude-sessions.mjs'
-import { scanDesigns } from './claude-designs.mjs'
-import { snapshot, changesSince, display, setupProjectFolder } from './git.mjs'
-import { resolveCwd, folderExists } from './claude-run.mjs'
-import { agentById, AGENTS } from './agents/index.mjs'
-import { normalizeAnswer } from './agents/protocol.mjs'
-import { answer, awaitAnswer, forgetJob } from './agents/answers.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 { gitTools } from './git-tools.mjs'
+import { createRequire } from 'node:module'
+import { AGENTS } from './agents/index.mjs'
 import { claudeTools } from './agents/claude-local.mjs'
+import { skillTools } from './claude-config.mjs'
+import { connect, disconnect, sendIfLive } from './connection.mjs'
+import { fileTools } from './file-tools.mjs'
+import { gitTools } from './git-tools.mjs'
+import { host, log, setHooks } from './host.mjs'
+import { jobTools } from './job-tools.mjs'
+import { macTools } from './mac-tools.mjs'
+import { sessionTools } from './session-tools.mjs'
+import { initTerminals } from './terminals.mjs'
 
-import { createRequire } from 'node:module'
 const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
 
-let URL_ = ''
-let TOKEN = ''
-/** Running jobs, by id, so a person can stop one. */
-const running = new Map()
-/**
- * The live connection, and what could not be sent while there was none. Jobs
- * outlive connections (every API deploy reconnects us), so their events and
- * results go through here rather than the socket they were started on.
- */
-let live = null
-const outbox = []
-const OUTBOX_MAX = 2000
-function sendLive(obj) {
-  if (live && live.readyState === WebSocket.OPEN) return live.send(JSON.stringify(obj))
-  if (outbox.length >= OUTBOX_MAX) outbox.shift()
-  outbox.push(obj)
+const tools = {
+  ...fileTools,
+  ...macTools,
+  ...sessionTools,
+  ...jobTools,
+  ...gitTools,
+  ...claudeTools,
+  ...skillTools,
+}
+
+/** What this bridge build implements, told to the API after its hello. */
+function capabilities() {
+  const agents = Object.values(AGENTS).map(a => ({ id: a.id, name: a.name, capabilities: a.capabilities }))
+  return { tools: Object.keys(tools), version: BRIDGE_VERSION, platform: process.platform, agents }
 }
 
 /**
- * How the host hears from the bridge. The CLI passes nothing (logs to stdout, exits when the
- * 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)
- *   browser({ op, … })      Kira in the app's browser dock: open, read, click, type (browser-kira.mjs)
+ * Start the bridge with resolved settings. Runs until stopBridge() or the process exits.
+ * `hostHooks` is how the host hears from it (host.mjs).
  */
-let hooks = {}
-let stopped = false
-let reconnectTimer = null
-
-/** Start the bridge with resolved settings. Runs until stopBridge() or the process exits. */
 export function startBridge(config, hostHooks = {}) {
-  hooks = hostHooks
-  URL_ = config.url
-  TOKEN = config.token
+  setHooks(hostHooks)
   if (config.claudeBin) process.env.KIRA_CLAUDE_BIN = config.claudeBin
-  if (!URL_ || !TOKEN) {
-    throw new Error('No token. Run: npx kira-glasses-bridge --token <token>  (from the Kira portal → Connections → Claude Code)')
+  if (!config.url || !config.token) {
+    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)))
+  initTerminals(() => host().terminals ?? null, sendIfLive)
   log(`kira-bridge ${BRIDGE_VERSION} · agents: ${Object.keys(AGENTS).join(', ')}`)
-  connect()
+  connect({ url: config.url, token: config.token, tools, capabilities })
 }
 
 /** Disconnect and stop reconnecting (the app calls this on sign-out or a token change). */
 export function stopBridge() {
-  stopped = true
-  clearTimeout(reconnectTimer)
-  const ws = live
-  live = null
-  try {
-    ws?.close(1000, 'stopped')
-  } catch {
-    /* already closed */
-  }
-  status('disconnected')
+  disconnect()
 }
 
 export const bridgeVersion = BRIDGE_VERSION
-
-function status(s) {
-  hooks.onStatus?.(s)
-}
-
-const tools = {
-  async list_files(args) {
-    return listFiles(args)
-  },
-  async read_file(args) {
-    return readUserFile(args)
-  },
-  async create_folder(args) {
-    return withChange(args.path, () => createFolder(args))
-  },
-  async write_file(args) {
-    return withChange(args.path, () => writeUserFile(args))
-  },
-  async open_app(args) {
-    return openApp(args)
-  },
-  async delete_path(args) {
-    return withChange(args.path, () => trashPath(args))
-  },
-  async list_apps() {
-    return { apps: await installedApps() }
-  },
-  async list_claude_projects(args) {
-    return listProjects(args.max)
-  },
-  async scan_claude_designs(args) {
-    return scanDesigns({ since: args.since, known: Array.isArray(args.known) ? args.known : [], sessions: args.sessions })
-  },
-  async list_claude_sessions(args) {
-    return listSessions(args.max)
-  },
-  async read_claude_session(args) {
-    return readSession(String(args.session_id ?? ''), args.turns)
-  },
-  /**
-   * 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' }
-    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)
-    if (!folderExists(dir)) {
-      // The SDK would report a spawn failure as a broken binary; the folder is simply not there.
-      return { error: `The folder ${display(dir)} does not exist on this Mac. Link the project's real folder in the portal, or clone its repository there first (setup_project_folder); never guess a path.` }
-    }
-    log(`${agent.id} job=${jobId.slice(0, 8)}${args.persona?.name ? ` as ${args.persona.name}` : ''} session=${args.session_id ?? 'new'} in ${display(dir)}: ${prompt.slice(0, 80)}`)
-    let seq = 0
-    const io = {
-      emit: event => sendLive({ type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
-      ask: (request, signal) => awaitAnswer(jobId, request, signal),
-    }
-    const abort = new AbortController()
-    running.set(jobId, abort)
-    // Started is said at once. The git snapshot (what changed, reported at the end) is taken first but
-    // in the background: in a big repository it takes longer than the API waits for this answer.
-    const before = snapshot(dir).catch(() => null)
-    const persona = args.persona ?? null
-    const settings = args.settings ?? null
-    const job = { prompt, sessionId: args.session_id, cwd: dir, policy: args.policy ?? {}, persona, settings, abort }
-    void before.then(() => agent.run(job, io)).then(async outcome => {
-      running.delete(jobId)
-      forgetJob(jobId)
-      let change = null
-      const was = await before
-      if (was) change = await changesSince(was).catch(err => (log(`git after job failed: ${err.message}`), null))
-      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 }
-      sendLive({ type: 'job', jobId, status: outcome.ok ? 'done' : 'error', result, error: outcome.error })
-    })
-    return { started: true, agent: agent.id, cwd: display(dir) }
-  },
-  /** Stop a running job: the agent is cut off; whatever it committed stays. */
-  stop_job(args) {
-    const abort = running.get(String(args.job_id ?? ''))
-    if (!abort) return { stopped: false, note: 'no such job running here' }
-    abort.abort()
-    return { stopped: true }
-  },
-  /** Older API builds still call ask_claude. */
-  ask_claude(args, ws) {
-    return tools.run_agent({ ...args, agent: 'claude' }, ws)
-  },
-
-  /** A new project's folder on this Mac: created, cloned from its repo or started fresh. */
-  async setup_project_folder(args) {
-    const dir = resolveUserPath(String(args.path ?? ''))
-    return setupProjectFolder({ dir, name: args.name, description: args.description, sshUrl: args.ssh_url, httpsUrl: args.https_url })
-  },
-
-  /** This Mac's shells for a browser elsewhere (only inside the Mac app, only when switched on there). */
-  terminal: args => terminalCall(args),
-
-  /** Kira in the Mac app's browser dock: open a page, read it, click and type in it. */
-  async browser(args) {
-    if (!hooks.browser) return { error: 'the browser needs the Kira Mac app (this bridge has none)', reason: 'unavailable' }
-    return hooks.browser(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"
-  activate
-  do script "cd ${JSON.stringify(dir)} && ${command}"
-end tell`
-    return new Promise(resolve => execFile('osascript', ['-e', script], err => resolve(err ? { error: err.message } : { opened: true, cwd: display(dir), command })))
-  },
-
-  ...gitTools,
-  ...claudeTools,
-
-
-}
-
-/**
- * Run a file-changing tool with a git snapshot around it, so the API can show
- * the diff the same way it does for Claude jobs. Outside a repo: no change.
- */
-async function withChange(pathArg, fn) {
-  let before = null
-  try {
-    const full = resolveUserPath(String(pathArg ?? ''))
-    const { dirname } = await import('node:path')
-    const { stat } = await import('node:fs/promises')
-    const isDir = await stat(full).then(s => s.isDirectory()).catch(() => false)
-    before = await snapshot(isDir ? full : dirname(full))
-  } catch {
-    before = null
-  }
-  const result = await fn()
-  if (!before || (result && result.error)) return result
-  const change = await changesSince(before).catch(() => null)
-  return change ? { ...result, change } : result
-}
-
-let backoff = 1000
-function connect() {
-  if (stopped) return
-  status('connecting')
-  const ws = new WebSocket(`${URL_}?token=${encodeURIComponent(TOKEN)}`)
-  let ping
-  ws.on('open', () => {
-    backoff = 1000
-    log(`connected to ${URL_}`)
-    ping = setInterval(() => send(ws, { type: 'ping' }), 30_000)
-  })
-  ws.on('message', async raw => {
-    let msg
-    try {
-      msg = JSON.parse(raw.toString())
-    } catch {
-      return
-    }
-    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, agents: Object.values(AGENTS).map(a => ({ id: a.id, name: a.name, capabilities: a.capabilities })) })
-      live = ws
-      // Job events and results from while we were disconnected, in order.
-      if (outbox.length) {
-        log(`sending ${outbox.length} queued job messages`)
-        for (const o of outbox.splice(0)) ws.send(JSON.stringify(o))
-      }
-      status('connected')
-      return log(`registered as bridge ${msg.bridgeId} (${Object.keys(tools).length} tools)`)
-    }
-    if (msg.type === 'job.answer') {
-      const by = msg.by ?? 'portal'
-      if (answer(msg.jobId, msg.requestId, { answer: normalizeAnswer(msg.answer), by })) {
-        log(`request ${msg.requestId} for job ${String(msg.jobId).slice(0, 8)} answered by ${msg.by ?? 'portal'}`)
-      }
-      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}` })
-    try {
-      send(ws, { type: 'result', id: msg.id, result: await fn(msg.args ?? {}, ws) })
-    } catch (err) {
-      send(ws, { type: 'error', id: msg.id, error: err.message })
-    }
-  })
-  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')
-      if (!hooks.onStatus) process.exit(1) // the CLI's behavior; an app decides for itself
-      return
-    }
-    if (stopped) return
-    status('disconnected')
-    log(`disconnected (${code} ${reason}); retrying in ${backoff / 1000}s`)
-    reconnectTimer = setTimeout(connect, backoff)
-    backoff = Math.min(backoff * 2, 30_000)
-  })
-  ws.on('error', err => log(`socket error: ${err.message}`))
-}
-
-function send(ws, obj) {
-  if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(obj))
-}
-function log(m) {
-  const line = `[kira-bridge ${new Date().toLocaleTimeString()}] ${m}`
-  if (hooks.log) hooks.log(line)
-  else console.log(line)
-}
-

package/src/job-format.mjs

@@ -0,0 +1,21 @@
+// What a run_agent call asks for and how its outcome reads in the log: pure, so it's tested
+// (test/job-format.test.mjs) apart from the socket and the agents.
+
+/** The instruction, whichever name an API build sends it under. */
+export function promptOf(args) {
+  return String(args.prompt ?? args.message ?? args.text ?? args.instruction ?? '').trim()
+}
+
+/** The log line when a job starts. */
+export function jobStartLine({ agentId, jobId, persona, sessionId, dir, prompt }) {
+  const as = persona?.name ? ` as ${persona.name}` : ''
+  return `${agentId} job=${jobId.slice(0, 8)}${as} session=${sessionId ?? 'new'} in ${dir}: ${prompt.slice(0, 80)}`
+}
+
+/** The log line when a job ends: its outcome and, in a repository, what it changed. */
+export function jobEndLine(jobId, ok, change) {
+  const outcome = `job ${jobId.slice(0, 8)} ${ok ? 'done' : 'error'}`
+  if (!change) return outcome
+  const { files, adds, dels } = change.stats
+  return `${outcome} · ${files} files +${adds} -${dels}, ${change.commits.length} commits`
+}

package/src/job-tools.mjs

@@ -0,0 +1,96 @@
+// The bridge's coding-agent jobs: starting one (acknowledged at once, streamed as it runs,
+// reported when done) and stopping one.
+import { agentById } from './agents/index.mjs'
+import { awaitAnswer, forgetJob } from './agents/answers.mjs'
+import { resolveCwd, folderExists } from './claude-run.mjs'
+import { readSession } from './claude-sessions.mjs'
+import { changesSince, display, snapshot } from './git.mjs'
+import { sendLive } from './connection.mjs'
+import { log } from './host.mjs'
+import { jobEndLine, jobStartLine, promptOf } from './job-format.mjs'
+
+/** Running jobs, by id, so a person can stop one. */
+const running = new Map()
+
+export const jobTools = {
+  /**
+   * 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) {
+    const jobId = String(args.job_id ?? '')
+    const agent = agentById(args.agent)
+    if (!agent) return { error: `unknown agent ${args.agent}` }
+    const prompt = promptOf(args)
+    if (!prompt) return { error: 'prompt is required' }
+    const dir = resolveCwd(await jobCwd(args))
+    if (!folderExists(dir)) {
+      // The SDK would report a spawn failure as a broken binary; the folder is simply not there.
+      return {
+        error:
+          `The folder ${display(dir)} does not exist on this Mac. Link the project's real folder in the portal, ` +
+          `or clone its repository there first (setup_project_folder); never guess a path.`,
+      }
+    }
+    const sessionId = args.session_id
+    log(jobStartLine({ agentId: agent.id, jobId, persona: args.persona, sessionId, dir: display(dir), prompt }))
+    let seq = 0
+    const io = {
+      emit: event => sendLive({ type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
+      ask: (request, signal) => awaitAnswer(jobId, request, signal),
+    }
+    const abort = new AbortController()
+    running.set(jobId, abort)
+    // Started is said at once. The git snapshot (what changed, reported at the end) is taken first but
+    // in the background: in a big repository it takes longer than the API waits for this answer.
+    const before = snapshot(dir).catch(() => null)
+    const persona = args.persona ?? null
+    const settings = args.settings ?? null
+    const job = { prompt, sessionId, cwd: dir, policy: args.policy ?? {}, persona, settings, abort }
+    void before.then(() => agent.run(job, io)).then(outcome => finish({ jobId, agent, dir, before, outcome }))
+    return { started: true, agent: agent.id, cwd: display(dir) }
+  },
+  /** Stop a running job: the agent is cut off; whatever it committed stays. */
+  stop_job(args) {
+    const abort = running.get(String(args.job_id ?? ''))
+    if (!abort) return { stopped: false, note: 'no such job running here' }
+    abort.abort()
+    return { stopped: true }
+  },
+  /** Older API builds still call ask_claude. */
+  ask_claude(args) {
+    return jobTools.run_agent({ ...args, agent: 'claude' })
+  },
+}
+
+/** The folder a job runs in: as given, else the folder of the session it continues. */
+async function jobCwd(args) {
+  if (args.cwd || !args.session_id) return args.cwd
+  const s = await readSession(String(args.session_id), 1)
+  return s?.cwd ? s.cwd : args.cwd
+}
+
+/** A job ended: what it changed in the repository, and its outcome, go to the API. */
+async function finish({ jobId, agent, dir, before, outcome }) {
+  running.delete(jobId)
+  forgetJob(jobId)
+  let change = null
+  const was = await before
+  if (was) {
+    change = await changesSince(was).catch(err => {
+      log(`git after job failed: ${err.message}`)
+      return null
+    })
+  }
+  log(jobEndLine(jobId, outcome.ok, change))
+  const result = {
+    session_id: outcome.sessionId,
+    result: outcome.text ?? '',
+    stats: outcome.stats,
+    cwd: display(dir),
+    change,
+    agent: agent.id,
+  }
+  sendLive({ type: 'job', jobId, status: outcome.ok ? 'done' : 'error', result, error: outcome.error })
+}

package/src/mac-tools.mjs

@@ -0,0 +1,62 @@
+// The bridge's tools for this Mac itself: its apps, a terminal, a new project's folder, and
+// (inside the Mac app only) its shells for other devices and its browser dock.
+import { execFile } from 'node:child_process'
+import { openApp, installedApps } from './apps.mjs'
+import { resolveUserPath } from './files.mjs'
+import { display, setupProjectFolder } from './git.mjs'
+import { terminalCall } from './terminals.mjs'
+import { safeCommand, terminalScript } from './terminal-command.mjs'
+import { host } from './host.mjs'
+
+export const macTools = {
+  async open_app(args) {
+    return openApp(args)
+  },
+  async list_apps() {
+    return { apps: await installedApps() }
+  },
+
+  /** A new project's folder on this Mac: created, cloned from its repo or started fresh. */
+  async setup_project_folder(args) {
+    const dir = resolveUserPath(String(args.path ?? ''))
+    return setupProjectFolder({
+      dir,
+      name: args.name,
+      description: args.description,
+      sshUrl: args.ssh_url,
+      httpsUrl: args.https_url,
+    })
+  },
+
+  /** This Mac's shells for a browser elsewhere (only inside the Mac app, only when switched on there). */
+  terminal: args => terminalCall(args),
+
+  /** Kira in the Mac app's browser dock: open a page, read it, click and type in it. */
+  async browser(args) {
+    const hooks = host()
+    if (!hooks.browser) {
+      return { error: 'the browser needs the Kira Mac app (this bridge has none)', reason: 'unavailable' }
+    }
+    return hooks.browser(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 = safeCommand(args.command)
+    const hooks = host()
+    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' }
+    return new Promise(resolve => {
+      execFile('osascript', ['-e', terminalScript(dir, command)], err => {
+        resolve(err ? { error: err.message } : { opened: true, cwd: display(dir), command })
+      })
+    })
+  },
+}

package/src/service.mjs

@@ -10,7 +10,7 @@ import { KIRA_DIR, LOG_PATH } from './config.mjs'
 // working after npx's cache is pruned and survives package upgrades cleanly.
 const APP_DIR = join(KIRA_DIR, 'app')
 
-export const LABEL = 'com.kira.bridge'
+const LABEL = 'com.kira.bridge'
 const PLIST = join(homedir(), 'Library', 'LaunchAgents', `${LABEL}.plist`)
 
 function nodePath() {

package/src/session-tools.mjs

@@ -0,0 +1,20 @@
+// The bridge's read-only Claude Code tools: the projects and sessions on this Mac, a session's
+// transcript, and the designs found in them.
+import { listProjects, listSessions, readSession } from './claude-sessions.mjs'
+import { scanDesigns } from './claude-designs.mjs'
+
+export const sessionTools = {
+  async list_claude_projects(args) {
+    return listProjects(args.max)
+  },
+  async scan_claude_designs(args) {
+    const known = Array.isArray(args.known) ? args.known : []
+    return scanDesigns({ since: args.since, known, sessions: args.sessions })
+  },
+  async list_claude_sessions(args) {
+    return listSessions(args.max)
+  },
+  async read_claude_session(args) {
+    return readSession(String(args.session_id ?? ''), args.turns)
+  },
+}

package/src/terminal-command.mjs

@@ -0,0 +1,15 @@
+// open_terminal's command and the AppleScript that runs it in Terminal.app: pure, so it's tested
+// (test/terminal-command.test.mjs).
+
+/** Only characters a plain command needs: nothing that could break out of the script's quoting. */
+export function safeCommand(command) {
+  return String(command ?? '').replace(/[^\w\s./:@=-]/g, '')
+}
+
+/** Terminal.app, in front, running `command` in `dir`. */
+export function terminalScript(dir, command) {
+  return `tell application "Terminal"
+  activate
+  do script "cd ${JSON.stringify(dir)} && ${command}"
+end tell`
+}