@zooid/core 0.7.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zooid contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,491 @@
+import { ChildProcess } from 'node:child_process';
+import { ApprovalRequest, ApprovalDecision, PromptInput, PromptResult, AgentEvent, TapEvent } from '@zooid/acp-client';
+export { TapEvent } from '@zooid/acp-client';
+import { EventEmitter } from 'node:events';
+
+/**
+ * Per-agent ACP block in zooid.yaml. XOR: either a known preset or an
+ * explicit command. The schema parser rejects both/neither.
+ *
+ * Built-in presets: `claude`, `codex`, `opencode`, `cline`, `kiro`, `gemini`.
+ * See `@zooid/acp-client`'s preset registry for the current list.
+ */
+type AcpAgentSpec = {
+    preset: string;
+    model?: string;
+    command?: never;
+    args?: never;
+} | {
+    preset?: never;
+    model?: never;
+    command: string;
+    args?: string[];
+};
+/**
+ * A single bind mount the runtime should set up for the spawned agent
+ * process. Only DockerAcpRuntime honors mounts; LocalAcpRuntime ignores them.
+ */
+interface AcpMount {
+    /** Host-side source path (absolute). */
+    path: string;
+    /** Container-side target path. */
+    target: string;
+    mode: 'ro' | 'rw';
+}
+/**
+ * What an `AcpRuntime` needs in order to launch the ACP agent process.
+ * Unlike the legacy `SpawnConfig`, this is just process-spawn shape — no
+ * adapter-specific concepts (no workspaceReadOnly, no sessionStateDir).
+ */
+interface AcpSpawnSpec {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+    cwd?: string;
+    /** Container image. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+    image?: string;
+    /** Bind mounts. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+    mounts?: AcpMount[];
+}
+/**
+ * A runtime knows how to spawn the ACP shim process (locally, or inside a
+ * container). Returns a ChildProcess whose stdio is wired up for ACP NDJSON.
+ */
+interface AcpRuntime {
+    spawn(spec: AcpSpawnSpec): ChildProcess;
+}
+
+/**
+ * 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.
+ */
+interface InboundMessage {
+    id: string;
+    text: string;
+    sender: string;
+    thread: ThreadRef;
+    isFollowUp: boolean;
+}
+interface ThreadRef {
+    channelId: string;
+    threadId: string;
+}
+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`.
+ */
+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.
+ */
+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"`.
+ */
+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.
+ */
+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`).
+ */
+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).
+ */
+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.
+ */
+interface HttpTransportConfig {
+    type: 'http';
+    /**
+     * HTTP listener port.
+     * @default 8080
+     */
+    port: number;
+}
+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.
+ */
+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;
+    };
+}
+interface CliFlags {
+    runtime?: string;
+    /** Container image override (shorthand for container.image). */
+    image?: string;
+}
+
+declare function loadZooidConfig(yamlText: string): ZooidConfig;
+declare function findTransport(cfg: ZooidConfig, name: string): TransportConfig | undefined;
+declare function findMatrixTransport(cfg: ZooidConfig): {
+    name: string;
+    transport: MatrixTransportConfig;
+} | null;
+declare function findHttpTransport(cfg: ZooidConfig): {
+    name: string;
+    transport: HttpTransportConfig;
+} | null;
+interface FoundConfigFile {
+    path: string;
+}
+declare function findConfigFile(cwd: string): FoundConfigFile | null;
+declare function mergeCliFlags(base: ZooidConfig, flags: CliFlags): ZooidConfig;
+
+interface RegisteredApproval {
+    approvalId: string;
+    agentName: string;
+    sessionId: string;
+    toolCallId: string;
+    toolKind?: string;
+    toolTitle?: string;
+    toolInput?: unknown;
+    options: ApprovalRequest['options'];
+    decisionPromise: Promise<ApprovalDecision>;
+}
+interface RegisterOptions {
+    /** Wall-clock timeout in ms. 0 = no timeout. */
+    timeoutMs?: number;
+}
+/**
+ * Correlates ACP approval requests (mid-prompt, originating in `AcpClient`)
+ * with HTTP/transport-side decisions. The transport listens to:
+ *
+ *   - `'registered'` — fires after `register()` so the transport can emit
+ *     `approval.request` on the right SSE stream.
+ *   - `'timeout'`    — fires when an entry is auto-cancelled by the timer
+ *     so the transport can emit `approval.timeout`.
+ */
+declare class ApprovalCorrelator extends EventEmitter {
+    private readonly pending;
+    private readonly bySession;
+    register(agentName: string, sessionId: string, req: ApprovalRequest, opts?: RegisterOptions): RegisteredApproval;
+    resolve(sessionId: string, approvalId: string, decision: ApprovalDecision): boolean;
+    cancelSession(sessionId: string): void;
+    listPending(sessionId: string): RegisteredApproval[];
+    size(): number;
+    private toPublic;
+}
+
+type AcpRegistryEventHandler = (agentName: string, event: AgentEvent) => void;
+type AcpRegistryApprovalHandler = (agentName: string, req: ApprovalRequest) => Promise<ApprovalDecision>;
+/**
+ * Daemon-side surface of the ACP agent fleet. The transport (HTTP) consumes
+ * this; the CLI builds it via `buildAcpRegistry`. Long-lived: one
+ * `AcpClient` per agent, kept alive across prompts.
+ */
+interface AcpRegistry {
+    hasAgent(name: string): boolean;
+    /** Whether an agent has a transport-context provider attached. */
+    hasContextSpawn(name: string): boolean;
+    /** Per-agent approval timeout from zooid.yaml. 0 means no timeout. */
+    getApprovalTimeoutMs(name: string): number;
+    ensureSession(name: string, threadId: string, channelId?: string): Promise<string>;
+    /** Drop the in-memory session for (agent, threadId). Next prompt re-creates one. */
+    endSession(name: string, threadId: string): void;
+    prompt(name: string, input: PromptInput): Promise<PromptResult>;
+    /**
+     * Cancel an in-flight prompt for (agent, sessionId). Sends `session/cancel`
+     * via the underlying AcpClient and resolves any pending approvals with
+     * `decision: 'cancel'`. Idempotent.
+     */
+    cancelSession(name: string, sessionId: string): Promise<void>;
+    stopAll(): Promise<void>;
+    /** Set by the transport. Receives every ACP event from any agent. */
+    onEvent: AcpRegistryEventHandler;
+    /** Set by the transport. Resolves permission requests. */
+    onApprovalRequest: AcpRegistryApprovalHandler;
+}
+interface AcpAgentRegistryOptions {
+    runtime: AcpRuntime;
+    agents: Record<string, AgentConfig>;
+    /** Per-agent env passed to each `AcpClient`'s spawn spec. */
+    env?: Record<string, Record<string, string>>;
+    /** Per-agent container image. Used by DockerAcpRuntime; ignored by LocalAcpRuntime. */
+    image?: Record<string, string | undefined>;
+    /** Initial event handler (the transport may overwrite at app creation). */
+    onEvent?: AcpRegistryEventHandler;
+    /** Initial approval handler (the transport may overwrite at app creation). */
+    onApprovalRequest?: AcpRegistryApprovalHandler;
+    /**
+     * Optional correlator: when set, the registry's default
+     * `onApprovalRequest` registers each request on the correlator (with the
+     * agent's `approval_timeout_ms`) and returns the registered handle's
+     * `decisionPromise`. Transports listen on the correlator's `'registered'`
+     * + `'timeout'` events to drive the SSE wire and accept HTTP decisions.
+     */
+    approvals?: ApprovalCorrelator;
+    /** Called whenever the correlator-backed handler registers an approval. */
+    onApprovalRegistered?: (approval: RegisteredApproval) => void;
+    /**
+     * Optional observability tap. Forwarded to each AcpClient so the
+     * unfiltered ACP protocol stream + turn-boundary events are visible to
+     * the host (e.g. the dev CLI capturing them to disk).
+     */
+    onTap?: (agentName: string, event: TapEvent) => void;
+    /**
+     * Root directory under which each agent gets a per-agent state dir
+     * (`<agentsDir>/<agentName>/`). Used by the AcpClient session store to
+     * persist ACP `sessionId`s across daemon restarts. Optional: when unset,
+     * session continuity across restarts is disabled.
+     */
+    agentsDir?: string;
+    /**
+     * Per-agent factory that returns a `mcpServers[]` entry for the
+     * `zooid-context` MCP server. Forwarded to each AcpClient. Agents bound to
+     * transports without a context provider (e.g. HTTP) have no entry here.
+     */
+    contextSpawns?: Record<string, ContextSpawnFactory | undefined>;
+}
+type ContextSpawnFactory = (threadId: string, channelId?: string) => Promise<{
+    name: 'zooid-context';
+    command: string;
+    args: string[];
+    env: Array<{
+        name: string;
+        value: string;
+    }>;
+}>;
+declare class AcpAgentRegistry implements AcpRegistry {
+    readonly opts: AcpAgentRegistryOptions;
+    private readonly clients;
+    onEvent: AcpRegistryEventHandler;
+    onApprovalRequest: AcpRegistryApprovalHandler;
+    constructor(opts: AcpAgentRegistryOptions);
+    hasAgent(name: string): boolean;
+    hasContextSpawn(name: string): boolean;
+    resolveSpawnEnv(name: string): Record<string, string>;
+    resolveSpawnImage(name: string): string | undefined;
+    getApprovalTimeoutMs(name: string): number;
+    ensureSession(name: string, threadId: string, channelId?: string): Promise<string>;
+    endSession(name: string, threadId: string): void;
+    cancelSession(name: string, sessionId: string): Promise<void>;
+    prompt(name: string, input: PromptInput): Promise<PromptResult>;
+    stopAll(): Promise<void>;
+    private ensureClient;
+}
+declare function resolveAcpAgentSpec(spec: AcpAgentSpec): {
+    command: string;
+    args: string[];
+};
+
+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;
+}
+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;
+}
+interface Member {
+    id: string;
+    name: string;
+    is_agent: boolean;
+    agent_name?: string;
+}
+interface ChannelInfo {
+    id: string;
+    name: string;
+    transport: 'http' | 'matrix';
+}
+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`.
+ */
+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;
+}
+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
+ */
+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>;
+}
+
+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 };