Skip to content

armgit / chums

Public Imported from GitHub
0

Talk to Claude Code and Codex agents from an Apple Watch and an iPhone. Each agent is a character on the watch.

36.6 KB
Raw Blame
// Agents the hub runs itself: OpenAI Codex, GitHub Copilot, and any Agent Client Protocol agent. (Claude Code agents
// are interactive sessions in a terminal of their own instead: bin/chums-agents, the channel and the hooks.)
// docs/other-agents.md has the why; design/STATES.md has every signal's meaning on the watch.
//
//   runtime 'codex'    `codex app-server`: OpenAI's own JSON-RPC protocol, the one Codex's IDE extension, desktop app
//                      and terminal use, on a Unix socket of the agent's own. The hub is a client of it, and a Codex
//                      terminal can be one too, on the same thread at the same time (bin/chums-agents open).
//   runtime 'copilot'  the GitHub Copilot SDK (@github/copilot-sdk): GitHub's own JSON-RPC client for the Copilot CLI
//                      runtime, which it runs (its bundled runtime, or `command` for the installed `copilot`).
//   runtime 'acp'      any Agent Client Protocol agent, from its `command`: ["copilot", "--acp"], ["gemini",
//                      "--experimental-acp"], ["npx", "@agentclientprotocol/claude-agent-acp"]…
//
// Each run gives the watch what a Claude Code session gives it, in the same words: the hub's hook vocabulary
// (UserPromptSubmit, PreToolUse, PostToolUse, Stop, StopFailure, PreCompact…), approval cards and spoken replies.
// Orders arrive through deliver(); the agent replies with chums_reply / chums_show from the Chums MCP server
// (channel/chums-channel.mjs in tools-only mode), and when a turn from the watch ends without one, the hub speaks the
// first sentence of the agent's last message instead, so the watch never stays silent.
import { spawn, execFileSync } from 'node:child_process'
import fs from 'node:fs'
import os from 'node:os'
import path from 'node:path'
import crypto from 'node:crypto'
import { lines, wsUnix, peer } from './jsonrpc.mjs'
import { standingFor, WATCH_GUIDE, MAX_WORDS, Owner, markFor, wordsFor } from './standing.mjs'

const ROOT = path.join(import.meta.dirname, '..')
const CHANNEL = path.join(ROOT, 'channel/chums-channel.mjs')
const REAL_HOME = os.userInfo().homedir                    // the CLIs' logins live there, whatever HOME the hub has
const VERSION = '0.1.0'

export const RUNTIMES = ['claude', 'codex', 'copilot', 'acp']
/// Agents whose process the hub runs (not a Claude Code session in its own terminal).
export const runByHub = a => !!a.runtime && a.runtime !== 'claude'

const DEBUG = !!process.env.CHUMS_RUNTIME_DEBUG                 // every event the agent sends, in its host log
const LIMIT = /rate.?limit|quota|too many requests|\b429\b|usage limit|allowance|overloaded|capacity|exceeded your/i
const short = (t, n = 60) => { const s = String(t ?? '').replace(/\s+/g, ' ').trim(); return s.length > n ? s.slice(0, n - 1) + '…' : s }

