@ekairos/events 1.22.4-beta.development.0

package/dist/context.contract.js

@@ -0,0 +1,132 @@
+export const CONTEXT_STATUSES = ["open_idle", "open_streaming", "closed"];
+export const EXECUTION_STATUSES = ["executing", "completed", "failed"];
+export const STEP_STATUSES = ["running", "completed", "failed"];
+export const STEP_KINDS = [
+    "message",
+    "action_execute",
+    "action_result",
+];
+export const ITEM_STATUSES = ["stored", "pending", "completed"];
+export const ITEM_TYPES = [
+    "input",
+    "output",
+];
+export const CHANNELS = ["web", "whatsapp", "email"];
+export const TRACE_EVENT_KINDS = [
+    "workflow.run",
+    "workflow.step",
+    "context.run",
+    "context.lifecycle",
+    "context.execution",
+    "context.item",
+    "context.review",
+    "context.step",
+    "context.part",
+    "context.llm",
+];
+export const STREAM_LIFECYCLE_CHUNK_TYPES = [
+    "chunk.start",
+    "chunk.start_step",
+    "chunk.finish_step",
+    "chunk.finish",
+];
+export const STREAM_TEXT_CHUNK_TYPES = [
+    "chunk.text_start",
+    "chunk.text_delta",
+    "chunk.text_end",
+];
+export const STREAM_REASONING_CHUNK_TYPES = [
+    "chunk.reasoning_start",
+    "chunk.reasoning_delta",
+    "chunk.reasoning_end",
+];
+export const STREAM_ACTION_CHUNK_TYPES = [
+    "chunk.action_input_start",
+    "chunk.action_input_delta",
+    "chunk.action_input_available",
+    "chunk.action_output_available",
+    "chunk.action_output_error",
+];
+export const STREAM_SOURCE_CHUNK_TYPES = [
+    "chunk.source_url",
+    "chunk.source_document",
+    "chunk.file",
+];
+export const STREAM_METADATA_CHUNK_TYPES = [
+    "chunk.message_metadata",
+    "chunk.response_metadata",
+];
+export const STREAM_ERROR_CHUNK_TYPES = [
+    "chunk.error",
+    "chunk.unknown",
+];
+export const CONTEXT_STREAM_CHUNK_TYPES = [
+    ...STREAM_LIFECYCLE_CHUNK_TYPES,
+    ...STREAM_TEXT_CHUNK_TYPES,
+    ...STREAM_REASONING_CHUNK_TYPES,
+    ...STREAM_ACTION_CHUNK_TYPES,
+    ...STREAM_SOURCE_CHUNK_TYPES,
+    ...STREAM_METADATA_CHUNK_TYPES,
+    ...STREAM_ERROR_CHUNK_TYPES,
+];
+export function isContextStreamChunkType(value) {
+    return CONTEXT_STREAM_CHUNK_TYPES.includes(value);
+}
+export const CONTEXT_TRANSITIONS = [
+    { from: "open_idle", to: "open_streaming" },
+    { from: "open_streaming", to: "open_idle" },
+    { from: "open_idle", to: "closed" },
+    { from: "open_streaming", to: "closed" },
+    { from: "closed", to: "open_idle" },
+];
+export const EXECUTION_TRANSITIONS = [
+    { from: "executing", to: "completed" },
+    { from: "executing", to: "failed" },
+];
+export const STEP_TRANSITIONS = [
+    { from: "running", to: "completed" },
+    { from: "running", to: "failed" },
+];
+export const ITEM_TRANSITIONS = [
+    { from: "stored", to: "pending" },
+    { from: "stored", to: "completed" },
+    { from: "pending", to: "completed" },
+];
+function canTransition(transitions, from, to) {
+    return transitions.some((transition) => transition.from === from && transition.to === to);
+}
+function assertTransition(transitions, from, to, entity) {
+    if (!canTransition(transitions, from, to)) {
+        throw new Error(`Invalid ${entity} transition: ${from} -> ${to}`);
+    }
+}
+export function canContextTransition(from, to) {
+    return canTransition(CONTEXT_TRANSITIONS, from, to);
+}
+export function canExecutionTransition(from, to) {
+    return canTransition(EXECUTION_TRANSITIONS, from, to);
+}
+export function canStepTransition(from, to) {
+    return canTransition(STEP_TRANSITIONS, from, to);
+}
+export function canItemTransition(from, to) {
+    return canTransition(ITEM_TRANSITIONS, from, to);
+}
+export function assertContextTransition(from, to) {
+    assertTransition(CONTEXT_TRANSITIONS, from, to, "context.status");
+}
+export function assertExecutionTransition(from, to) {
+    assertTransition(EXECUTION_TRANSITIONS, from, to, "execution.status");
+}
+export function assertStepTransition(from, to) {
+    assertTransition(STEP_TRANSITIONS, from, to, "step.status");
+}
+export function assertItemTransition(from, to) {
+    assertTransition(ITEM_TRANSITIONS, from, to, "item.status");
+}
+export function assertContextPartKey(stepId, idx, key) {
+    const expected = `${stepId}:${idx}`;
+    if (key !== expected) {
+        throw new Error(`Invalid context_parts.key: expected "${expected}" got "${key}"`);
+    }
+}

