@ekairos/story 1.21.41-beta.0 → 1.21.43-beta.0

package/dist/ekairos.config.js

@@ -1,15 +1,4 @@
 import { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, } from "./story.config";
-const GLOBAL_EKAIROS_CONFIG = Symbol.for("@ekairos/story.ekairosConfig");
-function setGlobalEkairosConfig(config) {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ;
-        globalThis[GLOBAL_EKAIROS_CONFIG] = config;
-    }
-    catch {
-        // ignore
-    }
-}
 /**
  * Creates a small "framework-style" config object that can be executed in the step runtime.
  *
@@ -18,7 +7,7 @@ function setGlobalEkairosConfig(config) {
  */
 export function createEkairosConfig(params) {
     const stories = params.stories ?? [];
-    const config = {
+    return {
         stories,
         runtime: params.runtime,
         setup() {
@@ -34,8 +23,4 @@ export function createEkairosConfig(params) {
                 s.register();
         },
     };
-    // Register globally (process-level) so libraries/steps can access it transparently.
-    // Note: This does NOT call `setup()` (no runtime side-effects).
-    setGlobalEkairosConfig(config);
-    return config;
 }

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export { story, createStory, type StoryConfig, type StoryInstance, type StoryOptions, type StoryStreamOptions, Story, type RegistrableStoryBuilder, } from "./story";
-export type { StoryStore, ContextIdentifier, StoredContext, ContextEvent, } from "./story.store";
-export { registerStory, getStory, getStoryFactory, hasStory, listStories, type StoryKey, } from "./story.registry";
-export { storyDomain } from "./schema";
-export { didToolExecute } from "./story.toolcalls";
-export { USER_MESSAGE_TYPE, ASSISTANT_MESSAGE_TYPE, SYSTEM_MESSAGE_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserEventFromUIMessages, createAssistantEventFromUIMessages, convertToUIMessage, convertEventToModelMessages, convertEventsToModelMessages, convertModelMessageToEvent, type ResponseMessage, } from "./events";
+export { story, createStory, type StoryConfig, type StoryInstance, type StoryOptions, type StoryStreamOptions, Story, type RegistrableStoryBuilder, } from "./story.js";
+export type { StoryStore, ContextIdentifier, StoredContext, ContextEvent, } from "./story.store.js";
+export { registerStory, getStory, getStoryFactory, hasStory, listStories, type StoryKey, } from "./story.registry.js";
+export { storyDomain } from "./schema.js";
+export { didToolExecute } from "./story.toolcalls.js";
+export { USER_MESSAGE_TYPE, ASSISTANT_MESSAGE_TYPE, SYSTEM_MESSAGE_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserEventFromUIMessages, createAssistantEventFromUIMessages, convertToUIMessage, convertEventToModelMessages, convertEventsToModelMessages, convertModelMessageToEvent, type ResponseMessage, } from "./events.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { 
 // Story API
-story, createStory, Story, } from "./story";
-export { registerStory, getStory, getStoryFactory, hasStory, listStories, } from "./story.registry";
-export { storyDomain } from "./schema";
-export { didToolExecute } from "./story.toolcalls";
-export { USER_MESSAGE_TYPE, ASSISTANT_MESSAGE_TYPE, SYSTEM_MESSAGE_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserEventFromUIMessages, createAssistantEventFromUIMessages, convertToUIMessage, convertEventToModelMessages, convertEventsToModelMessages, convertModelMessageToEvent, } from "./events";
+story, createStory, Story, } from "./story.js";
+export { registerStory, getStory, getStoryFactory, hasStory, listStories, } from "./story.registry.js";
+export { storyDomain } from "./schema.js";
+export { didToolExecute } from "./story.toolcalls.js";
+export { USER_MESSAGE_TYPE, ASSISTANT_MESSAGE_TYPE, SYSTEM_MESSAGE_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserEventFromUIMessages, createAssistantEventFromUIMessages, convertToUIMessage, convertEventToModelMessages, convertEventsToModelMessages, convertModelMessageToEvent, } from "./events.js";

package/dist/runtime.d.ts

@@ -8,6 +8,5 @@
  * - Do NOT import this entrypoint from client/browser code.
  * - Keep `@ekairos/story` main entrypoint safe to import from schema/domain modules.
  */
-export { configureStoryRuntime, configureStoryRuntimeBootstrap, getEkairosConfig, isStoryRuntimeConfigured, resolveStoryRuntime, type StoryEnvironment, type StoryRuntime, type StoryRuntimeResolver, } from "./story.config";
+export { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, resolveStoryRuntime, type StoryEnvironment, type StoryRuntime, type StoryRuntimeResolver, } from "./story.config";
 export { createEkairosConfig, type EkairosConfig, type RegistrableStory, } from "./ekairos.config";
-export { withEkairosRuntime } from "./next";

package/dist/runtime.js

@@ -8,6 +8,5 @@
  * - Do NOT import this entrypoint from client/browser code.
  * - Keep `@ekairos/story` main entrypoint safe to import from schema/domain modules.
  */
-export { configureStoryRuntime, configureStoryRuntimeBootstrap, getEkairosConfig, isStoryRuntimeConfigured, resolveStoryRuntime, } from "./story.config";
+export { configureStoryRuntime, configureStoryRuntimeBootstrap, isStoryRuntimeConfigured, resolveStoryRuntime, } from "./story.config";
 export { createEkairosConfig, } from "./ekairos.config";
-export { withEkairosRuntime } from "./next";

package/dist/steps/reaction.steps.d.ts

@@ -0,0 +1,25 @@
+import { type ModelMessage } from "ai";
+import type { StoryEnvironment } from "../story.config";
+import type { ContextEvent, ContextIdentifier } from "../story.store";
+import type { SerializableToolForModel } from "../tools-to-model-tools";
+/**
+ * Executes a full "reaction" inside a single workflow step:
+ * - load events from store
+ * - convert events to model messages
+ * - run the streaming model call and emit chunks
+ * - extract tool calls from the resulting assistant event
+ */
+export declare function executeReaction(params: {
+    env: StoryEnvironment;
+    contextIdentifier: ContextIdentifier;
+    model: any;
+    system: string;
+    tools: Record<string, SerializableToolForModel>;
+    eventId: string;
+    maxSteps: number;
+    sendStart?: boolean;
+}): Promise<{
+    assistantEvent: ContextEvent;
+    toolCalls: any[];
+    messagesForModel: ModelMessage[];
+}>;

