@zooid/core 0.7.0

package/src/env-interpolation.ts

@@ -0,0 +1,90 @@
+import dotenvExpand from 'dotenv-expand'
+
+/**
+ * Matches compose-style env references inside a value string:
+ *   `${NAME}`, `$NAME`, `${NAME:-default}`, `${NAME-default}`,
+ *   `${NAME:+alt}`, `${NAME+alt}`.
+ *
+ * The captured group is always the referenced variable name.
+ */
+const REF_RE =
+  /\$\{([A-Za-z_][A-Za-z0-9_]*)(?::?[-+][^}]*)?\}|\$([A-Za-z_][A-Za-z0-9_]*)/g
+
+export class EnvInterpolationError extends Error {}
+
+const isDenied = (name: string): boolean =>
+  name === 'ZOOID_TOKEN' || name.startsWith('ZOOID_')
+
+/**
+ * Run compose-style interpolation over a `{ KEY: literal-or-${ref} }` map.
+ *
+ * - Rejects keys in the `ZOOID_*` namespace.
+ * - Rejects any `${ZOOID_*}` reference, including inside composed values
+ *   (e.g. `"prefix-${ZOOID_INTERNAL}"`).
+ * - Otherwise delegates to `dotenv-expand` for the actual substitution,
+ *   preserving compose semantics (missing → empty string,
+ *   `${VAR:-default}`, `${VAR-default}`, `$$` escape).
+ */
+export function interpolateEnv(
+  parsed: Record<string, string>,
+  processEnv: NodeJS.ProcessEnv,
+  scope: string,
+): Record<string, string> {
+  for (const [key, val] of Object.entries(parsed)) {
+    if (isDenied(key)) {
+      throw new EnvInterpolationError(
+        `${scope}.${key}: keys in the ZOOID_* namespace are not allowed`,
+      )
+    }
+    if (typeof val !== 'string') {
+      throw new EnvInterpolationError(
+        `${scope}.${key}: env values must be strings (got ${typeof val})`,
+      )
+    }
+    REF_RE.lastIndex = 0
+    let m: RegExpExecArray | null
+    while ((m = REF_RE.exec(val)) !== null) {
+      const ref = (m[1] ?? m[2]) as string
+      if (isDenied(ref)) {
+        throw new EnvInterpolationError(
+          `${scope}.${key}: references to ZOOID_* vars are not allowed (saw \${${ref}})`,
+        )
+      }
+    }
+  }
+  // Process each value through interpolateString. Per-key processing avoids
+  // dotenv-expand's "processEnv shadows parsed" behaviour, which would let the
+  // daemon's `LOG_LEVEL=debug` overwrite a literal `LOG_LEVEL: info` declared in
+  // zooid.yaml. References still resolve against the full processEnv.
+  const out: Record<string, string> = {}
+  for (const [key, val] of Object.entries(parsed)) {
+    out[key] = interpolateString(val, processEnv)
+  }
+  return out
+}
+
+/**
+ * Run compose-style interpolation over a single string value (e.g. a
+ * transport's `as_token`). No denylist — transports legitimately reference
+ * `ZOOID_*` tokens for the daemon itself (see [ZOD043] §Denylist note).
+ */
+export function interpolateString(
+  value: string,
+  processEnv: NodeJS.ProcessEnv,
+): string {
+  // Fast path: literals with no `$` need no expansion. Skipping the dotenv-expand
+  // call also avoids the library's "processEnv shadows parsed" merge behaviour,
+  // which can leak unrelated env vars through a sentinel key.
+  if (!value.includes('$')) return value
+  const sentinel = '__zooid_interp_v1__'
+  const env: Record<string, string> = {}
+  for (const [k, v] of Object.entries(processEnv)) {
+    if (typeof v === 'string') env[k] = v
+  }
+  delete env[sentinel]
+  const result = dotenvExpand.expand({
+    parsed: { [sentinel]: value },
+    processEnv: env,
+  })
+  return result.parsed?.[sentinel] ?? ''
+}