package/dist/context.d.ts

@@ -0,0 +1,4 @@
+export { ContextEngine, type ContextOptions, type ContextStreamOptions, type ShouldContinue, type ContextShouldContinueArgs, type ContextReactParams, type ContextReactResult, type ContextDurableWorkflowPayload, type ContextDurableWorkflowFunction, type ContextModelInit, type ContextTool, runContextReactionDirect, } from "./context.engine.js";
+export { context, createContext, type ContextConfig, type ContextInstance, type RegistrableContextBuilder, } from "./context.builder.js";
+export { createAiSdkReactor, createScriptedReactor, type CreateAiSdkReactorOptions, type CreateScriptedReactorOptions, type ScriptedReactorStep, type ContextReactor, type ContextReactorParams, type ContextReactionResult, type ContextActionRequest, type ContextReactionLLM, } from "./context.reactor.js";
+export type { ContextSkillPackage, ContextSkillPackageFile, } from "./context.skill.js";

package/dist/context.durable.d.ts

@@ -0,0 +1,5 @@
+import type { ContextDurableWorkflowFunction, ContextReactResult, ContextDurableWorkflowPayload } from "./context.engine.js";
+import type { ContextEnvironment } from "./context.config.js";
+export declare function configureContextDurableWorkflow<Context = any, Env extends ContextEnvironment = ContextEnvironment>(workflow: ContextDurableWorkflowFunction<Context, Env> | null): void;
+export declare function getContextDurableWorkflow(): ContextDurableWorkflowFunction<any, any> | undefined;
+export type { ContextDurableWorkflowFunction, ContextDurableWorkflowPayload, ContextReactResult, };

package/dist/context.durable.js

@@ -0,0 +1,13 @@
+const durableWorkflowSymbol = Symbol.for("ekairos.events.contextDurableWorkflow");
+export function configureContextDurableWorkflow(workflow) {
+    if (typeof globalThis === "undefined")
+        return;
+    const store = globalThis;
+    store[durableWorkflowSymbol] = workflow ?? undefined;
+}
+export function getContextDurableWorkflow() {
+    if (typeof globalThis === "undefined")
+        return undefined;
+    const store = globalThis;
+    return store[durableWorkflowSymbol];
+}

package/dist/context.engine.d.ts

