kira-glasses-bridge 2.30.0 → 2.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kira-glasses-bridge",
-  "version": "2.30.0",
+  "version": "2.31.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/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)
+    },
+  }
+}

package/src/agents/codex-local.mjs

@@ -1,7 +1,9 @@
-// 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).
+// Codex on this Mac, as the person signed in to it: whether it's there and signed in, the models it
+// offers them (its own list, so the composer never names a model Codex wouldn't take), and their
+// ChatGPT usage limits (none with an API key).
 import { homedir } from 'node:os'
 import { codexBin, openCodex } from './codex-rpc.mjs'
+import { limitsOf, snapshotOf } from './codex-usage.mjs'
 
 const ASK_MS = 15_000
 
@@ -19,7 +21,7 @@ export function modelsOf(list) {
   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 }`. */
+/** Whether Codex is here and signed in, its models and their limits: `{ installed, signedIn, models, limits }`. */
 async function codexModels() {
   const bin = codexBin()
   if (!bin) return { installed: false, signedIn: false, models: [] }
@@ -30,7 +32,11 @@ async function codexModels() {
     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', {})) }
+    const [list, read] = await Promise.all([
+      codex.request('model/list', {}),
+      codex.request('account/rateLimits/read', { excludeResetCreditDetails: true }).catch(() => null),
+    ])
+    return { installed: true, signedIn: true, models: modelsOf(list), limits: limitsOf(snapshotOf(read)) }
   } catch (err) {
     return { error: `Codex didn't answer: ${err.message}` }
   } finally {

package/src/agents/codex-requests.mjs

@@ -0,0 +1,114 @@
+// What Codex asks the person besides approving a command or a file change, in Kira's agent protocol
+// (protocol.mjs): its questions (item/tool/requestUserInput), more access (item/permissions/requestApproval)
+// and an MCP server's form (mcpServer/elicitation/request), each as a request card; and the person's
+// answer back in Codex's own response shape (an MCP server's form: codex-forms.mjs). Pure; codex-ask.mjs asks.
+import { displayPath, short } from './claude-calls.mjs'
+import { permissionOptions, requestId } from './protocol.mjs'
+
+const options = list => list.map((o, k) => ({ id: `o${k + 1}`, ...o }))
+/** A question's answer: per question, else (the first one) the answer's own options and words. */
+const answerTo = (answer, id, first) => answer?.answers?.[id] ?? (first ? answer ?? {} : {})
+const picked = (q, a) => (a.optionIds ?? []).map(id => q.options.find(o => o.id === id)).filter(Boolean)
+const typed = a => (typeof a.text === 'string' && a.text.trim() ? a.text.trim() : '')
+
+/** Codex's questions as a choice, one question each; a secret one isn't carried through Kira. */
+export function userInputRequest(params) {
+  const asked = (params.questions ?? []).filter(q => !q.isSecret)
+  const questions = asked.map((q, n) => ({
+    id: `q${n + 1}`,
+    question: q.question,
+    header: q.header,
+    multi: false,
+    options: options((q.options ?? []).map(o => ({ label: o.label, description: o.description || undefined }))),
+  }))
+  const secret = (params.questions ?? []).length - asked.length
+  if (!questions.length) return null
+  return {
+    id: requestId(),
+    type: 'choice',
+    title: questions.length === 1 ? questions[0].question : `${questions.length} questions`,
+    ...(secret ? { detail: 'Codex also asked for something secret: answer that in Codex on the Mac.' } : {}),
+    options: questions[0].options,
+    allowText: true,
+    questions,
+    action: { tool: 'AskUserQuestion', label: 'Question', target: short(questions.map(q => q.question).join(' / ')) },
+  }
+}
+
+/** The answers as Codex takes them, by its question ids; unanswered (timed out, secret) ones are empty. */
+export function userInputResponse(params, request, resolved) {
+  const answer = resolved?.by === 'timeout' ? undefined : resolved?.answer
+  const asked = (params.questions ?? []).filter(q => !q.isSecret)
+  const answers = Object.fromEntries((params.questions ?? []).map(q => [q.id, { answers: [] }]))
+  asked.forEach((codexQ, n) => {
+    const q = request?.questions?.[n]
+    if (!q) return
+    const a = answerTo(answer, q.id, n === 0)
+    const words = [...picked(q, a).map(o => o.label), typed(a)].filter(Boolean)
+    answers[codexQ.id] = { answers: words }
+  })
+  return { answers }
+}
+
+/** A folder Codex asks for, as Kira shows and checks it; null for what no path names. */
+function folderOf(path, cwd) {
+  if (path?.type === 'path') return path.path
+  if (path?.type === 'glob_pattern') return path.pattern
+  const v = path?.value ?? {}
+  if (v.kind === 'slash_tmp') return '/tmp'
+  if (v.kind === 'project_roots') return v.subpath ? `${cwd}/${v.subpath}` : cwd
+  return null
+}
+const SPECIAL = { root: 'the whole disk', minimal: 'system basics', tmpdir: 'the temporary folder' }
+
+/** What more access Codex asks for: each folder as the call Kira's rules check, and what no rule can. */
+export function permissionsAsked(params, cwd) {
+  const fs = params.permissions?.fileSystem ?? {}
+  const entries = [
+    ...(fs.entries ?? []),
+    ...(fs.read ?? []).map(path => ({ access: 'read', path: { type: 'path', path } })),
+    ...(fs.write ?? []).map(path => ({ access: 'write', path: { type: 'path', path } })),
+  ].filter(e => e.access !== 'deny')
+  const calls = []
+  const unchecked = []
+  const parts = []
+  for (const e of entries) {
+    const folder = folderOf(e.path, cwd)
+    const verb = e.access === 'write' ? 'write in' : 'read'
+    if (!folder) {
+      const v = e.path?.value ?? {}
+      unchecked.push(e)
+      parts.push(`${verb} ${SPECIAL[v.kind] ?? v.path ?? 'a folder'}`)
+      continue
+    }
+    const tool = e.access === 'write' ? 'Edit' : 'Read'
+    calls.push({ tool, input: { file_path: folder }, cwd })
+    parts.push(`${verb} ${displayPath(folder, cwd)}`)
+  }
+  // The network isn't a call Kira's rules name: the person decides it.
+  if (params.permissions?.network?.enabled) {
+    unchecked.push('network')
+    parts.unshift('use the network')
+  }
+  return { calls, unchecked: unchecked.length > 0, summary: parts.join(', ') }
+}
+
+/** More access as a permission; "don't ask again" only when one folder is all it asks. */
+export function permissionsRequest(params, cwd, verdict) {
+  const { calls, unchecked, summary } = permissionsAsked(params, cwd)
+  const rule = !unchecked && calls.length === 1 ? verdict?.suggest : ''
+  return {
+    id: requestId(),
+    type: 'permission',
+    title: `Codex wants to ${summary || 'get more access'}`,
+    detail: params.reason ? short(params.reason, 2000) : undefined,
+    options: permissionOptions(rule),
+    action: { tool: 'Permissions', label: 'Get access', target: short(summary, 200) },
+    ...(rule ? { rule } : {}),
+    ...(verdict?.why ? { why: verdict.why } : {}),
+  }
+}
+
+/** Granted (all it asked, for this turn) or not (nothing). */
+export const permissionsResponse = (params, yes) =>
+  yes ? { permissions: params.permissions ?? {}, scope: 'turn' } : { permissions: {} }

package/src/agents/codex-review.mjs

@@ -0,0 +1,89 @@
+// Codex's code review (review/start) in Kira's agent protocol. Pure. What to review comes as Kira's
+// target (genui review.ts) and goes to Codex as its ReviewTarget; the review comes back in Codex's
+// exitedReviewMode item as the text codex-rs renders (review_format.rs), read here into the findings
+// card's event:
+//
+//   <overall explanation>
+//
+//   Full review comments:            ("Review comment:" for one)
+//
+//   - [P1] <title> — /abs/path/file.ts:3-3
+//     <body, indented two spaces>
+import { displayPath, short } from './claude-calls.mjs'
+
+const MAX_FINDINGS = 50
+const SHA = /^[0-9a-f]{4,40}$/i
+const REF = /^(?!-)[\w./-]{1,200}$/
+const HEADER = /(?:^|\n)(?:Review comment|Full review comments):\n/
+/** "- [x] title — path:3-9": the selection box only in Codex's own TUI; the location after the last " — ". */
+const LOCATED = /^- (?:\[[ x]\] )?(.*) — (.+?):(\d+)-(\d+)$/
+const UNPLACED = /^- (?:\[[ x]\] )?(.*)$/
+const PRIORITY = /^\[P([0-3])\]\s*/
+
+/** Kira's review target as Codex's review/start takes it; a branch without a base asks `base()` for one. */
+export async function codexTarget(review, base) {
+  switch (review?.type) {
+    case 'baseBranch': {
+      const branch = review.branch || (await base())
+      if (!REF.test(branch)) throw new Error(`“${branch}” isn't a branch Codex can review against`)
+      return { type: 'baseBranch', branch }
+    }
+    case 'commit':
+      if (!SHA.test(String(review.sha))) throw new Error(`“${review.sha}” isn't a commit`)
+      return { type: 'commit', sha: review.sha }
+    case 'custom':
+      return { type: 'custom', instructions: short(review.instructions, 4000) }
+    default:
+      return { type: 'uncommittedChanges' }
+  }
+}
+
+/** One finding's head line and the body lines under it. */
+function findingOf(head, body, cwd) {
+  const [, said, path, start, end] = head
+  const priority = PRIORITY.exec(said)
+  return {
+    title: short(said.replace(PRIORITY, '').trim(), 300),
+    priority: priority ? Number(priority[1]) : null,
+    path: path ? displayPath(path, cwd) : '',
+    line: start ? Number(start) : null,
+    endLine: end ? Number(end) : null,
+    body: short(body.join('\n').trim(), 2000),
+  }
+}
+
+/** Codex's rendered review: its overall explanation, and each finding. */
+export function readReview(text, cwd) {
+  const all = String(text ?? '').replace(/\r\n/g, '\n')
+  const header = HEADER.exec(all)
+  if (!header) return { summary: all.trim(), findings: [] }
+  const found = []
+  for (const line of all.slice(header.index + header[0].length).split('\n')) {
+    const head = line.startsWith('- ') ? (LOCATED.exec(line) ?? UNPLACED.exec(line)) : null
+    if (head) found.push({ head, body: [] })
+    else if (found.length && (line.startsWith('  ') || !line.trim())) found.at(-1).body.push(line.slice(2))
+  }
+  const findings = found.slice(0, MAX_FINDINGS).map(f => findingOf(f.head, f.body, cwd))
+  return { summary: all.slice(0, header.index).trim(), findings }
+}
+
+/**
+ * A review as it goes by: what it looks at (enteredReviewMode, in Codex's words) and, when it ends
+ * (exitedReviewMode), the findings card's event. Codex then repeats the review as its message; the
+ * card says it once.
+ */
+export function reviewWatch(cwd) {
+  let target = ''
+  let said = null
+  return {
+    /** A finished item: the review's event when it's the review's end, else null. */
+    completed(item) {
+      if (item.type === 'enteredReviewMode') target = String(item.review ?? '')
+      if (item.type !== 'exitedReviewMode') return null
+      said = String(item.review ?? '')
+      const { summary, findings } = readReview(said, cwd)
+      return { kind: 'review', id: item.id, target: short(target, 200), summary: short(summary, 4000), findings }
+    },
+    repeats: text => said !== null && text.trim() === said.trim(),
+  }
+}

package/src/agents/codex-steer.mjs

@@ -0,0 +1,31 @@
+// Steering a Codex turn while it runs: what a person says to Codex at work goes into the turn it's on
+// (the app server's turn/steer, held to the turn it expects) instead of waiting for it to end. Codex
+// says so in its capabilities (`steer: true`); the API sends such a message through `steer_job`
+// (job-tools.mjs), and when it isn't taken (no turn at work, or Codex refused) it waits on the job.
+import { codexInput } from './codex-input.mjs'
+
+/** A run's way into its turn at work. `request` is the app server's (codex-rpc.mjs). */
+export function turnSteering(request) {
+  let turn = null
+  return {
+    /** A turn started on the thread: what's said now goes into it. */
+    started(threadId, turnId) {
+      turn = { threadId, turnId }
+    },
+    /** The turn ended: what's said now waits for the job's end. */
+    ended() {
+      turn = null
+    },
+    /** Add the person's words to the turn at work: { steered: true }, or why not. */
+    async steer(text) {
+      if (!turn) return { steered: false, note: 'Codex has no turn at work' }
+      const { threadId, turnId } = turn
+      try {
+        await request('turn/steer', { threadId, expectedTurnId: turnId, input: codexInput(text) })
+        return { steered: true }
+      } catch (err) {
+        return { steered: false, note: String(err?.message ?? err) }
+      }
+    },
+  }
+}

package/src/agents/codex-usage.mjs

@@ -0,0 +1,101 @@
+// How full a Codex thread is and how much of the person's ChatGPT plan is left, from Codex's app
+// server: `thread/tokenUsage/updated` (the context), `account/rateLimits/read` and
+// `account/rateLimits/updated` (the limits). Becomes the protocol's `usage` event, and the words a run
+// fails with when a limit stops it: which limit, and when it resets.
+
+/** A window as Kira sends it: { usedPercent, resetsAt (Unix seconds), minutes }. */
+const windowOf = w =>
+  w && typeof w.usedPercent === 'number'
+    ? { usedPercent: w.usedPercent, resetsAt: w.resetsAt ?? null, minutes: w.windowDurationMins ?? null }
+    : null
+
+/** The context a thread fills: its last request's tokens out of the model's window; null when unknown. */
+export function contextOf(tokenUsage) {
+  const window = tokenUsage?.modelContextWindow
+  const used = tokenUsage?.last?.totalTokens
+  return window > 0 && typeof used === 'number' ? { used, window } : null
+}
+
+/** The Codex limits in a `rateLimits/read` answer: its `codex` bucket, else the single one. */
+export const snapshotOf = read => read?.rateLimitsByLimitId?.codex ?? read?.rateLimits ?? null
+
+/**
+ * A rate-limit snapshot as Kira's limits, merged over what was known: an update is sparse, and what
+ * it leaves out (null) keeps its last value. Another bucket's update (not Codex's) changes nothing.
+ */
+export function limitsOf(snapshot, prev = null) {
+  if (!snapshot || (snapshot.limitId && snapshot.limitId !== 'codex')) return prev
+  const c = snapshot.credits
+  const credits = c ? { has: !!c.hasCredits, unlimited: !!c.unlimited, balance: c.balance ?? null } : null
+  return {
+    primary: windowOf(snapshot.primary) ?? prev?.primary ?? null,
+    secondary: windowOf(snapshot.secondary) ?? prev?.secondary ?? null,
+    credits: credits ?? prev?.credits ?? null,
+    plan: snapshot.planType ?? prev?.plan ?? null,
+  }
+}
+
+/** A window's name: "5-hour", "weekly". */
+function windowName(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'
+}
+
+const LIMIT_ERRORS = new Set(['usageLimitExceeded', 'rateLimitExceeded'])
+
+/** What a run says when it stops: which limit stopped it and when it resets, else Codex's own words. */
+export function stoppedBy(turnError, limits, now = Date.now()) {
+  const said = `Codex stopped: ${turnError?.message ?? 'error'}`
+  if (!LIMIT_ERRORS.has(turnError?.codexErrorInfo)) return said
+  const full = [limits?.primary, limits?.secondary].filter(Boolean).sort((a, b) => b.usedPercent - a.usedPercent)[0]
+  if (!full) return `Codex stopped: you've reached your ChatGPT usage limit. ${turnError.message ?? ''}`.trim()
+  const when = full.resetsAt ? resetWords(full.resetsAt, now) : 'later'
+  const name = windowName(full.minutes)
+  return `Codex stopped: your ${name} ChatGPT limit is used up (${full.usedPercent}%). It resets ${when}.`
+}
+
+/** "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}`
+}
+
+const pctOf = c => (c ? Math.round((c.used / c.window) * 100) : null)
+
+/**
+ * A run's usage: fed Codex's notifications, 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 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 {
+    onTokens(tokenUsage) {
+      context = contextOf(tokenUsage) ?? context
+      send()
+    },
+    onLimits(snapshot) {
+      limits = limitsOf(snapshot, limits)
+      if (limits) send()
+    },
+    /** The limits known so far, for the words a run fails with. */
+    get limits() {
+      return limits
+    },
+    /** What the run ends with, for its stats. */
+    get stats() {
+      return { ...(context ? { context } : {}), ...(limits ? { limits } : {}) }
+    },
+  }
+}

