zooid 0.6.1 → 0.7.1

package/src/bootstrap/tokens.test.ts

@@ -0,0 +1,44 @@
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { ensureTokens, readTokens } from './tokens.js'
+
+let dir: string
+beforeEach(() => {
+  dir = join(tmpdir(), `zooid-tokens-${Math.random().toString(36).slice(2)}`)
+  mkdirSync(dir, { recursive: true })
+})
+afterEach(() => rmSync(dir, { recursive: true, force: true }))
+
+describe('ensureTokens', () => {
+  it('generates two distinct hex tokens on first call and persists them', () => {
+    const envPath = join(dir, '.env')
+    const t = ensureTokens(envPath)
+    expect(t.asToken).toMatch(/^as-[0-9a-f]{32,}$/)
+    expect(t.hsToken).toMatch(/^hs-[0-9a-f]{32,}$/)
+    expect(t.asToken).not.toBe(t.hsToken)
+    const env = readFileSync(envPath, 'utf8')
+    expect(env).toContain(`MATRIX_AS_TOKEN=${t.asToken}`)
+    expect(env).toContain(`MATRIX_HS_TOKEN=${t.hsToken}`)
+  })
+
+  it('reuses tokens on subsequent calls (idempotent)', () => {
+    const envPath = join(dir, '.env')
+    const a = ensureTokens(envPath)
+    const b = ensureTokens(envPath)
+    expect(a).toEqual(b)
+  })
+
+  it('errors with a clear message if .env exists but is missing tokens', () => {
+    const envPath = join(dir, '.env')
+    writeFileSync(envPath, 'MATRIX_AS_TOKEN=as-abc\n', 'utf8')
+    expect(() => ensureTokens(envPath)).toThrow(
+      /missing MATRIX_AS_TOKEN or MATRIX_HS_TOKEN/i,
+    )
+  })
+
+  it('readTokens returns null when file does not exist', () => {
+    expect(readTokens(join(dir, 'nope.env'))).toBeNull()
+  })
+})

package/src/bootstrap/tokens.ts

@@ -0,0 +1,43 @@
+import { randomBytes } from 'node:crypto'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname } from 'node:path'
+
+export interface Tokens {
+  asToken: string
+  hsToken: string
+}
+
+const AS_RE = /^MATRIX_AS_TOKEN=(.+)$/m
+const HS_RE = /^MATRIX_HS_TOKEN=(.+)$/m
+
+function genToken(prefix: string): string {
+  return `${prefix}-${randomBytes(24).toString('hex')}`
+}
+
+export function readTokens(envPath: string): Tokens | null {
+  if (!existsSync(envPath)) return null
+  const text = readFileSync(envPath, 'utf8')
+  const as = text.match(AS_RE)?.[1]
+  const hs = text.match(HS_RE)?.[1]
+  if (!as && !hs) return null
+  if (!as || !hs) {
+    throw new Error(
+      `${envPath}: missing MATRIX_AS_TOKEN or MATRIX_HS_TOKEN. Delete the file to regenerate, or restore the missing value.`,
+    )
+  }
+  return { asToken: as, hsToken: hs }
+}
+
+export function ensureTokens(envPath: string): Tokens {
+  const existing = readTokens(envPath)
+  if (existing) return existing
+  const tokens: Tokens = { asToken: genToken('as'), hsToken: genToken('hs') }
+  mkdirSync(dirname(envPath), { recursive: true })
+  const previous = existsSync(envPath) ? readFileSync(envPath, 'utf8') : ''
+  const next =
+    previous.trimEnd() +
+    (previous ? '\n' : '') +
+    `MATRIX_AS_TOKEN=${tokens.asToken}\nMATRIX_HS_TOKEN=${tokens.hsToken}\n`
+  writeFileSync(envPath, next, { mode: 0o600 })
+  return tokens
+}

