@zooid/core 0.7.0 → 0.7.1

package/dist/index.d.ts

@@ -80,9 +80,25 @@ interface Transport {
     listen(channel: string, onMessage: (msg: InboundMessage) => void): void;
     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.
+ */
+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.
  */
 interface ContainerConfig {
     image?: string;
@@ -93,6 +109,13 @@ 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[];
 }
 /**
  * Workforce-level container defaults. Currently `image` only — see
@@ -254,7 +277,16 @@ interface CliFlags {
     image?: string;
 }
 
-declare function loadZooidConfig(yamlText: string): ZooidConfig;
+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;
+}
+declare function loadZooidConfig(yamlText: string, opts?: LoadZooidConfigOptions): ZooidConfig;
 declare function findTransport(cfg: ZooidConfig, name: string): TransportConfig | undefined;
 declare function findMatrixTransport(cfg: ZooidConfig): {
     name: string;
@@ -374,6 +406,21 @@ interface AcpAgentRegistryOptions {
      * transports without a context provider (e.g. HTTP) have no entry here.
      */
     contextSpawns?: Record<string, ContextSpawnFactory | undefined>;
+    /**
+     * Per-agent resolved bind-mount list. Threaded into the AcpClient's spawn
+     * spec; honoured by the docker runtime, ignored by the local runtime.
+     */
+    mounts?: Record<string, AcpMount[]>;
+    /**
+     * Per-agent list of host directories to `mkdir -p` before the first
+     * `runtime.spawn` for that agent. Subset of mount entries with `create: true`.
+     */
+    mkdirOnSpawn?: Record<string, string[]>;
+    /**
+     * Per-agent override for the spawn-spec `cwd`. Set to e.g. `/workspace`
+     * when the workspace mount is active; falls back to `agent.workdir`.
+     */
+    cwd?: Record<string, string>;
 }
 type ContextSpawnFactory = (threadId: string, channelId?: string) => Promise<{
     name: 'zooid-context';
@@ -394,6 +441,9 @@ declare class AcpAgentRegistry implements AcpRegistry {
     hasContextSpawn(name: string): boolean;
     resolveSpawnEnv(name: string): Record<string, string>;
     resolveSpawnImage(name: string): string | undefined;
+    resolveSpawnMounts(name: string): AcpMount[];
+    resolveSpawnCwd(name: string): string;
+    agentNames(): string[];
     getApprovalTimeoutMs(name: string): number;
     ensureSession(name: string, threadId: string, channelId?: string): Promise<string>;
     endSession(name: string, threadId: string): void;
@@ -488,4 +538,4 @@ interface TransportContextProvider {
     getChannelInfo(channelId: string): Promise<ChannelInfo>;
 }
 
-export { AcpAgentRegistry, type AcpAgentRegistryOptions, type AcpAgentSpec, type AcpMount, type AcpRegistry, type AcpRegistryApprovalHandler, type AcpRegistryEventHandler, type AcpRuntime, type AcpSpawnSpec, type AgentConfig, ApprovalCorrelator, type ChannelInfo, type CliFlags, type ContainerConfig, type ContextSpawnFactory, type HistoryOptions, type HistoryPage, type HttpBinding, type HttpTransportConfig, type InboundMessage, type MatrixBinding, type MatrixTransportConfig, type Member, type Message, type RegisterOptions, type RegisteredApproval, type ThreadOverview, type ThreadOverviewPage, type ThreadRef, type Transport, type TransportConfig, type TransportContextProvider, type ZooidConfig, type ZooidContainerConfig, findConfigFile, findHttpTransport, findMatrixTransport, findTransport, loadZooidConfig, mergeCliFlags, resolveAcpAgentSpec };
+export { AcpAgentRegistry, type AcpAgentRegistryOptions, type AcpAgentSpec, type AcpMount, type AcpRegistry, type AcpRegistryApprovalHandler, type AcpRegistryEventHandler, type AcpRuntime, type AcpSpawnSpec, type AgentConfig, ApprovalCorrelator, type ChannelInfo, type CliFlags, type ContainerConfig, type ContextSpawnFactory, type HistoryOptions, type HistoryPage, type HttpBinding, type HttpTransportConfig, type InboundMessage, type LoadZooidConfigOptions, type MatrixBinding, type MatrixTransportConfig, type Member, type Message, type MountConfig, type RegisterOptions, type RegisteredApproval, type ThreadOverview, type ThreadOverviewPage, type ThreadRef, type Transport, type TransportConfig, type TransportContextProvider, type ZooidConfig, type ZooidContainerConfig, findConfigFile, findHttpTransport, findMatrixTransport, findTransport, loadZooidConfig, mergeCliFlags, resolveAcpAgentSpec };

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/config.ts
 import { existsSync } from "fs";
-import { join } from "path";
+import { isAbsolute, join, resolve as pathResolve } from "path";
 import { parse } from "yaml";
 import { isPreset } from "@zooid/acp-client";
 
@@ -142,7 +142,7 @@ function parseApprovalTimeout(name, raw) {
   }
   throw new Error("unreachable");
 }
-function parseAgentContainer(name, raw, processEnv) {
+function parseAgentContainer(name, raw, processEnv, configDir) {
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error(`agents.${name}.container must be a mapping`);
   }
@@ -170,6 +170,132 @@ function parseAgentContainer(name, raw, processEnv) {
     }
     out.env = interpolateEnv(stringEnv, processEnv, `agents.${name}.container.env`);
   }
+  if (r.mounts !== void 0) {
+    out.mounts = parseMountList(name, r.mounts, processEnv, configDir);
+  }
+  if (r.disable_mounts !== void 0) {
+    out.disable_mounts = parseDisableMounts(name, r.disable_mounts);
+  }
+  return out;
+}
+function parseMountList(agentName, raw, processEnv, configDir) {
+  if (!Array.isArray(raw)) {
+    throw new Error(`agents.${agentName}.container.mounts must be an array`);
+  }
+  const out = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  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;
+    if (e.host === void 0) {
+      throw new Error(`agents.${agentName}.container.mounts[${i}].host is required`);
+    }
+    if (e.target === void 0) {
+      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;
+    if (e.id !== void 0) {
+      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;
+    if (e.create !== void 0) {
+      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 = { host, target, mode };
+    if (id !== void 0) m.id = id;
+    if (create !== void 0) m.create = create;
+    out.push(m);
+  }
+  return out;
+}
+function resolveHostPath(agentName, index, host, configDir) {
+  if (host.startsWith("~/")) {
+    const home = process.env.HOME;
+    if (!home) {
+      throw new Error(
+        `agents.${agentName}.container.mounts[${index}].host: cannot expand ~ \u2014 $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 ~ \u2014 $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) \u2014 pass it via loadZooidConfig(yaml, { configDir })`
+    );
+  }
+  return pathResolve(configDir, host);
+}
+function parseDisableMounts(agentName, raw) {
+  if (!Array.isArray(raw)) {
+    throw new Error(`agents.${agentName}.container.disable_mounts must be an array of strings`);
+  }
+  const out = [];
+  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;
 }
 function parseZooidContainer(raw) {
@@ -419,7 +545,7 @@ function parseTransportBinding(name, entry, transports) {
   }
   return { http: { transport: refName } };
 }
-function parseAgents(raw, runtime, transports, daemonHooks, processEnv) {
+function parseAgents(raw, runtime, transports, daemonHooks, processEnv, configDir) {
   if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
     throw new Error("agents: must be a mapping");
   }
@@ -496,11 +622,18 @@ See [ZOD043].`
     let containerBlock;
     if (entry.container !== void 0 && 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 \u2014 there is no container, so 'image' is inert and 'env' would silently lie (the agent 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;
+        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 \u2014 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);
     const agentCfg = {
@@ -533,7 +666,7 @@ function zooidHooks(raw) {
   }
   return out;
 }
-function loadZooidConfig(yamlText) {
+function loadZooidConfig(yamlText, opts = {}) {
   const raw = parse(yamlText) ?? {};
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new Error("zooid.yaml must be a YAML object");
@@ -566,7 +699,7 @@ function loadZooidConfig(yamlText) {
   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 = {
     runtime,
     transports,
@@ -647,6 +780,7 @@ function mergeCliFlags(base, flags) {
 }
 
 // src/acp-registry.ts
+import { mkdirSync } from "fs";
 import { join as join2 } from "path";
 import {
   AcpClient,
@@ -689,6 +823,15 @@ var AcpAgentRegistry = class {
   resolveSpawnImage(name) {
     return this.opts.image?.[name];
   }
+  resolveSpawnMounts(name) {
+    return this.opts.mounts?.[name] ?? [];
+  }
+  resolveSpawnCwd(name) {
+    return this.opts.cwd?.[name] ?? this.opts.agents[name]?.workdir ?? process.cwd();
+  }
+  agentNames() {
+    return Object.keys(this.opts.agents);
+  }
   getApprovalTimeoutMs(name) {
     return this.opts.agents[name]?.approval_timeout_ms ?? 0;
   }
@@ -730,14 +873,18 @@ var AcpAgentRegistry = class {
     const cfg = this.opts.agents[name];
     if (!cfg.acp) throw new Error(`agents.${name}: missing acp block`);
     const spawn = resolveAcpAgentSpec(cfg.acp);
+    for (const dir of this.opts.mkdirOnSpawn?.[name] ?? []) {
+      mkdirSync(dir, { recursive: true });
+    }
     const client = new AcpClient({
       agent: {
         id: name,
         command: spawn.command,
         args: spawn.args,
         env: this.opts.env?.[name],
-        cwd: cfg.workdir,
-        image: this.opts.image?.[name]
+        cwd: this.resolveSpawnCwd(name),
+        image: this.opts.image?.[name],
+        mounts: this.resolveSpawnMounts(name)
       },
       agentDataDir: this.opts.agentsDir ? join2(this.opts.agentsDir, name) : void 0,
       runtime: this.opts.runtime,