package/src/agents/codex.mjs

@@ -1,12 +1,21 @@
 // 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.
+// change Codex asks about is decided by Kira's rules (io.check), and by the person when they ask; its
+// questions, more access and MCP servers' forms are asked as cards too (codex-ask.mjs).
 import { permissionOptions, requestId } from './protocol.mjs'
 import { TEXT_CAP, short } from './claude-calls.mjs'
 import { callsOf, codexOptionsFor, imageOf, itemAction, itemResult, strictest } from './codex-items.mjs'
 import { codexBin, openCodex } from './codex-rpc.mjs'
+import { codexInput } from './codex-input.mjs'
+import { turnSteering } from './codex-steer.mjs'
+import { codexStream } from './codex-live.mjs'
+import { liveEmitter } from './live.mjs'
 import { kiraDecides } from './checks.mjs'
+import { CODEX_ASKS, askPerson, refusedByPolicy, said } from './codex-ask.mjs'
 import { codexAgentOf, developerInstructions } from './codex-agent.mjs'
+import { snapshotOf, stoppedBy, usageFeed } from './codex-usage.mjs'
+import { codexTarget, reviewWatch } from './codex-review.mjs'
+import { defaultBranch } from '../refs.mjs'
 import { kiraSkillRoots } from '../kira-plugin.mjs'
 
 const COMMAND = 'item/commandExecution/requestApproval'
