@automatalabs/workflows 0.33.1 → 0.35.0

package/README.md

@@ -97,7 +97,7 @@ Options (`RunDynamicWorkflowOptions`):
 | `args`   | `unknown`      | The value handed to the script's `args` global. |
 | `cwd`    | `string`       | Base working directory for the run (e.g. the project root): every subagent session runs here (a per-agent `agent({ cwd })` or worktree isolation overrides it), worktrees branch from it, and `agentType` definitions are scanned from it. Omitted ⇒ `process.cwd()`. |
 | `runner` | `AgentRunner`  | Swap the backend (or stub it in tests). Omitted ⇒ `createAcpRunner()`. |
-| `exec`   | `ExecOptions`  | Per-run controls forwarded to the manager: `tokenBudget`, `agentTimeoutMs`, `concurrency`, `agentRetries`, `signal`, `onProgress`, `confirm`, `checkpointReplies`, … |
+| `exec`   | `ExecOptions`  | Per-run controls forwarded to the manager: `tokenBudget`, `agentTimeoutMs`, `concurrency`, `agentRetries`, `signal`, `onProgress`, `confirm`, `resumeFromRunId`, `resumePolicy`, `checkpointReplies`, … |
 | `allowScriptBackends` | `boolean \| callback` | Approve the commands declared in `meta.backends`; declarations are inert without host approval. |
 | `workflows` | `string \| string[] \| WorkflowDir` | Resolve the first argument and nested `workflow("name")` calls from one or more directories. |
 
@@ -116,6 +116,23 @@ Every script **must** begin with `export const meta = { name, description, phase
 statement, and must be **deterministic** — `Date.now()`, `Math.random()`, and `new Date()` are
 unavailable inside the realm (they would break journal replay on resume).
 
+Replay-safe read-only/worktree fan-out is explicit:
+
+```js
+const [audit, experiment] = await parallel([
+  () => agent("Audit src/api without changing files.", {
+    label: "audit:api", resume: { filesystem: "read-only" },
+  }),
+  () => agent("Try the worker fix in isolation; return a unified diff.", {
+    label: "try:worker", isolation: "worktree", resume: { filesystem: "read-only" },
+  }),
+]);
+```
+
+The worktree and edits are discarded; return the diff as data. The declaration is required for
+content-addressed reuse in both arms—worktree isolation alone is not a safety proof. See the
+[incremental resume API](../../docs/api.md#content-addressed-incremental-resume).
+
 ### Substitution testing (isolation mode)
 
 Record a normal managed run, then re-run its recorded script with one selected step live while all
@@ -258,6 +275,13 @@ if (run.status === "paused") {
   const accepted = await manager.resume(run.runId);
   console.log(accepted); // true when the paused run was accepted for resume
 }
+
+// Edited-script/current-args resume is a NEW managed run with a correspondence report.
+const next = await manager.runSync(script, { repo: "agentprism", expanded: true }, {
+  resumeFromRunId: run.runId,
+  resumePolicy: "auto",
+});
+console.log(next.runId, next.resumeReport);
 ```
 
 `runSync(script, args?, exec?)` always resolves to a terminal `WorkflowRunResult`. A run **pauses**
@@ -284,12 +308,21 @@ per-execution `exec.agent` until that promise settles, including rejection. Read
 `getRun()`, `getSnapshot()`, or `inspectRun()`, and subscribe to cumulative `tokenUsage` events while
 work is running. Live attempts update `snapshot.tokenUsage` monotonically; replayed calls add zero.
 
