zooid 0.6.1 → 0.7.0

package/src/commands/init/registry.ts

@@ -0,0 +1,75 @@
+export interface SimplePresetMeta {
+  preset: 'claude' | 'codex'
+  models: string[]
+  subscriptionLabel: string
+  apiKeyEnvVar: string
+  apiKeyPromptLabel: string
+  /** Home-relative directory checked on the subscription sniff (existence only). */
+  credentialDir: string
+}
+
+export const SIMPLE_PRESETS: readonly SimplePresetMeta[] = [
+  {
+    preset: 'claude',
+    models: ['claude-sonnet-4-6', 'claude-opus-4-7', 'claude-haiku-4-5'],
+    subscriptionLabel: 'Claude subscription (Pro / Max / Team / Enterprise)',
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+    apiKeyPromptLabel: 'Anthropic',
+    credentialDir: '.claude',
+  },
+  {
+    preset: 'codex',
+    models: ['gpt-5.5'],
+    subscriptionLabel: 'ChatGPT subscription (Plus / Pro / Team)',
+    apiKeyEnvVar: 'OPENAI_API_KEY',
+    apiKeyPromptLabel: 'OpenAI',
+    credentialDir: '.codex',
+  },
+]
+
+export interface OpencodeProviderMeta {
+  id: string
+  label: string
+  description: string
+  models: string[]
+  apiKeyEnvVar: string
+}
+
+export const OPENCODE_PROVIDERS: readonly OpencodeProviderMeta[] = [
+  {
+    id: 'opencode-go',
+    label: 'opencode-go',
+    description: '$10/mo subscription — Kimi, GLM, MiniMax',
+    models: ['kimi-k2.6', 'kimi-k2.5', 'glm-5.1', 'glm-5', 'minimax-m2.7'],
+    apiKeyEnvVar: 'OPENCODE_API_KEY',
+  },
+  {
+    id: 'opencode',
+    label: 'opencode (Zen)',
+    description: 'free tier — curated models',
+    models: ['kimi-k2.5-free', 'glm-4.7-free', 'minimax-m2.1-free'],
+    apiKeyEnvVar: 'OPENCODE_API_KEY',
+  },
+  {
+    id: 'anthropic',
+    label: 'Anthropic',
+    description: 'Claude via direct Anthropic API',
+    models: ['claude-sonnet-4-6', 'claude-opus-4-7', 'claude-haiku-4-5'],
+    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
+  },
+  {
+    id: 'openrouter',
+    label: 'OpenRouter',
+    description: 'many providers via OpenRouter',
+    models: ['anthropic/claude-sonnet-4-6', 'zhipuai/glm-5', 'moonshot/kimi-k2.6'],
+    apiKeyEnvVar: 'OPENROUTER_API_KEY',
+  },
+]
+
+export function findSimplePreset(name: string): SimplePresetMeta | undefined {
+  return SIMPLE_PRESETS.find((p) => p.preset === name)
+}
+
+export function findOpencodeProvider(id: string): OpencodeProviderMeta | undefined {
+  return OPENCODE_PROVIDERS.find((p) => p.id === id)
+}

package/src/commands/init/sniff.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { sniffCredentials } from './sniff.js'
+
+let fakeHome: string
+
+beforeEach(() => {
+  fakeHome = mkdtempSync(join(tmpdir(), 'zooid-sniff-'))
+})
+
+afterEach(() => {
+  rmSync(fakeHome, { recursive: true, force: true })
+})
+
+describe('sniffCredentials', () => {
+  it('reports found when ~/.claude/ exists', () => {
+    mkdirSync(join(fakeHome, '.claude'))
+    const r = sniffCredentials('claude', fakeHome)
+    expect(r.found).toBe(true)
+    expect(r.path).toMatch(/\.claude$/)
+  })
+
+  it('reports found when ~/.codex/ exists', () => {
+    mkdirSync(join(fakeHome, '.codex'))
+    const r = sniffCredentials('codex', fakeHome)
+    expect(r.found).toBe(true)
+    expect(r.path).toMatch(/\.codex$/)
+  })
+
+  it('reports not-found when no config dir exists', () => {
+    const r = sniffCredentials('claude', fakeHome)
+    expect(r.found).toBe(false)
+  })
+
+  it('does not read directory contents — empty dir still counts as found', () => {
+    mkdirSync(join(fakeHome, '.claude'))
+    expect(sniffCredentials('claude', fakeHome).found).toBe(true)
+  })
+})

