@automatalabs/workflows 0.6.2 → 0.8.0

package/README.md

@@ -214,6 +214,18 @@ above. `WorkflowManagerOptions` lets you set a default `agent`, `concurrency`, `
 `loadSavedWorkflow` resolver (enables nested `workflow('name')`), and per-agent timeout/retry
 defaults.
 
+Manager events are Node `EventEmitter` notifications: `agentStart`, `agentEnd`, `agentHistory`,
+`tokenUsage`, `log`, `phase`, `complete`, `paused`, `resumed`, `stopped`, `error`, and
+`agentEvent`. `agentEvent` forwards the live ACP stream from an ACP-capable runner with `name`,
+`event`, and the runner context fields (`runId`, `label`, `sessionId`, `backendId`) when the event
+carries them; `backend_error` is connection-scoped and carries `backendId` only. ACP
+`session/update` traffic is emitted once under its inner discriminant name, while
+permission/session/raw/backend events keep their runner names.
+
+```ts
+manager.on("agentEvent", ({ runId, label, name }) => console.error(runId, label, name));
+```
+
 ### d) Bring your own backend — implement the `AgentRunner` seam
 
 `AgentRunner` is the single, frozen coupling point between the engine and any backend. Implement
@@ -283,9 +295,10 @@ await runner.dispose();
 | event | payload |
 |-------|---------|
 | `session_update` | `{ update }` — catch-all for **every** update, regardless of kind |
-| `permission_request` | `{ request, outcome }` — a tool permission the runner auto-answered |
+| `permission_pending` | `{ request }` — resolver-only; emitted after the request is parked and before the resolver is invoked |
+| `permission_request` | `{ request, outcome }` — the final permission outcome returned to the agent |
 | `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 |
+| `session_open` / `session_close` | an ACP session opened / was released |
 | `backend_error` | `{ backendId, error }` — a pooled backend process crashed |
 
 **Context envelope.** A pooled runner multiplexes many concurrent runs over one process, so every