-When `exec.resumeJournal` is preloaded, the underlying manager sorts and copies the inherited prefix
-into the child run before its fail-fast initial persistence. Cached replay does not re-emit journal
-events, but every subsequent live suffix write persists the complete prefix. This makes each new
-background run ID independently resumable across multiple pause/resume hops. Process loss can stop
-in-flight work; the next manager recovers a stale durable `running` record to `paused`, and an
-unjournaled in-flight call may run again.
+`exec.resumeFromRunId` asks the manager to admit a terminal source, persist a self-contained seed
+under a new run ID, and match safe calls by exact path/hash or unique hash+input fingerprint.
+Uncertain, ambiguous, unsafe, or environment-mismatched calls run live. Identity hits preserve
+script-visible logical budget debit while adding zero current provider usage; replayed session
+records are rebound to the current call index/label/phase. `resumePolicy: "positional"` requests
+index/prefix matching but cannot bypass new-format input/safety/environment gates. The distinct
+same-ID `resume()` and low-level `resumeJournal` paths remain permanently legacy positional and
+emit no `resumeReport`. See the [full contract](../../docs/api.md#content-addressed-incremental-resume).
+
+The manager's critical initial save contains the complete inherited seed before a background
+acknowledgement. A manager-prepared `resumeFromRunId` hit re-journals the selected value under its
+current target index; same-ID/manual legacy cache hits retain the historical no-journal-callback
+behavior and rely on the already-seeded prefix. Each new run is independently resumable across
+multiple pause/resume hops. Process loss can stop in-flight work; the next manager recovers a stale
+durable `running` record to `paused`, and an unjournaled in-flight call may run again.
 
 `inspectRun(runId, options?)` is inherited through this facade and returns the shared
 `WorkflowRunStatus` without importing `@automatalabs/workflow-engine`. It reads the freshest live
@@ -303,18 +336,56 @@ execution results carry an immediate redacted final-20 `logTail`; completed resu
 
 Manager events are Node `EventEmitter` notifications: `agentStart`, `agentEnd`, `agentHistory`,
 `journal`, `tokenUsage`, `log`, `phase`, `complete`, `paused`, `resumed`, `stopped`, `error`,
-and `agentEvent`. `journal` emits `{ runId, entry }` for each live journal append, even when
-file journaling is disabled via `journaling: false`. `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/elicitation/session/raw/backend events keep their runner
-names.
+and `agentEvent`. Their overloads infer exact payloads from `EngineRunEventPayloadMap` and
+`WorkflowAgentEventPayloadMap`; `WorkflowRunEvent` is the exhaustive union when a host wants one
+dispatcher. Every engine event carries the owning root `runId` and originating engine `scope`.
+`journal` emits `{ runId, scope, entry }` for each live journal append, even when file journaling is
+disabled via `journaling: false`.
 
 ```ts
-manager.on("agentEvent", ({ runId, label, name }) => console.error(runId, label, name));
+import {
+  WorkflowManager,
+  createAcpRunner,
+  type EngineRunEventPayloadMap,
+  type WorkflowRunEvent,
+} from "@automatalabs/workflows";
+
+const manager = new WorkflowManager({ agent: createAcpRunner() });
+
+const onAgentEnd = (event: EngineRunEventPayloadMap["agentEnd"]) => {
+  console.error(event.scope, event.callIndex, event.label, event.result);
+};
+manager.on("agentEnd", onAgentEnd); // the overload infers the same payload without annotation
+
+const target = { scope: "build-abc-nested1", callIndex: 3 };
+manager.on("agentEvent", (event) => {
+  if (event.scope === target.scope && event.callIndex === target.callIndex) {
+    renderAcpUpdate(event.name, event.event);
+  }
+});
+
+function consumeEvent(event: WorkflowRunEvent): void {
+  switch (event.type) {
+    case "phase":
+      console.error(event.scope, event.title);
+      break;
+    case "agentEvent":
+      console.error(event.scope, event.callIndex, event.name);
+      break;
+    default:
+      break;
+  }
+}
 ```
 
+`agentEvent` forwards the live ACP stream from an ACP-capable runner with `name`, `event`, and the
+runner context fields (`runId`, `scope`, `callIndex`, `label`, `sessionId`, `backendId`) when present.
+`scope` repeats the runner's originating engine `runId`, so nested calls filter directly on
+`(scope, callIndex)`. Direct runner/interactive sessions can omit `callIndex`; `backend_error` is
+connection-scoped and carries `backendId` only. ACP `session/update` traffic is emitted once under
+its inner discriminant name, while permission/elicitation/session/raw/backend events keep their
+runner names.
+
 Every live ACP-backed `agent()` call records a non-secret re-attach handle in
 `run.agentSessions`. Set `agent(..., { keepSession: true })` to skip release-time `session/close`,
 then use the runner's `loadSession()` or `resumeSession()` host API with that record. Session
@@ -388,9 +459,9 @@ Semantics worth knowing:
   script resolves from the same view. (Without it, `runDynamicWorkflow` has no saved-workflow
   resolver and nested names cannot resolve.) A top-level string containing `export const meta`
   is always treated as a verbatim script, never a name.
-- **Versioning is git's job.** A run persists its script content, so `resume()` replays the exact
-  script that started the run even if the file changed since; an edited file simply cache-misses
-  from the first changed call on the next fresh run.
+- **Versioning is git's job.** Same-ID `resume()` reloads the exact persisted script. A new
+  `resumeFromRunId` execution can use an edited script: changed calls run live, while uniquely
+  matching safety-marked calls may move and replay after admission.
 - **`resolve()` validates name shape strictly** (one flat path segment) — inline nested scripts
   fall through to verbatim parsing, and path traversal out of the configured dirs is impossible.
 
@@ -441,16 +512,18 @@ await runner.dispose();
 | `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.
+event (except `backend_error`) carries `{ sessionId, backendId, label?, runId?, callIndex? }`.
+`callIndex` echoes the optional `RunOptions.callIndex` used to open the session and is never sent on
+the ACP wire. Engine-created calls supply it; direct/interactive runner callers may omit it.
 
 **Best-effort.** Listeners are observers: a throwing listener is isolated and never breaks the run,
 the update drain, or sibling listeners.
 
 **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
+`manager.on("agentEvent", ({ scope, callIndex, name, event }) => …)`. Every `agent()` call in the
+script then streams live ACP events through the manager; the bridge sets `scope = runId` and repeats
+the optional `callIndex` for direct call filtering. 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.
 
 ---
@@ -465,7 +538,7 @@ ships no runtime code).
 
 | global | what it does |
 |--------|--------------|
