@automatalabs/workflows 0.1.2 → 0.3.0

package/README.md

@@ -137,10 +137,24 @@ try {
 ```
 
 `run(prompt, options?)` accepts the seam's `RunOptions`: `schema`, `model`, `tier`, `cwd`,
-`instructions`, `label`, `toolNames` / `disallowedToolNames`, `signal`, `mcpServers`, and the
-out-of-band telemetry callbacks `onUsage` / `onModelResolved` / `onModelFallback` / `onHistory`.
-Token/cost usage is delivered via `onUsage` (it may never fire — ACP usage is experimental), never
-via the return value.
+`instructions`, `label`, `toolNames` / `disallowedToolNames`, `signal`, `mcpServers`,
+`baseInstructions` / `developerInstructions` (Codex-only), and the out-of-band telemetry callbacks
+`onUsage` / `onModelResolved` / `onModelFallback` / `onHistory`. Token/cost usage is delivered via
+`onUsage` (it may never fire — ACP usage is experimental), never via the return value.
+
+> **Codex session instructions.** When the run routes to the Codex backend, `baseInstructions`
+> **replaces** Codex's built-in base system prompt and `developerInstructions` adds developer-role
+> instructions for the session. They ride ACP `session/new` `_meta` into Codex `thread/start` and
+> are **ignored by the Claude backend** (which has no analog) — unlike `instructions`, which is
+> folded into the prompt text for either backend.
+>
+> ```ts
+> await runner.run("Cut the release.", {
+>   model: "gpt-5-codex",
+>   baseInstructions: "You are a release bot. Only touch CHANGELOG.md.",
+>   developerInstructions: "Prefer conventional-commit summaries.",
+> });
+> ```
 
 > The ACP server **process** is pooled and reused across `run()` calls; each `run()` opens and
 > closes one **session** on it. Call `dispose()` once at shutdown to tear the pool down. Pool size
@@ -208,6 +222,60 @@ testable without a live agent — pass a stub runner.
 
 ---
 
+## Listening in on the live ACP stream (events)
+
+`createAcpRunner()` returns an `AcpAgentRunner` with a **typed event bus**. Subscribe with
+`runner.on(name, listener)` to observe the live ACP stream of every run on that runner — streaming
+assistant text, tool calls, usage, permissions — without touching the `run()` return value or the
+`AgentRunner` seam.
+
+```ts
+import { createAcpRunner } from "@automatalabs/workflows";
+
+const runner = createAcpRunner();
+
+// ACP `sessionUpdate` discriminants are the event names; the listener payload is typed to each.
+runner.on("agent_message_chunk", (e) => {
+  if (e.content.type === "text") process.stdout.write(e.content.text); // stream tokens as they land
+});
+runner.on("tool_call", (e) => console.error(`[${e.label}] tool: ${e.title}`));
+runner.on("usage_update", (e) => console.error(`ctx ${e.used}/${e.size} tokens`));
+
+// One catch-all for "everything": fires for EVERY session/update, carrying the raw update.
+const off = runner.on("session_update", (e) => console.error(e.update.sessionUpdate));
+
+await runner.run("Refactor this module and run the tests.", { label: "refactor", cwd });
+off(); // on()/once() return an unsubscribe thunk; off(name, listener) and removeAllListeners() also exist
+await runner.dispose();
+```
+
+**Event names.** The ACP `sessionUpdate` discriminants verbatim — `user_message_chunk`,
+`agent_message_chunk`, `agent_thought_chunk`, `tool_call`, `tool_call_update`, `plan`,
+`plan_update`, `plan_removed`, `available_commands_update`, `current_mode_update`,
+`config_option_update`, `session_info_update`, `usage_update` — plus a few cross-cutting events:
+
+| event | payload |
+|-------|---------|
+| `session_update` | `{ update }` — catch-all for **every** update, regardless of kind |
+| `permission_request` | `{ request, outcome }` — a tool permission the runner auto-answered |
+| `raw_message` | `{ method, message }` — a vendor extension notification (e.g. Claude `_claude/sdkMessage`) |
+| `session_open` / `session_close` | a session opened / was released on a pooled connection |
+| `backend_error` | `{ backendId, error }` — a pooled backend process crashed |
+
+**Context envelope.** A pooled runner multiplexes many concurrent runs over one process, so every
+event (except `backend_error`) carries `{ sessionId, backendId, label?, runId? }` — filter by
+`label`/`runId` (from the run's `RunOptions`) to attribute an event to a specific run.
+
+**Best-effort.** Listeners are observers: a throwing listener is isolated and never breaks the run,
+the update drain, or sibling listeners.
+
+**With `runDynamicWorkflow` / `WorkflowManager`.** Construct the runner yourself, subscribe, then
+inject it: `runDynamicWorkflow(script, { runner })` or `new WorkflowManager({ agent: runner })`.
+Every `agent()` call in the script then streams through your listeners (filter by `label` to tell
+agents apart).
+
+---
+
 ## The in-script DSL
 
 The orchestration primitives are **not importable symbols**. They are **globals injected into the
@@ -310,11 +378,12 @@ parseWorkflowScript,          // parse a script's meta + body
 WorkflowManager,              // stateful / resumable run manager
 
 // ── ACP backend ──
-createAcpRunner,              // () => AcpAgentRunner (the default AgentRunner)
+createAcpRunner,              // () => AcpAgentRunner (the default AgentRunner; has .on(...) events)
 AcpAgentRunner,               // class — implements AgentRunner over ACP
 selectBackend,                // pick Claude vs Codex from a model/tier spec
 ClaudeBackend, CodexBackend,  // the concrete backends
 toJsonSchema, toStrictJsonSchema,
+TypedEventEmitter,            // the tiny typed emitter backing runner.on(...)
 
 // ── Errors ──
 WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit,
@@ -323,6 +392,9 @@ WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit,
 RunDynamicWorkflowOptions, WorkflowRunOptions, AgentOptions, ExecOptions,
 WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot,
 AcpPoolOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
+// ACP events: the runner.on(...) surface
+AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext,
+AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent,
 ```
 
 (The DSL globals — `agent`, `parallel`, `pipeline`, … — are **not** exported; they are realm

package/dist/index.d.ts

@@ -5,6 +5,8 @@ export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOpti
 export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
 export { createAcpRunner, AcpAgentRunner, selectBackend, ClaudeBackend, CodexBackend, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
 export type { AcpPoolOptions } from "@automatalabs/acp-agents";
+export { TypedEventEmitter } from "@automatalabs/acp-agents";
+export type { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "@automatalabs/acp-agents";
 export type { AgentRunner, RunOptions, AgentResult, AgentUsage } from "@automatalabs/shared-types";
 export type { JournalEntry } from "@automatalabs/shared-types";
 /** Options for {@link runDynamicWorkflow}. */

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIjF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAI/D,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACnG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIjF,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAClG,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EAAE,cAAc,EAAE,MAAM,0BAA0B,CAAC;AAM/D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AACnG,YAAY,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kGAAkG;IAClG,IAAI,CAAC,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAE5B"}

package/dist/index.js

@@ -18,6 +18,11 @@ export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit
 // ── ACP backend: the default AgentRunner implementation, backend selection, the
 //    concrete backends, the pool options, and the JSON-Schema helpers. ──
 export { createAcpRunner, AcpAgentRunner, selectBackend, ClaudeBackend, CodexBackend, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
+// ── Live ACP events: `createAcpRunner().on("tool_call", evt => …)` to listen in on the
+//    stream of a run. The event map keys are ACP `sessionUpdate` discriminants plus a few
+//    cross-cutting events; each payload carries a `{ sessionId, backendId, label?, runId? }`
+//    context envelope so a pooled runner's concurrent runs are disambiguable. ──
+export { TypedEventEmitter } from "@automatalabs/acp-agents";
 /**
  * Run a dynamic workflow script to a TERMINAL result, with the AgentRunner seam
  * defaulted to the ACP backend.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -24,9 +24,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@automatalabs/shared-types": "0.1.2",
-    "@automatalabs/workflow-engine": "0.1.2",
-    "@automatalabs/acp-agents": "0.1.2"
+    "@automatalabs/shared-types": "0.2.0",
+    "@automatalabs/workflow-engine": "0.1.3",
+    "@automatalabs/acp-agents": "0.3.0"
   },
   "scripts": {
     "build": "tsc -b",