package/src/example-yaml.test.ts

@@ -0,0 +1,35 @@
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, it, expect } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+describe('zooid/examples/zooid-dev/zooid.yaml', () => {
+  it('parses with MATRIX_AS_TOKEN / MATRIX_HS_TOKEN set', () => {
+    const prev = {
+      MATRIX_AS_TOKEN: process.env.MATRIX_AS_TOKEN,
+      MATRIX_HS_TOKEN: process.env.MATRIX_HS_TOKEN,
+    }
+    process.env.MATRIX_AS_TOKEN = 'as-tok'
+    process.env.MATRIX_HS_TOKEN = 'hs-tok'
+    try {
+      const path = join(__dirname, '__fixtures__', 'zooid-dev.yaml')
+      const yamlText = readFileSync(path, 'utf8')
+      const cfg = loadZooidConfig(yamlText)
+      expect(cfg.runtime).toBe('local')
+      const mt = cfg.transports.matrix
+      if (mt.type !== 'matrix') throw new Error('not matrix')
+      expect(mt.sender_localpart).toBe('zooid')
+      expect(mt.user_namespace).toBe('@.*:localhost')
+      expect(cfg.agents.echo.workdir).toBe('./agents/echo')
+      expect(cfg.agents.echo.matrix?.user_id).toBe('@echo:localhost')
+    } finally {
+      if (prev.MATRIX_AS_TOKEN === undefined) delete process.env.MATRIX_AS_TOKEN
+      else process.env.MATRIX_AS_TOKEN = prev.MATRIX_AS_TOKEN
+      if (prev.MATRIX_HS_TOKEN === undefined) delete process.env.MATRIX_HS_TOKEN
+      else process.env.MATRIX_HS_TOKEN = prev.MATRIX_HS_TOKEN
+    }
+  })
+})

package/src/index.ts

@@ -0,0 +1,56 @@
+export {
+  loadZooidConfig,
+  mergeCliFlags,
+  findTransport,
+  findMatrixTransport,
+  findHttpTransport,
+  findConfigFile,
+} from './config.js'
+export {
+  AcpAgentRegistry,
+  resolveAcpAgentSpec,
+} from './acp-registry.js'
+export {
+  ApprovalCorrelator,
+  type RegisteredApproval,
+  type RegisterOptions,
+} from './approval-correlator.js'
+export type {
+  AcpRegistry,
+  AcpAgentRegistryOptions,
+  AcpRegistryEventHandler,
+  AcpRegistryApprovalHandler,
+  ContextSpawnFactory,
+} from './acp-registry.js'
+export type { TapEvent } from '@zooid/acp-client'
+export type {
+  AcpAgentSpec,
+  AcpMount,
+  AcpRuntime,
+  AcpSpawnSpec,
+} from './acp-types.js'
+export type {
+  AgentConfig,
+  ContainerConfig,
+  ZooidContainerConfig,
+  MatrixBinding,
+  HttpBinding,
+  ZooidConfig,
+  TransportConfig,
+  MatrixTransportConfig,
+  HttpTransportConfig,
+  CliFlags,
+  Transport,
+  InboundMessage,
+  ThreadRef,
+} from './types.js'
+export type {
+  HistoryOptions,
+  HistoryPage,
+  Message,
+  Member,
+  ChannelInfo,
+  ThreadOverview,
+  ThreadOverviewPage,
+  TransportContextProvider,
+} from './transport-context.js'

package/src/transport-context.test.ts