-| `agent(prompt, options?)` | Run ONE subagent to completion; returns its result (text, or the validated object with `options.schema`). |
+| `agent(prompt, options?)` | Run ONE subagent to completion; returns its result (text, or the validated object with `options.schema`). `options.resume: { filesystem: "read-only" }` is the author safety declaration for content-addressed replay. |
 | `parallel(thunks)` | Run an array of **thunks** (`() => Promise`) concurrently; resolves in input order. |
 | `pipeline(items, ...stages)` | Map `items` through sequential async stages, concurrently across items. |
 | `workflow(nameOrScript, args?)` | Run a saved (or inline) workflow nested in this run, sharing its limiter/budget. |
@@ -659,6 +732,8 @@ fabricateFromSchema,          // the dry run's JSON-Schema value fabricator
 formatValidateReport,         // render a ValidateWorkflowReport as CLI text
 openWorkflowDir,              // read-only view over folders of workflow scripts (name = filename stem)
 WorkflowManager,              // stateful / resumable run manager
+RESUME_FALLBACK_REASONS, RESUME_DISABLED_REASONS,
+RESUME_CALL_LIVE_REASONS, RESUME_CALL_FAILED_REASONS,
 
 // ── ACP backend ──
 createAcpRunner,              // () => AcpAgentRunner (the default AgentRunner; has .on(...) events)
@@ -689,6 +764,10 @@ ValidateWorkflowOptions, ValidateWorkflowReport, ValidateHarnessOptions,
 ValidatedAgentCall, ValidatedCheckpoint,
 WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowRunFallback,
 WorkflowCheckpointTaken, WorkflowCheckpointSource, WorkflowSnapshot,
+ResumePolicy, WorkflowResumeStrategy, WorkflowResumeMatch, WorkflowResumeSafety,
+WorkflowResumeFallbackReason, WorkflowResumeDisabledReason,
+WorkflowResumeCallLiveReason, WorkflowResumeCallFailedReason,
+WorkflowCallReplayProvenance, WorkflowResumeCallDecision, WorkflowResumeReport,
 WorkflowPathOptions, RunPersistence, RunPersistenceOptions,
 AcpPoolOptions, AcpRunnerOptions, AgentRunner, RunOptions, AgentResult, AgentUsage, JournalEntry,
 AgentSessionRef, AgentSessionRecord, WorkflowBackendConfig, WorkflowCallRecord, WorkflowRecordedError,

package/dist/index.d.ts

@@ -1,16 +1,18 @@
 import { WorkflowManager as EngineWorkflowManager } from "@automatalabs/workflow-engine";
 import type { AcpEventName, AcpRunnerEventMap } from "@automatalabs/acp-agents";
 import type { ExecOptions, WorkflowDir, WorkflowManagerOptions } from "@automatalabs/workflow-engine";
-import type { AgentRunner, WorkflowRunResult } from "@automatalabs/shared-types";
+import type { AgentRunner, RunEvent, WorkflowRunResult } from "@automatalabs/shared-types";
 import { type ScriptBackendApproval } from "./script-backends.js";
-export { runWorkflow, parseWorkflowScript, redactText, truncateUtf8 } from "@automatalabs/workflow-engine";
+export { runWorkflow, parseWorkflowScript, hashCheckpointInputs, redactText, truncateUtf8, CALL_PATH_FORMAT, CALL_INPUTS_FORMAT, CHECKPOINT_INPUTS_FORMAT, RESUME_FALLBACK_REASONS, RESUME_DISABLED_REASONS, RESUME_CALL_LIVE_REASONS, RESUME_CALL_FAILED_REASONS, } from "@automatalabs/workflow-engine";
 export { runIsolation, createReplayRunner, type RunIsolationSdkOptions } from "./isolation.js";
 export type { RunIsolationOptions, IsolationRunResult, ReplayRunnerOptions, ResolvedIsolationTarget, IsolationTarget, ReplayRunner, ReplayObservation, ReplayReport, ReplayCallReport, ReplayDivergenceEvent, CheckpointCallContext, WorkflowCallRecord, WorkflowRecordedError, } from "./isolation.js";
 export { openWorkflowDir, type WorkflowDir, type WorkflowDirEntry, type OpenWorkflowDirOptions, } from "@automatalabs/workflow-engine";
 export { validateWorkflowScript, fabricateFromSchema, formatValidateReport, MOCK_TOKENS_PER_AGENT } from "./validate.js";
 export type { MockAnswerJson, MockAnswerRule, MockAnswers, MockAnswerSequence, UnusedMockAnswer, ValidateWorkflowOptions, ValidateWorkflowReport, ValidateHarnessOptions, ValidatedAgentCall, ValidatedCheckpoint, ValidatedMockAnswerRule, ValidatedMockAnswers, ValidatedMockAnswerUse, } from "./validate.js";
