@ekairos/thread 1.21.88-beta.0

package/dist/story.actions.js

@@ -0,0 +1,120 @@
+import { getStory, hasStory, listStories } from "./story.registry.js";
+function isContextEvent(value) {
+    return Boolean(value &&
+        typeof value === "object" &&
+        typeof value.type === "string" &&
+        typeof value.id === "string");
+}
+function resolveStoryKey(input, ctx) {
+    if (input && typeof input === "object") {
+        const key = String(input.storyKey ?? "").trim();
+        if (key)
+            return key;
+        const storyKey = String(input.story?.key ?? "").trim();
+        if (storyKey)
+            return storyKey;
+    }
+    if (typeof ctx.storyKey === "string" && ctx.storyKey.trim()) {
+        return ctx.storyKey.trim();
+    }
+    if (ctx.domain?.meta && typeof ctx.domain.meta.storyKey === "string") {
+        const key = String(ctx.domain.meta.storyKey ?? "").trim();
+        if (key)
+            return key;
+    }
+    if (typeof ctx.env?.storyKey === "string") {
+        const key = String(ctx.env.storyKey ?? "").trim();
+        if (key)
+            return key;
+    }
+    return null;
+}
+function resolveStoryInstance(input, ctx) {
+    if (input && typeof input === "object") {
+        const story = input.story;
+        if (story && typeof story.react === "function")
+            return story;
+    }
+    if (ctx.story && typeof ctx.story.react === "function")
+        return ctx.story;
+    if (ctx.domain?.meta && ctx.domain.meta?.story) {
+        const story = ctx.domain.meta.story;
+        if (story && typeof story.react === "function")
+            return story;
+    }
+    return null;
+}
+function resolveTriggerEvent(input) {
+    if (isContextEvent(input))
+        return input;
+    if (input && typeof input === "object") {
+        const triggerEvent = input.triggerEvent ?? input.incomingEvent;
+        if (isContextEvent(triggerEvent))
+            return triggerEvent;
+    }
+    return null;
+}
+function resolveContextIdentifier(input) {
+    if (input && typeof input === "object") {
+        return input.context ?? input.contextIdentifier ?? null;
+    }
+    return null;
+}
+function resolveOptions(input) {
+    if (input && typeof input === "object") {
+        return input.options;
+    }
+    return undefined;
+}
+export const storyActions = {
+    react: {
+        description: "Run a registered story reaction for an incoming event.",
+        execute: async (input, ctx) => {
+            "use workflow";
+            const resolvedEnv = ctx?.env ??
+                (input && typeof input === "object" ? input.env : undefined);
+            if (!resolvedEnv) {
+                throw new Error("story.react: env is required (ctx.env or input.env).");
+            }
+            const triggerEvent = resolveTriggerEvent(input);
+            if (!triggerEvent) {
+                throw new Error("story.react: triggerEvent is required.");
+            }
+            const contextIdentifier = resolveContextIdentifier(input);
+            const options = resolveOptions(input);
+            const storyInstance = resolveStoryInstance(input, ctx ?? { env: resolvedEnv });
+            if (storyInstance) {
+                return await storyInstance.react(triggerEvent, {
+                    env: resolvedEnv,
+                    context: contextIdentifier ?? null,
+                    options,
+                });
+            }
+            const storyKey = resolveStoryKey(input, ctx ?? { env: resolvedEnv });
+            if (!storyKey) {
+                throw new Error("story.react: storyKey is required (env.storyKey, input.storyKey, or registered story).");
+            }
+            const story = getStory(storyKey);
+            return await story.react(triggerEvent, {
+                env: resolvedEnv,
+                context: contextIdentifier ?? null,
+                options,
+            });
+        },
+    },
+    listStories: {
+        description: "List registered story keys in the current runtime.",
+        execute: async () => {
+            return { ok: true, data: { stories: listStories() } };
+        },
+    },
+    hasStory: {
+        description: "Check if a story key is registered in the current runtime.",
+        execute: async (input) => {
+            const key = String(input?.storyKey ?? "").trim();
+            if (!key)
+                return { ok: false, error: "missing_story_key" };
+            return { ok: true, data: { storyKey: key, registered: hasStory(key) } };
+        },
+    },
+};

package/dist/story.builder.d.ts

