@ekairos/story 1.21.29-beta.0 → 1.21.32-beta.0

package/dist/story.config.js

@@ -0,0 +1,57 @@
+let runtimeResolver = null;
+function getRuntimeResolver() {
+    return runtimeResolver;
+}
+let runtimeBootstrap = null;
+export function configureStoryRuntimeBootstrap(bootstrap) {
+    runtimeBootstrap = bootstrap;
+}
+/**
+ * Configure the story runtime resolver (global).
+ *
+ * This should be called once during initialization (module load) in your app.
+ * The resolver itself will be invoked inside steps, where it can safely create DB clients.
+ */
+export function configureStoryRuntime(resolver) {
+    runtimeResolver = resolver;
+}
+export function isStoryRuntimeConfigured() {
+    return Boolean(runtimeResolver);
+}
+export async function resolveStoryRuntime(env) {
+    if (!getRuntimeResolver()) {
+        // Best-effort: allow the step runtime to self-bootstrap once.
+        if (runtimeBootstrap) {
+            await runtimeBootstrap();
+        }
+        // Convention bootstrap (Next.js / monorepo apps):
+        // If the app exposes `src/ekairos.ts` and uses the `@/` alias, loading that module will
+        // run `ekairosConfig.setup()` which configures the resolver + bootstrap hook.
+        //
+        // This is intentionally ONLY attempted when runtime is missing, and is safe as long as
+        // `story.config` is not part of client bundles (see `@ekairos/story/runtime`).
+        if (!getRuntimeResolver()) {
+            try {
+                // @ts-expect-error - optional, app-provided convention module
+                await import("@/ekairos");
+            }
+            catch {
+                // ignore: module missing / alias not configured
+            }
+        }
+        // If bootstrap succeeded, proceed.
+        const resolver = getRuntimeResolver();
+        if (resolver)
+            return await resolver(env);
+        throw new Error([
+            "Story runtime is not configured.",
+            "",
+            "Convention:",
+            "- Create an app-level `ekairos.ts` that exports `ekairosConfig = createEkairosConfig({ runtime })`",
+            "- Ensure `ekairosConfig.setup()` runs in the step runtime (module load / worker boot).",
+            "",
+            "If you already have that file, ensure it is evaluated in the step runtime before calling story store steps.",
+        ].join("\n"));
+    }
+    return await getRuntimeResolver()(env);
+}

package/dist/story.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.config.js","sourceRoot":"","sources":["../src/story.config.ts"],"names":[],"mappings":"AAyBA,IAAI,eAAe,GAAqC,IAAI,CAAA;AAiB5D,IAAI,gBAAgB,GAA4B,IAAI,CAAA;AAEpD,MAAM,UAAU,8BAA8B,CAAC,SAA2B;IACxE,gBAAgB,GAAG,SAAS,CAAA;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,QAAmC;IAEnC,eAAe,GAAG,QAAe,CAAA;AACnC,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,OAAO,CAAC,eAAe,CAAC,CAAA;AACjC,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,GAAqB;IAC7D,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,8DAA8D;QAC9D,IAAI,gBAAgB,EAAE,CAAC;YACrB,MAAM,gBAAgB,EAAE,CAAA;QAC1B,CAAC;QACD,MAAM,IAAI,KAAK,CACb;YACE,kCAAkC;YAClC,EAAE;YACF,aAAa;YACb,oGAAoG;YACpG,wFAAwF;YACxF,EAAE;YACF,6GAA6G;SAC9G,CAAC,IAAI,CAAC,IAAI,CAAC,CACb,CAAA;IACH,CAAC;IACD,OAAO,MAAM,eAAe,CAAC,GAAG,CAAC,CAAA;AACnC,CAAC","sourcesContent":["import type { StoryStore } from \"./story.store\"\r\n\r\n/**\r\n * ## story.config.ts\r\n *\r\n * Workflow-first story execution means we **cannot** keep non-serializable runtime objects\r\n * (database clients, network handles, SDK instances) inside workflow state.\r\n *\r\n * Instead, we centralize runtime construction behind a global resolver:\r\n * - The workflow passes a **serializable** `StoryEnvironment` into steps.\r\n * - Steps call `resolveStoryRuntime(env)` to instantiate the right store (Instant/Postgres/etc).\r\n *\r\n * This keeps `createStory(...)` purely declarative while still allowing per-tenant/per-org routing.\r\n */\r\n\r\nexport type StoryEnvironment = Record<string, unknown>\r\n\r\nexport type StoryRuntime = {\r\n  store: StoryStore\r\n}\r\n\r\nexport type StoryRuntimeResolver<Env extends StoryEnvironment = StoryEnvironment> = (\r\n  env: Env\r\n) => Promise<StoryRuntime> | StoryRuntime\r\n\r\nlet runtimeResolver: StoryRuntimeResolver<any> | null = null\r\n\r\n/**\r\n * Optional global bootstrap hook for step runtimes.\r\n *\r\n * Motivation:\r\n * - Workflow step runtimes may execute in a separate process/bundle.\r\n * - If the app's `ekairos.ts` was not evaluated in that runtime yet, the story runtime\r\n *   resolver won't be configured and store steps will fail.\r\n *\r\n * Convention:\r\n * - Apps should have a single `ekairos.ts` that creates `ekairosConfig` and calls `ekairosConfig.setup()`.\r\n * - That module (or `createEkairosConfig().setup()`) can register this bootstrap function,\r\n *   so library steps can \"pull\" initialization on-demand before first store access.\r\n */\r\ntype RuntimeBootstrap = () => void | Promise<void>\r\n\r\nlet runtimeBootstrap: RuntimeBootstrap | null = null\r\n\r\nexport function configureStoryRuntimeBootstrap(bootstrap: RuntimeBootstrap) {\r\n  runtimeBootstrap = bootstrap\r\n}\r\n\r\n/**\r\n * Configure the story runtime resolver (global).\r\n *\r\n * This should be called once during initialization (module load) in your app.\r\n * The resolver itself will be invoked inside steps, where it can safely create DB clients.\r\n */\r\nexport function configureStoryRuntime<Env extends StoryEnvironment>(\r\n  resolver: StoryRuntimeResolver<Env>,\r\n) {\r\n  runtimeResolver = resolver as any\r\n}\r\n\r\nexport function isStoryRuntimeConfigured() {\r\n  return Boolean(runtimeResolver)\r\n}\r\n\r\nexport async function resolveStoryRuntime(env: StoryEnvironment): Promise<StoryRuntime> {\r\n  if (!runtimeResolver) {\r\n    // Best-effort: allow the step runtime to self-bootstrap once.\r\n    if (runtimeBootstrap) {\r\n      await runtimeBootstrap()\r\n    }\r\n    throw new Error(\r\n      [\r\n        \"Story runtime is not configured.\",\r\n        \"\",\r\n        \"Convention:\",\r\n        \"- Create an app-level `ekairos.ts` that exports `ekairosConfig = createEkairosConfig({ runtime })`\",\r\n        \"- Ensure `ekairosConfig.setup()` runs in the step runtime (module load / worker boot).\",\r\n        \"\",\r\n        \"If you already have that file, ensure it is evaluated in the step runtime before calling story store steps.\",\r\n      ].join(\"\\n\"),\r\n    )\r\n  }\r\n  return await runtimeResolver(env)\r\n}\r\n\r\n\r\n\r\n"]}