package/src/build-registry.context.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect, vi } from 'vitest'
+import { buildAcpRegistry } from './build-registry.js'
+import type { ZooidConfig } from '@zooid/core'
+
+const matrixCfg: ZooidConfig = {
+  runtime: 'local',
+  transports: {
+    mx: {
+      type: 'matrix',
+      homeserver: 'https://hs',
+      as_token: 'as',
+      hs_token: 'hs',
+      user_namespace: '@.*:hs',
+      sender_localpart: '_zooid',
+      space: 'dev',
+      port: 0,
+    },
+  },
+  agents: {
+    architect: {
+      name: 'architect',
+      workdir: '/tmp',
+      hooks: {},
+      acp: { command: 'fake', args: [] },
+      approval_timeout_ms: 0,
+      matrix: {
+        transport: 'mx',
+        user_id: '@architect:hs',
+        rooms: ['!r:hs'],
+        trigger: 'mention',
+      },
+    },
+  },
+  hooks: {},
+} as unknown as ZooidConfig
+
+describe('buildAcpRegistry — context provider wiring', () => {
+  it('attaches a Matrix-backed context provider to agents bound to a matrix transport', () => {
+    const registry = buildAcpRegistry(matrixCfg, {
+      approvals: { register: vi.fn(), on: vi.fn() } as never,
+      contextSpawnRegistry: {} as never,
+      daemonSockPath: '/tmp/zooid-test.sock',
+    })
+    expect(registry.hasContextSpawn('architect')).toBe(true)
+  })
+
+  it('does not attach a context provider to http-bound agents', () => {
+    const httpCfg = structuredClone(matrixCfg)
+    httpCfg.transports = {
+      h: { type: 'http', port: 0 } as never,
+    }
+    httpCfg.agents.architect.matrix = undefined as never
+    ;(httpCfg.agents.architect as { http?: unknown }).http = { transport: 'h' }
+    const registry = buildAcpRegistry(httpCfg, {
+      approvals: { register: vi.fn(), on: vi.fn() } as never,
+      contextSpawnRegistry: {} as never,
+      daemonSockPath: '/tmp/zooid-test.sock',
+    })
+    expect(registry.hasContextSpawn('architect')).toBe(false)
+  })
+})

package/src/build-registry.test.ts

@@ -0,0 +1,59 @@
+import { describe, it, expect } from 'vitest'
+import { LocalAcpRuntime } from '@zooid/runtime-local'
+import { DockerAcpRuntime } from '@zooid/runtime-docker'
+import type { ZooidConfig } from '@zooid/core'
+import { buildAcpRegistry } from './build-registry.js'
+
+function cfg(overrides: Partial<ZooidConfig> & Pick<ZooidConfig, 'runtime'>): ZooidConfig {
+  return {
+    runtime: overrides.runtime,
+    transports: overrides.transports ?? { 'http-local': { type: 'http', port: 8080 } },
+    agents: overrides.agents ?? {
+      a: {
+        name: 'a',
+        workdir: '.',
+        hooks: {},
+        acp: { preset: 'claude' },
+        approval_timeout_ms: 0,
+        http: { transport: 'http-local' },
+      },
+    },
+    hooks: {},
+    container: overrides.container,
+  } as ZooidConfig
+}
+
+describe('buildAcpRegistry', () => {
+  it('constructs with LocalAcpRuntime for runtime: local', () => {
+    const reg = buildAcpRegistry(cfg({ runtime: 'local' }))
+    expect((reg as unknown as { opts: { runtime: unknown } }).opts.runtime).toBeInstanceOf(LocalAcpRuntime)
+  })
+
+  it('constructs with DockerAcpRuntime (docker engine) for runtime: docker', () => {
+    const reg = buildAcpRegistry(
+      cfg({ runtime: 'docker', container: { image: 'img:latest' } }),
+    )
+    const rt = (reg as unknown as { opts: { runtime: DockerAcpRuntime } }).opts.runtime
+    expect(rt).toBeInstanceOf(DockerAcpRuntime)
+  })
+
+  it('constructs with DockerAcpRuntime (podman engine) for runtime: podman', () => {
+    const reg = buildAcpRegistry(
+      cfg({ runtime: 'podman', container: { image: 'img:latest' } }),
+    )
+    const rt = (reg as unknown as { opts: { runtime: DockerAcpRuntime } }).opts.runtime
+    expect(rt).toBeInstanceOf(DockerAcpRuntime)
+  })
+
+  it('throws if any agent has no acp block (defense in depth)', () => {
+    const c: ZooidConfig = {
+      runtime: 'local',
+      transports: { 'http-local': { type: 'http', port: 8080 } },
+      agents: {
+        a: { name: 'a', workdir: '.', hooks: {}, http: { transport: 'http-local' } } as never,
+      },
+      hooks: {},
+    }
+    expect(() => buildAcpRegistry(c)).toThrow(/agents\.a.*acp/i)
+  })
+})