package/dist/steps/reaction.steps.js

@@ -0,0 +1,135 @@
+import { jsonSchema, gateway, smoothStream, stepCountIs, streamText, } from "ai";
+import { getWritable } from "workflow";
+import { resolveStoryRuntime } from "../story.config";
+import { extractToolCallsFromParts } from "../story.toolcalls";
+function safeErrorJson(error) {
+    const seen = new WeakSet();
+    const redactKey = (k) => /token|authorization|cookie|secret|api[_-]?key|password/i.test(k);
+    const err = error;
+    const payload = {
+        name: err?.name,
+        message: err?.message,
+        status: err?.status,
+        body: err?.body,
+        data: err?.data,
+        stack: err?.stack,
+    };
+    try {
+        return JSON.stringify(payload, (k, v) => {
+            if (redactKey(k))
+                return "[redacted]";
+            if (typeof v === "string" && v.length > 5000)
+                return "[truncated-string]";
+            if (typeof v === "object" && v !== null) {
+                if (seen.has(v))
+                    return "[circular]";
+                seen.add(v);
+            }
+            return v;
+        });
+    }
+    catch {
+        return JSON.stringify({ message: String(err?.message ?? "error") });
+    }
+}
+/**
+ * Executes a full "reaction" inside a single workflow step:
+ * - load events from store
+ * - convert events to model messages
+ * - run the streaming model call and emit chunks
+ * - extract tool calls from the resulting assistant event
+ */
+export async function executeReaction(params) {
+    "use step";
+    const { store } = await resolveStoryRuntime(params.env);
+    console.log("executeReaction: begin");
+    let events;
+    try {
+        console.log("executeReaction: store.getEvents begin");
+        events = await store.getEvents(params.contextIdentifier);
+        console.log("executeReaction: store.getEvents ok");
+    }
+    catch (error) {
+        console.error("executeReaction: store.getEvents failed");
+        throw error;
+    }
+    let messagesForModel;
+    try {
+        console.log("executeReaction: store.eventsToModelMessages begin");
+        messagesForModel = (await store.eventsToModelMessages(events));
+        console.log("executeReaction: store.eventsToModelMessages ok");
+    }
+    catch (error) {
+        console.error("executeReaction: store.eventsToModelMessages failed", safeErrorJson(error));
+        throw error;
+    }
+    const writable = getWritable();
+    // Match DurableAgent-style model init behavior:
+    const resolvedModel = typeof params.model === "string"
+        ? gateway(params.model)
+        : typeof params.model === "function"
+            ? await params.model()
+            : params.model;
+    // Wrap plain JSON Schema objects so the AI SDK doesn't attempt Zod conversion at runtime.
+    const toolsForStreamText = {};
+    for (const [name, t] of Object.entries(params.tools)) {
+        toolsForStreamText[name] = {
+            description: t?.description,
+            inputSchema: jsonSchema(t.inputSchema),
+        };
+    }
+    console.log("executeReaction: streamText begin");
+    const result = streamText({
+        model: resolvedModel,
+        system: params.system,
+        messages: messagesForModel,
+        tools: toolsForStreamText,
+        toolChoice: "required",
+        stopWhen: stepCountIs(params.maxSteps),
+        experimental_transform: smoothStream({ delayInMs: 30, chunking: "word" }),
+    });
+    console.log("executeReaction: streamText ok");
+    // Ensure the underlying stream is consumed (AI SDK requirement)
+    result.consumeStream();
+    let resolveFinish;
+    let rejectFinish;
+    const finishPromise = new Promise((resolve, reject) => {
+        resolveFinish = resolve;
+        rejectFinish = reject;
+    });
+    const uiStream = result
+        .toUIMessageStream({
+        sendStart: Boolean(params.sendStart),
+        generateMessageId: () => params.eventId,
+        messageMetadata() {
+            return { eventId: params.eventId };
+        },
+        onFinish: ({ messages }) => {
+            const lastMessage = messages[messages.length - 1];
+            const event = {
+                id: params.eventId,
+                type: "assistant.message",
+                channel: "web",
+                createdAt: new Date().toISOString(),
+                content: { parts: lastMessage?.parts ?? [] },
+            };
+            resolveFinish(event);
+        },
+        onError: (e) => {
+            rejectFinish(e);
+            return e instanceof Error ? e.message : String(e);
+        },
+    })
+        // Filter out per-step finish boundary. Workflow will emit a single finish.
+        .pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            if (chunk.type === "finish")
+                return;
+            controller.enqueue(chunk);
+        },
+    }));
+    await uiStream.pipeTo(writable, { preventClose: true });
+    const assistantEvent = await finishPromise;
+    const toolCalls = extractToolCallsFromParts(assistantEvent?.content?.parts);
+    return { assistantEvent, toolCalls, messagesForModel };
+}

package/dist/steps/store.steps.d.ts

@@ -1,43 +1,28 @@
-import type { ModelMessage } from "ai";
 import { type StoryEnvironment } from "../story.config";
 import type { ContextEvent, ContextIdentifier, StoredContext } from "../story.store";
-export declare function generateId(): Promise<string>;
-export declare function getOrCreateContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null): Promise<{
-    context: StoredContext<C>;
-    isNew: boolean;
-}>;
 /**
- * Ensures a context exists and emits a single `data-context-id` chunk to the workflow stream.
+ * Initializes/ensures the story context exists and emits a single `data-context-id` chunk.
  *
- * Why this exists:
- * - `getOrCreateContext(...)` and `writeContextIdChunk(...)` are semantically coupled.
- * - Keeping them in a single step reduces step invocations per run (cheaper) without changing behavior.
+ * This is the "context init" boundary for the story engine.
  */
-export declare function ensureContextAndEmitContextId<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null): Promise<{
+export declare function initializeContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null): Promise<{
     context: StoredContext<C>;
     isNew: boolean;
 }>;