@@ -0,0 +1,34 @@
+import { describe, it, expectTypeOf } from 'vitest'
+import type {
+  TransportContextProvider,
+  HistoryPage,
+  Message,
+  Member,
+  ChannelInfo,
+  ThreadOverviewPage,
+} from './transport-context.js'
+
+describe('TransportContextProvider', () => {
+  it('declares the navigation methods with the spec shape', () => {
+    expectTypeOf<TransportContextProvider['getRoomHistory']>().parameters.toEqualTypeOf<
+      [string, { limit?: number; before?: string }]
+    >()
+    expectTypeOf<TransportContextProvider['getRoomHistory']>().returns.resolves.toEqualTypeOf<HistoryPage>()
+    expectTypeOf<TransportContextProvider['getRecentThreads']>().returns.resolves.toEqualTypeOf<ThreadOverviewPage>()
+    expectTypeOf<TransportContextProvider['getThreadHistory']>().parameters.toEqualTypeOf<
+      [string, string, { limit?: number; before?: string }]
+    >()
+    expectTypeOf<TransportContextProvider['getThreadHistory']>().returns.resolves.toEqualTypeOf<HistoryPage>()
+    expectTypeOf<TransportContextProvider['getChannelMembers']>().returns.resolves.toEqualTypeOf<Member[]>()
+    expectTypeOf<TransportContextProvider['getChannelInfo']>().returns.resolves.toEqualTypeOf<ChannelInfo>()
+  })
+
+  it('ChannelInfo.transport is the two-transport MVP union', () => {
+    expectTypeOf<ChannelInfo['transport']>().toEqualTypeOf<'http' | 'matrix'>()
+  })
+
+  it('Message and Member carry the is_agent flag', () => {
+    expectTypeOf<Message['is_agent']>().toEqualTypeOf<boolean>()
+    expectTypeOf<Member['is_agent']>().toEqualTypeOf<boolean>()
+  })
+})

package/src/transport-context.ts

@@ -0,0 +1,91 @@
+export interface HistoryOptions {
+  /** Max messages to return. Default 50, max 200 (enforced by the MCP server). */
+  limit?: number
+  /** Pagination cursor — opaque to the agent. Provider-defined shape. */
+  before?: string
+}
+
+export interface Message {
+  id: string
+  sender: string
+  text: string
+  timestamp: string
+  is_agent: boolean
+  agent_name?: string
+  /**
+   * Thread root event id when this message belongs to a thread. Absent for
+   * top-level messages. Lets agents group messages by thread or drill into
+   * a specific thread root.
+   */
+  thread_id?: string
+}
+
+export interface Member {
+  id: string
+  name: string
+  is_agent: boolean
+  agent_name?: string
+}
+
+export interface ChannelInfo {
+  id: string
+  name: string
+  transport: 'http' | 'matrix'
+}
+
+export interface HistoryPage {
+  messages: Message[]
+  next_before?: string
+  has_more: boolean
+}
+
+/**
+ * A top-level entry in a room — either a standalone message or a thread
+ * root. Lets the agent scan a room without thread-reply noise. Drill into
+ * a thread with `getThreadHistory(thread_id)` where `thread_id` is this
+ * entry's `id`.
+ */
+export interface ThreadOverview {
+  id: string
+  sender: string
+  text: string
+  timestamp: string
+  is_agent: boolean
+  agent_name?: string
+  /** Number of replies in the thread under this entry. 0 = no replies yet. */
+  reply_count: number
+  /**
+   * ISO 8601 of the latest activity in the thread (latest reply, or this
+   * entry's own timestamp when there are no replies). Useful for sorting.
+   */
+  last_activity_at: string
+}
+
+export interface ThreadOverviewPage {
+  threads: ThreadOverview[]
+  next_before?: string
+  has_more: boolean
+}
+
+/**
+ * Read-only conversation-context surface for a single transport.
+ * Implemented per-transport when the transport owns (or fronts) durable
+ * conversation context. Transports that don't (e.g. current HTTP) return
+ * `null` from `Transport.getContextProvider()`.
+ *
+ * Lets agents navigate a room the way a human does:
+ *   - `getRoomHistory`     — every message chronologically
+ *   - `getRecentThreads`   — top-level entries only (scan-the-room view)
+ *   - `getThreadHistory`   — drill into one specific thread
+ */
+export interface TransportContextProvider {
+  getRoomHistory(channelId: string, opts: HistoryOptions): Promise<HistoryPage>
+  getRecentThreads(channelId: string, opts: HistoryOptions): Promise<ThreadOverviewPage>
+  getThreadHistory(
+    channelId: string,
+    threadId: string,
+    opts: HistoryOptions,
+  ): Promise<HistoryPage>
+  getChannelMembers(channelId: string): Promise<Member[]>
+  getChannelInfo(channelId: string): Promise<ChannelInfo>
+}