package/src/build-registry.ts

@@ -0,0 +1,343 @@
+import { isAbsolute, resolve as pathResolve } from 'node:path'
+import { LocalAcpRuntime } from '@zooid/runtime-local'
+import { DockerAcpRuntime } from '@zooid/runtime-docker'
+import {
+  AcpAgentRegistry,
+  type AcpMount,
+  type AcpRuntime,
+  type AgentConfig,
+  type ApprovalCorrelator,
+  type ContextSpawnFactory,
+  type MountConfig,
+  type TapEvent,
+  type ZooidConfig,
+  type TransportContextProvider,
+} from '@zooid/core'
+import { MatrixClient, MatrixContextProvider } from '@zooid/transport-matrix'
+import { SpawnRegistry, buildContextServerSpec } from '@zooid/context-mcp'
+import { PRESETS, type PresetMount, type PresetName } from '@zooid/acp-client'
+
+export interface BuildAcpRegistryOptions {
+  /** Override the runtime selection (tests). */
+  runtime?: AcpRuntime
+  /** When set, the registry's approval handler routes through this correlator. */
+  approvals?: ApprovalCorrelator
+  /** Observability tap forwarded to each AcpClient. */
+  onTap?: (agentName: string, event: TapEvent) => void
+  /**
+   * Per-agent state root (`<dataRoot>/agents/`). When set, each AcpClient
+   * persists its `(threadId → sessionId)` map under
+   * `<agentsDir>/<agentName>/sessions.json` so threads survive daemon restarts.
+   */
+  agentsDir?: string
+  /**
+   * Per-spawn binding store for the zooid-context MCP server. When set
+   * together with `daemonSockPath`, agents bound to a transport that owns
+   * conversation context get a `contextSpawn` factory threaded into their
+   * AcpClient so `session/new mcpServers` includes the zooid-context entry.
+   */
+  contextSpawnRegistry?: SpawnRegistry
+  /** Path to the daemon's context Unix socket. Passed to the MCP server bin. */
+  daemonSockPath?: string
+  /**
+   * Directory containing zooid.yaml. Required when any agent uses the
+   * workspace auto-mount (the default under `runtime: docker | podman`):
+   * relative `agent.workdir` paths are resolved against this dir.
+   */
+  configDir?: string
+  /**
+   * Daemon data root. Each agent's preset mounts target
+   * `<dataDir>/agents/<agentName>` on the host.
+   */
+  dataDir?: string
+  /**
+   * Daemon user's `$HOME`. Sourced by the v1 preset `home` / `data` /
+   * `config` mounts. Tests inject a stub; production threads
+   * `process.env.HOME` from `start-daemon`.
+   */
+  daemonHome?: string
+  /**
+   * Sink for the per-agent "resolved image + mounts" startup log lines.
+   * Defaults to `console.log`. Tests pass a capture array.
+   */
+  log?: (line: string) => void
+}
+
+type ImageProvenance = 'agent' | 'workforce' | `preset:${PresetName}` | 'unresolved'
+
+interface ResolvedImage {
+  image: string | undefined
+  source: ImageProvenance
+}
+
+const CONTAINER_WORKDIR = '/workspace'
+
+function presetOf(agent: AgentConfig): PresetName | undefined {
+  const spec = agent.acp as { preset?: string } | undefined
+  if (spec?.preset && spec.preset in PRESETS) return spec.preset as PresetName
+  return undefined
+}
+
+function resolveAgentImage(
+  agent: AgentConfig,
+  cfg: ZooidConfig,
+): ResolvedImage {
+  if (agent.container?.image) return { image: agent.container.image, source: 'agent' }
+  if (cfg.container?.image) return { image: cfg.container.image, source: 'workforce' }
+  const preset = presetOf(agent)
+  const presetImage = preset ? PRESETS[preset]?.image : undefined
+  if (presetImage && preset) return { image: presetImage, source: `preset:${preset}` }
+  return { image: undefined, source: 'unresolved' }
+}
+
+interface ComposedMounts {
+  mounts: PresetMount[]
+  mkdirs: string[]
+  cwd: string
+}
+
+function composeAgentMounts(
+  name: string,
+  agent: AgentConfig,
+  cfg: ZooidConfig,
+  opts: BuildAcpRegistryOptions,
+): ComposedMounts {
+  if (cfg.runtime === 'local') {
+    return { mounts: [], mkdirs: [], cwd: agent.workdir }
+  }
+
+  const disabled = new Set(agent.container?.disable_mounts ?? [])
+  const knownIds = new Set<string>(['workspace'])
+  const composed: PresetMount[] = []
+  let workspaceActive = false
+
+  // Layer 1: workspace auto-mount. Skip when explicitly disabled, or when
+  // configDir is missing and the workdir is relative — the daemon path always
+  // passes configDir; tests that exercise other concerns (image resolution,
+  // env) can leave it off without the workspace mount intruding.
+  if (!disabled.has('workspace')) {
+    let host = agent.workdir
+    if (isAbsolute(host)) {
+      composed.push({
+        id: 'workspace',
+        host,
+        target: CONTAINER_WORKDIR,
+        mode: 'rw',
+        create: true,
+      })
+      workspaceActive = true
+    } else if (opts.configDir) {
+      host = pathResolve(opts.configDir, host)
+      composed.push({
+        id: 'workspace',
+        host,
+        target: CONTAINER_WORKDIR,
+        mode: 'rw',
+        create: true,
+      })
+      workspaceActive = true
+    }
+  }
+
+  // Layer 2: preset mounts.
+  const preset = presetOf(agent)
+  if (preset && PRESETS[preset]?.mounts) {
+    const dataDir = opts.dataDir ?? process.cwd()
+    const ctx = {
+      agentName: name,
+      agentDataDir: pathResolve(dataDir, 'agents', name),
+      containerWorkdir: CONTAINER_WORKDIR,
+      daemonHome: opts.daemonHome ?? process.env.HOME ?? '',
+    }
+    const presetMounts = PRESETS[preset].mounts!(ctx)
+    for (const m of presetMounts) {
+      knownIds.add(m.id)
+      if (!disabled.has(m.id)) composed.push(m)
+    }
+  }
+
+  // Validate disable_mounts ids — every entry must be either 'workspace' or a
+  // preset-declared id. Unknown ids are typos that would silently no-op.
+  for (const id of disabled) {
+    if (!knownIds.has(id)) {
+      throw new Error(
+        `agents.${name}.container.disable_mounts: unknown id "${id}". ` +
+          `Known ids for this agent: ${[...knownIds].sort().join(', ')}`,
+      )
+    }
+  }
+
+  // Layer 3: user mounts. Auto-id any without one.
+  const userMounts: MountConfig[] = agent.container?.mounts ?? []
+  let userIdx = 0
+  for (const m of userMounts) {
+    const id = m.id ?? `user-${userIdx}`
+    userIdx++
+    const out: PresetMount = {
+      id,
+      host: m.host,
+      target: m.target,
+      mode: m.mode,
+    }
+    if (m.create !== undefined) out.create = m.create
+    composed.push(out)
+  }
+
+  const mkdirs: string[] = composed
+    .filter((m) => m.create)
+    .map((m) => m.host)
+
+  return {
+    mounts: composed,
+    mkdirs,
+    cwd: workspaceActive ? CONTAINER_WORKDIR : agent.workdir,
+  }
+}
+
+/**
+ * Build an `AcpAgentRegistry` from a parsed workforce config.
+ *
+ *   - `runtime: local`   → `LocalAcpRuntime`
+ *   - `runtime: docker`  → `DockerAcpRuntime` (engine: docker)
+ *   - `runtime: podman`  → `DockerAcpRuntime` (engine: podman)
+ *
+ * Compose layers (docker/podman only): workspace auto-mount → preset-declared
+ * canonical-id mounts (filtered by `container.disable_mounts`) → user mounts.
+ * Image resolution: agent.container.image > workforce container.image >
+ * preset.image. Under `runtime: docker | podman`, throws at startup if any
+ * agent has no resolvable image.
+ */
+export function buildAcpRegistry(
+  cfg: ZooidConfig,
+  opts: BuildAcpRegistryOptions = {},
+): AcpAgentRegistry {
+  for (const [name, agent] of Object.entries(cfg.agents)) {
+    if (!agent.acp) {
+      throw new Error(`agents.${name}: missing acp block (parser should have caught this)`)
+    }
+  }
+
+  // Startup validation: every docker/podman agent must resolve to an image.
+  if (cfg.runtime !== 'local') {
+    const missing: Array<{ name: string; preset?: string }> = []
+    for (const [name, agent] of Object.entries(cfg.agents)) {
+      const { image } = resolveAgentImage(agent, cfg)
+      if (!image) {
+        missing.push({ name, preset: presetOf(agent) })
+      }
+    }
+    if (missing.length > 0) {
+      const lines = missing.map(({ name, preset }) =>
+        `  - ${name}${preset ? ` (preset: ${preset})` : ''} — no preset-default image`,
+      )
+      throw new Error(
+        `runtime: ${cfg.runtime} requires a container image for each agent. Unresolved:\n` +
+          lines.join('\n') +
+          `\nSet agents.<name>.container.image, top-level container.image, or use a ` +
+          `preset that ships a default image (claude, codex, opencode).`,
+      )
+    }
+  }
+
+  const runtime = opts.runtime ?? defaultRuntimeFor(cfg)
+  const env: Record<string, Record<string, string>> = {}
+  const image: Record<string, string | undefined> = {}
+  const mountsByAgent: Record<string, AcpMount[]> = {}
+  const mkdirByAgent: Record<string, string[]> = {}
+  const cwdByAgent: Record<string, string> = {}
+  const log = opts.log ?? ((line: string) => console.log(line))
+
+  for (const [name, agent] of Object.entries(cfg.agents)) {
+    env[name] = agent.container?.env ?? {}
+    const { image: resolvedImage, source } = resolveAgentImage(agent, cfg)
+    image[name] = resolvedImage
+    const composed = composeAgentMounts(name, agent, cfg, opts)
+    mountsByAgent[name] = composed.mounts.map((m) => ({
+      path: m.host,
+      target: m.target,
+      mode: m.mode,
+    }))
+    mkdirByAgent[name] = composed.mkdirs
+    cwdByAgent[name] = composed.cwd
+    if (resolvedImage && cfg.runtime !== 'local') {
+      const mountSummary = composed.mounts.length === 0
+        ? 'mounts=[]'
+        : `mounts=[${composed.mounts.map((m) => m.id ?? m.target).join(',')}]`
+      log(
+        `[zooid] agent ${name.padEnd(12)} image=${resolvedImage}  source=${source}  ${mountSummary}`,
+      )
+    }
+  }
+
+  const contextSpawns = buildContextSpawns(cfg, opts)
+
+  return new AcpAgentRegistry({
+    runtime,
+    agents: cfg.agents,
+    env,
+    image,
+    mounts: mountsByAgent,
+    mkdirOnSpawn: mkdirByAgent,
+    cwd: cwdByAgent,
+    approvals: opts.approvals,
+    onTap: opts.onTap,
+    agentsDir: opts.agentsDir,
+    contextSpawns,
+  })
+}
+
+function buildContextSpawns(
+  cfg: ZooidConfig,
+  opts: BuildAcpRegistryOptions,
+): Record<string, ContextSpawnFactory | undefined> | undefined {
+  if (!opts.contextSpawnRegistry || !opts.daemonSockPath) return undefined
+  const registry = opts.contextSpawnRegistry
+  const sockPath = opts.daemonSockPath
+
+  const matrixClients = new Map<string, MatrixClient>()
+  const agentBots = new Map<string, string>()
+  for (const [name, agent] of Object.entries(cfg.agents)) {
+    if (agent.matrix?.user_id) agentBots.set(agent.matrix.user_id, name)
+  }
+  for (const [tname, tcfg] of Object.entries(cfg.transports)) {
+    if (tcfg.type !== 'matrix') continue
+    matrixClients.set(
+      tname,
+      new MatrixClient({ homeserver: tcfg.homeserver, asToken: tcfg.as_token }),
+    )
+  }
+
+  const result: Record<string, ContextSpawnFactory | undefined> = {}
+  for (const [name, agent] of Object.entries(cfg.agents)) {
+    if (agent.matrix && matrixClients.has(agent.matrix.transport)) {
+      const client = matrixClients.get(agent.matrix.transport)!
+      const provider: TransportContextProvider = new MatrixContextProvider({
+        client,
+        asUserId: agent.matrix.user_id,
+        agentBots,
+      })
+      result[name] = async (threadId: string, channelId?: string) => {
+        const spawnId = registry.register({
+          agentName: name,
+          threadRef: { channelId: channelId ?? threadId, threadId },
+          provider,
+        })
+        return buildContextServerSpec({ spawnId, sockPath })
+      }
+    } else {
+      result[name] = undefined
+    }
+  }
+  return result
+}
+
+function defaultRuntimeFor(cfg: ZooidConfig): AcpRuntime {
+  if (cfg.runtime === 'local') return new LocalAcpRuntime()
+  if (cfg.runtime === 'docker') {
+    return new DockerAcpRuntime({ defaultImage: cfg.container?.image, engine: 'docker' })
+  }
+  if (cfg.runtime === 'podman') {
+    return new DockerAcpRuntime({ defaultImage: cfg.container?.image, engine: 'podman' })
+  }
+  throw new Error(`unsupported runtime: ${cfg.runtime}`)
+}

