mirab 0.0.0-stage → 0.2.0

package/src/spawn-adapters/claude.ts

@@ -0,0 +1,112 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { rmSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  event,
+  payload,
+  shellQuote,
+  nativeOptions,
+  type AgentAdapter,
+} from './types'
+// A new session sits at its prompt, so it starts idle. Claude's idle
+// notification ("waiting for your input") is also ready for a prompt; every
+// other notification (permission, elicitation) still needs the human.
+const types = {
+  SessionStart: 'idle',
+  UserPromptSubmit: 'busy',
+  PreToolUse: 'tool_start',
+  PostToolUse: 'tool_end',
+  PostToolUseFailure: 'tool_end',
+  Notification: 'waiting',
+  PermissionRequest: 'waiting',
+  Stop: 'idle',
+} as const
+export const claudeAdapter: AgentAdapter = {
+  name: 'claude',
+  profileArgs({ model, effort }) {
+    if (effort && !['low', 'medium', 'high', 'xhigh', 'max'].includes(effort))
+      throw Error('Claude effort must be low, medium, high, xhigh or max')
+    return [
+      ...(model ? ['--model', model] : []),
+      ...(effort ? ['--effort', effort] : []),
+    ]
+  },
+  async prepare(context, args) {
+    // Modes explicitly disabling hooks must retain their native semantics.
+    if (nativeOptions(args).some((a) => ['--bare', '--safe-mode'].includes(a)))
+      return { args, cleanup() {} }
+    const directory = join(context.directory, context.id)
+    await mkdir(directory, { mode: 0o700 })
+    const file = join(directory, 'settings.json')
+    try {
+      context.onCleanup?.(() =>
+        rmSync(directory, { recursive: true, force: true }),
+      )
+      const command = [...context.command, 'hook', '--session', context.id]
+        .map(shellQuote)
+        .join(' ')
+      const hooks = Object.fromEntries(
+        Object.keys(types).map((name) => [
+          name,
+          [{ hooks: [{ type: 'command', command, timeout: 1 }] }],
+        ]),
+      )
+      await writeFile(file, JSON.stringify({ hooks }), {
+        mode: 0o600,
+        flag: 'wx',
+      })
+      // Installed Claude accepts only the last --settings. If the caller has
+      // one, additive plugin hooks preserve their entire settings source.
+      const extra: string[] = []
+      if (
+        nativeOptions(args).some(
+          (a) => a === '--settings' || a.startsWith('--settings='),
+        )
+      ) {
+        await mkdir(join(directory, '.claude-plugin'), { mode: 0o700 })
+        await mkdir(join(directory, 'hooks'), { mode: 0o700 })
+        await writeFile(
+          join(directory, '.claude-plugin', 'plugin.json'),
+          JSON.stringify({ name: 'mirab-session-observer', version: '1.0.0' }),
+          { mode: 0o600 },
+        )
+        await writeFile(
+          join(directory, 'hooks', 'hooks.json'),
+          JSON.stringify({ hooks }),
+          { mode: 0o600 },
+        )
+        extra.push('--plugin-dir', directory)
+      }
+      return {
+        args: ['--settings', file, ...extra, ...args],
+        cleanup: () => rmSync(directory, { recursive: true, force: true }),
+      }
+    } catch (error) {
+      rmSync(directory, { recursive: true, force: true })
+      throw error
+    }
+  },
+  translate(session, raw) {
+    const p = payload(raw)
+    if (
+      !p ||
+      typeof p.hook_event_name !== 'string' ||
+      typeof p.agent_id === 'string'
+    )
+      return null
+    const type =
+      p.hook_event_name === 'Notification' &&
+      p.notification_type === 'idle_prompt'
+        ? 'idle'
+        : types[p.hook_event_name as keyof typeof types]
+    return type
+      ? event(
+          session,
+          'claude',
+          type,
+          raw,
+          typeof p.tool_name === 'string' ? p.tool_name : undefined,
+        )
+      : null
+  },
+}

package/src/spawn-adapters/codex-logs.ts