@@ -20,8 +29,9 @@ const kiraServer = ({ url }) => ({ 'mcp_servers.kira.url': url, 'mcp_servers.kir
 /**
  * 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 }.
+ * io.steerable(steer) is handed the way into the turn at work (codex-steer.mjs).
  */
-async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
+async function run({ prompt, attachments, sessionId, cwd, persona, settings, abort }, io) {
   const bin = codexBin()
   if (!bin) {
     io.emit({ kind: 'result', ok: false, error: NOT_INSTALLED, sessionId })
@@ -34,8 +44,18 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
   let error = null
   /** The files each change will touch, from when it started: what its approval is checked on. */
   const changes = new Map()
+  /** How full the thread is and the person's limits, as they change (codex-usage.mjs). */
+  const usage = usageFeed(e => io.emit(e))
+  /** A review asked for ("@codex /review"): Codex's review/start instead of a turn, its findings a card. */
+  const review = reviewWatch(cwd)
+  /** What is still being written (live.mjs): sent as it comes, the final form of each kept. */
+  const live = liveEmitter(io.emit)
+  const stream = codexStream()
   let finished
   const ended = new Promise(resolve => (finished = resolve))
+  // What the person says while a turn runs goes into it (`codex` is the app server, opened below).
+  const steering = turnSteering((method, params) => codex.request(method, params))
+  io.steerable?.(steering.steer)
 
   const decide = async (method, params) => {
     const calls = callsOf(method, params, changes.get(params.itemId)).map(c => ({ ...c, cwd: c.cwd ?? cwd }))
@@ -48,10 +68,7 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       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 })
+      refusedByPolicy(io, action.tool, verdict)
       return { decision: 'decline' }
     }
     const request = {
@@ -64,44 +81,48 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       ...(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 resolved = await askPerson(io, request, abort?.signal)
+    return { decision: said(resolved, 'allow', 'always') ? 'accept' : 'decline' }
   }
 
   const onNotify = (method, p) => {
+    const update = stream.update(method, p)
+    if (update) return live.update(update)
     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') {
+      const reviewed = review.completed(p.item)
+      if (reviewed) io.emit(reviewed)
       if (p.item.type === 'agentMessage' && p.item.text?.trim()) {
         text = p.item.text
-        io.emit({ kind: 'message', text: short(p.item.text, TEXT_CAP) })
+        if (!review.repeats(text)) live.final({ kind: 'message', id: p.item.id, 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) })
+        live.final({ kind: 'action_result', id: p.item.id, ...itemResult(p.item) })
         const image = imageOf(p.item)
         if (image) io.emit(image)
       }
+      const thought = stream.done(p.item)
+      if (thought) live.final(thought)
       changes.delete(p.item.id)
+    } else if (method === 'thread/tokenUsage/updated' && p.threadId === thread) {
+      usage.onTokens(p.tokenUsage)
+    } else if (method === 'account/rateLimits/updated') {
+      usage.onLimits(p.rateLimits)
     } else if (method === 'error' && !p.willRetry) {
-      error = `Codex stopped: ${p.error?.message ?? 'error'}`
+      error = stoppedBy(p.error, usage.limits)
     } else if (method === 'turn/completed' && p.turn?.id === turnId) {
       const t = p.turn
-      if (t.status === 'failed') error = `Codex stopped: ${t.error?.message ?? 'failed'}`
+      steering.ended()
+      if (t.status === 'failed') error = stoppedBy(t.error ?? { message: 'failed' }, usage.limits)
       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)
+    if (Object.hasOwn(CODEX_ASKS, method)) return CODEX_ASKS[method](params, { io, cwd, signal: abort?.signal })
     throw new Error(`Kira does not answer ${method}`)
   }
 
@@ -115,6 +136,11 @@ 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')
+    // Their limits as the run starts (not waited on): a ChatGPT sign-in has them, a key doesn't.
+    void codex.request('account/rateLimits/read', { excludeResetCreditDetails: true }).then(
+      read => usage.onLimits(snapshotOf(read)),
+      () => {},
+    )
     // 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.
@@ -127,12 +153,17 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
       : 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 } : {}) })
