@zooid/core 0.7.0 → 0.7.2

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
@@ -101,6 +124,27 @@ interface ContainerConfig {
 interface ZooidContainerConfig {
     image?: string;
 }
+/**
+ * A room binding for an agent. Either a bare alias (default PL) or
+ * an alias with a declared power level applied at room creation.
+ *
+ * `alias` may be an alias (`#room:server`) or a room ID (`!id:server`).
+ * Resolved to a canonical room ID by `bot-pool` at bootstrap. The
+ * declared `powerLevel` (when set) seeds the agent's entry in
+ * `m.room.power_levels.users` at room creation; the daemon never reads
+ * or modifies power levels after that — promote/demote in the UI is
+ * canonical.
+ */
+interface RoomBinding {
+    /** Room alias (typical) or room ID. */
+    alias: string;
+    /**
+     * Power level the agent should hold in this room at the moment it is
+     * created. Omitted = `users_default` (effectively 0). Not reconciled
+     * after creation.
+     */
+    powerLevel?: number;
+}
 /**
  * Matrix transport binding. Lives under `agents.<name>.matrix:` in
  * zooid.yaml. The block name (`matrix`) is the transport-kind
@@ -123,8 +167,8 @@ interface MatrixBinding {
      * profile on bootstrap. Falls back to the user_id localpart when absent.
      */
     display_name?: string;
-    /** Room IDs / aliases this agent watches. */
-    rooms: string[];
+    /** Rooms this agent watches. Each entry carries the alias/ID and an optional declared PL. */
+    rooms: RoomBinding[];
     /**
      * Routing rule. `mention` requires the bot to be tagged; `any` triggers
      * on every message.
@@ -181,7 +225,9 @@ interface AgentConfig {
 }
 /**
  * Matrix application-service transport. The CLI binds the AS HTTP listener
- * to `port` (defaults to 8080).
+ * to `port` (defaults to 9000 — the most common Matrix AS convention; see
+ * Synapse / mautrix / matrix-appservice-* projects). Must match the port in
+ * the registration YAML's `url` (read by the homeserver, not by Zooid).
  */
 interface MatrixTransportConfig {
     type: 'matrix';
@@ -207,8 +253,11 @@ interface MatrixTransportConfig {
      */
     user_namespace: string;
     /**
-     * AS HTTP listener port.
-     * @default 8080
+     * AS HTTP listener port. Must match the registration YAML's `url` port —
+     * Zooid never reads the registration, so a mismatch silently sinks every
+     * transaction (the homeserver gets connection refused; you see no error
+     * in Zooid's logs).
+     * @default 9000
      */
     port?: number;
     /**
@@ -254,7 +303,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 +432,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 +467,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 +564,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 RoomBinding, 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) {
@@ -306,6 +432,39 @@ function parseTransport(name, raw, processEnv) {
   }
   return { type: "http", port };
 }
+function parseRoomBinding(path, raw, serverName) {
+  function normalizeAlias(alias) {
+    if (alias.length === 0) {
+      throw new Error(`${path}: must be a non-empty alias`);
+    }
+    if (!MATRIX_ROOM_IDENT_RE.test(alias)) {
+      throw new Error(
+        `${path}: must start with '#' or '!' (got ${JSON.stringify(alias)})`
+      );
+    }
+    return alias.includes(":") ? alias : `${alias}:${serverName}`;
+  }
+  if (typeof raw === "string") {
+    return { alias: normalizeAlias(raw) };
+  }
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new Error(`${path}: must be a string or { alias, power_level } object`);
+  }
+  const r = raw;
+  if (typeof r.alias !== "string" || r.alias.length === 0) {
+    throw new Error(`${path}.alias: must be a non-empty string`);
+  }
+  const out = { alias: normalizeAlias(r.alias) };
+  if (r.power_level !== void 0) {
+    if (typeof r.power_level !== "number" || !Number.isInteger(r.power_level)) {
+      throw new Error(
+        `${path}.power_level: must be an integer (got ${JSON.stringify(r.power_level)})`
+      );
+    }
+    out.powerLevel = r.power_level;
+  }
+  return out;
+}
 function parseTransportBinding(name, entry, transports) {
   const present = TRANSPORT_KINDS.filter(
     (k) => entry[k] !== void 0 && entry[k] !== null
@@ -375,16 +534,8 @@ function parseTransportBinding(name, entry, transports) {
       throw new Error(`agents.${name}.matrix.rooms is required and must be a non-empty array`);
     }
     const rooms = [];
-    for (const r of block.rooms) {
-      if (typeof r !== "string" || r.length === 0) {
-        throw new Error(`agents.${name}.matrix.rooms[] must be a non-empty string`);
-      }
-      if (!MATRIX_ROOM_IDENT_RE.test(r)) {
-        throw new Error(
-          `agents.${name}.matrix.rooms[] must start with '#' or '!' (got ${JSON.stringify(r)})`
-        );
-      }
-      rooms.push(r.includes(":") ? r : `${r}:${serverName}`);
+    for (let i = 0; i < block.rooms.length; i++) {
+      rooms.push(parseRoomBinding(`agents.${name}.matrix.rooms[${i}]`, block.rooms[i], serverName));
     }
     let displayName;
     if (block.display_name !== void 0) {
@@ -419,7 +570,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 +647,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 +691,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 +724,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 +805,7 @@ function mergeCliFlags(base, flags) {
 }
 
 // src/acp-registry.ts
+import { mkdirSync } from "fs";
 import { join as join2 } from "path";
 import {
   AcpClient,
@@ -689,6 +848,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 +898,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,