@@ -0,0 +1,130 @@
+import { open, readdir, stat } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import type { AgentEvent } from '../spawn-events'
+import { event, payload } from './types'
+/** Best effort, bound only by a notify-proven thread ID; never guess by cwd. */
+export class CodexLogs {
+  private path?: string
+  private offset = 0
+  private partial = ''
+  private tools = new Map<string, string>()
+  private timer?: ReturnType<typeof setInterval>
+  private reading = false
+  private closed = false
+  private bound = false
+  private notBefore = 0
+  constructor(
+    private readonly root: string,
+    private readonly session: string,
+    private readonly emit: (event: AgentEvent) => void,
+  ) {}
+  async bind(raw: unknown) {
+    this.notBefore = Date.now()
+    this.tools.clear()
+    const p = payload(raw),
+      id = p?.['thread-id']
+    if (
+      this.bound ||
+      typeof id !== 'string' ||
+      !/^[a-zA-Z0-9_-]{1,100}$/.test(id)
+    )
+      return
+    this.bound = true
+    try {
+      const entries = await readdir(this.root, { recursive: true })
+      const match = entries.find(
+        (path) =>
+          basename(path) === id + '.jsonl' ||
+          basename(path).endsWith('-' + id + '.jsonl'),
+      )
+      if (!match || this.closed) return
+      this.path = join(this.root, match)
+      // Old history cannot change the live state after a notify event.
+      this.offset = (await stat(this.path)).size
+      if (!this.closed)
+        this.timer = setInterval(() => {
+          void this.poll()
+        }, 250)
+    } catch {
+      /* Missing/paginated logs do not disable notify. */
+    }
+  }
+  async poll() {
+    if (this.reading || this.closed || !this.path) return
+    this.reading = true
+    let file: Awaited<ReturnType<typeof open>> | undefined
+    try {
+      file = await open(this.path, 'r')
+      const size = (await file.stat()).size
+      if (size < this.offset) {
+        this.offset = size
+        this.partial = ''
+        return
+      }
+      if (size === this.offset) return
+      if (size - this.offset > 1024 * 1024) {
+        this.offset = size
+        this.partial = ''
+        return
+      }
+      const buffer = Buffer.alloc(size - this.offset)
+      const { bytesRead } = await file.read(
+        buffer,
+        0,
+        buffer.length,
+        this.offset,
+      )
+      this.offset += bytesRead
+      const lines = (
+        this.partial + buffer.subarray(0, bytesRead).toString('utf8')
+      ).split('\n')
+      this.partial = lines.pop() ?? ''
+      if (this.partial.length > 65536) this.partial = ''
+      for (const line of lines) {
+        if (line.length > 65536 || this.closed) continue
+        try {
+          const raw = JSON.parse(line),
+            p = payload(raw.payload)
+          const timestamp =
+            typeof raw.timestamp === 'string' ? Date.parse(raw.timestamp) : NaN
+          if (!p || !Number.isFinite(timestamp) || timestamp <= this.notBefore)
+            continue
+          if (raw.type === 'event_msg' && p.type === 'task_started')
+            this.emit(event(this.session, 'codex', 'busy', raw))
+          if (raw.type !== 'response_item') continue
+          if (
+            ['function_call', 'custom_tool_call'].includes(String(p.type)) &&
+            typeof p.name === 'string' &&
+            typeof p.call_id === 'string'
+          ) {
+            if (this.tools.size >= 1000) this.tools.clear()
+            this.tools.set(p.call_id, p.name)
+            this.emit(event(this.session, 'codex', 'tool_start', raw, p.name))
+          } else if (
+            ['function_call_output', 'custom_tool_call_output'].includes(
+              String(p.type),
+            ) &&
+            typeof p.call_id === 'string'
+          ) {
+            const tool = this.tools.get(p.call_id)
+            if (tool) {
+              this.tools.delete(p.call_id)
+              this.emit(event(this.session, 'codex', 'tool_end', raw, tool))
+            }
+          }
+          // Completion comes only from notify; delayed log records cannot unlock injection.
+        } catch {
+          /* Internal JSONL shapes are not a protocol. */
+        }
+      }
+    } catch {
+    } finally {
+      await file?.close().catch(() => {})
+      this.reading = false
+    }
+  }
+  close() {
+    this.closed = true
+    clearInterval(this.timer)
+  }
+}

package/src/spawn-adapters/codex-notify.ts