/// The first sentence of an agent's answer, said aloud: no markdown, code, links or paths, 15 words at most. With a
/// longer limit (an order from the iPhone), as many whole sentences as fit in it.
export function spokenLine(text, limit = MAX_WORDS) {
  const t = String(text ?? '')
    .replace(/```[\s\S]*?```/g, ' ')
    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
    .replace(/https?:\/\/\S+/g, 'a link')
    .replace(/(^|\s)(~|\.{0,2})?\/[\w.\-/]+/g, (m, sp, _p, off, all) => sp + m.trim().split('/').filter(Boolean).pop())
    .replace(/[`*]|^#+\s*|^\s*([-•]|\d+\.)\s+/gm, '')
    .replace(/\s+/g, ' ').trim()
  if (!t) return ''
  // sentences end at . ! ? before a space or the end (so "notes.md" stays whole)
  const sentences = (t.match(/.+?[.!?]+(?=\s|$)|.+$/g) ?? [t]).map(x => x.trim())
  let first = sentences[0]
  if (limit > MAX_WORDS) for (const s of sentences.slice(1)) {             // the watch: the first sentence only
    if ((first + ' ' + s).split(' ').length > limit) break
    first += ' ' + s
  }
  const words = first.split(' ')
  return words.length > limit ? words.slice(0, limit).join(' ').replace(/[,;:]$/, '') + '…' : first
}

/// What a shell command an agent runs looks like on the watch, in Claude Code's words (hub/hub.mjs toolEvent).
function shellTool(command, actions) {
  const a = actions?.length === 1 ? actions[0] : null
  if (a?.type === 'read' && a.path) return { tool: 'Read', input: { file_path: a.path } }
  if (a?.type === 'search') return { tool: 'Grep', input: { pattern: a.query ?? a.command } }
  if (a?.type === 'listFiles') return { tool: 'Glob', input: { pattern: a.path ?? a.command } }
  // codex wraps every command in the login shell: /bin/zsh -lc '…'
  const plain = actions?.length ? actions.map(x => x.command).join(' && ') : String(command ?? '').replace(/^\S*\/(ba|z)?sh -l?c '([\s\S]*)'$/, '$2')
  return { tool: 'Bash', input: { command: plain } }
}

/// An ACP tool call in Claude Code's words.
function acpTool(tc) {
  const input = tc.rawInput ?? {}, title = String(tc.title ?? '')
  const file = tc.locations?.[0]?.path ?? input.path ?? input.file_path ?? input.filePath
  switch (tc.kind) {
    case 'read': return { tool: 'Read', input: { file_path: file ?? title } }
    case 'edit': case 'delete': case 'move': return { tool: 'Edit', input: { file_path: file ?? title } }
    case 'search': return { tool: 'Grep', input: { pattern: input.pattern ?? input.query ?? title } }
    case 'fetch': return { tool: 'WebFetch', input: { url: input.url ?? input.query ?? title } }
    case 'execute': return { tool: 'Bash', input: { command: input.command ?? input.commands?.join(' && ') ?? title } }
    case 'think': return { tool: 'Task', input: { description: title } }
    default: return { tool: short(title, 40) || 'Tool', input }
  }
}
// the agent calling Chums' own tools: never an event or an approval card, like mcp__chums__* in Claude Code
const CHUMS_TOOL = /chums[\w.-]*(reply|show)\b/i
const isChums = tc => CHUMS_TOOL.test(`${tc.title ?? ''} ${tc.toolCallId ?? ''} ${JSON.stringify(tc._meta ?? '')}`)

// ---------- one agent's process, kept running ----------
class Runner {
  constructor(agent, hub) {
    this.a = agent; this.hub = hub
    this.s = null                    // the hub's session while the agent is up
    this.asks = new Map()            // approval card id -> resolve(behavior)
    this.turn = null                 // { startedAt, text, fromWatch, tools }
    this.stopped = false; this.backoff = 5_000; this.upAt = 0; this.runs = 0; this.ended = 0
    this.logFile = path.join(hub.dir, 'agents', `${agent.id}.host.log`)
    fs.mkdirSync(path.dirname(this.logFile), { recursive: true })
  }
  note(...m) { fs.appendFileSync(this.logFile, `${new Date().toISOString().slice(0, 19).replace('T', ' ')} ${m.join(' ')}\n`) }
  env(extra = {}) {
    const PATH = [`${REAL_HOME}/.npm-global/bin`, '/opt/homebrew/bin', '/usr/local/bin', '/usr/bin', '/bin', '/usr/sbin', '/sbin', process.env.PATH].filter(Boolean).join(':')
    const env = { ...process.env, HOME: REAL_HOME, PATH, ...extra }
    for (const k of ['CHUMS_NO_WHISPER', 'CHUMS_NAME', 'CHUMS_SESSION']) delete env[k]
    return env
  }
  spawnAgent(cmd, args, stdio = ['pipe', 'pipe', 'pipe']) {
    fs.mkdirSync(this.a.cwd, { recursive: true })
    const child = spawn(cmd, args, { cwd: this.a.cwd, env: this.env(), stdio })
    child.on('error', e => this.note('could not start:', e.message))
    const out = fs.openSync(this.logFile, 'a')
    child.stderr?.on('data', d => fs.writeSync(out, d))
    child.on('exit', (code, sig) => { this.note(`exited (${sig ?? code})`); fs.closeSync(out); this.exited() })
    this.child = child
    return child
  }
  start() {
    this.upAt = Date.now(); this.runs++
    this.run().then(() => { this.note('running'); this.hub.log(`${this.a.id}: ${this.a.runtime} running`) })
      .catch(e => { this.note('not started:', e.message); this.hub.log(`${this.a.id}: ${this.a.runtime} not started: ${e.message}`); this.kill(); this.exited() })
  }
  kill() { try { this.child?.kill() } catch {} }
  /// The run is over (its process exited, or it never got going): the agent leaves the watch, and starts again later.
  exited() {
    if (this.ended === this.runs) return
    this.ended = this.runs
    if (this.s) { this.hub.leave(this.s.id); this.s = null }
    this.asks.clear(); this.turn = null; this.child = null
    if (this.stopped) return
    if (Date.now() - this.upAt > 120_000) this.backoff = 5_000           // it had been up a while: a fresh start
    const wait = this.backoff; this.backoff = Math.min(this.backoff * 2, 120_000)
    this.note(`starting again in ${wait / 1000} s`)
    setTimeout(() => !this.stopped && this.start(), wait).unref?.()
  }
  stop() { this.stopped = true; this.kill() }
  join(source) {
    this.s = this.hub.join({ id: this.sid, name: this.a.id, cwd: this.a.cwd, driver: this })
    this.hub.hook(this.s, 'SessionStart', { source })
  }

  // the hub's side: an order or a verdict for this agent
  deliver(item) {
    if (item.type === 'order') this.device = item.device                // its answer's length follows where it was asked
    if (item.type === 'verdict') { const r = this.asks.get(item.requestId); if (r) { this.asks.delete(item.requestId); r(item.behavior) } }
    else if (item.type === 'order') this.order(item)
  }
  /// An approval card on the watch; resolves 'allow' or 'deny' when it's answered.
  ask(tool, description, input) {
    const requestId = crypto.randomBytes(5).toString('hex')
    return { requestId, answer: new Promise(resolve => { this.asks.set(requestId, resolve); this.hub.ask(this.s, { requestId, tool, description, input }) }) }
  }
  newTurn(fromWatch) {
    this.turn = { startedAt: Date.now(), text: '', fromWatch, tools: new Map() }
    this.hub.hook(this.s, 'UserPromptSubmit')
  }
  /// The turn ended. A turn from the watch that didn't speak gets its answer's first sentence said for it.
  finish(how, error) {
    const s = this.s, t = this.turn
    this.turn = null
    if (!s) return
    if (how === 'interrupted') this.hub.react(s, 'interrupt')
    if (how === 'done' || how === 'interrupted') {
      const line = spokenLine(t?.text, wordsFor(this.device))
      if (t?.fromWatch && line && !(s.lastSpokeAt > t.startedAt)) this.hub.reply(s, line, 'done', 'final message')
      this.hub.hook(s, 'Stop')
    } else this.hub.hook(s, 'StopFailure', { error: LIMIT.test(error) ? 'rate_limit' : short(error) || 'error' })
  }
}

// ---------- Agent Client Protocol (`copilot --acp`, `gemini --experimental-acp`, the ACP adapters…) ----------
class AcpRunner extends Runner {
  command() {
    if (!this.a.command?.length) throw new Error('an acp agent needs "command", e.g. ["copilot", "--acp"]')
    return [...this.a.command, ...(this.a.args ?? [])]
  }
  async run() {
    const [cmd, ...args] = this.command()
    this.sid = crypto.randomUUID(); this.queue = []; this.busy = false; this.primed = false
    const child = this.spawnAgent(cmd, args)
    this.rpc = peer(lines(child), {
      onRequest: (m, p) => this.request(m, p), onNotification: (m, p) => this.update(m, p), log: (...x) => this.note(...x),
    })
    const init = await this.rpc.request('initialize', {
      protocolVersion: 1, clientCapabilities: { fs: { readTextFile: false, writeTextFile: false }, terminal: false },
      clientInfo: { name: 'chums', title: 'Chums', version: VERSION },
    }, 60_000)
    this.note(`initialized: ${init.agentInfo?.name ?? cmd} ${init.agentInfo?.version ?? ''} (protocol ${init.protocolVersion})`)
    const env = { CHUMS_SESSION: this.sid, CHUMS_HUB: this.hub.url, CHUMS_TOKEN: this.hub.token, CHUMS_NAME: this.a.id }
    const mcpServers = this.a.chumsTools === false ? [] : [{ name: 'chums', command: process.execPath, args: [CHANNEL], env: Object.entries(env).map(([name, value]) => ({ name, value })) }]
    let resumed = false
    if (this.a.sessionId && init.agentCapabilities?.loadSession) {
      this.loading = true                                     // the agent replays the conversation: none of it is news
      try { await this.rpc.request('session/load', { sessionId: this.a.sessionId, cwd: this.a.cwd, mcpServers }, 120_000); resumed = true }
      catch (e) { this.note(`couldn't load ${this.a.sessionId}: ${e.message}; starting a new one`) }
      this.loading = false
    }
    if (!resumed) {
      const r = await this.rpc.request('session/new', { cwd: this.a.cwd, mcpServers }, 120_000)
      this.hub.saveSessionId(this.a.id, r.sessionId)
    }
    this.acpSession = this.a.sessionId
    this.join(resumed ? 'resume' : 'startup')
  }
  order(item) { this.queue.push(item); if (!this.busy) this.pump() }
  // one prompt at a time (the protocol's rule); orders said meanwhile wait their turn
  async pump() {
    this.busy = true
    while (this.queue.length && this.s) {
      const { text, device } = this.queue.shift()
      const intro = this.primed ? '' : `[Standing instructions from Chums, for this whole conversation:]\n${standingFor(this.a)}\n${WATCH_GUIDE}\n\n`
      this.primed = true
      this.newTurn(true)
      try {
        const r = await this.rpc.request('session/prompt', { sessionId: this.acpSession, prompt: [{ type: 'text', text: `${intro}${markFor(device)} ${text}` }] })
        const stop = r?.stopReason ?? 'end_turn'
        if (stop === 'end_turn') this.finish('done')
        else if (stop === 'cancelled') this.finish('interrupted')
        else this.finish('failed', { max_tokens: 'max output tokens', max_turn_requests: 'too many turns', refusal: 'refused' }[stop] ?? stop)
      } catch (e) {
        if (e.code === 'closed') break
        this.note('prompt failed:', e.message); this.finish('failed', e.message)
      }
    }
    this.busy = false
  }
  update(method, p) {
    if (DEBUG) this.note('<-', method, p.update?.sessionUpdate ?? '', this.loading ? '(loading)' : '')
    if (method !== 'session/update' || this.loading || !this.s) return
    const u = p.update ?? {}, s = this.s
    this.turn ??= { startedAt: Date.now(), text: '', fromWatch: false, tools: new Map() }
    const tools = this.turn.tools
    switch (u.sessionUpdate) {
      case 'agent_message_chunk':
        if (u.content?.type === 'text') this.turn.text += u.content.text
        break
      case 'tool_call': {
        if (tools.has(u.toolCallId)) break
        this.turn.text = ''                                       // its answer is what it says after its last tool call
        if (isChums(u)) { tools.set(u.toolCallId, { chums: true }); break }
        const { tool, input } = acpTool(u)
        tools.set(u.toolCallId, { tool, kind: u.kind, title: u.title, rawInput: u.rawInput, locations: u.locations })
        this.hub.hook(s, 'PreToolUse', { tool, input })
        this.toolDone(u)
        break
      }
      case 'tool_call_update': this.toolDone(u); break
    }
  }
  toolDone(u) {
    const t = this.turn?.tools.get(u.toolCallId)
    if (!t || t.chums || t.done || !['completed', 'failed'].includes(u.status)) return
    t.done = true
    const said = (u.content ?? []).map(c => c.content?.text ?? '').join(' ')
    if (u.status === 'failed') this.hub.hook(this.s, 'PostToolUseFailure', { tool: t.tool, error: short(said || 'failed', 80) })
    else this.hub.hook(this.s, 'PostToolUse', { tool: t.tool, result: JSON.stringify(u.rawOutput ?? said).slice(-1500) })
  }
  async request(method, p) {
    if (method !== 'session/request_permission') throw Object.assign(new Error(`${method} isn't offered`), { code: -32601 })
    const known = this.turn?.tools.get(p.toolCall?.toolCallId) ?? {}
    const tc = { ...known, ...p.toolCall, kind: p.toolCall?.kind ?? known.kind, rawInput: p.toolCall?.rawInput ?? known.rawInput }
    const pick = (...kinds) => { for (const k of kinds) { const o = p.options?.find(x => x.kind === k); if (o) return { outcome: { outcome: 'selected', optionId: o.optionId } } } return { outcome: { outcome: 'cancelled' } } }
    if (known.chums || isChums(tc)) return pick('allow_once', 'allow_always')            // speaking to the watch is always allowed
    const { tool, input } = acpTool(tc)
    const behavior = await this.ask(tool, String(tc.title ?? tool), input).answer
    return behavior === 'allow' ? pick('allow_once', 'allow_always') : pick('reject_once', 'reject_always')
  }
}