package/src/commands/init/sniff.ts

@@ -0,0 +1,30 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { findSimplePreset } from './registry.js'
+
+export interface SniffResult {
+  found: boolean
+  /** Absolute path that satisfied the sniff (the config directory). */
+  path?: string
+}
+
+/**
+ * Checks whether the operator's per-CLI config directory exists. NEVER reads
+ * any file inside — only `existsSync` on the dir. One rule covers Linux,
+ * macOS Keychain, and OS keyring without per-backend logic. The edge case
+ * where the dir exists but the operator isn't actually logged in is accepted;
+ * the spawned shim will surface a clearer error on first turn.
+ *
+ * `home` is overridable for tests.
+ */
+export function sniffCredentials(
+  preset: 'claude' | 'codex',
+  home: string = homedir(),
+): SniffResult {
+  const meta = findSimplePreset(preset)
+  if (!meta) return { found: false }
+  const full = join(home, meta.credentialDir)
+  if (existsSync(full)) return { found: true, path: full }
+  return { found: false }
+}

package/src/commands/init.test.ts

@@ -0,0 +1,131 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { mkdtempSync, readFileSync, existsSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { parse as parseYaml } from 'yaml'
+import { runInit } from './init.js'
+
+let dir: string
+
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-init-test-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+})
+
+function loadYaml(path: string): unknown {
+  return parseYaml(readFileSync(path, 'utf8'))
+}
+
+describe('runInit — claude subscription path', () => {
+  it('writes yaml + AGENTS.md + .claude/settings.json + .gitignore (no .env, no opencode.json)', async () => {
+    await runInit({
+      dir,
+      preset: 'claude',
+      auth: 'subscription',
+      model: 'claude-sonnet-4-6',
+    })
+
+    expect(existsSync(join(dir, 'zooid.yaml'))).toBe(true)
+    expect(existsSync(join(dir, 'agents/zooid-assistant/AGENTS.md'))).toBe(true)
+    expect(existsSync(join(dir, 'agents/zooid-assistant/CLAUDE.md'))).toBe(true)
+    expect(existsSync(join(dir, 'agents/zooid-assistant/.claude/settings.json'))).toBe(true)
+    expect(existsSync(join(dir, '.gitignore'))).toBe(true)
+    expect(existsSync(join(dir, '.env'))).toBe(false)
+    expect(existsSync(join(dir, 'agents/zooid-assistant/opencode.json'))).toBe(false)
+
+    const cfg = loadYaml(join(dir, 'zooid.yaml')) as {
+      agents: { 'zooid-assistant': { acp: { preset: string; model: string } } }
+    }
+    expect(cfg.agents['zooid-assistant'].acp).toEqual({
+      preset: 'claude',
+      model: 'claude-sonnet-4-6',
+    })
+  })
+})
+
+describe('runInit — claude api-key path', () => {
+  it('also writes .env with the ANTHROPIC_API_KEY line', async () => {
+    await runInit({
+      dir,
+      preset: 'claude',
+      auth: 'api-key',
+      model: 'claude-sonnet-4-6',
+      apiKey: 'sk-ant-xyz',
+    })
+
+    expect(readFileSync(join(dir, '.env'), 'utf8').trim()).toBe('ANTHROPIC_API_KEY=sk-ant-xyz')
+  })
+})
+
+describe('runInit — opencode opencode-go path', () => {
+  it('writes opencode.json with opencode-go provider + env-interpolated apiKey', async () => {
+    await runInit({
+      dir,
+      preset: 'opencode',
+      provider: 'opencode-go',
+      model: 'kimi-k2.6',
+      apiKey: 'sk-opencode-zzz',
+    })
+
+    expect(existsSync(join(dir, 'agents/zooid-assistant/.claude'))).toBe(false)
+    const oc = JSON.parse(
+      readFileSync(join(dir, 'agents/zooid-assistant/opencode.json'), 'utf8'),
+    )
+    expect(oc.model).toBe('opencode-go/kimi-k2.6')
+    expect(oc.provider['opencode-go'].options.apiKey).toBe('{env:OPENCODE_API_KEY}')
+    expect(oc.permission.webfetch).toBe('allow')
+
+    expect(readFileSync(join(dir, '.env'), 'utf8').trim()).toBe('OPENCODE_API_KEY=sk-opencode-zzz')
+
+    const yamlCfg = loadYaml(join(dir, 'zooid.yaml')) as {
+      agents: { 'zooid-assistant': { acp: unknown } }
+    }
+    expect(yamlCfg.agents['zooid-assistant'].acp).toEqual({ preset: 'opencode' })
+  })
+})
+
+describe('runInit — idempotency', () => {
+  it('errors on non-empty dir without --force', async () => {
+    writeFileSync(join(dir, 'preexisting.txt'), 'x')
+    await expect(
+      runInit({ dir, preset: 'claude', auth: 'subscription', model: 'claude-sonnet-4-6' }),
+    ).rejects.toThrow(/non-empty/i)
+  })
+
+  it('ignores package-manager files (node_modules, package.json, lockfiles, .git)', async () => {
+    writeFileSync(join(dir, 'package.json'), '{"name":"x"}')
+    writeFileSync(join(dir, 'pnpm-lock.yaml'), 'lockfileVersion: 9')
+    require('node:fs').mkdirSync(join(dir, 'node_modules'))
+    require('node:fs').mkdirSync(join(dir, '.git'))
+    await runInit({ dir, preset: 'claude', auth: 'subscription', model: 'claude-sonnet-4-6' })
+    expect(existsSync(join(dir, 'zooid.yaml'))).toBe(true)
+  })
+
+  it('preserves existing files under --force (additive create only)', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), 'preexisting: true')
+    await runInit({
+      dir,
+      preset: 'claude',
+      auth: 'subscription',
+      model: 'claude-sonnet-4-6',
+      force: true,
+    })
+    expect(readFileSync(join(dir, 'zooid.yaml'), 'utf8')).toContain('preexisting: true')
+    expect(existsSync(join(dir, 'agents/zooid-assistant/AGENTS.md'))).toBe(true)
+  })
+
+  it('overwrites under --force --overwrite', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), 'preexisting: true')
+    await runInit({
+      dir,
+      preset: 'claude',
+      auth: 'subscription',
+      model: 'claude-sonnet-4-6',
+      force: true,
+      overwrite: true,
+    })
+    expect(readFileSync(join(dir, 'zooid.yaml'), 'utf8')).not.toContain('preexisting: true')
+  })
+})