@@ -0,0 +1,73 @@
+import { readFile } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { parse } from 'smol-toml'
+
+function notifyCommand(value: unknown): string[] {
+  if (value === undefined) return []
+  if (!Array.isArray(value) || !value.every((arg) => typeof arg === 'string'))
+    throw new Error('Codex notify must be an array of strings')
+  return value
+}
+async function config(path: string) {
+  try {
+    return parse(await readFile(path, 'utf8'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error
+    return {}
+  }
+}
+/** Resolve notification layers only; project config cannot set notify. */
+export async function originalNotify(
+  args: string[],
+  environment = process.env,
+) {
+  const home =
+    environment.CODEX_HOME ?? join(environment.HOME ?? homedir(), '.codex')
+  const system = await config('/etc/codex/config.toml')
+  const user = await config(join(home, 'config.toml'))
+  let command = notifyCommand(user.notify ?? system.notify)
+  let profile = user.profile ?? system.profile
+  let explicitProfile: string | undefined
+  let override: string[] | undefined
+  const remaining: string[] = []
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]
+    if (arg === '--') {
+      remaining.push(...args.slice(i))
+      break
+    }
+    if (arg === '-p' || arg === '--profile') {
+      explicitProfile = args[i + 1]
+      remaining.push(arg, args[++i])
+      continue
+    }
+    if (arg.startsWith('--profile=')) explicitProfile = arg.slice(10)
+    else if (arg.startsWith('-p') && arg.length > 2)
+      explicitProfile = arg.slice(2)
+    const separate = arg === '-c' || arg === '--config'
+    const value = separate
+      ? args[i + 1]
+      : arg.startsWith('--config=')
+        ? arg.slice(9)
+        : arg.startsWith('-c')
+          ? arg.slice(2)
+          : undefined
+    if (value && /^\s*notify\s*=/.test(value)) {
+      override = notifyCommand(parse(value).notify)
+      if (separate) i++
+    } else {
+      if (value && /^\s*profile\s*=/.test(value)) profile = parse(value).profile
+      remaining.push(arg)
+    }
+  }
+  profile = explicitProfile ?? profile
+  if (profile !== undefined) {
+    if (typeof profile !== 'string' || !/^[a-zA-Z0-9_-]+$/.test(profile))
+      throw new Error('Invalid Codex profile name')
+    const selected = await config(join(home, `${profile}.config.toml`))
+    if (selected.notify !== undefined) command = notifyCommand(selected.notify)
+  }
+  if (override !== undefined) command = override
+  return { command, args: remaining }
+}

package/src/spawn-adapters/codex.ts

@@ -0,0 +1,89 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { originalNotify } from './codex-notify'
+import { CodexLogs } from './codex-logs'
+import { event, payload, type AgentAdapter } from './types'
+/** Codex settings every mirab session needs, because mirab types its prompts.
+ * - The startup "Update available" menu would swallow the first prompt (its
+ *   Enter picks "Update now").
+ * - Paste-burst detection treats typed prompt text as a paste and the Enter
+ *   that follows it as part of the paste, so the prompt sat in the composer
+ *   unsent: 0 of 3 fresh sessions answered on 10 Oct, 3 of 3 with it off.
+ * Profile args come later on the command line, so a profile can still turn
+ * either back on. */
+export const SESSION_CONFIG = [
+  '-c',
+  'check_for_update_on_startup=false',
+  '-c',
+  'tui.disable_paste_burst=true',
+]
+export const codexAdapter: AgentAdapter = {
+  name: 'codex',
+  profileArgs({ model, effort }) {
+    return [
+      ...(model ? ['-m', model] : []),
+      ...(effort
+        ? ['-c', `model_reasoning_effort=${JSON.stringify(effort)}`]
+        : []),
+    ]
+  },
+  async prepare(context, args) {
+    const environment = context.environment ?? process.env
+    const original = await originalNotify(args, environment)
+    const command = [
+      ...context.command,
+      'hook',
+      '--session',
+      context.id,
+      '--agent',
+      'codex',
+      ...(original.command.length
+        ? ['--notify-command', JSON.stringify(original.command)]
+        : []),
+    ]
+    const logs = context.emit
+      ? new CodexLogs(
+          join(
+            environment.CODEX_HOME ??
+              join(environment.HOME ?? homedir(), '.codex'),
+            'sessions',
+          ),
+          context.id,
+          context.emit,
+        )
+      : undefined
+    context.onCleanup?.(() => logs?.close())
+    // JSON array syntax is also a TOML array of quoted strings.
+    return {
+      args: [
+        '-c',
+        `notify=${JSON.stringify(command)}`,
+        ...SESSION_CONFIG,
+        ...original.args,
+      ],
+      cleanup: () => logs?.close(),
+      receive: (raw) => {
+        void logs?.bind(raw)
+      },
+    }
+  },
+  // Codex's notify fires only after a turn, and its SessionStart hook only on
+  // the first prompt, so nothing says a fresh TUI is ready; without this a
+  // mention to a new Codex session waits forever as "agent not idle". Codex
+  // draws its composer first and its trust dialog up to ~3 s later (10 Oct),
+  // so a fresh screen must stay quiet for 5 s. A busy Codex redraws its
+  // "Working (Ns)" timer every second, so 5 s of silence after an Enter means
+  // no turn is running. Its startup dialogs (trust, update) are for a person,
+  // never for a channel message.
+  quiet: {
+    startupMs: 5000,
+    busyMs: 5000,
+    dialogs: /Trustthisfolder|Updateavailable|Updatenow/i,
+  },
+  translate(session, raw) {
+    const p = payload(raw)
+    return p?.type === 'agent-turn-complete'
+      ? event(session, 'codex', 'idle', raw)
+      : null
+  },
+}

