@automatalabs/acp-agents 0.1.1 → 0.2.0

package/README.md

@@ -0,0 +1,89 @@
+# @automatalabs/acp-agents
+
+Low-level building block: the [Agent Client Protocol](https://agentclientprotocol.com) (ACP) client plus Claude and Codex backends that implement the `AgentRunner` seam from `@automatalabs/shared-types`. It spawns `claude-agent-acp` / `codex-acp` as child processes, drives one subagent turn to completion over ACP, and returns structured output or text.
+
+This is the layer `@automatalabs/workflows` and `@automatalabs/mcp-server` are built on.
+
+## Most users want `@automatalabs/workflows`
+
+If you are orchestrating a workflow, use [`@automatalabs/workflows`](../workflows) instead — it re-exports `createAcpRunner` and wires it into the engine for you. Reach for this package directly only when you want to drive a **single** Claude/Codex agent over ACP yourself.
+
+```bash
+npm install @automatalabs/acp-agents
+```
+
+## Standalone use: drive one agent
+
+`createAcpRunner().run(prompt, options)` runs a single agent to completion. Pass a [typebox](https://github.com/sinclairzx81/typebox) `schema` to get a validated object back (typed as `Static<typeof schema>`); omit it to get the final assistant text as a `string`. The backend (Claude vs Codex) is selected from `model` / `tier`. Call `dispose()` when you're done to tear down the pooled child processes.
+
+```ts
+import { createAcpRunner } from "@automatalabs/acp-agents";
+import { Type } from "typebox";
+
+const runner = createAcpRunner();
+
+try {
+  // Structured output: result is typed and validated against the schema.
+  const review = await runner.run("Review the diff and summarize risk.", {
+    schema: Type.Object({
+      risk: Type.Union([Type.Literal("low"), Type.Literal("high")]),
+      summary: Type.String(),
+    }),
+    model: "anthropic/claude-sonnet-4", // routes to the Claude backend
+    cwd: "/abs/path/to/worktree",       // ACP session/new { cwd } — absolute
+  });
+  console.log(review.risk, review.summary);
+
+  // No schema: result is the final assistant text.
+  const text = await runner.run("Explain this repo in one paragraph.", {
+    model: "openai/gpt-5", // routes to the Codex backend
+    cwd: "/abs/path/to/worktree",
+  });
+  console.log(text);
+} finally {
+  await runner.dispose();
+}
+```
+
+`run()` accepts the full `RunOptions` seam: `schema`, `model`, `tier`, `cwd`, `instructions`, `label`, `signal` (cancellation), `toolNames` / `disallowedToolNames`, `mcpServers`, `onUsage`, `onModelResolved`, `onModelFallback`, and `onHistory`. See `@automatalabs/shared-types` for the field-by-field contract.
+
+## Listening in: live ACP events
+
+`AcpAgentRunner` is also a typed event bus — `runner.on(name, listener)` bubbles up the live ACP stream of every run (streaming text, tool calls, usage, permissions). Event names are the ACP `sessionUpdate` discriminants (`agent_message_chunk`, `tool_call`, `usage_update`, …) plus the cross-cutting `session_update` (catch-all), `permission_request`, `raw_message`, `session_open` / `session_close`, and `backend_error`. Each payload carries a `{ sessionId, backendId, label?, runId? }` context envelope (a pooled runner multiplexes many runs at once). `on()` / `once()` return an unsubscribe thunk; `off()` and `removeAllListeners()` round it out. Listeners are best-effort observers — a throwing listener never affects the run.
+
+```ts
+const off = runner.on("agent_message_chunk", (e) => {
+  if (e.content.type === "text") process.stdout.write(e.content.text);
+});
+runner.on("tool_call", (e) => console.error(`[${e.label}] ${e.title}`));
+// … run() …
+off();
+```
+
+The full event map (`AcpRunnerEventMap`) and helpers (`TypedEventEmitter`) are exported here and re-exported from `@automatalabs/workflows`.
+
+## Key exports
+
+From [`src/index.ts`](./src/index.ts):
+
+- **`createAcpRunner(options?)`** — factory returning an `AcpAgentRunner` (this is what `@automatalabs/workflows` injects into the engine).
+- **`AcpAgentRunner`** — the `AgentRunner` implementation; `run(prompt, options)` and `dispose()`.
+- **`selectBackend({ model, tier })`** — the cross-provider routing rule: which backend a spec maps to.
+- **`ClaudeBackend` / `CodexBackend`** — the two backend strategies (spawn config + per-backend schema wiring).
+- **`toJsonSchema(schema)` / `toStrictJsonSchema(schema)`** — turn a typebox schema into the on-the-wire shapes: a plain JSON Schema for Claude `outputFormat`, and an OpenAI-strict-normalized schema for Codex `outputSchema`.
+
+Also exported: `AcpAgentPool` / `resolvePoolSize`, `PooledConnection` / `SessionHandle`, `decidePermission`, `UsageAccumulator`, `resolveStructuredOutput` / `extractValidated` / `findJsonBlock` / `validateValue`, `errorText` / `mapThrownError`, and the event surface `TypedEventEmitter` / `AcpRunnerEventMap` / `AcpEventName` / `AcpEventListener` / `AcpEventContext` / `AcpSessionUpdate` (+ the per-event payload types), plus their associated types.
+
+## Environment overrides
+
+| Variable | Effect |
+| --- | --- |
+| `AGENTPRISM_DEFAULT_BACKEND` | Backend when `model`/`tier` don't pick one (`codex` selects Codex; anything else is Claude). |
+| `AGENTPRISM_ACP_POOL_SIZE` | Long-lived processes to keep per backend (default `1`). |
+| `AGENTPRISM_CLAUDE_ACP_CMD` / `AGENTPRISM_CLAUDE_ACP_ARGS` | Override the command (and args) used to spawn the Claude ACP server. |
+| `AGENTPRISM_CODEX_ACP_CMD` / `AGENTPRISM_CODEX_ACP_ARGS` | Override the command (and args) used to spawn the Codex ACP server. |
+| `AGENTPRISM_CODEX_ACP_BIN` | Override only the resolved Codex ACP bin path (keeps the default node launcher). |
+
+## License
+
+Apache-2.0

package/dist/acp-client.d.ts

@@ -2,6 +2,7 @@ import { ClientSideConnection, type PromptResponse, type SessionConfigOption, ty
 import type { TSchema } from "typebox";
 import { type AgentHistoryEntry, type McpServerConfig } from "@automatalabs/shared-types";
 import type { Backend, BackendId, StructuredSource } from "./backend.js";
+import { type AcpEventSink } from "./events.js";
 import { type ToolPolicy } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
 interface RawResultSuccess {
@@ -13,12 +14,16 @@ interface RawResultSuccess {
  *  and the tool policy used to auto-answer permission requests for THIS session. */
 declare class SessionState {
     readonly policy: ToolPolicy;
+    readonly label?: string | undefined;
+    readonly runId?: string | undefined;
     readonly textChunks: string[];
     readonly history: AgentHistoryEntry[];
     readonly usage: UsageAccumulator;
     rawResultSuccess: RawResultSuccess | undefined;
     private turnStartIndex;
-    constructor(policy: ToolPolicy);
+    /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
+     *  events as context — they never affect routing or the wire request. */
+    constructor(policy: ToolPolicy, label?: string | undefined, runId?: string | undefined);
     /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn. */
     beginTurn(): void;
     currentTurnText(): string;
@@ -37,10 +42,16 @@ export interface AcpSessionOptions {
     /** Engine run id, stamped onto session/new `_meta` (META_KEYS.runId) as a correlation id.
      *  Omitted => no runId `_meta` is stamped (the request `_meta` is whatever the backend set). */
     runId?: string;
+    /** `RunOptions.label`, propagated onto emitted events as context. NOT sent on the wire. */
+    label?: string;
 }
 /** Notified by a PooledConnection when its process dies, so the pool can drop it. */
 export interface PooledConnectionDeps {
     onDead(connection: PooledConnection): void;
+    /** Optional typed event sink. When present, every ACP notification / permission request /
+     *  session lifecycle change on this connection is bubbled up through it (additive observability;
+     *  it is invoked AFTER the drain accumulation and never affects the run). */
+    onEvent?: AcpEventSink;
 }
 /**
  * One long-lived ACP server subprocess + its held ACP client connection. Initialized ONCE and
@@ -55,6 +66,9 @@ export declare class PooledConnection {
     private readonly child;
     private readonly client;
     private readonly onDead;
+    private readonly onEvent;
+    /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
+    private disposing;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
     private readonly ready;
     /** Resolves when the process dies; `race()` turns it into a thrown, descriptive error. */

package/dist/acp-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acp-client.d.ts","sourceRoot":"","sources":["../src/acp-client.ts"],"names":[],"mappings":"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"}

package/dist/acp-client.js

@@ -24,6 +24,7 @@ import { spawn } from "node:child_process";
 import { Readable, Writable } from "node:stream";
 import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
 import { META_KEYS } from "@automatalabs/shared-types";
+import { emitSessionUpdate } from "./events.js";
 import { decidePermission } from "./permissions.js";
 import { UsageAccumulator } from "./usage.js";
 /** A benign client identity. NOT JetBrains/IntelliJ 2026.1 — that exact identity makes
@@ -42,13 +43,19 @@ const DISPOSE_SIGKILL_GRACE_MS = 2_000;
  *  and the tool policy used to auto-answer permission requests for THIS session. */
 class SessionState {
     policy;
+    label;
+    runId;
     textChunks = [];
     history = [];
     usage = new UsageAccumulator();
     rawResultSuccess;
     turnStartIndex = 0;
-    constructor(policy) {
+    /** `label`/`runId` are carried here ONLY so the MultiplexClient can stamp them onto emitted
+     *  events as context — they never affect routing or the wire request. */
+    constructor(policy, label, runId) {
         this.policy = policy;
+        this.label = label;
+        this.runId = runId;
     }
     /** Mark the start of a new turn so currentTurnText()/structured_output read only this turn. */
     beginTurn() {
@@ -103,22 +110,48 @@ class SessionState {
  *  permission request to the per-session SessionState by `sessionId`, so one process can serve
  *  many concurrent sessions without their streams crossing. */
 class MultiplexClient {
+    backendId;
+    onEvent;
     sessions = new Map();
+    /** `backendId` stamps event context; `onEvent` (optional) bubbles every notification, permission
+     *  request and session lifecycle change up to the runner's typed bus. */
+    constructor(backendId, onEvent) {
+        this.backendId = backendId;
+        this.onEvent = onEvent;
+    }
+    contextFor(sessionId, state) {
+        return { sessionId, backendId: this.backendId, label: state?.label, runId: state?.runId };
+    }
     register(sessionId, state) {
         this.sessions.set(sessionId, state);
+        this.onEvent?.("session_open", this.contextFor(sessionId, state));
     }
     unregister(sessionId) {
+        const state = this.sessions.get(sessionId);
         this.sessions.delete(sessionId);
+        if (state)
+            this.onEvent?.("session_close", this.contextFor(sessionId, state));
     }
     requestPermission(params) {
         const state = this.sessions.get(params.sessionId);
         // Unknown/closed session: refuse rather than silently allow a tool we can't attribute.
         if (!state)
             return { outcome: { outcome: "cancelled" } };
-        return decidePermission(params, state.policy);
+        const outcome = decidePermission(params, state.policy);
+        this.onEvent?.("permission_request", {
+            ...this.contextFor(params.sessionId, state),
+            request: params,
+            outcome,
+        });
+        return outcome;
     }
     sessionUpdate(params) {
-        this.sessions.get(params.sessionId)?.applyUpdate(params.update);
+        const state = this.sessions.get(params.sessionId);
+        // Fold into the accumulator FIRST (the drain contract), THEN bubble the event up unchanged.
+        state?.applyUpdate(params.update);
+        if (this.onEvent) {
+            emitSessionUpdate(this.onEvent, params.update, this.contextFor(params.sessionId, state));
+        }
     }
     extNotification(method, params) {
         if (method !== CLAUDE_RAW_MESSAGE_METHOD)
@@ -128,8 +161,14 @@ class MultiplexClient {
         const sessionId = typeof params.sessionId === "string" ? params.sessionId : undefined;
         if (!sessionId)
             return;
-        const message = params.message;
-        this.sessions.get(sessionId)?.applyRawMessage(message);
+        const rawMessage = params.message;
+        const state = this.sessions.get(sessionId);
+        state?.applyRawMessage(rawMessage);
+        this.onEvent?.("raw_message", {
+            ...this.contextFor(sessionId, state),
+            method,
+            message: rawMessage,
+        });
     }
 }
 /** Merge the engine runId correlation stamp into a backend's session/new `_meta`. Returns the
@@ -162,8 +201,11 @@ export class PooledConnection {
     rpc;
     backend;
     child;
-    client = new MultiplexClient();
+    client;
     onDead;
+    onEvent;
+    /** Set true at the start of dispose() so the graceful-shutdown death is NOT reported as a crash. */
+    disposing = false;
     /** Resolves once `initialize` completed (or rejects if the process died first). */
     ready;
     /** Resolves when the process dies; `race()` turns it into a thrown, descriptive error. */
@@ -178,6 +220,8 @@ export class PooledConnection {
         this.backend = backend;
         this.backendId = backend.id;
         this.onDead = deps.onDead;
+        this.onEvent = deps.onEvent;
+        this.client = new MultiplexClient(this.backendId, this.onEvent);
         const { command, args, env } = backend.spawnConfig();
         // NOTE: deliberately NO `cwd` here. cwd is per-SESSION (session/new), so one pooled process
         // serves runs in different worktrees without losing isolation.
@@ -232,6 +276,11 @@ export class PooledConnection {
         this._alive = false;
         this.deathError = error;
         this.resolveDead();
+        // A crash (not a graceful dispose) is worth surfacing for observability; the engine still
+        // handles it by retrying the run on a fresh process. Best-effort, after death is recorded.
+        if (this.onEvent && !this.disposing) {
+            this.onEvent("backend_error", { backendId: this.backendId, error });
+        }
         this.onDead(this);
     }
     stderrSuffix() {
@@ -266,7 +315,7 @@ export class PooledConnection {
         this._activeSessions += 1;
         try {
             await this.ready;
-            const state = new SessionState(opts.policy);
+            const state = new SessionState(opts.policy, opts.label, opts.runId);
             // The backend's vendor `_meta` (Claude schema channel; undefined for Codex) plus the
             // optional engine runId correlation stamp. When neither is present, no `_meta` is sent.
             const meta = stampRunId(this.backend.sessionMeta(opts.schema), opts.runId);
@@ -329,6 +378,8 @@ export class PooledConnection {
     async dispose() {
         if (!this._alive)
             return;
+        // Mark graceful shutdown so the imminent process-exit `die()` does not emit `backend_error`.
+        this.disposing = true;
         const exited = new Promise((resolve) => {
             this.child.once("exit", () => resolve());
         });

package/dist/events.d.ts

@@ -0,0 +1,93 @@
+import type { RequestPermissionRequest, RequestPermissionResponse, SessionNotification } from "@agentclientprotocol/sdk";
+import type { BackendId } from "./backend.js";
+/** The ACP session/update discriminated union (every real-time update an agent can stream). */
+export type AcpSessionUpdate = SessionNotification["update"];
+/** The `sessionUpdate` discriminant strings (agent_message_chunk | tool_call | usage_update | …). */
+export type AcpUpdateKind = AcpSessionUpdate["sessionUpdate"];
+/** Which run / session / backend an event belongs to. A pooled runner multiplexes many concurrent
+ *  sessions over one process, so every event carries this envelope for disambiguation/filtering. */
+export interface AcpEventContext {
+    /** ACP session id this event pertains to. */
+    sessionId: string;
+    /** Backend that produced it ("claude" | "codex"). */
+    backendId: BackendId;
+    /** `RunOptions.label` of the originating run(), if one was set. */
+    label?: string;
+    /** `RunOptions.runId` correlation id, if one was set. */
+    runId?: string;
+}
+/** Per-discriminant events: key = ACP `sessionUpdate` string, payload = that variant + context. */
+type AcpSessionUpdateEvents = {
+    [K in AcpUpdateKind]: Extract<AcpSessionUpdate, {
+        sessionUpdate: K;
+    }> & AcpEventContext;
+};
+/** A tool-permission request the runner auto-answered, paired with the decision it returned. */
+export interface AcpPermissionEvent extends AcpEventContext {
+    request: RequestPermissionRequest;
+    outcome: RequestPermissionResponse;
+}
+/** A vendor extension notification (e.g. Claude `_claude/sdkMessage`) routed to a session. */
+export interface AcpRawMessageEvent extends AcpEventContext {
+    method: string;
+    message: unknown;
+}
+/** A pooled backend process crashed (not a graceful dispose). The engine retries the run on a
+ *  fresh process; this surfaces the crash for observability. Carries no session context. */
+export interface AcpBackendErrorEvent {
+    backendId: BackendId;
+    error: Error;
+}
+/**
+ * The full typed event map for AcpAgentRunner — every ACP `session/update` kind, plus the
+ * cross-cutting events. The keys are exactly the strings you pass to `runner.on(...)`, and the
+ * value is the payload your listener receives.
+ */
+export type AcpRunnerEventMap = AcpSessionUpdateEvents & {
+    /** Catch-all: fires for EVERY session/update regardless of kind (carries the raw update). */
+    session_update: {
+        update: AcpSessionUpdate;
+    } & AcpEventContext;
+    /** A permission request the runner auto-answered, with the decision returned. */
+    permission_request: AcpPermissionEvent;
+    /** A vendor extension notification arrived for a session. */
+    raw_message: AcpRawMessageEvent;
+    /** A new session was opened on a pooled connection. */
+    session_open: AcpEventContext;
+    /** A session was released / closed. */
+    session_close: AcpEventContext;
+    /** A pooled backend process crashed (not a graceful dispose). */
+    backend_error: AcpBackendErrorEvent;
+};
+export type AcpEventName = keyof AcpRunnerEventMap;
+export type AcpEventListener<K extends AcpEventName> = (event: AcpRunnerEventMap[K]) => void;
+/** Internal emit boundary handed from the runner down through the pool to each connection. */
+export interface AcpEventSink {
+    <K extends AcpEventName>(name: K, event: AcpRunnerEventMap[K]): void;
+}
+/**
+ * A tiny strongly-typed event emitter (no node:events, zero deps). `on()`/`once()` return an
+ * unsubscribe thunk. `emit()` ISOLATES listener exceptions — one bad listener can never break the
+ * run, the synchronous drain, or sibling listeners — mirroring the best-effort contract of
+ * onUsage/onHistory. Generic over any event map `{ name: payload }`.
+ */
+export declare class TypedEventEmitter<EventMap> {
+    private readonly listeners;
+    /** Subscribe to `name`. Returns an unsubscribe thunk (calling it is equivalent to `off`). */
+    on<K extends keyof EventMap>(name: K, listener: (event: EventMap[K]) => void): () => void;
+    /** Subscribe once: the listener auto-unsubscribes after its first delivery. */
+    once<K extends keyof EventMap>(name: K, listener: (event: EventMap[K]) => void): () => void;
+    off<K extends keyof EventMap>(name: K, listener: (event: EventMap[K]) => void): void;
+    removeAllListeners(name?: keyof EventMap): void;
+    listenerCount(name: keyof EventMap): number;
+    emit<K extends keyof EventMap>(name: K, event: EventMap[K]): void;
+}
+/**
+ * Fan ONE ACP session/update out to the typed bus: the `session_update` catch-all first, then the
+ * per-discriminant event. The payload IS the update variant merged with `ctx`, but TS cannot
+ * correlate the runtime discriminant `name` with the mapped payload type at the call site, so the
+ * (name, payload) pair is asserted once here against the precise indexed type — never `any`.
+ */
+export declare function emitSessionUpdate(emit: AcpEventSink, update: AcpSessionUpdate, ctx: AcpEventContext): void;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"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"}

package/dist/events.js

@@ -0,0 +1,69 @@
+/**
+ * A tiny strongly-typed event emitter (no node:events, zero deps). `on()`/`once()` return an
+ * unsubscribe thunk. `emit()` ISOLATES listener exceptions — one bad listener can never break the
+ * run, the synchronous drain, or sibling listeners — mirroring the best-effort contract of
+ * onUsage/onHistory. Generic over any event map `{ name: payload }`.
+ */
+export class TypedEventEmitter {
+    listeners = new Map();
+    /** Subscribe to `name`. Returns an unsubscribe thunk (calling it is equivalent to `off`). */
+    on(name, listener) {
+        let set = this.listeners.get(name);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(name, set);
+        }
+        set.add(listener);
+        return () => this.off(name, listener);
+    }
+    /** Subscribe once: the listener auto-unsubscribes after its first delivery. */
+    once(name, listener) {
+        const off = this.on(name, (event) => {
+            off();
+            listener(event);
+        });
+        return off;
+    }
+    off(name, listener) {
+        const set = this.listeners.get(name);
+        if (!set)
+            return;
+        set.delete(listener);
+        if (set.size === 0)
+            this.listeners.delete(name);
+    }
+    removeAllListeners(name) {
+        if (name === undefined)
+            this.listeners.clear();
+        else
+            this.listeners.delete(name);
+    }
+    listenerCount(name) {
+        return this.listeners.get(name)?.size ?? 0;
+    }
+    emit(name, event) {
+        const set = this.listeners.get(name);
+        if (!set || set.size === 0)
+            return;
+        // Snapshot so a listener that (un)subscribes during dispatch can't perturb this emit.
+        for (const listener of [...set]) {
+            try {
+                listener(event);
+            }
+            catch {
+                // Listeners are observers — never let one break the run or sibling listeners.
+            }
+        }
+    }
+}
+/**
+ * Fan ONE ACP session/update out to the typed bus: the `session_update` catch-all first, then the
+ * per-discriminant event. The payload IS the update variant merged with `ctx`, but TS cannot
+ * correlate the runtime discriminant `name` with the mapped payload type at the call site, so the
+ * (name, payload) pair is asserted once here against the precise indexed type — never `any`.
+ */
+export function emitSessionUpdate(emit, update, ctx) {
+    emit("session_update", { update, ...ctx });
+    const name = update.sessionUpdate;
+    emit(name, { ...update, ...ctx });
+}

package/dist/index.d.ts

@@ -2,7 +2,9 @@ export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
 export type { AcpSessionOptions, PooledConnectionDeps } from "./acp-client.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
-export type { AcpPoolOptions } from "./pool.js";
+export type { AcpPoolOptions, AcpPoolDeps } from "./pool.js";
+export { TypedEventEmitter, emitSessionUpdate } from "./events.js";
+export type { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpEventSink, AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "./events.js";
 export type { Backend, BackendId, SpawnConfig, StructuredSource } from "./backend.js";
 export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEhD,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAClE,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC1D,YAAY,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACnE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,YAAY,EAAE,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACtF,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EACL,gBAAgB,EAChB,aAAa,EACb,uBAAuB,EACvB,aAAa,GACd,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAEhF,OAAO,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -7,6 +7,8 @@
 export { AcpAgentRunner, createAcpRunner, selectBackend } from "./runner.js";
 export { PooledConnection, SessionHandle } from "./acp-client.js";
 export { AcpAgentPool, resolvePoolSize } from "./pool.js";
+// The typed ACP event bus surfaced on AcpAgentRunner (`runner.on(name, evt => …)`).
+export { TypedEventEmitter, emitSessionUpdate } from "./events.js";
 export { ClaudeBackend } from "./backends/claude.js";
 export { CodexBackend } from "./backends/codex.js";
 export { decidePermission } from "./permissions.js";

package/dist/pool.d.ts

@@ -1,18 +1,25 @@
 import type { Backend } from "./backend.js";
 import { SessionHandle, type AcpSessionOptions } from "./acp-client.js";
+import type { AcpEventSink } from "./events.js";
 export interface AcpPoolOptions {
     /** Long-lived processes to keep PER backend. Default 1; falls back to AGENTPRISM_ACP_POOL_SIZE. */
     size?: number;
 }
+/** Internal wiring the runner injects (NOT part of the public AcpPoolOptions surface): the typed
+ *  event sink forwarded to every PooledConnection so ACP events bubble up to `runner.on(...)`. */
+export interface AcpPoolDeps {
+    onEvent?: AcpEventSink;
+}
 /** Resolve the per-backend pool size: explicit option wins, else env, else 1. Clamped to >= 1. */
 export declare function resolvePoolSize(option?: number): number;
 export declare class AcpAgentPool {
+    private readonly deps;
     private readonly size;
     private readonly byBackend;
     private readonly onProcessExit;
     private exitHookInstalled;
     private disposed;
-    constructor(options?: AcpPoolOptions);
+    constructor(options?: AcpPoolOptions, deps?: AcpPoolDeps);
     /** Acquire a session for one agent() run: get/grow a pooled connection and open a session. */
     acquire(backend: Backend, opts: AcpSessionOptions): Promise<SessionHandle>;
     /**

package/dist/pool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAoB,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAK1F,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAEb,OAAO,GAAE,cAAmB;IAIxC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAoBxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}
+{"version":3,"file":"pool.d.ts","sourceRoot":"","sources":["../src/pool.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,OAAO,EAAa,MAAM,cAAc,CAAC;AACvD,OAAO,EAAoB,aAAa,EAAE,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,MAAM,WAAW,cAAc;IAC7B,mGAAmG;IACnG,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;kGACkG;AAClG,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC;CACxB;AAED,kGAAkG;AAClG,wBAAgB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAUvD;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,QAAQ,CAAC,IAAI;IARvB,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAC9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,aAAa,CAA4B;IAC1D,OAAO,CAAC,iBAAiB,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAS;gBAGvB,OAAO,GAAE,cAAmB,EACX,IAAI,GAAE,WAAgB;IAKzC,8FAA8F;IACxF,OAAO,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC;IAMhF;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAqBxB,OAAO,CAAC,cAAc;IAStB,+DAA+D;IAC/D,OAAO,CAAC,IAAI;IAOZ,iEAAiE;IAC3D,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ9B,OAAO,CAAC,cAAc;IAMtB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,cAAc;IAMtB,gGAAgG;IAChG,OAAO,CAAC,WAAW;CAGpB"}

package/dist/pool.js

@@ -15,12 +15,14 @@ export function resolvePoolSize(option) {
     return DEFAULT_POOL_SIZE;
 }
 export class AcpAgentPool {
+    deps;
     size;
     byBackend = new Map();
     onProcessExit = () => this.killAllSync();
     exitHookInstalled = false;
     disposed = false;
-    constructor(options = {}) {
+    constructor(options = {}, deps = {}) {
+        this.deps = deps;
         this.size = resolvePoolSize(options.size);
     }
     /** Acquire a session for one agent() run: get/grow a pooled connection and open a session. */
@@ -45,6 +47,7 @@ export class AcpAgentPool {
             this.installExitHook();
             const connection = PooledConnection.create(backend, {
                 onDead: (dead) => this.drop(backend.id, dead),
+                onEvent: this.deps.onEvent,
             });
             connections.push(connection);
             return connection;

package/dist/runner.d.ts

@@ -1,10 +1,30 @@
 import { type AgentResult, type AgentRunner, type RunOptions } from "@automatalabs/shared-types";
 import type { TSchema } from "typebox";
 import { type AcpPoolOptions } from "./pool.js";
+import { type AcpEventListener, type AcpEventName } from "./events.js";
 import type { Backend } from "./backend.js";
 export declare class AcpAgentRunner implements AgentRunner {
     private readonly pool;
+    /** Typed bus carrying every ACP event from every pooled session. Beyond the AgentRunner seam
+     *  (additive observability) — subscribing never affects a run and never enters the resume hash. */
+    private readonly events;
+    private readonly emitEvent;
     constructor(options?: AcpPoolOptions);
+    /**
+     * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
+     * ("agent_message_chunk", "tool_call", "usage_update", …) or one of the cross-cutting events
+     * ("session_update" catch-all, "permission_request", "raw_message", "session_open",
+     * "session_close", "backend_error"). The listener is typed to the event. Returns an unsubscribe
+     * thunk. A pooled runner multiplexes many concurrent runs, so each event carries
+     * `{ sessionId, backendId, label?, runId? }` for filtering. Listeners are best-effort observers:
+     * a throwing listener is isolated and never affects the run.
+     */
+    on<K extends AcpEventName>(name: K, listener: AcpEventListener<K>): () => void;
+    /** Subscribe once; the listener auto-unsubscribes after its first delivery. */
+    once<K extends AcpEventName>(name: K, listener: AcpEventListener<K>): () => void;
+    off<K extends AcpEventName>(name: K, listener: AcpEventListener<K>): void;
+    removeAllListeners(name?: AcpEventName): void;
+    listenerCount(name: AcpEventName): number;
     run<S extends TSchema | undefined = undefined>(prompt: string, options?: RunOptions<S>): Promise<AgentResult<S>>;
     /** Tear down the whole pool (close every long-lived process). Call when the run ends / the
      *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */

package/dist/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAS5C,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;gBAExB,OAAO,GAAE,cAAmB;IAIlC,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAiF1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAG/B;AAED;;qEAEqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAExE;AAoED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAG9E"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../src/runner.ts"],"names":[],"mappings":"AAkBA,OAAO,EAGL,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,UAAU,EAChB,MAAM,4BAA4B,CAAC;AAEpC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAEvC,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,WAAW,CAAC;AAC9D,OAAO,EAEL,KAAK,gBAAgB,EACrB,KAAK,YAAY,EAGlB,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAS5C,qBAAa,cAAe,YAAW,WAAW;IAChD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAe;IACpC;uGACmG;IACnG,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8C;IACrE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgE;gBAE9E,OAAO,GAAE,cAAmB;IAIxC;;;;;;;;OAQG;IACH,EAAE,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAI9E,+EAA+E;IAC/E,IAAI,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI;IAIhF,GAAG,CAAC,CAAC,SAAS,YAAY,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,gBAAgB,CAAC,CAAC,CAAC,GAAG,IAAI;IAIzE,kBAAkB,CAAC,IAAI,CAAC,EAAE,YAAY,GAAG,IAAI;IAI7C,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM;IAInC,GAAG,CAAC,CAAC,SAAS,OAAO,GAAG,SAAS,GAAG,SAAS,EACjD,MAAM,EAAE,MAAM,EACd,OAAO,GAAE,UAAU,CAAC,CAAC,CAAM,GAC1B,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAmF1B;qGACiG;IAC3F,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CAI/B;AAED;;qEAEqE;AACrE,wBAAgB,eAAe,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,cAAc,CAExE;AAoED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,IAAI,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAG9E"}

package/dist/runner.js

@@ -18,14 +18,44 @@
 // and re-throw on abort, but never implement our own timeout.
 import { WorkflowError, WorkflowErrorCode, } from "@automatalabs/shared-types";
 import { AcpAgentPool } from "./pool.js";
+import { TypedEventEmitter, } from "./events.js";
 import { ClaudeBackend } from "./backends/claude.js";
 import { CodexBackend } from "./backends/codex.js";
 import { mapThrownError } from "./errors-map.js";
 import { resolveStructuredOutput } from "./structured-output.js";
 export class AcpAgentRunner {
     pool;
+    /** Typed bus carrying every ACP event from every pooled session. Beyond the AgentRunner seam
+     *  (additive observability) — subscribing never affects a run and never enters the resume hash. */
+    events = new TypedEventEmitter();
+    emitEvent = (name, event) => this.events.emit(name, event);
     constructor(options = {}) {
-        this.pool = new AcpAgentPool(options);
+        this.pool = new AcpAgentPool(options, { onEvent: this.emitEvent });
+    }
+    /**
+     * Listen in on the live ACP stream. `name` is an ACP `sessionUpdate` discriminant
+     * ("agent_message_chunk", "tool_call", "usage_update", …) or one of the cross-cutting events
+     * ("session_update" catch-all, "permission_request", "raw_message", "session_open",
+     * "session_close", "backend_error"). The listener is typed to the event. Returns an unsubscribe
+     * thunk. A pooled runner multiplexes many concurrent runs, so each event carries
+     * `{ sessionId, backendId, label?, runId? }` for filtering. Listeners are best-effort observers:
+     * a throwing listener is isolated and never affects the run.
+     */
+    on(name, listener) {
+        return this.events.on(name, listener);
+    }
+    /** Subscribe once; the listener auto-unsubscribes after its first delivery. */
+    once(name, listener) {
+        return this.events.once(name, listener);
+    }
+    off(name, listener) {
+        this.events.off(name, listener);
+    }
+    removeAllListeners(name) {
+        this.events.removeAllListeners(name);
+    }
+    listenerCount(name) {
+        return this.events.listenerCount(name);
     }
     async run(prompt, options = {}) {
         const opts = options;
@@ -41,6 +71,8 @@ export class AcpAgentRunner {
             mcpServers: opts.mcpServers,
             // Engine correlation id -> session/new _meta (META_KEYS.runId). Additive; never hashed.
             runId: opts.runId,
+            // Stamped onto emitted ACP events as context (never sent on the wire).
+            label: opts.label,
         });
         try {
             opts.signal?.throwIfAborted();
@@ -113,6 +145,7 @@ export class AcpAgentRunner {
      *  runner is disposed. Beyond the AgentRunner seam (additive) — never enters the resume hash. */
     async dispose() {
         await this.pool.dispose();
+        this.events.removeAllListeners();
     }
 }
 /** Factory the mcp-server composition root calls to inject the runner into the engine. The pool

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/acp-agents",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -28,7 +28,7 @@
     "@agentclientprotocol/claude-agent-acp": "0.53.0",
     "@automatalabs/codex-acp": "1.0.2",
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.1.1"
+    "@automatalabs/shared-types": "0.1.2"
   },
   "scripts": {
     "build": "tsc -b",