package/src/build-registry.zod043.test.ts

@@ -0,0 +1,64 @@
+import { describe, it, expect } from 'vitest'
+import { buildAcpRegistry } from './build-registry.js'
+import type { ZooidConfig } from '@zooid/core'
+
+const baseTransports = {
+  m1: {
+    type: 'matrix' as const,
+    homeserver: 'http://localhost:8448',
+    as_token: 't',
+    hs_token: 'h',
+    sender_localpart: 'z',
+    user_namespace: '@.*:localhost',
+  },
+}
+
+function makeCfg(over: Partial<ZooidConfig> = {}): ZooidConfig {
+  return {
+    runtime: 'docker',
+    container: { image: 'workforce-default:1' },
+    transports: baseTransports,
+    agents: {
+      alice: {
+        name: 'alice',
+        workdir: './alice',
+        hooks: {},
+        acp: { preset: 'claude' },
+        approval_timeout_ms: 0,
+        matrix: {
+          transport: 'm1',
+          user_id: '@alice:localhost',
+          rooms: ['!r:localhost'],
+          trigger: 'mention',
+        },
+        container: { env: { LOG_LEVEL: 'info' } },
+      },
+    },
+    hooks: {},
+    ...over,
+  }
+}
+
+describe('buildAcpRegistry — ZOD043', () => {
+  it('passes agent.container.env through as the spawn env (no forward_env layer)', () => {
+    const cfg = makeCfg()
+    const reg = buildAcpRegistry(cfg)
+    expect(reg.resolveSpawnEnv('alice')).toEqual({ LOG_LEVEL: 'info' })
+  })
+
+  it('resolves image with per-agent override beating workforce default', () => {
+    const cfg = makeCfg()
+    cfg.agents.alice!.container = {
+      ...cfg.agents.alice!.container,
+      image: 'alice:2',
+    }
+    const reg = buildAcpRegistry(cfg)
+    expect(reg.resolveSpawnImage('alice')).toBe('alice:2')
+  })
+
+  it('falls back to workforce container.image when no per-agent image', () => {
+    const cfg = makeCfg()
+    const reg = buildAcpRegistry(cfg)
+    expect(reg.resolveSpawnImage('alice')).toBe('workforce-default:1')
+  })
+})