kira-glasses-bridge 2.26.0 → 2.28.0

package/package.json

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

@@ -1,18 +1,17 @@
 // Claude Code as an agent, through the Agent SDK. Runs in this process on the
 // user's Mac with their own Claude login; files never leave the machine.
 import { query } from '@anthropic-ai/claude-agent-sdk'
-import { resolve, sep } from 'node:path'
 import {
   NOT_ANOTHER_WAY,
   TEXT_CAP,
   applyAnswer,
   describeAction,
-  displayPath,
   short,
   toRequest,
 } from './claude-calls.mjs'
 import { kiraDecides } from './checks.mjs'
 import { sdkOptionsFor } from './settings.mjs'
+import { kiraPluginOptions } from '../kira-plugin.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}` } })
@@ -44,36 +43,17 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   /** What Kira's rules said about each tool call, by its id, for the question if Claude Code asks. */
   const verdicts = new Map()
 
-  // A member with a restricted shell (a designer, a researcher) runs only what its preset allows.
-  const shellAllow = persona?.shellAllow ? new RegExp(persona.shellAllow) : null
-  // A member that only produces artifacts (a designer, a researcher) writes nowhere but its output folders.
-  const within = (persona?.writeWithin ?? []).map(d => resolve(cwd, d))
-  const writeTools = new Set(['Write', 'Edit', 'MultiEdit', 'NotebookEdit'])
   /** Refused before it runs: the job shows why, and Claude is told (`told`, when it needs more). */
   const refuse = (tool, reason, told = reason) => {
     const answer = { optionIds: ['deny'] }
     io.emit({ kind: 'request_resolved', id: `policy-${Date.now().toString(36)}`, answer, by: 'policy', tool, reason })
     return hookAnswer('deny', told)
   }
-  // Pre-tool hook: the member's limits, then Kira's rules (io.check asks the API). Allow and deny
+  // Pre-tool hook: Kira's rules (io.check asks the API), a member's role among them. Allow and deny
   // are final; ask forces the question even where the person's own Claude Code settings would allow
   // it; a call no rule decides is left to Claude Code's permission mode, which asks through canUseTool.
   const preToolUse = async (input, toolUseID) => {
     if (input.hook_event_name !== 'PreToolUse') return {}
-    if (within.length && writeTools.has(input.tool_name)) {
-      const target = resolve(cwd, String(input.tool_input?.file_path ?? input.tool_input?.notebook_path ?? ''))
-      if (!within.some(dir => target === dir || target.startsWith(dir + sep))) {
-        const where = `${persona.writeWithin.join(', ')}; ${displayPath(target, cwd)} is off limits`
-        const instead = 'Describe what an engineer should change in your spec instead.'
-        return refuse(input.tool_name, `${persona.name} only writes under ${where}. ${instead}`)
-      }
-    }
-    // Every command in a chain ("ls; rm -rf x", "a && b", "a | b") has to be allowed, not only the first.
-    const segments = c => String(c ?? '').split(/&&|\|\||;|\|/).map(x => x.trim()).filter(Boolean)
-    if (shellAllow && input.tool_name === 'Bash' && !segments(input.tool_input?.command).every(seg => shellAllow.test(seg))) {
-      const only = 'uses the shell only for git and for reading files; run that another way or leave it.'
-      return refuse('Bash', `${persona.name} ${only}`)
-    }
     if (QUESTIONS.has(input.tool_name)) return {}
     const verdict = await io.check({ tool: input.tool_name, input: input.tool_input ?? {}, cwd })
     // Kept only for a question that may follow: an ask, or Claude Code's own mode asking.
@@ -134,6 +114,8 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
         // 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).
         ...(persona?.kiraTools ? { mcpServers: { kira: kiraServer(persona.kiraTools) } } : {}),
+        // Her built-in skills, as Claude Code's own: a plugin the bridge writes (kira-plugin.mjs).
+        ...(await kiraPluginOptions(persona)),
         canUseTool,
         hooks: { PreToolUse: [{ hooks: [preToolUse] }] },
         ...(process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}),

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-items.mjs