package/src/types.ts

@@ -0,0 +1,213 @@
+import type { AcpAgentSpec } from './acp-types.js'
+
+/**
+ * One classified line of agent stdout. Currently unused (legacy adapter
+ * machinery is gone); kept for forward compatibility with future on-disk
+ * stream parsing.
+ */
+
+/**
+ * A Transport handles inbound messages and outbound replies. Implemented in
+ * future epics (HTTP, Slack, Zooid). Declared here so the core knows the
+ * shape downstream packages will plug in to.
+ */
+export interface InboundMessage {
+  id: string
+  text: string
+  sender: string
+  thread: ThreadRef
+  isFollowUp: boolean
+}
+
+export interface ThreadRef {
+  channelId: string
+  threadId: string
+}
+
+export interface Transport {
+  listen(channel: string, onMessage: (msg: InboundMessage) => void): void
+  reply(thread: ThreadRef, message: string): Promise<void> | void
+}
+
+/**
+ * Per-agent container configuration. Holds runtime-neutral container
+ * concerns — image, env. Rejected at parse time when `runtime: local`.
+ */
+export interface ContainerConfig {
+  image?: string
+  /**
+   * Env vars passed to the spawned agent container. Values support
+   * compose-style `${VAR}` / `${VAR:-default}` / `${VAR-default}`
+   * interpolation, resolved at parse time against the daemon's `process.env`.
+   * `ZOOID_*` references and `ZOOID_*` keys are rejected.
+   */
+  env?: Record<string, string>
+}
+
+/**
+ * Workforce-level container defaults. Currently `image` only — see
+ * [ZOD043] §Non-goals on workforce-level env.
+ */
+export interface ZooidContainerConfig {
+  image?: string
+}
+
+/**
+ * Matrix transport binding. Lives under `agents.<name>.matrix:` in
+ * zooid.yaml. The block name (`matrix`) is the transport-kind
+ * discriminator: `transports[transport].type` must equal `"matrix"`.
+ */
+export interface MatrixBinding {
+  /**
+   * Ref into `ZooidConfig.transports`. Resolved transport must have type: 'matrix'.
+   * @default if exactly one matrix transport is declared, that transport's key
+   */
+  transport: string
+  /**
+   * Full Matrix user ID for this agent's bot, e.g. `@architect:example.com`.
+   * @default `@<agent name>:<server>` — server is derived from the resolved
+   *          transport's `user_namespace`
+   */
+  user_id: string
+  /**
+   * Optional human-readable display name. Written to the agent's Matrix
+   * profile on bootstrap. Falls back to the user_id localpart when absent.
+   */
+  display_name?: string
+  /** Room IDs / aliases this agent watches. */
+  rooms: string[]
+  /**
+   * Routing rule. `mention` requires the bot to be tagged; `any` triggers
+   * on every message.
+   * @default 'mention'
+   */
+  trigger: 'mention' | 'any'
+}
+
+/**
+ * HTTP transport binding. Lives under `agents.<name>.http:` in
+ * zooid.yaml. Reserved for future HTTP-specific binding fields.
+ */
+export interface HttpBinding {
+  /** Ref into `ZooidConfig.transports`. Resolved transport must have type: 'http'. */
+  transport: string
+}
+
+/**
+ * Per-agent config inside a multi-agent zooid.yaml. Each agent has its
+ * own workspace, hooks, an ACP block describing the shim to spawn, and
+ * exactly one transport-kind block (`matrix` or `http`).
+ */
+export interface AgentConfig {
+  /**
+   * Routing name. Always the agent's key in `ZooidConfig.agents` — cannot
+   * be overridden, and a `name:` field under an agent is silently ignored.
+   * The key must match /^[a-z][a-z0-9-]{0,31}$/.
+   */
+  name: string
+  /**
+   * Host directory for the agent's workspace.
+   * @default `./agents/<name>`
+   */
+  workdir: string
+  /** Per-agent hooks. Workforce-wide hooks are merged in at load time. */
+  hooks: {
+    pre_turn?: string
+    post_turn?: string
+  }
+  /** Required: how to launch this agent's ACP shim. */
+  acp: AcpAgentSpec
+  /**
+   * Wall-clock timeout for pending permission requests, in milliseconds.
+   * 0 = no timeout. The paused agent's idle cost is negligible, so opt-in
+   * is the right shape — set this only if you're running in a
+   * scale-to-zero / serverless context where unbounded waits would hold
+   * resources.
+   * @default 0
+   */
+  approval_timeout_ms: number
+  /** Container config. Rejected at parse time when runtime: local. */
+  container?: ContainerConfig
+  /** Exactly one of matrix / http is set per agent. */
+  matrix?: MatrixBinding
+  http?: HttpBinding
+}
+
+/**
+ * Matrix application-service transport. The CLI binds the AS HTTP listener
+ * to `port` (defaults to 8080).
+ */
+export interface MatrixTransportConfig {
+  type: 'matrix'
+  homeserver: string
+  /**
+   * Application-service token. Sent on every Client-Server API call.
+   * @default value of `$MATRIX_AS_TOKEN` in the daemon's env
+   */
+  as_token: string
+  /**
+   * Homeserver-to-AS token. The homeserver presents this on push.
+   * @default value of `$MATRIX_HS_TOKEN` in the daemon's env
+   */
+  hs_token: string
+  /**
+   * Localpart of the AS sender user (the bridge bot).
+   * @default 'zooid'
+   */
+  sender_localpart: string
+  /**
+   * Regex covering all bot users, e.g. `@.*:example.com`.
+   * @default `@.*:<host>` — host derived from `homeserver`
+   */
+  user_namespace: string
+  /**
+   * AS HTTP listener port.
+   * @default 8080
+   */
+  port?: number
+  /**
+   * Workforce space localpart. Resolves to alias `#<space>:<server>`.
+   * @default 'dev'
+   */
+  space?: string
+}
+
+/**
+ * Plain HTTP API transport.
+ */
+export interface HttpTransportConfig {
+  type: 'http'
+  /**
+   * HTTP listener port.
+   * @default 8080
+   */
+  port: number
+}
+
+export type TransportConfig = MatrixTransportConfig | HttpTransportConfig
+
+/**
+ * Parsed zooid.yaml shape. Always multi-agent — `agents:` is required and
+ * must have at least one entry. At least one transport must be declared and
+ * each agent must reference one by name.
+ */
+export interface ZooidConfig {
+  runtime: 'local' | 'docker' | 'podman'
+  /** Workforce-wide container defaults. Image only — no workforce-level env. Rejected when runtime: local. */
+  container?: ZooidContainerConfig
+  /** Required. Map of operator-chosen names → transport config. At least one entry. */
+  transports: Record<string, TransportConfig>
+  /** Required. Must have at least one entry. */
+  agents: Record<string, AgentConfig>
+  /** Workforce-wide hook defaults. Merged into each agent.hooks at load time. */
+  hooks: {
+    pre_turn?: string
+    post_turn?: string
+  }
+}
+
+export interface CliFlags {
+  runtime?: string
+  /** Container image override (shorthand for container.image). */
+  image?: string
+}

