@zooid/core 0.7.0 → 0.7.1

package/src/config.ts

@@ -1,5 +1,5 @@
 import { existsSync } from 'node:fs'
-import { join } from 'node:path'
+import { isAbsolute, join, resolve as pathResolve } from 'node:path'
 import { parse } from 'yaml'
 import type { AcpAgentSpec } from './acp-types.js'
 import { isPreset } from '@zooid/acp-client'
@@ -12,11 +12,22 @@ import type {
   HttpTransportConfig,
   MatrixBinding,
   MatrixTransportConfig,
+  MountConfig,
   TransportConfig,
   ZooidConfig,
   ZooidContainerConfig,
 } from './types.js'
 
+export interface LoadZooidConfigOptions {
+  /**
+   * Directory containing zooid.yaml. Required when any agent uses a
+   * relative `container.mounts[].host` path; resolution happens at parse
+   * time so the resulting `MountConfig` always carries an absolute host
+   * path.
+   */
+  configDir?: string
+}
+
 const AGENT_NAME_RE = /^[a-z][a-z0-9-]{0,31}$/
 const MATRIX_USER_ID_RE = /^@[A-Za-z0-9._\-=/+]+:[A-Za-z0-9.\-]+$/
 const MATRIX_USER_LOCALPART_RE = /^@[a-z0-9._=/+\-]+$/
@@ -117,6 +128,7 @@ function parseAgentContainer(
   name: string,
   raw: unknown,
   processEnv: NodeJS.ProcessEnv,
+  configDir: string | undefined,
 ): ContainerConfig {
   if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
     throw new Error(`agents.${name}.container must be a mapping`)
@@ -145,6 +157,145 @@ function parseAgentContainer(
     }
     out.env = interpolateEnv(stringEnv, processEnv, `agents.${name}.container.env`)
   }