package/dist/story.d.ts

@@ -1,50 +1,2 @@
-import type { ContextIdentifier } from "./service";
-export type PrimitiveType = "string" | "number" | "boolean" | "object" | "array";
-export type FieldSchema = {
-    type: PrimitiveType;
-    description?: string;
-    required?: boolean;
-    properties?: Record<string, FieldSchema>;
-    items?: FieldSchema;
-};
-export type StepInputSchema = {
-    type: "object";
-    description?: string;
-    properties?: Record<string, FieldSchema>;
-};
-export type StoryActionSpec = {
-    name: string;
-    description: string;
-    implementationKey: string;
-    inputSchema?: StepInputSchema;
-    finalize?: boolean;
-    execute?: (args: any & {
-        contextId?: string;
-    }) => Promise<any>;
-};
-export type StoryOptions = {
-    reasoningEffort?: "low" | "medium" | "high";
-    webSearch?: boolean;
-    maxLoops?: number;
-    finalActions?: string[];
-    includeBaseTools?: {
-        createMessage?: boolean;
-        requestDirection?: boolean;
-        end?: boolean;
-    };
-};
-export type StoryConfig = {
-    narrative: string;
-    actions: StoryActionSpec[];
-    options?: StoryOptions;
-};
-export type StoryStartArgs = {
-    context?: ContextIdentifier | null;
-    trigger?: any | null;
-};
-export declare function story(key: string, config: StoryConfig): (args?: StoryStartArgs) => Promise<{
-    contextId: unknown;
-    status: "completed";
-}>;
-export type { StoryActionSpec as StoryAction, StoryOptions as StoryConfigOptions };
-//# sourceMappingURL=story.d.ts.map
+export { Story, type StoryOptions, type StoryStreamOptions, type ShouldContinue, type StoryShouldContinueArgs, } from "./story.engine";
+export { story, createStory, type StoryConfig, type StoryInstance, type RegistrableStoryBuilder, } from "./story.builder";