@@ -0,0 +1,115 @@
+import type { StoryEnvironment } from "./story.config.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> {
+    context: (context: StoredContext<Context>, env: Env) => Promise<Context> | Context;
+    /**
+     * Event expansion stage (first-class; executed by the engine on every loop iteration).
+     *
+     * Runs inside the Story loop after events are loaded from the store and before
+     * they are converted into model messages.
+     *
+     * This is the intended place to do "document expansion" (turn file references
+     * into text parts) using LlamaCloud/Reducto/etc.
+     *
+     * If you do not provide an implementation, the default is an identity transform
+     * (events pass through unchanged).
+     *
+     * If you do I/O here, implement it as a `"use-step"` function.
+     */
+    expandEvents?: (events: ContextEvent[], context: StoredContext<Context>, env: Env) => Promise<ContextEvent[]> | ContextEvent[];
+    /**
+     * Story-first "system" message for the model for this story run.
+     */
+    narrative: (context: StoredContext<Context>, env: Env) => Promise<string> | string;
+    /**
+     * Actions available to the model (aka "tools" in AI SDK terminology).
+     */
+    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, StoryTool>> | Record<string, StoryTool>;
+    /**
+     * Model configuration (DurableAgent-style).
+     *
+     * - `string`: AI Gateway model id, resolved in the LLM step (e.g. `"openai/gpt-5.1-thinking"`).
+     * - `() => Promise<model>`: model factory. For Workflow compatibility, provide a `"use-step"` function
+     *   so it can be serialized by reference.
+     * - `(context, env) => ...`: dynamic selection based on current context/env (runs in workflow context).
+     */
+    model?: StoryModelInit | ((context: StoredContext<Context>, env: Env) => StoryModelInit);
+    /**
+     * Called after each streamed model "reaction" and subsequent tool executions.
+     *
+     * Use this to decide whether the story loop should continue.
+     *
+     * - `true`  => continue looping
+     * - `false` => finalize the story run
+     */
+    shouldContinue?: (args: StoryShouldContinueArgs<Context, Env>) => Promise<ShouldContinue> | ShouldContinue;
+    opts?: StoryOptions<Context, Env>;
+}
+export type StoryInstance<Context, Env extends StoryEnvironment = StoryEnvironment> = Story<Context, Env> & {
+    readonly __config: StoryConfig<Context, Env>;
+};
+export declare function story<Context, Env extends StoryEnvironment = StoryEnvironment>(config: StoryConfig<Context, Env>): StoryInstance<Context, Env>;
+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, 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);
+export type RegistrableStoryBuilder = {
+    key: StoryKey;
+    register: () => void;
+};
+type FluentStoryBuilder<Context, Env extends StoryEnvironment> = {
+    key: StoryKey;
+    expandEvents(fn: BuilderExpandEvents<Context, Env>): FluentStoryBuilder<Context, Env>;
+    narrative(fn: BuilderSystemPrompt<Context, Env>): FluentStoryBuilder<Context, Env>;
+    /**
+     * "System" facade (AI SDK terminology).
+     */
+    system(fn: BuilderSystemPrompt<Context, Env>): FluentStoryBuilder<Context, Env>;
+    actions(fn: BuilderTools<Context, Env>): FluentStoryBuilder<Context, Env>;
+    /**
+     * @deprecated Use `actions()` instead.
+     */
+    tools(fn: BuilderTools<Context, Env>): FluentStoryBuilder<Context, Env>;
+    model(model: BuilderModel<Context, Env>): FluentStoryBuilder<Context, Env>;
+    /**
+     * Stop/continue hook (DurableAgent-like stop condition).
+     */
+    shouldContinue(fn: BuilderShouldContinue<Context, Env>): FluentStoryBuilder<Context, Env>;
+    opts(opts: StoryOptions<Context, Env>): FluentStoryBuilder<Context, Env>;
+    /**
+     * Convenience: react to an incoming event without requiring an explicit `.build()`.
+     *
+     * This still validates the config is complete (same as `.build()`), then delegates to the
+     * underlying `Story.react(...)`.
+     */
+    react(triggerEvent: ContextEvent, params: StoryReactParams<Env>): ReturnType<Story<Context, Env>["react"]>;
+    /**
+     * @deprecated Use `react()` instead. Kept for backwards compatibility.
+     */
+    stream(triggerEvent: ContextEvent, params: StoryReactParams<Env>): ReturnType<Story<Context, Env>["react"]>;
+    /**
+     * Registers this story definition in the global registry under `key`.
+     *
+     * This is intended to be called at module load / boot time so durable workflows
+     * can resume and still resolve the story by key without requiring an endpoint
+     * to call `.build()` again.
+     */
+    register(): void;
+    config(): StoryConfig<Context, Env>;
+    build(): StoryInstance<Context, Env>;
+};
+type CreateStoryEntry<Env extends StoryEnvironment> = {
+    context<Initializer extends AnyContextInitializer<Env>>(initializer: Initializer): FluentStoryBuilder<InferContextFromInitializer<Initializer>, Env>;
+    initialize<Initializer extends AnyContextInitializer<Env>>(initializer: Initializer): FluentStoryBuilder<InferContextFromInitializer<Initializer>, Env>;
+};
+export declare function createStory<Env extends StoryEnvironment = StoryEnvironment>(key: StoryKey): CreateStoryEntry<Env>;
+export {};

