zooid 0.7.0 → 0.7.2

package/src/commands/init/generators.ts

@@ -35,6 +35,11 @@ You are the zooid setup assistant. Your job is to help the operator get a workfo
 - Zooid documentation: https://zooid.dev/docs/
 - Use your web fetch tool to read documentation pages when answering questions.
 
+## Stack facts
+
+- **Tuwunel** is a lightweight Rust Matrix homeserver (Conduit fork) backed by RocksDB. Single binary, low resource floor — not "heavy" for typical workforces.
+- **Logs land on disk** in \`./data/\` inside this zooid home dir: tuwunel logs, the daemon, and each agent's ACP stream. Use \`zooid logs <source>\` to tail them (sources: \`tuwunel\`, \`daemon\`, \`dev\`, \`agent-<name>\`, \`agent-<name>.acp\`). Debugging is mostly "read the log file" — don't tell the operator it's opaque.
+
 ## Behavior
 
 - Be terse. Give the answer; link to the doc page; stop.

package/src/commands/status.ts

@@ -1,4 +1,5 @@
 import { readFileSync } from 'node:fs'
+import { dirname } from 'node:path'
 import chalk from 'chalk'
 import { findConfigFile, findMatrixTransport, loadZooidConfig } from '@zooid/core'
 import { deriveHomeserverShape } from '../bootstrap/derive.js'
@@ -43,7 +44,9 @@ export async function collectStatus(opts: {
       agents: [],
     }
   }
-  const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'))
+  const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'), {
+    configDir: dirname(found.path),
+  })
   const matrixEntry = Object.entries(cfg.transports).find(
     ([, t]) => t.type === 'matrix',
   ) as [string, { port?: number }] | undefined
@@ -73,7 +76,9 @@ export async function runStatus(flags: StatusFlags): Promise<void> {
   if (port === undefined) {
     const found = findConfigFile(cwd)
     if (found) {
-      const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'))
+      const cfg = loadZooidConfig(readFileSync(found.path, 'utf8'), {
+        configDir: dirname(found.path),
+      })
       const matrix = findMatrixTransport(cfg)
       if (matrix) {
         const userIds = Object.values(cfg.agents)

package/src/daemon/start-daemon.ts

@@ -18,6 +18,7 @@ import { createApp } from '@zooid/transport-http'
 import {
   MatrixClient,
   createMatrixTransport,
+  ensureDefaultChannel,
   ensureWorkforceSpace,
   startWorkforcePublisher,
   type AgentBinding,
@@ -29,6 +30,7 @@ import {
   type DaemonSocketHandle,
 } from '@zooid/context-mcp'
 import { buildAcpRegistry } from '../build-registry.js'
+import { prepullImages } from '../prepull-images.js'
 
 export interface StartDaemonOpts {
   configPath?: string
@@ -45,6 +47,17 @@ export interface StartDaemonOpts {
    * daemon restarts.
    */
   agentsDir?: string
+  /** Skip the startup image-prepull pass entirely. */
+  noPrepull?: boolean
+  /** Force a re-pull of every resolved image at startup (no inspect check). */
+  refreshImages?: boolean
+  /**
+   * Per-line progress hook for the image-prepull pass. Called once per
+   * top-level summary plus once per image (start + completion). Used by
+   * `zooid dev` to surface pull progress under the "Start daemon" listr
+   * task instead of leaving the user staring at an unmoving spinner.
+   */
+  prepullLog?: (line: string) => void
 }
 
 export interface DaemonHandle {
@@ -75,7 +88,8 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
   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 configDir = dirname(found.path)
+  const base = loadZooidConfig(readFileSync(found.path, 'utf8'), { configDir })
   const config = mergeCliFlags(base, opts.cliFlags ?? {})
 
   const approvals = new ApprovalCorrelator()
@@ -95,15 +109,29 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     console.warn('[context] daemon socket startup failed; zooid-context MCP disabled:', err)
   }
 
+  const dataDir = opts.agentsDir ? dirname(opts.agentsDir) : undefined
   const registry = buildAcpRegistry(config, {
     approvals,
     onTap: opts.onTap,
     agentsDir: opts.agentsDir,
     contextSpawnRegistry: contextSocket ? contextSpawnRegistry : undefined,
     daemonSockPath: contextSocket ? daemonSockPath : undefined,
+    configDir,
+    dataDir,
+    daemonHome: process.env.HOME,
   })
   const agentNames = Object.keys(config.agents)
 
+  if (config.runtime !== 'local') {
+    await prepullImages(registry, {
+      engine: config.runtime === 'podman' ? 'podman' : 'docker',
+      runtime: config.runtime,
+      skip: opts.noPrepull ?? process.env.ZOOID_NO_PREPULL === '1',
+      refresh: opts.refreshImages ?? process.env.ZOOID_REFRESH_IMAGES === '1',
+      log: opts.prepullLog,
+    })
+  }
+
   console.log(
     `[context] socket=${daemonSockPath} ` +
       `status=${contextSocket ? 'listening' : 'disabled'} ` +
@@ -147,7 +175,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       hsToken: matrix.transport.hs_token,
       adminUserId: opts.adminUserId,
     })
-    const requestedPort = matrix.transport.port ?? 8080
+    const requestedPort = matrix.transport.port ?? 9000
     // 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>.
@@ -162,6 +190,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
       new URL(matrix.transport.homeserver).hostname
     const asUserId = `@${matrix.transport.sender_localpart}:${serverName}`
     const spaceLocalpart = matrix.transport.space ?? 'dev'
+    const adminUserIds = opts.adminUserId ? [opts.adminUserId] : []
     let spaceRoomId: string | undefined
     try {
       spaceRoomId = await ensureWorkforceSpace({
@@ -170,6 +199,7 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
         serverName,
         spaceLocalpart,
         preset: 'public_chat',
+        admins: adminUserIds,
       })
       console.log(`[matrix] ensured workforce space #${spaceLocalpart}:${serverName} → ${spaceRoomId}`)
     } catch (err) {
@@ -182,9 +212,21 @@ export async function startDaemon(opts: StartDaemonOpts = {}): Promise<DaemonHan
     // 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 })
+    await transport.bootstrap({ spaceRoomId, asUserId, adminUserIds })
 
     if (spaceRoomId) {
+      try {
+        const generalRoomId = await ensureDefaultChannel({
+          client,
+          asUserId,
+          serverName,
+          spaceId: spaceRoomId,
+          admins: adminUserIds,
+        })
+        console.log(`[matrix] ensured default channel #general:${serverName} → ${generalRoomId}`)
+      } catch (err) {
+        console.warn('[matrix] default channel provisioning failed:', err)
+      }
       try {
         const publisher: PublisherHandle = await startWorkforcePublisher({
           client,

package/src/prepull-images.test.ts

@@ -0,0 +1,149 @@
+import { describe, it, expect, vi } from 'vitest'
+import { prepullImages } from './prepull-images.js'
+
+type Call = { argv: string[] }
+
+function mkExec(
+  plan: Record<
+    string,
+    { inspectExit: number; pullExit?: number; pullStderr?: string }
+  >,
+) {
+  const calls: Call[] = []
+  const exec = vi.fn(async (cmd: string, args: string[]) => {
+    calls.push({ argv: [cmd, ...args] })
+    const op = args[0] === 'image' ? 'inspect' : 'pull'
+    const image = op === 'inspect' ? args[2] : args[1]
+    const entry = plan[image!]
+    if (!entry) throw new Error(`unexpected image: ${image}`)
+    if (op === 'inspect') {
+      return { code: entry.inspectExit, stdout: '', stderr: '' }
+    }
+    return { code: entry.pullExit ?? 0, stdout: '', stderr: entry.pullStderr ?? '' }
+  })
+  return { exec, calls }
+}
+
+const mkRegistry = (imagesByAgent: Record<string, string | undefined>) => ({
+  resolveSpawnImage: (n: string) => imagesByAgent[n],
+  agentNames: () => Object.keys(imagesByAgent),
+})
+
+describe('prepullImages', () => {
+  it('skips locally cached images (inspect exit 0)', async () => {
+    const { exec, calls } = mkExec({
+      'ghcr.io/zooid-ai/agent-claude:latest': { inspectExit: 0 },
+    })
+    const lines: string[] = []
+    await prepullImages(
+      mkRegistry({ alice: 'ghcr.io/zooid-ai/agent-claude:latest' }) as any,
+      {
+        engine: 'docker',
+        runtime: 'docker',
+        exec,
+        log: (l) => lines.push(l),
+      },
+    )
+    expect(calls.filter((c) => c.argv.includes('pull'))).toHaveLength(0)
+    expect(lines.some((l) => /1 unique images \(1 cached, 0 to pull\)/.test(l))).toBe(
+      true,
+    )
+  })
+
+  it('pulls only missing images (inspect exit non-zero → pull)', async () => {
+    const { exec, calls } = mkExec({
+      'cached:1': { inspectExit: 0 },
+      'missing:1': { inspectExit: 1, pullExit: 0 },
+    })
+    const lines: string[] = []
+    await prepullImages(
+      mkRegistry({ a: 'cached:1', b: 'missing:1' }) as any,
+      { engine: 'docker', runtime: 'docker', exec, log: (l) => lines.push(l) },
+    )
+    const pulls = calls.filter((c) => c.argv.includes('pull')).map((c) => c.argv[2])
+    expect(pulls).toEqual(['missing:1'])
+    expect(lines.some((l) => /1 cached, 1 to pull/.test(l))).toBe(true)
+    expect(lines.some((l) => /missing:1.*✓/.test(l))).toBe(true)
+  })
+
+  it('dedupes by image — five agents on the same image pull once', async () => {
+    const { exec, calls } = mkExec({
+      'shared:1': { inspectExit: 1, pullExit: 0 },
+    })
+    await prepullImages(
+      mkRegistry({
+        a: 'shared:1',
+        b: 'shared:1',
+        c: 'shared:1',
+        d: 'shared:1',
+        e: 'shared:1',
+      }) as any,
+      { engine: 'docker', runtime: 'docker', exec, log: () => {} },
+    )
+    expect(calls.filter((c) => c.argv.includes('pull'))).toHaveLength(1)
+  })
+
+  it('refresh=true skips the inspect check and pulls every image', async () => {
+    const { exec, calls } = mkExec({
+      'a:1': { inspectExit: 0, pullExit: 0 },
+      'b:1': { inspectExit: 0, pullExit: 0 },
+    })
+    await prepullImages(mkRegistry({ x: 'a:1', y: 'b:1' }) as any, {
+      engine: 'docker',
+      runtime: 'docker',
+      exec,
+      refresh: true,
+      log: () => {},
+    })
+    expect(calls.filter((c) => c.argv.includes('inspect'))).toHaveLength(0)
+    expect(calls.filter((c) => c.argv.includes('pull'))).toHaveLength(2)
+  })
+
+  it('fail-fast: pull exit non-zero throws with engine stderr embedded', async () => {
+    const { exec } = mkExec({
+      'broken:1': { inspectExit: 1, pullExit: 1, pullStderr: 'manifest unknown' },
+    })
+    await expect(
+      prepullImages(mkRegistry({ a: 'broken:1' }) as any, {
+        engine: 'docker',
+        runtime: 'docker',
+        exec,
+        log: () => {},
+      }),
+    ).rejects.toThrow(/broken:1[\s\S]*manifest unknown/)
+  })
+
+  it('skip=true is a no-op (returns immediately, no exec calls)', async () => {
+    const { exec, calls } = mkExec({})
+    await prepullImages(mkRegistry({ a: 'whatever:1' }) as any, {
+      engine: 'docker',
+      runtime: 'docker',
+      exec,
+      skip: true,
+      log: () => {},
+    })
+    expect(calls).toHaveLength(0)
+  })
+
+  it('runtime: local is a no-op regardless of opts', async () => {
+    const { exec, calls } = mkExec({})
+    await prepullImages(mkRegistry({ a: 'whatever:1' }) as any, {
+      engine: 'docker',
+      runtime: 'local',
+      exec,
+      log: () => {},
+    })
+    expect(calls).toHaveLength(0)
+  })
+
+  it('uses the configured engine (podman) in argv', async () => {
+    const { exec, calls } = mkExec({ 'x:1': { inspectExit: 1, pullExit: 0 } })
+    await prepullImages(mkRegistry({ a: 'x:1' }) as any, {
+      engine: 'podman',
+      runtime: 'podman',
+      exec,
+      log: () => {},
+    })
+    expect(calls.every((c) => c.argv[0] === 'podman')).toBe(true)
+  })
+})

package/src/prepull-images.ts

@@ -0,0 +1,100 @@
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const pExecFile = promisify(execFile)
+
+export interface PrepullExec {
+  (cmd: string, args: string[]): Promise<{ code: number; stdout: string; stderr: string }>
+}
+
+export interface PrepullOptions {
+  engine: 'docker' | 'podman'
+  runtime: 'local' | 'docker' | 'podman'
+  /** Injectable for tests. Defaults to a child_process.execFile-backed exec. */
+  exec?: PrepullExec
+  /** When true, skip the inspect check and pull every image. */
+  refresh?: boolean
+  /** When true, the function returns immediately without touching the engine. */
+  skip?: boolean
+  log?: (line: string) => void
+}
+
+export interface PrepullableRegistry {
+  agentNames(): string[]
+  resolveSpawnImage(name: string): string | undefined
+}
+
+/**
+ * Walk the registry's unique resolved-image set, `<engine> image inspect`
+ * each one, and `<engine> pull` the ones not cached locally. Parallel and
+ * fail-fast: any pull exit ≠ 0 throws with the engine's stderr embedded.
+ * No-op when `opts.skip` or `opts.runtime === 'local'`.
+ */
+export async function prepullImages(
+  registry: PrepullableRegistry,
+  opts: PrepullOptions,
+): Promise<void> {
+  if (opts.skip || opts.runtime === 'local') return
+  const exec = opts.exec ?? defaultExec
+  const log = opts.log ?? ((l: string) => console.log(l))
+
+  const images = new Set<string>()
+  for (const name of registry.agentNames()) {
+    const img = registry.resolveSpawnImage(name)
+    if (img) images.add(img)
+  }
+
+  const toPull: string[] = []
+  let cached = 0
+  if (opts.refresh) {
+    toPull.push(...images)
+  } else {
+    await Promise.all(
+      [...images].map(async (img) => {
+        const r = await exec(opts.engine, ['image', 'inspect', img])
+        if (r.code === 0) cached++
+        else toPull.push(img)
+      }),
+    )
+  }
+
+  log(
+    `[zooid] image prepull: ${images.size} unique images (${cached} cached, ${toPull.length} to pull)`,
+  )
+  if (toPull.length === 0) return
+
+  await Promise.all(
+    toPull.map(async (img) => {
+      log(`[zooid]   ${img}  pulling…`)
+      const start = Date.now()
+      const r = await exec(opts.engine, ['pull', img])
+      const secs = ((Date.now() - start) / 1000).toFixed(1)
+      if (r.code !== 0) {
+        throw new Error(
+          `image prepull failed for ${img}:\n${r.stderr.trim() || '(no stderr)'}`,
+        )
+      }
+      log(`[zooid]   ${img}  ✓ ${secs}s`)
+    }),
+  )
+}
+
+const defaultExec: PrepullExec = async (cmd, args) => {
+  try {
+    const { stdout, stderr } = await pExecFile(cmd, args, {
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    return { code: 0, stdout, stderr }
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException & {
+      code?: number | string
+      stdout?: string
+      stderr?: string
+    }
+    return {
+      code: typeof e.code === 'number' ? e.code : 1,
+      stdout: e.stdout ?? '',
+      stderr: e.stderr ?? String(e),
+    }
+  }
+}