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

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;
@@ -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

@@ -1,8 +1,16 @@
-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";
+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 ensureContextAndEmitContextId(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
@@ -70,12 +87,23 @@ 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;
+        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.
+        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;
@@ -87,7 +115,9 @@ export class Story {
                 // noop
             }
             try {
-                await closeStoryStream({ preventClose, sendFinish });
+                if (!silent) {
+                    await closeStoryStream({ preventClose, sendFinish });
+                }
             }
             catch {
                 // noop
@@ -95,34 +125,50 @@ 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)
+                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);
-                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,
                     // 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 saveEvent(params.env, contextSelector, {
+                    reactionEvent = await saveReactionEvent(params.env, contextSelector, {
                         ...assistantEvent,
                         status: "pending",
                     });
+                    storyEngineInfo("[ekairos/story] story.engine saveReactionEvent ok");
                 }
                 else {
                     reactionEvent = await updateEvent(params.env, reactionEvent.id, {
@@ -135,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, {
@@ -148,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,
@@ -159,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,
@@ -172,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,
@@ -181,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,
@@ -192,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)
@@ -217,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) {
@@ -232,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,
@@ -240,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,
@@ -247,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/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.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.41-beta.0",
+    "@ekairos/domain": "^1.21.52-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "@vercel/sandbox": "^0.0.23",