package/src/spawn-adapters/index.ts

@@ -0,0 +1,40 @@
+import { basename } from 'node:path'
+import { claudeAdapter } from './claude'
+import { codexAdapter } from './codex'
+import {
+  nativeOptions,
+  type AgentAdapter,
+  type RuntimeSettings,
+  type RuntimeFlags,
+} from './types'
+const adapters: AgentAdapter[] = [claudeAdapter, codexAdapter]
+export function adapterFor(
+  agent: string,
+  args: string[],
+): AgentAdapter | undefined {
+  if (
+    basename(agent) === 'claude' &&
+    nativeOptions(args).some((a) => ['--bare', '--safe-mode'].includes(a))
+  )
+    return undefined
+  return adapters.find((adapter) => adapter.name === basename(agent))
+}
+
+// Kimi has no structured event observer yet. Its verified flags share the
+// runtime registry; absent effort support is an error, never a guessed flag.
+const runtimeFlags = new Map<string, RuntimeFlags>(
+  adapters.map((a) => [a.name, a.profileArgs]),
+)
+runtimeFlags.set('kimi', ({ model, effort }) => {
+  if (effort)
+    throw Error(
+      'Kimi --help exposes no effort flag; omit effort and use native args',
+    )
+  return model ? ['--model', model] : []
+})
+export function profileArguments(
+  runtime: string,
+  settings: RuntimeSettings,
+): string[] {
+  return runtimeFlags.get(basename(runtime))?.(settings) ?? []
+}

package/src/spawn-adapters/types.ts

@@ -0,0 +1,55 @@
+import type { AgentEvent } from '../spawn-events'
+export type AdapterContext = {
+  id: string
+  directory: string
+  command: string[]
+  environment?: NodeJS.ProcessEnv
+  emit?: (event: AgentEvent) => void
+  onCleanup?: (cleanup: () => void) => void
+}
+export type RuntimeSettings = { model?: string; effort?: string }
+export type RuntimeFlags = (settings: RuntimeSettings) => string[]
+export type AgentAdapter = {
+  profileArgs: RuntimeFlags
+  name: string
+  prepare(
+    context: AdapterContext,
+    args: string[],
+  ): Promise<{
+    args: string[]
+    cleanup(): void
+    receive?: (raw: unknown) => void
+  }>
+  translate(session: string, raw: unknown): AgentEvent | null
+  /** For a runtime that reports only turn ends: terminal-quiet readiness
+   * (see QuietIdle). `dialogs` matches screen text with whitespace removed. */
+  quiet?: { startupMs: number; busyMs: number; dialogs?: RegExp }
+}
+export function event(
+  session: string,
+  agent: string,
+  type: AgentEvent['type'],
+  raw: unknown,
+  tool?: string,
+): AgentEvent {
+  return {
+    session,
+    agent,
+    type,
+    ...(tool ? { tool } : {}),
+    ts: new Date().toISOString(),
+    raw,
+  }
+}
+export function payload(raw: unknown): Record<string, unknown> | null {
+  return raw && typeof raw === 'object' && !Array.isArray(raw)
+    ? (raw as Record<string, unknown>)
+    : null
+}
+export const shellQuote = (value: string) =>
+  "'" + value.replaceAll("'", "'\\''") + "'"
+
+export function nativeOptions(args: string[]) {
+  const separator = args.indexOf('--')
+  return separator < 0 ? args : args.slice(0, separator)
+}