kira-glasses-bridge 2.22.0 → 2.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.22.0",
+  "version": "2.24.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/agent-files.mjs

@@ -0,0 +1,139 @@
+// Subagents on this Mac: Claude Code's (one Markdown file each in ~/.claude/agents, front matter
+// for its settings and the body as its system prompt, with `memory: user` kept in
+// ~/.claude/agent-memory/<name>/MEMORY.md) and Codex's (~/.codex/agents/<name>.toml, listed only:
+// the bridge doesn't run Codex yet). Kira's agents are Claude Code subagents: she writes their
+// files and memory here, and a task runs as one (agents/claude.mjs).
+import { readdir, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  FOLDERS,
+  agentFolders,
+  display,
+  exists,
+  field,
+  inside,
+  readSmall,
+  refuseLinks,
+  splitFront,
+  writeWhole,
+} from './config-folders.mjs'
+
+const MAX_MD = 256 * 1024
+/** Claude Code loads the first 200 lines or 25KB of MEMORY.md; Kira keeps it to this. */
+const MAX_MEMORY = 64 * 1024
+const WHAT = 'a subagent'
+const NAMED = { loose: true }
+const claudeRoot = () => agentFolders()[0].root
+
+/** A TOML string value on its own line (`name = "x"`), enough for Codex's name and description. */
+const tomlField = (toml, key) => {
+  const m = new RegExp(`^${key}\\s*=\\s*(?:"((?:[^"\\\\]|\\\\.)*)"|'([^']*)')`, 'm').exec(toml)
+  return m ? (m[1] ?? m[2]).replace(/\\"/g, '"') : null
+}
+
+/** The name and description a tool shows, from a subagent file (its file name when it has none). */
+function agentSummary(text, slug, ext = '.md') {
+  if (ext === '.toml') {
+    return { name: tomlField(text, 'name') || slug, description: tomlField(text, 'description') || '' }
+  }
+  const { front } = splitFront(text)
+  return { name: field(front, 'name') || slug, description: field(front, 'description') || '' }
+}
+
+const memoryFile = (name, root = FOLDERS.claude.agentMemory()) => join(inside(root, name, WHAT, NAMED), 'MEMORY.md')
+
+/**
+ * Every subagent file: its slug (the file name), name, description, where it is, its text, which
+ * tool loads it, and for Claude Code's its MEMORY.md (empty when it has none).
+ */
+export async function listAgents(folders = agentFolders(), memoryRoot = FOLDERS.claude.agentMemory()) {
+  const agents = []
+  for (const { root, loadedBy, ext } of folders) {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => [])
+    for (const e of entries) {
+      if (!e.name.endsWith(ext) || !(e.isFile() || e.isSymbolicLink())) continue
+      const slug = e.name.slice(0, -ext.length)
+      const text = await readSmall(join(root, e.name), MAX_MD)
+      if (text === null) continue
+      const summary = agentSummary(text, slug, ext)
+      const memory = loadedBy.includes('claude') ? await readMemory(summary.name, memoryRoot) : ''
+      agents.push({ slug, ...summary, path: display(join(root, e.name)), md: text, providers: loadedBy, memory })
+    }
+  }
+  agents.sort((a, b) => a.slug.localeCompare(b.slug) || a.path.localeCompare(b.path))
+  return { root: display(folders[0].root), agents }
+}
+
+async function readMemory(name, root) {
+  try {
+    return (await readSmall(memoryFile(name, root), MAX_MEMORY)) ?? ''
+  } catch {
+    return '' // a name Kira can't make a folder of has no memory she can read
+  }
+}
+
+/** One of Claude Code's subagents, with its memory. */
+export async function readAgent({ slug } = {}, root = claudeRoot(), memoryRoot = FOLDERS.claude.agentMemory()) {
+  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
+  const md = await readSmall(file, MAX_MD)
+  if (md === null) return { error: `No subagent at ${display(file)}` }
+  const summary = agentSummary(md, slug)
+  return { slug, ...summary, path: display(file), md, memory: await readMemory(summary.name, memoryRoot) }
+}
+
+/**
+ * Write a Claude Code subagent's file, whole: replacing the one there, or with `create` only a new
+ * one (a subagent already there, Kira's or not, is never overwritten by a new one of that name).
+ */
+export async function writeAgent({ slug, md, create = false } = {}, root = claudeRoot()) {
+  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
+  const text = String(md ?? '')
+  if (!/^---\r?\n/.test(text)) throw new Error('A subagent file starts with front matter between --- lines')
+  if (Buffer.byteLength(text) > MAX_MD) throw new Error('That subagent file is too large')
+  await refuseLinks([root, file], 'edit')
+  if (create && (await exists(file))) throw new Error(`A subagent named ${slug} is already on your Mac`)
+  await writeWhole(file, text)
+  return { slug, ...agentSummary(text, slug), path: display(file), providers: ['claude'] }
+}
+
+/** Remove a Claude Code subagent's file. Its memory folder stays (it's what it learned). */
+export async function removeAgent({ slug } = {}, root = claudeRoot()) {
+  const file = inside(root, slug, WHAT, { ...NAMED, ext: '.md' })
+  await refuseLinks([root, file], 'remove')
+  const removed = await unlink(file).then(
+    () => true,
+    e => {
+      if (e.code === 'ENOENT') return false
+      throw e
+    },
+  )
+  return { slug, removed, path: display(file) }
+}
+
+/** Replace a subagent's MEMORY.md, whole (`name` is its front-matter name). */
+export async function writeAgentMemory({ name, md } = {}, root = FOLDERS.claude.agentMemory()) {
+  const file = memoryFile(name, root)
+  const text = String(md ?? '')
+  if (Buffer.byteLength(text) > MAX_MEMORY) throw new Error('That memory is too large')
+  await refuseLinks([root, join(file, '..'), file], 'edit')
+  await writeWhole(file, text)
+  return { name, path: display(file), memory: text }
+}
+
+/** Add a line to a subagent's MEMORY.md (what Kira keeps after a task); the oldest go when it's full. */
+export async function rememberAgent({ name, line } = {}, root = FOLDERS.claude.agentMemory()) {
+  const entry = `- ${String(line ?? '').replace(/\s+/g, ' ').trim().slice(0, 400)}`
+  let text = `${(await readMemory(name, root)).trimEnd()}\n${entry}`.trim() + '\n'
+  while (Buffer.byteLength(text) > MAX_MEMORY && text.includes('\n')) text = text.slice(text.indexOf('\n') + 1)
+  return writeAgentMemory({ name, md: text }, root)
+}
+
+/** The bridge tools (index.mjs). */
+export const agentTools = {
+  list_subagents: () => listAgents(),
+  read_subagent: args => readAgent(args),
+  write_subagent: args => writeAgent(args),
+  remove_subagent: args => removeAgent(args),
+  write_subagent_memory: args => writeAgentMemory(args),
+  remember_subagent: args => rememberAgent(args),
+}