// ---------- GitHub Copilot: its SDK ----------
let copilotSdk = null
const loadCopilotSdk = async () => copilotSdk ??= await import('@github/copilot-sdk')
  .catch(e => { throw new Error(`runtime "copilot" needs the Copilot SDK, an optional dependency (about 130 MB): cd ${ROOT} && npm install --no-save @github/copilot-sdk (${e.message})`) })

/// A Copilot CLI tool call in Claude Code's words.
function copilotTool(name, args, d = {}) {
  const i = args ?? {}, n = String(name ?? '').toLowerCase()
  const file = i.path ?? i.file_path ?? i.filePath ?? i.file
  if (d.shellToolInfo || ['bash', 'shell', 'powershell', 'zsh'].includes(n)) return { tool: 'Bash', input: { command: i.command ?? i.fullCommandText ?? name } }
  if (['view', 'read', 'read_file', 'show_file'].includes(n)) return { tool: 'Read', input: { file_path: file } }
  if (['create', 'write', 'write_file', 'create_file'].includes(n)) return { tool: 'Write', input: { file_path: file } }
  if (/edit|replace|patch/.test(n)) return { tool: 'Edit', input: { file_path: file } }
  if (['grep', 'rg', 'search', 'search_code'].includes(n)) return { tool: 'Grep', input: { pattern: i.pattern ?? i.query } }
  if (n === 'glob') return { tool: 'Glob', input: { pattern: i.pattern } }
  if (/fetch/.test(n)) return { tool: 'WebFetch', input: { url: i.url } }
  if (/web_?search/.test(n)) return { tool: 'WebSearch', input: { query: i.query } }
  if (['task', 'agent', 'subagent'].includes(n)) return { tool: 'Task', input: { description: i.description ?? i.prompt } }
  return { tool: short(d.toolTitle ?? (d.mcpServerName ? `${d.mcpServerName} ${d.mcpToolName ?? name}` : name), 40) || 'Tool', input: i }
}