@@ -0,0 +1,216 @@
+import type { Tool, UIMessageChunk } from "ai";
+import type { ContextEnvironment } from "./context.config.js";
+import type { ContextExecution, ContextItem, ContextIdentifier, StoredContext } from "./context.store.js";
+import type { ContextSkillPackage } from "./context.skill.js";
+import { type ContextReactor } from "./context.reactor.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken } from "./context.hooks.js";
+export interface ContextOptions<Context = any, Env extends ContextEnvironment = ContextEnvironment> {
+    onContextCreated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onContextUpdated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onEventCreated?: (event: ContextItem) => void | Promise<void>;
+    onActionExecuted?: (executionEvent: any) => void | Promise<void>;
+    onEnd?: (lastEvent: ContextItem) => void | boolean | Promise<void | boolean>;
+}
+type ContextBenchmarkRecorder = {
+    measure<T>(name: string, run: () => Promise<T> | T): Promise<T>;
+    add?(name: string, value: number): void;
+    getCurrentStage?(): string | undefined;
+};
+export declare function runContextReactionDirect<Context, Env extends ContextEnvironment = ContextEnvironment>(context: ContextEngine<Context, Env>, triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+export interface ContextStreamOptions {
+    /**
+     * Maximum loop iterations (LLM call → tool execution → repeat).
+     * Default: 20
+     */
+    maxIterations?: number;
+    /**
+     * Maximum model steps per LLM call.
+     * Default: 1 (or 5 if you override it in your implementation).
+     */
+    maxModelSteps?: number;
+    /**
+     * If true, we do not close the workflow writable stream.
+     * Default: false.
+     */
+    preventClose?: boolean;
+    /**
+     * If true, we write a `finish` chunk to the workflow stream.
+     * 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;
+    /**
+     * Optional writable stream used by direct/non-durable execution.
+     *
+     * Durable execution owns its workflow stream and will reject custom writables.
+     */
+    writable?: WritableStream<UIMessageChunk>;
+}
+/**
+ * Model initializer (DurableAgent-style).
+ *
+ * - `string`: Vercel AI Gateway model id (e.g. `"openai/gpt-5"`), resolved inside the LLM step.
+ * - `function`: a function that returns a model instance. For Workflow compatibility, this should
+ *   be a `"use-step"` function (so it can be serialized by reference).
+ */
+export type ContextModelInit = string | (() => Promise<any>);
+export type ContextReactParams<Env extends ContextEnvironment = ContextEnvironment> = {
+    env: Env;
+    /**
+     * Context selector (exclusive: `{ id }` OR `{ key }`).
+     * - `{ id }` resolves a concrete context id.
+     * - `{ key }` resolves by `context.key`.
+     * If omitted/null, the story will create a new context.
+     */
+    context?: ContextIdentifier | null;
+    durable?: boolean;
+    options?: ContextStreamOptions;
+    /**
+     * Internal bootstrap used by the workflow-owned continuation path.
+     * Not part of the public API surface.
+     */
+    __bootstrap?: {
+        contextId: string;
+        trigger: ContextItem;
+        reaction: ContextItem;
+        execution: ContextExecution;
+    };
+    __benchmark?: ContextBenchmarkRecorder;
+};
+export type ContextReactResult<Context = any> = {
+    context: StoredContext<Context>;
+    trigger: ContextItem;
+    reaction: ContextItem;
+    execution: ContextExecution;
+};
+export type ContextDurableWorkflowPayload<Env extends ContextEnvironment = ContextEnvironment> = {
+    contextKey: string;
+    env: Env;
+    context?: ContextIdentifier | null;
+    triggerEvent: ContextItem;
+    options?: Omit<ContextStreamOptions, "writable">;
+    bootstrap: NonNullable<ContextReactParams<Env>["__bootstrap"]>;
+};
+export type ContextDurableWorkflowFunction<Context = any, Env extends ContextEnvironment = ContextEnvironment> = (payload: ContextDurableWorkflowPayload<Env>) => Promise<ContextReactResult<Context>>;
+export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
+/**
+ * Context-level tool type.
+ *
+ * Allows contexts 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 ContextTool = 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;
+};
+/**
+ * ## Context loop continuation signal
+ *
+ * This hook result is intentionally a **boolean** so stories can be extremely declarative:
+ *
+ * - `return true`  => **continue** the durable loop
+ * - `return false` => **finalize** the durable loop
+ *
+ * (No imports required in callers.)
+ */
+export type ShouldContinue = boolean;
+export type ContextShouldContinueArgs<Context = any, Env extends ContextEnvironment = ContextEnvironment> = {
+    env: Env;
+    context: StoredContext<Context>;
+    /**
+     * The persisted reaction event **so far** for the current streaming run.
+     *
+     * This contains the assistant's streamed parts as well as merged tool execution
+     * outcomes (e.g. `state: "output-available"` / `"output-error"`).
+     *
+     * Stories can inspect `reactionEvent.content.parts` to determine stop conditions
+     * (for example: when `tool-end` has an `output-available` state).
+     */
+    reactionEvent: ContextItem;
+    assistantEvent: ContextItem;
+    actionRequests: Array<{
+        actionRef: string;
+        actionName: string;
+        input: unknown;
+    }>;
+    actionResults: Array<{
+        actionRequest: {
+            actionRef: string;
+            actionName: string;
+            input: unknown;
+        };
+        success: boolean;
+        output: any;
+        errorText?: string;
+    }>;
+};
+export declare abstract class ContextEngine<Context, Env extends ContextEnvironment = ContextEnvironment> {
+    protected readonly opts: ContextOptions<Context, Env>;
+    private readonly reactor;
+    constructor(opts?: ContextOptions<Context, Env>, reactor?: ContextReactor<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, ContextTool>> | Record<string, ContextTool>;
+    protected buildSkills(_context: StoredContext<Context>, _env: Env): Promise<ContextSkillPackage[]>;
+    /**
+     * First-class event expansion stage (runs on every iteration of the durable loop).
+     *
+     * Use this to expand/normalize events before they are converted into model messages.
+     * Typical use-cases:
+     * - Expand file/document references into text (LlamaCloud/Reducto/…)
+     * - Token compaction / summarization of older parts
+     * - Attaching derived context snippets to the next model call
+     *
+     * IMPORTANT:
+     * - This stage is ALWAYS executed by the engine.
+     * - If you don't provide an implementation, the default behavior is an identity transform
+     *   (events pass through unchanged).
+     * - If your implementation performs I/O, implement it as a `"use-step"` function (provided via
+     *   the builder) so results are durable and replay-safe.
+     * - If it’s pure/deterministic, it can run in workflow context.
+     */
+    protected expandEvents(events: ContextItem[], _context: StoredContext<Context>, _env: Env): Promise<ContextItem[]>;
+    protected getModel(_context: StoredContext<Context>, _env: Env): ContextModelInit;
+    protected getReactor(_context: StoredContext<Context>, _env: Env): ContextReactor<Context, Env>;
+    /**
+     * Context stop/continue hook.
+     *
+     * After the model streamed and tools executed, the story can decide whether the loop should
+     * continue.
+     *
+     * Default: `true` (continue).
+     */
+    protected shouldContinue(_args: ContextShouldContinueArgs<Context, Env>): Promise<ShouldContinue>;
+    react(triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+    private static prepareExecutionShell;
+    private static startDurable;
+    static runDirect<Context, Env extends ContextEnvironment>(story: ContextEngine<Context, Env>, triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<{
+        context: StoredContext<Context>;
+        trigger: ContextItem;
+        reaction: ContextItem;
+        execution: ContextExecution;
+    }>;
+    /**
+     * @deprecated Use `react()` instead. Kept for backwards compatibility.
+     */
+    stream(triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+    private callOnEnd;
+}