@ekairos/story 1.21.58-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

@@ -30,10 +30,8 @@ export async function initializeContext(env, contextIdentifier, opts) {
     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",

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

@@ -1,3 +1,4 @@
+import type { UIMessageChunk } from "ai";
 export declare function writeContextSubstate(params: {
     /**
      * Ephemeral substate key for the UI (story engine internal state).
@@ -7,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: {
     /**
@@ -17,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<{
@@ -28,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,7 +1,8 @@
 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({
@@ -16,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({
@@ -32,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({
@@ -48,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) {
@@ -77,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

@@ -3,6 +3,26 @@ 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";
+/**
+ * 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}`;
+}
+/**
+ * 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 = {}) {
         this.opts = opts;
@@ -59,8 +79,9 @@ export class Story {
         const preventClose = params.options?.preventClose ?? false;
         const sendFinish = params.options?.sendFinish ?? true;
         const silent = params.options?.silent ?? false;
+        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;
         const contextSelector = params.contextIdentifier?.id
             ? { id: String(params.contextIdentifier.id) }
@@ -81,7 +102,7 @@ export class Story {
         // 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).
@@ -95,7 +116,7 @@ export class Story {
             }
             try {
                 if (!silent) {
-                    await closeStoryStream({ preventClose, sendFinish });
+                    await closeStoryStream({ preventClose, sendFinish, writable });
                 }
             }
             catch {
@@ -126,6 +147,7 @@ export class Story {
                     // Only emit a `start` chunk once per story turn.
                     sendStart: !silent && iter === 0 && reactionEvent === null,
                     silent,
+                    writable,
                 });
                 // Persist/append the assistant event for this iteration
                 if (!reactionEvent) {
@@ -159,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,
@@ -172,7 +194,7 @@ 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];
@@ -185,7 +207,41 @@ export class Story {
                         };
                     }
                     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,
@@ -214,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) {
@@ -266,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.58-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.58-beta.0",
+    "@ekairos/domain": "^1.21.59-beta.0",
     "@instantdb/admin": "^0.22.13",
     "@instantdb/core": "^0.22.13",
     "@vercel/sandbox": "^0.0.23",