package/dist/story.builder.js

@@ -0,0 +1,130 @@
+import { Story, } from "./story.engine.js";
+import { registerStory } from "./story.registry.js";
+export function story(config) {
+    class FunctionalStory extends Story {
+        constructor() {
+            super(config.opts);
+            this.__config = config;
+        }
+        async initialize(context, env) {
+            return config.context(context, env);
+        }
+        async expandEvents(events, context, env) {
+            if (config.expandEvents)
+                return config.expandEvents(events, context, env);
+            return super.expandEvents(events, context, env);
+        }
+        async buildSystemPrompt(context, env) {
+            if (config.narrative)
+                return config.narrative(context, env);
+            throw new Error("Story config is missing narrative()");
+        }
+        async buildTools(context, env) {
+            // Back-compat: accept `tools` in old configs.
+            if (config.actions)
+                return config.actions(context, env);
+            if (config.tools)
+                return config.tools(context, env);
+            throw new Error("Story config is missing actions()");
+        }
+        getModel(context, env) {
+            if (typeof config.model === "function")
+                return config.model(context, env);
+            return config.model ?? super.getModel(context, env);
+        }
+        async shouldContinue(args) {
+            if (config.shouldContinue)
+                return config.shouldContinue(args);
+            return true;
+        }
+    }
+    const instance = new FunctionalStory();
+    return Object.assign(instance, { __config: config });
+}
+function assertConfigComplete(config) {
+    if (!config.context) {
+        throw new Error("createStory: you must define context() before building the story.");
+    }
+    if (!config.narrative) {
+        throw new Error("createStory: you must define narrative() before building the story.");
+    }
+    if (!config.actions && !config.tools) {
+        throw new Error("createStory: you must define actions() before building the story.");
+    }
+}
+export function createStory(key) {
+    const initializeBuilder = (initializer) => {
+        const typedInitializer = (ctx, env) => initializer(ctx, env);
+        const fluentState = {
+            context: typedInitializer,
+        };
+        let cached = null;
+        const builder = {
+            key,
+            expandEvents(fn) {
+                fluentState.expandEvents = fn;
+                return builder;
+            },
+            narrative(narrative) {
+                fluentState.narrative = narrative;
+                return builder;
+            },
+            system(system) {
+                // Facade alias.
+                fluentState.narrative = system;
+                return builder;
+            },
+            actions(actionsFactory) {
+                fluentState.actions = actionsFactory;
+                return builder;
+            },
+            tools(toolsFactory) {
+                // Back-compat alias.
+                fluentState.actions = toolsFactory;
+                return builder;
+            },
+            model(model) {
+                fluentState.model = model;
+                return builder;
+            },
+            shouldContinue(fn) {
+                fluentState.shouldContinue = fn;
+                return builder;
+            },
+            opts(options) {
+                fluentState.opts = options;
+                return builder;
+            },
+            react(triggerEvent, params) {
+                assertConfigComplete(fluentState);
+                if (!cached) {
+                    const config = fluentState;
+                    cached = story(config);
+                }
+                return cached.react(triggerEvent, params);
+            },
+            stream(triggerEvent, params) {
+                return builder.react(triggerEvent, params);
+            },
+            register() {
+                assertConfigComplete(fluentState);
+                const config = fluentState;
+                registerStory(key, () => story(config));
+            },
+            config() {
+                assertConfigComplete(fluentState);
+                return fluentState;
+            },
+            build() {
+                assertConfigComplete(fluentState);
+                const config = fluentState;
+                return story(config);
+            },
+        };
+        return builder;
+    };
+    return {
+        context: initializeBuilder,
+        initialize: initializeBuilder,
+    };
+}

