@ekairos/thread 1.21.88-beta.0

package/dist/story.engine.d.ts

@@ -0,0 +1,224 @@
+import type { Tool, UIMessageChunk } from "ai";
+import type { StoryEnvironment } from "./story.config.js";
+import type { ContextEvent, ContextIdentifier, StoredContext } from "./story.store.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken } from "./story.hooks.js";
+export interface StoryOptions<Context = any, Env extends StoryEnvironment = StoryEnvironment> {
+    onContextCreated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onContextUpdated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onEventCreated?: (event: ContextEvent) => void | Promise<void>;
+    onToolCallExecuted?: (executionEvent: any) => void | Promise<void>;
+    onEnd?: (lastEvent: ContextEvent) => void | {
+        end?: boolean;
+    } | Promise<void | {
+        end?: boolean;
+    }>;
+}
+export interface StoryStreamOptions {
+    /**
+     * Maximum loop iterations (LLM call → tool execution → repeat).
+     * Default: 20
+     */
+    maxIterations?: number;
+    /**
+     * Maximum model steps per LLM call.
+     * Default: 1 (or 5 if you override it in your implementation).
+     */
+    maxModelSteps?: number;
+    /**
+     * If true, we do not close the workflow writable stream.
+     * Default: false.
+     */
+    preventClose?: boolean;
+    /**
+     * If true, we write a `finish` chunk to the workflow stream.
+     * Default: true.
+     */
+    sendFinish?: boolean;
+    /**
+     * If true, the story loop runs silently (no UI streaming output).
+     *
+     * Persistence (contexts/events/executions) still happens normally.
+     *
+     * Default: false.
+     */
+    silent?: boolean;
+    /**
+     * Optional workflow writable stream to emit UIMessageChunks into.
+     *
+     * When omitted, the story will obtain a namespaced writable automatically:
+     * `getWritable({ namespace: "context:<contextId>" })`.
+     *
+     * This allows multiple stories / contexts to stream concurrently within the same workflow run.
+     */
+    writable?: WritableStream<UIMessageChunk>;
+}
+/**
+ * Model initializer (DurableAgent-style).
+ *
+ * - `string`: Vercel AI Gateway model id (e.g. `"openai/gpt-5"`), resolved inside the LLM step.
+ * - `function`: a function that returns a model instance. For Workflow compatibility, this should
+ *   be a `"use-step"` function (so it can be serialized by reference).
+ */
+export type StoryModelInit = string | (() => Promise<any>) | any;
+export type StoryReactParams<Env extends StoryEnvironment = StoryEnvironment> = {
+    env: Env;
+    /**
+     * Context selector (exclusive: `{ id }` OR `{ key }`).
+     * If omitted/null, the story will create a new context.
+     */
+    context?: ContextIdentifier | null;
+    options?: StoryStreamOptions;
+};
+/**
+ * Payload expected to resume an auto=false tool execution.
+ *
+ * This must be serializable because it crosses the workflow hook boundary.
+ *
+ * See: https://useworkflow.dev/docs/foundations/hooks
+ */
+export type StoryToolApprovalPayload = {
+    approved: true;
+    comment?: string;
+    args?: Record<string, unknown>;
+} | {
+    approved: false;
+    comment?: string;
+};
+export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
+/**
+ * Story-level tool type.
+ *
+ * Allows stories to attach metadata to actions/tools (e.g. `{ auto: false }`)
+ * while remaining compatible with the AI SDK `Tool` runtime shape.
+ *
+ * Default behavior when omitted: `auto === true`.
+ */
+export type StoryTool = Tool & {
+    /**
+     * If `false`, this action is not intended for automatic execution by the engine.
+     * (Validation/enforcement can be added by callers; default is `true`.)
+     */
+    auto?: boolean;
+};
+/**
+ * ## Story loop continuation signal
+ *
+ * This hook result is intentionally a **boolean** so stories can be extremely declarative:
+ *
+ * - `return true`  => **continue** the durable loop
+ * - `return false` => **finalize** the durable loop
+ *
+ * (No imports required in callers.)
+ */
+export type ShouldContinue = boolean;
+export type StoryShouldContinueArgs<Context = any, Env extends StoryEnvironment = StoryEnvironment> = {
+    env: Env;
+    context: StoredContext<Context>;
+    /**
+     * The persisted reaction event **so far** for the current streaming run.
+     *
+     * This contains the assistant's streamed parts as well as merged tool execution
+     * outcomes (e.g. `state: "output-available"` / `"output-error"`).
+     *
+     * Stories can inspect `reactionEvent.content.parts` to determine stop conditions
+     * (for example: when `tool-end` has an `output-available` state).
+     */
+    reactionEvent: ContextEvent;
+    assistantEvent: ContextEvent;
+    toolCalls: any[];
+    toolExecutionResults: Array<{
+        tc: any;
+        success: boolean;
+        output: any;
+        errorText?: string;
+    }>;
+};
+export declare abstract class Story<Context, Env extends StoryEnvironment = StoryEnvironment> {
+    private opts;
+    constructor(opts?: StoryOptions<Context, Env>);
+    protected abstract initialize(context: StoredContext<Context>, env: Env): Promise<Context> | Context;
+    protected abstract buildSystemPrompt(context: StoredContext<Context>, env: Env): Promise<string> | string;
+    protected abstract buildTools(context: StoredContext<Context>, env: Env): Promise<Record<string, StoryTool>> | Record<string, StoryTool>;
+    /**
+     * 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.
+     */
+    protected expandEvents(events: ContextEvent[], _context: StoredContext<Context>, _env: Env): Promise<ContextEvent[]>;
+    protected getModel(_context: StoredContext<Context>, _env: Env): StoryModelInit;
+    /**
+     * Story stop/continue hook.
+     *
+     * After the model streamed and tools executed, the story can decide whether the loop should
+     * continue.
+     *
+     * Default: `true` (continue).
+     */
+    protected shouldContinue(_args: StoryShouldContinueArgs<Context, Env>): Promise<ShouldContinue>;
+    /**
+     * Workflow-first execution entrypoint.
+     *
+     * - Streaming is written to the workflow run's output stream.
+     * - All I/O is delegated to steps (store access, LLM streaming, stream writes).
+     * - This method returns metadata only.
+     */
+    /**
+     * React to an incoming event and advance the story.
+     *
+     * This is the primary workflow entrypoint.
+     */
+    react(triggerEvent: ContextEvent, params: StoryReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    /**
+     * @deprecated Back-compat: old object-style call signature.
+     */
+    react(params: {
+        env: Env;
+        /** @deprecated Use `triggerEvent` */
+        incomingEvent?: ContextEvent;
+        triggerEvent?: ContextEvent;
+        contextIdentifier: ContextIdentifier | null;
+        options?: StoryStreamOptions;
+    }): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    private static runWorkflow;
+    /**
+     * @deprecated Use `react()` instead. Kept for backwards compatibility.
+     */
+    stream(triggerEvent: ContextEvent, params: StoryReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    private callOnEnd;
+}

package/dist/story.engine.js

@@ -0,0 +1,464 @@
+import { getWritable } from "workflow";
+import { registerStoryEnv } from "./env.js";
+import { applyToolExecutionResultToParts } from "./story.toolcalls.js";
+import { executeReaction } from "./steps/reaction.steps.js";
+import { toolsToModelTools } from "./tools-to-model-tools.js";
+import { closeStoryStream, writeContextSubstate, writeStoryPing, writeToolOutputs, } from "./steps/stream.steps.js";
+import { completeExecution, createStoryStep, emitContextIdChunk, initializeContext, saveReactionEvent, saveTriggerAndCreateExecution, saveStoryPartsStep, updateStoryStep, updateContextContent, updateEvent, } from "./steps/store.steps.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken, } from "./story.hooks.js";
+export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
+export class Story {
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    /**
+     * 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";
+    }
+    /**
+     * Story 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(incomingEventOrParams, paramsMaybe) {
+        return await Story.runWorkflow(this, incomingEventOrParams, paramsMaybe);
+    }
+    static async runWorkflow(story, incomingEventOrParams, paramsMaybe) {
+        "use workflow";
+        const params = typeof incomingEventOrParams?.type === "string" && paramsMaybe
+            ? {
+                env: paramsMaybe.env,
+                triggerEvent: incomingEventOrParams,
+                contextIdentifier: paramsMaybe.context ?? null,
+                options: paramsMaybe.options,
+            }
+            : incomingEventOrParams;
+        const triggerEvent = params.triggerEvent ?? params.incomingEvent;
+        if (!triggerEvent) {
+            throw new Error("Story.react: triggerEvent is required");
+        }
+        // Register env for step runtimes (workflow-friendly).
+        try {
+            const { getWorkflowMetadata } = await import("workflow");
+            const meta = getWorkflowMetadata?.();
+            const runId = meta?.workflowRunId ? String(meta.workflowRunId) : null;
+            registerStoryEnv(params.env, runId ?? undefined);
+        }
+        catch {
+            registerStoryEnv(params.env);
+        }
+        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;
+        let writable = params.options?.writable;
+        // 1) Ensure context exists (step)
+        const ctxResult = await initializeContext(params.env, params.contextIdentifier, { silent, writable });
+        const currentContext = ctxResult.context;
+        // If the caller didn't provide a writable, we still stream by default (unless silent),
+        // using a namespaced stream per context: `context:<contextId>`.
+        if (!silent && !writable) {
+            writable = getWritable({
+                namespace: `context:${String(currentContext.id)}`,
+            });
+            // If the context was created in `initializeContext` (which didn't have a writable yet),
+            // re-emit the context id chunk now so clients can subscribe to the right persisted thread.
+            if (ctxResult.isNew) {
+                await emitContextIdChunk({
+                    env: params.env,
+                    contextId: String(currentContext.id),
+                    writable,
+                });
+            }
+        }
+        const contextSelector = params.contextIdentifier?.id
+            ? { id: String(params.contextIdentifier.id) }
+            : params.contextIdentifier?.key
+                ? { key: params.contextIdentifier.key }
+                : { id: String(currentContext.id) };
+        if (ctxResult.isNew) {
+            await story.opts.onContextCreated?.({ env: params.env, context: currentContext });
+        }
+        // 2) Persist trigger event + create execution shell (single step)
+        const { triggerEventId, reactionEventId, executionId } = await saveTriggerAndCreateExecution({
+            env: params.env,
+            contextIdentifier: contextSelector,
+            triggerEvent,
+        });
+        // Emit a simple ping chunk early so clients can validate that streaming works end-to-end.
+        // This should be ignored safely by clients that don't care about it.
+        if (!silent) {
+            await writeStoryPing({ label: "story-start", writable });
+        }
+        let reactionEvent = null;
+        // Latest persisted context state for this run (we keep it in memory; store is updated via steps).
+        let updatedContext = currentContext;
+        let currentStepId = null;
+        const failExecution = async () => {
+            try {
+                await completeExecution(params.env, contextSelector, executionId, "failed");
+            }
+            catch {
+                // noop
+            }
+            try {
+                if (!silent) {
+                    await closeStoryStream({ 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 stepCreate = await createStoryStep({
+                    env: params.env,
+                    executionId,
+                    iteration: iter,
+                });
+                currentStepId = stepCreate.stepId;
+                // Hook: Story DSL `context()` (implemented by subclasses via `initialize()`)
+                const nextContent = await story.initialize(updatedContext, params.env);
+                updatedContext = await updateContextContent(params.env, contextSelector, nextContent);
+                await story.opts.onContextUpdated?.({ env: params.env, context: updatedContext });
+                // Hook: Story DSL `narrative()` (implemented by subclasses via `buildSystemPrompt()`)
+                const systemPrompt = await story.buildSystemPrompt(updatedContext, params.env);
+                // Hook: Story DSL `actions()` (implemented by subclasses via `buildTools()`)
+                const toolsAll = await story.buildTools(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 { assistantEvent, toolCalls, messagesForModel } = await executeReaction({
+                    env: params.env,
+                    contextIdentifier: contextSelector,
+                    model: story.getModel(updatedContext, params.env),
+                    system: systemPrompt,
+                    tools: toolsForModel,
+                    eventId: reactionEventId,
+                    iteration: iter,
+                    maxSteps: maxModelSteps,
+                    // Only emit a `start` chunk once per story turn.
+                    sendStart: !silent && iter === 0 && reactionEvent === null,
+                    silent,
+                    writable,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    stepId: String(stepCreate.stepId),
+                });
+                const reviewRequests = toolCalls.length > 0
+                    ? toolCalls.flatMap((tc) => {
+                        const toolDef = toolsAll[tc.toolName];
+                        const auto = toolDef?.auto !== false;
+                        tc.auto = auto;
+                        if (auto)
+                            return [];
+                        return [
+                            {
+                                toolCallId: String(tc.toolCallId),
+                                toolName: String(tc.toolName ?? ""),
+                            },
+                        ];
+                    })
+                    : [];
+                // Persist normalized parts hanging off the producing step (story_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 = (assistantEvent?.content?.parts ?? []);
+                await saveStoryPartsStep({
+                    env: params.env,
+                    stepId: stepCreate.stepId,
+                    parts: stepParts,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                });
+                // Persist/append the aggregated reaction event (stable `reactionEventId` for the execution).
+                if (!reactionEvent) {
+                    const reactionPayload = {
+                        ...assistantEvent,
+                        status: "pending",
+                    };
+                    reactionEvent = await saveReactionEvent(params.env, contextSelector, reactionPayload, {
+                        executionId,
+                        contextId: String(currentContext.id),
+                        reviewRequests,
+                    });
+                }
+                else {
+                    reactionEvent = await updateEvent(params.env, reactionEvent.id, {
+                        ...reactionEvent,
+                        content: {
+                            parts: [
+                                ...(reactionEvent?.content?.parts ?? []),
+                                ...(assistantEvent?.content?.parts ?? []),
+                            ],
+                        },
+                        status: "pending",
+                    }, { executionId, contextId: String(currentContext.id) });
+                }
+                story.opts.onEventCreated?.(assistantEvent);
+                // Done: no tool calls requested by the model
+                if (!toolCalls.length) {
+                    const endResult = await story.callOnEnd(assistantEvent);
+                    if (endResult) {
+                        // Mark iteration step completed (no tools)
+                        await updateStoryStep({
+                            env: params.env,
+                            stepId: stepCreate.stepId,
+                            patch: {
+                                status: "completed",
+                                toolCalls: [],
+                                toolExecutionResults: [],
+                                continueLoop: false,
+                            },
+                            executionId,
+                            contextId: String(currentContext.id),
+                            iteration: iter,
+                        });
+                        // Mark reaction event completed
+                        await updateEvent(params.env, reactionEventId, {
+                            ...reactionEvent,
+                            status: "completed",
+                        }, { executionId, contextId: String(currentContext.id) });
+                        await completeExecution(params.env, contextSelector, executionId, "completed");
+                        if (!silent) {
+                            await closeStoryStream({ preventClose, sendFinish, writable });
+                        }
+                        return {
+                            contextId: currentContext.id,
+                            context: updatedContext,
+                            triggerEventId,
+                            reactionEventId,
+                            executionId,
+                        };
+                    }
+                }
+                // Execute tool calls (workflow context; tool implementations decide step vs workflow)
+                if (!silent && toolCalls.length) {
+                    await writeContextSubstate({ key: "actions", transient: true, writable });
+                }
+                const executionResults = await Promise.all(toolCalls.map(async (tc) => {
+                    const toolDef = toolsAll[tc.toolName];
+                    if (!toolDef || typeof toolDef.execute !== "function") {
+                        return {
+                            tc,
+                            success: false,
+                            output: null,
+                            errorText: `Tool "${tc.toolName}" not found or has no execute().`,
+                        };
+                    }
+                    try {
+                        let toolArgs = tc.args;
+                        if (toolDef?.auto === false) {
+                            const { createHook, createWebhook } = await import("workflow");
+                            const toolCallId = String(tc.toolCallId);
+                            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 {
+                                    tc,
+                                    success: false,
+                                    output: null,
+                                    errorText: approval && "comment" in approval && approval.comment
+                                        ? `Tool execution not approved: ${approval.comment}`
+                                        : "Tool execution not approved",
+                                };
+                            }
+                            if ("args" in approval && approval.args !== undefined) {
+                                toolArgs = approval.args;
+                            }
+                        }
+                        const output = await toolDef.execute(toolArgs, {
+                            toolCallId: tc.toolCallId,
+                            messages: messagesForModel,
+                            eventId: reactionEventId,
+                            executionId,
+                            triggerEventId,
+                            contextId: currentContext.id,
+                        });
+                        return { tc, success: true, output };
+                    }
+                    catch (e) {
+                        return {
+                            tc,
+                            success: false,
+                            output: null,
+                            errorText: e instanceof Error ? e.message : String(e),
+                        };
+                    }
+                }));
+                // Emit tool outputs to the workflow stream (step)
+                if (!silent) {
+                    await writeToolOutputs({
+                        results: executionResults.map((r) => r.success
+                            ? { toolCallId: r.tc.toolCallId, success: true, output: r.output }
+                            : {
+                                toolCallId: r.tc.toolCallId,
+                                success: false,
+                                errorText: r.errorText,
+                            }),
+                        writable,
+                    });
+                }
+                // Clear action status once tool execution results have been emitted.
+                if (!silent && toolCalls.length) {
+                    await writeContextSubstate({ key: null, transient: true, writable });
+                }
+                // Merge tool results into persisted parts (so next LLM call can see them)
+                if (reactionEvent) {
+                    let parts = reactionEvent?.content?.parts ?? [];
+                    for (const r of executionResults) {
+                        parts = applyToolExecutionResultToParts(parts, r.tc, {
+                            success: Boolean(r.success),
+                            result: r.output,
+                            message: r.errorText,
+                        });
+                    }
+                    reactionEvent = await updateEvent(params.env, reactionEventId, {
+                        ...reactionEvent,
+                        content: { parts },
+                        status: "pending",
+                    }, { executionId, contextId: String(currentContext.id) });
+                }
+                // Callback for observability/integration
+                for (const r of executionResults) {
+                    await story.opts.onToolCallExecuted?.({
+                        toolCall: r.tc,
+                        success: r.success,
+                        output: r.output,
+                        errorText: r.errorText,
+                        eventId: reactionEventId,
+                        executionId,
+                    });
+                }
+                // Stop/continue boundary: allow the Story 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 story.shouldContinue({
+                    env: params.env,
+                    context: updatedContext,
+                    reactionEvent: reactionEvent ?? assistantEvent,
+                    assistantEvent,
+                    toolCalls,
+                    toolExecutionResults: executionResults,
+                });
+                // Persist per-iteration step outcome (tools + continue signal)
+                await updateStoryStep({
+                    env: params.env,
+                    stepId: stepCreate.stepId,
+                    patch: {
+                        status: "completed",
+                        toolCalls,
+                        toolExecutionResults: executionResults,
+                        continueLoop: continueLoop !== false,
+                    },
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                });
+                if (continueLoop === false) {
+                    await updateEvent(params.env, reactionEventId, {
+                        ...reactionEvent,
+                        status: "completed",
+                    }, { executionId, contextId: String(currentContext.id) });
+                    await completeExecution(params.env, contextSelector, executionId, "completed");
+                    if (!silent) {
+                        await closeStoryStream({ preventClose, sendFinish, writable });
+                    }
+                    return {
+                        contextId: currentContext.id,
+                        context: updatedContext,
+                        triggerEventId,
+                        reactionEventId,
+                        executionId,
+                    };
+                }
+            }
+            throw new Error(`Story: maxIterations reached (${maxIterations}) without completion`);
+        }
+        catch (error) {
+            // Best-effort: persist failure on the current iteration step (if any)
+            if (currentStepId) {
+                try {
+                    await updateStoryStep({
+                        env: params.env,
+                        stepId: currentStepId,
+                        patch: {
+                            status: "failed",
+                            errorText: error instanceof Error ? error.message : String(error),
+                        },
+                        executionId,
+                        contextId: String(currentContext.id),
+                    });
+                }
+                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;
+        if (result && typeof result === "object" && "end" in result)
+            return Boolean(result.end);
+        return true;
+    }
+}