+    const input = codexInput(prompt, attachments)
+    const target = settings?.review ? await codexTarget(settings.review, () => defaultBranch(cwd)) : null
+    const started = target
+      ? await codex.request('review/start', { threadId: thread, target })
+      : await codex.request('turn/start', { threadId: thread, input, ...(effort ? { effort } : {}) })
     turnId = started.turn.id
+    steering.started(thread, turnId)
     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
+    const stats = { ...(end.durationMs ? { durationMs: end.durationMs } : {}), ...usage.stats }
+    for (const kept of stream.ends()) live.final(kept)
     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) {
@@ -140,9 +171,12 @@ async function run({ prompt, sessionId, cwd, persona, settings, abort }, io) {
     io.emit({ kind: 'result', ok: false, error: message, sessionId: thread })
     return { ok: false, error: message, sessionId: thread }
   } finally {
+    live.close()
     abort?.signal.removeEventListener('abort', stop)
     codex.close()
   }
 }
 
-export const codex = { id: 'codex', name: 'Codex', run, capabilities: { resume: true, requests: ['permission'] } }
+/** steer: what a person says while it works goes into the turn at work (codex-steer.mjs). */
+const capabilities = { resume: true, requests: ['permission', 'choice'], steer: true }
+export const codex = { id: 'codex', name: 'Codex', run, capabilities }