package/src/commands/init.ts

@@ -0,0 +1,158 @@
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import {
+  generateAgentsMd,
+  generateClaudeMd,
+  generateClaudeSettings,
+  generateEnv,
+  generateGitignore,
+  generateOpencodeJson,
+  generateOpencodeReadme,
+  generateZooidYaml,
+} from './init/generators.js'
+import {
+  findOpencodeProvider,
+  findSimplePreset,
+} from './init/registry.js'
+import { sniffCredentials } from './init/sniff.js'
+
+export interface InitOptions {
+  dir: string
+  preset: 'claude' | 'codex' | 'opencode'
+  /** Required for claude/codex; ignored for opencode. */
+  auth?: 'subscription' | 'api-key'
+  /** Required for claude/codex; required for opencode (paired with `provider`). */
+  model?: string
+  /** Required for opencode. */
+  provider?: string
+  /** Required on api-key path; required for opencode. */
+  apiKey?: string
+  /** Allow generating into a non-empty dir. */
+  force?: boolean
+  /** Required with `force` to overwrite existing files. */
+  overwrite?: boolean
+}
+
+interface WriteSpec {
+  path: string
+  content: string
+}
+
+// Pre-existing entries that don't count toward "non-empty". Lets operators
+// run `pnpm install` before `zooid init` without tripping the guard.
+const IGNORED_PREEXISTING = new Set([
+  '.',
+  '..',
+  '.git',
+  '.DS_Store',
+  'node_modules',
+  'package.json',
+  'package-lock.json',
+  'pnpm-lock.yaml',
+  'yarn.lock',
+])
+
+export async function runInit(opts: InitOptions): Promise<void> {
+  const dir = resolve(opts.dir)
+  mkdirSync(dir, { recursive: true })
+
+  if (!opts.force) {
+    const blocking = readdirSync(dir).filter((n) => !IGNORED_PREEXISTING.has(n))
+    if (blocking.length > 0) {
+      throw new Error(
+        `${dir} is non-empty (use --force to allow scaffolding into it). Conflicting entries: ${blocking.join(', ')}`,
+      )
+    }
+  }
+
+  const writes: WriteSpec[] = []
+
+  if (opts.preset === 'claude' || opts.preset === 'codex') {
+    if (!opts.model) throw new Error(`--model is required for preset ${opts.preset}`)
+    if (!opts.auth) throw new Error('--auth (subscription|api-key) is required for claude/codex')
+    const meta = findSimplePreset(opts.preset)!
+
+    writes.push({
+      path: 'zooid.yaml',
+      content: generateZooidYaml({ preset: opts.preset, model: opts.model }),
+    })
+    writes.push({ path: 'agents/zooid-assistant/AGENTS.md', content: generateAgentsMd() })
+
+    if (opts.preset === 'claude') {
+      writes.push({
+        path: 'agents/zooid-assistant/CLAUDE.md',
+        content: generateClaudeMd(),
+      })
+      writes.push({
+        path: 'agents/zooid-assistant/.claude/settings.json',
+        content: generateClaudeSettings(),
+      })
+    }
+
+    if (opts.auth === 'api-key') {
+      if (!opts.apiKey) throw new Error('--api-key is required when --auth=api-key')
+      writes.push({
+        path: '.env',
+        content: generateEnv({ envVar: meta.apiKeyEnvVar, value: opts.apiKey }),
+      })
+    }
+  } else if (opts.preset === 'opencode') {
+    if (!opts.provider) throw new Error('--provider is required for opencode')
+    const isCustom = opts.provider === 'custom'
+    const providerMeta = isCustom ? undefined : findOpencodeProvider(opts.provider)
+    if (!isCustom && !providerMeta) throw new Error(`unknown opencode provider: ${opts.provider}`)
+    if (!isCustom && !opts.model) throw new Error('--model is required (paired with --provider)')
+    if (!isCustom && !opts.apiKey) throw new Error('--api-key is required for opencode')
+
+    writes.push({ path: 'zooid.yaml', content: generateZooidYaml({ preset: 'opencode' }) })
+    writes.push({ path: 'agents/zooid-assistant/AGENTS.md', content: generateAgentsMd() })
+    writes.push({
+      path: 'agents/zooid-assistant/opencode.json',
+      content: generateOpencodeJson({
+        provider: opts.provider,
+        model: opts.model,
+        apiKeyEnvVar: providerMeta?.apiKeyEnvVar,
+      }),
+    })
+    if (isCustom) {
+      writes.push({
+        path: 'agents/zooid-assistant/opencode.json.README',
+        content: generateOpencodeReadme(),
+      })
+    } else {
+      writes.push({
+        path: '.env',
+        content: generateEnv({ envVar: providerMeta!.apiKeyEnvVar, value: opts.apiKey! }),
+      })
+    }
+  } else {
+    throw new Error(`unknown preset: ${String(opts.preset)}`)
+  }
+
+  writes.push({ path: '.gitignore', content: generateGitignore() })
+
+  for (const w of writes) {
+    const full = join(dir, w.path)
+    const exists = existsSync(full)
+    if (exists && !opts.overwrite) {
+      console.warn(`⚠ ${w.path} exists; left as-is (use --force --overwrite to replace)`)
+      continue
+    }
+    mkdirSync(dirname(full), { recursive: true })
+    writeFileSync(full, w.content)
+    console.log(`✓ Created ${w.path}`)
+  }
+
+  if ((opts.preset === 'claude' || opts.preset === 'codex') && opts.auth === 'subscription') {
+    const s = sniffCredentials(opts.preset)
+    if (s.found) {
+      console.log(`✓ Found ${opts.preset} config at ${s.path}`)
+    } else {
+      console.warn(
+        `⚠ No ${opts.preset} config detected — run \`${opts.preset}\` to log in before \`zooid dev\``,
+      )
+    }
+  }
+
+  console.log('\nNext: zooid dev')
+}

