@ekairos/events 1.22.4-beta.development.0

package/dist/context.engine.js

@@ -0,0 +1,1098 @@
+import { registerContextEnv } from "./env.js";
+import { OUTPUT_ITEM_TYPE, WEB_CHANNEL } from "./context.events.js";
+import { applyToolExecutionResultToParts } from "./context.toolcalls.js";
+import { isContextPartEnvelope, normalizePartsForPersistence, } from "./context.parts.js";
+import { toolsToModelTools } from "./tools-to-model-tools.js";
+import { createAiSdkReactor, } from "./context.reactor.js";
+import { abortPersistedContextStepStream, closePersistedContextStepStream, createPersistedContextStepStream, closeContextStream, } from "./steps/stream.steps.js";
+import { completeExecution, createContextStep, initializeContext, saveTriggerAndCreateExecution, saveContextPartsStep, updateContextContent, updateContextStatus, updateItem, updateContextStep, } from "./steps/store.steps.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken, } from "./context.hooks.js";
+import { getContextDurableWorkflow } from "./context.durable.js";
+export async function runContextReactionDirect(context, triggerEvent, params) {
+    return await ContextEngine.runDirect(context, triggerEvent, params);
+}
+export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
+function nowIso() {
+    return new Date().toISOString();
+}
+function clipPreview(value, max = 240) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max)}...`;
+}
+function summarizePartPreview(part) {
+    if (!part || typeof part !== "object")
+        return {};
+    if (isContextPartEnvelope(part)) {
+        const preview = part.content[0]?.type === "text"
+            ? part.content[0].text
+            : JSON.stringify(part.content[0] ?? part);
+        const state = "state" in part && typeof part.state === "string" ? part.state : undefined;
+        const toolCallId = "toolCallId" in part && typeof part.toolCallId === "string"
+            ? part.toolCallId
+            : undefined;
+        return {
+            partPreview: preview ? clipPreview(preview) : undefined,
+            partState: state,
+            partToolCallId: toolCallId,
+        };
+    }
+    const row = part;
+    const partType = typeof row.type === "string" ? row.type : "";
+    const partState = typeof row.state === "string" ? row.state : undefined;
+    const partToolCallId = typeof row.toolCallId === "string"
+        ? row.toolCallId
+        : typeof row.id === "string"
+            ? row.id
+            : undefined;
+    if (typeof row.text === "string" && row.text.trim().length > 0) {
+        return {
+            partPreview: clipPreview(row.text),
+            partState,
+            partToolCallId,
+        };
+    }
+    if (partType.startsWith("tool-")) {
+        const payload = {
+            tool: partType,
+            state: partState,
+            input: row.input,
+            output: row.output,
+            errorText: row.errorText,
+        };
+        return {
+            partPreview: clipPreview(JSON.stringify(payload)),
+            partState,
+            partToolCallId,
+        };
+    }
+    return {
+        partState,
+        partToolCallId,
+    };
+}
+async function emitContextEvents(params) {
+    void params;
+}
+async function measureBenchmark(benchmark, name, run) {
+    if (!benchmark)
+        return await run();
+    return await benchmark.measure(name, run);
+}
+async function readActiveWorkflowRunId() {
+    try {
+        const { getWorkflowMetadata } = await import("workflow");
+        const runId = getWorkflowMetadata?.()?.workflowRunId;
+        return runId ? String(runId) : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function createRuntimeOps(env, benchmark) {
+    const { getContextRuntime } = await import("./runtime.js");
+    const runtime = await getContextRuntime(env);
+    const { db } = runtime;
+    const { InstantStore } = await import("./stores/instant.store.js");
+    const requireContextId = (contextIdentifier) => {
+        if ("id" in contextIdentifier && typeof contextIdentifier.id === "string" && contextIdentifier.id) {
+            return String(contextIdentifier.id);
+        }
+        throw new Error("ContextEngine direct runtime requires resolved context ids.");
+    };
+    const makeRuntimeId = () => globalThis.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const instrumentAsync = async (kind, run) => {
+        const startedAt = Date.now();
+        try {
+            return await run();
+        }
+        finally {
+            const elapsedMs = Date.now() - startedAt;
+            benchmark?.add?.("react.network.totalMs", elapsedMs);
+            benchmark?.add?.(`react.network.${kind}Ms`, elapsedMs);
+            benchmark?.add?.(`react.network.${kind}Count`, 1);
+            const currentStage = benchmark?.getCurrentStage?.();
+            if (currentStage) {
+                benchmark?.add?.(`${currentStage}.networkMs`, elapsedMs);
+                benchmark?.add?.(`${currentStage}.${kind}Count`, 1);
+            }
+        }
+    };
+    const instrumentedDb = new Proxy(db, {
+        get(target, prop, receiver) {
+            if (prop === "query") {
+                return async (...args) => await instrumentAsync("query", async () => await target.query(...args));
+            }
+            if (prop === "transact") {
+                return async (...args) => await instrumentAsync("transact", async () => await target.transact(...args));
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+    const store = new InstantStore(instrumentedDb);
+    return {
+        db: instrumentedDb,
+        initializeContext: async (contextIdentifier) => {
+            if (!contextIdentifier) {
+                const context = await store.getOrCreateContext(null);
+                return { context, isNew: true };
+            }
+            const existing = await store.getContext(contextIdentifier);
+            if (existing) {
+                return { context: existing, isNew: false };
+            }
+            const context = await store.getOrCreateContext(contextIdentifier);
+            return { context, isNew: true };
+        },
+        updateContextContent: async (contextIdentifier, content) => await store.updateContextContent(contextIdentifier, content),
+        updateContextStatus: async (contextIdentifier, status) => await instrumentedDb.transact([
+            instrumentedDb.tx.event_contexts[requireContextId(contextIdentifier)].update({
+                status,
+                updatedAt: new Date(),
+            }),
+        ]),
+        saveTriggerAndCreateExecution: async ({ contextIdentifier, triggerEvent }) => {
+            const contextId = requireContextId(contextIdentifier);
+            const triggerId = String(triggerEvent.id);
+            const reactionId = makeRuntimeId();
+            const executionId = makeRuntimeId();
+            const reactionEvent = {
+                id: reactionId,
+                type: OUTPUT_ITEM_TYPE,
+                channel: typeof triggerEvent.channel === "string"
+                    ? triggerEvent.channel
+                    : WEB_CHANNEL,
+                createdAt: new Date().toISOString(),
+                status: "pending",
+                content: { parts: [] },
+            };
+            const now = new Date();
+            await instrumentedDb.transact([
+                instrumentedDb.tx.event_items[triggerId].update({
+                    ...triggerEvent,
+                    id: triggerId,
+                    status: "stored",
+                }),
+                instrumentedDb.tx.event_items[triggerId].link({ context: contextId }),
+                instrumentedDb.tx.event_items[reactionId].update({
+                    ...reactionEvent,
+                    id: reactionId,
+                    status: "pending",
+                }),
+                instrumentedDb.tx.event_items[reactionId].link({ context: contextId }),
+                instrumentedDb.tx.event_executions[executionId].create({
+                    createdAt: now,
+                    updatedAt: now,
+                    status: "executing",
+                }),
+                instrumentedDb.tx.event_executions[executionId].link({ context: contextId }),
+                instrumentedDb.tx.event_executions[executionId].link({ trigger: triggerId }),
+                instrumentedDb.tx.event_executions[executionId].link({ reaction: reactionId }),
+                instrumentedDb.tx.event_items[triggerId].link({ execution: executionId }),
+                instrumentedDb.tx.event_items[reactionId].link({ execution: executionId }),
+                instrumentedDb.tx.event_contexts[contextId].update({
+                    status: "open_streaming",
+                    updatedAt: now,
+                }),
+                instrumentedDb.tx.event_contexts[contextId].link({ currentExecution: executionId }),
+            ]);
+            return {
+                triggerEvent: {
+                    ...triggerEvent,
+                    id: triggerId,
+                    status: "stored",
+                },
+                reactionEvent,
+                execution: {
+                    id: executionId,
+                    status: "executing",
+                },
+            };
+        },
+        createContextStep: async ({ executionId, iteration }) => {
+            const stepId = makeRuntimeId();
+            await instrumentedDb.transact([
+                instrumentedDb.tx.event_steps[stepId].create({
+                    createdAt: new Date(),
+                    updatedAt: new Date(),
+                    status: "running",
+                    iteration,
+                }),
+                instrumentedDb.tx.event_steps[stepId].link({ execution: executionId }),
+            ]);
+            return { stepId };
+        },
+        updateContextStep: async (params) => {
+            await instrumentedDb.transact([
+                instrumentedDb.tx.event_steps[params.stepId].update({
+                    ...params.patch,
+                    updatedAt: new Date(),
+                }),
+            ]);
+        },
+        saveContextPartsStep: async (params) => {
+            await store.saveStepParts({ stepId: params.stepId, parts: params.parts });
+        },
+        updateItem: async (itemId, item) => {
+            await instrumentedDb.transact([instrumentedDb.tx.event_items[itemId].update(item)]);
+            return {
+                ...item,
+                id: itemId,
+            };
+        },
+        completeExecution: async (contextIdentifier, executionId, status) => {
+            const contextId = requireContextId(contextIdentifier);
+            await instrumentedDb.transact([
+                instrumentedDb.tx.event_executions[executionId].update({
+                    status,
+                    updatedAt: new Date(),
+                }),
+                instrumentedDb.tx.event_contexts[contextId].update({
+                    status: "closed",
+                    updatedAt: new Date(),
+                }),
+            ]);
+        },
+    };
+}
+async function createWorkflowOps(env) {
+    return {
+        initializeContext: async (contextIdentifier, opts) => await initializeContext(env, contextIdentifier, opts),
+        updateContextContent: async (contextIdentifier, content) => await updateContextContent(env, contextIdentifier, content),
+        updateContextStatus: async (contextIdentifier, status) => await updateContextStatus(env, contextIdentifier, status),
+        saveTriggerAndCreateExecution: async ({ contextIdentifier, triggerEvent }) => await saveTriggerAndCreateExecution({ env, contextIdentifier, triggerEvent }),
+        createContextStep: async ({ executionId, iteration }) => await createContextStep({ env, executionId, iteration }),
+        updateContextStep: async (params) => await updateContextStep({ env, ...params }),
+        saveContextPartsStep: async (params) => await saveContextPartsStep({ env, ...params }),
+        updateItem: async (itemId, item, opts) => await updateItem(env, itemId, item, opts),
+        completeExecution: async (contextIdentifier, executionId, status) => await completeExecution(env, contextIdentifier, executionId, status),
+    };
+}
+async function getContextEngineOps(env, benchmark) {
+    const workflowRunId = await readActiveWorkflowRunId();
+    if (workflowRunId) {
+        registerContextEnv(env, workflowRunId);
+        return await createWorkflowOps(env);
+    }
+    registerContextEnv(env);
+    return await createRuntimeOps(env, benchmark);
+}
+export class ContextEngine {
+    constructor(opts = {}, reactor) {
+        this.opts = opts;
+        this.reactor = reactor ?? createAiSdkReactor();
+    }
+    async buildSkills(_context, _env) {
+        return [];
+    }
+    /**
+     * First-class event expansion stage (runs on every iteration of the durable loop).
+     *
+     * Use this to expand/normalize events before they are converted into model messages.
+     * Typical use-cases:
+     * - Expand file/document references into text (LlamaCloud/Reducto/…)
+     * - Token compaction / summarization of older parts
+     * - Attaching derived context snippets to the next model call
+     *
+     * IMPORTANT:
+     * - This stage is ALWAYS executed by the engine.
+     * - If you don't provide an implementation, the default behavior is an identity transform
+     *   (events pass through unchanged).
+     * - If your implementation performs I/O, implement it as a `"use-step"` function (provided via
+     *   the builder) so results are durable and replay-safe.
+     * - If it’s pure/deterministic, it can run in workflow context.
+     */
+    async expandEvents(events, _context, _env) {
+        return events;
+    }
+    getModel(_context, _env) {
+        return "openai/gpt-5";
+    }
+    getReactor(_context, _env) {
+        return this.reactor;
+    }
+    /**
+     * Context stop/continue hook.
+     *
+     * After the model streamed and tools executed, the story can decide whether the loop should
+     * continue.
+     *
+     * Default: `true` (continue).
+     */
+    async shouldContinue(_args) {
+        return true;
+    }
+    async react(triggerEvent, params) {
+        if (params.durable) {
+            return await ContextEngine.startDurable(this, triggerEvent, params);
+        }
+        return await ContextEngine.runDirect(this, triggerEvent, params);
+    }
+    static async prepareExecutionShell(story, triggerEvent, params) {
+        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.env, params.__benchmark));
+        const silent = params.options?.silent ?? false;
+        const ctxResult = await measureBenchmark(params.__benchmark, "react.initializeContextMs", async () => await ops.initializeContext(params.context ?? null, { silent }));
+        let currentContext = ctxResult.context;
+        const contextSelector = { id: String(currentContext.id) };
+        if (ctxResult.isNew) {
+            await story.opts.onContextCreated?.({ env: params.env, context: currentContext });
+        }
+        if (currentContext.status === "closed") {
+            await measureBenchmark(params.__benchmark, "react.reopenClosedContextMs", async () => await ops.updateContextStatus(contextSelector, "open_idle"));
+            currentContext = { ...currentContext, status: "open_idle" };
+        }
+        const shell = await measureBenchmark(params.__benchmark, "react.bootstrapShellMs", async () => await ops.saveTriggerAndCreateExecution({
+            contextIdentifier: contextSelector,
+            triggerEvent,
+        }));
+        currentContext = { ...currentContext, status: "open_streaming" };
+        return {
+            contextSelector,
+            currentContext,
+            trigger: shell.triggerEvent,
+            reaction: shell.reactionEvent,
+            execution: shell.execution,
+        };
+    }
+    static async startDurable(story, triggerEvent, params) {
+        if (params.options?.writable) {
+            throw new Error("ContextEngine.react: durable runs manage their own workflow stream");
+        }
+        const contextKey = typeof story.__contextKey === "string" ? String(story.__contextKey) : "";
+        if (!contextKey) {
+            throw new Error("ContextEngine.react: durable mode requires a context built with createContext(...).build().");
+        }
+        const workflow = getContextDurableWorkflow();
+        if (typeof workflow !== "function") {
+            throw new Error("ContextEngine.react: durable workflow is not configured. Call configureContextDurableWorkflow(...) in runtime bootstrap.");
+        }
+        const shell = await ContextEngine.prepareExecutionShell(story, triggerEvent, params);
+        try {
+            const [{ start }] = await Promise.all([
+                import("workflow/api"),
+            ]);
+            const run = await start(workflow, [
+                {
+                    contextKey,
+                    env: params.env,
+                    context: params.context ?? null,
+                    triggerEvent,
+                    options: {
+                        maxIterations: params.options?.maxIterations,
+                        maxModelSteps: params.options?.maxModelSteps,
+                        preventClose: params.options?.preventClose,
+                        sendFinish: params.options?.sendFinish,
+                        silent: params.options?.silent,
+                    },
+                    bootstrap: {
+                        contextId: shell.currentContext.id,
+                        trigger: shell.trigger,
+                        reaction: shell.reaction,
+                        execution: shell.execution,
+                    },
+                },
+            ]);
+            const runtime = await createRuntimeOps(params.env);
+            await runtime.db.transact([
+                runtime.db.tx.event_executions[shell.execution.id].update({
+                    workflowRunId: run.runId,
+                    updatedAt: new Date(),
+                }),
+            ]);
+        }
+        catch (error) {
+            const ops = await getContextEngineOps(params.env, params.__benchmark);
+            await ops.completeExecution(shell.contextSelector, shell.execution.id, "failed").catch(() => null);
+            throw error;
+        }
+        return {
+            context: shell.currentContext,
+            trigger: shell.trigger,
+            reaction: shell.reaction,
+            execution: shell.execution,
+        };
+    }
+    static async runDirect(story, triggerEvent, params) {
+        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.env, params.__benchmark));
+        const maxIterations = params.options?.maxIterations ?? 20;
+        const maxModelSteps = params.options?.maxModelSteps ?? 1;
+        const preventClose = params.options?.preventClose ?? false;
+        const sendFinish = params.options?.sendFinish ?? true;
+        const silent = params.options?.silent ?? false;
+        const writable = params.options?.writable;
+        const bootstrapped = params.__bootstrap;
+        const shell = bootstrapped
+            ? {
+                contextSelector: { id: String(bootstrapped.contextId) },
+                currentContext: (await measureBenchmark(params.__benchmark, "react.bootstrapContextLookupMs", async () => await ops.initializeContext({ id: String(bootstrapped.contextId) }, { silent }))).context,
+                trigger: bootstrapped.trigger,
+                reaction: bootstrapped.reaction,
+                execution: bootstrapped.execution,
+            }
+            : await ContextEngine.prepareExecutionShell(story, triggerEvent, params);
+        let currentContext = shell.currentContext;
+        let trigger = shell.trigger;
+        let reactionEvent = shell.reaction;
+        let execution = shell.execution;
+        const activeContextSelector = shell.contextSelector;
+        const triggerEventId = trigger.id;
+        const reactionEventId = reactionEvent.id;
+        const executionId = execution.id;
+        let updatedContext = { ...currentContext, status: "open_streaming" };
+        let currentStepId = null;
+        let currentStepStream = null;
+        const failExecution = async () => {
+            try {
+                await ops.completeExecution(activeContextSelector, executionId, "failed");
+                execution = { ...execution, status: "failed" };
+                updatedContext = { ...updatedContext, status: "closed" };
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: [
+                        {
+                            type: "execution.failed",
+                            at: nowIso(),
+                            executionId,
+                            contextId: String(currentContext.id),
+                            status: "failed",
+                        },
+                        {
+                            type: "context.status_changed",
+                            at: nowIso(),
+                            contextId: String(currentContext.id),
+                            status: "closed",
+                        },
+                    ],
+                });
+            }
+            catch {
+                // noop
+            }
+            try {
+                if (!silent) {
+                    await closeContextStream({ preventClose, sendFinish, writable });
+                }
+            }
+            catch {
+                // noop
+            }
+        };
+        try {
+            for (let iter = 0; iter < maxIterations; iter++) {
+                // Create a persisted step per iteration (IDs generated in step runtime for replay safety)
+                const stagePrefix = `react.iteration.${iter}`;
+                const stepCreate = await measureBenchmark(params.__benchmark, `${stagePrefix}.createStepMs`, async () => await ops.createContextStep({
+                    executionId,
+                    iteration: iter,
+                }));
+                currentStepId = stepCreate.stepId;
+                currentStepStream = await createPersistedContextStepStream({
+                    env: params.env,
+                    executionId,
+                    stepId: stepCreate.stepId,
+                });
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: [
+                        {
+                            type: "step.created",
+                            at: nowIso(),
+                            stepId: String(stepCreate.stepId),
+                            executionId,
+                            iteration: iter,
+                            status: "running",
+                        },
+                    ],
+                });
+                // Hook: Context DSL `context()` (implemented by subclasses via `initialize()`)
+                const nextContent = await measureBenchmark(params.__benchmark, `${stagePrefix}.contextMs`, async () => await story.initialize(updatedContext, params.env));
+                updatedContext = await measureBenchmark(params.__benchmark, `${stagePrefix}.persistContextMs`, async () => await ops.updateContextContent(activeContextSelector, nextContent));
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: [
+                        {
+                            type: "context.content_updated",
+                            at: nowIso(),
+                            contextId: String(updatedContext.id),
+                        },
+                    ],
+                });
+                await story.opts.onContextUpdated?.({ env: params.env, context: updatedContext });
+                // Hook: Context DSL `narrative()` (implemented by subclasses via `buildSystemPrompt()`)
+                const systemPrompt = await measureBenchmark(params.__benchmark, `${stagePrefix}.narrativeMs`, async () => await story.buildSystemPrompt(updatedContext, params.env));
+                // Hook: Context DSL `actions()` (implemented by subclasses via `buildTools()`)
+                const toolsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.actionsMs`, async () => await story.buildTools(updatedContext, params.env));
+                const skillsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.skillsMs`, async () => await story.buildSkills(updatedContext, params.env));
+                // IMPORTANT: step args must be serializable.
+                // Match DurableAgent behavior: convert tool input schemas to plain JSON Schema in workflow context.
+                const toolsForModel = toolsToModelTools(toolsAll);
+                // Execute model reaction for this iteration using the stable reaction event id.
+                //
+                // IMPORTANT:
+                // We expose a single visible `context_event` per story turn (`reactionEventId`).
+                // If we stream with a per-step id, the UI will render an optimistic assistant message
+                // (step id) and then a second persisted assistant message (reaction id) with the same
+                // content once InstantDB updates.
+                const reactor = story.getReactor(updatedContext, params.env);
+                const reactionPartsBeforeStep = Array.isArray(reactionEvent.content?.parts)
+                    ? [...reactionEvent.content.parts]
+                    : [];
+                let persistedReactionPartsSignature = "";
+                const persistReactionParts = async (nextParts) => {
+                    const normalizedParts = normalizePartsForPersistence(Array.isArray(nextParts) ? nextParts : []);
+                    const nextSignature = JSON.stringify(normalizedParts);
+                    if (nextSignature === persistedReactionPartsSignature)
+                        return;
+                    persistedReactionPartsSignature = nextSignature;
+                    await ops.saveContextPartsStep({
+                        stepId: stepCreate.stepId,
+                        parts: normalizedParts,
+                        executionId,
+                        contextId: String(currentContext.id),
+                        iteration: iter,
+                    });
+                    reactionEvent = await ops.updateItem(reactionEvent.id, {
+                        ...reactionEvent,
+                        content: {
+                            ...reactionEvent.content,
+                            parts: [...reactionPartsBeforeStep, ...normalizedParts],
+                        },
+                        status: "pending",
+                    }, { executionId, contextId: String(currentContext.id) });
+                };
+                const { assistantEvent, actionRequests, messagesForModel } = await measureBenchmark(params.__benchmark, `${stagePrefix}.reactorMs`, async () => await reactor({
+                    env: params.env,
+                    context: updatedContext,
+                    contextIdentifier: activeContextSelector,
+                    triggerEvent,
+                    model: story.getModel(updatedContext, params.env),
+                    systemPrompt,
+                    actions: toolsAll,
+                    toolsForModel,
+                    skills: skillsAll,
+                    eventId: reactionEventId,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    stepId: String(stepCreate.stepId),
+                    iteration: iter,
+                    maxModelSteps,
+                    // Only emit a `start` chunk once per story turn.
+                    sendStart: !silent && iter === 0,
+                    silent,
+                    contextStepStream: currentStepStream?.stream,
+                    writable,
+                    persistReactionParts,
+                }));
+                const reviewRequests = actionRequests.length > 0
+                    ? actionRequests.flatMap((actionRequest) => {
+                        const toolDef = toolsAll[actionRequest.actionName];
+                        const auto = toolDef?.auto !== false;
+                        actionRequest.auto = auto;
+                        if (auto)
+                            return [];
+                        return [
+                            {
+                                toolCallId: String(actionRequest.actionRef),
+                                toolName: String(actionRequest.actionName ?? ""),
+                            },
+                        ];
+                    })
+                    : [];
+                // Persist normalized parts hanging off the producing step (event_parts).
+                // IMPORTANT:
+                // We intentionally do NOT persist the per-step LLM assistant event as a `context_event`.
+                // The story exposes a single visible `context_event` per turn (`reactionEventId`) so the UI
+                // doesn't render duplicate assistant messages (LLM-step + aggregated reaction).
+                const stepParts = normalizePartsForPersistence((assistantEvent?.content?.parts ?? []));
+                const assistantEventEffective = {
+                    ...assistantEvent,
+                    content: {
+                        ...(assistantEvent?.content ?? {}),
+                        parts: stepParts,
+                    },
+                };
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.saveStepPartsMs`, async () => await ops.saveContextPartsStep({
+                    stepId: stepCreate.stepId,
+                    parts: stepParts,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: stepParts.map((part, idx) => ({
+                        type: "part.created",
+                        at: nowIso(),
+                        partKey: `${String(stepCreate.stepId)}:${idx}`,
+                        stepId: String(stepCreate.stepId),
+                        idx,
+                        partType: part && typeof part.type === "string"
+                            ? String(part.type)
+                            : undefined,
+                        ...summarizePartPreview(part),
+                    })),
+                });
+                // Persist/append the aggregated reaction event (stable `reactionEventId` for the execution).
+                const nextAssistantParts = Array.isArray(assistantEventEffective.content?.parts)
+                    ? assistantEventEffective.content.parts
+                    : [];
+                const nextReactionEvent = {
+                    ...reactionEvent,
+                    content: {
+                        ...reactionEvent.content,
+                        parts: [...reactionPartsBeforeStep, ...nextAssistantParts],
+                    },
+                    status: "pending",
+                };
+                reactionEvent = await measureBenchmark(params.__benchmark, `${stagePrefix}.persistAssistantReactionMs`, async () => await ops.updateItem(reactionEvent.id, nextReactionEvent, { executionId, contextId: String(currentContext.id) }));
+                if (currentStepStream) {
+                    await closePersistedContextStepStream({
+                        env: params.env,
+                        session: currentStepStream,
+                    });
+                    currentStepStream = null;
+                }
+                story.opts.onEventCreated?.(assistantEventEffective);
+                const firstActionRequest = actionRequests?.[0];
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.markStepRunningMs`, async () => await ops.updateContextStep({
+                    stepId: stepCreate.stepId,
+                    patch: firstActionRequest
+                        ? {
+                            kind: "action_execute",
+                            actionName: typeof firstActionRequest.actionName === "string"
+                                ? firstActionRequest.actionName
+                                : undefined,
+                            actionInput: firstActionRequest.input,
+                        }
+                        : {
+                            kind: "message",
+                        },
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: [
+                        {
+                            type: "step.updated",
+                            at: nowIso(),
+                            stepId: String(stepCreate.stepId),
+                            executionId,
+                            iteration: iter,
+                            status: "running",
+                            kind: firstActionRequest ? "action_execute" : "message",
+                            actionName: firstActionRequest && typeof firstActionRequest.actionName === "string"
+                                ? firstActionRequest.actionName
+                                : undefined,
+                        },
+                    ],
+                });
+                // Done: no tool calls requested by the model
+                if (!actionRequests.length) {
+                    const endResult = await story.callOnEnd(assistantEventEffective);
+                    if (endResult) {
+                        // Mark iteration step completed (no tools)
+                        await measureBenchmark(params.__benchmark, `${stagePrefix}.finalizeMessageStepMs`, async () => await ops.updateContextStep({
+                            stepId: stepCreate.stepId,
+                            patch: {
+                                status: "completed",
+                                kind: "message",
+                                actionRequests: [],
+                                actionResults: [],
+                                continueLoop: false,
+                            },
+                            executionId,
+                            contextId: String(currentContext.id),
+                            iteration: iter,
+                        }));
+                        await emitContextEvents({
+                            silent,
+                            writable,
+                            events: [
+                                {
+                                    type: "step.updated",
+                                    at: nowIso(),
+                                    stepId: String(stepCreate.stepId),
+                                    executionId,
+                                    iteration: iter,
+                                    status: "completed",
+                                    kind: "message",
+                                },
+                                {
+                                    type: "step.completed",
+                                    at: nowIso(),
+                                    stepId: String(stepCreate.stepId),
+                                    executionId,
+                                    iteration: iter,
+                                    status: "completed",
+                                },
+                            ],
+                        });
+                        // Mark reaction event completed
+                        await measureBenchmark(params.__benchmark, `${stagePrefix}.completeReactionMs`, async () => await ops.updateItem(reactionEventId, {
+                            ...reactionEvent,
+                            status: "completed",
+                        }, { executionId, contextId: String(currentContext.id) }));
+                        await emitContextEvents({
+                            silent,
+                            writable,
+                            events: [
+                                {
+                                    type: "item.completed",
+                                    at: nowIso(),
+                                    itemId: String(reactionEventId),
+                                    contextId: String(currentContext.id),
+                                    executionId,
+                                    status: "completed",
+                                },
+                            ],
+                        });
+                        await measureBenchmark(params.__benchmark, `${stagePrefix}.completeExecutionMs`, async () => await ops.completeExecution(activeContextSelector, executionId, "completed"));
+                        execution = { ...execution, status: "completed" };
+                        updatedContext = { ...updatedContext, status: "closed" };
+                        await emitContextEvents({
+                            silent,
+                            writable,
+                            events: [
+                                {
+                                    type: "execution.completed",
+                                    at: nowIso(),
+                                    executionId,
+                                    contextId: String(currentContext.id),
+                                    status: "completed",
+                                },
+                                {
+                                    type: "context.status_changed",
+                                    at: nowIso(),
+                                    contextId: String(currentContext.id),
+                                    status: "closed",
+                                },
+                            ],
+                        });
+                        if (!silent) {
+                            await closeContextStream({ preventClose, sendFinish, writable });
+                        }
+                        reactionEvent = {
+                            ...reactionEvent,
+                            status: "completed",
+                        };
+                        return {
+                            context: updatedContext,
+                            trigger,
+                            reaction: reactionEvent,
+                            execution,
+                        };
+                    }
+                }
+                // Execute actions (workflow context; action implementations decide step vs workflow)
+                const actionResults = await measureBenchmark(params.__benchmark, `${stagePrefix}.actionExecutionMs`, async () => await Promise.all(actionRequests.map(async (actionRequest) => {
+                    const toolDef = toolsAll[actionRequest.actionName];
+                    if (!toolDef || typeof toolDef.execute !== "function") {
+                        return {
+                            actionRequest,
+                            success: false,
+                            output: null,
+                            errorText: `Action "${actionRequest.actionName}" not found or has no execute().`,
+                        };
+                    }
+                    try {
+                        let actionInput = actionRequest.input;
+                        if (toolDef?.auto === false) {
+                            const { createHook, createWebhook } = await import("workflow");
+                            const toolCallId = String(actionRequest.actionRef);
+                            const hookToken = toolApprovalHookToken({ executionId, toolCallId });
+                            const webhookToken = toolApprovalWebhookToken({ executionId, toolCallId });
+                            const hook = createHook({ token: hookToken });
+                            const webhook = createWebhook({ token: webhookToken });
+                            const approvalOrRequest = await Promise.race([
+                                hook.then((approval) => ({ source: "hook", approval })),
+                                webhook.then((request) => ({ source: "webhook", request })),
+                            ]);
+                            const approval = approvalOrRequest.source === "hook"
+                                ? approvalOrRequest.approval
+                                : await approvalOrRequest.request.json().catch(() => null);
+                            if (!approval || approval.approved !== true) {
+                                return {
+                                    actionRequest,
+                                    success: false,
+                                    output: null,
+                                    errorText: approval && "comment" in approval && approval.comment
+                                        ? `Action execution not approved: ${approval.comment}`
+                                        : "Action execution not approved",
+                                };
+                            }
+                            if ("args" in approval && approval.args !== undefined) {
+                                actionInput = approval.args;
+                            }
+                        }
+                        const output = await toolDef.execute(actionInput, {
+                            toolCallId: actionRequest.actionRef,
+                            messages: messagesForModel,
+                            eventId: reactionEventId,
+                            executionId,
+                            triggerEventId,
+                            contextId: currentContext.id,
+                        });
+                        return { actionRequest, success: true, output };
+                    }
+                    catch (e) {
+                        return {
+                            actionRequest,
+                            success: false,
+                            output: null,
+                            errorText: e instanceof Error ? e.message : String(e),
+                        };
+                    }
+                })));
+                // Merge action results into persisted parts (so next LLM call can see them)
+                let finalizedStepParts = Array.isArray(stepParts) ? [...stepParts] : [];
+                for (const r of actionResults) {
+                    finalizedStepParts = applyToolExecutionResultToParts(finalizedStepParts, {
+                        toolCallId: r.actionRequest.actionRef,
+                        toolName: r.actionRequest.actionName,
+                    }, {
+                        success: Boolean(r.success),
+                        result: r.output,
+                        message: r.errorText,
+                    });
+                }
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.saveFinalStepPartsMs`, async () => await ops.saveContextPartsStep({
+                    stepId: stepCreate.stepId,
+                    parts: finalizedStepParts,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
+                reactionEvent = {
+                    ...reactionEvent,
+                    content: {
+                        ...reactionEvent.content,
+                        // Deprecated mirror for compatibility. `event_parts` are the
+                        // source of truth for replay and step inspection.
+                        parts: [...reactionPartsBeforeStep, ...finalizedStepParts],
+                    },
+                    status: "pending",
+                };
+                // Callback for observability/integration
+                for (const r of actionResults) {
+                    await story.opts.onActionExecuted?.({
+                        actionRequest: r.actionRequest,
+                        success: r.success,
+                        output: r.output,
+                        errorText: r.errorText,
+                        eventId: reactionEventId,
+                        executionId,
+                    });
+                }
+                // Stop/continue boundary: allow the Context to decide if the loop should continue.
+                // IMPORTANT: we call this after tool results have been merged into the persisted `reactionEvent`,
+                // so stories can inspect `reactionEvent.content.parts` deterministically.
+                const continueLoop = await measureBenchmark(params.__benchmark, `${stagePrefix}.shouldContinueMs`, async () => await story.shouldContinue({
+                    env: params.env,
+                    context: updatedContext,
+                    reactionEvent,
+                    assistantEvent: assistantEventEffective,
+                    actionRequests,
+                    actionResults: actionResults,
+                }));
+                // Persist per-iteration step outcome (tools + continue signal)
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.completeStepMs`, async () => await ops.updateContextStep({
+                    stepId: stepCreate.stepId,
+                    patch: {
+                        status: "completed",
+                        kind: actionRequests?.length ? "action_result" : "message",
+                        actionName: typeof actionResults?.[0]?.actionRequest?.actionName === "string"
+                            ? actionResults[0].actionRequest.actionName
+                            : undefined,
+                        actionInput: actionResults?.[0]?.actionRequest?.input,
+                        actionOutput: actionResults?.[0]?.success === true
+                            ? actionResults[0]?.output
+                            : undefined,
+                        actionError: actionResults?.[0]?.success === false
+                            ? String(actionResults[0]?.errorText ?? "action_execution_failed")
+                            : undefined,
+                        actionRequests,
+                        actionResults,
+                        continueLoop: continueLoop !== false,
+                    },
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
+                await emitContextEvents({
+                    silent,
+                    writable,
+                    events: [
+                        {
+                            type: "step.updated",
+                            at: nowIso(),
+                            stepId: String(stepCreate.stepId),
+                            executionId,
+                            iteration: iter,
+                            status: "completed",
+                            kind: actionRequests?.length ? "action_result" : "message",
+                            actionName: typeof actionResults?.[0]?.actionRequest?.actionName === "string"
+                                ? actionResults[0].actionRequest.actionName
+                                : undefined,
+                        },
+                        {
+                            type: "step.completed",
+                            at: nowIso(),
+                            stepId: String(stepCreate.stepId),
+                            executionId,
+                            iteration: iter,
+                            status: "completed",
+                        },
+                    ],
+                });
+                if (continueLoop !== false) {
+                    reactionEvent = await measureBenchmark(params.__benchmark, `${stagePrefix}.persistPendingReactionMs`, async () => await ops.updateItem(reactionEventId, {
+                        ...reactionEvent,
+                        status: "pending",
+                    }, { executionId, contextId: String(currentContext.id) }));
+                    await emitContextEvents({
+                        silent,
+                        writable,
+                        events: [
+                            {
+                                type: "item.updated",
+                                at: nowIso(),
+                                itemId: String(reactionEventId),
+                                contextId: String(currentContext.id),
+                                executionId,
+                                status: "pending",
+                            },
+                        ],
+                    });
+                }
+                if (continueLoop === false) {
+                    await measureBenchmark(params.__benchmark, `${stagePrefix}.completeReactionMs`, async () => await ops.updateItem(reactionEventId, {
+                        ...reactionEvent,
+                        status: "completed",
+                    }, { executionId, contextId: String(currentContext.id) }));
+                    await emitContextEvents({
+                        silent,
+                        writable,
+                        events: [
+                            {
+                                type: "item.completed",
+                                at: nowIso(),
+                                itemId: String(reactionEventId),
+                                contextId: String(currentContext.id),
+                                executionId,
+                                status: "completed",
+                            },
+                        ],
+                    });
+                    await measureBenchmark(params.__benchmark, `${stagePrefix}.completeExecutionMs`, async () => await ops.completeExecution(activeContextSelector, executionId, "completed"));
+                    execution = { ...execution, status: "completed" };
+                    updatedContext = { ...updatedContext, status: "closed" };
+                    await emitContextEvents({
+                        silent,
+                        writable,
+                        events: [
+                            {
+                                type: "execution.completed",
+                                at: nowIso(),
+                                executionId,
+                                contextId: String(currentContext.id),
+                                status: "completed",
+                            },
+                            {
+                                type: "context.status_changed",
+                                at: nowIso(),
+                                contextId: String(currentContext.id),
+                                status: "closed",
+                            },
+                        ],
+                    });
+                    if (!silent) {
+                        await closeContextStream({ preventClose, sendFinish, writable });
+                    }
+                    reactionEvent = {
+                        ...reactionEvent,
+                        status: "completed",
+                    };
+                    return {
+                        context: updatedContext,
+                        trigger,
+                        reaction: reactionEvent,
+                        execution,
+                    };
+                }
+            }
+            throw new Error(`ContextEngine: maxIterations reached (${maxIterations}) without completion`);
+        }
+        catch (error) {
+            if (currentStepStream) {
+                try {
+                    await abortPersistedContextStepStream({
+                        env: params.env,
+                        session: currentStepStream,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                catch {
+                    // noop
+                }
+                finally {
+                    currentStepStream = null;
+                }
+            }
+            // Best-effort: persist failure on the current iteration step (if any)
+            if (currentStepId) {
+                const failedStepId = currentStepId;
+                try {
+                    await measureBenchmark(params.__benchmark, "react.failureStepPersistMs", async () => await ops.updateContextStep({
+                        stepId: failedStepId,
+                        patch: {
+                            status: "failed",
+                            errorText: error instanceof Error ? error.message : String(error),
+                        },
+                        executionId,
+                        contextId: String(currentContext.id),
+                    }));
+                    await emitContextEvents({
+                        silent,
+                        writable,
+                        events: [
+                            {
+                                type: "step.failed",
+                                at: nowIso(),
+                                stepId: String(failedStepId),
+                                executionId,
+                                status: "failed",
+                                errorText: error instanceof Error ? error.message : String(error),
+                            },
+                        ],
+                    });
+                }
+                catch {
+                    // noop
+                }
+            }
+            await failExecution();
+            throw error;
+        }
+    }
+    /**
+     * @deprecated Use `react()` instead. Kept for backwards compatibility.
+     */
+    async stream(triggerEvent, params) {
+        return await this.react(triggerEvent, params);
+    }
+    async callOnEnd(lastEvent) {
+        if (!this.opts.onEnd)
+            return true;
+        const result = await this.opts.onEnd(lastEvent);
+        if (typeof result === "boolean")
+            return result;
+        return true;
+    }
+}