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

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

@@ -18,6 +18,7 @@ export declare function executeReaction(params: {
     eventId: string;
     maxSteps: number;
     sendStart?: boolean;
+    silent?: boolean;
 }): Promise<{
     assistantEvent: ContextEvent;
     toolCalls: any[];

package/dist/steps/reaction.steps.js

@@ -42,28 +42,30 @@ function safeErrorJson(error) {
 export async function executeReaction(params) {
     "use step";
     const { store } = await resolveStoryRuntime(params.env);
-    console.log("executeReaction: begin");
+    console.log("[ekairos/story] reaction.step executeReaction begin");
     let events;
     try {
-        console.log("executeReaction: store.getEvents begin");
+        console.log("[ekairos/story] reaction.step store.getEvents begin");
         events = await store.getEvents(params.contextIdentifier);
-        console.log("executeReaction: store.getEvents ok");
+        console.log("[ekairos/story] reaction.step store.getEvents ok");
     }
     catch (error) {
-        console.error("executeReaction: store.getEvents failed");
+        console.error("[ekairos/story] reaction.step store.getEvents failed");
         throw error;
     }
     let messagesForModel;
     try {
-        console.log("executeReaction: store.eventsToModelMessages begin");
+        console.log("[ekairos/story] reaction.step store.eventsToModelMessages begin");
         messagesForModel = (await store.eventsToModelMessages(events));
-        console.log("executeReaction: store.eventsToModelMessages ok");
+        console.log("[ekairos/story] reaction.step store.eventsToModelMessages ok");
     }
     catch (error) {
-        console.error("executeReaction: store.eventsToModelMessages failed", safeErrorJson(error));
+        console.error("[ekairos/story] reaction.step store.eventsToModelMessages failed", safeErrorJson(error));
         throw error;
     }
-    const writable = getWritable();
+    const writable = params.silent
+        ? new WritableStream({ write() { } })
+        : getWritable();
     // Match DurableAgent-style model init behavior:
     const resolvedModel = typeof params.model === "string"
         ? gateway(params.model)
@@ -78,7 +80,7 @@ export async function executeReaction(params) {
             inputSchema: jsonSchema(t.inputSchema),
         };
     }
-    console.log("executeReaction: streamText begin");
+    console.log("[ekairos/story] reaction.step streamText begin");
     const result = streamText({
         model: resolvedModel,
         system: params.system,
@@ -88,7 +90,7 @@ export async function executeReaction(params) {
         stopWhen: stepCountIs(params.maxSteps),
         experimental_transform: smoothStream({ delayInMs: 30, chunking: "word" }),
     });
-    console.log("executeReaction: streamText ok");
+    console.log("[ekairos/story] reaction.step streamText ok");
     // Ensure the underlying stream is consumed (AI SDK requirement)
     result.consumeStream();
     let resolveFinish;

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

@@ -5,7 +5,9 @@ import type { ContextEvent, ContextIdentifier, StoredContext } from "../story.st
  *
  * This is the "context init" boundary for the story engine.
  */
-export declare function initializeContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null): Promise<{
+export declare function initializeContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null, opts?: {
+    silent?: boolean;
+}): Promise<{
     context: StoredContext<C>;
     isNew: boolean;
 }>;

package/dist/steps/store.steps.js

@@ -5,7 +5,7 @@ import { resolveStoryRuntime } from "../story.config";
  *
  * This is the "context init" boundary for the story engine.
  */
-export async function initializeContext(env, contextIdentifier) {
+export async function initializeContext(env, contextIdentifier, opts) {
     "use step";
     const { store } = await resolveStoryRuntime(env);
     // Detect creation explicitly so the engine can run onContextCreated hooks.
@@ -24,17 +24,21 @@ export async function initializeContext(env, contextIdentifier) {
             result = { context: created, isNew: true };
         }
     }
-    const writable = getWritable();
-    const writer = writable.getWriter();
-    try {
-        await writer.write({
-            type: "data-context-id",
-            id: String(result.context.id),
-            data: { contextId: String(result.context.id) },
-        });
-    }
-    finally {
-        writer.releaseLock();
+    // If we're running in a non-streaming context (e.g. tests or headless usage),
+    // we skip writing stream chunks entirely.
+    if (!opts?.silent) {
+        const writable = getWritable();
+        const writer = writable.getWriter();
+        try {
+            await writer.write({
+                type: "data-context-id",
+                id: String(result.context.id),
+                data: { contextId: String(result.context.id) },
+            });
+        }
+        finally {
+            writer.releaseLock();
+        }
     }
     return result;
 }

package/dist/stores/instant.store.js

@@ -135,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: {
                 $: {

package/dist/story.config.d.ts

@@ -14,6 +14,7 @@ import type { StoryStore } from "./story.store";
 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;
 /**

package/dist/story.config.js

@@ -48,21 +48,6 @@ export async function resolveStoryRuntime(env) {
                 }
             }
         }
-        // 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)

package/dist/story.engine.d.ts

@@ -39,6 +39,14 @@ export interface StoryStreamOptions {
      * Default: true.
      */
     sendFinish?: boolean;
+    /**
+     * If true, the story loop runs silently (no UI streaming output).
+     *
+     * Persistence (contexts/events/executions) still happens normally.
+     *
+     * Default: false.
+     */
+    silent?: boolean;
 }
 /**
  * Model initializer (DurableAgent-style).

package/dist/story.engine.js

@@ -3,6 +3,14 @@ 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";
+function storyEngineInfo(message, ...args) {
+    // CRITICAL: static string log messages only. Dynamic values go in args.
+    console.log(message, ...args);
+}
+function storyEngineDebug(message, ...args) {
+    // CRITICAL: static string log messages only. Dynamic values go in args.
+    console.debug(message, ...args);
+}
 export class Story {
     constructor(opts = {}) {
         this.opts = opts;
@@ -58,9 +66,18 @@ export class Story {
         const maxModelSteps = params.options?.maxModelSteps ?? 1;
         const preventClose = params.options?.preventClose ?? false;
         const sendFinish = params.options?.sendFinish ?? true;
+        const silent = params.options?.silent ?? false;
+        storyEngineInfo("[ekairos/story] story.engine react begin");
+        storyEngineInfo("[ekairos/story] story.engine react contextIdentifier", params.contextIdentifier);
+        storyEngineInfo("[ekairos/story] story.engine react maxIterations", maxIterations);
+        storyEngineInfo("[ekairos/story] story.engine react maxModelSteps", maxModelSteps);
+        storyEngineInfo("[ekairos/story] story.engine react silent", silent);
         // 1) Ensure context exists (step)
-        const ctxResult = await initializeContext(params.env, params.contextIdentifier);
+        const ctxResult = await initializeContext(params.env, params.contextIdentifier, { silent });
         const currentContext = ctxResult.context;
+        storyEngineInfo("[ekairos/story] story.engine initializeContext ok");
+        storyEngineInfo("[ekairos/story] story.engine initializeContext contextId", currentContext.id);
+        storyEngineInfo("[ekairos/story] story.engine initializeContext isNew", ctxResult.isNew);
         const contextSelector = params.contextIdentifier?.id
             ? { id: String(params.contextIdentifier.id) }
             : params.contextIdentifier?.key
@@ -72,14 +89,21 @@ export class Story {
         // 2) Persist trigger event + create execution shell (steps)
         const persistedTriggerEvent = await saveTriggerEvent(params.env, contextSelector, triggerEvent);
         const triggerEventId = persistedTriggerEvent.id;
+        storyEngineInfo("[ekairos/story] story.engine saveTriggerEvent ok");
+        storyEngineInfo("[ekairos/story] story.engine saveTriggerEvent triggerEventId", triggerEventId);
         const { reactionEventId, executionId } = await createReactionEvent({
             env: params.env,
             contextIdentifier: contextSelector,
             triggerEventId,
         });
+        storyEngineInfo("[ekairos/story] story.engine createReactionEvent ok");
+        storyEngineInfo("[ekairos/story] story.engine createReactionEvent reactionEventId", reactionEventId);
+        storyEngineInfo("[ekairos/story] story.engine createReactionEvent executionId", executionId);
         // 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" });
+        if (!silent) {
+            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;
@@ -91,7 +115,9 @@ export class Story {
                 // noop
             }
             try {
-                await closeStoryStream({ preventClose, sendFinish });
+                if (!silent) {
+                    await closeStoryStream({ preventClose, sendFinish });
+                }
             }
             catch {
                 // noop
@@ -99,12 +125,22 @@ export class Story {
         };
         try {
             for (let iter = 0; iter < maxIterations; iter++) {
-                // Normalize/initialize context (workflow-level; may call steps if needed)
+                storyEngineInfo("[ekairos/story] story.engine === LOOP ITERATION ===", iter);
+                // Hook: Story DSL `context()` (implemented by subclasses via `initialize()`)
+                storyEngineInfo("[ekairos/story] >>> HOOK context() BEGIN", iter);
                 const nextContent = await this.initialize(updatedContext, params.env);
+                storyEngineInfo("[ekairos/story] <<< HOOK context() END", iter);
                 updatedContext = await updateContextContent(params.env, contextSelector, nextContent);
+                storyEngineInfo("[ekairos/story] story.engine updateContextContent ok");
                 await this.opts.onContextUpdated?.({ env: params.env, context: updatedContext });
+                // Hook: Story DSL `narrative()` (implemented by subclasses via `buildSystemPrompt()`)
+                storyEngineInfo("[ekairos/story] >>> HOOK narrative() BEGIN", iter);
                 const systemPrompt = await this.buildSystemPrompt(updatedContext, params.env);
+                storyEngineInfo("[ekairos/story] <<< HOOK narrative() END", iter);
+                // Hook: Story DSL `actions()` (implemented by subclasses via `buildTools()`)
+                storyEngineInfo("[ekairos/story] >>> HOOK actions() BEGIN", iter);
                 const toolsAll = await this.buildTools(updatedContext, params.env);
+                storyEngineInfo("[ekairos/story] <<< HOOK actions() END", iter);
                 // IMPORTANT: step args must be serializable.
                 // Match DurableAgent behavior: convert tool input schemas to plain JSON Schema in workflow context.
                 const toolsForModel = toolsToModelTools(toolsAll);
@@ -117,14 +153,22 @@ export class Story {
                     eventId: reactionEventId,
                     maxSteps: maxModelSteps,
                     // Only emit a `start` chunk once per story turn.
-                    sendStart: iter === 0 && reactionEvent === null,
+                    sendStart: !silent && iter === 0 && reactionEvent === null,
+                    silent,
                 });
+                storyEngineInfo("[ekairos/story] story.engine executeReaction ok");
+                storyEngineInfo("[ekairos/story] story.engine executeReaction toolCallsCount", toolCalls.length);
+                if (toolCalls.length) {
+                    storyEngineInfo("[ekairos/story] >>> TOOL_CALLS requested", toolCalls.map((tc) => tc?.toolName).filter(Boolean));
+                    storyEngineDebug("[ekairos/story] >>> TOOL_CALLS payload", toolCalls);
+                }
                 // Persist/append the assistant event for this iteration
                 if (!reactionEvent) {
                     reactionEvent = await saveReactionEvent(params.env, contextSelector, {
                         ...assistantEvent,
                         status: "pending",
                     });
+                    storyEngineInfo("[ekairos/story] story.engine saveReactionEvent ok");
                 }
                 else {
                     reactionEvent = await updateEvent(params.env, reactionEvent.id, {
@@ -137,11 +181,14 @@ export class Story {
                         },
                         status: "pending",
                     });
+                    storyEngineInfo("[ekairos/story] story.engine updateEvent appendAssistantParts ok");
                 }
                 this.opts.onEventCreated?.(assistantEvent);
                 // Done: no tool calls requested by the model
                 if (!toolCalls.length) {
+                    storyEngineInfo("[ekairos/story] >>> HOOK onEnd() BEGIN", iter);
                     const endResult = await this.callOnEnd(assistantEvent);
+                    storyEngineInfo("[ekairos/story] <<< HOOK onEnd() END", iter, endResult);
                     if (endResult) {
                         // Mark reaction event completed
                         await updateEvent(params.env, reactionEventId, {
@@ -150,7 +197,9 @@ export class Story {
                         });
                         await updateContextStatus(params.env, contextSelector, "open");
                         await completeExecution(params.env, contextSelector, executionId, "completed");
-                        await closeStoryStream({ preventClose, sendFinish });
+                        if (!silent) {
+                            await closeStoryStream({ preventClose, sendFinish });
+                        }
                         return {
                             contextId: currentContext.id,
                             context: updatedContext,
@@ -161,12 +210,13 @@ export class Story {
                     }
                 }
                 // Execute tool calls (workflow context; tool implementations decide step vs workflow)
-                if (toolCalls.length) {
+                if (!silent && 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") {
+                        storyEngineInfo("[ekairos/story] story.engine toolExecution missingTool", tc?.toolName);
                         return {
                             tc,
                             success: false,
@@ -174,6 +224,8 @@ export class Story {
                             errorText: `Tool "${tc.toolName}" not found or has no execute().`,
                         };
                     }
+                    storyEngineInfo("[ekairos/story] >>> TOOL_EXEC BEGIN", tc?.toolName, tc?.toolCallId);
+                    storyEngineDebug("[ekairos/story] >>> TOOL_EXEC input", tc?.toolName, tc?.toolCallId, tc?.args);
                     try {
                         const output = await toolDef.execute(tc.args, {
                             toolCallId: tc.toolCallId,
@@ -183,9 +235,13 @@ export class Story {
                             triggerEventId,
                             contextId: currentContext.id,
                         });
+                        storyEngineInfo("[ekairos/story] <<< TOOL_EXEC OK", tc?.toolName, tc?.toolCallId);
+                        storyEngineDebug("[ekairos/story] <<< TOOL_EXEC output", tc?.toolName, tc?.toolCallId, output);
                         return { tc, success: true, output };
                     }
                     catch (e) {
+                        storyEngineInfo("[ekairos/story] <<< TOOL_EXEC FAILED", tc?.toolName, tc?.toolCallId);
+                        storyEngineDebug("[ekairos/story] <<< TOOL_EXEC error", tc?.toolName, tc?.toolCallId, e instanceof Error ? e.message : String(e));
                         return {
                             tc,
                             success: false,
@@ -194,14 +250,21 @@ export class Story {
                         };
                     }
                 }));
+                storyEngineInfo("[ekairos/story] story.engine toolExecution resultsCount", executionResults.length);
                 // 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 }),
-                });
+                if (!silent) {
+                    await writeToolOutputs({
+                        results: executionResults.map((r) => r.success
+                            ? { toolCallId: r.tc.toolCallId, success: true, output: r.output }
+                            : {
+                                toolCallId: r.tc.toolCallId,
+                                success: false,
+                                errorText: r.errorText,
+                            }),
+                    });
+                }
                 // Clear action status once tool execution results have been emitted.
-                if (toolCalls.length) {
+                if (!silent && toolCalls.length) {
                     await writeContextSubstate({ key: null, transient: true });
                 }
                 // Merge tool results into persisted parts (so next LLM call can see them)
@@ -219,6 +282,7 @@ export class Story {
                         content: { parts },
                         status: "pending",
                     });
+                    storyEngineInfo("[ekairos/story] story.engine updateEvent mergeToolResults ok");
                 }
                 // Callback for observability/integration
                 for (const r of executionResults) {
@@ -234,6 +298,7 @@ export class Story {
                 // 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.
+                storyEngineInfo("[ekairos/story] >>> HOOK shouldContinue() BEGIN", iter);
                 const continueLoop = await this.shouldContinue({
                     env: params.env,
                     context: updatedContext,
@@ -242,6 +307,7 @@ export class Story {
                     toolCalls,
                     toolExecutionResults: executionResults,
                 });
+                storyEngineInfo("[ekairos/story] <<< HOOK shouldContinue() END", iter, continueLoop);
                 if (continueLoop === false) {
                     await updateEvent(params.env, reactionEventId, {
                         ...reactionEvent,
@@ -249,7 +315,9 @@ export class Story {
                     });
                     await updateContextStatus(params.env, contextSelector, "open");
                     await completeExecution(params.env, contextSelector, executionId, "completed");
-                    await closeStoryStream({ preventClose, sendFinish });
+                    if (!silent) {
+                        await closeStoryStream({ preventClose, sendFinish });
+                    }
                     return {
                         contextId: currentContext.id,
                         context: updatedContext,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/story",
-  "version": "1.21.43-beta.0",
+  "version": "1.21.52-beta.0",
   "description": "Pulzar Story - Workflow-based AI Stories",
   "type": "module",
   "main": "dist/index.js",
@@ -21,6 +21,7 @@
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
+      "require": "./dist/index.js",
       "default": "./dist/index.js"
     },
     "./runtime": {
@@ -39,6 +40,19 @@
       "default": "./dist/stores/instant.store.js"
     }
   },
+  "typesVersions": {
+    "*": {
+      "runtime": [
+        "dist/runtime.d.ts"
+      ],
+      "next": [
+        "dist/next.d.ts"
+      ],
+      "instant": [
+        "dist/stores/instant.store.d.ts"
+      ]
+    }
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsc -p tsconfig.json --watch",
@@ -48,7 +62,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.52",
-    "@ekairos/domain": "^1.21.43-beta.0",
+    "@ekairos/domain": "^1.21.52-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "@vercel/sandbox": "^0.0.23",