zooid 0.6.0 → 0.7.0

package/src/commands/status.test.ts

@@ -0,0 +1,73 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { collectStatus } from './status.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-status-'))
+})
+afterEach(() => {
+  rmSync(dir, { recursive: true, force: true })
+  vi.restoreAllMocks()
+})
+
+const yaml = [
+  'transports:',
+  '  m:',
+  '    type: matrix',
+  '    homeserver: http://localhost:8448',
+  '    as_token: as-x',
+  '    hs_token: hs-x',
+  '    sender_localpart: zooid',
+  '    user_namespace: "@.*:localhost"',
+  '    port: 9099',
+  'agents:',
+  '  assistant:',
+  '    workdir: .',
+  '    acp: { preset: claude }',
+  '    matrix:',
+  '      transport: m',
+  '      user_id: "@assistant:localhost"',
+  '      rooms: ["!general:localhost"]',
+  '      trigger: mention',
+].join('\n')
+
+describe('collectStatus', () => {
+  it('reports tuwunel up + daemon up + agents listed', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), yaml)
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string) => {
+        if (url.includes('/_matrix/client/versions')) {
+          return new Response(JSON.stringify({ versions: ['v1.13'] }), { status: 200 })
+        }
+        return new Response('not found', { status: 404 })
+      }),
+    )
+    const s = await collectStatus({ cwd: dir, tuwunelUrl: 'http://localhost:8448' })
+    expect(s.tuwunel).toEqual({ status: 'up', url: 'http://localhost:8448' })
+    expect(s.daemon).toEqual({ status: 'up', url: 'http://localhost:9099' })
+    expect(s.agents).toEqual([
+      { name: 'assistant', userId: '@assistant:localhost', trigger: 'mention' },
+    ])
+  })
+
+  it('reports daemon down when the AS callback port refuses the connection', async () => {
+    writeFileSync(join(dir, 'zooid.yaml'), yaml)
+    vi.stubGlobal(
+      'fetch',
+      vi.fn(async (url: string) => {
+        if (url.includes('/_matrix/client/versions')) {
+          return new Response(JSON.stringify({ versions: ['v1.13'] }), { status: 200 })
+        }
+        throw new Error('ECONNREFUSED')
+      }),
+    )
+    const s = await collectStatus({ cwd: dir, tuwunelUrl: 'http://localhost:8448' })
+    expect(s.tuwunel.status).toBe('up')
+    if ('status' in s.daemon) expect(s.daemon.status).toBe('down')
+    else throw new Error('expected daemon to have status field')
+  })
+})

package/src/commands/status.ts

@@ -0,0 +1,100 @@
+import { readFileSync } from 'node:fs'
+import chalk from 'chalk'
+import { findConfigFile, findMatrixTransport, loadZooidConfig } from '@zooid/core'
+import { deriveHomeserverShape } from '../bootstrap/derive.js'
+
+export interface StatusFlags {
+  cwd?: string
+  dataDir: string
+  /** Tuwunel host port. If omitted, derived from zooid.yaml's matrix transport. */
+  port?: number
+}
+
+export interface StatusReport {
+  tuwunel: { status: 'up' | 'down'; url: string }
+  daemon: { status: 'up' | 'down'; url: string } | { status: 'unknown'; reason: string }
+  agents: { name: string; userId: string; trigger: string }[]
+}
+
+async function probe(url: string, timeoutMs = 2_000): Promise<boolean> {
+  try {
+    const r = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) })
+    return r.status > 0
+  } catch {
+    return false
+  }
+}
+
+export async function collectStatus(opts: {
+  cwd: string
+  tuwunelUrl: string
+}): Promise<StatusReport> {
+  const tuwunelUp = await probe(`${opts.tuwunelUrl}/_matrix/client/versions`)
+  const tuwunel: StatusReport['tuwunel'] = {
+    status: tuwunelUp ? 'up' : 'down',
+    url: opts.tuwunelUrl,
+  }
+
+  const found = findConfigFile(opts.cwd)
+  if (!found) {
+    return {
+      tuwunel,
+      daemon: { status: 'unknown', reason: 'no zooid.yaml' },
+      agents: [],
+    }
+  }
+  const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'))
+  const matrixEntry = Object.entries(cfg.transports).find(
+    ([, t]) => t.type === 'matrix',
+  ) as [string, { port?: number }] | undefined
+  const daemonPort = matrixEntry?.[1]?.port ?? 8080
+  const daemonUrl = `http://localhost:${daemonPort}`
+  const daemonUp = await probe(daemonUrl)
+  const agents: StatusReport['agents'] = []
+  for (const a of Object.values(cfg.agents)) {
+    if (a.matrix) {
+      agents.push({
+        name: a.name,
+        userId: a.matrix.user_id,
+        trigger: a.matrix.trigger,
+      })
+    }
+  }
+  return {
+    tuwunel,
+    daemon: { status: daemonUp ? 'up' : 'down', url: daemonUrl },
+    agents,
+  }
+}
+
+export async function runStatus(flags: StatusFlags): Promise<void> {
+  const cwd = flags.cwd ?? process.cwd()
+  let port = flags.port
+  if (port === undefined) {
+    const found = findConfigFile(cwd)
+    if (found) {
+      const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'))
+      const matrix = findMatrixTransport(cfg)
+      if (matrix) {
+        const userIds = Object.values(cfg.agents)
+          .filter((a) => a.matrix?.transport === matrix.name)
+          .map((a) => a.matrix!.user_id)
+        port = deriveHomeserverShape(matrix.transport, userIds).port
+      }
+    }
+  }
+  const tuwunelUrl = `http://localhost:${port ?? 8448}`
+  const s = await collectStatus({ cwd, tuwunelUrl })
+  const fmt = (st: 'up' | 'down' | 'unknown'): string =>
+    st === 'up' ? chalk.green('up') : st === 'down' ? chalk.red('down') : chalk.yellow('unknown')
+  process.stdout.write(
+    [
+      `tuwunel  ${fmt(s.tuwunel.status)}  ${s.tuwunel.url}`,
+      `daemon   ${fmt(s.daemon.status)}  ${'url' in s.daemon ? s.daemon.url : s.daemon.reason}`,
+      ...s.agents.map(
+        (a) => `  agent: ${a.name} (${a.userId}, trigger: ${a.trigger})`,
+      ),
+      '',
+    ].join('\n'),
+  )
+}