package/src/commands/logs.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, mkdir, writeFile, symlink, readdir } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { runLogs, type LogsFlags } from './logs.js'
+
+async function fixtureDay(
+  dataDir: string,
+  day: string,
+  files: Record<string, string>,
+): Promise<void> {
+  const dir = join(dataDir, 'logs', day)
+  await mkdir(dir, { recursive: true })
+  for (const [name, content] of Object.entries(files)) {
+    await writeFile(join(dir, name), content)
+  }
+}
+
+describe('runLogs', () => {
+  let dataDir: string
+  let stdout: string[]
+  beforeEach(async () => {
+    dataDir = await mkdtemp(join(tmpdir(), 'zooid-obs-cmd-'))
+    stdout = []
+  })
+  afterEach(() => {
+    rmSync(dataDir, { recursive: true, force: true })
+  })
+
+  function run(flags: Partial<LogsFlags> = {}): Promise<void> {
+    return runLogs({
+      dataDir,
+      writer: (s) => {
+        stdout.push(s)
+      },
+      now: new Date('2026-05-06T10:00:00Z'),
+      ...flags,
+    } as LogsFlags)
+  }
+
+  it('lists known sources for the requested day', async () => {
+    await fixtureDay(dataDir, '2026-05-06', {
+      'tuwunel.log': 'tw line\n',
+      'daemon.log': '{"msg":"d"}\n',
+      'agent-docs.log': 'docs stderr\n',
+      'agent-docs.acp.jsonl': '{"kind":"turn_started","agent":"docs","turn_id":"t1"}\n',
+    })
+    await symlink('2026-05-06', join(dataDir, 'logs', 'today'))
+    await run({ source: undefined })
+    const out = stdout.join('')
+    expect(out).toContain('tuwunel')
+    expect(out).toContain('daemon')
+    expect(out).toContain('agent-docs')
+  })
+
+  it('reads a single source from today by default', async () => {
+    await fixtureDay(dataDir, '2026-05-06', { 'tuwunel.log': 'hello tuwunel\n' })
+    await symlink('2026-05-06', join(dataDir, 'logs', 'today'))
+    await run({ source: 'tuwunel' })
+    expect(stdout.join('')).toContain('hello tuwunel')
+  })
+
+  it('--day overrides the default (today)', async () => {
+    await fixtureDay(dataDir, '2026-05-04', { 'tuwunel.log': 'old line\n' })
+    await fixtureDay(dataDir, '2026-05-06', { 'tuwunel.log': 'new line\n' })
+    await symlink('2026-05-06', join(dataDir, 'logs', 'today'))
+    await run({ source: 'tuwunel', day: '2026-05-04' })
+    const out = stdout.join('')
+    expect(out).toContain('old line')
+    expect(out).not.toContain('new line')
+  })
+
+  it('--turn filters JSONL events across all agent taps for that day', async () => {
+    await fixtureDay(dataDir, '2026-05-06', {
+      'agent-docs.acp.jsonl':
+        [
+          '{"kind":"turn_started","agent":"docs","turn_id":"t1"}',
+          '{"kind":"session_update","agent":"docs","turn_id":"t1","notification":{"sessionUpdate":"tool_call"}}',
+          '{"kind":"turn_completed","agent":"docs","turn_id":"t1","stop_reason":"end_turn"}',
+          '{"kind":"turn_started","agent":"docs","turn_id":"t2"}',
+        ].join('\n') + '\n',
+      'agent-echo.acp.jsonl': '{"kind":"turn_started","agent":"echo","turn_id":"t1"}\n',
+    })
+    await symlink('2026-05-06', join(dataDir, 'logs', 'today'))
+    await run({ turn: 't1' })
+    const out = stdout.join('')
+    expect(out).toContain('"turn_id":"t1"')
+    expect(out).toContain('"agent":"docs"')
+    expect(out).toContain('"agent":"echo"')
+    expect(out).not.toContain('"turn_id":"t2"')
+  })
+
+  it('prune removes folders older than --keep, leaves today', async () => {
+    await fixtureDay(dataDir, '2026-04-20', { 'x.log': '' })
+    await fixtureDay(dataDir, '2026-05-01', { 'x.log': '' })
+    await fixtureDay(dataDir, '2026-05-06', { 'x.log': '' })
+    await symlink('2026-05-06', join(dataDir, 'logs', 'today'))
+    await run({ subcommand: 'prune', keep: 3 })
+    const remaining = (await readdir(join(dataDir, 'logs')))
+      .filter((n) => n !== 'today')
+      .sort()
+    expect(remaining).toEqual(['2026-05-06'])
+  })
+})