package/dist/story.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../src/story.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAOlD,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAEhF,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,aAAa,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;IACxC,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,QAAQ,CAAA;IACd,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAA;CACzC,CAAA;AAED,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IAEnB,iBAAiB,EAAE,MAAM,CAAA;IAEzB,WAAW,CAAC,EAAE,eAAe,CAAA;IAE7B,QAAQ,CAAC,EAAE,OAAO,CAAA;IAElB,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,GAAG;QAAE,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,GAAG,CAAC,CAAA;CAC/D,CAAA;AAED,MAAM,MAAM,YAAY,GAAG;IACzB,eAAe,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC3C,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAA;IACvB,gBAAgB,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAC;QAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;QAAC,GAAG,CAAC,EAAE,OAAO,CAAA;KAAE,CAAA;CAC1F,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAA;CACvB,CAAA;AAED,MAAM,MAAM,cAAc,GAAG;IAC3B,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAA;IAClC,OAAO,CAAC,EAAE,GAAG,GAAG,IAAI,CAAA;CACrB,CAAA;AAYD,wBAAgB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,IAErB,OAAO,cAAc;;;GAqDrD;AAED,YAAY,EAAE,eAAe,IAAI,WAAW,EAAE,YAAY,IAAI,kBAAkB,EAAE,CAAA"}
+{"version":3,"file":"story.d.ts","sourceRoot":"","sources":["../src/story.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,EACL,KAAK,YAAY,EACjB,KAAK,kBAAkB,GACxB,MAAM,gBAAgB,CAAA;AAEvB,OAAO,EAEL,KAAK,EACL,WAAW,EACX,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,uBAAuB,GAC7B,MAAM,iBAAiB,CAAA"}

package/dist/story.engine.d.ts

@@ -0,0 +1,174 @@
+import type { Tool } from "ai";
+import type { StoryEnvironment } from "./story.config";
+import type { ContextEvent, ContextIdentifier, StoredContext } from "./story.store";
+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;
+}
+/**
+ * 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;
+};
+/**
+ * ## 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, Tool>> | Record<string, Tool>;
+    /**
+     * 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;
+    }>;
+    /**
+     * @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.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.engine.d.ts","sourceRoot":"","sources":["../src/story.engine.ts"],"names":[],"mappings":"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"}

package/dist/story.engine.js

@@ -0,0 +1,283 @@
+import { applyToolExecutionResultToParts } from "./story.toolcalls";
+import { doStoryStreamStep } from "./steps/do-story-stream-step";
+import { toolsToModelTools } from "./tools-to-model-tools";
+import { closeStoryStream, writeContextSubstate, writeToolOutputs } from "./steps/stream.steps";
+import { completeExecution, createExecution, eventsToModelMessages, generateId, ensureContextAndEmitContextId, getEvents, saveEvent, updateContextContent, updateContextStatus, updateEvent, } from "./steps/store.steps";
+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) {
+        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");
+        }
+        const maxIterations = params.options?.maxIterations ?? 20;
+        const maxModelSteps = params.options?.maxModelSteps ?? 1;
+        const preventClose = params.options?.preventClose ?? false;
+        const sendFinish = params.options?.sendFinish ?? true;
+        // 1) Ensure context exists (step)
+        const ctxResult = await ensureContextAndEmitContextId(params.env, params.contextIdentifier);
+        const currentContext = ctxResult.context;
+        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 this.opts.onContextCreated?.({ env: params.env, context: currentContext });
+        }
+        // 2) Persist trigger event + create execution shell (steps)
+        const persistedTriggerEvent = await saveEvent(params.env, contextSelector, triggerEvent);
+        const triggerEventId = persistedTriggerEvent.id;
+        const reactionEventId = await generateId();
+        await updateContextStatus(params.env, contextSelector, "streaming");
+        const execution = await createExecution(params.env, contextSelector, triggerEventId, reactionEventId);
+        const executionId = execution.id;
+        let reactionEvent = null;
+        // Latest persisted context state for this run (we keep it in memory; store is updated via steps).
+        let updatedContext = currentContext;
+        const failExecution = async () => {
+            try {
+                await completeExecution(params.env, contextSelector, executionId, "failed");
+            }
+            catch {
+                // noop
+            }
+            try {
+                await closeStoryStream({ preventClose, sendFinish });
+            }
+            catch {
+                // noop
+            }
+        };
+        try {
+            for (let iter = 0; iter < maxIterations; iter++) {
+                const events = await getEvents(params.env, contextSelector);
+                // Normalize/initialize context (workflow-level; may call steps if needed)
+                const nextContent = await this.initialize(updatedContext, params.env);
+                updatedContext = await updateContextContent(params.env, contextSelector, nextContent);
+                await this.opts.onContextUpdated?.({ env: params.env, context: updatedContext });
+                const systemPrompt = await this.buildSystemPrompt(updatedContext, params.env);
+                const toolsAll = await this.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);
+                const expandedEvents = await this.expandEvents(events, updatedContext, params.env);
+                const messagesForModel = await eventsToModelMessages(params.env, expandedEvents);
+                const { assistantEvent, toolCalls } = await doStoryStreamStep({
+                    model: this.getModel(updatedContext, params.env),
+                    system: systemPrompt,
+                    messages: messagesForModel,
+                    tools: toolsForModel,
+                    eventId: reactionEventId,
+                    maxSteps: maxModelSteps,
+                    // Only emit a `start` chunk once per story turn.
+                    sendStart: iter === 0 && reactionEvent === null,
+                });
+                // Persist/append the assistant event for this iteration
+                if (!reactionEvent) {
+                    reactionEvent = await saveEvent(params.env, contextSelector, {
+                        ...assistantEvent,
+                        status: "pending",
+                    });
+                }
+                else {
+                    reactionEvent = await updateEvent(params.env, reactionEvent.id, {
+                        ...reactionEvent,
+                        content: {
+                            parts: [
+                                ...(reactionEvent?.content?.parts ?? []),
+                                ...(assistantEvent?.content?.parts ?? []),
+                            ],
+                        },
+                        status: "pending",
+                    });
+                }
+                this.opts.onEventCreated?.(assistantEvent);
+                // Done: no tool calls requested by the model
+                if (!toolCalls.length) {
+                    const endResult = await this.callOnEnd(assistantEvent);
+                    if (endResult) {
+                        // Mark reaction event completed
+                        await updateEvent(params.env, reactionEventId, {
+                            ...reactionEvent,
+                            status: "completed",
+                        });
+                        await updateContextStatus(params.env, contextSelector, "open");
+                        await completeExecution(params.env, contextSelector, executionId, "completed");
+                        await closeStoryStream({ preventClose, sendFinish });
+                        return {
+                            contextId: currentContext.id,
+                            context: updatedContext,
+                            triggerEventId,
+                            reactionEventId,
+                            executionId,
+                        };
+                    }
+                }
+                // Execute tool calls (workflow context; tool implementations decide step vs workflow)
+                if (toolCalls.length) {
+                    await writeContextSubstate({ key: "actions", transient: true });
+                }
+                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 {
+                        const output = await toolDef.execute(tc.args, {
+                            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)
+                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 }),
+                });
+                // Clear action status once tool execution results have been emitted.
+                if (toolCalls.length) {
+                    await writeContextSubstate({ key: null, transient: true });
+                }
+                // 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",
+                    });
+                }
+                // Callback for observability/integration
+                for (const r of executionResults) {
+                    await this.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 this.shouldContinue({
+                    env: params.env,
+                    context: updatedContext,
+                    reactionEvent: reactionEvent ?? assistantEvent,
+                    assistantEvent,
+                    toolCalls,
+                    toolExecutionResults: executionResults,
+                });
+                if (continueLoop === false) {
+                    await updateEvent(params.env, reactionEventId, {
+                        ...reactionEvent,
+                        status: "completed",
+                    });
+                    await updateContextStatus(params.env, contextSelector, "open");
+                    await completeExecution(params.env, contextSelector, executionId, "completed");
+                    await closeStoryStream({ preventClose, sendFinish });
+                    return {
+                        contextId: currentContext.id,
+                        context: updatedContext,
+                        triggerEventId,
+                        reactionEventId,
+                        executionId,
+                    };
+                }
+            }
+            throw new Error(`Story: maxIterations reached (${maxIterations}) without completion`);
+        }
+        catch (error) {
+            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;
+    }
+}

package/dist/story.engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"story.engine.js","sourceRoot":"","sources":["../src/story.engine.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,+BAA+B,EAAE,MAAM,mBAAmB,CAAA;AAEnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAC9F,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,qBAAqB,EACrB,UAAU,EACV,UAAU,EACV,SAAS,EACT,kBAAkB,EAClB,SAAS,EACT,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,GACZ,MAAM,qBAAqB,CAAA;AAsC5B,MAAM,OAAgB,KAAK;IACzB,YAAoB,OAAmC,EAAE;QAArC,SAAI,GAAJ,IAAI,CAAiC;IAAG,CAAC;IAiB7D;;;;;;;;;;;;;;;;OAgBG;IACO,KAAK,CAAC,YAAY,CAC1B,MAAsB,EACtB,QAAgC,EAChC,IAAS;QAET,OAAO,MAAM,CAAA;IACf,CAAC;IAES,QAAQ,CAAC,QAAgC,EAAE,IAAS;QAC5D,OAAO,cAAc,CAAA;IACvB,CAAC;IAED;;;OAGG;IACO,KAAK,CAAC,wBAAwB;QACtC,OAAO,EAAE,CAAA;IACX,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,MAAM,CAAC,MAMnB;QACC,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,EAAE,aAAa,IAAI,EAAE,CAAA;QACzD,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,EAAE,aAAa,IAAI,CAAC,CAAA;QACxD,MAAM,YAAY,GAAG,MAAM,CAAC,OAAO,EAAE,YAAY,IAAI,KAAK,CAAA;QAC1D,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,UAAU,IAAI,IAAI,CAAA;QAErD,kCAAkC;QAClC,MAAM,SAAS,GAAG,MAAM,kBAAkB,CACxC,MAAM,CAAC,GAAG,EACV,MAAM,CAAC,iBAAiB,CACzB,CAAA;QACD,MAAM,cAAc,GAAG,SAAS,CAAC,OAAO,CAAA;QAExC,MAAM,eAAe,GACnB,MAAM,CAAC,iBAAiB,EAAE,EAAE;YAC1B,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,MAAM,CAAC,iBAAiB,CAAC,EAAE,CAAC,EAAE;YAC7C,CAAC,CAAC,MAAM,CAAC,iBAAiB,EAAE,GAAG;gBAC7B,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE;gBACvC,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAA;QAEzC,mGAAmG;QACnG,MAAM,mBAAmB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,SAAS,EAAE,MAAM,CAAC,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC,CAAA;QAE9F,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAA;QAClF,CAAC;QAED,4DAA4D;QAC5D,MAAM,YAAY,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,aAAa,CAAC,CAAA;QACvF,MAAM,cAAc,GAAG,YAAY,CAAC,EAAE,CAAA;QAEtC,MAAM,eAAe,GAAG,MAAM,UAAU,EAAE,CAAA;QAE1C,MAAM,mBAAmB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,CAAC,CAAA;QACnE,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,CAAC,CAAA;QACrG,MAAM,WAAW,GAAG,SAAS,CAAC,EAAE,CAAA;QAEhC,IAAI,aAAa,GAAwB,IAAI,CAAA;QAE7C,MAAM,aAAa,GAAG,KAAK,IAAI,EAAE;YAC/B,IAAI,CAAC;gBACH,MAAM,iBAAiB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAA;YAC7E,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;YACT,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,gBAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;YACjF,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;YACT,CAAC;QACH,CAAC,CAAA;QAED,IAAI,CAAC;YACH,KAAK,IAAI,IAAI,GAAG,CAAC,EAAE,IAAI,GAAG,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC;gBAChD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAU,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;gBACrE,IAAI,CAAC,MAAM;oBAAE,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;gBAExD,0EAA0E;gBAC1E,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;gBAC7D,MAAM,cAAc,GAAG,MAAM,oBAAoB,CAC/C,MAAM,CAAC,GAAG,EACV,eAAe,EACf,WAAW,CACZ,CAAA;gBAED,MAAM,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAA;gBAEhF,MAAM,YAAY,GAAG,MAAM,IAAI,CAAC,iBAAiB,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;gBAC7E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;gBAElE,+DAA+D;gBAC/D,MAAM,aAAa,GAAyB,EAAE,CAAA;gBAC9C,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;oBACjD,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,GAAI,CAAS,EAAE,CAAA;oBACvC,OAAQ,aAAa,CAAC,IAAI,CAAS,CAAC,OAAO,CAAA;gBAC7C,CAAC;gBAED,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,CAAC,CAAA;gBAC3D,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;gBAClF,MAAM,gBAAgB,GAAmB,MAAM,qBAAqB,CAClE,MAAM,CAAC,GAAG,EACV,cAAc,CACf,CAAA;gBAED,MAAM,EAAE,cAAc,EAAE,SAAS,EAAE,GAAG,MAAM,iBAAiB,CAAC;oBAC5D,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC,GAAG,CAAC;oBAChD,MAAM,EAAE,YAAY;oBACpB,QAAQ,EAAE,gBAAgB;oBAC1B,KAAK,EAAE,aAAa;oBACpB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,OAAO,EAAE,eAAe;oBACxB,QAAQ,EAAE,aAAa;iBACxB,CAAC,CAAA;gBAEF,wDAAwD;gBACxD,IAAI,CAAC,aAAa,EAAE,CAAC;oBACnB,aAAa,GAAG,MAAM,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE;wBAC3D,GAAI,cAAsB;wBAC1B,MAAM,EAAE,SAAS;qBAClB,CAAC,CAAA;gBACJ,CAAC;qBAAM,CAAC;oBACN,aAAa,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,aAAa,CAAC,EAAE,EAAE;wBAC9D,GAAI,aAAqB;wBACzB,OAAO,EAAE;4BACP,KAAK,EAAE;gCACL,GAAG,CAAE,aAAqB,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;gCACjD,GAAG,CAAE,cAAsB,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAC;6BACnD;yBACF;wBACD,MAAM,EAAE,SAAS;qBACX,CAAC,CAAA;gBACX,CAAC;gBAED,IAAI,CAAC,IAAI,CAAC,cAAc,EAAE,CAAC,cAAc,CAAC,CAAA;gBAE1C,6CAA6C;gBAC7C,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;oBACtB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,cAAc,CAAC,CAAA;oBACtD,IAAI,SAAS,EAAE,CAAC;wBACd,gCAAgC;wBAChC,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE;4BAC7C,GAAI,aAAqB;4BACzB,MAAM,EAAE,WAAW;yBACb,CAAC,CAAA;wBACT,MAAM,mBAAmB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,CAAA;wBAC9D,MAAM,iBAAiB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;wBAC9E,MAAM,gBAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;wBAC/E,OAAO;4BACL,SAAS,EAAE,cAAc,CAAC,EAAE;4BAC5B,cAAc;4BACd,eAAe;4BACf,WAAW;yBACZ,CAAA;oBACH,CAAC;gBACH,CAAC;gBAED,sFAAsF;gBACtF,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,GAAG,CACxC,SAAS,CAAC,GAAG,CAAC,KAAK,EAAE,EAAO,EAAE,EAAE;oBAC9B,MAAM,OAAO,GAAI,QAAgB,CAAC,EAAE,CAAC,QAAQ,CAAQ,CAAA;oBACrD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;wBACtD,OAAO;4BACL,EAAE;4BACF,OAAO,EAAE,KAAK;4BACd,MAAM,EAAE,IAAI;4BACZ,SAAS,EAAE,SAAS,EAAE,CAAC,QAAQ,kCAAkC;yBAClE,CAAA;oBACH,CAAC;oBACD,IAAI,CAAC;wBACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;4BAC5C,UAAU,EAAE,EAAE,CAAC,UAAU;4BACzB,QAAQ,EAAE,gBAAgB;yBAC3B,CAAC,CAAA;wBACF,OAAO,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAA;oBACtC,CAAC;oBAAC,OAAO,CAAM,EAAE,CAAC;wBAChB,OAAO;4BACL,EAAE;4BACF,OAAO,EAAE,KAAK;4BACd,MAAM,EAAE,IAAI;4BACZ,SAAS,EAAE,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;yBACtD,CAAA;oBACH,CAAC;gBACH,CAAC,CAAC,CACH,CAAA;gBAED,kDAAkD;gBAClD,MAAM,gBAAgB,CAAC;oBACrB,QAAQ,EAAE,MAAM,CAAC,QAAQ;oBACzB,OAAO,EAAE,gBAAgB,CAAC,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CACvC,CAAC,CAAC,OAAO;wBACP,CAAC,CAAE,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAY;wBAC7E,CAAC,CAAE,EAAE,UAAU,EAAE,CAAC,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAY,CACvF;iBACF,CAAC,CAAA;gBAEF,0EAA0E;gBAC1E,IAAI,aAAa,EAAE,CAAC;oBAClB,IAAI,KAAK,GAAI,aAAqB,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE,CAAA;oBACxD,KAAK,MAAM,CAAC,IAAI,gBAAyB,EAAE,CAAC;wBAC1C,KAAK,GAAG,+BAA+B,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE;4BACnD,OAAO,EAAE,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;4BAC3B,MAAM,EAAE,CAAC,CAAC,MAAM;4BAChB,OAAO,EAAE,CAAC,CAAC,SAAS;yBACrB,CAAC,CAAA;oBACJ,CAAC;oBAED,aAAa,GAAG,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE;wBAC7D,GAAI,aAAqB;wBACzB,OAAO,EAAE,EAAE,KAAK,EAAE;wBAClB,MAAM,EAAE,SAAS;qBACX,CAAC,CAAA;gBACX,CAAC;gBAED,yCAAyC;gBACzC,KAAK,MAAM,CAAC,IAAI,gBAAyB,EAAE,CAAC;oBAC1C,MAAM,IAAI,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;wBACnC,QAAQ,EAAE,CAAC,CAAC,EAAE;wBACd,OAAO,EAAE,CAAC,CAAC,OAAO;wBAClB,MAAM,EAAE,CAAC,CAAC,MAAM;wBAChB,SAAS,EAAE,CAAC,CAAC,SAAS;wBACtB,OAAO,EAAE,eAAe;wBACxB,WAAW;qBACZ,CAAC,CAAA;gBACJ,CAAC;gBAED,wBAAwB;gBACxB,MAAM,cAAc,GAAG,MAAM,IAAI,CAAC,wBAAwB,EAAE,CAAA;gBAC5D,MAAM,cAAc,GAAI,gBAA0B,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAC5D,cAAc,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,CACvC,CAAA;gBAED,IAAI,cAAc,EAAE,CAAC;oBACnB,MAAM,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE;wBAC7C,GAAI,aAAqB;wBACzB,MAAM,EAAE,WAAW;qBACb,CAAC,CAAA;oBACT,MAAM,mBAAmB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,MAAM,CAAC,CAAA;oBAC9D,MAAM,iBAAiB,CAAC,MAAM,CAAC,GAAG,EAAE,eAAe,EAAE,WAAW,EAAE,WAAW,CAAC,CAAA;oBAC9E,MAAM,gBAAgB,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,CAAC,CAAA;oBAC/E,OAAO;wBACL,SAAS,EAAE,cAAc,CAAC,EAAE;wBAC5B,cAAc;wBACd,eAAe;wBACf,WAAW;qBACZ,CAAA;gBACH,CAAC;YACH,CAAC;YAED,MAAM,IAAI,KAAK,CAAC,iCAAiC,aAAa,sBAAsB,CAAC,CAAA;QACvF,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,aAAa,EAAE,CAAA;YACrB,MAAM,KAAK,CAAA;QACb,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,SAAS,CAAC,SAAuB;QAC7C,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QACjC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;QAC/C,IAAI,OAAO,MAAM,KAAK,SAAS;YAAE,OAAO,MAAM,CAAA;QAC9C,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,IAAI,MAAM;YAAE,OAAO,OAAO,CAAE,MAAc,CAAC,GAAG,CAAC,CAAA;QAChG,OAAO,IAAI,CAAA;IACb,CAAC;CACF","sourcesContent":["import type { ModelMessage, Tool, UIMessageChunk } from \"ai\"\r\n\r\nimport type { StoryEnvironment } from \"./story.config\"\r\nimport type { ContextEvent, ContextIdentifier, StoredContext } from \"./story.store\"\r\nimport { applyToolExecutionResultToParts } from \"./story.toolcalls\"\r\n\r\nimport { doStoryStreamStep } from \"./steps/do-story-stream-step\"\r\nimport { closeStoryStream, writeContextIdChunk, writeToolOutputs } from \"./steps/stream.steps\"\r\nimport {\r\n  completeExecution,\r\n  createExecution,\r\n  eventsToModelMessages,\r\n  generateId,\r\n  getContext,\r\n  getEvents,\r\n  getOrCreateContext,\r\n  saveEvent,\r\n  updateContextContent,\r\n  updateContextStatus,\r\n  updateEvent,\r\n} from \"./steps/store.steps\"\r\n\r\nexport interface StoryOptions<Context = any, Env extends StoryEnvironment = StoryEnvironment> {\r\n  onContextCreated?: (args: { env: Env; context: StoredContext<Context> }) => void | Promise<void>\r\n  onContextUpdated?: (args: { env: Env; context: StoredContext<Context> }) => void | Promise<void>\r\n  onEventCreated?: (event: ContextEvent) => void | Promise<void>\r\n  onToolCallExecuted?: (executionEvent: any) => void | Promise<void>\r\n  onEnd?: (\r\n    lastEvent: ContextEvent,\r\n  ) => void | { end?: boolean } | Promise<void | { end?: boolean }>\r\n}\r\n\r\nexport interface StoryStreamOptions {\r\n  /**\r\n   * Maximum loop iterations (LLM call → tool execution → repeat).\r\n   * Default: 20\r\n   */\r\n  maxIterations?: number\r\n\r\n  /**\r\n   * Maximum model steps per LLM call.\r\n   * Default: 1 (or 5 if you override it in your implementation).\r\n   */\r\n  maxModelSteps?: number\r\n\r\n  /**\r\n   * If true, we do not close the workflow writable stream.\r\n   * Default: false.\r\n   */\r\n  preventClose?: boolean\r\n\r\n  /**\r\n   * If true, we write a `finish` chunk to the workflow stream.\r\n   * Default: true.\r\n   */\r\n  sendFinish?: boolean\r\n}\r\n\r\nexport abstract class Story<Context, Env extends StoryEnvironment = StoryEnvironment> {\r\n  constructor(private opts: StoryOptions<Context, Env> = {}) {}\r\n\r\n  protected abstract initialize(\r\n    context: StoredContext<Context>,\r\n    env: Env,\r\n  ): Promise<Context> | Context\r\n\r\n  protected abstract buildSystemPrompt(\r\n    context: StoredContext<Context>,\r\n    env: Env,\r\n  ): Promise<string> | string\r\n\r\n  protected abstract buildTools(\r\n    context: StoredContext<Context>,\r\n    env: Env,\r\n  ): Promise<Record<string, Tool>> | Record<string, Tool>\r\n\r\n  /**\r\n   * First-class event expansion stage (runs on every iteration of the durable loop).\r\n   *\r\n   * Use this to expand/normalize events before they are converted into model messages.\r\n   * Typical use-cases:\r\n   * - Expand file/document references into text (LlamaCloud/Reducto/…)\r\n   * - Token compaction / summarization of older parts\r\n   * - Attaching derived context snippets to the next model call\r\n   *\r\n   * IMPORTANT:\r\n   * - This stage is ALWAYS executed by the engine.\r\n   * - If you don't provide an implementation, the default behavior is an identity transform\r\n   *   (events pass through unchanged).\r\n   * - If your implementation performs I/O, implement it as a `\"use step\"` function (provided via\r\n   *   the builder) so results are durable and replay-safe.\r\n   * - If it’s pure/deterministic, it can run in workflow context.\r\n   */\r\n  protected async expandEvents(\r\n    events: ContextEvent[],\r\n    _context: StoredContext<Context>,\r\n    _env: Env,\r\n  ): Promise<ContextEvent[]> {\r\n    return events\r\n  }\r\n\r\n  protected getModel(_context: StoredContext<Context>, _env: Env): any {\r\n    return \"openai/gpt-5\"\r\n  }\r\n\r\n  /**\r\n   * Return tool names that should terminate the loop after they execute.\r\n   * This mirrors the durable-agent style where “finalization” is a tool-driven boundary.\r\n   */\r\n  protected async getFinalizationToolNames(): Promise<string[]> {\r\n    return []\r\n  }\r\n\r\n  /**\r\n   * Workflow-first execution entrypoint.\r\n   *\r\n   * - The workflow owns the stream (`writable`).\r\n   * - All I/O is delegated to steps (store access, LLM streaming, stream writes).\r\n   * - This method returns metadata only.\r\n   */\r\n  public async stream(params: {\r\n    env: Env\r\n    incomingEvent: ContextEvent\r\n    contextIdentifier: ContextIdentifier | null\r\n    writable: WritableStream<UIMessageChunk>\r\n    options?: StoryStreamOptions\r\n  }) {\r\n    const maxIterations = params.options?.maxIterations ?? 20\r\n    const maxModelSteps = params.options?.maxModelSteps ?? 1\r\n    const preventClose = params.options?.preventClose ?? false\r\n    const sendFinish = params.options?.sendFinish ?? true\r\n\r\n    // 1) Ensure context exists (step)\r\n    const ctxResult = await getOrCreateContext<Context>(\r\n      params.env,\r\n      params.contextIdentifier,\r\n    )\r\n    const currentContext = ctxResult.context\r\n\r\n    const contextSelector: ContextIdentifier =\r\n      params.contextIdentifier?.id\r\n        ? { id: String(params.contextIdentifier.id) }\r\n        : params.contextIdentifier?.key\r\n          ? { key: params.contextIdentifier.key }\r\n          : { id: String(currentContext.id) }\r\n\r\n    // 1.5) Tell the client which context/thread to use (workflow-owned writable, written from a step).\r\n    await writeContextIdChunk({ writable: params.writable, contextId: String(currentContext.id) })\r\n\r\n    if (ctxResult.isNew) {\r\n      await this.opts.onContextCreated?.({ env: params.env, context: currentContext })\r\n    }\r\n\r\n    // 2) Persist trigger event + create execution shell (steps)\r\n    const triggerEvent = await saveEvent(params.env, contextSelector, params.incomingEvent)\r\n    const triggerEventId = triggerEvent.id\r\n\r\n    const reactionEventId = await generateId()\r\n\r\n    await updateContextStatus(params.env, contextSelector, \"streaming\")\r\n    const execution = await createExecution(params.env, contextSelector, triggerEventId, reactionEventId)\r\n    const executionId = execution.id\r\n\r\n    let reactionEvent: ContextEvent | null = null\r\n\r\n    const failExecution = async () => {\r\n      try {\r\n        await completeExecution(params.env, contextSelector, executionId, \"failed\")\r\n      } catch {\r\n        // noop\r\n      }\r\n      try {\r\n        await closeStoryStream({ writable: params.writable, preventClose, sendFinish })\r\n      } catch {\r\n        // noop\r\n      }\r\n    }\r\n\r\n    try {\r\n      for (let iter = 0; iter < maxIterations; iter++) {\r\n        const ctxRow = await getContext<Context>(params.env, contextSelector)\r\n        if (!ctxRow) throw new Error(\"Story: context not found\")\r\n\r\n        // Normalize/initialize context (workflow-level; may call steps if needed)\r\n        const nextContent = await this.initialize(ctxRow, params.env)\r\n        const updatedContext = await updateContextContent<Context>(\r\n          params.env,\r\n          contextSelector,\r\n          nextContent,\r\n        )\r\n\r\n        await this.opts.onContextUpdated?.({ env: params.env, context: updatedContext })\r\n\r\n        const systemPrompt = await this.buildSystemPrompt(updatedContext, params.env)\r\n        const toolsAll = await this.buildTools(updatedContext, params.env)\r\n\r\n        // Strip execute before sending to the model (manual tool loop)\r\n        const toolsForModel: Record<string, Tool> = {}\r\n        for (const [name, t] of Object.entries(toolsAll)) {\r\n          toolsForModel[name] = { ...(t as any) }\r\n          delete (toolsForModel[name] as any).execute\r\n        }\r\n\r\n        const events = await getEvents(params.env, contextSelector)\r\n        const expandedEvents = await this.expandEvents(events, updatedContext, params.env)\r\n        const messagesForModel: ModelMessage[] = await eventsToModelMessages(\r\n          params.env,\r\n          expandedEvents,\r\n        )\r\n\r\n        const { assistantEvent, toolCalls } = await doStoryStreamStep({\r\n          model: this.getModel(updatedContext, params.env),\r\n          system: systemPrompt,\r\n          messages: messagesForModel,\r\n          tools: toolsForModel,\r\n          writable: params.writable,\r\n          eventId: reactionEventId,\r\n          maxSteps: maxModelSteps,\r\n        })\r\n\r\n        // Persist/append the assistant event for this iteration\r\n        if (!reactionEvent) {\r\n          reactionEvent = await saveEvent(params.env, contextSelector, {\r\n            ...(assistantEvent as any),\r\n            status: \"pending\",\r\n          })\r\n        } else {\r\n          reactionEvent = await updateEvent(params.env, reactionEvent.id, {\r\n            ...(reactionEvent as any),\r\n            content: {\r\n              parts: [\r\n                ...((reactionEvent as any)?.content?.parts ?? []),\r\n                ...((assistantEvent as any)?.content?.parts ?? []),\r\n              ],\r\n            },\r\n            status: \"pending\",\r\n          } as any)\r\n        }\r\n\r\n        this.opts.onEventCreated?.(assistantEvent)\r\n\r\n        // Done: no tool calls requested by the model\r\n        if (!toolCalls.length) {\r\n          const endResult = await this.callOnEnd(assistantEvent)\r\n          if (endResult) {\r\n            // Mark reaction event completed\r\n            await updateEvent(params.env, reactionEventId, {\r\n              ...(reactionEvent as any),\r\n              status: \"completed\",\r\n            } as any)\r\n            await updateContextStatus(params.env, contextSelector, \"open\")\r\n            await completeExecution(params.env, contextSelector, executionId, \"completed\")\r\n            await closeStoryStream({ writable: params.writable, preventClose, sendFinish })\r\n            return {\r\n              contextId: currentContext.id,\r\n              triggerEventId,\r\n              reactionEventId,\r\n              executionId,\r\n            }\r\n          }\r\n        }\r\n\r\n        // Execute tool calls (workflow context; tool implementations decide step vs workflow)\r\n        const executionResults = await Promise.all(\r\n          toolCalls.map(async (tc: any) => {\r\n            const toolDef = (toolsAll as any)[tc.toolName] as any\r\n            if (!toolDef || typeof toolDef.execute !== \"function\") {\r\n              return {\r\n                tc,\r\n                success: false,\r\n                output: null,\r\n                errorText: `Tool \"${tc.toolName}\" not found or has no execute().`,\r\n              }\r\n            }\r\n            try {\r\n              const output = await toolDef.execute(tc.args, {\r\n                toolCallId: tc.toolCallId,\r\n                messages: messagesForModel,\r\n              })\r\n              return { tc, success: true, output }\r\n            } catch (e: any) {\r\n              return {\r\n                tc,\r\n                success: false,\r\n                output: null,\r\n                errorText: e instanceof Error ? e.message : String(e),\r\n              }\r\n            }\r\n          }),\r\n        )\r\n\r\n        // Emit tool outputs to the workflow stream (step)\r\n        await writeToolOutputs({\r\n          writable: params.writable,\r\n          results: executionResults.map((r: any) =>\r\n            r.success\r\n              ? ({ toolCallId: r.tc.toolCallId, success: true, output: r.output } as const)\r\n              : ({ toolCallId: r.tc.toolCallId, success: false, errorText: r.errorText } as const),\r\n          ),\r\n        })\r\n\r\n        // Merge tool results into persisted parts (so next LLM call can see them)\r\n        if (reactionEvent) {\r\n          let parts = (reactionEvent as any)?.content?.parts ?? []\r\n          for (const r of executionResults as any[]) {\r\n            parts = applyToolExecutionResultToParts(parts, r.tc, {\r\n              success: Boolean(r.success),\r\n              result: r.output,\r\n              message: r.errorText,\r\n            })\r\n          }\r\n\r\n          reactionEvent = await updateEvent(params.env, reactionEventId, {\r\n            ...(reactionEvent as any),\r\n            content: { parts },\r\n            status: \"pending\",\r\n          } as any)\r\n        }\r\n\r\n        // Callback for observability/integration\r\n        for (const r of executionResults as any[]) {\r\n          await this.opts.onToolCallExecuted?.({\r\n            toolCall: r.tc,\r\n            success: r.success,\r\n            output: r.output,\r\n            errorText: r.errorText,\r\n            eventId: reactionEventId,\r\n            executionId,\r\n          })\r\n        }\r\n\r\n        // Finalization boundary\r\n        const finalToolNames = await this.getFinalizationToolNames()\r\n        const shouldFinalize = (executionResults as any[]).some((r) =>\r\n          finalToolNames.includes(r.tc.toolName),\r\n        )\r\n\r\n        if (shouldFinalize) {\r\n          await updateEvent(params.env, reactionEventId, {\r\n            ...(reactionEvent as any),\r\n            status: \"completed\",\r\n          } as any)\r\n          await updateContextStatus(params.env, contextSelector, \"open\")\r\n          await completeExecution(params.env, contextSelector, executionId, \"completed\")\r\n          await closeStoryStream({ writable: params.writable, preventClose, sendFinish })\r\n          return {\r\n            contextId: currentContext.id,\r\n            triggerEventId,\r\n            reactionEventId,\r\n            executionId,\r\n          }\r\n        }\r\n      }\r\n\r\n      throw new Error(`Story: maxIterations reached (${maxIterations}) without completion`)\r\n    } catch (error) {\r\n      await failExecution()\r\n      throw error\r\n    }\r\n  }\r\n\r\n  private async callOnEnd(lastEvent: ContextEvent): Promise<boolean> {\r\n    if (!this.opts.onEnd) return true\r\n    const result = await this.opts.onEnd(lastEvent)\r\n    if (typeof result === \"boolean\") return result\r\n    if (result && typeof result === \"object\" && \"end\" in result) return Boolean((result as any).end)\r\n    return true\r\n  }\r\n}\r\n\r\n\r\n\r\n"]}