+  if (r.mounts !== undefined) {
+    out.mounts = parseMountList(name, r.mounts, processEnv, configDir)
+  }
+  if (r.disable_mounts !== undefined) {
+    out.disable_mounts = parseDisableMounts(name, r.disable_mounts)
+  }
+  return out
+}
+
+function parseMountList(
+  agentName: string,
+  raw: unknown,
+  processEnv: NodeJS.ProcessEnv,
+  configDir: string | undefined,
+): MountConfig[] {
+  if (!Array.isArray(raw)) {
+    throw new Error(`agents.${agentName}.container.mounts must be an array`)
+  }
+  const out: MountConfig[] = []
+  const seenIds = new Set<string>()
+  for (let i = 0; i < raw.length; i++) {
+    const entry = raw[i]
+    if (typeof entry !== 'object' || entry === null || Array.isArray(entry)) {
+      throw new Error(`agents.${agentName}.container.mounts[${i}] must be a mapping`)
+    }
+    const e = entry as Record<string, unknown>
+    if (e.host === undefined) {
+      throw new Error(`agents.${agentName}.container.mounts[${i}].host is required`)
+    }
+    if (e.target === undefined) {
+      throw new Error(`agents.${agentName}.container.mounts[${i}].target is required`)
+    }
+    if (typeof e.host !== 'string' || e.host.length === 0) {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${i}].host must be a non-empty string`,
+      )
+    }
+    if (typeof e.target !== 'string' || e.target.length === 0) {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${i}].target must be a non-empty string`,
+      )
+    }
+    const mode = e.mode ?? 'rw'
+    if (mode !== 'ro' && mode !== 'rw') {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${i}].mode must be "ro" or "rw" (got ${JSON.stringify(e.mode)})`,
+      )
+    }
+    let id: string | undefined
+    if (e.id !== undefined) {
+      if (typeof e.id !== 'string' || e.id.length === 0) {
+        throw new Error(
+          `agents.${agentName}.container.mounts[${i}].id must be a non-empty string`,
+        )
+      }
+      if (e.id === 'workspace') {
+        throw new Error(
+          `agents.${agentName}.container.mounts[${i}].id: "workspace" is a reserved id (set by the workspace auto-mount). Use a different id or rely on disable_mounts to subtract.`,
+        )
+      }
+      if (seenIds.has(e.id)) {
+        throw new Error(
+          `agents.${agentName}.container.mounts: duplicate id "${e.id}"`,
+        )
+      }
+      seenIds.add(e.id)
+      id = e.id
+    }
+    let create: boolean | undefined
+    if (e.create !== undefined) {
+      if (typeof e.create !== 'boolean') {
+        throw new Error(
+          `agents.${agentName}.container.mounts[${i}].create must be a boolean`,
+        )
+      }
+      create = e.create
+    }
+    const host = resolveHostPath(
+      agentName,
+      i,
+      interpolateString(e.host, processEnv),
+      configDir,
+    )
+    const target = interpolateString(e.target, processEnv)
+    const m: MountConfig = { host, target, mode }
+    if (id !== undefined) m.id = id
+    if (create !== undefined) m.create = create
+    out.push(m)
+  }
+  return out
+}
+
+function resolveHostPath(
+  agentName: string,
+  index: number,
+  host: string,
+  configDir: string | undefined,
+): string {
+  if (host.startsWith('~/')) {
+    const home = process.env.HOME
+    if (!home) {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${index}].host: cannot expand ~ — $HOME is not set`,
+      )
+    }
+    return `${home}/${host.slice(2)}`
+  }
+  if (host === '~') {
+    const home = process.env.HOME
+    if (!home) {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${index}].host: cannot expand ~ — $HOME is not set`,
+      )
+    }
+    return home
+  }
+  if (isAbsolute(host)) return host
+  if (!configDir) {
+    throw new Error(
+      `agents.${agentName}.container.mounts[${index}]: relative host path "${host}" requires configDir (zooid.yaml directory) — pass it via loadZooidConfig(yaml, { configDir })`,
+    )
+  }
+  return pathResolve(configDir, host)
+}
+
+function parseDisableMounts(agentName: string, raw: unknown): string[] {
+  if (!Array.isArray(raw)) {
+    throw new Error(`agents.${agentName}.container.disable_mounts must be an array of strings`)
+  }
+  const out: string[] = []
+  for (let i = 0; i < raw.length; i++) {
+    const v = raw[i]
+    if (typeof v !== 'string' || v.length === 0) {
+      throw new Error(
+        `agents.${agentName}.container.disable_mounts[${i}] must be a non-empty string`,
+      )
+    }
+    out.push(v)
+  }
   return out
 }
 
@@ -439,6 +590,7 @@ function parseAgents(
   transports: Record<string, TransportConfig>,
   daemonHooks: { pre_turn?: string; post_turn?: string },
   processEnv: NodeJS.ProcessEnv,
+  configDir: string | undefined,
 ): Record<string, AgentConfig> {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
     throw new Error('agents: must be a mapping')
@@ -523,14 +675,26 @@ function parseAgents(
     let containerBlock: ContainerConfig | undefined
     if (entry.container !== undefined && entry.container !== null) {
       if (runtime === 'local') {
-        throw new Error(
-          `agents.${name}.container is only valid when runtime is 'docker' or 'podman'. ` +
-            `runtime: local spawns agents as host child processes — there is no container, ` +
-            `so 'image' is inert and 'env' would silently lie (the agent inherits the daemon's ` +
-            `full process.env regardless).`,
-        )
+        // Under runtime: local, the parser only accepts mounts/disable_mounts
+        // (which the compose layer ignores). image/env stay rejected because
+        // they would silently lie: there's no container and the host inherits
+        // the daemon's full process.env regardless.
+        if (typeof entry.container !== 'object' || entry.container === null || Array.isArray(entry.container)) {
+          throw new Error(`agents.${name}.container must be a mapping`)
+        }
+        const c = entry.container as Record<string, unknown>
+        const disallowed = Object.keys(c).filter((k) => k !== 'mounts' && k !== 'disable_mounts')
+        if (disallowed.length > 0) {
+          throw new Error(
+            `agents.${name}.container.${disallowed[0]} is only valid when runtime is 'docker' or 'podman'. ` +
+              `runtime: local spawns agents as host child processes — there is no container, ` +
+              `so 'image' is inert and 'env' would silently lie (the agent inherits the daemon's ` +
+              `full process.env regardless). 'mounts' and 'disable_mounts' are accepted under ` +
+              `runtime: local but ignored at compose time.`,
+          )
+        }
       }
-      containerBlock = parseAgentContainer(name, entry.container, processEnv)
+      containerBlock = parseAgentContainer(name, entry.container, processEnv, configDir)
     }
 
     const binding = parseTransportBinding(name, entry, transports)
@@ -568,7 +732,10 @@ function zooidHooks(raw: Record<string, unknown>): { pre_turn?: string; post_tur
   return out
 }
 