package/src/agents/live.mjs

@@ -0,0 +1,52 @@
+// What an agent is still in the middle of (its reply as it's written, its thinking, a running
+// command's output, its plan, the turn's changes) goes out as it happens, as transient events
+// (protocol.mjs): the API forwards them to the screens following the job and never stores them.
+// Each id is sent at most once every `every` ms, the latest update winning; the event that settles
+// an id (its final form, stored as usual) cancels what's still pending for it, so it is never
+// overtaken by a stale update.
+
+const LIVE_EVERY = 250
+
+/** A throttled emitter over io.emit: `update` for transient events, `final` for the ones that settle them. */
+export function liveEmitter(emit, every = LIVE_EVERY) {
+  /** id -> the update waiting for its turn, and its timer. */
+  const pending = new Map()
+  /** id -> when an update for it last went out. */
+  const sent = new Map()
+  const cancel = id => {
+    clearTimeout(pending.get(id)?.timer)
+    pending.delete(id)
+  }
+  const send = event => {
+    sent.set(event.id, Date.now())
+    emit({ ...event, transient: true })
+  }
+  return {
+    update(event) {
+      const waiting = pending.get(event.id)
+      if (waiting) {
+        waiting.event = event
+        return
+      }
+      const wait = (sent.get(event.id) ?? -Infinity) + every - Date.now()
+      if (wait <= 0) return send(event)
+      const entry = { event, timer: null }
+      entry.timer = setTimeout(() => {
+        pending.delete(event.id)
+        send(entry.event)
+      }, wait)
+      pending.set(event.id, entry)
+    },
+    final(event) {
+      if (event.id !== undefined) {
+        cancel(event.id)
+        sent.delete(event.id)
+      }
+      emit(event)
+    },
+    /** The run is over: nothing pending goes out after its end. */
+    close() {
+      for (const id of [...pending.keys()]) cancel(id)
+    },
+  }
+}