class CopilotRunner extends Runner {
  async run() {
    const { CopilotClient, RuntimeConnection } = await loadCopilotSdk()
    const a = this.a
    this.sid = crypto.randomUUID(); this.calls = new Map()
    fs.mkdirSync(a.cwd, { recursive: true })
    const env = this.env()
    // the SDK's own Copilot runtime (pinned with the SDK), or the installed CLI when `command` names it
    this.client = new CopilotClient({
      workingDirectory: a.cwd, logLevel: 'error',
      ...(a.command?.length ? { connection: RuntimeConnection.forStdio({ path: a.command[0], args: a.command.slice(1), env }) } : { env }),
    })
    await this.client.start()
    // the SDK watches its runtime's process this way itself; when it exits, so does this run
    this.client.processExitPromise?.catch(e => { this.note(e.message); this.exited() })
    const chums = { CHUMS_SESSION: this.sid, CHUMS_HUB: this.hub.url, CHUMS_TOKEN: this.hub.token, CHUMS_NAME: a.id }
    const config = {
      ...(a.model ? { model: a.model } : {}),
      workingDirectory: a.cwd, additionalDirectories: a.addDirs ?? [],
      systemMessage: { mode: 'append', content: `${standingFor(a)}\n\n${WATCH_GUIDE}` },
      mcpServers: a.chumsTools === false ? {} : { chums: { type: 'local', command: process.execPath, args: [CHANNEL], env: chums, tools: ['*'] } },
      onPermissionRequest: req => this.permission(req),
    }
    let session = null, resumed = false
    if (a.sessionId) {
      try { session = await this.client.resumeSession(a.sessionId, config); resumed = true }
      catch (e) { this.note(`couldn't resume ${a.sessionId}: ${e.message}; starting a new session`) }
    }
    if (!session) {
      session = await this.client.createSession(config)
      this.hub.saveSessionId(a.id, session.sessionId)
    }
    this.session = session
    session.on(ev => { try { this.event(ev) } catch (e) { this.note('event:', ev.type, e.message) } })
    this.join(resumed ? 'resume' : 'startup')
    this.note(`session ${session.sessionId}`)
  }
  kill() { const c = this.client; this.client = null; c?.forceStop?.().catch(() => {}) }

