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

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();
@@ -126,7 +135,9 @@ export class InstantStore {
     async getEvents(contextIdentifier) {
         const contextWhere = contextIdentifier.id
             ? { context: contextIdentifier.id }
-            : { context: lookup("key", contextIdentifier.key) };
+            : // IMPORTANT: `lookup("key", ...)` is valid in transactions, but not in query filters for links.
+                // Use nested where on the linked context's indexed `key` instead.
+                { "context.key": contextIdentifier.key };
         const res = await this.db.query({
             context_events: {
                 $: {
@@ -172,14 +183,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
  *
@@ -15,9 +14,9 @@ import type { EkairosConfig } from "./ekairos.config";
 export type StoryEnvironment = Record<string, unknown>;
 export type StoryRuntime = {
     store: StoryStore;
+    db: any;
 };
 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,30 @@ 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
+                    }
+                }
+            }
         }
         // If bootstrap succeeded, proceed.
         const resolver = getRuntimeResolver();
@@ -66,8 +55,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";