npm - lyra-ai-agent - Versions diffs - 0.1.0 - Mend

lyra-ai-agent 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (62) hide show

package/README.md +39 -0
package/bin/lyra +11 -0
package/package.json +65 -0
package/src/commands/_agents.ts +14 -0
package/src/commands/chat-telegram.ts +398 -0
package/src/commands/chat.tsx +1220 -0
package/src/commands/demo.ts +177 -0
package/src/commands/gateway-logs.ts +49 -0
package/src/commands/gateway-run.ts +42 -0
package/src/commands/gateway-start.ts +89 -0
package/src/commands/gateway-status.ts +73 -0
package/src/commands/gateway-stop.ts +133 -0
package/src/commands/gateway.ts +101 -0
package/src/commands/init/model-picker.ts +17 -0
package/src/commands/init.ts +153 -0
package/src/commands/logs.ts +37 -0
package/src/commands/model.ts +48 -0
package/src/commands/pairing-approve.ts +65 -0
package/src/commands/pairing-clear.ts +39 -0
package/src/commands/pairing-list.ts +55 -0
package/src/commands/pairing-revoke.ts +49 -0
package/src/commands/pairing.test.ts +88 -0
package/src/commands/pairing.ts +81 -0
package/src/commands/status.ts +84 -0
package/src/commands/telegram-remove.ts +45 -0
package/src/commands/telegram-setup.ts +84 -0
package/src/commands/telegram-status.ts +48 -0
package/src/commands/telegram.test.ts +50 -0
package/src/commands/telegram.ts +44 -0
package/src/commands/whoami.ts +62 -0
package/src/config/load.ts +35 -0
package/src/config/render.test.ts +96 -0
package/src/config/render.ts +99 -0
package/src/index.ts +147 -0
package/src/ui/app.tsx +719 -0
package/src/ui/approval-summary.test.ts +132 -0
package/src/ui/approval-summary.ts +28 -0
package/src/ui/markdown-parse.ts +219 -0
package/src/ui/markdown.test.ts +146 -0
package/src/ui/markdown.tsx +37 -0
package/src/ui/state.test.ts +74 -0
package/src/ui/state.ts +176 -0
package/src/util/bootstrap-mode.test.ts +40 -0
package/src/util/bootstrap-mode.ts +25 -0
package/src/util/bootstrap-progress-box.test.ts +190 -0
package/src/util/bootstrap-progress-box.ts +378 -0
package/src/util/cli-version.ts +28 -0
package/src/util/format.test.ts +16 -0
package/src/util/format.ts +11 -0
package/src/util/gateway-spawn.test.ts +86 -0
package/src/util/gateway-spawn.ts +125 -0
package/src/util/gateway-version.test.ts +113 -0
package/src/util/gateway-version.ts +154 -0
package/src/util/github-releases.test.ts +116 -0
package/src/util/github-releases.ts +79 -0
package/src/util/ref-resolver.test.ts +77 -0
package/src/util/ref-resolver.ts +55 -0
package/src/util/silence-console.test.ts +53 -0
package/src/util/silence-console.ts +40 -0
package/src/util/sui-runtime.ts +74 -0
package/src/util/telegram-secrets.test.ts +104 -0
package/src/util/telegram-secrets.ts +99 -0

package/src/util/bootstrap-progress-box.ts ADDED Viewed