  async order(item) {
    // said while it works, the order waits for the turn to end (the SDK's queue, as typing into its terminal would);
    // it becomes a turn of its own when the runtime takes it up (user.message). Its `immediate` mode, which would
    // push it into the turn in progress, can lose a message said just as a turn ends.
    if (!this.turn) this.newTurn(true)
    try { await this.session.send({ prompt: `${markFor(item.device)} ${item.text}` }) }
    catch (e) { this.note('send failed:', e.message); this.finish('failed', e.message) }
  }
  event(ev) {
    if (DEBUG && !/delta|usage|model\.|background_tasks/.test(ev.type)) this.note('<-', ev.type, `turn: ${!!this.turn}`)
    const s = this.s, d = ev.data ?? {}
    if (!s) return
    switch (ev.type) {
      case 'tool.execution_start': {
        if (d.mcpServerName === 'chums' || CHUMS_TOOL.test(d.toolName)) { this.calls.set(d.toolCallId, { chums: true }); break }
        const { tool, input } = copilotTool(d.toolName, d.arguments, d)
        this.calls.set(d.toolCallId, { tool })
        this.turn ??= { startedAt: Date.now(), text: '', fromWatch: false, tools: new Map() }
        this.hub.hook(s, 'PreToolUse', { tool, input })
        break
      }
      case 'tool.execution_complete': {
        const c = this.calls.get(d.toolCallId)
        if (!c || c.chums) break
        this.calls.delete(d.toolCallId)
        const failed = !d.success || (d.shellExecution?.exitCode ?? 0) !== 0
        if (!d.success && d.error && !/denied|declined|reject/i.test(d.error.message)) this.hub.hook(s, 'PostToolUseFailure', { tool: c.tool, error: short(d.error.message, 80) })
        else this.hub.hook(s, 'PostToolUse', { tool: c.tool, result: JSON.stringify({ is_error: failed }) })
        break
      }
      case 'user.message': if (!this.turn) this.newTurn(true); break               // a queued order, taken up now
      // its answer: the last message that isn't on its way to a tool call
      case 'assistant.message': if (this.turn && d.content?.trim() && !d.toolRequests?.length) this.turn.text = d.content; break
      case 'session.error':
        if (this.turn) this.finish('failed', ['rate_limit', 'quota'].includes(d.errorType) ? 'rate limit' : d.message ?? d.errorType)
        break
      case 'session.idle': if (this.turn) this.finish(d.aborted ? 'interrupted' : 'done'); break
      case 'session.compaction_start': this.hub.hook(s, 'PreCompact', { trigger: 'auto' }); break
      case 'session.compaction_complete': this.hub.hook(s, 'PostCompact'); break
      case 'subagent.started': this.hub.hook(s, 'SubagentStart', { agent: d.toolCallId }); break
      case 'subagent.completed': case 'subagent.failed': this.hub.hook(s, 'SubagentStop', { agent: d.toolCallId }); break
    }
  }
  async permission(req) {
    if ((req.kind === 'mcp' && req.serverName === 'chums') || (req.kind === 'custom-tool' && CHUMS_TOOL.test(req.toolName))) return { kind: 'approve-once' }
    const [tool, description, input] =
      req.kind === 'shell' ? ['Bash', req.intention, { command: req.fullCommandText }]
      : req.kind === 'write' ? [req.newFileContents != null && !req.diff ? 'Write' : 'Edit', req.intention, { file_path: req.fileName }]
      : req.kind === 'read' ? ['Read', req.intention, { file_path: req.path }]
      : req.kind === 'url' ? ['WebFetch', req.intention, { url: req.url }]
      : req.kind === 'mcp' ? [`${req.serverName} ${req.toolName}`, req.toolTitle, req.args ?? {}]
      : [req.kind, req.intention ?? req.toolName ?? req.kind, req.args ?? {}]
    const ok = await this.ask(tool, String(description || tool), input).answer
    return ok === 'allow' ? { kind: 'approve-once' } : { kind: 'reject', feedback: `${Owner} said no, on the watch.` }
  }
}