package/src/agents/claude.mjs

@@ -128,6 +128,11 @@ function applyAnswer(name, input, request, answer, suggestions) {
   return { behavior: 'deny', message: `The user declined this${answer.text ? ` ("${answer.text}")` : ''}. Do not achieve the same effect another way; if the task cannot proceed without it, stop and say what you could not do.` }
 }
 
+/** Claude Code's own prompt, with what Kira adds for this run after it. */
+function systemPromptFor(persona) {
+  return { type: 'preset', preset: 'claude_code', ...(persona.systemPrompt ? { append: persona.systemPrompt } : {}) }
+}
+
 /**
  * Run one instruction in a Claude session.
  * @param io.emit(event)       a protocol event
@@ -221,8 +226,13 @@ async function run({ prompt, sessionId, cwd, policy, persona, settings, abort },
         // The model, effort and permission mode the person chose in the composer (plan mode: plan first).
         ...sdkOptionsFor(settings),
         ...(abort ? { abortController: abort } : {}),
-        // A team member's soul, skills and conventions ride on top of Claude Code's own prompt; its preset says which tools it does without.
-        ...(persona?.systemPrompt ? { systemPrompt: { type: 'preset', preset: 'claude_code', append: persona.systemPrompt } } : {}),
+        // A Kira agent runs as its Claude Code subagent (~/.claude/agents/<name>.md, agent-files.mjs): the
+        // file's body takes the place of Claude Code's default instructions, and what Kira adds for the
+        // run (its preset's conventions, the team) is appended. The claude_code preset has to be asked
+        // for: without it the SDK's bare prompt leaves the subagent's out (checked with SDK 0.3.278).
+        ...(persona?.agent ? { agent: persona.agent } : {}),
+        ...(persona?.systemPrompt || persona?.agent ? { systemPrompt: systemPromptFor(persona) } : {}),
+        // Its preset says which tools it does without (on top of any its file lists).
         ...(persona?.disallowedTools?.length ? { disallowedTools: persona.disallowedTools } : {}),
         // Claude as the person's Kira: her tools come from her own MCP server, with a token the API
         // made for this conversation. Claude Code loads them as it needs them (no tool ceiling).

package/src/config-folders.mjs

@@ -0,0 +1,124 @@
+// Where the coding agents on this Mac keep the things Kira reads and writes (skills, subagents and
+// their memory), and the one way to touch them: a name is one plain file or folder name inside its
+// folder, a folder that links elsewhere is never written through, and every write is whole and
+// atomic (a temporary file renamed over the old one).
+//
+// Which tool loads which folder, from their docs (2026-10-12):
+//   Claude Code (code.claude.com/docs/en/skills, /sub-agents): ~/.claude/skills/<name>/SKILL.md,
+//     ~/.claude/agents/<name>.md, and a subagent's `memory: user` in ~/.claude/agent-memory/<name>/.
+//     It doesn't read ~/.agents/skills.
+//   Codex (developers.openai.com/codex: skills, subagents): ~/.agents/skills/<name>/SKILL.md (the
+//     shared Agent Skills folder) and ~/.codex/agents/<name>.toml. ~/.codex/skills isn't in its docs,
+//     but the Codex app keeps its own skills there, so Kira lists them as Codex's.
+import { lstat, mkdir, readFile, rename, stat, writeFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join, relative } from 'node:path'
+
+const claudeHome = () => process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude')
+const codexHome = () => process.env.CODEX_HOME || join(homedir(), '.codex')
+
+/** Each provider's folders. `shared` is the cross-tool Agent Skills folder. */
+export const FOLDERS = {
+  claude: {
+    skills: () => join(claudeHome(), 'skills'),
+    agents: () => join(claudeHome(), 'agents'),
+    agentMemory: () => join(claudeHome(), 'agent-memory'),
+  },
+  codex: { skills: () => join(codexHome(), 'skills'), agents: () => join(codexHome(), 'agents') },
+  shared: { skills: () => join(homedir(), '.agents', 'skills') },
+}
+
+/** The skills folders and who loads each; Kira writes only the first (Claude Code's). */
+export const skillFolders = () => [
+  { root: FOLDERS.claude.skills(), loadedBy: ['claude'] },
+  { root: FOLDERS.shared.skills(), loadedBy: ['codex'] },
+  { root: FOLDERS.codex.skills(), loadedBy: ['codex'] },
+]
+
+/** The subagent folders, their file format and who loads each; Kira writes only Claude Code's. */
+export const agentFolders = () => [
+  { root: FOLDERS.claude.agents(), loadedBy: ['claude'], ext: '.md' },
+  { root: FOLDERS.codex.agents(), loadedBy: ['codex'], ext: '.toml' },
+]
+
+/** One plain name: lowercase letters, digits and dashes (and dots and underscores where `loose`). */
+const STRICT = /^[a-z0-9][a-z0-9-]{0,63}$/
+const LOOSE = /^[a-z0-9][a-z0-9._-]{0,63}$/
+export const isName = (s, loose = false) => (loose ? LOOSE : STRICT).test(String(s ?? ''))
+
+/** The path for `name` in `root`, after checking it can't name anything else. */
+export function inside(root, name, what, { loose = false, ext = '' } = {}) {
+  const s = String(name ?? '')
+  if (!isName(s, loose)) {
+    const allowed = loose
+      ? 'lowercase letters, digits, dots, dashes and underscores'
+      : 'lowercase letters, digits and dashes'
+    throw new Error(`“${s}” isn’t ${what} name (${allowed})`)
+  }
+  return join(root, s + ext)
+}
+
+/** As people read it: under the home folder with ~. */
+export function display(full) {
+  const rel = relative(homedir(), full)
+  return rel && !rel.startsWith('..') ? `~/${rel}` : full
+}
+
+const isSymlink = p =>
+  lstat(p).then(
+    s => s.isSymbolicLink(),
+    () => false,
+  )
+
+/** Anything on the way that links elsewhere is changed where it really is, never through the link. */
+export async function refuseLinks(paths, verb) {
+  for (const p of paths) {
+    if (await isSymlink(p)) throw new Error(`${display(p)} is a link to somewhere else; ${verb} it there`)
+  }
+}
+
+/** A file's text when it's a file no bigger than `max`, else null. */
+export async function readSmall(file, max) {
+  const st = await stat(file).catch(() => null)
+  if (!st?.isFile() || st.size > max) return null
+  return readFile(file, 'utf8').catch(() => null)
+}
+
+/** Whether something is at `p`. */
+export const exists = p => stat(p).then(
+  () => true,
+  () => false,
+)
+
+/** Write `text` to `file` whole: its folder made, through a temporary file renamed over the old one. */
+export async function writeWhole(file, text) {
+  const dir = join(file, '..')
+  await mkdir(dir, { recursive: true })
+  const tmp = join(dir, `.${file.slice(dir.length + 1)}.${process.pid}.tmp`)
+  await writeFile(tmp, text, 'utf8')
+  await rename(tmp, file)
+}
+
+/** Front matter between --- lines, and the rest. */
+export function splitFront(md) {
+  const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/.exec(md)
+  return m ? { front: m[1].replace(/\r\n/g, '\n'), body: md.slice(m[0].length) } : { front: '', body: md }
+}
+
+/** A front-matter value: quoted or plain on its line, or a `|` / `>` block below it. */
+export 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
+}