@@ -295,10 +308,11 @@ event (except `backend_error`) carries `{ sessionId, backendId, label?, runId? }
 **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).
+**With `runDynamicWorkflow` / `WorkflowManager`.** Subscribe at the manager layer:
+`manager.on("agentEvent", ({ runId, label, name, event }) => …)`. Every `agent()` call in the
+script then streams live ACP events through the manager; ACP `session/update` traffic is forwarded
+once under `name = event.sessionUpdate`, so hosts do not receive both the catch-all and the
+per-discriminant runner event.
 
 ---
 
@@ -406,21 +420,30 @@ WorkflowManager,              // stateful / resumable run manager
 // ── ACP backend ──
 createAcpRunner,              // () => AcpAgentRunner (the default AgentRunner; has .on(...) events)
 AcpAgentRunner,               // class — implements AgentRunner over ACP
+InteractiveSession,           // held-open multi-turn ACP session returned by openSession()
 selectBackend,                // pick Claude vs Codex from a model/tier spec
 ClaudeBackend, CodexBackend,  // the concrete backends
+clientCapabilitiesFor, adaptPromptContent,
 toJsonSchema, toStrictJsonSchema,
 TypedEventEmitter,            // the tiny typed emitter backing runner.on(...)
 
 // ── Errors ──
 WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit,
 
+// ── Persistence paths ──
+AGENTPRISM_PERSISTENCE_ROOT_ENV,
+
 // ── Types ──
 RunDynamicWorkflowOptions, WorkflowRunOptions, AgentOptions, ExecOptions,
 WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot,
+WorkflowPathOptions, RunPersistenceOptions,
 AcpPoolOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
+InteractiveSessionOptions, InteractiveTurn, PermissionResolver,
+ClientHandlers, FsHandlers, TerminalHandlers, AcpSessionContext, NegotiatedCapabilities,
 // ACP events: the runner.on(...) surface
 AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext,
-AcpSessionUpdate, AcpUpdateKind, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent,
+AcpSessionUpdate, AcpUpdateKind, AcpPermissionPendingEvent, AcpPermissionEvent,
+AcpRawMessageEvent, AcpBackendErrorEvent,
 ```
 
 (The DSL globals — `agent`, `parallel`, `pipeline`, … — are **not** exported; they are realm

package/dist/index.d.ts

@@ -1,14 +1,62 @@
-import type { ExecOptions } from "@automatalabs/workflow-engine";
+import { WorkflowManager as EngineWorkflowManager } from "@automatalabs/workflow-engine";
+import type { AcpEventName, AcpRunnerEventMap } from "@automatalabs/acp-agents";
+import type { ExecOptions, WorkflowManagerOptions } from "@automatalabs/workflow-engine";
 import type { AgentRunner, WorkflowBackendConfig, WorkflowRunResult } from "@automatalabs/shared-types";
-export { runWorkflow, parseWorkflowScript, WorkflowManager } from "@automatalabs/workflow-engine";
-export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, } from "@automatalabs/workflow-engine";
-export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
-export { createAcpRunner, AcpAgentRunner, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, resolveBackendRegistry, BACKENDS_ENV, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
-export type { AcpPoolOptions, AcpRunnerOptions, BackendRegistry, CustomBackendConfig, RegisteredBackend, } from "@automatalabs/acp-agents";
+export { runWorkflow, parseWorkflowScript } from "@automatalabs/workflow-engine";
+export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, WorkflowPathOptions, RunPersistenceOptions, } from "@automatalabs/workflow-engine";
+export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
+export { createAcpRunner, AcpAgentRunner, InteractiveSession, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, clientCapabilitiesFor, adaptPromptContent, resolveBackendRegistry, BACKENDS_ENV, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
+export type { AcpPoolOptions, AcpRunnerOptions, InteractiveSessionOptions, InteractiveTurn, BackendRegistry, CustomBackendConfig, RegisteredBackend, ClientHandlers, FsHandlers, TerminalHandlers, AcpSessionContext, NegotiatedCapabilities, PermissionResolver, } 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 { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpSessionUpdate, AcpUpdateKind, AcpPermissionPendingEvent, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "@automatalabs/acp-agents";
 export type { AgentRunner, RunOptions, AgentResult, AgentUsage } from "@automatalabs/shared-types";
 export type { JournalEntry, WorkflowBackendConfig, WorkflowMeta } from "@automatalabs/shared-types";
+type ContextProperty<T, K extends PropertyKey> = K extends keyof T ? T[K] : never;
+type OptionalContextProperty<T, K extends PropertyKey> = K extends keyof T ? T[K] : undefined;
+/** Payload of `WorkflowManager`'s `agentEvent` observer. `event` is the verbatim runner event
+ *  payload; the top-level envelope repeats the ACP context fields hosts filter on. `backend_error`
+ *  is connection-scoped in acp-agents and therefore has no session/run context to repeat. */
+type AgentEventPayloadMap = {
+    [K in AcpEventName]: {
+        name: K;
+        event: AcpRunnerEventMap[K];
+        backendId: ContextProperty<AcpRunnerEventMap[K], "backendId">;
+    } & ("sessionId" extends keyof AcpRunnerEventMap[K] ? {
+        sessionId: ContextProperty<AcpRunnerEventMap[K], "sessionId">;
+    } : {
+        sessionId?: undefined;
+    }) & {
+        label?: OptionalContextProperty<AcpRunnerEventMap[K], "label">;
+        runId?: OptionalContextProperty<AcpRunnerEventMap[K], "runId">;
+    };
+};
+export type AgentEventPayload<K extends AcpEventName = AcpEventName> = AgentEventPayloadMap[K];
+/**
+ * Stateful workflow manager exported by the SDK facade. It is the workflow-engine manager plus
+ * ONE composition-root bridge for ACP-capable runners: when the injected AgentRunner also exposes
+ * the acp-agents `.on(name, listener)` bus, the manager forwards that live stream as `agentEvent`.
+ *
+ * The engine package stays backend-agnostic; this facade already owns the ACP default runner and
+ * ACP event types, so the bridge belongs here. Forwarding is OBSERVABILITY ONLY: manager
+ * `agentEvent` listeners are isolated from each other and from the run, and `dispose()` removes
+ * only the manager's runner subscriptions (runner process ownership stays with the caller).
+ */
+export declare class WorkflowManager extends EngineWorkflowManager {
+    private readonly acpBridges;
+    constructor(options?: WorkflowManagerOptions);
+    startInBackground(script: string, args?: unknown, exec?: ExecOptions): {
+        runId: string;
+        promise: Promise<WorkflowRunResult>;
+    };
+    runSync(script: string, args?: unknown, exec?: ExecOptions): Promise<WorkflowRunResult>;
+    resume(runId: string, exec?: ExecOptions): Promise<boolean>;
+    /** Detach manager-owned ACP event subscriptions. The manager does NOT dispose the runner: the
+     *  caller may share one runner across managers or own its process lifetime explicitly. */
+    dispose(): void;
+    /** Node-style alias for hosts that tear down managers through close hooks. */
+    close(): void;
+    private acquireAcpRunnerBridge;
+}
 /**
  * Approval policy for SCRIPT-DECLARED custom ACP backends (`meta.backends`). Script backends
  * spawn arbitrary commands on this machine, so they are INERT unless the embedder approves

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,qBAAqB,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAIxG,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;AAOvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,0BAA0B,CAAC;AAMlC,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,qBAAqB,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAEpG;;;;;;;;GAQG;AACH,MAAM,MAAM,qBAAqB,GAC7B,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,qBAAqB,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;AAExF,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;IACnB,+FAA+F;IAC/F,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,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":"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"}

package/dist/index.js

@@ -1,31 +1,152 @@
 /// <reference path="./dsl.d.ts" />
 // @automatalabs/workflows — the importable SDK for the AgentPrism dynamic-workflow
-// orchestrator. A THIN FACADE re-export barrel: it owns NO logic of its own, it
-// re-exports the clean public surface of the three engine packages and adds ONE
-// convenience helper (`runDynamicWorkflow`) that defaults the AgentRunner seam to the
-// ACP backend. It is SEPARATE from @automatalabs/mcp-server (the stdio MCP server) and
-// stays a PURE library — it pulls in neither @modelcontextprotocol/sdk nor zod.
+// orchestrator. A FACADE re-export barrel: it re-exports the clean public surface of
+// the three engine packages, adds the SDK-level WorkflowManager ACP-event bridge, and
+// adds ONE convenience helper (`runDynamicWorkflow`) that defaults the AgentRunner seam
+// to the ACP backend. It is SEPARATE from @automatalabs/mcp-server (the stdio MCP server)
+// and stays a PURE library — it pulls in neither @modelcontextprotocol/sdk nor zod.
 //
 // The DSL globals available INSIDE a workflow script (agent, parallel, pipeline, …) are
 // vm-realm globals, NOT importable symbols; they are documented for author IntelliSense
 // in ./dsl.d.ts (referenced above), not exported here.
-import { createAcpRunner } from "@automatalabs/acp-agents";
-import { parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager } from "@automatalabs/workflow-engine";
+import { ACP_CROSS_CUTTING_EVENT_NAMES, createAcpRunner } from "@automatalabs/acp-agents";
+import { parseWorkflowScript, WorkflowError, WorkflowErrorCode, WorkflowManager as EngineWorkflowManager, } from "@automatalabs/workflow-engine";
 // ── Engine: run entry, script parsing, the managed-run lifecycle, and the
 //    option/result + error types the host composes against. ──
-export { runWorkflow, parseWorkflowScript, WorkflowManager } from "@automatalabs/workflow-engine";
-export { WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
-// ── ACP backend: the default AgentRunner implementation, backend selection, the
-//    concrete backends (built-in + custom registry), the pool/runner options, and the
-//    JSON-Schema helpers. Custom backends let ANY ACP agent serve agent() calls:
+export { runWorkflow, parseWorkflowScript } from "@automatalabs/workflow-engine";
+export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, } from "@automatalabs/workflow-engine";
+// ── ACP backend: the default AgentRunner implementation, interactive sessions, backend
+//    selection, the concrete backends (built-in + custom registry), the pool/runner options,
+//    capability helpers, client handlers, permission resolvers, and JSON-Schema helpers.
+//    Custom backends let ANY ACP agent serve agent() calls:
 //    `createAcpRunner({ backends: { browser: { command: "…" } } })` (or the
 //    AGENTPRISM_BACKENDS env var), then route with `agent(p, { model: "browser" })`. ──
-export { createAcpRunner, AcpAgentRunner, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, resolveBackendRegistry, BACKENDS_ENV, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
+export { createAcpRunner, AcpAgentRunner, InteractiveSession, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, clientCapabilitiesFor, adaptPromptContent, resolveBackendRegistry, BACKENDS_ENV, 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";
+const MANAGER_ACP_CROSS_CUTTING_EVENT_NAMES = ACP_CROSS_CUTTING_EVENT_NAMES;
+/**
+ * Stateful workflow manager exported by the SDK facade. It is the workflow-engine manager plus
+ * ONE composition-root bridge for ACP-capable runners: when the injected AgentRunner also exposes
+ * the acp-agents `.on(name, listener)` bus, the manager forwards that live stream as `agentEvent`.
+ *
+ * The engine package stays backend-agnostic; this facade already owns the ACP default runner and
+ * ACP event types, so the bridge belongs here. Forwarding is OBSERVABILITY ONLY: manager
+ * `agentEvent` listeners are isolated from each other and from the run, and `dispose()` removes
+ * only the manager's runner subscriptions (runner process ownership stays with the caller).
+ */
+export class WorkflowManager extends EngineWorkflowManager {
+    acpBridges = new Map();
+    constructor(options = {}) {
+        super(options);
+        this.acquireAcpRunnerBridge(options.agent);
+    }
+    startInBackground(script, args, exec = {}) {
+        const releaseBridge = this.acquireAcpRunnerBridge(exec.agent);
+        try {
+            const started = super.startInBackground(script, args, exec);
+            void started.promise.then(releaseBridge, releaseBridge);
+            return started;
+        }
+        catch (error) {
+            releaseBridge();
+            throw error;
+        }
+    }
+    async runSync(script, args, exec = {}) {
+        const releaseBridge = this.acquireAcpRunnerBridge(exec.agent);
+        try {
+            return await super.runSync(script, args, exec);
+        }
+        finally {
+            releaseBridge();
+        }
+    }
+    async resume(runId, exec = {}) {
+        const releaseBridge = this.acquireAcpRunnerBridge(exec.agent);
+        try {
+            return await super.resume(runId, exec);
+        }
+        finally {
+            releaseBridge();
+        }
+    }
+    /** Detach manager-owned ACP event subscriptions. The manager does NOT dispose the runner: the
+     *  caller may share one runner across managers or own its process lifetime explicitly. */
+    dispose() {
+        for (const bridge of this.acpBridges.values()) {
+            for (const unsubscribe of bridge.unsubscribers)
+                unsubscribe();
+        }
+        this.acpBridges.clear();
+    }
+    /** Node-style alias for hosts that tear down managers through close hooks. */
+    close() {
+        this.dispose();
+    }
+    acquireAcpRunnerBridge(agent) {
+        if (!isAcpEventBusRunner(agent))
+            return () => { };
+        let bridge = this.acpBridges.get(agent);
+        if (!bridge) {
+            bridge = {
+                refs: 0,
+                unsubscribers: [
+                    agent.on("session_update", (event) => {
+                        this.emit("agentEvent", toSessionUpdateAgentEventPayload(event));
+                    }),
+                    ...MANAGER_ACP_CROSS_CUTTING_EVENT_NAMES.map((name) => agent.on(name, (event) => {
+                        this.emit("agentEvent", toAgentEventPayload(name, event));
+                    })),
+                ],
+            };
+            this.acpBridges.set(agent, bridge);
+        }
+        bridge.refs++;
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            const current = this.acpBridges.get(agent);
+            if (current !== bridge)
+                return;
+            current.refs--;
+            if (current.refs > 0)
+                return;
+            for (const unsubscribe of current.unsubscribers)
+                unsubscribe();
+            this.acpBridges.delete(agent);
+        };
+    }
+}
+function isAcpEventBusRunner(agent) {
+    return typeof agent?.on === "function";
+}
+function toSessionUpdateAgentEventPayload(event) {
+    const name = event.update.sessionUpdate;
+    return toAgentEventPayload(name, {
+        ...event.update,
+        sessionId: event.sessionId,
+        backendId: event.backendId,
+        label: event.label,
+        runId: event.runId,
+    });
+}
+function toAgentEventPayload(name, event) {
+    const context = event;
+    return {
+        name,
+        event,
+        backendId: context.backendId,
+        ...(context.sessionId !== undefined ? { sessionId: context.sessionId } : {}),
+        ...(context.label !== undefined ? { label: context.label } : {}),
+        ...(context.runId !== undefined ? { runId: context.runId } : {}),
+    };
+}
 /**
  * Run a dynamic workflow script to a TERMINAL result, with the AgentRunner seam
  * defaulted to the ACP backend.
@@ -51,7 +172,13 @@ export async function runDynamicWorkflow(script, opts = {}) {
     if (declared && Object.keys(declared).length > 0) {
         exec = { ...(exec ?? {}), scriptBackends: await approveScriptBackends(declared, opts.allowScriptBackends) };
     }
-    return new WorkflowManager({ agent: opts.runner ?? createAcpRunner() }).runSync(script, opts.args, exec);
+    const manager = new WorkflowManager({ agent: opts.runner ?? createAcpRunner() });
+    try {
+        return await manager.runSync(script, opts.args, exec);
+    }
+    finally {
+        manager.dispose();
+    }
 }
 /** Resolve the embedder's approval policy over the declared backends; throw with guidance when
  *  approval is missing or any backend is declined (an unapproved dependency must abort, never

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.6.2",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
@@ -25,8 +25,8 @@
   },
   "dependencies": {
     "@automatalabs/shared-types": "0.7.0",
-    "@automatalabs/workflow-engine": "0.3.2",
-    "@automatalabs/acp-agents": "0.8.0"
+    "@automatalabs/workflow-engine": "0.4.0",
+    "@automatalabs/acp-agents": "0.9.0"
   },
   "scripts": {
     "build": "tsc -b",