-export function loadZooidConfig(yamlText: string): ZooidConfig {
+export function loadZooidConfig(
+  yamlText: string,
+  opts: LoadZooidConfigOptions = {},
+): ZooidConfig {
   const raw = parse(yamlText) ?? {}
   if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
     throw new Error('zooid.yaml must be a YAML object')
@@ -604,7 +771,7 @@ export function loadZooidConfig(yamlText: string): ZooidConfig {
   const processEnv = process.env
   const transports = parseTransports(r.transports, processEnv)
   const hooks = zooidHooks(r)
-  const agents = parseAgents(r.agents, runtime, transports, hooks, processEnv)
+  const agents = parseAgents(r.agents, runtime, transports, hooks, processEnv, opts.configDir)
 
   const cfg: ZooidConfig = {
     runtime,

package/src/container-mounts.test.ts

@@ -0,0 +1,292 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const baseTransports = `
+transports:
+  m1:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    sender_localpart: z
+    user_namespace: '@.*:localhost'
+`
+
+const matrixAgent = (extra = ''): string => `
+  alice:
+    workdir: ./agents/alice
+    acp: { preset: claude }
+    matrix:
+      transport: m1
+      user_id: '@alice:localhost'
+      rooms: ['!r:localhost']${extra}
+`
+
+const wrap = (extra: string): string => `
+runtime: docker
+${baseTransports}
+agents:${matrixAgent(extra)}
+`
+
+describe('container.mounts — shape', () => {
+  it('parses a minimal mount with default mode rw', () => {
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: /var/run/docker.sock
+          target: /var/run/docker.sock`),
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.mounts).toEqual([
+      { host: '/var/run/docker.sock', target: '/var/run/docker.sock', mode: 'rw' },
+    ])
+  })
+
+  it('honours explicit mode: ro', () => {
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: /etc/hosts
+          target: /etc/hosts
+          mode: ro`),
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.mounts?.[0]?.mode).toBe('ro')
+  })
+
+  it('rejects mode other than ro/rw', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - host: /a
+          target: /a
+          mode: rwx`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/mode must be "ro" or "rw"/i)
+  })
+
+  it('rejects entries missing host or target', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - target: /a`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/host.*required/i)
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - host: /a`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/target.*required/i)
+  })
+
+  it('rejects duplicate user-declared ids', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - id: x
+          host: /a
+          target: /a
+        - id: x
+          host: /b
+          target: /b`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/duplicate.*id.*"x"/i)
+  })
+
+  it('rejects the reserved id "workspace" on user entries', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - id: workspace
+          host: /a
+          target: /a`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/reserved id.*workspace/i)
+  })
+})
+
+describe('container.mounts — host path resolution', () => {
+  it('keeps absolute paths verbatim', () => {
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: /var/lib/foo
+          target: /opt/foo`),
+      { configDir: '/some/where' },
+    )
+    expect(cfg.agents.alice!.container?.mounts?.[0]?.host).toBe('/var/lib/foo')
+  })
+
+  it('expands ~/... against $HOME', () => {
+    const home = process.env.HOME!
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: ~/.cache/zooid
+          target: /cache`),
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.mounts?.[0]?.host).toBe(`${home}/.cache/zooid`)
+  })
+
+  it('resolves relative paths against configDir', () => {
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: ./shared
+          target: /shared`),
+      { configDir: '/example/path' },
+    )
+    expect(cfg.agents.alice!.container?.mounts?.[0]?.host).toBe('/example/path/shared')
+  })
+
+  it('throws on relative host path when configDir is omitted', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      mounts:
+        - host: ./shared
+          target: /shared`),
+        // no configDir
+      ),
+    ).toThrow(/relative.*host.*configDir/i)
+  })
+})
+
+describe('container.mounts — ${VAR} interpolation', () => {
+  let saved: NodeJS.ProcessEnv
+  beforeEach(() => {
+    saved = { ...process.env }
+  })
+  afterEach(() => {
+    for (const k of Object.keys(process.env)) delete process.env[k]
+    Object.assign(process.env, saved)
+  })
+
+  it('expands ${VAR} in host and target', () => {
+    process.env.SHARED = '/srv/shared'
+    process.env.MOUNTPT = '/mnt/shared'
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      mounts:
+        - host: \${SHARED}
+          target: \${MOUNTPT}`),
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.mounts?.[0]).toMatchObject({
+      host: '/srv/shared',
+      target: '/mnt/shared',
+    })
+  })
+})
+
+describe('container.disable_mounts', () => {
+  it('parses a list of strings', () => {
+    const cfg = loadZooidConfig(
+      wrap(`
+    container:
+      disable_mounts: [history, workspace]`),
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.disable_mounts).toEqual(['history', 'workspace'])
+  })
+
+  it('rejects empty strings', () => {
+    expect(() =>
+      loadZooidConfig(
+        wrap(`
+    container:
+      disable_mounts: ['', 'history']`),
+        { configDir: '/tmp' },
+      ),
+    ).toThrow(/disable_mounts.*non-empty string/i)
+  })
+})
+
+describe('runtime: local + container.mounts', () => {
+  it('accepts mounts under runtime: local without error (silently ignored at compose time)', () => {
+    const cfg = loadZooidConfig(
+      `runtime: local
+${baseTransports}
+agents:
+  alice:
+    workdir: ./agents/alice
+    acp: { preset: claude }
+    matrix:
+      transport: m1
+      user_id: '@alice:localhost'
+      rooms: ['!r:localhost']
+    container:
+      mounts:
+        - host: /a
+          target: /a
+      disable_mounts: [memory]
+`,
+      { configDir: '/tmp' },
+    )
+    expect(cfg.agents.alice!.container?.mounts).toHaveLength(1)
+    expect(cfg.agents.alice!.container?.disable_mounts).toEqual(['memory'])
+  })
+})
+
+describe('post-migration shape — relative workdir + image + env interpolation', () => {
+  it('parses an opencode reviewer agent with relative workdir and ${VAR} env', () => {
+    const yaml = `
+runtime: docker
+
+transports:
+  matrix:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: \${MATRIX_AS_TOKEN}
+    hs_token: \${MATRIX_HS_TOKEN}
+    sender_localpart: zooid
+    user_namespace: '@.*:localhost'
+    port: 9099
+
+agents:
+  reviewer:
+    workdir: ./agents/reviewer
+    acp:
+      preset: opencode
+    container:
+      image: zooid-opencode-vertex:smoke
+      env:
+        GOOGLE_VERTEX_API_KEY: \${GOOGLE_VERTEX_API_KEY}
+    matrix:
+      transport: matrix
+      user_id: '@reviewer:localhost'
+      rooms:
+        - '#review:localhost'
+      trigger: mention
+`
+    process.env.MATRIX_AS_TOKEN ??= 'fixture-as'
+    process.env.MATRIX_HS_TOKEN ??= 'fixture-hs'
+    const cfg = loadZooidConfig(yaml, { configDir: '/example/path' })
+    expect(cfg.agents.reviewer!.workdir).toBe('./agents/reviewer')
+    expect(cfg.agents.reviewer!.container?.image).toBe('zooid-opencode-vertex:smoke')
+  })
+})