package/src/index.mjs

@@ -2,6 +2,7 @@
 // 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 { AGENTS } from './agents/index.mjs'
 import { claudeTools } from './agents/claude-local.mjs'
 import { connect, disconnect, sendIfLive } from './connection.mjs'
@@ -11,6 +12,7 @@ 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 { skillTools } from './skill-files.mjs'
 import { initTerminals } from './terminals.mjs'
 
 const { version: BRIDGE_VERSION } = createRequire(import.meta.url)('../package.json')
@@ -22,6 +24,8 @@ const tools = {
   ...jobTools,
   ...gitTools,
   ...claudeTools,
+  ...skillTools,
+  ...agentTools,
 }
 
 /** What this bridge build implements, told to the API after its hello. */

package/src/skill-files.mjs

@@ -0,0 +1,119 @@
+// Skills on this Mac: one SKILL.md each in a folder of its own, in Claude Code's skills folder and
+// in Codex's (config-folders.mjs says which loads which). Kira lists all of them, each with the
+// tools that load it (a skill linked into both folders is both's), and writes and removes the ones
+// a person makes in Kira, in Claude Code's folder.
+import { readdir, realpath, rmdir, unlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import {
+  display,
+  exists,
+  field,
+  inside,
+  isName,
+  readSmall,
+  refuseLinks,
+  skillFolders,
+  splitFront,
+  writeWhole,
+} from './config-folders.mjs'
+
+/** A SKILL.md past this isn't one: skipped when listing, refused when writing. */
+const MAX_MD = 256 * 1024
+const WHAT = 'a skill folder'
+/** Where Kira writes: Claude Code's folder. */
+const writeRoot = () => skillFolders()[0].root
+
+/** The name and description a tool shows, from a SKILL.md (the folder's name when it has none). */
+export function skillSummary(md, slug) {
+  const { front, body } = splitFront(md)
+  const firstLine = body.split('\n').map(l => l.trim()).find(Boolean) ?? ''
+  return { name: field(front, 'name') || slug, description: field(front, 'description') || firstLine }
+}
+
+/** The skills in one folder. */
+async function skillsIn(root) {
+  const entries = await readdir(root, { withFileTypes: true }).catch(e => {
+    if (e.code === 'ENOENT') return []
+    throw e
+  })
+  const out = []
+  for (const e of entries) {
+    if (!isName(e.name) || !(e.isDirectory() || e.isSymbolicLink())) continue
+    const dir = join(root, e.name)
+    const md = await readSmall(join(dir, 'SKILL.md'), MAX_MD)
+    if (md !== null) out.push({ slug: e.name, dir, real: await realpath(dir).catch(() => dir), md })
+  }
+  return out
+}
+
+/**
+ * Every skill in every folder: its slug, name, description, where it is, its SKILL.md, and which
+ * tools load it (`providers`). One folder linked into another is one skill, loaded by both.
+ */
+export async function listSkills(folders = skillFolders()) {
+  const byReal = new Map()
+  for (const { root, loadedBy } of folders) {
+    for (const s of await skillsIn(root)) {
+      const had = byReal.get(s.real)
+      if (had) had.providers = [...new Set([...had.providers, ...loadedBy])]
+      else {
+        const skill = { slug: s.slug, ...skillSummary(s.md, s.slug), path: display(s.dir), md: s.md }
+        byReal.set(s.real, { ...skill, providers: [...loadedBy] })
+      }
+    }
+  }
+  // By name; a name in two folders keeps the folders' order (Claude Code's first).
+  const skills = [...byReal.values()].sort((a, b) => a.slug.localeCompare(b.slug))
+  return { root: display(folders[0].root), skills }
+}
+
+/** One skill's SKILL.md, from Claude Code's folder. */
+export async function readSkill({ slug } = {}, root = writeRoot()) {
+  const dir = inside(root, slug, WHAT)
+  const md = await readSmall(join(dir, 'SKILL.md'), MAX_MD)
+  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 = writeRoot()) {
+  const dir = inside(root, slug, WHAT)
+  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 exists(file))) throw new Error(`A skill named ${slug} is already on your Mac`)
+  await writeWhole(file, text)
+  return { slug, ...skillSummary(text, slug), path: display(dir), providers: ['claude'] }
+}
+
+/**
+ * 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 = writeRoot()) {
+  const dir = inside(root, slug, WHAT)
+  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 = {
+  list_skills: () => listSkills(),
+  read_skill: args => readSkill(args),
+  write_skill: args => writeSkill(args),
+  remove_skill: args => removeSkill(args),
+}