@@ -0,0 +1,96 @@
+// Codex's thread items and settings in Kira's agent protocol (protocol.mjs). Pure.
+import { displayPath, short } from './claude-calls.mjs'
+
+/**
+ * The composer's permission modes in Codex's own terms: accept edits = it writes in the project
+ * (workspace-write) and asks before commands it doesn't trust; ask before edits = read-only, so every
+ * change and command asks; plan = read-only and it never asks, so it can only look and propose.
+ */
+const MODES = {
+  acceptEdits: { sandbox: 'workspace-write', approvalPolicy: 'untrusted' },
+  default: { sandbox: 'read-only', approvalPolicy: 'untrusted' },
+  plan: { sandbox: 'read-only', approvalPolicy: 'never' },
+}
+/** The composer's older names for the same modes. */
+const OLD_MODES = { auto: 'acceptEdits', ask: 'default' }
+const EFFORTS = new Set(['low', 'medium', 'high'])
+/** A model as Codex's own list names it (codex-local.mjs); never a Claude one. */
+const MODEL = /^(?!claude)[a-z0-9][a-z0-9.-]{0,63}$/
+
+/** thread/start's options for these settings; what's unset is left to the person's ~/.codex/config.toml. */
+export function codexOptionsFor(settings, kiraDecides = true) {
+  const s = settings ?? {}
+  const named = OLD_MODES[s.mode] ?? s.mode
+  const mode = Object.hasOwn(MODES, named) ? named : 'acceptEdits'
+  // Without Kira deciding each call, nothing is written without asking (as with Claude Code).
+  const chosen = kiraDecides || mode === 'plan' ? MODES[mode] : MODES.default
+  return {
+    ...chosen,
+    ...(typeof s.model === 'string' && MODEL.test(s.model) ? { model: s.model } : {}),
+    ...(EFFORTS.has(s.effort) ? { effort: s.effort } : {}),
+  }
+}
+
+/** Codex runs each command as `/bin/zsh -lc '<script>'`. */
+const WRAPPED = /^(?:\/(?:usr\/)?bin\/)?(?:ba|z)?sh -l?c (?:'((?:[^']|'\\'')*)'|"((?:[^"\\$`]|\\["\\$`])*)")$/s
+
+/** The script Codex runs, as the person would have typed it; anything unusual is left as it is (and asks). */
+export function scriptOf(command) {
+  const m = WRAPPED.exec(String(command ?? '').trim())
+  if (!m) return String(command ?? '')
+  return m[1] !== undefined ? m[1].replaceAll("'\\''", "'") : m[2].replace(/\\(["\\$`])/g, '$1')
+}
+
+/** Codex's call as Kira's rules read it: a command is Bash, each changed file an Edit. */
+export function callsOf(method, params, changes) {
+  if (method === 'item/commandExecution/requestApproval') {
+    return [{ tool: 'Bash', input: { command: scriptOf(params.command) }, cwd: params.cwd }]
+  }
+  return (changes ?? []).map(c => ({ tool: 'Edit', input: { file_path: c.path } }))
+}
+
+/** The strictest of several verdicts: any refusal refuses, any ask asks, and allow only when all allow. */
+export function strictest(verdicts) {
+  const order = ['deny', 'ask', 'mode', 'allow']
+  return [...verdicts].sort((a, b) => order.indexOf(a.effect) - order.indexOf(b.effect))[0] ?? null
+}
+
+const act = (type, label, target, more = {}) => ({ type, label, target, ...more })
+
+/** One of Codex's items as a protocol action (null for what isn't one: messages, reasoning). */
+export function itemAction(item, cwd) {
+  switch (item.type) {
+    case 'commandExecution': {
+      const command = scriptOf(item.command)
+      return act('run', 'Run', short(command, 400), { tool: 'Bash', detail: { command: short(command, 2000) } })
+    }
+    case 'fileChange': {
+      const paths = (item.changes ?? []).map(c => displayPath(c.path, cwd))
+      const more = paths.length > 1 ? ` and ${paths.length - 1} more` : ''
+      const diff = (item.changes ?? []).map(c => c.diff).join('\n')
+      return act('edit', 'Edit', `${paths[0] ?? ''}${more}`, { tool: 'Edit', detail: { content: short(diff, 6000) } })
+    }
+    case 'mcpToolCall':
+      return act('other', item.tool, short(JSON.stringify(item.arguments ?? {}), 200), {
+        tool: `mcp__${item.server}__${item.tool}`,
+      })
+    case 'webSearch':
+      return act('fetch', 'Search the web', short(item.query ?? '', 160), { tool: 'WebSearch' })
+    case 'plan':
+      return act('plan', 'Plan', short(item.text, 160), { tool: 'Plan' })
+    case 'collabAgentToolCall':
+      return act('delegate', 'Subtask', short(item.prompt ?? '', 160), { tool: 'Subtask' })
+    default:
+      return null
+  }
+}
+
+/** A finished item's outcome: whether it went through, and what it said. */
+export function itemResult(item) {
+  if (item.type === 'commandExecution') {
+    const ok = item.status === 'completed' && (item.exitCode ?? 0) === 0
+    return { ok, preview: short(String(item.aggregatedOutput ?? '').trim(), 240) }
+  }
+  if (item.type === 'mcpToolCall') return { ok: !item.error && item.status === 'completed', preview: '' }
+  return { ok: item.status ? item.status === 'completed' : true, preview: '' }
+}

package/src/agents/codex-local.mjs

@@ -0,0 +1,42 @@
+// Codex on this Mac, as the person signed in to it: whether it's there and signed in, and the models
+// it offers them (its own list, so the composer never names a model Codex wouldn't take).
+import { homedir } from 'node:os'
+import { codexBin, openCodex } from './codex-rpc.mjs'
+
+const ASK_MS = 15_000
+
+/** Codex's models for this person, as `model/list` gives them: the default first. */
+export function modelsOf(list) {
+  const models = (Array.isArray(list?.data) ? list.data : [])
+    .filter(m => !m.hidden)
+    .map(m => ({
+      id: String(m.model ?? m.id ?? ''),
+      label: String(m.displayName || m.model || m.id || ''),
+      description: typeof m.description === 'string' ? m.description : undefined,
+      default: !!m.isDefault,
+    }))
+    .filter(m => m.id)
+  return [...models.filter(m => m.default), ...models.filter(m => !m.default)]
+}
+
+/** Whether Codex is here and signed in, and its models: `{ installed, signedIn, models }` or `{ error }`. */
+async function codexModels() {
+  const bin = codexBin()
+  if (!bin) return { installed: false, signedIn: false, models: [] }
+  const codex = openCodex(bin, { cwd: homedir(), env: process.env, onNotify() {}, onRequest: async () => ({}) })
+  const timer = setTimeout(() => codex.close(), ASK_MS)
+  try {
+    await codex.request('initialize', { clientInfo: { name: 'kira', title: 'Kira', version: '1' }, capabilities: null })
+    codex.notify('initialized')
+    const account = await codex.request('account/read', {})
+    if (!account?.account) return { installed: true, signedIn: false, models: [] }
+    return { installed: true, signedIn: true, models: modelsOf(await codex.request('model/list', {})) }
+  } catch (err) {
+    return { error: `Codex didn't answer: ${err.message}` }
+  } finally {
+    clearTimeout(timer)
+    codex.close()
+  }
+}
+
+export const codexTools = { codex_models: codexModels }

package/src/agents/codex-rpc.mjs

@@ -0,0 +1,91 @@
+// Codex's app server (`codex app-server`): JSON-RPC, one message per line over stdio. Requests get
+// answers by id; notifications and the server's own requests (approvals) go to the handlers.
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { delimiter, join } from 'node:path'
+
+/** Where ChatGPT's Mac app keeps the Codex it ships. */
+const CHATGPT_CODEX = '/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex'
+
+/** The person's own Codex: KIRA_CODEX_BIN, then `codex` on the PATH, then the one in ChatGPT.app. */
+export function codexBin(env = process.env) {
+  if (env.KIRA_CODEX_BIN) return env.KIRA_CODEX_BIN
+  const onPath = String(env.PATH ?? '')
+    .split(delimiter)
+    .filter(Boolean)
+    .map(dir => join(dir, 'codex'))
+    .find(p => existsSync(p))
+  if (onPath) return onPath
+  return existsSync(CHATGPT_CODEX) ? CHATGPT_CODEX : null
+}
+
+/**
+ * Start Codex's app server. `onNotify(method, params)` hears what happens; `onRequest(method, params)`
+ * answers what Codex asks (its result is sent back). Returns { request, close, done }.
+ */
+export function openCodex(bin, { cwd, env, onNotify, onRequest }) {
+  const child = spawn(bin, ['app-server'], { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] })
+  const waiting = new Map()
+  let seq = 0
+  let buffer = ''
+  let stderr = ''
+  const write = msg => child.stdin.writable && child.stdin.write(`${JSON.stringify(msg)}\n`)
+
+  const handle = async msg => {
+    if (msg.id != null && msg.method) {
+      try {
+        write({ id: msg.id, result: await onRequest(msg.method, msg.params ?? {}) })
+      } catch (err) {
+        write({ id: msg.id, error: { code: -32603, message: String(err?.message ?? err) } })
+      }
+    } else if (msg.id != null) {
+      const w = waiting.get(msg.id)
+      waiting.delete(msg.id)
+      if (msg.error) w?.reject(new Error(msg.error.message ?? 'Codex refused the request'))
+      else w?.resolve(msg.result)
+    } else if (msg.method) {
+      onNotify(msg.method, msg.params ?? {})
+    }
+  }
+  child.stdout.on('data', chunk => {
+    buffer += chunk
+    for (let i = buffer.indexOf('\n'); i >= 0; i = buffer.indexOf('\n')) {
+      const line = buffer.slice(0, i).trim()
+      buffer = buffer.slice(i + 1)
+      if (!line) continue
+      try {
+        void handle(JSON.parse(line))
+      } catch {
+        // Not a protocol line: ignored.
+      }
+    }
+  })
+  child.stderr.on('data', chunk => {
+    stderr = (stderr + chunk).slice(-2000)
+  })
+  const done = new Promise(resolve => {
+    const end = err => {
+      const why = err?.message ?? (stderr.trim().split('\n').pop() || 'Codex stopped')
+      for (const w of waiting.values()) w.reject(new Error(why))
+      waiting.clear()
+      resolve(why)
+    }
+    child.on('error', end)
+    child.on('exit', () => end())
+  })
+  const request = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = ++seq
+      waiting.set(id, { resolve, reject })
+      if (!write({ id, method, params })) {
+        waiting.delete(id)
+        reject(new Error('Codex is not running'))
+      }
+    })
+  const notify = (method, params) => write(params ? { method, params } : { method })
+  const close = () => {
+    child.stdin.end()
+    child.kill()
+  }
+  return { request, notify, close, done }
+}

