kira-glasses-bridge 2.30.0 → 2.32.0

package/package.json

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

@@ -0,0 +1,87 @@
+// A run's usage, whichever agent it is: how full its thread's context is ({ used, window }) and the
+// person's plan limits (AgentLimits, packages/genui/src/wire/agentUsage.ts), as the protocol's `usage`
+// event, and the words a run fails with when a limit stops it: which limit, and when it resets (and that
+// window, as the run's stats.limitHit, for the card that offers the other agent). Each
+// agent reads its own reports into these shapes (claude-usage.mjs, codex-usage.mjs).
+
+/** A window's name: "5-hour", "weekly", "weekly Opus". */
+function windowName({ minutes, model }) {
+  const length = lengthName(minutes)
+  return model ? `${length} ${model}` : length
+}
+
+function lengthName(minutes) {
+  if (minutes === 7 * 24 * 60) return 'weekly'
+  if (minutes && minutes < 24 * 60) return `${Math.round(minutes / 60)}-hour`
+  return minutes ? `${Math.round(minutes / (24 * 60))}-day` : 'usage'
+}
+
+/** Every window the limits have: the plan's two, then each model's own. */
+const windowsOf = limits => [limits?.primary, limits?.secondary, ...(limits?.models ?? [])].filter(Boolean)
+
+/** The fullest window, the one that most likely stopped a run. */
+export const fullestOf = limits => windowsOf(limits).sort((a, b) => b.usedPercent - a.usedPercent)[0] ?? null
+
+/** "at 3:10 PM" today, "on Tue at 9:05 AM" otherwise, in this Mac's own way of saying times. */
+function resetWords(resetsAt, now) {
+  const at = new Date(resetsAt * 1000)
+  const time = at.toLocaleTimeString([], { hour: 'numeric', minute: '2-digit' })
+  if (at.toDateString() === new Date(now).toDateString()) return `at ${time}`
+  return `on ${at.toLocaleDateString([], { weekday: 'short', month: 'short', day: 'numeric' })} at ${time}`
+}
+
+/**
+ * Which limit is used up and when it resets: "your 5-hour ChatGPT limit is used up (100%). It resets
+ * at 3:10 PM." (`plan` names whose: "ChatGPT", "Claude"; a model's own window names the model instead.)
+ */
+export function usedUpWords(window, plan, now = Date.now()) {
+  const when = window.resetsAt ? resetWords(window.resetsAt, now) : 'later'
+  const whose = window.model ? windowName(window) : `${windowName(window)} ${plan}`
+  return `your ${whose} limit is used up (${Math.round(window.usedPercent)}%). It resets ${when}.`
+}
+
+const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
+
+/**
+ * A run's usage feed: given the context and limits as they change, it emits a `usage` event with the
+ * latest of both, only when what a person sees changes (a whole percent of context, a limit), not on
+ * every token count.
+ */
+export function usageFeed(emit) {
+  let context = null
+  let limits = null
+  let limitHit = null
+  let sent = ''
+  const send = () => {
+    if (!context && !limits) return
+    const key = JSON.stringify([pctOf(context), limits])
+    if (key === sent) return
+    sent = key
+    emit({ kind: 'usage', context, limits })
+  }
+  return {
+    /** The context now (null: not known, the last one stands). */
+    context(next) {
+      context = next ?? context
+      send()
+    },
+    /** The limits now, whole (null: not known, the last ones stand). */
+    limits(next) {
+      limits = next ?? limits
+      if (limits) send()
+    },
+    /** The limits known so far, to merge an update over and for the words a run fails with. */
+    get known() {
+      return limits
+    },
+    /** A run stopped ({ error, hit } from an agent's stoppedBy): keeps the window that stopped it. */
+    stopped({ error, hit }) {
+      limitHit = hit ?? limitHit
+      return error
+    },
+    /** What the run ends with, for its stats: `limitHit` is the window that stopped it, if one did. */
+    get stats() {
+      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}), ...(limitHit ? { limitHit } : {}) }
+    },
+  }
+}

package/src/agents/claude-local.mjs