// ---------- OpenAI Codex: its app-server ----------
const SOCK_DIR = `/tmp/chums-${process.getuid?.() ?? 'u'}`        // short: a Unix socket's path has room for 103 bytes
const toml = v => JSON.stringify(v)                               // TOML's strings and arrays of strings are JSON's

class CodexRunner extends Runner {
  socket() { return path.join(SOCK_DIR, `${this.hub.port}-${this.a.id}.sock`) }
  /// An app-server a previous hub left running on this socket (a hub killed hard can't stop it): stop it first.
  stale(sock) {
    try {
      const { pid } = JSON.parse(fs.readFileSync(path.join(this.hub.dir, 'agents', `${this.a.id}.runtime.json`), 'utf8'))
      const cmd = execFileSync('/bin/ps', ['-o', 'command=', '-p', String(pid)], { encoding: 'utf8' })
      if (cmd.includes('app-server') && cmd.includes(sock)) { process.kill(pid); this.note(`stopped the app-server a previous run left (pid ${pid})`) }
    } catch {}
  }
  async run() {
    const a = this.a, sock = this.socket()
    fs.mkdirSync(SOCK_DIR, { recursive: true, mode: 0o700 })
    // a folder of our own, not a link to one, that only we can open (one made earlier with other modes is closed)
    const dir = fs.lstatSync(SOCK_DIR)
    if (!dir.isDirectory() || dir.uid !== process.getuid()) throw new Error(`${SOCK_DIR} isn't ours`)
    if (dir.mode & 0o077) fs.chmodSync(SOCK_DIR, 0o700)
    this.stale(sock)
    fs.rmSync(sock, { force: true })
    this.sid = crypto.randomUUID(); this.files = new Map(); this.byRpc = new Map(); this.activeTurn = null
    // the token's file, not the token: Codex's -c arguments are in the process list, which every user of the Mac can read
    const env = `{ CHUMS_SESSION = ${toml(this.sid)}, CHUMS_HUB = ${toml(this.hub.url)}, CHUMS_CONFIG = ${toml(path.join(this.hub.dir, 'config.json'))}, CHUMS_NAME = ${toml(a.id)} }`
    const config = [
      ...(a.chumsTools === false ? [] : [
        `mcp_servers.chums.command=${toml(process.execPath)}`, `mcp_servers.chums.args=[${toml(CHANNEL)}]`, `mcp_servers.chums.env=${env}`,
      ]),
      ...(a.addDirs?.length ? [`sandbox_workspace_write.writable_roots=[${a.addDirs.map(toml).join(', ')}]`] : []),
      ...(a.config ?? []),
    ]
    const [bin = 'codex', ...more] = a.command ?? []
    this.spawnAgent(bin, [...more, 'app-server', '--listen', `unix://${sock}`, ...config.flatMap(c => ['-c', c])], ['ignore', 'ignore', 'pipe'])
    let transport = null
    for (let i = 0; i < 150 && !transport && this.child; i++) {
      await new Promise(r => setTimeout(r, 100))
      if (fs.existsSync(sock)) transport = await wsUnix(sock).catch(() => null)
    }
    if (!transport) throw new Error(`codex app-server didn't open ${sock}`)
    this.rpc = peer(transport, {
      onRequest: (m, p, id) => this.request(m, p, id), onNotification: (m, p) => this.event(m, p), log: (...x) => this.note(...x),
    })
    this.rpc.on('close', () => this.kill())
    const init = await this.rpc.request('initialize', { clientInfo: { name: 'chums', title: 'Chums', version: VERSION }, capabilities: null }, 60_000)
    this.rpc.notify('initialized')
    this.note(`initialized: ${init.userAgent}`)
    const params = {
      cwd: a.cwd, model: a.model ?? null, approvalPolicy: a.approvalPolicy ?? this.hub.codexPolicy(), sandbox: a.sandbox ?? 'workspace-write',
      developerInstructions: `${standingFor(a)}\n\n${WATCH_GUIDE}`,
    }
    let thread = null
    if (a.sessionId) {
      try { thread = (await this.rpc.request('thread/resume', { threadId: a.sessionId, ...params, excludeTurns: true }, 120_000)).thread }
      catch (e) { this.note(`couldn't resume ${a.sessionId}: ${e.message}; starting a new thread`) }
    }
    if (!thread) {
      thread = (await this.rpc.request('thread/start', params, 120_000)).thread
      this.hub.saveSessionId(a.id, thread.id)
    }
    this.threadId = thread.id
    this.nameThread()
    // what bin/chums-agents open needs to put a Codex terminal on this same thread
    fs.writeFileSync(path.join(this.hub.dir, 'agents', `${a.id}.runtime.json`),
      JSON.stringify({ runtime: 'codex', thread: thread.id, socket: sock, cwd: a.cwd, pid: this.child?.pid }, null, 2))
    this.join(a.sessionId === thread.id && thread.status?.type !== 'notLoaded' ? 'resume' : 'startup')
  }