package/src/agents/protocol.mjs

@@ -2,15 +2,26 @@
 // agent. The API, the portal and the glasses only ever see these shapes.
 //
 //   session          { kind, sessionId, model? }
-//   message          { kind, text }                        the agent said something
+//   message          { kind, id?, text }                   the agent said something
+//   thinking         { kind, id, text }                    its reasoning, as the agent summarizes it
+//   output           { kind, id, text }                    a running action's output so far (always transient)
+//   plan             { kind, id, explanation?, steps: [{ text, status: pending | inProgress | completed }] }
+//   changes          { kind, id, files: [{ path, adds, dels }], diff, truncated? }   the turn's whole diff
 //   action           { kind, id, type, tool, label, target, note?, detail? }
 //                      type: read | search | edit | write | run | fetch | delegate | plan | other
 //                      detail: { edit: {old,new,all} | edits: [...] | content | command }
 //   action_result    { kind, id, ok, preview? }
 //   request          { kind, request: AgentRequest }        needs a person; the job waits
 //   request_resolved { kind, id, answer, by }              by: voice | lens | phone | portal | timeout | policy
+//   usage            { kind, context: {used,window} | null, limits: CodexLimits | null }   Codex: how full its
+//                      thread is and the person's ChatGPT limits ({primary,secondary: {usedPercent,resetsAt,minutes},
+//                      credits, plan}), the latest of both each time one changes (codex-usage.mjs)
 //   result           { kind, ok, text?, error?, sessionId?, stats? }
 //