-export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, WorkflowPathOptions, RunPersistence, RunPersistenceOptions, PersistedRunState, PersistedAgentState, WorkflowLogTail, WorkflowRunCallStatus, WorkflowRunInspectionOptions, WorkflowRunStatus, WorkflowRunStatusTruncation, WorkflowRunFallback, WorkflowCheckpointSource, WorkflowCheckpointTaken, } from "@automatalabs/workflow-engine";
+export type { WorkflowRunOptions, AgentOptions, ExecOptions, WorkflowManagerOptions, CheckpointOptions, WorkflowRunResult, WorkflowSnapshot, WorkflowPathOptions, RunPersistence, RunPersistenceOptions, PersistedRunState, PersistedAgentState, PersistedResumeFormat, PersistedResumeCandidate, PersistedCheckpointInjection, PersistedResumeSeed, PreparedResume, WorkflowLogTail, WorkflowRunCallStatus, WorkflowRunInspectionOptions, WorkflowRunStatus, WorkflowRunStatusTruncation, WorkflowRunFallback, WorkflowCheckpointSource, WorkflowCheckpointTaken, ResumePolicy, WorkflowResumeStrategy, WorkflowResumeMatch, WorkflowResumeFallbackReason, WorkflowResumeDisabledReason, WorkflowResumeCallLiveReason, WorkflowResumeCallFailedReason, WorkflowResumeSafety, WorkflowCallReplayProvenance, WorkflowResumeCallDecision, WorkflowResumeReport, } from "@automatalabs/workflow-engine";
 export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, isAuthRequired, } from "@automatalabs/workflow-engine";
+export { withRunEvents, RunEventLogError, RUN_EVENT_READ_LIMIT_DEFAULT, RUN_EVENT_READ_LIMIT_MAX, RUN_EVENT_MAX_RECORD_BYTES, } from "@automatalabs/workflow-engine";
+export type { RunEventPersistence, RunEventStream, AppendRunEventInput, ReadRunEventsOptions, ReadRunEventsResult, WatchRunEventsOptions, RunEventLogErrorCode, } from "@automatalabs/workflow-engine";
 export { createAcpRunner, AcpAgentRunner, InteractiveSession, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, AGENT_METHODS, CLIENT_METHODS, AGENT_METHOD_COVERAGE, CLIENT_METHOD_COVERAGE, ACP_AUTH_REQUIRED_ERROR_CODE, clientCapabilitiesFor, adaptPromptContent, resolveBackendRegistry, BACKENDS_ENV, toJsonSchema, toStrictJsonSchema, } from "@automatalabs/acp-agents";
 export type { AcpPoolOptions, AcpRunnerOptions, AuthenticateOptions, AuthMethodsOptions, DisableProviderOptions, DeleteSessionOptions, InteractiveSessionOptions, InteractiveTurn, ListProvidersOptions, ListSessionsOptions, LogoutOptions, ProbedConfigOptions, ReattachSessionOptions, SetProviderOptions, BackendRegistry, CustomBackendConfig, RegisteredBackend, ClientCapabilityOptions, ClientHandlers, FsHandlers, McpHandlers, TerminalHandlers, AcpSessionContext, NegotiatedCapabilities, PermissionResolver, AgentAuthCapabilities, AgentRequestMethod, AgentRequestParamsByMethod, AgentRequestResponsesByMethod, AuthCapabilities, AuthEnvVar, AuthenticateRequest, AuthenticateResponse, AuthMethod, AuthMethodAgent, AuthMethodEnvVar, AuthMethodId, AuthMethodTerminal, ConnectMcpRequest, ConnectMcpResponse, DeleteSessionRequest, DeleteSessionResponse, DisableProviderRequest, DisableProviderResponse, DisconnectMcpRequest, DisconnectMcpResponse, ListProvidersRequest, ListProvidersResponse, ListSessionsRequest, ListSessionsResponse, LlmProtocol, LoadSessionRequest, LoadSessionResponse, LogoutCapabilities, LogoutRequest, LogoutResponse, McpConnectionId, McpServerAcp, McpServerAcpId, MessageMcpNotification, MessageMcpRequest, MessageMcpResponse, ProviderCurrentConfig, ProviderId, ProviderInfo, ProvidersCapabilities, ResumeSessionRequest, ResumeSessionResponse, SetProviderRequest, SetProviderResponse, AgentNotificationMethod, AgentNotificationParamsByMethod, CompleteElicitationNotification, CreateElicitationRequest, CreateElicitationResponse, ElicitationAcceptAction, ElicitationCapabilities, ElicitationContentValue, ElicitationFormCapabilities, ElicitationFormMode, ElicitationId, ElicitationPropertySchema, ElicitationRequestScope, ElicitationResolver, ElicitationSchema, ElicitationSchemaType, ElicitationSessionScope, ElicitationUrlCapabilities, ElicitationUrlMode, SessionMode, SessionModeState, SessionConfigOption, SessionInfo, SendRequestOptions, AgentMethodCoverage, ClientMethodCoverage, } from "@automatalabs/acp-agents";
 export type { AuthResolver, AuthContext, AuthResolution, AuthMethodDescriptor, CompleteAuthOptions, AuthOutcome, AuthController, AuthStatusSnapshot, AuthCapableRunner, ProviderCapableRunner, } from "@automatalabs/acp-agents";