package/dist/story.config.d.ts

@@ -0,0 +1,54 @@
+import type { StoryStore } from "./story.store.js";
+import type { ConcreteDomain } from "@ekairos/domain";
+/**
+ * ## story.config.ts
+ *
+ * Workflow-first story execution means we **cannot** keep non-serializable runtime objects
+ * (database clients, network handles, SDK instances) inside workflow state.
+ *
+ * Instead, we centralize runtime construction behind a global resolver:
+ * - The workflow passes a **serializable** `StoryEnvironment` into steps.
+ * - Steps call `resolveStoryRuntime(env)` to instantiate the right store (Instant/Postgres/etc).
+ *
+ * This keeps `createStory(...)` purely declarative while still allowing per-tenant/per-org routing.
+ */
+export type StoryEnvironment = Record<string, unknown>;
+export type StoryRuntime = {
+    store: StoryStore;
+    db: any;
+    domain?: ConcreteDomain<any, any>;
+};
+export type StoryRuntimeResolver<Env extends StoryEnvironment = StoryEnvironment> = (env: Env) => Promise<StoryRuntime | {
+    db?: any;
+    store?: StoryStore;
+    domain?: ConcreteDomain<any, any>;
+} | any> | StoryRuntime | {
+    db?: any;
+    store?: StoryStore;
+    domain?: ConcreteDomain<any, any>;
+} | any;
+/**
+ * Optional global bootstrap hook for step runtimes.
+ *
+ * Motivation:
+ * - Workflow step runtimes may execute in a separate process/bundle.
+ * - If the app's `ekairos.ts` was not evaluated in that runtime yet, the story runtime
+ *   resolver won't be configured and store steps will fail.
+ *
+ * Convention:
+ * - Apps should have a single `ekairos.ts` that calls `createEkairosConfig()` from `@ekairos/domain/runtime`.
+ * - That module can register this bootstrap function,
+ *   so library steps can "pull" initialization on-demand before first store access.
+ */
+type RuntimeBootstrap = () => void | Promise<void>;
+export declare function configureStoryRuntimeBootstrap(bootstrap: RuntimeBootstrap): void;
+/**
+ * Configure the story runtime resolver (global).
+ *
+ * This should be called once during initialization (module load) in your app.
+ * The resolver itself will be invoked inside steps, where it can safely create DB clients.
+ */
+export declare function configureStoryRuntime<Env extends StoryEnvironment>(resolver: StoryRuntimeResolver<Env>): void;
+export declare function isStoryRuntimeConfigured(): boolean;
+export declare function resolveStoryRuntime(env: StoryEnvironment): Promise<StoryRuntime>;
+export {};

package/dist/story.config.js