+// Any event with an id may come first as `transient: true` (live.mjs): what is still being written,
+// sent live as it changes and never stored. The next event with the same id that isn't transient is
+// its final form (an output's is its action_result), stored as usual.
+//
 // AgentRequest:
 //   { id, type: permission | choice | text | plan, title, detail?, options: [{id,label,description?}],
 //     multi?, allowText?, action?: {tool,label,target}, questions?: [{id, question, header, options, multi}] }

package/src/job-tools.mjs

@@ -1,5 +1,5 @@
 // The bridge's coding-agent jobs: starting one (acknowledged at once, streamed as it runs,
-// reported when done) and stopping one.
+// reported when done), stopping one, and steering one (words into its turn at work).
 import { agentById } from './agents/index.mjs'
 import { awaitAnswer, forgetJob } from './agents/answers.mjs'
 import { resolveCwd, folderExists } from './claude-run.mjs'
@@ -10,7 +10,7 @@ import { sendIfLive, sendLive } from './connection.mjs'
 import { log } from './host.mjs'
 import { jobEndLine, jobStartLine, promptOf } from './job-format.mjs'
 
-/** Running jobs, by id, so a person can stop one. */
+/** Running jobs, by id, so a person can stop one (abort) or, for an agent that can, steer it. */
 const running = new Map()
 
 /** The ids of the jobs running here now. */