@@ -1,7 +1,11 @@
-// Claude Code on this Mac, as the person signed in to it: which account it uses, the permission
-// rules in their own settings, and one piece of text written with that sign-in (complete.mjs).
+// Claude Code on this Mac, as the person signed in to it: which account it uses, its plan's usage
+// limits, the permission rules in their own settings, and one piece of text written with that sign-in
+// (complete.mjs).
 import { execFile } from 'node:child_process'
 import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { query } from '@anthropic-ai/claude-agent-sdk'
+import { limitsFromUsage } from './claude-usage.mjs'
 import { FOLDERS } from '../config-folders.mjs'
 import { completeText } from './complete.mjs'
 
@@ -28,6 +32,43 @@ async function claudeAccount() {
   )
 }
 
+/**
+ * The person's plan limits as a Claude Code session reads them: the data behind its /usage (the SDK's
+ * experimental structured answer; an older SDK or CLI without it gives none). No model call.
+ */
+export async function planLimits(q) {
+  const ask = q.usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET
+  if (typeof ask !== 'function') return null
+  return limitsFromUsage(await ask.call(q, { skipBehaviors: true }).catch(() => null))
+}
+
+const LIMITS_MS = 15_000
+
+/**
+ * Their plan limits outside a run, for the composer: a session opened only to ask (its prompt never
+ * comes, so nothing is sent to a model), closed once it has answered.
+ */
+async function claudeLimits() {
+  let release
+  const never = (async function* () {
+    await new Promise(resolve => (release = resolve))
+  })()
+  const abortController = new AbortController()
+  const timer = setTimeout(() => abortController.abort(), LIMITS_MS)
+  const env = { ...process.env, ENABLE_CLAUDEAI_MCP_SERVERS: 'false' }
+  const bin = process.env.KIRA_CLAUDE_BIN ? { pathToClaudeCodeExecutable: process.env.KIRA_CLAUDE_BIN } : {}
+  // None of their settings or MCP servers: it only asks (a second, not three).
+  const quiet = { settingSources: [], strictMcpConfig: true }
+  const q = query({ prompt: never, options: { cwd: homedir(), env, abortController, ...quiet, ...bin } })
+  try {
+    return { limits: await planLimits(q) }
+  } finally {
+    clearTimeout(timer)
+    release?.()
+    q.close()
+  }
+}
+
 /** The permissions block of a Claude Code settings file, as written there (nothing when it has none). */
 export function permissionsIn(settings) {
   const p = settings?.permissions ?? {}
@@ -48,6 +89,7 @@ async function claudePermissions() {
 
 export const claudeTools = {
   claude_account: claudeAccount,
+  claude_limits: claudeLimits,
   claude_permissions: claudePermissions,
   complete_text: completeText,
 }

package/src/agents/claude-usage.mjs

@@ -0,0 +1,116 @@
+// How full a Claude Code session is and how much of the person's Claude plan is left, from the Agent
+// SDK: `getContextUsage()` (the context, as /context counts it), the structured /usage answer (the
+// plan, its 5-hour and weekly windows, each model's own weekly window, extra usage) and
+// `rate_limit_event` messages as a run goes. Read into the shapes every agent sends (agent-usage.mjs),
+// and the words a run fails with when a limit stops it. Pure.
+import { fullestOf, usedUpWords } from './agent-usage.mjs'
+
+const FIVE_HOURS = 300
+const WEEK = 7 * 24 * 60
+
+/** The context the session fills: its tokens out of the window Claude Code measures against. */
+export function contextFrom(usage) {
+  const window = usage?.rawMaxTokens || usage?.maxTokens
+  return window > 0 && typeof usage.totalTokens === 'number' ? { used: usage.totalTokens, window } : null
+}
+
+/** A /usage window ({ utilization: 0-100, resets_at: ISO }) as Kira sends it. */
+function windowOf(w, minutes, model = null) {
+  if (typeof w?.utilization !== 'number') return null
+  const at = w.resets_at ? Date.parse(w.resets_at) : NaN
+  const resetsAt = Number.isNaN(at) ? null : Math.round(at / 1000)
+  return { usedPercent: w.utilization, resetsAt, minutes, ...(model ? { model } : {}) }
+}
+
+/** Each model's own weekly window: the server's list, else the older Opus and Sonnet fields. */
+function modelWindows(r) {
+  const listed = Array.isArray(r.model_scoped) ? r.model_scoped : null
+  const named = listed
+    ? listed.map(w => windowOf(w, WEEK, w.display_name || 'Model'))
+    : [windowOf(r.seven_day_opus, WEEK, 'Opus'), windowOf(r.seven_day_sonnet, WEEK, 'Sonnet')]
+  return named.filter(Boolean)
+}
+
+/** Extra usage, from minor units (cents) to the currency's own. */
+function extraOf(x) {
+  if (!x) return null
+  const unit = 10 ** (Number.isInteger(x.decimal_places) ? x.decimal_places : 2)
+  const major = n => (typeof n === 'number' ? n / unit : null)
+  const currency = x.currency ?? null
+  return { enabled: !!x.is_enabled, used: major(x.used_credits), limit: major(x.monthly_limit), currency }
+}
+
+/** The /usage answer (`usage_EXPERIMENTAL…()`) as Kira's limits; null when no plan limits apply (an API key). */
+export function limitsFromUsage(answer) {
+  const r = answer?.rate_limits
+  if (!answer?.rate_limits_available || !r) return null
+  return {
+    account: 'claude',
+    primary: windowOf(r.five_hour, FIVE_HOURS),
+    secondary: windowOf(r.seven_day, WEEK),
+    models: modelWindows(r),
+    credits: null,
+    extra: extraOf(r.extra_usage),
+    plan: answer.subscription_type ?? null,
+  }
+}
+
+/** Where each `rateLimitType` of an event goes in Kira's limits. */
+const SLOTS = {
+  five_hour: { slot: 'primary', minutes: FIVE_HOURS },
+  seven_day: { slot: 'secondary', minutes: WEEK },
+  seven_day_opus: { slot: 'models', minutes: WEEK, model: 'Opus' },
+  seven_day_sonnet: { slot: 'models', minutes: WEEK, model: 'Sonnet' },
+}
+
+const EMPTY = { account: 'claude', primary: null, secondary: null, models: [], credits: null, extra: null, plan: null }
+
+/** One window of an event (utilization 0-1, resetsAt in seconds) set into the limits. */
+function setWindow(limits, type, { utilization, resetsAt, rejected }) {
+  const at = SLOTS[type]
+  if (!at) return limits
+  const prev = at.slot === 'models' ? limits.models.find(w => w.model === at.model) : limits[at.slot]
+  const said = typeof utilization === 'number' ? Math.round(utilization * 100) : rejected ? 100 : null
+  // An event's fraction is coarser than /usage's percent: within a point of the same window, what's known stands.
+  const same = prev && (resetsAt ?? prev.resetsAt) === prev.resetsAt
+  const usedPercent = said === null || (same && Math.abs(said - prev.usedPercent) <= 1) ? prev?.usedPercent : said
+  if (typeof usedPercent !== 'number') return limits
+  const window = { usedPercent, resetsAt: resetsAt ?? prev?.resetsAt ?? null, minutes: at.minutes }
+  if (at.slot !== 'models') return { ...limits, [at.slot]: window }
+  return { ...limits, models: [...limits.models.filter(w => w.model !== at.model), { ...window, model: at.model }] }
+}
+
+/**
+ * A `rate_limit_event` merged over what was known: the windows it carries (its `unifiedWindows` when
+ * the CLI sends them, and the one its `rateLimitType` names), the rest as they were.
+ */
+export function limitsFromEvent(info, prev = null) {
+  if (!info) return prev
+  let limits = { ...EMPTY, ...prev, models: prev?.models ?? [] }
+  for (const [type, w] of Object.entries(info.unifiedWindows ?? {})) limits = setWindow(limits, type, w ?? {})
+  if (info.rateLimitType) {
+    const rejected = info.status === 'rejected'
+    limits = setWindow(limits, info.rateLimitType, { ...info, rejected })
+  }
+  return limits
+}
+
+/** The window an event says is used up, to name it when the run stops. */
+export function rejectedWindow(info, limits) {
+  if (info?.status !== 'rejected' || !SLOTS[info.rateLimitType]) return null
+  const at = SLOTS[info.rateLimitType]
+  return at.slot === 'models' ? limits?.models?.find(w => w.model === at.model) : limits?.[at.slot]
+}
+
+/**
+ * What a run says when it ends on an error (`error`): for a usage limit (Claude Code's words start with
+ * one of `limitPrefixes`), which one and when it resets; else Claude Code's own words. `hit`: the
+ * window that stopped it, when a limit did and it's known.
+ */
+export function stoppedBy(said, { limits, rejected, limitPrefixes = [] }, now = Date.now()) {
+  const text = String(said ?? 'error').trim()
+  if (!limitPrefixes.some(p => text.startsWith(p))) return { error: `Claude stopped: ${text.slice(0, 300)}`, hit: null }
+  const full = rejected ?? fullestOf(limits)
+  if (!full) return { error: `Claude stopped: ${text}`, hit: null }
+  return { error: `Claude stopped: ${usedUpWords(full, 'Claude', now)}`, hit: full }
+}

package/src/agents/claude.mjs

@@ -1,6 +1,7 @@
 // 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 { USAGE_LIMIT_ERROR_PREFIXES, query } from '@anthropic-ai/claude-agent-sdk'
+import { usageFeed } from './agent-usage.mjs'
 import {
   NOT_ANOTHER_WAY,
   TEXT_CAP,
@@ -10,6 +11,8 @@ import {
   toRequest,
 } from './claude-calls.mjs'
 import { kiraDecides } from './checks.mjs'
+import { planLimits } from './claude-local.mjs'
+import { contextFrom, limitsFromEvent, rejectedWindow, stoppedBy } from './claude-usage.mjs'
 import { sdkOptionsFor } from './settings.mjs'
 import { kiraPluginOptions } from '../kira-plugin.mjs'
 
@@ -42,6 +45,11 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   let error = null
   /** What Kira's rules said about each tool call, by its id, for the question if Claude Code asks. */
   const verdicts = new Map()
+  /** How full the session is and the person's limits, as they change (claude-usage.mjs). */
+  const usage = usageFeed(e => io.emit(e))
+  /** The limit a rate_limit_event said is used up, and the last turn whose context was read. */
+  let rejected = null
+  let turn = null
 
   /** Refused before it runs: the job shows why, and Claude is told (`told`, when it needs more). */
   const refuse = (tool, reason, told = reason) => {
@@ -127,11 +135,21 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       if (m.type === 'system' && m.subtype === 'init') {
         session = m.session_id ?? session
         io.emit({ kind: 'session', sessionId: session, model: m.model ?? null })
+        // The plan's windows, each model's own and extra usage (events carry only some of them).
+        void planLimits(q).then(limits => usage.limits(limits))
+      } else if (m.type === 'rate_limit_event') {
+        usage.limits(limitsFromEvent(m.rate_limit_info, usage.known))
+        rejected = rejectedWindow(m.rate_limit_info, usage.known) ?? rejected
       } else if (m.type === 'system' && m.subtype === 'task_started') {
         if (m.is_backgrounded && m.tool_use_id) orphans.set(m.tool_use_id, m.description ?? m.subagent_type ?? 'task')
       } else if (m.type === 'system' && m.subtype === 'task_notification') {
         if (m.tool_use_id) orphans.delete(m.tool_use_id)
       } else if (m.type === 'assistant') {
+        // A new turn of the main thread: how full the context is now, as /context counts it (no model call).
+        if (!nested && m.message?.id && m.message.id !== turn) {
+          turn = m.message.id
+          usage.context(contextFrom(await q.getContextUsage({ detail: 'summary' }).catch(() => null)))
+        }
         for (const b of m.message?.content ?? []) {
           // A subagent's narration is for its parent, not the user; its actions still show what is going on while the Subtask runs.
           if (b.type === 'text' && b.text?.trim() && !nested) io.emit({ kind: 'message', text: short(b.text, TEXT_CAP) })
@@ -147,14 +165,18 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
         }
       } else if (m.type === 'result') {
         session = m.session_id ?? session
-        if (m.subtype === 'success') text = String(m.result ?? '')
+        // A turn that ended on an API error (a usage limit among them) is a success carrying the error.
+        const limit = { limits: usage.known, rejected, limitPrefixes: USAGE_LIMIT_ERROR_PREFIXES }
+        if (m.subtype === 'success' && !m.is_error) text = String(m.result ?? '')
+        else if (m.subtype === 'success') error = usage.stopped(stoppedBy(m.result, limit))
         else error = `Claude stopped: ${m.subtype}${Array.isArray(m.errors) && m.errors.length ? ` (${m.errors.join('; ').slice(0, 300)})` : ''}`
         // Work left running in the background dies with this process; say so rather than let "still running" stand as the outcome.
         if (orphans.size) {
           const note = `${orphans.size} background ${orphans.size === 1 ? 'task was' : 'tasks were'} still running when Claude ended its turn (${[...orphans.values()].slice(0, 5).join(', ')}); they were stopped with the session and their findings are not in this report. Send a follow-up to have that work done inline.`
           text = text ? `${text}\n\n(${note})` : `(${note})`
         }
-        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd }
+        // How full the session ended and the limits it last saw (claude-usage.mjs), beside the run's own.
+        const stats = { durationMs: m.duration_ms, turns: m.num_turns, costUsd: m.total_cost_usd, ...usage.stats }
         io.emit({ kind: 'result', ok: !error, text: short(text, TEXT_CAP), error, sessionId: session, stats })
         return { ok: !error, text, error, sessionId: session, stats }
       }

package/src/agents/codex-ask.mjs

@@ -0,0 +1,66 @@
+// Asking the person what Codex asks (codex.mjs): the request card, the wait for its answer (none in
+// time, or the job stopped, is the timeout's), and Kira's rules refusing before anyone is asked.
+import { strictest } from './codex-items.mjs'
+import { formRequest, formResponse } from './codex-forms.mjs'
+import {
+  permissionsAsked,
+  permissionsRequest,
+  permissionsResponse,
+  userInputRequest,
+  userInputResponse,
+} from './codex-requests.mjs'
+
+/** Show the request and wait for its answer: `{ answer, by }`. */
+export async function askPerson(io, request, signal) {
+  io.emit({ kind: 'request', request })
+  let resolved
+  try {
+    resolved = await io.ask(request, 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 })
+  return resolved
+}
+
+/** Kira's rules said no: the thread shows it as answered by them, and nobody is asked. */
+export function refusedByPolicy(io, tool, verdict) {
+  const reason = `Kira: ${verdict.why ?? 'your rules'}${verdict.rule ? ` (${verdict.rule})` : ''}`
+  const id = `policy-${Date.now().toString(36)}`
+  io.emit({ kind: 'request_resolved', id, answer: { optionIds: ['deny'] }, by: 'policy', tool, reason })
+}
+
+export const said = (resolved, ...ids) => (resolved.answer.optionIds ?? []).some(id => ids.includes(id))
+
+/** More access: every folder Kira's rules allow and nothing they can't check goes through; else asks. */
+async function permissions(params, { io, cwd, signal }) {
+  const { calls, unchecked } = permissionsAsked(params, cwd)
+  const verdicts = await Promise.all(calls.map(c => io.check(c)))
+  const verdict = strictest([...verdicts, ...(unchecked ? [{ effect: 'ask' }] : [])]) ?? { effect: 'mode' }
+  if (verdict.effect === 'allow') return permissionsResponse(params, true)
+  if (verdict.effect === 'deny') {
+    refusedByPolicy(io, 'Permissions', verdict)
+    return permissionsResponse(params, false)
+  }
+  const resolved = await askPerson(io, permissionsRequest(params, cwd, verdict), signal)
+  return permissionsResponse(params, said(resolved, 'allow', 'always'))
+}
+
+async function userInput(params, { io, signal }) {
+  const request = userInputRequest(params)
+  const resolved = request ? await askPerson(io, request, signal) : null
+  return userInputResponse(params, request, resolved)
+}
+
+async function elicitation(params, { io, signal }) {
+  const request = formRequest(params)
+  const resolved = request ? await askPerson(io, request, signal) : null
+  return formResponse(params, request, resolved)
+}
+
+/** What Codex asks besides its approvals, by method: each answers with Codex's response. */
+export const CODEX_ASKS = {
+  'item/tool/requestUserInput': userInput,
+  'item/permissions/requestApproval': permissions,
+  'mcpServer/elicitation/request': elicitation,
+}

package/src/agents/codex-forms.mjs

@@ -0,0 +1,107 @@
+// An MCP server asking the person for something through Codex (mcpServer/elicitation/request), in
+// Kira's agent protocol: a form's fields as questions (a pick for a list or yes/no, words for the rest),
+// a link to open or a plain yes/no as a choice; and the answer back as MCP's accept, decline or cancel
+// with the form's content. Pure.
+import { short } from './claude-calls.mjs'
+import { requestId } from './protocol.mjs'
+
+const ACCEPT = [
+  { id: 'accept', label: 'Accept' },
+  { id: 'decline', label: 'Decline' },
+]
+const OPEN = [
+  { id: 'accept', label: 'Done', description: 'I opened it and did what it asks' },
+  { id: 'decline', label: 'Decline' },
+]
+const YES_NO = [
+  { label: 'Yes', value: true },
+  { label: 'No', value: false },
+]
+
+/** A field's choices as [{ label, value }], from whichever enum shape MCP gives; [] for words. */
+function choicesOf(f) {
+  if (f.type === 'boolean') return YES_NO
+  const list = f.type === 'array' ? f.items ?? {} : f
+  if (list.oneOf ?? list.anyOf) return (list.oneOf ?? list.anyOf).map(o => ({ label: o.title, value: o.const }))
+  return (list.enum ?? []).map((value, k) => ({ label: f.enumNames?.[k] ?? value, value }))
+}
+
+/** A form's fields, in its order: what each asks and what its answers mean. */
+export function fieldsOf(schema) {
+  const required = new Set(schema?.required ?? [])
+  return Object.entries(schema?.properties ?? {}).map(([key, f], n) => ({
+    key,
+    id: `q${n + 1}`,
+    type: f.type,
+    question: f.description || f.title || key,
+    header: f.title || key,
+    multi: f.type === 'array',
+    choices: choicesOf(f),
+    required: required.has(key),
+    ...(f.default !== undefined && f.default !== null ? { default: f.default } : {}),
+  }))
+}
+
+const choiceOptions = choices => choices.map((c, k) => ({ id: `o${k + 1}`, label: String(c.label) }))
+const base = (params, more) => ({
+  id: requestId(),
+  type: 'choice',
+  title: short(params.message || `${params.serverName} asks`, 300),
+  action: { tool: `mcp__${params.serverName}`, label: 'Asks', target: short(params.message, 200) },
+  ...more,
+})
+
+/** The request for a server's ask; null for a kind Kira doesn't show (Codex is told no). */
+export function formRequest(params) {
+  if (params.mode === 'url') return base(params, { detail: params.url, options: OPEN })
+  if (params.mode !== 'form') return null
+  const fields = fieldsOf(params.requestedSchema)
+  if (!fields.length) return base(params, { options: ACCEPT })
+  const questions = fields.map(f => ({
+    id: f.id,
+    question: f.question,
+    header: f.header,
+    multi: f.multi,
+    options: choiceOptions(f.choices),
+  }))
+  return base(params, { options: questions[0].options, multi: questions[0].multi, allowText: true, questions })
+}
+
+/** One field's value from its answer (undefined when there's none it can take). */
+function valueOf(f, a) {
+  const picked = (a.optionIds ?? []).map(id => f.choices[Number(String(id).slice(1)) - 1]).filter(Boolean)
+  const text = typeof a.text === 'string' ? a.text.trim() : ''
+  const said = s => String(s).toLowerCase() === text.toLowerCase()
+  const named = f.choices.find(c => said(c.label) || said(c.value))
+  if (f.multi) {
+    const values = [...picked, ...(named ? [named] : [])].map(c => c.value)
+    return values.length ? values : undefined
+  }
+  if (picked.length) return picked[0].value
+  if (named) return named.value
+  if (!text || f.choices.length) return undefined
+  if (f.type === 'number' || f.type === 'integer') {
+    const n = Number(text)
+    return Number.isFinite(n) && (f.type === 'number' || Number.isInteger(n)) ? n : undefined
+  }
+  return text
+}
+
+/**
+ * The answer as MCP takes it: accept with the form filled in (an unanswered field keeps its default),
+ * decline when they said no or left a required field empty, cancel when nobody answered in time.
+ */
+export function formResponse(params, request, resolved) {
+  if (!request) return { action: 'decline' }
+  if (resolved?.by === 'timeout') return { action: 'cancel' }
+  const answer = resolved?.answer ?? {}
+  if (!request.questions) return { action: (answer.optionIds ?? []).includes('accept') ? 'accept' : 'decline' }
+  const content = {}
+  for (const f of fieldsOf(params.requestedSchema)) {
+    const a = answer.answers?.[f.id] ?? (f.id === 'q1' ? answer : {})
+    const value = valueOf(f, a) ?? f.default
+    if (value !== undefined) content[f.key] = value
+    else if (f.required) return { action: 'decline' }
+  }
+  return Object.keys(content).length ? { action: 'accept', content } : { action: 'decline' }
+}

package/src/agents/codex-input.mjs

@@ -0,0 +1,24 @@
+// What Codex is given for a turn: turn/start's `input` (UserInput in its app-server protocol). The
+// instruction is the text; what came with it from Kira is already on this Mac (the API's stage_files
+// copied it under .kira/attachments/, and the text ends with each one's path, as Claude Code is told).
+// A picture also goes in as `localImage`, so Codex sees it with the message instead of having to open
+// it, and nothing leaves the Mac but what Codex itself sends; anything else it reads by its path.
+// Pure: tested in test/codex-input.test.mjs.
+
+/** The pictures Codex reads from a path (codex-rs encodes these; an SVG is text, read by path). */
+const IMAGES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp'])
+
+/** An attachment Codex can be shown as a picture: one of IMAGES, at an absolute path. */
+const isPicture = a => typeof a?.path === 'string' && a.path.startsWith('/') && IMAGES.has(String(a.mime))
+
+/**
+ * turn/start's input for `prompt` and the files staged with it (`attachments`: { path, mime }, as the
+ * API's StageService gave them): the text first, then each picture, in the order they were attached.
+ */
+export function codexInput(prompt, attachments = []) {
+  const pictures = (Array.isArray(attachments) ? attachments : []).filter(isPicture)
+  return [
+    { type: 'text', text: prompt, text_elements: [] },
+    ...pictures.map(a => ({ type: 'localImage', path: a.path })),
+  ]
+}

package/src/agents/codex-items.mjs

@@ -80,6 +80,8 @@ export function itemAction(item, cwd) {
       return act('plan', 'Plan', short(item.text, 160), { tool: 'Plan' })
     case 'collabAgentToolCall':
       return act('delegate', 'Subtask', short(item.prompt ?? '', 160), { tool: 'Subtask' })
+    case 'enteredReviewMode':
+      return act('read', 'Review', short(item.review ?? '', 160), { tool: 'Review' })
     case 'imageGeneration':
       return act('other', 'Make an image', short(item.revisedPrompt ?? '', 160), { tool: 'ImageGeneration' })
     default:

package/src/agents/codex-live.mjs

@@ -0,0 +1,107 @@
+// What Codex streams while a turn runs, as the agent protocol's live events (live.mjs): its reply as
+// it's written, its reasoning summaries, a running command's output, its plan and the turn's whole
+// diff. Pure: it keeps what has come so far of each and says what to send.
+import { TEXT_CAP, short } from './claude-calls.mjs'
+
+/** How much of a running command's output is shown: its last lines. */
+const OUTPUT_TAIL = 4000
+/** How much of the turn's diff is kept with the job; its files and counts are always whole. */
+export const DIFF_CAP = 40_000
+const STEP_CAP = 300
+
+/** A unified diff's files, each with the lines it adds and removes. */
+export function diffFiles(diff) {
+  const files = []
+  let cur = null
+  for (const line of String(diff ?? '').split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      cur = { path: / b\/(.+)$/.exec(line)?.[1] ?? line.slice(11), adds: 0, dels: 0 }
+      files.push(cur)
+    } else if (!cur || line.startsWith('+++ ') || line.startsWith('--- ')) continue
+    else if (line.startsWith('+')) cur.adds++
+    else if (line.startsWith('-')) cur.dels++
+  }
+  return files
+}
+
+/** turn/plan/updated as a plan event: its steps, each pending, in progress or completed. */
+function planEvent(p) {
+  return {
+    kind: 'plan',
+    id: `${p.turnId}:plan`,
+    ...(p.explanation?.trim() ? { explanation: short(p.explanation.trim(), 600) } : {}),
+    steps: (p.plan ?? []).map(s => ({ text: short(s.step, STEP_CAP), status: s.status })),
+  }
+}
+
+/** turn/diff/updated as a changes event: the files with their counts, and the diff (cut when long). */
+function changesEvent(p) {
+  const diff = String(p.diff ?? '')
+  const truncated = diff.length > DIFF_CAP
+  return {
+    kind: 'changes',
+    id: `${p.turnId}:changes`,
+    files: diffFiles(diff),
+    diff: truncated ? diff.slice(0, DIFF_CAP) : diff,
+    ...(truncated ? { truncated } : {}),
+  }
+}
+
+/** One turn's streams: `update` maps a notification to a live event, `done` and `ends` say what to keep. */
+export function codexStream() {
+  /** itemId -> what it has written so far (a message, a command's output). */
+  const texts = new Map()
+  /** itemId -> its reasoning summary, part by part. */
+  const thoughts = new Map()
+  let plan = null
+  let changes = null
+  const grow = (id, delta, keep) => {
+    const text = keep((texts.get(id) ?? '') + delta)
+    texts.set(id, text)
+    return text
+  }
+  const thinking = id => {
+    const text = (thoughts.get(id) ?? []).filter(Boolean).join('\n\n').trim()
+    return { kind: 'thinking', id, text: short(text, TEXT_CAP) }
+  }
+
+  return {
+    /** The live event a notification makes, or null when it makes none. */
+    update(method, p) {
+      switch (method) {
+        case 'item/agentMessage/delta': {
+          const text = grow(p.itemId, p.delta, t => t.slice(0, TEXT_CAP + 1))
+          return { kind: 'message', id: p.itemId, text: short(text, TEXT_CAP) }
+        }
+        case 'item/reasoning/summaryPartAdded':
+        case 'item/reasoning/summaryTextDelta': {
+          const parts = thoughts.get(p.itemId) ?? []
+          parts[p.summaryIndex] = (parts[p.summaryIndex] ?? '') + (p.delta ?? '')
+          thoughts.set(p.itemId, parts)
+          return p.delta ? thinking(p.itemId) : null
+        }
+        case 'item/commandExecution/outputDelta':
+          return { kind: 'output', id: p.itemId, text: grow(p.itemId, p.delta, t => t.slice(-OUTPUT_TAIL)) }
+        case 'turn/plan/updated':
+          return (plan = planEvent(p))
+        case 'turn/diff/updated':
+          return (changes = changesEvent(p))
+        default:
+          return null
+      }
+    },
+    /** A finished item: its reasoning summary to keep (null for anything else, or nothing said); forgets it. */
+    done(item) {
+      texts.delete(item.id)
+      if (item.type !== 'reasoning') return null
+      if (item.summary?.length) thoughts.set(item.id, item.summary)
+      const kept = thinking(item.id)
+      thoughts.delete(item.id)
+      return kept.text ? kept : null
+    },
+    /** What the turn ends with, to keep: its last plan and its changes (when it changed anything). */
+    ends() {
+      return [plan, changes?.files.length ? changes : null].filter(Boolean)
+    },
+  }
+}