package/src/agents/codex.mjs

@@ -0,0 +1,147 @@
+// Codex as an agent, through its app server (codex-rpc.mjs). Runs on the person's Mac with their own
+// Codex and its sign-in (ChatGPT or their key); files never leave the machine. Each command and file
+// change Codex asks about is decided by Kira's rules (io.check), and by the person when they ask.
+import { permissionOptions, requestId } from './protocol.mjs'
+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'])
+const NOT_INSTALLED =
+  'Codex is not installed on this Mac. Install it (npm install -g @openai/codex, or the ChatGPT app) and sign in.'
+
+/** Kira's MCP server as Codex connects to it: Streamable HTTP, the token read from the environment. */
+const kiraServer = ({ url }) => ({ 'mcp_servers.kira.url': url, 'mcp_servers.kira.bearer_token_env_var': 'KIRA_TOKEN' })
+
+/**
+ * Run one instruction in a Codex thread. Same contract as claude.mjs:
+ * io.emit(event), io.ask(request, signal), io.check(call); returns { ok, text, error, sessionId, stats }.
+ */
+async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
+  const bin = codexBin()
+  if (!bin) {
+    io.emit({ kind: 'result', ok: false, error: NOT_INSTALLED, sessionId })
+    return { ok: false, error: NOT_INSTALLED, sessionId }
+  }
+  const { effort, ...options } = codexOptionsFor(settings, kiraDecides())
+  let thread = sessionId ?? null
+  let turnId = null
+  let text = ''
+  let error = null
+  /** The files each change will touch, from when it started: what its approval is checked on. */
+  const changes = new Map()
+  let finished
+  const ended = new Promise(resolve => (finished = resolve))
+
+  const decide = async (method, params) => {
+    const calls = callsOf(method, params, changes.get(params.itemId)).map(c => ({ ...c, cwd: c.cwd ?? cwd }))
+    const verdict = strictest(await Promise.all(calls.map(c => io.check(c)))) ?? { effect: 'mode' }
+    if (verdict.effect === 'allow') return { decision: 'accept' }
+    const action = itemAction(
+      method === COMMAND
+        ? { type: 'commandExecution', command: params.command }
+        : { type: 'fileChange', changes: changes.get(params.itemId) ?? [] },
+      cwd,
+    )
+    if (verdict.effect === 'deny') {
+      const reason = `Kira: ${verdict.why ?? 'your rules'}${verdict.rule ? ` (${verdict.rule})` : ''}`
+      const id = `policy-${Date.now().toString(36)}`
+      const answer = { optionIds: ['deny'] }
+      io.emit({ kind: 'request_resolved', id, answer, by: 'policy', tool: action.tool, reason })
+      return { decision: 'decline' }
+    }
+    const request = {
+      id: requestId(),
+      type: 'permission',
+      title: `Codex wants to ${action.label.toLowerCase()} ${action.target}`.trim(),
+      detail: short(action.detail?.command ?? action.detail?.content ?? params.reason ?? '', 2000) || undefined,
+      options: permissionOptions(verdict.suggest),
+      action: { tool: action.tool, label: action.label, target: action.target },
+      ...(verdict.suggest ? { rule: verdict.suggest } : {}),
+      ...(verdict.why ? { why: verdict.why } : {}),
+    }
+    io.emit({ kind: 'request', request })
+    let resolved
+    try {
+      resolved = await io.ask(request, abort?.signal)
+    } catch (err) {
+      resolved = { answer: { optionIds: [], text: err.message }, by: 'timeout' }
+    }
+    io.emit({ kind: 'request_resolved', id: request.id, answer: resolved.answer, by: resolved.by })
+    const yes = (resolved.answer.optionIds ?? []).some(id => id === 'allow' || id === 'always')
+    return { decision: yes ? 'accept' : 'decline' }
+  }
+
+  const onNotify = (method, p) => {
+    if (method === 'item/started') {
+      if (p.item.type === 'fileChange') changes.set(p.item.id, p.item.changes ?? [])
+      const action = itemAction(p.item, cwd)
+      if (action) io.emit({ kind: 'action', id: p.item.id, ...action })
+    } else if (method === 'item/completed') {
+      if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
+        text = p.item.text
+        io.emit({ kind: 'message', text: short(p.item.text, TEXT_CAP) })
+      } else if (itemAction(p.item, cwd)) {
+        io.emit({ kind: 'action_result', id: p.item.id, ...itemResult(p.item) })
+      }
+      changes.delete(p.item.id)
+    } else if (method === 'error' && !p.willRetry) {
+      error = `Codex stopped: ${p.error?.message ?? 'error'}`
+    } else if (method === 'turn/completed' && p.turn?.id === turnId) {
+      const t = p.turn
+      if (t.status === 'failed') error = `Codex stopped: ${t.error?.message ?? 'failed'}`
+      if (t.status === 'interrupted') error = 'Stopped by the user.'
+      finished({ durationMs: t.durationMs ?? undefined })
+    }
+  }
+  const onRequest = async (method, params) => {
+    if (APPROVALS.has(method)) return decide(method, params)
+    throw new Error(`Kira does not answer ${method}`)
+  }
+
+  const env = { ...process.env, ...(persona?.kiraTools ? { KIRA_TOKEN: persona.kiraTools.token } : {}) }
+  const codex = openCodex(bin, { cwd, env, onNotify, onRequest })
+  void codex.done.then(why => finished({ crashed: why }))
+  const stop = () => {
+    if (thread && turnId) void codex.request('turn/interrupt', { threadId: thread, turnId }).catch(() => {})
+  }
+  abort?.signal.addEventListener('abort', stop, { once: true })
+  try {
+    await codex.request('initialize', { clientInfo: { name: 'kira', title: 'Kira', version: '1' }, capabilities: null })
+    codex.notify('initialized')
+    // 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 })
+    thread = opened.thread.id
+    io.emit({ kind: 'session', sessionId: thread, model: opened.model ?? null })
+    const input = [{ type: 'text', text: prompt, text_elements: [] }]
+    const started = await codex.request('turn/start', { threadId: thread, input, ...(effort ? { effort } : {}) })
+    turnId = started.turn.id
+    const end = await ended
+    if (end.crashed && !error) error = abort?.signal.aborted ? 'Stopped by the user.' : `Codex stopped: ${end.crashed}`
+    const stats = end.durationMs ? { durationMs: end.durationMs } : undefined
+    io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: thread, stats })
+    return { ok: !error, text, error, sessionId: thread, stats }
+  } catch (err) {
+    const message = abort?.signal.aborted ? 'Stopped by the user.' : `could not run Codex: ${err.message}`
+    io.emit({ kind: 'result', ok: false, error: message, sessionId: thread })
+    return { ok: false, error: message, sessionId: thread }
+  } finally {
+    abort?.signal.removeEventListener('abort', stop)
+    codex.close()
+  }
+}
+
+export const codex = { id: 'codex', name: 'Codex', run, capabilities: { resume: true, requests: ['permission'] } }