package/src/zooid-config.test.ts

@@ -0,0 +1,164 @@
+import { describe, expect, it } from 'vitest'
+import { loadZooidConfig } from './config.js'
+
+const minimal = `
+runtime: docker
+
+transports:
+  matrix-local:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: as-x
+    hs_token: hs-x
+    sender_localpart: zooid
+    user_namespace: '@.*:localhost'
+
+agents:
+  assistant:
+    workdir: .
+    acp: { preset: claude }
+    matrix:
+      transport: matrix-local
+      user_id: '@assistant:localhost'
+      rooms: ['!general:localhost']
+      trigger: mention
+`
+
+describe('loadZooidConfig — new shape', () => {
+  it('parses a single-matrix-transport workforce', () => {
+    const c = loadZooidConfig(minimal)
+    expect(c.transports['matrix-local']).toMatchObject({
+      type: 'matrix',
+      homeserver: 'http://localhost:8448',
+      as_token: 'as-x',
+      hs_token: 'hs-x',
+      sender_localpart: 'zooid',
+      user_namespace: '@.*:localhost',
+    })
+    expect(c.agents.assistant!.matrix?.transport).toBe('matrix-local')
+    expect(c.agents.assistant!.matrix?.user_id).toBe('@assistant:localhost')
+  })
+
+  it('runtime defaults to docker when omitted', () => {
+    const yaml = `
+transports:
+  http-only:
+    type: http
+    port: 8080
+agents:
+  one:
+    workdir: .
+    acp: { preset: claude }
+    http:
+      transport: http-only
+`
+    expect(loadZooidConfig(yaml).runtime).toBe('docker')
+  })
+
+  it('errors when transports is empty', () => {
+    expect(() =>
+      loadZooidConfig(`
+transports: {}
+agents:
+  a:
+    workdir: .
+    acp: { preset: claude }
+    http:
+      transport: x
+`),
+    ).toThrow(/transports.*at least one/i)
+  })
+
+  it("errors when an agent's transport reference doesn't exist", () => {
+    expect(() =>
+      loadZooidConfig(`
+transports:
+  matrix-local:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: as-x
+    hs_token: hs-x
+    sender_localpart: zooid
+    user_namespace: '@.*:localhost'
+agents:
+  oops:
+    workdir: .
+    acp: { preset: claude }
+    matrix:
+      transport: ghost
+      user_id: '@oops:localhost'
+      rooms: ['!r:localhost']
+`),
+    ).toThrow(/agents\.oops\.matrix\.transport.*ghost.*not declared/i)
+  })
+
+  it('errors when a transport has an unknown type', () => {
+    expect(() =>
+      loadZooidConfig(`
+transports:
+  bad:
+    type: smtp
+agents:
+  a:
+    workdir: .
+    acp: { preset: claude }
+    http:
+      transport: bad
+`),
+    ).toThrow(/transports\.bad\.type.*matrix.*http/i)
+  })
+
+  it('errors when a matrix-typed transport is referenced from an http: block', () => {
+    expect(() =>
+      loadZooidConfig(`
+transports:
+  m:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: t
+    hs_token: h
+    sender_localpart: z
+    user_namespace: '@.*:l'
+agents:
+  one:
+    workdir: .
+    acp: { preset: claude }
+    http:
+      transport: m
+`),
+    ).toThrow(/http.*references transport.*type: matrix/i)
+  })
+
+  it('allows multiple transports of mixed types', () => {
+    const yaml = `
+transports:
+  matrix-local:
+    type: matrix
+    homeserver: http://localhost:8448
+    as_token: as-x
+    hs_token: hs-x
+    sender_localpart: zooid
+    user_namespace: '@.*:localhost'
+  http-direct:
+    type: http
+    port: 8080
+agents:
+  m:
+    workdir: .
+    acp: { preset: claude }
+    matrix:
+      transport: matrix-local
+      user_id: '@m:localhost'
+      rooms: ['!a:localhost']
+  h:
+    workdir: .
+    acp: { preset: claude }
+    http:
+      transport: http-direct
+`
+    const c = loadZooidConfig(yaml)
+    expect(Object.keys(c.transports)).toEqual(['matrix-local', 'http-direct'])
+    expect(c.agents.m!.matrix?.transport).toBe('matrix-local')
+    expect(c.agents.h!.http?.transport).toBe('http-direct')
+  })
+})