kira-glasses-bridge 2.27.0 → 2.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.27.0",
+  "version": "2.28.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,6 +19,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.278",
+    "smol-toml": "1.9.0",
     "ws": "^8.18.0"
   },
   "keywords": [

package/src/agent-files.mjs

@@ -1,10 +1,12 @@
-// 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).
+// Subagents on this Mac, in each agent's own format: 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 (one TOML file each
+// in ~/.codex/agents: name, description, developer_instructions and any config key; Codex keeps no
+// memory per agent). Kira's agents are one or the other: she writes their files (and a Claude Code
+// one's memory) here, and a task runs as one (agents/claude.mjs, agents/codex-agent.mjs).
 import { readdir, unlink } from 'node:fs/promises'
 import { join } from 'node:path'
+import { parse } from 'smol-toml'
 import {
   FOLDERS,
   agentFolders,
@@ -29,12 +31,34 @@ const LOAD_BYTES = 25 * 1024
 const KIRAS_LINE = /^- \d{4}-\d{2}-\d{2}: /
 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. */
+/** Each agent's folder and file: where Kira writes it, and what a file of it must be. */
+const KINDS = {
+  claude: { root: () => agentFolders()[0].root, ext: '.md', check: checkMd },
+  codex: { root: () => agentFolders()[1].root, ext: '.toml', check: checkToml },
+}
+const kindOf = provider => KINDS[provider ?? 'claude'] ?? KINDS.claude
+
+function checkMd(text) {
+  if (!/^---\r?\n/.test(text)) throw new Error('A subagent file starts with front matter between --- lines')
+}
+
+function checkToml(text) {
+  try {
+    parse(text)
+  } catch (err) {
+    throw new Error(`A Codex agent file is TOML: ${err.message}`)
+  }
+}
+
+/** A Codex agent file's string field, or null (and null for all when it isn't TOML). */
 const tomlField = (toml, key) => {
-  const m = new RegExp(`^${key}\\s*=\\s*(?:"((?:[^"\\\\]|\\\\.)*)"|'([^']*)')`, 'm').exec(toml)
-  return m ? (m[1] ?? m[2]).replace(/\\"/g, '"') : null
+  try {
+    const v = parse(toml)[key]
+    return typeof v === 'string' ? v : null
+  } catch {
+    return null
+  }
 }
 
 /** The name and description a tool shows, from a subagent file (its file name when it has none). */
@@ -78,34 +102,44 @@ async function readMemory(name, root) {
   }
 }
 
-/** 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' })
+/**
+ * One subagent, `provider`'s (Claude Code's by default), with its memory (Claude Code's only). `md`
+ * is its file's text whatever the format: Markdown for Claude Code, TOML for Codex.
+ */
+export async function readAgent({ slug, provider } = {}, root, memoryRoot = FOLDERS.claude.agentMemory()) {
+  const kind = kindOf(provider)
+  const file = inside(root ?? kind.root(), slug, WHAT, { ...NAMED, ext: kind.ext })
   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) }
+  const summary = agentSummary(md, slug, kind.ext)
+  const memory = kind === KINDS.claude ? await readMemory(summary.name, memoryRoot) : ''
+  return { slug, ...summary, path: display(file), md, memory }
 }
 
 /**
- * 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).
+ * Write a subagent's file (`provider`'s), 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' })
+export async function writeAgent({ slug, md, create = false, provider } = {}, root) {
+  const kind = kindOf(provider)
+  const dir = root ?? kind.root()
+  const file = inside(dir, slug, WHAT, { ...NAMED, ext: kind.ext })
   const text = String(md ?? '')
-  if (!/^---\r?\n/.test(text)) throw new Error('A subagent file starts with front matter between --- lines')
+  kind.check(text)
   if (Buffer.byteLength(text) > MAX_MD) throw new Error('That subagent file is too large')
-  await refuseLinks([root, file], 'edit')
+  await refuseLinks([dir, 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'] }
+  const providers = [kind === KINDS.codex ? 'codex' : 'claude']
+  return { slug, ...agentSummary(text, slug, kind.ext), path: display(file), providers }
 }
 
-/** 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')
+/** Remove a subagent's file (`provider`'s). A Claude Code one's memory folder stays (it's what it learned). */
+export async function removeAgent({ slug, provider } = {}, root) {
+  const kind = kindOf(provider)
+  const dir = root ?? kind.root()
+  const file = inside(dir, slug, WHAT, { ...NAMED, ext: kind.ext })
+  await refuseLinks([dir, file], 'remove')
   const removed = await unlink(file).then(
     () => true,
     e => {

package/src/agents/codex-agent.mjs

@@ -0,0 +1,47 @@
+// A Kira agent that runs on Codex: its Codex agent file (~/.codex/agents/<handle>.toml, written by
+// agent-files.mjs). Codex's app server has no "start this thread as agent X" (its agent roles are a
+// config layer it applies when it spawns a subagent: codex-rs/agent-roles), so a job applies the
+// file the way Codex applies a role: its `developer_instructions` are the thread's developer
+// instructions (what Kira adds for the run after them) and its other settings (model,
+// model_reasoning_effort…) the thread's config. Fields from codex-rs/agent-roles/src/agent_role_config.rs.
+import { parse } from 'smol-toml'
+import { FOLDERS, display, inside, readSmall } from '../config-folders.mjs'
+
+const MAX_TOML = 256 * 1024
+/** What names and describes the agent: Codex reads them for its spawn list, never as config. */
+const NOT_CONFIG = new Set(['name', 'description', 'nickname_candidates', 'developer_instructions'])
+
+/** A table's settings as Codex's config overrides take them: one dotted key per value. */
+function flatten(table, prefix = '', out = {}) {
+  for (const [k, v] of Object.entries(table)) {
+    const key = prefix + k
+    if (v && typeof v === 'object' && !Array.isArray(v) && !(v instanceof Date)) flatten(v, `${key}.`, out)
+    else out[key] = v instanceof Date ? v.toISOString() : v
+  }
+  return out
+}
+
+/** An agent file as a thread takes it: its instructions and the rest of its config. Throws when it isn't TOML. */
+export function roleLayer(toml) {
+  const table = parse(String(toml ?? ''))
+  const rest = Object.fromEntries(Object.entries(table).filter(([k]) => !NOT_CONFIG.has(k)))
+  const said = table.developer_instructions
+  return { instructions: typeof said === 'string' ? said.trim() : '', config: flatten(rest) }
+}
+
+/** The thread's developer instructions: the agent's own, then what Kira adds for this run. */
+export const developerInstructions = (role, persona) =>
+  [role?.instructions, persona?.systemPrompt].filter(Boolean).join('\n\n')
+
+/** The Codex agent a job runs as (null for none); throws, saying where, when its file isn't there. */
+export async function codexAgentOf(persona, root = FOLDERS.codex.agents()) {
+  if (!persona?.agent) return null
+  const file = inside(root, persona.agent, 'a Codex agent', { loose: true, ext: '.toml' })
+  const toml = await readSmall(file, MAX_TOML)
+  if (toml === null) throw new Error(`@${persona.agent}'s Codex agent isn't on this Mac (${display(file)})`)
+  try {
+    return roleLayer(toml)
+  } catch (err) {
+    throw new Error(`${display(file)} isn't TOML Codex can read: ${err.message}`)
+  }
+}

package/src/agents/codex.mjs

@@ -6,6 +6,8 @@ import { TEXT_CAP, short } from './claude-calls.mjs'
 import { callsOf, codexOptionsFor, itemAction, itemResult, strictest } from './codex-items.mjs'
 import { codexBin, openCodex } from './codex-rpc.mjs'
 import { kiraDecides } from './checks.mjs'
+import { codexAgentOf, developerInstructions } from './codex-agent.mjs'
+import { kiraSkillRoots } from '../kira-plugin.mjs'
 
 const COMMAND = 'item/commandExecution/requestApproval'
 const APPROVALS = new Set([COMMAND, 'item/fileChange/requestApproval'])
@@ -111,8 +113,14 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   try {
     await codex.request('initialize', { clientInfo: { name: 'kira', title: 'Kira', version: '1' }, capabilities: null })
     codex.notify('initialized')
-    const config = persona?.kiraTools ? kiraServer(persona.kiraTools) : undefined
-    const instructions = persona?.systemPrompt ? { developerInstructions: persona.systemPrompt } : {}
+    // A Kira agent on Codex: its agent file, applied as Codex applies a role (codex-agent.mjs).
+    const role = await codexAgentOf(persona)
+    // Kira's built-in skills, as Codex's own for this app server: the folder Claude Code's plugin uses.
+    const roots = await kiraSkillRoots(persona)
+    if (roots.length) await codex.request('skills/extraRoots/set', { extraRoots: roots })
+    const config = { ...role?.config, ...(persona?.kiraTools ? kiraServer(persona.kiraTools) : {}) }
+    const said = developerInstructions(role, persona)
+    const instructions = said ? { developerInstructions: said } : {}
     const opened = thread
       ? await codex.request('thread/resume', { threadId: thread, cwd, ...options, ...instructions, config })
       : await codex.request('thread/start', { cwd, ...options, ...instructions, config })

package/src/config-folders.mjs

@@ -38,7 +38,7 @@ export const skillFolders = () => [
   { root: FOLDERS.codex.skills(), loadedBy: ['codex'] },
 ]
 
-/** The subagent folders, their file format and who loads each; Kira writes only Claude Code's. */
+/** The subagent folders, their file format and who loads each; Kira writes both (agent-files.mjs). */
 export const agentFolders = () => [
   { root: FOLDERS.claude.agents(), loadedBy: ['claude'], ext: '.md' },
   { root: FOLDERS.codex.agents(), loadedBy: ['codex'], ext: '.toml' },

package/src/kira-plugin.mjs

@@ -1,8 +1,10 @@
-// Kira's built-in skills as Claude Code takes skills that come with something: a plugin, on this
-// Mac (~/.kira/claude-plugin: .claude-plugin/plugin.json and skills/<name>/SKILL.md). The API sends
-// the ones a person's Kira has with each job she runs as Claude Code (persona.skills); this brings
-// the folder in line with them (each written whole, the ones gone removed) and Claude Code loads it
-// with the job (the Agent SDK's `plugins`), so it reads them as its own: /kira:draft-page.
+// Kira's built-in skills, one folder on this Mac that both agents load as their own. The API sends
+// the ones a person's Kira has with each job (persona.skills); this brings the folder in line with
+// them (each written whole, the ones gone removed). It is a Claude Code plugin
+// (~/.kira/claude-plugin: .claude-plugin/plugin.json and skills/<name>/SKILL.md), which Claude Code
+// loads with the job (the Agent SDK's `plugins`: /kira:draft-page). Its skills/ folder is plain
+// Agent Skills (<name>/SKILL.md), which Codex loads as an extra skills root for the job
+// (`skills/extraRoots/set` on its app server: $draft-page).
 import { readdir, rm } from 'node:fs/promises'
 import { join } from 'node:path'
 import { KIRA_DIR } from './config.mjs'
@@ -47,15 +49,27 @@ export function writeKiraPlugin(skills, root = pluginRoot()) {
 }
 
 /**
- * The query options that load Kira's skills for a job: none when it has none, or when the folder
- * can't be written (the job still runs; `warn` says why).
+ * The folder written for a job's skills, or null when it has none or it can't be written (the job
+ * still runs; `warn` says why, naming the agent that goes without them).
  */
-export async function kiraPluginOptions(persona, warn = log, root = pluginRoot()) {
-  if (!Array.isArray(persona?.skills) || !persona.skills.length) return {}
+async function writtenFor(persona, agent, warn, root) {
+  if (!Array.isArray(persona?.skills) || !persona.skills.length) return null
   try {
-    return { plugins: [{ type: 'local', path: await writeKiraPlugin(persona.skills, root) }] }
+    return await writeKiraPlugin(persona.skills, root)
   } catch (err) {
-    warn(`Kira's skills couldn't be written for Claude Code: ${err.message}`)
-    return {}
+    warn(`Kira's skills couldn't be written for ${agent}: ${err.message}`)
+    return null
   }
 }
+
+/** The Agent SDK query options that load Kira's skills for a Claude Code job (none without them). */
+export async function kiraPluginOptions(persona, warn = log, root = pluginRoot()) {
+  const path = await writtenFor(persona, 'Claude Code', warn, root)
+  return path ? { plugins: [{ type: 'local', path }] } : {}
+}
+
+/** The skills roots Codex is given for a job (`skills/extraRoots/set`): the plugin's skills/ folder, or none. */
+export async function kiraSkillRoots(persona, warn = log, root = pluginRoot()) {
+  const path = await writtenFor(persona, 'Codex', warn, root)
+  return path ? [join(path, 'skills')] : []
+}