-export declare function getContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier): Promise<StoredContext<C> | null>;
-/**
- * Loads the state needed for a single Story loop iteration.
- *
- * This is a "read aggregation" step: it groups read-only store calls into a single workflow step
- * invocation to reduce step overhead (cheaper) without changing behavior.
- */
-export declare function loadTurnState<C>(params: {
-    env: StoryEnvironment;
-    contextIdentifier: ContextIdentifier;
-}): Promise<{
-    context: StoredContext<C> | null;
-    events: ContextEvent[];
-}>;
 export declare function updateContextContent<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier, content: C): Promise<StoredContext<C>>;
 export declare function updateContextStatus(env: StoryEnvironment, contextIdentifier: ContextIdentifier, status: "open" | "streaming" | "closed"): Promise<void>;
-export declare function saveEvent(env: StoryEnvironment, contextIdentifier: ContextIdentifier, event: ContextEvent): Promise<ContextEvent>;
+export declare function saveTriggerEvent(env: StoryEnvironment, contextIdentifier: ContextIdentifier, event: ContextEvent): Promise<ContextEvent>;
+export declare function saveReactionEvent(env: StoryEnvironment, contextIdentifier: ContextIdentifier, event: ContextEvent): Promise<ContextEvent>;
 export declare function updateEvent(env: StoryEnvironment, eventId: string, event: ContextEvent): Promise<ContextEvent>;
-export declare function getEvents(env: StoryEnvironment, contextIdentifier: ContextIdentifier): Promise<ContextEvent[]>;
 export declare function createExecution(env: StoryEnvironment, contextIdentifier: ContextIdentifier, triggerEventId: string, reactionEventId: string): Promise<{
     id: string;
 }>;
+export declare function createReactionEvent(params: {
+    env: StoryEnvironment;
+    contextIdentifier: ContextIdentifier;
+    triggerEventId: string;
+}): Promise<{
+    reactionEventId: string;
+    executionId: string;
+}>;
 export declare function completeExecution(env: StoryEnvironment, contextIdentifier: ContextIdentifier, executionId: string, status: "completed" | "failed"): Promise<void>;
-export declare function eventsToModelMessages(env: StoryEnvironment, events: ContextEvent[]): Promise<ModelMessage[]>;

package/dist/steps/store.steps.js

@@ -1,36 +1,11 @@
 import { getWritable } from "workflow";
 import { resolveStoryRuntime } from "../story.config";
-export async function generateId() {
-    "use step";
-    // Use crypto.randomUUID when available (Node 18+)
-    const uuid = globalThis.crypto?.randomUUID?.();
-    if (uuid)
-        return uuid;
-    // Fallback
-    return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
-}
-export async function getOrCreateContext(env, contextIdentifier) {
-    "use step";
-    const { store } = await resolveStoryRuntime(env);
-    // Detect creation explicitly so the engine can run onContextCreated hooks.
-    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 created = await store.getOrCreateContext(contextIdentifier);
-    return { context: created, isNew: true };
-}
 /**
- * Ensures a context exists and emits a single `data-context-id` chunk to the workflow stream.
+ * Initializes/ensures the story context exists and emits a single `data-context-id` chunk.
  *
- * Why this exists:
- * - `getOrCreateContext(...)` and `writeContextIdChunk(...)` are semantically coupled.
- * - Keeping them in a single step reduces step invocations per run (cheaper) without changing behavior.
+ * This is the "context init" boundary for the story engine.
  */
-export async function ensureContextAndEmitContextId(env, contextIdentifier) {
+export async function initializeContext(env, contextIdentifier) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
     // Detect creation explicitly so the engine can run onContextCreated hooks.
@@ -63,24 +38,6 @@ export async function ensureContextAndEmitContextId(env, contextIdentifier) {
     }
     return result;
 }
-export async function getContext(env, contextIdentifier) {
-    "use step";
-    const { store } = await resolveStoryRuntime(env);
-    return await store.getContext(contextIdentifier);
-}
-/**
- * Loads the state needed for a single Story loop iteration.
- *
- * This is a "read aggregation" step: it groups read-only store calls into a single workflow step
- * invocation to reduce step overhead (cheaper) without changing behavior.
- */
-export async function loadTurnState(params) {
-    "use step";
-    const { store } = await resolveStoryRuntime(params.env);
-    const context = await store.getContext(params.contextIdentifier);
-    const events = await store.getEvents(params.contextIdentifier);
-    return { context, events };
-}
 export async function updateContextContent(env, contextIdentifier, content) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
@@ -91,33 +48,40 @@ export async function updateContextStatus(env, contextIdentifier, status) {
     const { store } = await resolveStoryRuntime(env);
     await store.updateContextStatus(contextIdentifier, status);
 }
-export async function saveEvent(env, contextIdentifier, event) {
+export async function saveTriggerEvent(env, contextIdentifier, event) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
     return await store.saveEvent(contextIdentifier, event);
 }
-export async function updateEvent(env, eventId, event) {
+export async function saveReactionEvent(env, contextIdentifier, event) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
-    return await store.updateEvent(eventId, event);
+    return await store.saveEvent(contextIdentifier, event);
 }
-export async function getEvents(env, contextIdentifier) {
+export async function updateEvent(env, eventId, event) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
-    return await store.getEvents(contextIdentifier);
+    return await store.updateEvent(eventId, event);
 }
 export async function createExecution(env, contextIdentifier, triggerEventId, reactionEventId) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
     return await store.createExecution(contextIdentifier, triggerEventId, reactionEventId);
 }