@@ -0,0 +1,125 @@
+import { pathToFileURL } from "node:url";
+import { join } from "node:path";
+const runtimeResolverSymbol = Symbol.for("ekairos.story.runtimeResolver");
+const runtimeBootstrapSymbol = Symbol.for("ekairos.story.runtimeBootstrap");
+function getGlobalRuntimeResolver() {
+    if (typeof globalThis === "undefined")
+        return null;
+    return globalThis[runtimeResolverSymbol] ?? null;
+}
+function setGlobalRuntimeResolver(resolver) {
+    if (typeof globalThis === "undefined")
+        return;
+    globalThis[runtimeResolverSymbol] = resolver;
+}
+let runtimeResolver = null;
+const runtimeByDb = new WeakMap();
+async function normalizeRuntime(value) {
+    if (!value) {
+        throw new Error("Story runtime resolver returned no value.");
+    }
+    if (typeof value === "object" && value.store) {
+        return value;
+    }
+    const dbCandidate = typeof value === "object" && value !== null && "db" in value
+        ? value.db
+        : value;
+    if (!dbCandidate) {
+        throw new Error("Story runtime resolver did not provide a database or store.");
+    }
+    if (typeof dbCandidate === "object" && dbCandidate !== null) {
+        const cached = runtimeByDb.get(dbCandidate);
+        if (cached)
+            return cached;
+    }
+    const { InstantStore } = await import("./stores/instant.store.js");
+    const runtime = {
+        store: new InstantStore(dbCandidate),
+        db: dbCandidate,
+        domain: typeof value === "object" ? value.domain : undefined,
+    };
+    if (typeof dbCandidate === "object" && dbCandidate !== null) {
+        runtimeByDb.set(dbCandidate, runtime);
+    }
+    return runtime;
+}
+function getRuntimeResolver() {
+    return runtimeResolver ?? getGlobalRuntimeResolver();
+}
+let runtimeBootstrap = null;
+function getGlobalRuntimeBootstrap() {
+    if (typeof globalThis === "undefined")
+        return null;
+    return globalThis[runtimeBootstrapSymbol] ?? null;
+}
+function setGlobalRuntimeBootstrap(bootstrap) {
+    if (typeof globalThis === "undefined")
+        return;
+    globalThis[runtimeBootstrapSymbol] = bootstrap;
+}
+function getRuntimeBootstrap() {
+    return runtimeBootstrap ?? getGlobalRuntimeBootstrap();
+}
+export function configureStoryRuntimeBootstrap(bootstrap) {
+    runtimeBootstrap = bootstrap;
+    setGlobalRuntimeBootstrap(bootstrap);
+}
+/**
+ * Configure the story runtime resolver (global).
+ *
+ * This should be called once during initialization (module load) in your app.
+ * The resolver itself will be invoked inside steps, where it can safely create DB clients.
+ */
+export function configureStoryRuntime(resolver) {
+    runtimeResolver = resolver;
+    setGlobalRuntimeResolver(runtimeResolver);
+}
+export function isStoryRuntimeConfigured() {
+    return Boolean(getRuntimeResolver());
+}
+export async function resolveStoryRuntime(env) {
+    if (!getRuntimeResolver()) {
+        // Best-effort: allow the step runtime to self-bootstrap once.
+        const bootstrap = getRuntimeBootstrap();
+        if (bootstrap) {
+            await bootstrap();
+        }
+        // Convention bootstrap (portable, runtime-resolvable):
+        // If the host app provides an `ekairos.bootstrap.js` at the project root, we can load it
+        // from the step runtime using a file URL. This avoids relying on bundler-only aliases.
+        if (!getRuntimeResolver()) {
+            const cwd = typeof process !== "undefined" && process.cwd ? process.cwd() : null;
+            if (cwd) {
+                const dynamicImport = new Function("specifier", "return import(specifier)");
+                const candidates = [
+                    "ekairos.bootstrap.js",
+                    "ekairos.bootstrap.cjs",
+                    "ekairos.bootstrap.mjs",
+                ];
+                for (const filename of candidates) {
+                    try {
+                        await dynamicImport(pathToFileURL(join(cwd, filename)).href);
+                        break;
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+            }
+        }
+        // If bootstrap succeeded, proceed.
+        const resolver = getRuntimeResolver();
+        if (resolver)
+            return await normalizeRuntime(await resolver(env));
+        throw new Error([
+            "Story runtime is not configured.",
+            "",
+            "Convention:",
+            "- Create an app-level `ekairos.ts` that exports `ekairosConfig = createEkairosConfig({ runtime })` from @ekairos/domain/runtime",
+            "- Ensure the bootstrap module is evaluated in the step runtime (module load / worker boot).",
+            "",
+            "If you already have that file, ensure it is evaluated in the step runtime before calling story store steps.",
+        ].join("\n"));
+    }
+    return await normalizeRuntime(await getRuntimeResolver()(env));
+}

package/dist/story.d.ts

@@ -0,0 +1,2 @@
+export { Story, type StoryOptions, type StoryStreamOptions, type ShouldContinue, type StoryShouldContinueArgs, } from "./story.engine.js";
+export { story, createStory, type StoryConfig, type StoryInstance, type RegistrableStoryBuilder, } from "./story.builder.js";