@ekairos/story 1.21.57-beta.0 → 1.21.59-beta.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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 type { WireDate, StoryMirrorContext, StoryMirrorExecution, StoryMirrorWrite, StoryMirrorRequest, } from "./mirror.js";
 export { registerStory, getStory, getStoryFactory, hasStory, listStories, type StoryKey, } from "./story.registry.js";
 export { storyDomain } from "./schema.js";
 export { didToolExecute } from "./story.toolcalls.js";

package/dist/mirror.d.ts

@@ -0,0 +1,41 @@
+import type { ContextEvent, StoredContext } from "./story.store";
+/**
+ * Wire-safe (JSON) mirror types shared by:
+ * - the workflow sender (`@ekairos/story` steps)
+ * - the ekairos-core receiver (`/api/story`)
+ *
+ * Note: `StoredContext` contains Date objects, but over HTTP we send ISO strings.
+ */
+export type WireDate = string;
+export type StoryMirrorContext = Omit<StoredContext<unknown>, "createdAt" | "updatedAt"> & {
+    createdAt: WireDate;
+    updatedAt?: WireDate;
+};
+export type StoryMirrorExecution = Record<string, unknown> & {
+    createdAt?: WireDate;
+    updatedAt?: WireDate;
+};
+export type StoryMirrorWrite = {
+    type: "context.upsert";
+    context: StoryMirrorContext;
+} | {
+    type: "event.upsert";
+    contextId: string;
+    event: ContextEvent;
+} | {
+    type: "event.update";
+    eventId: string;
+    event: ContextEvent;
+} | {
+    type: "execution.upsert";
+    contextId: string;
+    executionId: string;
+    execution: StoryMirrorExecution;
+    triggerEventId: string;
+    reactionEventId: string;
+    setCurrentExecution?: boolean;
+};
+export type StoryMirrorRequest = {
+    orgId: string;
+    writes: StoryMirrorWrite[];
+};

package/dist/mirror.js

@@ -0,0 +1 @@
+export {};

package/dist/steps/mirror.steps.d.ts

@@ -0,0 +1,6 @@
+import type { StoryEnvironment } from "../story.config";
+import type { StoryMirrorWrite } from "../mirror";
+export declare function mirrorStoryWrites(params: {
+    env: StoryEnvironment;
+    writes: StoryMirrorWrite[];
+}): Promise<void>;

package/dist/steps/mirror.steps.js

@@ -0,0 +1,44 @@
+function requireOrgId(env) {
+    const orgId = env?.orgId;
+    if (typeof orgId !== "string" || !orgId) {
+        throw new Error("[story/mirror] Missing env.orgId");
+    }
+    return orgId;
+}
+function requireBaseUrl() {
+    const baseUrl = process.env.EKAIROS_CORE_BASE_URL ||
+        process.env.EKAIROS_MIRROR_BASE_URL ||
+        process.env.EKAIROS_BASE_URL;
+    if (!baseUrl) {
+        throw new Error("[story/mirror] Missing EKAIROS_CORE_BASE_URL (or EKAIROS_MIRROR_BASE_URL)");
+    }
+    return baseUrl.replace(/\/$/, "");
+}
+function requireToken() {
+    const token = process.env.EKAIROS_STORY_MIRROR_TOKEN;
+    if (!token) {
+        throw new Error("[story/mirror] Missing EKAIROS_STORY_MIRROR_TOKEN");
+    }
+    return token;
+}
+export async function mirrorStoryWrites(params) {
+    "use step";
+    if (!params.writes?.length)
+        return;
+    const orgId = requireOrgId(params.env);
+    const baseUrl = requireBaseUrl();
+    const token = requireToken();
+    const body = { orgId, writes: params.writes };
+    const res = await fetch(`${baseUrl}/api/story`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new Error(`[story/mirror] ekairos-core write failed (${res.status}): ${text}`);
+    }
+}

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