package/src/index.ts

@@ -6,6 +6,7 @@ export {
   findHttpTransport,
   findConfigFile,
 } from './config.js'
+export type { LoadZooidConfigOptions } from './config.js'
 export {
   AcpAgentRegistry,
   resolveAcpAgentSpec,
@@ -32,6 +33,7 @@ export type {
 export type {
   AgentConfig,
   ContainerConfig,
+  MountConfig,
   ZooidContainerConfig,
   MatrixBinding,
   HttpBinding,

package/src/types.ts

@@ -29,9 +29,26 @@ export interface Transport {
   reply(thread: ThreadRef, message: string): Promise<void> | void
 }
 
+/**
+ * One bind mount. `id` is the handle used by `disable_mounts` to subtract
+ * a zooid- or preset-declared entry; user-declared entries that omit `id`
+ * are auto-assigned `user-N`. The reserved id `workspace` is rejected on
+ * user entries.
+ */
+export interface MountConfig {
+  id?: string
+  host: string
+  target: string
+  mode: 'ro' | 'rw'
+  /** mkdir -p the host path before bind-mounting. Default false. */
+  create?: boolean
+}
+
 /**
  * Per-agent container configuration. Holds runtime-neutral container
- * concerns — image, env. Rejected at parse time when `runtime: local`.
+ * concerns — image, env, mounts. `image` / `env` are rejected at parse time
+ * when `runtime: local`; `mounts` / `disable_mounts` are accepted under
+ * `runtime: local` but ignored at compose time.
  */
 export interface ContainerConfig {
   image?: string
@@ -42,6 +59,13 @@ export interface ContainerConfig {
    * `ZOOID_*` references and `ZOOID_*` keys are rejected.
    */
   env?: Record<string, string>
+  /** User-declared mounts, layered on top of workspace + preset. */
+  mounts?: MountConfig[]
+  /**
+   * Subtractive override by mount id. Built-in ids: `workspace` plus
+   * whatever each preset declares (canonical: `memory`, `history`, `config`).
+   */
+  disable_mounts?: string[]
 }
 
 /**