-export async function completeExecution(env, contextIdentifier, executionId, status) {
+export async function createReactionEvent(params) {
     "use step";
-    const { store } = await resolveStoryRuntime(env);
-    await store.completeExecution(contextIdentifier, executionId, status);
+    const { store } = await resolveStoryRuntime(params.env);
+    // Generate a new reaction event id inside the step boundary.
+    const uuid = globalThis.crypto?.randomUUID?.();
+    const reactionEventId = typeof uuid === "string"
+        ? uuid
+        : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    await store.updateContextStatus(params.contextIdentifier, "streaming");
+    const execution = await store.createExecution(params.contextIdentifier, params.triggerEventId, reactionEventId);
+    return { reactionEventId, executionId: execution.id };
 }
-export async function eventsToModelMessages(env, events) {
+export async function completeExecution(env, contextIdentifier, executionId, status) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
-    return await store.eventsToModelMessages(events);
+    await store.completeExecution(contextIdentifier, executionId, status);
 }

package/dist/steps/stream.steps.d.ts

@@ -11,6 +11,13 @@ export declare function writeContextSubstate(params: {
 export declare function writeContextIdChunk(params: {
     contextId: string;
 }): Promise<void>;
+export declare function writeStoryPing(params: {
+    /**
+     * Simple ping event to validate that the workflow stream is alive.
+     * This is intentionally generic so clients can ignore it safely.
+     */
+    label?: string;
+}): Promise<void>;
 export declare function writeToolOutputs(params: {
     results: Array<{
         toolCallId: string;

package/dist/steps/stream.steps.js

@@ -29,6 +29,21 @@ export async function writeContextIdChunk(params) {
         writer.releaseLock();
     }
 }
+export async function writeStoryPing(params) {
+    "use step";
+    const writable = getWritable();
+    const writer = writable.getWriter();
+    try {
+        await writer.write({
+            type: "data-story-ping",
+            data: { label: params.label ?? "story-ping" },
+            transient: true,
+        });
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
 export async function writeToolOutputs(params) {
     "use step";
     const writable = getWritable();

package/dist/stores/instant.document-parser.d.ts

@@ -2,4 +2,4 @@
  * Parses a document with LlamaParse and stores it in InstantDB (document_documents + link to file).
  * Returns the created documentId.
  */
-export declare function parseAndStoreDocument(db: any, buffer: Buffer, fileName: string, path: string, fileId: string): Promise<string>;
+export declare function parseAndStoreDocument(db: any, buffer: Buffer, fileName: string, fileId: string): Promise<string>;

package/dist/stores/instant.document-parser.js

@@ -1,7 +1,75 @@
 import { id } from "@instantdb/admin";
 const LLAMA_CLOUD_BASE_URL = "https://api.cloud.llamaindex.ai/api/v1";
+function safeErrorJson(error) {
+    const seen = new WeakSet();
+    const redactKey = (k) => /token|authorization|cookie|secret|api[_-]?key|password/i.test(k);
+    const err = error;
+    const payload = {
+        name: err?.name,
+        message: err?.message,
+        status: err?.status,
+        body: err?.body,
+        data: err?.data,
+        stack: err?.stack,
+    };
+    try {
+        return JSON.stringify(payload, (k, v) => {
+            if (redactKey(k))
+                return "[redacted]";
+            if (typeof v === "string" && v.length > 5000)
+                return "[truncated-string]";
+            if (typeof v === "object" && v !== null) {
+                if (seen.has(v))
+                    return "[circular]";
+                seen.add(v);
+            }
+            return v;
+        });
+    }
+    catch {
+        return JSON.stringify({ message: String(err?.message ?? "error") });
+    }
+}
+async function probeInstantDocumentSchema(db) {
+    // Best-effort probes to pinpoint missing schema pieces WITHOUT logging dynamic payloads.
+    // Each line is a static string.
+    try {
+        console.log("Instant schema probe: document_documents entity query begin");
+        await db.query({ document_documents: { $: { limit: 1 } } });
+        console.log("Instant schema probe: document_documents entity query ok");
+    }
+    catch {
+        console.error("Instant schema probe: document_documents entity query failed");
+    }
+    try {
+        console.log("Instant schema probe: document_documents.file link query begin");
+        await db.query({ document_documents: { $: { limit: 1 }, file: {} } });
+        console.log("Instant schema probe: document_documents.file link query ok");
+    }
+    catch {
+        console.error("Instant schema probe: document_documents.file link query failed");
+    }
+    try {
+        console.log("Instant schema probe: $files entity query begin");
+        await db.query({ $files: { $: { limit: 1 } } });
+        console.log("Instant schema probe: $files entity query ok");
+    }
+    catch {
+        console.error("Instant schema probe: $files entity query failed");
+    }
+    try {
+        console.log("Instant schema probe: $files.document link query begin");
+        await db.query({ $files: { $: { limit: 1 }, document: {} } });
+        console.log("Instant schema probe: $files.document link query ok");
+    }
+    catch {
+        console.error("Instant schema probe: $files.document link query failed");
+    }
+}
 async function uploadToLlamaCloud(buffer, fileName) {
+    console.log("LlamaCloud: upload begin");
     const formData = new FormData();
+    console.log("LlamaCloud: upload build form-data begin");
     const uint8Array = new Uint8Array(buffer);
     const blob = new Blob([uint8Array], { type: "application/pdf" });
     formData.append("file", blob, fileName);
@@ -10,77 +78,132 @@ async function uploadToLlamaCloud(buffer, fileName) {
     formData.append("adaptive_long_table", "true");
     formData.append("outlined_table_extraction", "true");
     formData.append("output_tables_as_HTML", "true");
-    const response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/upload`, {
-        method: "POST",
-        headers: {
-            Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
-        },
-        body: formData,
-    });
+    console.log("LlamaCloud: upload build form-data ok");
+    console.log("LlamaCloud: upload fetch begin");
+    let response;
+    try {
+        response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/upload`, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
+            },
+            body: formData,
+        });
+    }
+    catch (error) {
+        console.log("LlamaCloud: upload fetch threw", safeErrorJson(error));
+        throw error;
+    }
+    console.log("LlamaCloud: upload fetch ok");
     if (!response.ok) {
+        console.log("LlamaCloud: upload failed");
         const errorText = await response.text();
         throw new Error(`LlamaCloud upload failed: ${response.status} ${errorText}`);
     }
+    console.log("LlamaCloud: upload ok");
     const result = (await response.json());
     return result.id;
 }
 async function getJobStatus(jobId) {
-    const response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/job/${jobId}`, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
-        },
-    });
+    console.log("LlamaCloud: status fetch begin");
+    console.log("LlamaCloud: status fetch request begin");
+    let response;
+    try {
+        response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/job/${jobId}`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
+            },
+        });
+    }
+    catch (error) {
+        console.log("LlamaCloud: status fetch threw", safeErrorJson(error));
+        throw error;
+    }
+    console.log("LlamaCloud: status fetch request ok");
     if (!response.ok) {
+        console.log("LlamaCloud: status fetch failed");
         const errorText = await response.text();
         throw new Error(`LlamaCloud status fetch failed: ${response.status} ${errorText}`);
     }
+    console.log("LlamaCloud: status fetch ok");
     return (await response.json());
 }
 async function getParseResult(jobId) {
-    const response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/job/${jobId}/result/markdown`, {
-        method: "GET",
-        headers: {
-            Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
-        },
-    });
+    console.log("LlamaCloud: result fetch begin");
+    console.log("LlamaCloud: result fetch request begin");
+    let response;
+    try {
+        response = await fetch(`${LLAMA_CLOUD_BASE_URL}/parsing/job/${jobId}/result/markdown`, {
+            method: "GET",
+            headers: {
+                Authorization: `Bearer ${process.env.LLAMA_CLOUD_API_KEY}`,
+            },
+        });
+    }
+    catch (error) {
+        console.log("LlamaCloud: result fetch threw", safeErrorJson(error));
+        throw error;
+    }
+    console.log("LlamaCloud: result fetch request ok");
     if (!response.ok) {
+        console.log("LlamaCloud: result fetch failed");
         const errorText = await response.text();
         throw new Error(`LlamaCloud result fetch failed: ${response.status} ${errorText}`);
     }
+    console.log("LlamaCloud: result fetch ok");
     return (await response.json());
 }
 async function waitForProcessing(jobId, maxAttempts = 60) {
+    console.log("LlamaCloud: waitForProcessing begin");
     for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        console.log("LlamaCloud: waitForProcessing poll");
         const statusResponse = await getJobStatus(jobId);
         if (statusResponse.status === "SUCCESS" || statusResponse.status === "COMPLETED") {
+            console.log("LlamaCloud: waitForProcessing completed");
             return await getParseResult(jobId);
         }
         if (statusResponse.status === "ERROR" || statusResponse.status === "FAILED") {
+            console.log("LlamaCloud: waitForProcessing failed");
             throw new Error(`LlamaCloud processing failed with status: ${statusResponse.status}`);
         }
         await new Promise((resolve) => setTimeout(resolve, 2000));
     }
+    console.log("LlamaCloud: waitForProcessing timeout");
     throw new Error("LlamaCloud processing timeout");
 }
 /**
  * Parses a document with LlamaParse and stores it in InstantDB (document_documents + link to file).
  * Returns the created documentId.
  */
-export async function parseAndStoreDocument(db, buffer, fileName, path, fileId) {
-    const existingDocument = await db.query({
-        document_documents: {
-            $: {
-                where: { "file.id": fileId },
+export async function parseAndStoreDocument(db, buffer, fileName, fileId) {
+    console.log("parseAndStoreDocument: begin");
+    console.log("parseAndStoreDocument: query existing begin");
+    let existingDocument;
+    try {
+        existingDocument = await db.query({
+            document_documents: {
+                $: {
+                    where: { "file.id": fileId },
+                },
+                file: {},
             },
-            file: {},
-        },
-    });
+        });
+    }
+    catch (error) {
+        console.error("parseAndStoreDocument: query existing failed", safeErrorJson(error));
+        throw error;
+    }
+    console.log("parseAndStoreDocument: query existing ok");
     if (existingDocument.document_documents && existingDocument.document_documents.length > 0) {
+        console.log("parseAndStoreDocument: existing document found");
         return existingDocument.document_documents[0].id;
     }
+    console.log("parseAndStoreDocument: no existing document; start upload");
     const jobId = await uploadToLlamaCloud(buffer, fileName);
+    console.log("parseAndStoreDocument: upload ok; waitForProcessing begin");
     const result = await waitForProcessing(jobId);
+    console.log("parseAndStoreDocument: waitForProcessing ok; build pages begin");
     const pages = [];
     if (result.markdown) {
         pages.push({
@@ -97,20 +220,33 @@ export async function parseAndStoreDocument(db, buffer, fileName, path, fileId)
         }
     }
     if (pages.length === 0) {
+        console.log("parseAndStoreDocument: no content extracted");
         throw new Error("No content extracted from document");
     }
     const documentId = id();
-    await db.transact([
-        db.tx.document_documents[documentId].update({
-            content: { pages },
-            name: fileName,
-            mimeType: "application/pdf",
-            createdAt: new Date(),
-            path,
-        }),
-        db.tx.document_documents[documentId].link({
-            file: fileId,
-        }),
-    ]);
+    console.log("parseAndStoreDocument: transact begin");
+    try {
+        console.log("parseAndStoreDocument: transact update document_documents begin");
+        console.log("parseAndStoreDocument: transact link document->file begin");
+        await db.transact([
+            db.tx.document_documents[documentId].update({
+                content: { pages },
+                name: fileName,
+                mimeType: "application/pdf",
+                createdAt: new Date(),
+            }),
+            db.tx.document_documents[documentId].link({
+                file: fileId,
+            }),
+        ]);
+    }
+    catch (error) {
+        console.error("parseAndStoreDocument: transact failed", safeErrorJson(error));
+        // Diagnose missing schema attributes/links (static logs only).
+        await probeInstantDocumentSchema(db);
+        throw error;
+    }
+    console.log("parseAndStoreDocument: transact ok");
+    console.log("parseAndStoreDocument: end");
     return documentId;
 }

package/dist/stores/instant.documents.js

@@ -4,6 +4,14 @@ function isFilePart(part) {
         typeof part === "object" &&
         (part.type === "file" || part?.providerMetadata?.instant));
 }
+function formatAttachmentSummary(part) {
+    const instant = part?.providerMetadata?.instant ?? {};
+    const fileId = typeof instant?.fileId === "string" ? instant.fileId : "";
+    const filename = typeof part?.filename === "string" ? part.filename : "";
+    const mediaType = typeof part?.mediaType === "string" ? part.mediaType : "";
+    // Keep it compact; no URLs (can be signed/sensitive).
+    return `fileId="${fileId}" filename="${filename}" mediaType="${mediaType}"`;
+}
 export function coerceDocumentTextPages(documentRecord, opts) {
     const pages = documentRecord?.content?.pages;
     if (!Array.isArray(pages) || pages.length === 0)
@@ -17,75 +25,139 @@ export function coerceDocumentTextPages(documentRecord, opts) {
         .join("");
 }
 async function resolveInstantFileRecord(db, params) {
+    console.log("expandEventsWithInstantDocuments: resolveInstantFileRecord begin");
     const fileId = params.fileId ? String(params.fileId) : null;
     const filePath = params.path ? String(params.path) : null;
     if (!fileId && !filePath)
         return null;
     if (fileId) {
+        console.log("expandEventsWithInstantDocuments: resolveInstantFileRecord query by id");
         const q = await db.query({
             $files: { $: { where: { id: fileId }, limit: 1 }, document: {} },
         });
+        console.log("expandEventsWithInstantDocuments: resolveInstantFileRecord query by id ok");
         return q?.$files?.[0] ?? null;
     }
+    console.log("expandEventsWithInstantDocuments: resolveInstantFileRecord query by path");
     const q = await db.query({
         $files: { $: { where: { path: filePath }, limit: 1 }, document: {} },
     });
+    console.log("expandEventsWithInstantDocuments: resolveInstantFileRecord query by path ok");
     return q?.$files?.[0] ?? null;
 }
 async function ensureDocumentParsedForFile(db, params) {
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile begin");
     const fileRecord = params.fileRecord;
     const part = params.part;
     let documentRecord = Array.isArray(fileRecord?.document)
         ? fileRecord.document?.[0]
         : fileRecord.document;
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile check existing document link");
     if (documentRecord?.id)
         return documentRecord;
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile no existing doc; fetch file url");
     const fileUrl = typeof fileRecord?.url === "string" ? fileRecord.url : "";
     if (!fileUrl.startsWith("http://") && !fileUrl.startsWith("https://")) {
+        console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile invalid file url");
         return null;
     }
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile fetch begin");
     const resp = await fetch(fileUrl);
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile fetch ok");
     if (!resp.ok)
         throw new Error(`Failed to fetch file for parsing: HTTP ${resp.status}`);
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile buffer begin");
     const buffer = Buffer.from(await resp.arrayBuffer());
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile buffer ok");
     const name = (typeof part?.filename === "string" && part.filename) ||
         (typeof fileRecord?.path === "string" && fileRecord.path) ||
         "file";
-    const path = (typeof fileRecord?.path === "string" && fileRecord.path) ||
-        `/agent/${Date.now()}-${name}`;
-    const documentId = await parseAndStoreDocument(db, buffer, name, path, String(fileRecord.id));
+    // NOTE: Do not invent fallback paths. If the file doesn't have a stable `path`,
+    // we don't fabricate one.
+    const path = typeof fileRecord?.path === "string" ? fileRecord.path : undefined;
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile parseAndStoreDocument begin");
+    const documentId = await parseAndStoreDocument(db, buffer, name, String(fileRecord.id));
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile parseAndStoreDocument ok");
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile query document_documents begin");
     const dq = await db.query({
         document_documents: { $: { where: { id: documentId }, limit: 1 }, file: {} },
     });
+    console.log("expandEventsWithInstantDocuments: ensureDocumentParsedForFile query document_documents ok");
     documentRecord = dq?.document_documents?.[0] ?? null;
     return documentRecord;
 }
 export async function expandEventsWithInstantDocuments(params) {
+    console.log("expandEventsWithInstantDocuments: begin");
     const db = params.db;
     const maxChars = typeof params.maxChars === "number" ? params.maxChars : 120000;
     const derivedEventType = params.derivedEventType ?? "document.parsed";
     const out = [];
+    console.log("expandEventsWithInstantDocuments: loop events begin");
     for (const event of params.events) {
-        out.push(event);
         const parts = event?.content?.parts;
-        if (!Array.isArray(parts) || parts.length === 0)
+        if (!Array.isArray(parts) || parts.length === 0) {
+            out.push(event);
             continue;
+        }
+        console.log("expandEventsWithInstantDocuments: inspect event parts");
+        const hadFileParts = parts.some((p) => isFilePart(p));
+        if (hadFileParts) {
+            // Do not forward file parts to the model (gateways may not support some media types).
+            // The derived `document.parsed` event contains the extracted text.
+            const filtered = parts.filter((p) => !isFilePart(p));
+            const attachmentSummaries = parts
+                .filter((p) => isFilePart(p))
+                .map((p) => formatAttachmentSummary(p))
+                .join("\n");
+            const attachmentInfoText = attachmentSummaries
+                ? `Attachment info:\n${attachmentSummaries}`
+                : "Attachment info: (unavailable)";
+            const sanitized = {
+                ...event,
+                content: {
+                    ...event?.content,
+                    parts: [
+                        ...filtered,
+                        {
+                            type: "text",
+                            text: "[Attachment omitted from model input. Parsed content will follow in a document.parsed event.]\n" +
+                                attachmentInfoText,
+                        },
+                    ],
+                },
+            };
+            out.push(sanitized);
+        }
+        else {
+            out.push(event);
+        }
         for (const part of parts) {
             if (!isFilePart(part))
                 continue;
+            console.log("expandEventsWithInstantDocuments: file part detected");
             const instantMeta = part?.providerMetadata?.instant ?? {};
             const fileId = instantMeta?.fileId ? String(instantMeta.fileId) : undefined;
             const filePath = instantMeta?.path ? String(instantMeta.path) : undefined;
+            console.log("expandEventsWithInstantDocuments: resolve file record begin");
             const fileRecord = await resolveInstantFileRecord(db, { fileId, path: filePath });
+            console.log("expandEventsWithInstantDocuments: resolve file record ok");
             if (!fileRecord?.id)
                 continue;
+            console.log("expandEventsWithInstantDocuments: ensure document parsed begin");
             const documentRecord = await ensureDocumentParsedForFile(db, { fileRecord, part });
+            console.log("expandEventsWithInstantDocuments: ensure document parsed ok");
+            console.log("expandEventsWithInstantDocuments: coerce document pages begin");
             const pageText = coerceDocumentTextPages(documentRecord);
+            console.log("expandEventsWithInstantDocuments: coerce document pages ok");
             if (!pageText)
                 continue;
+            console.log("expandEventsWithInstantDocuments: clip extracted text begin");
             const clipped = pageText.length > maxChars
                 ? `${pageText.slice(0, maxChars)}\n\n[truncated: maxChars=${maxChars}]`
                 : pageText;
+            console.log("expandEventsWithInstantDocuments: clip extracted text ok");
+            console.log("expandEventsWithInstantDocuments: create derived document.parsed event");
+            const derivedAttachmentInfo = `Attachment info:\n${formatAttachmentSummary(part)}`;
             const derived = {
                 id: `derived:${event.id}:${String(fileRecord.id)}`,
                 type: derivedEventType,
@@ -95,14 +167,18 @@ export async function expandEventsWithInstantDocuments(params) {
                     parts: [
                         {
                             type: "text",
-                            text: `Parsed document available.\nFile: "${String(fileRecord.path || part.filename || "file")}"\nProvider: llamacloud`,
+                            text: "Parsed document available.\n" +
+                                derivedAttachmentInfo +
+                                "\nProvider: llamacloud",
                         },
                         { type: "text", text: `Document transcription:${clipped}` },
                     ],
                 },
             };
             out.push(derived);
+            console.log("expandEventsWithInstantDocuments: derived event appended");
         }
     }
+    console.log("expandEventsWithInstantDocuments: end");
     return out;
 }

package/dist/stores/instant.store.d.ts

@@ -12,6 +12,8 @@ export type InstantStoreDb = any;
 export declare class InstantStore implements StoryStore {
     private db;
     constructor(db: InstantStoreDb);
+    private debugEventExpansionEnabled;
+    private debugLog;
     getOrCreateContext<C>(contextIdentifier: ContextIdentifier | null): Promise<StoredContext<C>>;
     private createContext;
     getContext<C>(contextIdentifier: ContextIdentifier): Promise<StoredContext<C> | null>;

package/dist/stores/instant.store.js

@@ -7,6 +7,15 @@ export class InstantStore {
     constructor(db) {
         this.db = db;
     }
+    debugEventExpansionEnabled() {
+        return process.env.EKAIROS_DEBUG_EVENT_EXPANSION === "1";
+    }
+    debugLog(message) {
+        if (!this.debugEventExpansionEnabled())
+            return;
+        // CRITICAL: static strings only (no dynamic values in logs).
+        console.log(message);
+    }
     async getOrCreateContext(contextIdentifier) {
         if (!contextIdentifier) {
             return this.createContext();
@@ -172,14 +181,18 @@ export class InstantStore {
         await this.db.transact(txs);
     }
     async eventsToModelMessages(events) {
+        this.debugLog("InstantStore.eventsToModelMessages: begin");
         // Default behavior for Instant-backed stories:
         // - Expand file parts into derived `document.parsed` events (persisting parsed content into document_documents)
         // - Then convert expanded events to model messages
+        this.debugLog("InstantStore.eventsToModelMessages: expandEventsWithInstantDocuments begin");
         const expanded = await expandEventsWithInstantDocuments({
             db: this.db,
             events,
             derivedEventType: "document.parsed",
         });
+        this.debugLog("InstantStore.eventsToModelMessages: expandEventsWithInstantDocuments ok");
+        this.debugLog("InstantStore.eventsToModelMessages: convertEventsToModelMessages begin");
         return await convertEventsToModelMessages(expanded);
     }
 }

package/dist/story.builder.d.ts

@@ -1,8 +1,8 @@
 import type { Tool } from "ai";
-import type { StoryEnvironment } from "./story.config";
-import { Story, type StoryModelInit, type StoryOptions, type ShouldContinue, type StoryShouldContinueArgs, type StoryReactParams } from "./story.engine";
-import type { ContextEvent, StoredContext } from "./story.store";
-import { type StoryKey } from "./story.registry";
+import type { StoryEnvironment } from "./story.config.js";
+import { Story, type StoryModelInit, type StoryOptions, type ShouldContinue, type StoryShouldContinueArgs, type StoryReactParams } from "./story.engine.js";
+import type { ContextEvent, StoredContext } from "./story.store.js";
+import { type StoryKey } from "./story.registry.js";
 export interface StoryConfig<Context, Env extends StoryEnvironment = StoryEnvironment> {
     context: (context: StoredContext<Context>, env: Env) => Promise<Context> | Context;
     /**

package/dist/story.builder.js

@@ -1,5 +1,5 @@
-import { Story, } from "./story.engine";
-import { registerStory } from "./story.registry";
+import { Story, } from "./story.engine.js";
+import { registerStory } from "./story.registry.js";
 export function story(config) {
     class FunctionalStory extends Story {
         constructor() {

package/dist/story.config.d.ts

@@ -1,5 +1,4 @@
 import type { StoryStore } from "./story.store";
-import type { EkairosConfig } from "./ekairos.config";
 /**
  * ## story.config.ts
  *
@@ -17,7 +16,6 @@ export type StoryRuntime = {
     store: StoryStore;
 };
 export type StoryRuntimeResolver<Env extends StoryEnvironment = StoryEnvironment> = (env: Env) => Promise<StoryRuntime> | StoryRuntime;
-export declare function getEkairosConfig(): EkairosConfig | null;
 /**
  * Optional global bootstrap hook for step runtimes.
  *

package/dist/story.config.js

@@ -1,37 +1,12 @@
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
 let runtimeResolver = null;
-const GLOBAL_RUNTIME_RESOLVER = Symbol.for("@ekairos/story.runtimeResolver");
-const GLOBAL_RUNTIME_BOOTSTRAP = Symbol.for("@ekairos/story.runtimeBootstrap");
-const GLOBAL_EKAIROS_CONFIG = Symbol.for("@ekairos/story.ekairosConfig");
-function getGlobal(key) {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const v = globalThis?.[key];
-        return v ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-function setGlobal(key, value) {
-    try {
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        ;
-        globalThis[key] = value;
-    }
-    catch {
-        // ignore
-    }
-}
 function getRuntimeResolver() {
-    return runtimeResolver ?? getGlobal(GLOBAL_RUNTIME_RESOLVER);
-}
-export function getEkairosConfig() {
-    return getGlobal(GLOBAL_EKAIROS_CONFIG);
+    return runtimeResolver;
 }
 let runtimeBootstrap = null;
 export function configureStoryRuntimeBootstrap(bootstrap) {
     runtimeBootstrap = bootstrap;
-    setGlobal(GLOBAL_RUNTIME_BOOTSTRAP, bootstrap);
 }
 /**
  * Configure the story runtime resolver (global).
@@ -41,7 +16,6 @@ export function configureStoryRuntimeBootstrap(bootstrap) {
  */
 export function configureStoryRuntime(resolver) {
     runtimeResolver = resolver;
-    setGlobal(GLOBAL_RUNTIME_RESOLVER, runtimeResolver);
 }
 export function isStoryRuntimeConfigured() {
     return Boolean(runtimeResolver);
@@ -49,15 +23,45 @@ export function isStoryRuntimeConfigured() {
 export async function resolveStoryRuntime(env) {
     if (!getRuntimeResolver()) {
         // Best-effort: allow the step runtime to self-bootstrap once.
-        const bootstrap = runtimeBootstrap ?? getGlobal(GLOBAL_RUNTIME_BOOTSTRAP);
-        if (bootstrap)
-            await bootstrap();
-        // Transparent fallback: if the host app created an `ekairosConfig` (via createEkairosConfig),
-        // it is available process-wide. We only call setup() when runtime is actually needed.
+        if (runtimeBootstrap) {
+            await runtimeBootstrap();
+        }
+        // Convention bootstrap (portable, runtime-resolvable):
+        // If the host app provides an `ekairos.bootstrap.js` at the project root, we can load it
+        // from the step runtime using a file URL. This avoids relying on bundler-only aliases.
         if (!getRuntimeResolver()) {
-            const cfg = getEkairosConfig();
-            if (cfg?.setup)
-                cfg.setup();
+            const cwd = typeof process !== "undefined" && process.cwd ? process.cwd() : null;
+            if (cwd) {
+                const candidates = [
+                    "ekairos.bootstrap.js",
+                    "ekairos.bootstrap.cjs",
+                    "ekairos.bootstrap.mjs",
+                ];
+                for (const filename of candidates) {
+                    try {
+                        await import(pathToFileURL(join(cwd, filename)).href);
+                        break;
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }
+        // 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();
@@ -66,8 +70,11 @@ export async function resolveStoryRuntime(env) {
         throw new Error([
             "Story runtime is not configured.",
             "",
-            "Ensure your app registers a story runtime factory (global) in the step runtime,",
-            "before calling store steps.",
+            "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.d.ts

@@ -1,2 +1,2 @@
-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";
+export { Story, type StoryOptions, type StoryStreamOptions, type ShouldContinue, type StoryShouldContinueArgs, } from "./story.engine.js";
+export { story, createStory, type StoryConfig, type StoryInstance, type RegistrableStoryBuilder, } from "./story.builder.js";

package/dist/story.engine.d.ts

@@ -1,6 +1,6 @@
 import type { Tool } from "ai";
-import type { StoryEnvironment } from "./story.config";
-import type { ContextEvent, ContextIdentifier, StoredContext } from "./story.store";
+import type { StoryEnvironment } from "./story.config.js";
+import type { ContextEvent, ContextIdentifier, StoredContext } from "./story.store.js";
 export interface StoryOptions<Context = any, Env extends StoryEnvironment = StoryEnvironment> {
     onContextCreated?: (args: {
         env: Env;

package/dist/story.engine.js

@@ -1,8 +1,8 @@
-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";
+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, createReactionEvent, initializeContext, saveReactionEvent, saveTriggerEvent, updateContextContent, updateContextStatus, updateEvent, } from "./steps/store.steps.js";
 export class Story {
     constructor(opts = {}) {
         this.opts = opts;
@@ -59,7 +59,7 @@ export class Story {
         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 ctxResult = await initializeContext(params.env, params.contextIdentifier);
         const currentContext = ctxResult.context;
         const contextSelector = params.contextIdentifier?.id
             ? { id: String(params.contextIdentifier.id) }
@@ -70,12 +70,16 @@ export class Story {
             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 persistedTriggerEvent = await saveTriggerEvent(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;
+        const { reactionEventId, executionId } = await createReactionEvent({
+            env: params.env,
+            contextIdentifier: contextSelector,
+            triggerEventId,
+        });
+        // 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.
+        await writeStoryPing({ label: "story-start" });
         let reactionEvent = null;
         // Latest persisted context state for this run (we keep it in memory; store is updated via steps).
         let updatedContext = currentContext;
@@ -95,7 +99,6 @@ export class Story {
         };
         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);
@@ -105,12 +108,11 @@ export class Story {
                 // 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({
+                const { assistantEvent, toolCalls, messagesForModel } = await executeReaction({
+                    env: params.env,
+                    contextIdentifier: contextSelector,
                     model: this.getModel(updatedContext, params.env),
                     system: systemPrompt,
-                    messages: messagesForModel,
                     tools: toolsForModel,
                     eventId: reactionEventId,
                     maxSteps: maxModelSteps,
@@ -119,7 +121,7 @@ export class Story {
                 });
                 // Persist/append the assistant event for this iteration
                 if (!reactionEvent) {
-                    reactionEvent = await saveEvent(params.env, contextSelector, {
+                    reactionEvent = await saveReactionEvent(params.env, contextSelector, {
                         ...assistantEvent,
                         status: "pending",
                     });

package/dist/story.js

@@ -1,6 +1,6 @@
 export { 
 // engine
-Story, } from "./story.engine";
+Story, } from "./story.engine.js";
 export { 
 // builder
-story, createStory, } from "./story.builder";
+story, createStory, } from "./story.builder.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/story",
-  "version": "1.21.41-beta.0",
+  "version": "1.21.43-beta.0",
   "description": "Pulzar Story - Workflow-based AI Stories",
   "type": "module",
   "main": "dist/index.js",
@@ -48,7 +48,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.52",
-    "@ekairos/domain": "^1.21.41-beta.0",
+    "@ekairos/domain": "^1.21.43-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "@vercel/sandbox": "^0.0.23",