@@ -1,4 +1,4 @@
-import type { ModelMessage } from "ai";
+import type { ModelMessage, UIMessageChunk } from "ai";
 import type { StoryEnvironment } from "../story.config";
 import type { ContextEvent, ContextIdentifier } from "../story.store";
 import type { SerializableToolForModel } from "../tools-to-model-tools";
@@ -19,6 +19,7 @@ export declare function executeReaction(params: {
     maxSteps: number;
     sendStart?: boolean;
     silent?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<{
     assistantEvent: ContextEvent;
     toolCalls: any[];

package/dist/steps/reaction.steps.js

@@ -60,9 +60,9 @@ export async function executeReaction(params) {
         console.error("[ekairos/story] reaction.step store.eventsToModelMessages failed", safeErrorJson(error));
         throw error;
     }
-    const writable = params.silent
+    const writable = params.silent || !params.writable
         ? new WritableStream({ write() { } })
-        : (await import("workflow")).getWritable();
+        : params.writable;
     const { jsonSchema, gateway, smoothStream, stepCountIs, streamText } = await import("ai");
     const { extractToolCallsFromParts } = await import("../story.toolcalls");
     // Match DurableAgent-style model init behavior:

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

@@ -1,3 +1,4 @@
+import type { UIMessageChunk } from "ai";
 import type { StoryEnvironment } from "../story.config";
 import type { ContextEvent, ContextIdentifier, StoredContext } from "../story.store";
 /**
@@ -7,6 +8,7 @@ import type { ContextEvent, ContextIdentifier, StoredContext } from "../story.st
  */
 export declare function initializeContext<C>(env: StoryEnvironment, contextIdentifier: ContextIdentifier | null, opts?: {
     silent?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<{
     context: StoredContext<C>;
     isNew: boolean;

package/dist/steps/store.steps.js

@@ -7,6 +7,8 @@ export async function initializeContext(env, contextIdentifier, opts) {
     "use step";
     const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const { store } = await resolveStoryRuntime(env);
+    console.log("[ekairos/story] story.engine react begin");
+    console.log("[ekairos/story] story.engine react contextIdentifier", contextIdentifier);
     // Detect creation explicitly so the engine can run onContextCreated hooks.
     let result;
     if (!contextIdentifier) {
@@ -23,12 +25,13 @@ export async function initializeContext(env, contextIdentifier, opts) {
             result = { context: created, isNew: true };
         }
     }
+    console.log("[ekairos/story] story.engine initializeContext ok");
+    console.log("[ekairos/story] story.engine initializeContext contextId", result.context.id);
+    console.log("[ekairos/story] story.engine initializeContext isNew", result.isNew);
     // 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 { getWritable } = await import("workflow");
-        const writable = getWritable();
-        const writer = writable.getWriter();
+    if (!opts?.silent && opts?.writable) {
+        const writer = opts.writable.getWriter();
         try {
             await writer.write({
                 type: "data-context-id",
@@ -58,7 +61,10 @@ export async function saveTriggerEvent(env, contextIdentifier, event) {
     "use step";
     const { resolveStoryRuntime } = await import("@ekairos/story/runtime");
     const { store } = await resolveStoryRuntime(env);
-    return await store.saveEvent(contextIdentifier, event);
+    const saved = await store.saveEvent(contextIdentifier, event);
+    console.log("[ekairos/story] story.engine saveTriggerEvent ok");
+    console.log("[ekairos/story] story.engine saveTriggerEvent triggerEventId", saved.id);
+    return saved;
 }
 export async function saveReactionEvent(env, contextIdentifier, event) {
     "use step";
@@ -89,6 +95,9 @@ export async function createReactionEvent(params) {
         : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
     await store.updateContextStatus(params.contextIdentifier, "streaming");
     const execution = await store.createExecution(params.contextIdentifier, params.triggerEventId, reactionEventId);
+    console.log("[ekairos/story] story.engine createReactionEvent ok");
+    console.log("[ekairos/story] story.engine createReactionEvent reactionEventId", reactionEventId);
+    console.log("[ekairos/story] story.engine createReactionEvent executionId", execution.id);
     return { reactionEventId, executionId: execution.id };
 }
 export async function completeExecution(env, contextIdentifier, executionId, status) {

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

@@ -1,8 +1,4 @@
-export declare function writeStoryLog(params: {
-    level?: "info" | "debug" | "warn" | "error";
-    message: string;
-    args?: Array<string | number | boolean | null>;
-}): Promise<void>;
+import type { UIMessageChunk } from "ai";
 export declare function writeContextSubstate(params: {
     /**
      * Ephemeral substate key for the UI (story engine internal state).
@@ -12,9 +8,11 @@ export declare function writeContextSubstate(params: {
      */
     key: string | null;
     transient?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;
 export declare function writeContextIdChunk(params: {
     contextId: string;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;
 export declare function writeStoryPing(params: {
     /**
@@ -22,6 +20,7 @@ export declare function writeStoryPing(params: {
      * This is intentionally generic so clients can ignore it safely.
      */
     label?: string;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;
 export declare function writeToolOutputs(params: {
     results: Array<{
@@ -33,8 +32,10 @@ export declare function writeToolOutputs(params: {
         success: false;
         errorText: string;
     }>;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;
 export declare function closeStoryStream(params: {
     preventClose?: boolean;
     sendFinish?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;

package/dist/steps/stream.steps.js

@@ -1,19 +1,8 @@
-export async function writeStoryLog(params) {
-    "use step";
-    const level = params.level ?? "info";
-    const fn = level === "debug"
-        ? console.debug
-        : level === "warn"
-            ? console.warn
-            : level === "error"
-                ? console.error
-                : console.log;
-    fn(params.message, ...(params.args ?? []));
-}
 export async function writeContextSubstate(params) {
     "use step";
-    const { getWritable } = await import("workflow");
-    const writable = getWritable();
+    const writable = params.writable;
+    if (!writable)
+        return;
     const writer = writable.getWriter();
     try {
         await writer.write({
@@ -28,8 +17,9 @@ export async function writeContextSubstate(params) {
 }
 export async function writeContextIdChunk(params) {
     "use step";
-    const { getWritable } = await import("workflow");
-    const writable = getWritable();
+    const writable = params.writable;
+    if (!writable)
+        return;
     const writer = writable.getWriter();
     try {
         await writer.write({
@@ -44,8 +34,9 @@ export async function writeContextIdChunk(params) {
 }
 export async function writeStoryPing(params) {
     "use step";
-    const { getWritable } = await import("workflow");
-    const writable = getWritable();
+    const writable = params.writable;
+    if (!writable)
+        return;
     const writer = writable.getWriter();
     try {
         await writer.write({
@@ -60,8 +51,9 @@ export async function writeStoryPing(params) {
 }
 export async function writeToolOutputs(params) {
     "use step";
-    const { getWritable } = await import("workflow");
-    const writable = getWritable();
+    const writable = params.writable;
+    if (!writable)
+        return;
     const writer = writable.getWriter();
     try {
         for (const r of params.results) {
@@ -89,8 +81,9 @@ export async function closeStoryStream(params) {
     "use step";
     const sendFinish = params.sendFinish ?? true;
     const preventClose = params.preventClose ?? false;
-    const { getWritable } = await import("workflow");
-    const writable = getWritable();
+    const writable = params.writable;
+    if (!writable)
+        return;
     if (sendFinish) {
         const writer = writable.getWriter();
         try {

package/dist/story.builder.d.ts

@@ -1,6 +1,5 @@
-import type { Tool } from "ai";
 import type { StoryEnvironment } from "./story.config.js";
-import { Story, type StoryModelInit, type StoryOptions, type ShouldContinue, type StoryShouldContinueArgs, type StoryReactParams } from "./story.engine.js";
+import { Story, type StoryModelInit, type StoryOptions, type StoryTool, 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> {
@@ -27,11 +26,11 @@ export interface StoryConfig<Context, Env extends StoryEnvironment = StoryEnviro
     /**
      * Actions available to the model (aka "tools" in AI SDK terminology).
      */
-    actions: (context: StoredContext<Context>, env: Env) => Promise<Record<string, Tool>> | Record<string, Tool>;
+    actions: (context: StoredContext<Context>, env: Env) => Promise<Record<string, StoryTool>> | Record<string, StoryTool>;
     /**
      * @deprecated Use `actions()` instead.
      */
-    tools?: (context: StoredContext<Context>, env: Env) => Promise<Record<string, Tool>> | Record<string, Tool>;
+    tools?: (context: StoredContext<Context>, env: Env) => Promise<Record<string, StoryTool>> | Record<string, StoryTool>;
     /**
      * Model configuration (DurableAgent-style).
      *
@@ -59,7 +58,7 @@ export declare function story<Context, Env extends StoryEnvironment = StoryEnvir
 type AnyContextInitializer<Env extends StoryEnvironment> = (context: StoredContext<any>, env: Env) => Promise<any> | any;
 type InferContextFromInitializer<I extends AnyContextInitializer<any>> = Awaited<ReturnType<I>>;
 type BuilderSystemPrompt<Context, Env extends StoryEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<string> | string;
-type BuilderTools<Context, Env extends StoryEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<Record<string, Tool>> | Record<string, Tool>;
+type BuilderTools<Context, Env extends StoryEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<Record<string, StoryTool>> | Record<string, StoryTool>;
 type BuilderExpandEvents<Context, Env extends StoryEnvironment> = (events: ContextEvent[], context: StoredContext<Context>, env: Env) => Promise<ContextEvent[]> | ContextEvent[];
 type BuilderShouldContinue<Context, Env extends StoryEnvironment> = (args: StoryShouldContinueArgs<Context, Env>) => Promise<ShouldContinue> | ShouldContinue;
 type BuilderModel<Context, Env extends StoryEnvironment> = StoryModelInit | ((context: StoredContext<Context>, env: Env) => StoryModelInit);

package/dist/story.engine.d.ts

@@ -1,4 +1,4 @@
-import type { Tool } from "ai";
+import type { Tool, UIMessageChunk } from "ai";
 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> {
@@ -47,6 +47,16 @@ export interface StoryStreamOptions {
      * Default: false.
      */
     silent?: boolean;
+    /**
+     * Optional workflow writable stream to emit UIMessageChunks into.
+     *
+     * When omitted, the story will run without emitting stream chunks (equivalent to "headless"
+     * execution for output purposes).
+     *
+     * IMPORTANT: We intentionally avoid calling `getWritable()` inside steps; callers can pass a
+     * writable from a `"use workflow"` function if they need streaming.
+     */
+    writable?: WritableStream<UIMessageChunk>;
 }
 /**
  * Model initializer (DurableAgent-style).
@@ -65,6 +75,58 @@ export type StoryReactParams<Env extends StoryEnvironment = StoryEnvironment> =
     context?: ContextIdentifier | null;
     options?: StoryStreamOptions;
 };
+/**
+ * Payload expected to resume an auto=false tool execution.
+ *
+ * This must be serializable because it crosses the workflow hook boundary.
+ *
+ * See: https://useworkflow.dev/docs/foundations/hooks
+ */
+export type StoryToolApprovalPayload = {
+    approved: true;
+    comment?: string;
+    args?: Record<string, unknown>;
+} | {
+    approved: false;
+    comment?: string;
+};
+/**
+ * Deterministic hook token for approving an `auto: false` tool call.
+ *
+ * External systems can resume the hook with:
+ * `resumeHook(toolApprovalHookToken({ executionId, toolCallId }), { approved: true })`
+ */
+export declare function toolApprovalHookToken(params: {
+    executionId: string;
+    toolCallId: string;
+}): string;
+/**
+ * Deterministic webhook token for approving an `auto: false` tool call.
+ *
+ * When using Workflow DevKit, the webhook is available at:
+ * `/.well-known/workflow/v1/webhook/:token`
+ *
+ * See: https://useworkflow.dev/docs/foundations/hooks
+ */
+export declare function toolApprovalWebhookToken(params: {
+    executionId: string;
+    toolCallId: string;
+}): string;
+/**
+ * Story-level tool type.
+ *
+ * Allows stories to attach metadata to actions/tools (e.g. `{ auto: false }`)
+ * while remaining compatible with the AI SDK `Tool` runtime shape.
+ *
+ * Default behavior when omitted: `auto === true`.
+ */
+export type StoryTool = Tool & {
+    /**
+     * If `false`, this action is not intended for automatic execution by the engine.
+     * (Validation/enforcement can be added by callers; default is `true`.)
+     */
+    auto?: boolean;
+};
 /**
  * ## Story loop continuation signal
  *
@@ -103,7 +165,7 @@ export declare abstract class Story<Context, Env extends StoryEnvironment = Stor
     constructor(opts?: StoryOptions<Context, Env>);
     protected abstract initialize(context: StoredContext<Context>, env: Env): Promise<Context> | Context;
     protected abstract buildSystemPrompt(context: StoredContext<Context>, env: Env): Promise<string> | string;
-    protected abstract buildTools(context: StoredContext<Context>, env: Env): Promise<Record<string, Tool>> | Record<string, Tool>;
+    protected abstract buildTools(context: StoredContext<Context>, env: Env): Promise<Record<string, StoryTool>> | Record<string, StoryTool>;
     /**
      * First-class event expansion stage (runs on every iteration of the durable loop).
      *

package/dist/story.engine.js

@@ -1,49 +1,27 @@
 import { applyToolExecutionResultToParts } from "./story.toolcalls.js";
 import { executeReaction } from "./steps/reaction.steps.js";
 import { toolsToModelTools } from "./tools-to-model-tools.js";
-import { closeStoryStream, writeContextSubstate, writeStoryLog, writeStoryPing, writeToolOutputs, } from "./steps/stream.steps.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 safeLogArg(value) {
-    if (value === null)
-        return null;
-    if (value === undefined)
-        return null;
-    const t = typeof value;
-    if (t === "string" || t === "number" || t === "boolean")
-        return value;
-    if (t === "bigint")
-        return String(value);
-    try {
-        const seen = new WeakSet();
-        return JSON.stringify(value, (_k, v) => {
-            if (typeof v === "bigint")
-                return String(v);
-            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;
-        }, 2);
-    }
-    catch {
-        try {
-            return String(value);
-        }
-        catch {
-            return "[unserializable]";
-        }
-    }
-}
-async function storyEngineInfo(message, ...args) {
-    // CRITICAL: static string log messages only. Dynamic values go in args.
-    await writeStoryLog({ level: "info", message, args: args.map(safeLogArg) });
+/**
+ * Deterministic hook token for approving an `auto: false` tool call.
+ *
+ * External systems can resume the hook with:
+ * `resumeHook(toolApprovalHookToken({ executionId, toolCallId }), { approved: true })`
+ */
+export function toolApprovalHookToken(params) {
+    return `ekairos_story:tool-approval:${params.executionId}:${params.toolCallId}`;
 }
-async function storyEngineDebug(message, ...args) {
-    // CRITICAL: static string log messages only. Dynamic values go in args.
-    await writeStoryLog({ level: "debug", message, args: args.map(safeLogArg) });
+/**
+ * Deterministic webhook token for approving an `auto: false` tool call.
+ *
+ * When using Workflow DevKit, the webhook is available at:
+ * `/.well-known/workflow/v1/webhook/:token`
+ *
+ * See: https://useworkflow.dev/docs/foundations/hooks
+ */
+export function toolApprovalWebhookToken(params) {
+    return `ekairos_story:tool-approval-webhook:${params.executionId}:${params.toolCallId}`;
 }
 export class Story {
     constructor(opts = {}) {
@@ -101,17 +79,10 @@ export class Story {
         const preventClose = params.options?.preventClose ?? false;
         const sendFinish = params.options?.sendFinish ?? true;
         const silent = params.options?.silent ?? false;
-        await storyEngineInfo("[ekairos/story] story.engine react begin");
-        await storyEngineInfo("[ekairos/story] story.engine react contextIdentifier", params.contextIdentifier);
-        await storyEngineInfo("[ekairos/story] story.engine react maxIterations", maxIterations);
-        await storyEngineInfo("[ekairos/story] story.engine react maxModelSteps", maxModelSteps);
-        await storyEngineInfo("[ekairos/story] story.engine react silent", silent);
+        const writable = params.options?.writable;
         // 1) Ensure context exists (step)
-        const ctxResult = await initializeContext(params.env, params.contextIdentifier, { silent });
+        const ctxResult = await initializeContext(params.env, params.contextIdentifier, { silent, writable });
         const currentContext = ctxResult.context;
-        await storyEngineInfo("[ekairos/story] story.engine initializeContext ok");
-        await storyEngineInfo("[ekairos/story] story.engine initializeContext contextId", currentContext.id);
-        await storyEngineInfo("[ekairos/story] story.engine initializeContext isNew", ctxResult.isNew);
         const contextSelector = params.contextIdentifier?.id
             ? { id: String(params.contextIdentifier.id) }
             : params.contextIdentifier?.key
@@ -123,20 +94,15 @@ export class Story {
         // 2) Persist trigger event + create execution shell (steps)
         const persistedTriggerEvent = await saveTriggerEvent(params.env, contextSelector, triggerEvent);
         const triggerEventId = persistedTriggerEvent.id;
-        await storyEngineInfo("[ekairos/story] story.engine saveTriggerEvent ok");
-        await storyEngineInfo("[ekairos/story] story.engine saveTriggerEvent triggerEventId", triggerEventId);
         const { reactionEventId, executionId } = await createReactionEvent({
             env: params.env,
             contextIdentifier: contextSelector,
             triggerEventId,
         });
-        await storyEngineInfo("[ekairos/story] story.engine createReactionEvent ok");
-        await storyEngineInfo("[ekairos/story] story.engine createReactionEvent reactionEventId", reactionEventId);
-        await 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" });
+            await writeStoryPing({ label: "story-start", writable });
         }
         let reactionEvent = null;
         // Latest persisted context state for this run (we keep it in memory; store is updated via steps).
@@ -150,7 +116,7 @@ export class Story {
             }
             try {
                 if (!silent) {
-                    await closeStoryStream({ preventClose, sendFinish });
+                    await closeStoryStream({ preventClose, sendFinish, writable });
                 }
             }
             catch {
@@ -159,22 +125,14 @@ export class Story {
         };
         try {
             for (let iter = 0; iter < maxIterations; iter++) {
-                await storyEngineInfo("[ekairos/story] story.engine === LOOP ITERATION ===", iter);
                 // Hook: Story DSL `context()` (implemented by subclasses via `initialize()`)
-                await storyEngineInfo("[ekairos/story] >>> HOOK context() BEGIN", iter);
                 const nextContent = await this.initialize(updatedContext, params.env);
-                await storyEngineInfo("[ekairos/story] <<< HOOK context() END", iter);
                 updatedContext = await updateContextContent(params.env, contextSelector, nextContent);
-                await 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()`)
-                await storyEngineInfo("[ekairos/story] >>> HOOK narrative() BEGIN", iter);
                 const systemPrompt = await this.buildSystemPrompt(updatedContext, params.env);
-                await storyEngineInfo("[ekairos/story] <<< HOOK narrative() END", iter);
                 // Hook: Story DSL `actions()` (implemented by subclasses via `buildTools()`)
-                await storyEngineInfo("[ekairos/story] >>> HOOK actions() BEGIN", iter);
                 const toolsAll = await this.buildTools(updatedContext, params.env);
-                await 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);
@@ -189,20 +147,14 @@ export class Story {
                     // Only emit a `start` chunk once per story turn.
                     sendStart: !silent && iter === 0 && reactionEvent === null,
                     silent,
+                    writable,
                 });
-                await storyEngineInfo("[ekairos/story] story.engine executeReaction ok");
-                await storyEngineInfo("[ekairos/story] story.engine executeReaction toolCallsCount", toolCalls.length);
-                if (toolCalls.length) {
-                    await storyEngineInfo("[ekairos/story] >>> TOOL_CALLS requested", toolCalls.map((tc) => tc?.toolName).filter(Boolean));
-                    await 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",
                     });
-                    await storyEngineInfo("[ekairos/story] story.engine saveReactionEvent ok");
                 }
                 else {
                     reactionEvent = await updateEvent(params.env, reactionEvent.id, {
@@ -215,14 +167,11 @@ export class Story {
                         },
                         status: "pending",
                     });
-                    await storyEngineInfo("[ekairos/story] story.engine updateEvent appendAssistantParts ok");
                 }
                 this.opts.onEventCreated?.(assistantEvent);
                 // Done: no tool calls requested by the model
                 if (!toolCalls.length) {
-                    await storyEngineInfo("[ekairos/story] >>> HOOK onEnd() BEGIN", iter);
                     const endResult = await this.callOnEnd(assistantEvent);
-                    await storyEngineInfo("[ekairos/story] <<< HOOK onEnd() END", iter, endResult);
                     if (endResult) {
                         // Mark reaction event completed
                         await updateEvent(params.env, reactionEventId, {
@@ -232,7 +181,7 @@ export class Story {
                         await updateContextStatus(params.env, contextSelector, "open");
                         await completeExecution(params.env, contextSelector, executionId, "completed");
                         if (!silent) {
-                            await closeStoryStream({ preventClose, sendFinish });
+                            await closeStoryStream({ preventClose, sendFinish, writable });
                         }
                         return {
                             contextId: currentContext.id,
@@ -245,12 +194,11 @@ export class Story {
                 }
                 // Execute tool calls (workflow context; tool implementations decide step vs workflow)
                 if (!silent && toolCalls.length) {
-                    await writeContextSubstate({ key: "actions", transient: true });
+                    await writeContextSubstate({ key: "actions", transient: true, writable });
                 }
                 const executionResults = await Promise.all(toolCalls.map(async (tc) => {
                     const toolDef = toolsAll[tc.toolName];
                     if (!toolDef || typeof toolDef.execute !== "function") {
-                        await storyEngineInfo("[ekairos/story] story.engine toolExecution missingTool", tc?.toolName);
                         return {
                             tc,
                             success: false,
@@ -258,10 +206,42 @@ export class Story {
                             errorText: `Tool "${tc.toolName}" not found or has no execute().`,
                         };
                     }
-                    await storyEngineInfo("[ekairos/story] >>> TOOL_EXEC BEGIN", tc?.toolName, tc?.toolCallId);
-                    await storyEngineDebug("[ekairos/story] >>> TOOL_EXEC input", tc?.toolName, tc?.toolCallId, tc?.args);
                     try {
-                        const output = await toolDef.execute(tc.args, {
+                        let toolArgs = tc.args;
+                        if (toolDef?.auto === false) {
+                            const { createHook, createWebhook } = await import("workflow");
+                            const hookToken = toolApprovalHookToken({
+                                executionId,
+                                toolCallId: String(tc.toolCallId),
+                            });
+                            const webhookToken = toolApprovalWebhookToken({
+                                executionId,
+                                toolCallId: String(tc.toolCallId),
+                            });
+                            const hook = createHook({ token: hookToken });
+                            const webhook = createWebhook({ token: webhookToken });
+                            const approvalOrRequest = await Promise.race([
+                                hook.then((approval) => ({ source: "hook", approval })),
+                                webhook.then((request) => ({ source: "webhook", request })),
+                            ]);
+                            const approval = approvalOrRequest.source === "hook"
+                                ? approvalOrRequest.approval
+                                : await approvalOrRequest.request.json().catch(() => null);
+                            if (!approval || approval.approved !== true) {
+                                return {
+                                    tc,
+                                    success: false,
+                                    output: null,
+                                    errorText: approval && "comment" in approval && approval.comment
+                                        ? `Tool execution not approved: ${approval.comment}`
+                                        : "Tool execution not approved",
+                                };
+                            }
+                            if ("args" in approval && approval.args !== undefined) {
+                                toolArgs = approval.args;
+                            }
+                        }
+                        const output = await toolDef.execute(toolArgs, {
                             toolCallId: tc.toolCallId,
                             messages: messagesForModel,
                             eventId: reactionEventId,
@@ -269,13 +249,9 @@ export class Story {
                             triggerEventId,
                             contextId: currentContext.id,
                         });
-                        await storyEngineInfo("[ekairos/story] <<< TOOL_EXEC OK", tc?.toolName, tc?.toolCallId);
-                        await storyEngineDebug("[ekairos/story] <<< TOOL_EXEC output", tc?.toolName, tc?.toolCallId, output);
                         return { tc, success: true, output };
                     }
                     catch (e) {
-                        await storyEngineInfo("[ekairos/story] <<< TOOL_EXEC FAILED", tc?.toolName, tc?.toolCallId);
-                        await storyEngineDebug("[ekairos/story] <<< TOOL_EXEC error", tc?.toolName, tc?.toolCallId, e instanceof Error ? e.message : String(e));
                         return {
                             tc,
                             success: false,
@@ -284,7 +260,6 @@ export class Story {
                         };
                     }
                 }));
-                await storyEngineInfo("[ekairos/story] story.engine toolExecution resultsCount", executionResults.length);
                 // Emit tool outputs to the workflow stream (step)
                 if (!silent) {
                     await writeToolOutputs({
@@ -295,11 +270,12 @@ export class Story {
                                 success: false,
                                 errorText: r.errorText,
                             }),
+                        writable,
                     });
                 }
                 // Clear action status once tool execution results have been emitted.
                 if (!silent && toolCalls.length) {
-                    await writeContextSubstate({ key: null, transient: true });
+                    await writeContextSubstate({ key: null, transient: true, writable });
                 }
                 // Merge tool results into persisted parts (so next LLM call can see them)
                 if (reactionEvent) {
@@ -316,7 +292,6 @@ export class Story {
                         content: { parts },
                         status: "pending",
                     });
-                    await storyEngineInfo("[ekairos/story] story.engine updateEvent mergeToolResults ok");
                 }
                 // Callback for observability/integration
                 for (const r of executionResults) {
@@ -332,7 +307,6 @@ 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.
-                await storyEngineInfo("[ekairos/story] >>> HOOK shouldContinue() BEGIN", iter);
                 const continueLoop = await this.shouldContinue({
                     env: params.env,
                     context: updatedContext,
@@ -341,7 +315,6 @@ export class Story {
                     toolCalls,
                     toolExecutionResults: executionResults,
                 });
-                await storyEngineInfo("[ekairos/story] <<< HOOK shouldContinue() END", iter, continueLoop);
                 if (continueLoop === false) {
                     await updateEvent(params.env, reactionEventId, {
                         ...reactionEvent,
@@ -350,7 +323,7 @@ export class Story {
                     await updateContextStatus(params.env, contextSelector, "open");
                     await completeExecution(params.env, contextSelector, executionId, "completed");
                     if (!silent) {
-                        await closeStoryStream({ preventClose, sendFinish });
+                        await closeStoryStream({ preventClose, sendFinish, writable });
                     }
                     return {
                         contextId: currentContext.id,

package/package.json

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