package/src/commands/logs.ts

@@ -0,0 +1,108 @@
+import { readFile, readdir, readlink } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { pruneOldDays } from '../observability/paths.js'
+
+export interface LogsFlags {
+  dataDir: string
+  source?: string
+  day?: string
+  turn?: string
+  follow?: boolean
+  subcommand?: 'prune'
+  keep?: number
+  /** Tests inject an alternate writer. */
+  writer?: (s: string) => void
+  now?: Date
+}
+
+const KNOWN_SOURCES = ['tuwunel', 'daemon', 'dev'] as const
+
+export async function runLogs(flags: LogsFlags): Promise<void> {
+  const writer = flags.writer ?? ((s: string) => process.stdout.write(s))
+
+  if (flags.subcommand === 'prune') {
+    const removed = await pruneOldDays({
+      dataDir: flags.dataDir,
+      retainDays: flags.keep ?? 14,
+      now: flags.now,
+    })
+    writer(`pruned ${removed.length} day(s): ${removed.join(', ')}\n`)
+    return
+  }
+
+  const day = flags.day ?? (await resolveTodaySlug(flags.dataDir))
+  if (!day) {
+    writer('no logs yet\n')
+    return
+  }
+  const dayDir = join(flags.dataDir, 'logs', day)
+  if (!existsSync(dayDir)) {
+    writer(`no logs for ${day}\n`)
+    return
+  }
+
+  if (flags.turn) {
+    await dumpByTurn(dayDir, flags.turn, writer)
+    return
+  }
+
+  if (!flags.source) {
+    const entries = await readdir(dayDir)
+    const sources = new Set<string>()
+    for (const e of entries) {
+      if (e.endsWith('.log')) sources.add(e.replace(/\.log$/, ''))
+      if (e.endsWith('.acp.jsonl')) sources.add(e.replace(/\.acp\.jsonl$/, '.acp'))
+    }
+    writer([...sources].sort().join('\n') + '\n')
+    return
+  }
+
+  const path = resolveSourcePath(dayDir, flags.source)
+  if (!existsSync(path)) {
+    writer(`no such source: ${flags.source}\n`)
+    return
+  }
+  writer(await readFile(path, 'utf8'))
+  // -f is intentionally not implemented in this cycle; documented as a follow-up.
+}
+
+async function resolveTodaySlug(dataDir: string): Promise<string | null> {
+  const link = join(dataDir, 'logs', 'today')
+  try {
+    return await readlink(link)
+  } catch {
+    return null
+  }
+}
+
+function resolveSourcePath(dayDir: string, source: string): string {
+  if (source.startsWith('agent-')) {
+    if (source.endsWith('.acp')) return join(dayDir, `${source.slice(0, -4)}.acp.jsonl`)
+    return join(dayDir, `${source}.log`)
+  }
+  if ((KNOWN_SOURCES as readonly string[]).includes(source))
+    return join(dayDir, `${source}.log`)
+  return join(dayDir, source)
+}
+
+async function dumpByTurn(
+  dayDir: string,
+  turnId: string,
+  writer: (s: string) => void,
+): Promise<void> {
+  const entries = await readdir(dayDir)
+  const taps = entries.filter((e) => e.endsWith('.acp.jsonl')).sort()
+  for (const f of taps) {
+    const text = await readFile(join(dayDir, f), 'utf8')
+    for (const line of text.split('\n')) {
+      if (!line) continue
+      try {
+        const obj = JSON.parse(line)
+        if (obj.turn_id === turnId) writer(line + '\n')
+      } catch {
+        // skip malformed line
+      }
+    }
+  }
+}

package/src/commands/start.ts

@@ -0,0 +1,28 @@
+import { randomBytes } from 'node:crypto'
+import { resolve } from 'node:path'
+import type { CliFlags } from '@zooid/core'
+import { resolveDataLayout } from '../bootstrap/data-layout.js'
+import { startDaemon } from '../daemon/start-daemon.js'
+
+export interface StartFlags extends CliFlags {
+  printToken?: boolean
+  /** Data root dir; defaults to `./data` relative to cwd. */
+  dataDir?: string
+}
+
+export async function runStart(flags: StartFlags): Promise<void> {
+  if (flags.printToken) {
+    process.stdout.write(`${randomBytes(32).toString('hex')}\n`)
+    return
+  }
+  const dataRoot = resolve(process.cwd(), flags.dataDir ?? './data')
+  const layout = resolveDataLayout(dataRoot)
+  const handle = await startDaemon({
+    cliFlags: flags,
+    installSignalHandlers: true,
+    agentsDir: layout.agentsDir,
+  })
+  console.log(`zooid listening on http://localhost:${handle.port}`)
+  for (const name of handle.agentNames) console.log(`  agent: ${name}`)
+  await handle.whenStopped
+}