  /// Its name in Codex's own lists (`codex resume`, the desktop app): "Chums: <agent>". A new thread can only be
  /// named once it has a first turn on disk, so it's tried again after each turn until it takes.
  nameThread() {
    const name = `Chums: ${this.a.name ?? this.a.id}`
    this.rpc.request('thread/name/set', { threadId: this.threadId, name }, 30_000)
      .then(() => { this.named = true }, e => DEBUG && this.note('naming the thread:', e.message))
  }

  async order(item) {
    const s = this.s
    if (this.answerNext) { const r = this.answerNext; this.answerNext = null; return r(item.said ?? item.text) }
    const input = [{ type: 'text', text: `${markFor(item.device)} ${item.text}`, text_elements: [] }]
    if (this.activeTurn) {
      // it's working: the order joins the turn in progress, as typing into its terminal would
      try {
        await this.rpc.request('turn/steer', { threadId: this.threadId, input, expectedTurnId: this.activeTurn })
        if (this.turn) Object.assign(this.turn, { fromWatch: true, startedAt: Date.now(), text: '' })   // what counts is the answer to this
        return
      }
      catch (e) { this.note('steer refused:', e.message) }
    }
    this.watchTurn = true
    try { await this.rpc.request('turn/start', { threadId: this.threadId, input }) }
    catch (e) {
      this.watchTurn = false
      // a turn was still ending (too late to steer, too early to start): it goes once that turn is over
      if (this.activeTurn) { this.note('order waits for the turn to end:', e.message); (this.waitingOrders ??= []).push(item); return }
      this.note('turn failed to start:', e.message); if (s === this.s) this.finish('failed', e.message)
    }
  }