@@ -19,26 +21,61 @@ export { TypedEventEmitter } from "@automatalabs/acp-agents";
 export type { AcpRunnerEventMap, AcpEventName, AcpEventListener, AcpEventContext, AcpSessionUpdate, AcpUpdateKind, AcpElicitationCompleteEvent, AcpElicitationEvent, AcpElicitationPendingEvent, AcpPermissionPendingEvent, AcpPermissionEvent, AcpRawMessageEvent, AcpBackendErrorEvent, } from "@automatalabs/acp-agents";
 export type { AgentRunner, McpAcpServerConfig, McpServerConfig, RunOptions, AgentResult, AgentUsage, } from "@automatalabs/shared-types";
 export type { AgentSessionRecord, AgentSessionRef, JournalCallMetadata, 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">;
+export { RUN_EVENT_LOG_VERSION } from "@automatalabs/shared-types";
+export type { RunEvent, EngineRunEvent, EngineRunEventName, EngineRunEventPayloadMap, PersistableEngineRunEvent, PersistedRunEvent, RunEventLogRecord, RunEventValueProjection, RunEventErrorProjection, RunEventCheckpointProjection, PersistedRunAgentEndPayload, } from "@automatalabs/shared-types";
+type ContextProperty<T, Key extends PropertyKey> = Key extends keyof T ? T[Key] : never;
+type OptionalContextProperty<T, Key extends PropertyKey> = Key extends keyof T ? T[Key] : undefined;
+/** The manager unwraps the runner catch-all into its concrete sessionUpdate discriminant. */
+export type WorkflowAgentEventName = Exclude<AcpEventName, "session_update">;
+/**
+ * Envelope map over the runner's whole public event-name type. The manager-emitted map below
+ * picks only names the bridge actually publishes; retaining the full map preserves the existing
+ * AgentEventPayload<"session_update"> type argument for source compatibility.
+ */
+type WorkflowAgentEventEnvelopeMap = {
+    [Name in AcpEventName]: {
+        name: Name;
+        event: AcpRunnerEventMap[Name];
+        backendId: ContextProperty<AcpRunnerEventMap[Name], "backendId">;
+    } & ("sessionId" extends keyof AcpRunnerEventMap[Name] ? {
+        sessionId: ContextProperty<AcpRunnerEventMap[Name], "sessionId">;
     } : {
         sessionId?: undefined;
     }) & {
-        label?: OptionalContextProperty<AcpRunnerEventMap[K], "label">;
-        runId?: OptionalContextProperty<AcpRunnerEventMap[K], "runId">;
+        label?: OptionalContextProperty<AcpRunnerEventMap[Name], "label">;
+        runId?: OptionalContextProperty<AcpRunnerEventMap[Name], "runId">;
+        scope?: OptionalContextProperty<AcpRunnerEventMap[Name], "runId">;
+        callIndex?: OptionalContextProperty<AcpRunnerEventMap[Name], "callIndex">;
     };
 };
-export type AgentEventPayload<K extends AcpEventName = AcpEventName> = AgentEventPayloadMap[K];
+export type WorkflowAgentEventPayloadMap = Pick<WorkflowAgentEventEnvelopeMap, WorkflowAgentEventName>;
+export type WorkflowAgentEventPayload<Name extends WorkflowAgentEventName = WorkflowAgentEventName> = WorkflowAgentEventPayloadMap[Name];
+export type WorkflowAgentEvent = {
+    [Name in WorkflowAgentEventName]: {
+        type: "agentEvent";
+    } & WorkflowAgentEventPayload<Name>;
+}[WorkflowAgentEventName];
+export type WorkflowRunEvent = RunEvent<WorkflowAgentEvent>;
+/**
+ * Compatibility alias retained with its pre-contract generic constraint and default. The
+ * "session_update" member is type-only: the manager did not emit it before this contract and
+ * still does not. New exact consumers use WorkflowAgentEventPayload/WorkflowAgentEvent.
+ */
+export type AgentEventPayload<Name extends AcpEventName = AcpEventName> = WorkflowAgentEventEnvelopeMap[Name];
+export interface WorkflowManager {
+    addListener(eventName: "agentEvent", listener: (payload: WorkflowAgentEventPayload) => void): this;
+    on(eventName: "agentEvent", listener: (payload: WorkflowAgentEventPayload) => void): this;
+    once(eventName: "agentEvent", listener: (payload: WorkflowAgentEventPayload) => void): this;
+    removeListener(eventName: "agentEvent", listener: (payload: WorkflowAgentEventPayload) => void): this;
+    off(eventName: "agentEvent", listener: (payload: WorkflowAgentEventPayload) => void): this;
+    emit(eventName: "agentEvent", payload: WorkflowAgentEventPayload): boolean;
+    addListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    on(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    once(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    removeListener(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    off(eventName: string | symbol, listener: (...args: any[]) => void): this;
+    emit(eventName: string | symbol, ...args: any[]): boolean;
+}
 /**
  * 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

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAaA,OAAO,EAKL,eAAe,IAAI,qBAAqB,EACzC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAoB,YAAY,EAAE,iBAAiB,EAAiB,MAAM,0BAA0B,CAAC;AACjH,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,+BAA+B,CAAC;AACtG,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAyB,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAClH,OAAO,EAAyB,KAAK,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAMzF,OAAO,EACL,WAAW,EACX,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,wBAAwB,EACxB,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EAAE,YAAY,EAAE,kBAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/F,YAAY,EACV,mBAAmB,EACnB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,eAAe,EACf,YAAY,EACZ,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,EACrB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,gBAAgB,CAAC;AAOxB,OAAO,EACL,eAAe,EACf,KAAK,WAAW,EAChB,KAAK,gBAAgB,EACrB,KAAK,sBAAsB,GAC5B,MAAM,+BAA+B,CAAC;AAIvC,OAAO,EAAE,sBAAsB,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AACzH,YAAY,EACV,cAAc,EACd,cAAc,EACd,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,sBAAsB,EACtB,sBAAsB,EACtB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,kBAAkB,EAClB,YAAY,EACZ,WAAW,EACX,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,EACrB,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,EACrB,wBAAwB,EACxB,4BAA4B,EAC5B,mBAAmB,EACnB,cAAc,EACd,eAAe,EACf,qBAAqB,EACrB,4BAA4B,EAC5B,iBAAiB,EACjB,2BAA2B,EAC3B,mBAAmB,EACnB,wBAAwB,EACxB,uBAAuB,EACvB,YAAY,EACZ,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC5B,4BAA4B,EAC5B,4BAA4B,EAC5B,8BAA8B,EAC9B,oBAAoB,EACpB,4BAA4B,EAC5B,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,+BAA+B,EAC/B,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,cAAc,GACf,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,4BAA4B,EAC5B,wBAAwB,EACxB,0BAA0B,GAC3B,MAAM,+BAA+B,CAAC;AACvC,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,mBAAmB,EACnB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,+BAA+B,CAAC;AAQvC,OAAO,EACL,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,cAAc,EACd,qBAAqB,EACrB,sBAAsB,EACtB,4BAA4B,EAC5B,qBAAqB,EACrB,kBAAkB,EAClB,sBAAsB,EACtB,YAAY,EACZ,YAAY,EACZ,kBAAkB,GACnB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,cAAc,EACd,gBAAgB,EAChB,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,oBAAoB,EACpB,yBAAyB,EACzB,eAAe,EACf,oBAAoB,EACpB,mBAAmB,EACnB,aAAa,EACb,mBAAmB,EACnB,sBAAsB,EACtB,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,iBAAiB,EACjB,uBAAuB,EACvB,cAAc,EACd,UAAU,EACV,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,0BAA0B,EAC1B,6BAA6B,EAC7B,gBAAgB,EAChB,UAAU,EACV,mBAAmB,EACnB,oBAAoB,EACpB,UAAU,EACV,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,mBAAmB,EACnB,oBAAoB,EACpB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,cAAc,EACd,eAAe,EACf,YAAY,EACZ,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,kBAAkB,EAClB,qBAAqB,EACrB,UAAU,EACV,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,kBAAkB,EAClB,mBAAmB,EACnB,uBAAuB,EACvB,+BAA+B,EAC/B,+BAA+B,EAC/B,wBAAwB,EACxB,yBAAyB,EACzB,uBAAuB,EACvB,uBAAuB,EACvB,uBAAuB,EACvB,2BAA2B,EAC3B,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,uBAAuB,EACvB,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,0BAA0B,EAC1B,kBAAkB,EAClB,WAAW,EACX,gBAAgB,EAChB,mBAAmB,EACnB,WAAW,EACX,kBAAkB,EAClB,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAOlC,YAAY,EACV,YAAY,EACZ,WAAW,EACX,cAAc,EACd,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACX,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,0BAA0B,CAAC;AAClC,YAAY,EACV,yBAAyB,EACzB,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,2BAA2B,EAC3B,mBAAmB,EACnB,0BAA0B,EAC1B,yBAAyB,EACzB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,0BAA0B,CAAC;AAIlC,YAAY,EACV,WAAW,EACX,kBAAkB,EAClB,eAAe,EACf,UAAU,EACV,WAAW,EACX,UAAU,GACX,MAAM,4BAA4B,CAAC;AACpC,YAAY,EACV,kBAAkB,EAClB,eAAe,EACf,mBAAmB,EACnB,YAAY,EACZ,qBAAqB,EACrB,YAAY,GACb,MAAM,4BAA4B,CAAC;AAMpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,YAAY,EACV,QAAQ,EACR,cAAc,EACd,kBAAkB,EAClB,wBAAwB,EACxB,yBAAyB,EACzB,iBAAiB,EACjB,iBAAiB,EACjB,uBAAuB,EACvB,uBAAuB,EACvB,4BAA4B,EAC5B,2BAA2B,GAC5B,MAAM,4BAA4B,CAAC;AAwBpC,KAAK,eAAe,CAAC,CAAC,EAAE,GAAG,SAAS,WAAW,IAAI,GAAG,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;AACxF,KAAK,uBAAuB,CAAC,CAAC,EAAE,GAAG,SAAS,WAAW,IACrD,GAAG,SAAS,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,SAAS,CAAC;AAE3C,6FAA6F;AAC7F,MAAM,MAAM,sBAAsB,GAAG,OAAO,CAAC,YAAY,EAAE,gBAAgB,CAAC,CAAC;AAE7E;;;;GAIG;AACH,KAAK,6BAA6B,GAAG;KAClC,IAAI,IAAI,YAAY,GAAG;QACtB,IAAI,EAAE,IAAI,CAAC;QACX,KAAK,EAAE,iBAAiB,CAAC,IAAI,CAAC,CAAC;QAC/B,SAAS,EAAE,eAAe,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;KAClE,GAAG,CAAC,WAAW,SAAS,MAAM,iBAAiB,CAAC,IAAI,CAAC,GAClD;QAAE,SAAS,EAAE,eAAe,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAA;KAAE,GACpE;QAAE,SAAS,CAAC,EAAE,SAAS,CAAA;KAAE,CAAC,GAAG;QAC7B,KAAK,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAClE,KAAK,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAClE,KAAK,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;QAClE,SAAS,CAAC,EAAE,uBAAuB,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,CAAC;KAC3E;CACJ,CAAC;AAEF,MAAM,MAAM,4BAA4B,GAAG,IAAI,CAC7C,6BAA6B,EAC7B,sBAAsB,CACvB,CAAC;AAEF,MAAM,MAAM,yBAAyB,CACnC,IAAI,SAAS,sBAAsB,GAAG,sBAAsB,IAC1D,4BAA4B,CAAC,IAAI,CAAC,CAAC;AAEvC,MAAM,MAAM,kBAAkB,GAAG;KAC9B,IAAI,IAAI,sBAAsB,GAC7B;QAAE,IAAI,EAAE,YAAY,CAAA;KAAE,GAAG,yBAAyB,CAAC,IAAI,CAAC;CAC3D,CAAC,sBAAsB,CAAC,CAAC;AAE1B,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC,kBAAkB,CAAC,CAAC;AAE5D;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAC3B,IAAI,SAAS,YAAY,GAAG,YAAY,IACtC,6BAA6B,CAAC,IAAI,CAAC,CAAC;AAExC,MAAM,WAAW,eAAe;IAC9B,WAAW,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,IAAI,CAAC;IACnG,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1F,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,IAAI,CAAC;IAC5F,cAAc,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,IAAI,CAAC;IACtG,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,yBAAyB,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3F,IAAI,CAAC,SAAS,EAAE,YAAY,EAAE,OAAO,EAAE,yBAAyB,GAAG,OAAO,CAAC;IAC3E,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAClF,EAAE,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACzE,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC3E,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACrF,GAAG,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E,IAAI,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC;CAC3D;AAED;;;;;;;;;GASG;AACH,qBAAa,eAAgB,SAAQ,qBAAqB;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgD;gBAE/D,OAAO,GAAE,sBAA2B;IAKvC,iBAAiB,CACxB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,OAAO,EACd,IAAI,GAAE,WAAgB,GACrB;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;KAAE;IAY1C,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAS3F,kBAAkB,CAC/B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,WAAgB,GACrB,OAAO,CACN;QAAE,QAAQ,EAAE,KAAK,CAAC;QAAC,OAAO,CAAC,EAAE,SAAS,CAAA;KAAE,GACxC;QAAE,QAAQ,EAAE,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAA;KAAE,CAC1D;IAgBc,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,OAAO,CAAC;IAK9E;8FAC0F;IAC1F,OAAO,IAAI,IAAI;IAOf,8EAA8E;IAC9E,KAAK,IAAI,IAAI;IAIb,OAAO,CAAC,sBAAsB;CAiC/B;AA2CD;;;;;;;;GAQG;AACH,YAAY,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAElE,8CAA8C;AAC9C,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+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;IAC5C;;;;;;OAMG;IACH,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,WAAW,CAAC;CAC7C;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,yBAA8B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAsC5B"}

package/dist/index.js

@@ -14,7 +14,7 @@ import { openWorkflowDir, parseWorkflowScript, WorkflowManager as EngineWorkflow
 import { approveScriptBackends } from "./script-backends.js";
 // ── Engine: run entry, script parsing, the managed-run lifecycle, and the
 //    option/result + error types the host composes against. ──
-export { runWorkflow, parseWorkflowScript, redactText, truncateUtf8 } from "@automatalabs/workflow-engine";
+export { runWorkflow, parseWorkflowScript, hashCheckpointInputs, redactText, truncateUtf8, CALL_PATH_FORMAT, CALL_INPUTS_FORMAT, CHECKPOINT_INPUTS_FORMAT, RESUME_FALLBACK_REASONS, RESUME_DISABLED_REASONS, RESUME_CALL_LIVE_REASONS, RESUME_CALL_FAILED_REASONS, } from "@automatalabs/workflow-engine";
 // ── Isolation mode: deterministic substitution testing over a recorded run. The SDK
 //    wrapper defaults the live target runner to ACP and owns that runner's disposal. ──
 export { runIsolation, createReplayRunner } from "./isolation.js";
@@ -28,6 +28,11 @@ export { openWorkflowDir, } from "@automatalabs/workflow-engine";
 //    the `agentprism-workflows validate` CLI (./cli.ts). ──
 export { validateWorkflowScript, fabricateFromSchema, formatValidateReport, MOCK_TOKENS_PER_AGENT } from "./validate.js";
 export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWorkflowError, isProviderUsageLimit, isAuthRequired, } from "@automatalabs/workflow-engine";
+// ── Durable run-event read/tail seam: the append/read/watch API over the per-run
+//    `<runId>.events.jsonl` sidecar, its error taxonomy, and the read caps (§2.10). A host
+//    attaches to a run's structured event log through these — and `withRunEvents` upgrades a
+//    custom RunPersistence into the seam — without reaching into package internals. ──
+export { withRunEvents, RunEventLogError, RUN_EVENT_READ_LIMIT_DEFAULT, RUN_EVENT_READ_LIMIT_MAX, RUN_EVENT_MAX_RECORD_BYTES, } 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.
@@ -37,9 +42,14 @@ export { AGENTPRISM_PERSISTENCE_ROOT_ENV, WorkflowError, WorkflowErrorCode, isWo
 export { createAcpRunner, AcpAgentRunner, InteractiveSession, selectBackend, ClaudeBackend, CodexBackend, CustomAcpBackend, AGENT_METHODS, CLIENT_METHODS, AGENT_METHOD_COVERAGE, CLIENT_METHOD_COVERAGE, ACP_AUTH_REQUIRED_ERROR_CODE, 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? }`
+//    cross-cutting events; each payload carries a `{ sessionId, backendId, label?, runId?, callIndex? }`
 //    context envelope so a pooled runner's concurrent runs are disambiguable. ──
 export { TypedEventEmitter } from "@automatalabs/acp-agents";
+// ── Shared durable run-event contract: the live/persisted event unions, the engine
+//    event name/payload maps, and the bounded persisted projections (§2.2, §2.5). Re-exported
+//    through the facade so SDK consumers type a durable-log reader without reaching past the SDK
+//    (the ACP-specialized agentEvent branch is bound below as WorkflowAgentEvent/WorkflowRunEvent). ──
+export { RUN_EVENT_LOG_VERSION } from "@automatalabs/shared-types";
 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
@@ -158,6 +168,7 @@ function toSessionUpdateAgentEventPayload(event) {
         backendId: event.backendId,
         label: event.label,
         runId: event.runId,
+        callIndex: event.callIndex,
     });
 }
 function toAgentEventPayload(name, event) {
@@ -169,6 +180,8 @@ function toAgentEventPayload(name, event) {
         ...(context.sessionId !== undefined ? { sessionId: context.sessionId } : {}),
         ...(context.label !== undefined ? { label: context.label } : {}),
         ...(context.runId !== undefined ? { runId: context.runId } : {}),
+        ...(context.runId !== undefined ? { scope: context.runId } : {}),
+        ...(context.callIndex !== undefined ? { callIndex: context.callIndex } : {}),
     };
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automatalabs/workflows",
-  "version": "0.33.1",
+  "version": "0.35.0",
   "license": "Apache-2.0",
   "engines": {
     "node": ">=22"
@@ -31,9 +31,9 @@
   },
   "dependencies": {
     "typebox": "1.3.2",
-    "@automatalabs/shared-types": "0.21.0",
-    "@automatalabs/acp-agents": "0.27.1",
-    "@automatalabs/workflow-engine": "0.22.0"
+    "@automatalabs/shared-types": "0.23.0",
+    "@automatalabs/workflow-engine": "0.24.0",
+    "@automatalabs/acp-agents": "0.28.1"
   },
   "scripts": {
     "build": "tsc -b",