@@ -0,0 +1,378 @@
+/**
+ * Multi-line ANSI progress box for sandbox bootstrap. Replaces the single-line
+ * clack spinner across the launch + poll + /healthz window:
+ *
+ *   ╭─ bootstrap progress ────────────────────────╮
+ *   │  [00:00] launchScript uploaded to Daytona   │
+ *   │  [00:12] apt update                     ✓   │
+ *   │  [00:38] system deps installed          ✓   │
+ *   │  [01:04] bun runtime installed          ✓   │
+ *   │  [01:22] lyra 0.24.7 installed         ✓   │
+ *   │  [01:45] browser deps installed         ✓   │
+ *   │  [02:08] harness daemon spawned         ✓   │
+ *   │  [02:11] /healthz Ready                 ✓   │
+ *   ╰─────────────────────────────────────────────╯
+ *
+ * Rendering uses `\x1b[NA` (cursor up) + `\x1b[0J` (clear to end) to redraw
+ * the same N+2 lines in place. Falls back to per-transition lines (no ANSI)
+ * when stdout is not a TTY (CI, piped output).
+ */
+import { BOOTSTRAP_STAGE_MARKERS } from 'lyra-gateway'
+const TIME_SLOT_WIDTH = 7
+const LABEL_WIDTH = 32
+const CONTENT_WIDTH = 45
+const FRAME_WIDTH = CONTENT_WIDTH + 2
+const SPINNER_FRAMES = ['◐', '◓', '◑', '◒'] as const
+export type BootstrapStageId =
+  | 'launch-upload'
+  | 'apt-update'
+  | 'system-deps'
+  | 'bun-install'
+  | 'lyra-install'
+  | 'browser-deps'
+  | 'harness-spawn'
+  | 'healthz-ready'
+export type BootstrapStageStatus = 'pending' | 'running' | 'done' | 'failed'
+const STAGE_ORDER: readonly BootstrapStageId[] = [
+  'launch-upload',
+  'apt-update',
+  'system-deps',
+  'bun-install',
+  'lyra-install',
+  'browser-deps',
+  'harness-spawn',
+  'healthz-ready',
+] as const
+const DEFAULT_LABELS: Record<BootstrapStageId, string> = {
+  'launch-upload': 'launchScript uploaded to Daytona',
+  'apt-update': 'apt update',
+  'system-deps': 'system deps installed',
+  'bun-install': 'bun runtime installed',
+  'lyra-install': 'lyra installed',
+  'browser-deps': 'browser deps installed',
+  'harness-spawn': 'harness daemon spawned',
+  'healthz-ready': '/healthz Ready',
+}
+interface StageState {
+  id: BootstrapStageId
+  label: string
+  status: BootstrapStageStatus
+  /** Seconds since box start when status transitioned to running. */
+  startedSec?: number
+  /** Seconds since box start when status transitioned to done/failed. */
+  endedSec?: number
+}
+export interface BootstrapProgressBoxOpts {
+  /** Box title. Defaults to "bootstrap progress". */
+  title?: string
+  /** Per-stage label override. Useful for injecting the version into lyra-install. */
+  labels?: Partial<Record<BootstrapStageId, string>>
+  /** Stream to write to. Defaults to process.stdout. */
+  out?: NodeJS.WritableStream & { isTTY?: boolean }
+}
+/**
+ * Map a raw STAGE marker (emitted by the gateway bootstrap script as
+ * `STAGE: <body>` and extracted by sandbox-provision's poll loop) to a stage
+ * id. Returns null for unknown markers; callers should treat unknown markers
+ * as informational, not as state transitions. Marker prefixes come from
+ * `BOOTSTRAP_STAGE_MARKERS` in the gateway package so renames stay in lockstep.
+ */
+export function mapBootstrapMarkerToStage(marker: string): BootstrapStageId | null {
+  const m = marker.trim()
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.aptUpdate)) return 'apt-update'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.systemDeps)) return 'system-deps'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.bunInstall)) return 'bun-install'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.lyraInstall)) return 'lyra-install'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.browserDeps)) return 'browser-deps'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.harnessSpawn)) return 'harness-spawn'
+  if (m.startsWith(BOOTSTRAP_STAGE_MARKERS.harnessReady)) return 'harness-spawn'
+  return null
+}
+export class BootstrapProgressBox {
+  private readonly title: string
+  private readonly out: NodeJS.WritableStream & { isTTY?: boolean }
+  private readonly useAnsi: boolean
+  private readonly stages: StageState[]
+  private startMs = 0
+  private tickIdx = 0
+  /** Number of lines we wrote the LAST time render() ran (so we know how
+   *  many to clear before the next render). Zero before the first render. */
+  private renderedLines = 0
+  /** Cleared on render — tracks last-printed status per stage in non-TTY mode. */
+  private readonly nonTtyLastPrinted = new Map<BootstrapStageId, BootstrapStageStatus>()
+  constructor(opts: BootstrapProgressBoxOpts = {}) {
+    this.title = opts.title ?? 'bootstrap progress'
+    this.out = opts.out ?? process.stdout
+    this.useAnsi = this.out.isTTY === true
+    this.stages = STAGE_ORDER.map(id => ({
+      id,
+      label: opts.labels?.[id] ?? DEFAULT_LABELS[id],
+      status: 'pending' as BootstrapStageStatus,
+    }))
+  }
+  start(): void {
+    this.startMs = Date.now()
+    if (!this.useAnsi) return
+    this.render()
+  }
+  /**
+   * Update one stage. When `status === 'running'`, every previously-running
+   * stage that hasn't transitioned to done/failed is auto-completed (the
+   * bash script is sequential, so a new stage starting implies the prior
+   * ones finished). Stages before the activated one that are still pending
+   * are also auto-completed — this handles conditional stages (e.g.
+   * bun-install gets skipped when bun is already in PATH).
+   */
+  markStage(id: BootstrapStageId, status: BootstrapStageStatus): void {
+    const sec = this.elapsedSec()
+    const idx = this.stages.findIndex(s => s.id === id)
+    if (idx < 0) return
+    if (status === 'running') {
+      for (let i = 0; i < idx; i++) {
+        const s = this.stages[i]!
+        if (s.status !== 'done' && s.status !== 'failed') {
+          s.status = 'done'
+          s.endedSec = sec
+        }
+      }
+      const target = this.stages[idx]!
+      if (target.status === 'pending') target.startedSec = sec
+      target.status = 'running'
+    } else {
+      const target = this.stages[idx]!
+      target.status = status
+      target.endedSec = sec
+      if (target.startedSec === undefined) target.startedSec = sec
+    }
+    this.tickIdx += 1
+    this.render()
+  }
+  /**
+   * Bump the spinner glyph + elapsed counter. Call every 1-5s while a
+   * running stage is in-flight to keep the visual alive even when no STAGE
+   * marker has arrived. No-op when the box hasn't started yet or when no
+   * stage is currently running.
+   */
+  tick(): void {
+    if (this.renderedLines === 0 && this.useAnsi) {
+      this.render()
+      return
+    }
+    this.tickIdx += 1
+    this.render()
+  }
+  /**
+   * Finalize the box. Marks any still-running stages as done (assumed
+   * complete; the upstream success signal is what triggered stop()), draws
+   * one final frame, and emits the trailing newline so subsequent CLI
+   * output (e.g. final spinner success line) starts cleanly below.
+   */
+  stop(): void {
+    const sec = this.elapsedSec()
+    for (const s of this.stages) {
+      if (s.status === 'running') {
+        s.status = 'done'
+        s.endedSec = sec
+      }
+    }
+    this.render()
+    if (this.useAnsi) this.out.write('\n')
+  }
+  /**
+   * Mark the box as aborted. Any running stage becomes failed; pending
+   * stages stay pending so the operator sees where bootstrap got stuck.
+   */
+  fail(): void {
+    const sec = this.elapsedSec()
+    for (const s of this.stages) {
+      if (s.status === 'running') {
+        s.status = 'failed'
+        s.endedSec = sec
+      }
+    }
+    this.render()
+    if (this.useAnsi) this.out.write('\n')
+  }
+  private elapsedSec(): number {
+    return Math.max(0, Math.round((Date.now() - this.startMs) / 1000))
+  }
+  private render(): void {
+    if (!this.useAnsi) {
+      this.renderNonTty()
+      return
+    }
+    const lines = this.buildLines()
+    if (this.renderedLines > 0) {
+      this.out.write(`\x1b[${this.renderedLines}A\x1b[0J`)
+    }
+    for (const line of lines) this.out.write(`${line}\n`)
+    this.renderedLines = lines.length
+  }
+  /**
+   * Non-TTY fallback: print one line per state change instead of a redrawn
+   * box. Tracks last-printed status per stage so re-renders don't spam.
+   */
+  private renderNonTty(): void {
+    for (const s of this.stages) {
+      const prev = this.nonTtyLastPrinted.get(s.id)
+      if (prev === s.status) continue
+      if (s.status === 'pending') continue
+      const tag =
+        s.status === 'done'
+          ? '[ok]'
+          : s.status === 'failed'
+            ? '[fail]'
+            : s.status === 'running'
+              ? '[..]'
+              : ''
+      const time =
+        s.status === 'running'
+          ? formatTime(s.startedSec ?? 0)
+          : formatTime(s.endedSec ?? this.elapsedSec())
+      this.out.write(`${tag} [${time}] ${s.label}\n`)
+      this.nonTtyLastPrinted.set(s.id, s.status)
+    }
+  }
+  private buildLines(): string[] {
+    const header = `╭─ ${this.title} ${'─'.repeat(FRAME_WIDTH - this.title.length - 5)}╮`
+    const footer = `╰${'─'.repeat(FRAME_WIDTH - 2)}╯`
+    const rows = this.stages.map(s => this.formatRow(s))
+    return [header, ...rows, footer]
+  }
+  private formatRow(s: StageState): string {
+    const timeText = pickTimeText(s)
+    const timeCol =
+      timeText === null ? ' '.repeat(TIME_SLOT_WIDTH) : `[${timeText}]`.padEnd(TIME_SLOT_WIDTH)
+    const labelText = truncate(s.label, LABEL_WIDTH).padEnd(LABEL_WIDTH)
+    const glyph = pickGlyph(s, this.tickIdx)
+    return `│  ${timeCol} ${labelText} ${glyph} │`
+  }
+}
+function pickTimeText(s: StageState): string | null {
+  if (s.status === 'pending') return null
+  const sec = s.status === 'running' ? (s.startedSec ?? 0) : (s.endedSec ?? s.startedSec ?? 0)
+  return formatTime(sec)
+}
+function formatTime(sec: number): string {
+  const m = Math.floor(sec / 60)
+  const s = sec % 60
+  return `${String(m).padStart(2, '0')}:${String(s).padStart(2, '0')}`
+}
+function pickGlyph(s: StageState, tickIdx: number): string {
+  if (s.status === 'done') return '✓'
+  if (s.status === 'failed') return '✗'
+  if (s.status === 'running') return SPINNER_FRAMES[tickIdx % SPINNER_FRAMES.length]!
+  return ' '
+}
+function truncate(s: string, max: number): string {
+  if (s.length <= max) return s
+  return `${s.slice(0, max - 1)}…`
+}
+export const __testing = {
+  STAGE_ORDER,
+  DEFAULT_LABELS,
+  SPINNER_FRAMES,
+  formatTime,
+  truncate,
+}
+/**
+ * Lifecycle owner for the bootstrap progress UX. Wraps the clack spinner
+ * (which renders the pre-bootstrap phase: deposit + createSandbox) and a
+ * lazily-created `BootstrapProgressBox` (which renders the actual bootstrap
+ * stages). Encapsulates the takeover handoff so `init.ts` and `upgrade.ts`
+ * don't repeat the same `let box / spinnerStopped` dance.
+ */
+export interface ClackSpinnerLike {
+  message: (msg: string) => void
+  stop: (msg?: string, code?: number) => void
+}
+export interface BootstrapProgressControllerOpts {
+  spinner: ClackSpinnerLike
+  cliVersion: string
+  /** Text shown when the spinner stops + the box takes over (e.g. "sandbox started, running bootstrap"). */
+  startedMsg: string
+}
+export class BootstrapProgressController {
+  private box: BootstrapProgressBox | null = null
+  private spinnerStopped = false
+  private readonly spinner: ClackSpinnerLike
+  private readonly cliVersion: string
+  private readonly startedMsg: string
+  constructor(opts: BootstrapProgressControllerOpts) {
+    this.spinner = opts.spinner
+    this.cliVersion = opts.cliVersion
+    this.startedMsg = opts.startedMsg
+  }
+  onProgress = (msg: string): void => {
+    if (this.box) return
+    this.spinner.message(msg)
+  }
+  onStageEvent = (stage: BootstrapStageId, status: BootstrapStageStatus): void => {
+    if (!this.box) {
+      this.spinner.stop(this.startedMsg)
+      this.spinnerStopped = true
+      this.box = new BootstrapProgressBox({
+        labels: { 'lyra-install': `lyra ${this.cliVersion} installed` },
+      })
+      this.box.start()
+    }
+    this.box.markStage(stage, status)
+  }
+  onTick = (): void => {
+    this.box?.tick()
+  }
+  /** Box closes itself; success line printed via the caller's `emit` (typically `log.step`). */
+  finalize(successLine: string, emit: (msg: string) => void): void {
+    if (this.box) {
+      this.box.stop()
+      emit(successLine)
+    } else {
+      this.spinner.stop(successLine)
+    }
+  }
+  /** Box marks running stage as failed; error line printed via caller's `emit` (typically `log.error`). */
+  fail(errLine: string, emit: (msg: string) => void): void {
+    if (this.box) {
+      this.box.fail()
+      emit(errLine)
+    } else if (!this.spinnerStopped) {
+      this.spinner.stop(errLine)
+    }
+  }
+}

