zooid 0.6.1 → 0.7.0

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,142 @@
+import { LocalAcpRuntime } from '@zooid/runtime-local'
+import { DockerAcpRuntime } from '@zooid/runtime-docker'
+import {
+  AcpAgentRegistry,
+  type AcpRuntime,
+  type ApprovalCorrelator,
+  type ContextSpawnFactory,
+  type TapEvent,
+  type ZooidConfig,
+  type TransportContextProvider,
+} from '@zooid/core'
+import { MatrixClient, MatrixContextProvider } from '@zooid/transport-matrix'
+import { SpawnRegistry, buildContextServerSpec } from '@zooid/context-mcp'
+
+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
+}
+
+/**
+ * Build an `AcpAgentRegistry` from a parsed workforce config.
+ *
+ *   - `runtime: local`   → `LocalAcpRuntime`
+ *   - `runtime: docker`  → `DockerAcpRuntime` (engine: docker)
+ *   - `runtime: podman`  → `DockerAcpRuntime` (engine: podman)
+ *
+ * Per-agent `container.env` is passed through to each `AcpClient`'s spawn
+ * spec verbatim (interpolation happens at parse time in `@zooid/core`).
+ * The image is resolved as `agent.container?.image ?? cfg.container?.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)`)
+    }
+  }
+
+  const runtime = opts.runtime ?? defaultRuntimeFor(cfg)
+  const env: Record<string, Record<string, string>> = {}
+  const image: Record<string, string | undefined> = {}
+  for (const [name, agent] of Object.entries(cfg.agents)) {
+    env[name] = agent.container?.env ?? {}
+    image[name] = agent.container?.image ?? cfg.container?.image
+  }
+
+  const contextSpawns = buildContextSpawns(cfg, opts)
+
+  return new AcpAgentRegistry({
+    runtime,
+    agents: cfg.agents,
+    env,
+    image,
+    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
+
+  // Share one MatrixClient per matrix transport (only state is homeserver +
+  // asToken). Per-agent providers wrap that client with the agent's own
+  // user_id as asUserId — when the AS impersonates the agent (via ?user_id=)
+  // it sees the rooms that bot is a member of. The AS sender_localpart
+  // typically isn't in those rooms, so impersonating it returns empty
+  // chunks.
+  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')
+  })
+})

package/src/commands/dev-cascade.test.ts

@@ -0,0 +1,38 @@
+import { describe, expect, it, vi } from 'vitest'
+import { buildShutdown } from './dev-cascade.js'
+
+describe('buildShutdown', () => {
+  it('stops in order: ui → daemon → tuwunel and is idempotent', async () => {
+    const calls: string[] = []
+    const stopUi = vi.fn(async () => {
+      calls.push('ui')
+    })
+    const stopDaemon = vi.fn(async () => {
+      calls.push('daemon')
+    })
+    const stopTuwunel = vi.fn(async () => {
+      calls.push('tuwunel')
+    })
+
+    const shutdown = buildShutdown({ stopUi, stopDaemon, stopTuwunel })
+    await shutdown()
+    expect(calls).toEqual(['ui', 'daemon', 'tuwunel'])
+
+    await shutdown()
+    expect(stopUi).toHaveBeenCalledTimes(1)
+    expect(stopDaemon).toHaveBeenCalledTimes(1)
+    expect(stopTuwunel).toHaveBeenCalledTimes(1)
+  })
+
+  it('continues stopping later layers even if an earlier one throws', async () => {
+    const stopUi = vi.fn(async () => {
+      throw new Error('ui boom')
+    })
+    const stopDaemon = vi.fn(async () => {})
+    const stopTuwunel = vi.fn(async () => {})
+    const shutdown = buildShutdown({ stopUi, stopDaemon, stopTuwunel })
+    await shutdown()
+    expect(stopDaemon).toHaveBeenCalled()
+    expect(stopTuwunel).toHaveBeenCalled()
+  })
+})

package/src/commands/dev-cascade.ts

@@ -0,0 +1,35 @@
+export interface ShutdownLayers {
+  stopUi: () => Promise<void>
+  stopDaemon: () => Promise<void>
+  stopTuwunel: () => Promise<void>
+  stopWebWatch?: () => Promise<void>
+  /** Flush per-agent ACP taps before stopping the daemon. */
+  stopCaptures?: () => Promise<void>
+  /** Resolves once Tuwunel's captured stdio file is flushed. */
+  finalizeTuwunelCapture?: () => Promise<void>
+}
+
+export function buildShutdown(layers: ShutdownLayers): () => Promise<void> {
+  let started: Promise<void> | null = null
+  return () => {
+    if (started) return started
+    started = (async () => {
+      const order = [
+        'stopUi',
+        'stopWebWatch',
+        'stopCaptures',
+        'stopDaemon',
+        'stopTuwunel',
+        'finalizeTuwunelCapture',
+      ] as const
+      for (const step of order) {
+        try {
+          await layers[step]?.()
+        } catch (err) {
+          console.error(`${step}:`, err)
+        }
+      }
+    })()
+    return started
+  }
+}

package/src/commands/dev-data-layout.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest'
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { rmSync, existsSync } from 'node:fs'
+import { resolveDataLayout } from '../bootstrap/data-layout.js'
+import { resolvePaths } from '../bootstrap/paths.js'
+import { writeBootstrapConfigs } from '../bootstrap/configs.js'
+
+// This test exercises the *layout boundary*: given a data root, the bootstrap
+// helpers write matrix-specific files under <root>/matrix/ and never elsewhere.
+// It does not boot tuwunel.
+
+describe('dev bootstrap honours the data-root layout', () => {
+  let root: string
+  beforeEach(async () => {
+    root = await mkdtemp(join(tmpdir(), 'zooid-dev-layout-'))
+  })
+  afterEach(() => {
+    rmSync(root, { recursive: true, force: true })
+  })
+
+  it('writes tuwunel.toml + appservice.yaml under <root>/matrix/, agents/ stays empty', () => {
+    const layout = resolveDataLayout(root)
+    const paths = resolvePaths(layout.matrixDir)
+    writeBootstrapConfigs({
+      paths,
+      serverName: 'localhost',
+      asToken: 'as-token',
+      hsToken: 'hs-token',
+      senderLocalpart: 'zooid',
+      userNamespace: '@.*:localhost',
+    })
+
+    // Matrix-side files exist where expected.
+    expect(existsSync(join(root, 'matrix', 'config', 'tuwunel.toml'))).toBe(true)
+    expect(
+      existsSync(join(root, 'matrix', 'config', 'registrations', 'zooid.yaml')),
+    ).toBe(true)
+    expect(existsSync(join(root, 'matrix', 'db'))).toBe(true)
+    expect(existsSync(join(root, 'matrix', 'media'))).toBe(true)
+
+    // Crucially: nothing writes to <root>/matrix/logs or <root>/matrix/agents.
+    expect(existsSync(join(root, 'matrix', 'logs'))).toBe(false)
+    expect(existsSync(join(root, 'matrix', 'agents'))).toBe(false)
+
+    // agents/ is reserved for ZOD028 and not pre-created by bootstrap.
+    expect(existsSync(join(root, 'agents'))).toBe(false)
+  })
+
+  it('agentDir(id) resolves a deterministic path even before the dir exists', () => {
+    const layout = resolveDataLayout(root)
+    expect(layout.agentDir('docs')).toBe(join(root, 'agents', 'docs'))
+  })
+})