  event(method, p) {
    if (DEBUG && !/delta|tokenUsage|rateLimits|startupStatus/.test(method)) this.note('<-', method, p.item?.type ?? '')
    const s = this.s
    if (!s || (p.threadId && p.threadId !== this.threadId)) return
    switch (method) {
      case 'turn/started':
        this.activeTurn = p.turn.id
        this.newTurn(this.watchTurn); this.watchTurn = false          // a turn typed in a Codex terminal isn't the watch's
        break
      case 'turn/completed': {
        this.activeTurn = null
        if (!this.named) this.nameThread()
        if (this.waitingOrders?.length) setTimeout(() => this.order(this.waitingOrders.shift()), 0)
        const t = p.turn
        if (t.status === 'failed') {
          const info = t.error?.codexErrorInfo, code = typeof info === 'string' ? info : Object.keys(info ?? {})[0]
          this.finish('failed', ['usageLimitExceeded', 'rateLimitExceeded', 'serverOverloaded', 'sessionBudgetExceeded'].includes(code) ? 'rate limit' : t.error?.message ?? code)
        } else this.finish(t.status === 'interrupted' ? 'interrupted' : 'done')
        break
      }
      case 'item/started': this.itemStarted(p.item); break
      case 'item/completed': this.itemCompleted(p.item); break
      case 'thread/status/changed':
        if (p.status?.activeFlags?.includes('waitingOnUserInput')) { s.status = 'waiting'; this.hub.bump() }
        break
      case 'mcpServer/startupStatus/updated':
        if (p.name === 'chums' && p.status !== 'starting') this.note(`chums tools: ${p.status}${p.error ? ` (${p.error})` : ''}`)
        break
      case 'serverRequest/resolved': {
        // answered in a Codex terminal on the same thread: the card on the watch goes
        const id = this.byRpc.get(p.requestId); this.byRpc.delete(p.requestId)
        if (id && this.asks.has(id)) { this.asks.delete(id); this.hub.closeApproval(id) }
        break
      }
    }
  }
  itemStarted(item) {
    const s = this.s, hook = (tool, input) => this.hub.hook(s, 'PreToolUse', { tool, input })
    switch (item.type) {
      case 'commandExecution': { const t = shellTool(item.command, item.commandActions); hook(t.tool, t.input); break }
      case 'fileChange':
        this.files.set(item.id, item.changes ?? [])
        hook(item.changes?.length === 1 && item.changes[0].kind?.type === 'add' ? 'Write' : 'Edit', { file_path: item.changes?.[0]?.path })
        break
      case 'mcpToolCall': if (item.server !== 'chums') hook(`${item.server} ${item.tool}`, item.arguments); break
      case 'dynamicToolCall': hook(item.tool, item.arguments); break
      case 'webSearch': hook('WebSearch', { query: item.query }); break
      case 'imageView': hook('Read', { file_path: item.path }); break
      case 'contextCompaction': this.hub.hook(s, 'PreCompact', { trigger: 'auto' }); break
      case 'subAgentActivity': if (item.kind === 'started') this.hub.hook(s, 'SubagentStart', { agent: item.agentThreadId }); break
    }
  }
  itemCompleted(item) {
    const s = this.s, done = failed => this.hub.hook(s, 'PostToolUse', { result: JSON.stringify({ is_error: !!failed }) })
    switch (item.type) {
      case 'commandExecution':                                // couldn't run at all: a failure; ran and exited non-zero: marked
        if (item.status === 'failed' && item.exitCode == null) this.hub.hook(s, 'PostToolUseFailure', { error: short(item.aggregatedOutput || 'failed', 80) })
        else done(item.status !== 'completed' || (item.exitCode ?? 0) !== 0)
        break
      case 'fileChange': done(item.status !== 'completed'); break
      case 'mcpToolCall': if (item.server !== 'chums') done(item.status === 'failed'); break
      case 'dynamicToolCall': done(item.success === false); break
      case 'webSearch': case 'imageView': done(false); break
      case 'contextCompaction': this.hub.hook(s, 'PostCompact'); break
      case 'subAgentActivity': if (item.kind !== 'started' && item.kind !== 'interacted') this.hub.hook(s, 'SubagentStop', { agent: item.agentThreadId }); break
      case 'collabAgentToolCall':
        for (const id of item.receiverThreadIds ?? []) {
          if (item.tool === 'spawnAgent' && item.status === 'completed') this.hub.hook(s, 'SubagentStart', { agent: id })
          if (item.tool === 'closeAgent') this.hub.hook(s, 'SubagentStop', { agent: id })
        }
        break
      case 'agentMessage': if (this.turn && item.phase !== 'commentary') this.turn.text = item.text ?? ''; break
    }
  }
  async request(method, p, rpcId) {
    const card = (tool, description, input) => { const c = this.ask(tool, description, input); this.byRpc.set(rpcId, c.requestId); return c.answer }
    switch (method) {
      case 'item/commandExecution/requestApproval': {
        const t = shellTool(p.command, p.commandActions)
        const ok = await card('Bash', p.reason ?? 'Run a command', { command: t.tool === 'Bash' ? t.input.command : p.commandActions?.map(x => x.command).join(' && ') ?? p.command })
        // decline: the command doesn't run and the turn goes on, so the agent can say so (cancel would end the turn).
        // Codex 0.160 takes it even when availableDecisions leaves it out.
        return { decision: ok === 'allow' ? 'accept' : 'decline' }
      }
      case 'item/fileChange/requestApproval': {
        const changes = this.files.get(p.itemId) ?? []
        const ok = await card(changes.length === 1 && changes[0].kind?.type === 'add' ? 'Write' : 'Edit',
          p.reason ?? `Change ${changes.length || 'some'} file${changes.length === 1 ? '' : 's'}`, { file_path: changes[0]?.path ?? p.grantRoot })
        return { decision: ok === 'allow' ? 'accept' : 'decline' }
      }
      case 'item/permissions/requestApproval': {
        const want = p.permissions ?? {}
        const what = [want.network && 'network access', want.fileSystem && 'more file access'].filter(Boolean).join(' and ') || 'more access'
        const ok = await card('Permissions', p.reason ?? `Allow ${what}`, { description: p.reason ?? what })
        const grant = {}
        if (ok === 'allow') { if (want.network) grant.network = want.network; if (want.fileSystem) grant.fileSystem = want.fileSystem }
        return { permissions: grant, scope: 'turn' }
      }
      case 'mcpServer/elicitation/request': {
        if (p.serverName === 'chums') return { action: 'accept', content: {}, _meta: null }
        const ok = await card(p.serverName, short(p.message, 160), { url: p.url, description: p.message })
        return { action: ok === 'allow' ? 'accept' : 'decline', content: ok === 'allow' ? {} : null, _meta: null }
      }
      case 'item/tool/requestUserInput': {
        // a question: said on the watch, and what's said next is the answer
        this.hub.reply(this.s, spokenLine(p.questions?.map(q => q.question).join(' ')) || 'A question for you.', 'question')
        const said = await new Promise(r => { this.answerNext = r })
        return { answers: Object.fromEntries((p.questions ?? []).map(q => [q.id, { answers: [said] }])) }
      }
    }
    throw Object.assign(new Error(`${method} isn't offered`), { code: -32601 })
  }
}

/// Starts one agent the hub runs (null for a runtime it doesn't know).
export function startRunner(a, hub) {
  if (!RUNTIMES.includes(a.runtime) || !runByHub(a)) { hub.log(`${a.id}: unknown runtime ${a.runtime} (one of ${RUNTIMES.join(', ')})`); return null }
  const r = new { codex: CodexRunner, copilot: CopilotRunner, acp: AcpRunner }[a.runtime](a, hub)
  r.start()
  return r
}

/// Starts every agent the hub runs; returns them by agent id.
export function startRunners(agents, hub) {
  const runners = new Map()
  for (const a of agents.filter(runByHub)) { const r = startRunner(a, hub); if (r) runners.set(a.id, r) }
  return runners
}