package/src/agents/index.mjs

@@ -1,8 +1,9 @@
 // Coding agents this bridge can run. Each adapter speaks agents/protocol.mjs;
-// adding Codex or another agent is a new file here and nothing else.
+// another agent is a new file here and nothing else.
 import { claude } from './claude.mjs'
+import { codex } from './codex.mjs'
 
-export const AGENTS = { claude }
+export const AGENTS = { claude, codex }
 
 export function agentById(id) {
   return AGENTS[id ?? 'claude'] ?? null

package/src/agents/settings.mjs

@@ -1,12 +1,14 @@
 // How a job runs, as the person chose it in Kira's composer (genui run-settings.ts): the model,
 // the effort, and the permission mode. Pure: the Agent SDK's options.
 //
-//   { model?: string, effort?: 'low'|'medium'|'high', mode?: 'auto'|'ask'|'plan' }
+//   { model?: string, effort?: 'low'|'medium'|'high', mode?: 'acceptEdits'|'default'|'plan' }
 
 const EFFORTS = new Set(['low', 'medium', 'high'])
 const MODEL = /^claude-[a-z0-9-]{1,60}$/
-/** The composer's modes are Claude Code's own: accept edits, ask before edits (its default), plan first. */
-const MODES = { auto: 'acceptEdits', ask: 'default', plan: 'plan' }
+/** The composer's modes are Claude Code's own ids: accept edits, ask before edits (its default), plan first. */
+const MODES = new Set(['acceptEdits', 'default', 'plan'])
+/** The ids an older Kira API sent (auto, ask), read as the modes they meant. */
+const OLD = { auto: 'acceptEdits', ask: 'default' }
 
 /**
  * The SDK's query options for these settings (left out when unset, so Claude Code's defaults stand).
@@ -14,7 +16,8 @@ const MODES = { auto: 'acceptEdits', ask: 'default', plan: 'plan' }
  */
 export function sdkOptionsFor(settings, kiraDecides = true) {
   const s = settings ?? {}
-  const mode = Object.hasOwn(MODES, s.mode) ? MODES[s.mode] : MODES.auto
+  const said = Object.hasOwn(OLD, s.mode) ? OLD[s.mode] : s.mode
+  const mode = MODES.has(said) ? said : 'acceptEdits'
   return {
     permissionMode: kiraDecides ? mode : mode === 'plan' ? 'plan' : 'default',
     ...(typeof s.model === 'string' && MODEL.test(s.model) ? { model: s.model } : {}),

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/connection.mjs

@@ -4,6 +4,7 @@ import WebSocket from 'ws'
 import { normalizeAnswer } from './agents/protocol.mjs'
 import { answer } from './agents/answers.mjs'
 import { decided, kiraChecks } from './agents/checks.mjs'
+import { heartbeat } from './heartbeat.mjs'
 import { terminalMessage, terminalsOffline } from './terminals.mjs'
 import { host, log, status } from './host.mjs'
 
@@ -15,6 +16,8 @@ import { host, log, status } from './host.mjs'
 let live = null
 const outbox = []
 const OUTBOX_MAX = 2000
+/** A connect that hangs (half-open network, a dyno mid-restart) is abandoned after this long. */
+const HANDSHAKE_TIMEOUT_MS = 15_000
 
 let settings = null
 let stopped = false
@@ -63,16 +66,16 @@ function open() {
   if (stopped) return
   status('connecting')
   const { url, token } = settings
-  const ws = new WebSocket(`${url}?token=${encodeURIComponent(token)}`)
-  let ping
+  const ws = new WebSocket(`${url}?token=${encodeURIComponent(token)}`, { handshakeTimeout: HANDSHAKE_TIMEOUT_MS })
+  let stopHeartbeat = () => {}
   ws.on('open', () => {
     backoff = 1000
     log(`connected to ${url}`)
-    ping = setInterval(() => send(ws, { type: 'ping' }), 30_000)
+    stopHeartbeat = heartbeat(ws, { onDead: () => log('no answer from the API; reconnecting') })
   })
   ws.on('message', raw => onMessage(ws, raw))
   ws.on('close', (code, reason) => {
-    clearInterval(ping)
+    stopHeartbeat()
     onClose(ws, code, reason)
   })
   ws.on('error', err => log(`socket error: ${err.message}`))
@@ -102,7 +105,11 @@ async function onMessage(ws, raw) {
 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() })
+  // runningJobs: the jobs this bridge still has (running, or with a result waiting in the outbox);
+  // the API fails the person's other running jobs at once instead of after its long sweep.
+  const caps = settings.capabilities()
+  const queued = outbox.map(o => o.jobId).filter(id => typeof id === 'string')
+  send(ws, { type: 'capabilities', ...caps, runningJobs: [...new Set([...caps.runningJobs, ...queued])] })
   live = ws
   kiraChecks(msg.checks, sendIfLive)
   // Job events and results from while we were disconnected, in order.

package/src/heartbeat.mjs

@@ -0,0 +1,34 @@
+// Dead-socket detection. A socket can die without a close (the Mac woke on another network,
+// a router dropped it); the bridge would sit "connected" and deaf. The API answers every
+// `ping` with `pong`, so anything not heard back in time means the socket is gone.
+
+/** How often the bridge pings (also keeps Heroku's 55 s idle limit away). */
+const PING_EVERY_MS = 30_000
+/** How long a pong may take before the socket is given up. */
+const PONG_WITHIN_MS = 10_000
+
+/**
+ * Ping `ws` every `every` ms; terminate it if no message at all arrives within `within` ms of a
+ * ping (any message proves it alive). Returns a stop function for when the socket closes.
+ */
+export function heartbeat(ws, { every = PING_EVERY_MS, within = PONG_WITHIN_MS, onDead = () => {} } = {}) {
+  let deadline = null
+  const heard = () => {
+    clearTimeout(deadline)
+    deadline = null
+  }
+  ws.on('message', heard)
+  const timer = setInterval(() => {
+    if (ws.readyState !== 1 || deadline) return
+    ws.send(JSON.stringify({ type: 'ping' }))
+    deadline = setTimeout(() => {
+      onDead()
+      ws.terminate()
+    }, within)
+  }, every)
+  return () => {
+    clearInterval(timer)
+    heard()
+    ws.off('message', heard)
+  }
+}

package/src/index.mjs

@@ -6,11 +6,12 @@ import { agentTools } from './agent-files.mjs'
 import { appolloBridgeTools } from './appollo/index.mjs'
 import { AGENTS } from './agents/index.mjs'
 import { claudeTools } from './agents/claude-local.mjs'
+import { codexTools } from './agents/codex-local.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 { jobTools, runningJobIds } from './job-tools.mjs'
 import { macTools } from './mac-tools.mjs'
 import { sessionTools } from './session-tools.mjs'
 import { skillTools } from './skill-files.mjs'
@@ -25,6 +26,7 @@ const tools = {
   ...jobTools,
   ...gitTools,
   ...claudeTools,
+  ...codexTools,
   ...skillTools,
   ...agentTools,
   ...appolloBridgeTools,
@@ -33,7 +35,8 @@ const tools = {
 /** 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 }
+  const platform = process.platform
+  return { tools: Object.keys(tools), version: BRIDGE_VERSION, platform, agents, runningJobs: runningJobIds() }
 }
 
 /**

package/src/job-tools.mjs

@@ -13,6 +13,11 @@ import { jobEndLine, jobStartLine, promptOf } from './job-format.mjs'
 /** Running jobs, by id, so a person can stop one. */
 const running = new Map()
 
+/** The ids of the jobs running here now. */
+export function runningJobIds() {
+  return [...running.keys()]
+}
+
 export const jobTools = {
   /**
    * Run an instruction with a coding agent. Acknowledges at once, streams every

package/src/kira-plugin.mjs

@@ -0,0 +1,75 @@
+// 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'
+import { inside, isName, oneAtATime, refuseLinks, writeWhole } from './config-folders.mjs'
+import { log } from './host.mjs'
+
+/** Its name in Claude Code: the start of every skill's /kira:<name>. */
+const PLUGIN = 'kira'
+const MANIFEST = {
+  name: PLUGIN,
+  description: 'Kira’s skills: how Kira drafts pages, starts projects, researches and uses the apps you connected.',
+}
+/** A skill past this isn't one of ours. */
+const MAX_MD = 256 * 1024
+
+const pluginRoot = () => join(KIRA_DIR, 'claude-plugin')
+
+/** The skills worth writing: a plain name and a SKILL.md with front matter, not too large. */
+function wanted(skills) {
+  const out = new Map()
+  for (const s of Array.isArray(skills) ? skills : []) {
+    const md = typeof s?.md === 'string' ? s.md : ''
+    if (isName(s?.name) && /^---\r?\n/.test(md) && Buffer.byteLength(md) <= MAX_MD) out.set(s.name, md)
+  }
+  return out
+}
+
+/** Write the plugin with exactly these skills; its folder. One write at a time (jobs can overlap). */
+export function writeKiraPlugin(skills, root = pluginRoot()) {
+  return oneAtATime(root, async () => {
+    const want = wanted(skills)
+    const dir = join(root, 'skills')
+    await refuseLinks([root, dir], 'write')
+    await writeWhole(join(root, '.claude-plugin', 'plugin.json'), `${JSON.stringify(MANIFEST, null, 2)}\n`)
+    for (const [name, md] of want) await writeWhole(join(inside(dir, name, 'a skill folder'), 'SKILL.md'), md)
+    const there = await readdir(dir, { withFileTypes: true }).catch(() => [])
+    for (const e of there) {
+      if (e.isDirectory() && isName(e.name) && !want.has(e.name)) await rm(join(dir, e.name), { recursive: true })
+    }
+    return root
+  })
+}
+
+/**
+ * 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).
+ */
+async function writtenFor(persona, agent, warn, root) {
+  if (!Array.isArray(persona?.skills) || !persona.skills.length) return null
+  try {
+    return await writeKiraPlugin(persona.skills, root)
+  } catch (err) {
+    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')] : []
+}