@@ -41,30 +41,42 @@ export const jobTools = {
     }
     const sessionId = args.session_id
     log(jobStartLine({ agentId: agent.id, jobId, persona: args.persona, sessionId, dir: display(dir), prompt }))
+    const abort = new AbortController()
+    const live = { abort, steer: null }
     let seq = 0
     const io = {
       emit: event => sendLive({ type: 'job.event', jobId, seq: ++seq, at: new Date().toISOString(), event }),
       ask: (request, signal) => awaitAnswer(jobId, request, signal),
       check: call => checkCall(jobId, call, sendIfLive),
+      steerable: steer => (live.steer = steer),
     }
-    const abort = new AbortController()
-    running.set(jobId, abort)
+    running.set(jobId, live)
     // Started is said at once. The git snapshot (what changed, reported at the end) is taken first but
     // in the background: in a big repository it takes longer than the API waits for this answer.
     const before = snapshot(dir).catch(() => null)
     const persona = args.persona ?? null
     const settings = args.settings ?? null
-    const job = { prompt, sessionId, cwd: dir, persona, settings, abort }
+    // What came with it from Kira, already copied here (the prompt names their paths): codex-input.mjs.
+    const attachments = Array.isArray(args.attachments) ? args.attachments : []
+    const job = { prompt, attachments, sessionId, cwd: dir, persona, settings, abort }
     void before.then(() => agent.run(job, io)).then(outcome => finish({ jobId, agent, dir, before, outcome }))
     return { started: true, agent: agent.id, cwd: display(dir) }
   },
   /** Stop a running job: the agent is cut off; whatever it committed stays. */
   stop_job(args) {
-    const abort = running.get(String(args.job_id ?? ''))
-    if (!abort) return { stopped: false, note: 'no such job running here' }
-    abort.abort()
+    const job = running.get(String(args.job_id ?? ''))
+    if (!job) return { stopped: false, note: 'no such job running here' }
+    job.abort.abort()
     return { stopped: true }
   },
+  /** A person's words into a running job's turn, for an agent that takes them mid-turn (codex-steer.mjs). */
+  async steer_job(args) {
+    const job = running.get(String(args.job_id ?? ''))
+    const text = String(args.text ?? '').trim()
+    if (!job || !text) return { steered: false, note: job ? 'nothing to say' : 'no such job running here' }
+    if (!job.steer) return { steered: false, note: 'this agent takes nothing mid-turn' }
+    return job.steer(text)
+  },
   /** Older API builds still call ask_claude. */
   ask_claude(args) {
     return jobTools.run_agent({ ...args, agent: 'claude' })

package/src/refs.mjs

@@ -58,3 +58,9 @@ export async function gitRefs(dir) {
   ])
   return { cwd: display(main), branches: joinRefs(parseBranches(branches), parseWorktrees(worktrees), main) }
 }
+
+/** The branch a folder's work goes back into: its remote's default (origin/HEAD), else main. */
+export async function defaultBranch(dir) {
+  const head = (await git(dir, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']))?.trim()
+  return head ? head.replace(/^origin\//, '') : 'main'
+}