package/src/util/cli-version.ts ADDED Viewed

@@ -0,0 +1,28 @@
+/**
+ * Resolve the CLI package's own version. Used by `lyra --version` and to pin
+ * the gateway version installed in sandbox containers (mode=npm) so the
+ * gateway matches the CLI.
+ *
+ * Reads package.json via a path relative to this module so it works in every
+ * install layout: monorepo workspace (where bare-specifier resolution of
+ * `lyra-ai-cli` doesn't include /package.json without an exports entry),
+ * `bun add -g` global install, and Bun's per-project content store.
+ */
+import { readFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+export async function resolveCliVersion(): Promise<string> {
+  const here = fileURLToPath(import.meta.url)
+  const pkgPath = resolve(here, '../../../package.json')
+  try {
+    const raw = await readFile(pkgPath, 'utf-8')
+    const pkg = JSON.parse(raw) as { version?: unknown }
+    if (typeof pkg.version !== 'string') {
+      throw new Error('package.json missing version field')
+    }
+    return pkg.version
+  } catch (e) {
+    throw new Error(`cannot read CLI version from ${pkgPath}: ${(e as Error).message}`)
+  }
+}

package/src/util/format.test.ts ADDED Viewed

@@ -0,0 +1,16 @@
+import { describe, expect, it } from 'bun:test'
+import { shortAddr } from './format'
+describe('shortAddr', () => {
+  it('returns ? for missing input', () => {
+    expect(shortAddr(undefined)).toBe('?')
+    expect(shortAddr('')).toBe('?')
+  })
+  it('passes through short / non-0x values unchanged', () => {
+    expect(shortAddr('alice.0g')).toBe('alice.0g')
+    expect(shortAddr('0xabc')).toBe('0xabc')
+  })
+  it('truncates a 0x EVM address to first 6 + last 4', () => {
+    expect(shortAddr('0xC635e6Eb223aE14143E23cEEa9440bC773dc87Ec')).toBe('0xC635…87Ec')
+  })
+})

package/src/util/format.ts ADDED Viewed

@@ -0,0 +1,11 @@
+/**
+ * Truncate an Sui 0x-address to first 6 + last 4 (e.g. 0x1234…abcd) for
+ * compact UI rendering. Returns the input unchanged for short or non-0x
+ * values (e.g. an `.0g` name, `'?'`, or empty), so callers can pass any
+ * identifier without checking type first.
+ */
+export function shortAddr(addr?: string | null): string {
+  if (!addr) return '?'
+  if (!addr.startsWith('0x') || addr.length <= 12) return addr
+  return `${addr.slice(0, 6)}…${addr.slice(-4)}`
+}

package/src/util/gateway-spawn.test.ts ADDED Viewed

@@ -0,0 +1,86 @@
+/**
+ * Bundle B unit tests: spawnGatewayDaemon path. Uses a tiny shell-stub bin
+ * that "binds" the socket by simply touching the path then sleeping. We
+ * avoid spinning up the real `bun packages/gateway/bin/lyra-gateway-local`
+ * because that pulls in the full Sui runtime + plugin stack.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { spawnGatewayDaemon } from './gateway-spawn'
+let workDir: string
+beforeEach(() => {
+  workDir = mkdtempSync(join(tmpdir(), 'lyra-spawn-test-'))
+})
+afterEach(() => {
+  rmSync(workDir, { recursive: true, force: true })
+})
+describe('spawnGatewayDaemon', () => {
+  it('reports pre-existing when sock already present', async () => {
+    const sock = join(workDir, 'gateway.sock')
+    writeFileSync(sock, '')
+    const r = await spawnGatewayDaemon({
+      agentId: 'a1',
+      configPath: 'cfg',
+      socketPath: sock,
+      binPath: join(workDir, 'unused-bin'),
+      timeoutMs: 100,
+    })
+    expect(r.ready).toBe(false)
+    expect(r.reason).toBe('pre-existing')
+  })
+  it('reports timeout when bin does not bind the sock', async () => {
+    const sock = join(workDir, 'gateway.sock')
+    const stub = join(workDir, 'noop.ts')
+    writeFileSync(stub, 'setTimeout(() => process.exit(0), 50)\n')
+    const r = await spawnGatewayDaemon({
+      agentId: 'a3',
+      configPath: 'cfg',
+      socketPath: sock,
+      binPath: stub,
+      timeoutMs: 600,
+      stdio: 'ignore',
+    })
+    expect(r.ready).toBe(false)
+    expect(r.reason).toBe('timeout')
+    expect(existsSync(sock)).toBe(false)
+  })
+  it('returns ready=true when bin binds the sock + passes env', async () => {
+    const sock = join(workDir, 'gateway.sock')
+    const envOut = join(workDir, 'env.out')
+    const stub = join(workDir, 'env-stub.ts')
+    writeFileSync(
+      stub,
+      `import { writeFileSync } from 'node:fs'
+writeFileSync(${JSON.stringify(envOut)}, JSON.stringify({
+  agent: process.env.LYRA_AGENT_ID,
+  config: process.env.LYRA_CONFIG,
+}))
+writeFileSync(${JSON.stringify(sock)}, '')
+setTimeout(() => process.exit(0), 200)
+`,
+    )
+    const r = await spawnGatewayDaemon({
+      agentId: 'agent-EXPECTED',
+      configPath: '/path/to/cfg.ts',
+      socketPath: sock,
+      binPath: stub,
+      timeoutMs: 8_000,
+      stdio: 'ignore',
+    })
+    expect(r.ready).toBe(true)
+    expect(r.pid).toBeNumber()
+    const { readFileSync } = await import('node:fs')
+    const captured = JSON.parse(readFileSync(envOut, 'utf8'))
+    expect(captured.agent).toBe('agent-EXPECTED')
+    expect(captured.config).toBe('/path/to/cfg.ts')
+  })
+})

package/src/util/gateway-spawn.ts ADDED Viewed

@@ -0,0 +1,125 @@
+/**
+ * v0.21.5 Bundle B: spawn-and-wait helper for the local gateway daemon.
+ *
+ * Two callers share this:
+ *   - `lyra gateway start` (interactive Touch ID flow → spawn detached)
+ *   - `lyra` chat fallback when no sock is present (auto-spawn before
+ *     embedded TUI fallthrough — see Bundle C / chat.tsx)
+ *
+ * The helper does NOT perform operator-session unlock. Callers that need a
+ * fresh session must run that path before invoking this. If the daemon dies
+ * during boot because no session exists, the sock never appears and we
+ * surface the failure as `{ ready: false, reason: 'timeout' }`.
+ */
+import { type ChildProcess, spawn } from 'node:child_process'
+import { existsSync, mkdirSync, openSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { agentPaths } from 'lyra-core'
+export interface SpawnGatewayDaemonOpts {
+  agentId: string
+  configPath: string
+  socketPath: string
+  /** Max ms to wait for the unix sock to appear. Default 10_000. */
+  timeoutMs?: number
+  /**
+   * Where to send daemon stdout/stderr. Default 'log-file' which redirects
+   * to `~/.lyra/agents/<id>/gateway.log` (truncated on each boot) so
+   * detached daemon diagnostics survive the parent's exit. 'inherit' keeps
+   * the legacy behavior where output goes to the parent's tty (and vanishes
+   * on detach). 'ignore' drops everything.
+   */
+  stdio?: 'inherit' | 'ignore' | 'log-file'
+  /** Override the bin resolution (tests). */
+  binPath?: string
+  /** Override env (tests). */
+  env?: NodeJS.ProcessEnv
+}
+export interface SpawnGatewayDaemonResult {
+  ready: boolean
+  /** Detached child PID iff spawn succeeded (regardless of readiness). */
+  pid?: number
+  /** Reason populated on failure: 'spawn-failed' | 'timeout' | 'pre-existing'. */
+  reason?: 'spawn-failed' | 'timeout' | 'pre-existing'
+  /** First-line error message when spawn failed. */
+  error?: string
+}
+export function resolveLocalBin(): string {
+  const pkgUrl = import.meta.resolve('lyra-gateway/package.json')
+  const pkgRoot = dirname(fileURLToPath(pkgUrl))
+  return join(pkgRoot, 'bin', 'lyra-gateway-local')
+}
+export async function spawnGatewayDaemon(
+  opts: SpawnGatewayDaemonOpts,
+): Promise<SpawnGatewayDaemonResult> {
+  if (existsSync(opts.socketPath)) {
+    return { ready: false, reason: 'pre-existing' }
+  }
+  const bin = opts.binPath ?? resolveLocalBin()
+  const env: NodeJS.ProcessEnv = {
+    ...(opts.env ?? process.env),
+    LYRA_AGENT_ID: opts.agentId,
+    LYRA_CONFIG: opts.configPath,
+  }
+  const stdioMode = opts.stdio ?? 'log-file'
+  // v0.21.12: when stdio is 'log-file' redirect daemon stdout+stderr to
+  // ~/.lyra/agents/<id>/gateway.log (truncate-on-restart). Pre-fix this
+  // helper used 'inherit' which sent output to the parent's tty; once the
+  // parent CLI returned, those handles vanished and operators couldn't see
+  // why the daemon misbehaved. Truncation is fine because operators rarely
+  // reboot the daemon mid-session and `lyra gateway logs -f` only follows
+  // the current invocation.
+  let stdioCfg: ['ignore', 'inherit' | 'ignore' | number, 'inherit' | 'ignore' | number]
+  if (stdioMode === 'log-file') {
+    const logPath = join(agentPaths.agent(opts.agentId).dir, 'gateway.log')
+    try {
+      mkdirSync(dirname(logPath), { recursive: true })
+      const fd = openSync(logPath, 'w') // truncate on each boot
+      stdioCfg = ['ignore', fd, fd]
+    } catch {
+      // If we can't open the log file (perm, disk), fall back to ignore so
+      // we still spawn cleanly. Operators lose diagnostics but the daemon
+      // boots.
+      stdioCfg = ['ignore', 'ignore', 'ignore']
+    }
+  } else {
+    stdioCfg = ['ignore', stdioMode, stdioMode]
+  }
+  let proc: ChildProcess
+  try {
+    proc = spawn('bun', [bin], {
+      env,
+      detached: true,
+      stdio: stdioCfg,
+    })
+    proc.unref()
+  } catch (err) {
+    return {
+      ready: false,
+      reason: 'spawn-failed',
+      error: (err as Error).message?.slice(0, 200),
+    }
+  }
+  const timeoutMs = opts.timeoutMs ?? 10_000
+  const start = Date.now()
+  while (Date.now() - start < timeoutMs) {
+    if (existsSync(opts.socketPath)) {
+      return { ready: true, pid: proc.pid }
+    }
+    await new Promise(r => setTimeout(r, 200))
+  }
+  return {
+    ready: false,
+    pid: proc.pid,
+    reason: 'timeout',
+  }
+}