package/src/daemon/start-daemon.test.ts

@@ -0,0 +1,67 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { startDaemon } from './start-daemon.js'
+
+let dir: string
+beforeEach(() => {
+  dir = mkdtempSync(join(tmpdir(), 'zooid-startd-'))
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('startDaemon — http transport (smoke without Matrix)', () => {
+  it('starts an http transport when zooid.yaml only declares one', async () => {
+    const yamlPath = join(dir, 'zooid.yaml')
+    writeFileSync(
+      yamlPath,
+      [
+        'runtime: local',
+        'transports:',
+        '  http-local:',
+        '    type: http',
+        '    port: 0',
+        'agents:',
+        '  noop:',
+        '    workdir: .',
+        '    acp: { preset: claude }',
+        '    http: { transport: http-local }',
+      ].join('\n'),
+    )
+    process.env.ZOOID_TOKEN = 'test-token'
+
+    const handle = await startDaemon({
+      configPath: yamlPath,
+      installSignalHandlers: false,
+    })
+
+    expect(handle.port).toBeGreaterThan(0)
+    expect(handle.agentNames).toEqual(['noop'])
+
+    const r = await fetch(`http://localhost:${handle.port}/`, {
+      headers: { authorization: 'Bearer test-token' },
+    })
+    expect(r.status).toBeGreaterThan(0)
+
+    await handle.stop()
+    await handle.stop()
+  })
+
+  it('rejects when no transport is declared', async () => {
+    const yamlPath = join(dir, 'zooid.yaml')
+    writeFileSync(
+      yamlPath,
+      [
+        'runtime: local',
+        'agents:',
+        '  a:',
+        '    workdir: .',
+        '    acp: { preset: claude }',
+        '    http: { transport: x }',
+      ].join('\n'),
+    )
+    await expect(
+      startDaemon({ configPath: yamlPath, installSignalHandlers: false }),
+    ).rejects.toThrow()
+  })
+})

package/src/daemon/start-daemon.ts

@@ -0,0 +1,243 @@
+import { readFileSync } from 'node:fs'
+import { mkdir, unlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { AddressInfo } from 'node:net'
+import { serve, type ServerType } from '@hono/node-server'
+import {
+  ApprovalCorrelator,
+  findConfigFile,
+  findHttpTransport,
+  findMatrixTransport,
+  loadZooidConfig,
+  mergeCliFlags,
+  type CliFlags,
+  type TapEvent,
+} from '@zooid/core'
+import { createApp } from '@zooid/transport-http'
+import {
+  MatrixClient,
+  createMatrixTransport,
+  ensureWorkforceSpace,
+  startWorkforcePublisher,
+  type AgentBinding,
+  type PublisherHandle,
+} from '@zooid/transport-matrix'
+import {
+  SpawnRegistry,
+  startDaemonSocketServer,
+  type DaemonSocketHandle,
+} from '@zooid/context-mcp'
+import { buildAcpRegistry } from '../build-registry.js'
+
+export interface StartDaemonOpts {
+  configPath?: string
+  cwd?: string
+  cliFlags?: CliFlags
+  installSignalHandlers?: boolean
+  /** Admin Matrix user ID. Forwarded to the matrix transport for room bootstrap. */
+  adminUserId?: string
+  /** Observability tap forwarded to each AcpClient. */
+  onTap?: (agentName: string, event: TapEvent) => void
+  /**
+   * Per-agent state root (`<dataRoot>/agents/`). Threaded into
+   * `buildAcpRegistry` so each AcpClient persists `sessionId`s across
+   * daemon restarts.
+   */
+  agentsDir?: string
+}
+
+export interface DaemonHandle {
+  port: number
+  agentNames: string[]
+  stop(): Promise<void>
+  whenStopped: Promise<void>
+}
+
+function listenAsync(server: ServerType): Promise<number> {
+  return new Promise((resolve) => {
+    const check = () => {
+      const addr = server.address() as AddressInfo | string | null
+      if (addr && typeof addr === 'object') resolve(addr.port)
+      else setImmediate(check)
+    }
+    check()
+  })
+}
+
+function closeAsync(server: ServerType): Promise<void> {
+  return new Promise((resolve) => {
+    server.close(() => resolve())
+  })
+}
+
+export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHandle> {
+  const cwd = opts.cwd ?? process.cwd()
+  const found = opts.configPath ? { path: opts.configPath } : findConfigFile(cwd)
+  if (!found) throw new Error('zooid.yaml is required')
+  const base = loadZooidConfig(readFileSync(found.path, 'utf8'))
+  const config = mergeCliFlags(base, opts.cliFlags ?? {})
+
+  const approvals = new ApprovalCorrelator()
+
+  const daemonSockPath = opts.agentsDir
+    ? join(opts.agentsDir, '..', 'run', 'context.sock')
+    : join(tmpdir(), `zooid-context-${process.pid}.sock`)
+  await mkdir(dirname(daemonSockPath), { recursive: true }).catch(() => {})
+  const contextSpawnRegistry = new SpawnRegistry()
+  let contextSocket: DaemonSocketHandle | null = null
+  try {
+    contextSocket = await startDaemonSocketServer({
+      sockPath: daemonSockPath,
+      registry: contextSpawnRegistry,
+    })
+  } catch (err) {
+    console.warn('[context] daemon socket startup failed; zooid-context MCP disabled:', err)
+  }
+
+  const registry = buildAcpRegistry(config, {
+    approvals,
+    onTap: opts.onTap,
+    agentsDir: opts.agentsDir,
+    contextSpawnRegistry: contextSocket ? contextSpawnRegistry : undefined,
+    daemonSockPath: contextSocket ? daemonSockPath : undefined,
+  })
+  const agentNames = Object.keys(config.agents)
+
+  console.log(
+    `[context] socket=${daemonSockPath} ` +
+      `status=${contextSocket ? 'listening' : 'disabled'} ` +
+      `agents={${agentNames
+        .map((n) => `${n}:${registry.hasContextSpawn(n) ? 'yes' : 'no'}`)
+        .join(', ')}}`,
+  )
+
+  let server: ServerType | null = null
+  let stopped = false
+  let resolveStopped!: () => void
+  const whenStopped = new Promise<void>((r) => {
+    resolveStopped = r
+  })
+
+  const matrix = findMatrixTransport(config)
+  let port: number
+
+  if (matrix) {
+    const client = new MatrixClient({
+      homeserver: matrix.transport.homeserver,
+      asToken: matrix.transport.as_token,
+    })
+    const bindings: AgentBinding[] = []
+    for (const a of Object.values(config.agents)) {
+      if (a.matrix?.transport !== matrix.name) continue
+      const binding: AgentBinding = {
+        name: a.name,
+        userId: a.matrix.user_id,
+        rooms: a.matrix.rooms,
+        trigger: a.matrix.trigger,
+      }
+      if (a.matrix.display_name !== undefined) binding.displayName = a.matrix.display_name
+      bindings.push(binding)
+    }
+    const transport = createMatrixTransport({
+      agents: registry,
+      approvals,
+      client,
+      bindings,
+      hsToken: matrix.transport.hs_token,
+      adminUserId: opts.adminUserId,
+    })
+    const requestedPort = matrix.transport.port ?? 8080
+    // Bind 0.0.0.0 explicitly — @hono/node-server defaults to IPv6-only on
+    // macOS, which Docker's NAT bridge can't reach when Tuwunel pushes AS
+    // events back to host.docker.internal:<port>.
+    server = serve({ fetch: transport.app.fetch, port: requestedPort, hostname: '0.0.0.0' })
+    port = await listenAsync(server)
+
+    // user_namespace is a regex like `@.*:localhost`; the part after the last
+    // `:` is the homeserver's server_name. Fall back to the homeserver URL's
+    // host if the namespace shape is unexpected.
+    const serverName =
+      matrix.transport.user_namespace.split(':').slice(1).join(':').replace(/\\?\)?$/, '') ||
+      new URL(matrix.transport.homeserver).hostname
+    const asUserId = `@${matrix.transport.sender_localpart}:${serverName}`
+    const spaceLocalpart = matrix.transport.space ?? 'dev'
+    let spaceRoomId: string | undefined
+    try {
+      spaceRoomId = await ensureWorkforceSpace({
+        client,
+        asUserId,
+        serverName,
+        spaceLocalpart,
+        preset: 'public_chat',
+      })
+      console.log(`[matrix] ensured workforce space #${spaceLocalpart}:${serverName} → ${spaceRoomId}`)
+    } catch (err) {
+      console.warn('[matrix] workforce space provisioning failed:', err)
+    }
+
+    // Bootstrap *after* the listener is up: registerBot/createRoom/joinRoom
+    // each trigger Tuwunel to push events back to the AS, and Tuwunel only
+    // retries those a few times before dropping. Listening first ensures
+    // those pushes don't hit a connection-refused. Bootstrap also runs
+    // *after* the space exists so BotPool can attach each agent room as
+    // m.space.child while joining it.
+    await transport.bootstrap({ spaceRoomId, asUserId })
+
+    if (spaceRoomId) {
+      try {
+        const publisher: PublisherHandle = await startWorkforcePublisher({
+          client,
+          spaceRoomId,
+          asUserId,
+          getAgents: () => bindings,
+        })
+        console.log(`[matrix] published eco.zoon.workforce (${bindings.length} agents)`)
+        void publisher
+      } catch (err) {
+        console.warn('[matrix] workforce roster publication failed:', err)
+      }
+    }
+  } else {
+    const http = findHttpTransport(config)
+    if (!http) throw new Error('no transport declared in zooid.yaml')
+    const token = process.env.ZOOID_TOKEN
+    if (!token) throw new Error('ZOOID_TOKEN is required for http transport')
+    const app = createApp({ agents: registry, approvals, token })
+    server = serve({ fetch: app.fetch, port: http.transport.port, hostname: '0.0.0.0' })
+    port = await listenAsync(server)
+  }
+
+  const stop = async (): Promise<void> => {
+    if (stopped) return whenStopped
+    stopped = true
+    try {
+      if (server) await closeAsync(server)
+    } catch {
+      // swallow
+    }
+    try {
+      await registry.stopAll()
+    } catch (err) {
+      console.error('stopAll:', err)
+    }
+    try {
+      if (contextSocket) await contextSocket.close()
+      await unlink(daemonSockPath).catch(() => {})
+    } catch {
+      // swallow
+    }
+    resolveStopped()
+  }
+
+  if (opts.installSignalHandlers !== false) {
+    const handler = (sig: NodeJS.Signals): void => {
+      console.log(`received ${sig}, stopping agents...`)
+      void stop().then(() => process.exit(0))
+    }
+    process.on('SIGINT', () => handler('SIGINT'))
+    process.on('SIGTERM', () => handler('SIGTERM'))
+  }
+
+  return { port, agentNames, stop, whenStopped }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export { buildAcpRegistry } from './build-registry.js'
+export type { BuildAcpRegistryOptions } from './build-registry.js'

package/src/observability/capture-agent.ts

@@ -0,0 +1,58 @@
+import type { TapEvent } from '@zooid/core'
+import type { LogPaths } from './paths.js'
+import { JsonlSink, shouldCaptureUpdate, type Verbosity } from './file-sink.js'
+
+export interface MatrixContext {
+  room_id: string
+  event_id: string
+}
+
+export interface WireAgentCaptureOpts {
+  agent: string
+  paths: LogPaths
+  verbosity: Verbosity
+  /** Returns the most-recently-known matrix context for the agent, or null. */
+  matrixContext: () => MatrixContext | null
+  /** Override for tests. */
+  now?: () => Date
+}
+
+export interface AgentCapture {
+  onTap: (event: TapEvent) => void
+  close: () => Promise<void>
+}
+
+export function wireAgentCapture(opts: WireAgentCaptureOpts): AgentCapture {
+  const sink = new JsonlSink(opts.paths.agentTap(opts.agent))
+  const now = opts.now ?? (() => new Date())
+  const pending: Promise<unknown>[] = []
+
+  const onTap = (event: TapEvent): void => {
+    if (event.kind === 'session_update') {
+      const variant =
+        (event.update as { sessionUpdate?: string }).sessionUpdate ?? 'unknown'
+      if (!shouldCaptureUpdate(opts.verbosity, variant)) return
+    }
+    const matrix = opts.matrixContext()
+    const envelope: Record<string, unknown> = {
+      ts: now().toISOString(),
+      agent: opts.agent,
+      session_id: event.sessionId,
+      turn_id: event.turnId,
+      kind: event.kind,
+    }
+    if (matrix) envelope.matrix = matrix
+    if (event.kind === 'session_update') envelope.notification = event.update
+    else if (event.kind === 'turn_started') envelope.prompt_text = event.promptText
+    else if (event.kind === 'turn_completed') envelope.stop_reason = event.stopReason
+    pending.push(sink.write(envelope))
+  }
+
+  return {
+    onTap,
+    close: async () => {
+      await Promise.all(pending)
+      await sink.close()
+    },
+  }
+}

package/src/observability/capture-tuwunel.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync } from 'node:fs'
+import { spawn } from 'node:child_process'
+import { buildRunArgs } from '../services/tuwunel.js'
+import { captureChildToFile } from './capture-tuwunel.js'
+
+const base = {
+  name: 'zooid-tuwunel',
+  hostPort: 8448,
+  paths: {
+    dataDir: '/abs/data/matrix',
+    dbDir: '/abs/data/matrix/db',
+    mediaDir: '/abs/data/matrix/media',
+    configDir: '/abs/data/matrix/config',
+    registrationsDir: '/abs/data/matrix/config/registrations',
+    tuwunelTomlPath: '/abs/data/matrix/config/tuwunel.toml',
+    appserviceYamlPath: '/abs/data/matrix/config/registrations/zooid.yaml',
+    envPath: '/abs/data/matrix/config/.env',
+  },
+} as const
+
+describe('buildRunArgs (post-floor)', () => {
+  it('no longer includes -d; container is foregrounded so the parent owns its stdio', () => {
+    const args = buildRunArgs({ ...base, engine: 'docker' })
+    expect(args).not.toContain('-d')
+    expect(args).toContain('--rm')
+    expect(args).toContain('--name')
+  })
+})
+
+describe('captureChildToFile', () => {
+  let dir: string
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), 'zooid-obs-tw-'))
+  })
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('tees stdout AND stderr of a child to the same log file in arrival order', async () => {
+    const path = join(dir, 'tuwunel.log')
+    const child = spawn(
+      process.execPath,
+      ['-e', 'process.stdout.write("alpha\\n"); process.stderr.write("beta\\n");'],
+      { stdio: ['ignore', 'pipe', 'pipe'] },
+    )
+    const done = captureChildToFile(child, path)
+    await new Promise<void>((r) => child.on('exit', () => r()))
+    await done
+    const text = await readFile(path, 'utf8')
+    expect(text).toContain('alpha')
+    expect(text).toContain('beta')
+  })
+})

package/src/observability/capture-tuwunel.ts

@@ -0,0 +1,24 @@
+import { createWriteStream } from 'node:fs'
+import { mkdir } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import type { ChildProcess } from 'node:child_process'
+
+/**
+ * Tee a child's stdout and stderr to one log file, in arrival order.
+ * Returns a promise that resolves once the file has been flushed after
+ * the child exits.
+ */
+export function captureChildToFile(
+  child: ChildProcess,
+  path: string,
+): Promise<void> {
+  return (async () => {
+    await mkdir(dirname(path), { recursive: true })
+    const stream = createWriteStream(path, { flags: 'a' })
+    if (child.stdout) child.stdout.on('data', (b: Buffer) => stream.write(b))
+    if (child.stderr) child.stderr.on('data', (b: Buffer) => stream.write(b))
+    await new Promise<void>((resolve) => {
+      child.on('exit', () => stream.end(() => resolve()))
+    })
+  })()
+}