@ekairos/events 1.22.4-beta.development.0

package/dist/reactors/ai-sdk.step.d.ts

@@ -0,0 +1,48 @@
+import type { ModelMessage, UIMessageChunk } from "ai";
+import type { ContextEnvironment } from "../context.config.js";
+import type { ContextModelInit } from "../context.engine.js";
+import type { ContextItem, ContextIdentifier } from "../context.store.js";
+import type { SerializableToolForModel } from "../tools-to-model-tools.js";
+/**
+ * AI SDK-backed reaction execution inside a single workflow step.
+ *
+ * Provider-specific responsibilities live here:
+ * - load items from store
+ * - build model messages
+ * - stream through the AI SDK
+ * - map provider chunks to the Context stream contract
+ * - emit UI chunks and persist step stream chunks
+ */
+export declare function executeAiSdkReaction(params: {
+    env: ContextEnvironment;
+    contextIdentifier: ContextIdentifier;
+    model: ContextModelInit;
+    system: string;
+    tools: Record<string, SerializableToolForModel>;
+    eventId: string;
+    iteration?: number;
+    maxSteps: number;
+    sendStart?: boolean;
+    silent?: boolean;
+    contextStepStream?: WritableStream<string>;
+    writable?: WritableStream<UIMessageChunk>;
+    executionId?: string;
+    contextId?: string;
+    stepId?: string;
+}): Promise<{
+    assistantEvent: ContextItem;
+    toolCalls: any[];
+    messagesForModel: ModelMessage[];
+    llm?: {
+        provider?: string;
+        model?: string;
+        promptTokens?: number;
+        promptTokensCached?: number;
+        promptTokensUncached?: number;
+        completionTokens?: number;
+        totalTokens?: number;
+        latencyMs?: number;
+        rawUsage?: any;
+        rawProviderMetadata?: any;
+    };
+}>;

package/dist/reactors/ai-sdk.step.js

@@ -0,0 +1,343 @@
+import { OUTPUT_ITEM_TYPE } from "../context.events.js";
+import { createContextStepStreamChunk, encodeContextStepStreamChunk, } from "../context.step-stream.js";
+import { mapAiSdkChunkToContextEvent } from "./ai-sdk.chunk-map.js";
+import { writeContextTraceEvents } from "../steps/trace.steps.js";
+async function readWorkflowMetadata() {
+    try {
+        const { getWorkflowMetadata } = await import("workflow");
+        return getWorkflowMetadata?.() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveWorkflowRunId(env, executionId) {
+    let runId = "";
+    const meta = await readWorkflowMetadata();
+    if (meta && meta.workflowRunId !== undefined && meta.workflowRunId !== null) {
+        runId = String(meta.workflowRunId);
+    }
+    if (!runId && executionId) {
+        try {
+            const { getContextRuntime } = await import("../runtime.js");
+            const runtime = await getContextRuntime(env);
+            const db = runtime?.db;
+            if (db) {
+                const q = await db.query({
+                    event_executions: {
+                        $: { where: { id: String(executionId) }, limit: 1 },
+                    },
+                });
+                const row = q?.event_executions?.[0];
+                if (row?.workflowRunId) {
+                    runId = String(row.workflowRunId);
+                }
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return runId || undefined;
+}
+function safeErrorJson(error) {
+    const seen = new WeakSet();
+    const redactKey = (k) => /token|authorization|cookie|secret|api[_-]?key|password/i.test(k);
+    const err = error;
+    const payload = {
+        name: err?.name,
+        message: err?.message,
+        status: err?.status,
+        body: err?.body,
+        data: err?.data,
+        stack: err?.stack,
+    };
+    try {
+        return JSON.stringify(payload, (k, v) => {
+            if (redactKey(k))
+                return "[redacted]";
+            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;
+        });
+    }
+    catch {
+        return JSON.stringify({ message: String(err?.message ?? "error") });
+    }
+}
+/**
+ * AI SDK-backed reaction execution inside a single workflow step.
+ *
+ * Provider-specific responsibilities live here:
+ * - load items from store
+ * - build model messages
+ * - stream through the AI SDK
+ * - map provider chunks to the Context stream contract
+ * - emit UI chunks and persist step stream chunks
+ */
+export async function executeAiSdkReaction(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(params.env);
+    let events;
+    try {
+        events = await store.getItems(params.contextIdentifier);
+    }
+    catch (error) {
+        console.error("[ekairos/story] ai-sdk.step store.getItems failed");
+        throw error;
+    }
+    let messagesForModel;
+    try {
+        messagesForModel = (await store.itemsToModelMessages(events));
+    }
+    catch (error) {
+        console.error("[ekairos/story] ai-sdk.step store.itemsToModelMessages failed", safeErrorJson(error));
+        throw error;
+    }
+    const { jsonSchema, gateway, smoothStream, stepCountIs, streamText } = await import("ai");
+    const { extractToolCallsFromParts } = await import("../context.toolcalls.js");
+    const resolvedModel = typeof params.model === "string"
+        ? gateway(params.model)
+        : typeof params.model === "function"
+            ? await params.model()
+            : (() => {
+                throw new Error("Invalid model init passed to executeAiSdkReaction. Expected a model id string or an async model factory.");
+            })();
+    const toolsForStreamText = {};
+    for (const [name, t] of Object.entries(params.tools)) {
+        toolsForStreamText[name] = {
+            description: t?.description,
+            inputSchema: jsonSchema(t.inputSchema),
+        };
+    }
+    const startedAtMs = Date.now();
+    const result = streamText({
+        model: resolvedModel,
+        system: params.system,
+        messages: messagesForModel,
+        tools: toolsForStreamText,
+        toolChoice: "required",
+        stopWhen: stepCountIs(params.maxSteps),
+        experimental_transform: smoothStream({ delayInMs: 30, chunking: "word" }),
+    });
+    result.consumeStream();
+    let resolveFinish;
+    let rejectFinish;
+    let chunkSequence = 0;
+    const finishPromise = new Promise((resolve, reject) => {
+        resolveFinish = resolve;
+        rejectFinish = reject;
+    });
+    const modelId = typeof params.model === "string" ? params.model : "";
+    const mappedProvider = modelId.includes("/") ? modelId.split("/")[0] : undefined;
+    const contextStepStreamWriter = params.contextStepStream?.getWriter();
+    try {
+        const uiStream = result
+            .toUIMessageStream({
+            sendStart: Boolean(params.sendStart),
+            generateMessageId: () => params.eventId,
+            messageMetadata() {
+                return { eventId: params.eventId };
+            },
+            onFinish: ({ messages }) => {
+                const lastMessage = messages[messages.length - 1];
+                const event = {
+                    id: params.eventId,
+                    type: OUTPUT_ITEM_TYPE,
+                    channel: "web",
+                    createdAt: new Date().toISOString(),
+                    content: { parts: lastMessage?.parts ?? [] },
+                };
+                resolveFinish(event);
+            },
+            onError: (e) => {
+                rejectFinish(e);
+                return e instanceof Error ? e.message : String(e);
+            },
+        })
+            .pipeThrough(new TransformStream({
+            async transform(chunk, controller) {
+                const contextId = typeof params.contextId === "string" && params.contextId.length > 0
+                    ? params.contextId
+                    : undefined;
+                if (contextId) {
+                    const mapped = mapAiSdkChunkToContextEvent({
+                        chunk,
+                        contextId,
+                        executionId: params.executionId,
+                        stepId: params.stepId,
+                        itemId: params.eventId,
+                        provider: mappedProvider,
+                        sequence: ++chunkSequence,
+                    });
+                    const persistedChunk = createContextStepStreamChunk({
+                        at: mapped.at,
+                        sequence: mapped.sequence,
+                        chunkType: mapped.chunkType,
+                        provider: mapped.provider,
+                        providerChunkType: mapped.providerChunkType,
+                        actionRef: mapped.actionRef,
+                        data: mapped.data && typeof mapped.data === "object"
+                            ? mapped.data
+                            : undefined,
+                        raw: mapped.raw && typeof mapped.raw === "object"
+                            ? mapped.raw
+                            : undefined,
+                    });
+                    if (contextStepStreamWriter) {
+                        await contextStepStreamWriter.write(encodeContextStepStreamChunk(persistedChunk));
+                    }
+                    controller.enqueue({
+                        type: "data-chunk.emitted",
+                        data: mapped,
+                    });
+                }
+                if (chunk.type === "finish")
+                    return;
+                controller.enqueue(chunk);
+            },
+        }));
+        if (params.writable) {
+            await uiStream.pipeTo(params.writable, { preventClose: true });
+        }
+        else {
+            const reader = uiStream.getReader();
+            try {
+                while (true) {
+                    const { done } = await reader.read();
+                    if (done)
+                        break;
+                }
+            }
+            finally {
+                reader.releaseLock();
+            }
+        }
+    }
+    finally {
+        contextStepStreamWriter?.releaseLock();
+    }
+    const assistantEvent = await finishPromise;
+    const finishedAtMs = Date.now();
+    const toolCalls = extractToolCallsFromParts(assistantEvent?.content?.parts);
+    const latencyMs = Math.max(0, finishedAtMs - startedAtMs);
+    let usage = undefined;
+    let providerMetadata = undefined;
+    try {
+        usage = result?.usage;
+        if (typeof usage?.then === "function")
+            usage = await usage;
+    }
+    catch {
+        usage = undefined;
+    }
+    try {
+        providerMetadata =
+            result?.providerMetadata ??
+                result?.experimental_providerMetadata ??
+                result?.response?.providerMetadata ??
+                undefined;
+    }
+    catch {
+        providerMetadata = undefined;
+    }
+    function toPlainJson(value) {
+        if (typeof value === "undefined")
+            return undefined;
+        try {
+            return JSON.parse(JSON.stringify(value));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    const usageJson = toPlainJson(usage);
+    const providerMetadataJson = toPlainJson(providerMetadata);
+    const provider = modelId.includes("/") ? modelId.split("/")[0] : providerMetadata?.provider;
+    const model = modelId.includes("/") ? modelId.split("/").slice(1).join("/") : providerMetadata?.model;
+    const promptTokens = Number(usage?.promptTokens ?? usage?.prompt_tokens ?? usage?.inputTokens ?? 0) || 0;
+    const completionTokens = Number(usage?.completionTokens ?? usage?.completion_tokens ?? usage?.outputTokens ?? 0) || 0;
+    const totalTokens = Number(usage?.totalTokens ?? usage?.total_tokens ?? 0) || (promptTokens + completionTokens);
+    const cachedPromptTokens = Number(usage?.promptTokensCached ??
+        usage?.cached_prompt_tokens ??
+        usage?.prompt_tokens_details?.cached_tokens ??
+        usage?.input_tokens_details?.cached_tokens ??
+        0) || 0;
+    const uncachedPromptTokens = Math.max(0, promptTokens - cachedPromptTokens);
+    const llm = promptTokens || completionTokens || cachedPromptTokens
+        ? {
+            provider,
+            model,
+            promptTokens,
+            promptTokensCached: cachedPromptTokens,
+            promptTokensUncached: uncachedPromptTokens,
+            completionTokens,
+            totalTokens,
+            latencyMs,
+            rawUsage: usageJson,
+            rawProviderMetadata: providerMetadataJson,
+        }
+        : {
+            provider,
+            model,
+            latencyMs,
+            rawUsage: usageJson,
+            rawProviderMetadata: providerMetadataJson,
+        };
+    try {
+        const runId = await resolveWorkflowRunId(params.env, params.executionId);
+        if (runId && llm) {
+            await writeContextTraceEvents({
+                env: params.env,
+                events: [
+                    {
+                        workflowRunId: runId,
+                        eventId: `context_llm:${String(params.executionId ?? "unknown")}:${String(params.stepId ?? params.eventId)}:${String(params.iteration ?? 0)}`,
+                        eventKind: "context.llm",
+                        eventAt: new Date().toISOString(),
+                        contextId: params.contextId,
+                        executionId: params.executionId,
+                        stepId: params.stepId,
+                        aiProvider: typeof llm.provider === "string" ? llm.provider : undefined,
+                        aiModel: typeof llm.model === "string" ? llm.model : undefined,
+                        promptTokens: Number.isFinite(Number(llm.promptTokens))
+                            ? Number(llm.promptTokens)
+                            : undefined,
+                        promptTokensCached: Number.isFinite(Number(llm.promptTokensCached))
+                            ? Number(llm.promptTokensCached)
+                            : undefined,
+                        promptTokensUncached: Number.isFinite(Number(llm.promptTokensUncached))
+                            ? Number(llm.promptTokensUncached)
+                            : undefined,
+                        completionTokens: Number.isFinite(Number(llm.completionTokens))
+                            ? Number(llm.completionTokens)
+                            : undefined,
+                        totalTokens: Number.isFinite(Number(llm.totalTokens))
+                            ? Number(llm.totalTokens)
+                            : undefined,
+                        latencyMs: Number.isFinite(Number(llm.latencyMs))
+                            ? Number(llm.latencyMs)
+                            : undefined,
+                        payload: {
+                            provider: llm.provider,
+                            model: llm.model,
+                            usage: llm.rawUsage,
+                            providerMetadata: llm.rawProviderMetadata,
+                            iteration: params.iteration,
+                        },
+                    },
+                ],
+            });
+        }
+    }
+    catch {
+        // tracing must not break reaction
+    }
+    return { assistantEvent, toolCalls, messagesForModel, llm };
+}

package/dist/reactors/scripted.reactor.d.ts

@@ -0,0 +1,17 @@
+import type { ModelMessage } from "ai";
+import type { ContextEnvironment } from "../context.config.js";
+import type { ContextItem } from "../context.store.js";
+import type { ContextReactionLLM, ContextActionRequest, ContextReactor, ContextReactorParams } from "./types.js";
+type ScriptedReactionPayload = {
+    assistantEvent?: Partial<ContextItem>;
+    actionRequests?: ContextActionRequest[];
+    messagesForModel?: ModelMessage[];
+    llm?: ContextReactionLLM;
+};
+export type ScriptedReactorStep<Context = unknown, Env extends ContextEnvironment = ContextEnvironment> = ScriptedReactionPayload | ((params: ContextReactorParams<Context, Env>) => Promise<ScriptedReactionPayload> | ScriptedReactionPayload);
+export type CreateScriptedReactorOptions<Context = unknown, Env extends ContextEnvironment = ContextEnvironment> = {
+    steps: ScriptedReactorStep<Context, Env>[];
+    repeatLast?: boolean;
+};
+export declare function createScriptedReactor<Context = unknown, Env extends ContextEnvironment = ContextEnvironment>(options: CreateScriptedReactorOptions<Context, Env>): ContextReactor<Context, Env>;
+export {};

package/dist/reactors/scripted.reactor.js

@@ -0,0 +1,51 @@
+import { OUTPUT_ITEM_TYPE } from "../context.events.js";
+function normalizeScriptedAssistantEvent(params, assistantEvent) {
+    const fallback = {
+        id: params.eventId,
+        type: OUTPUT_ITEM_TYPE,
+        channel: params.triggerEvent.channel,
+        createdAt: new Date().toISOString(),
+        content: { parts: [] },
+    };
+    const mergedContent = {
+        ...fallback.content,
+        ...(assistantEvent?.content ?? {}),
+    };
+    return {
+        ...fallback,
+        ...assistantEvent,
+        id: assistantEvent?.id ?? fallback.id,
+        createdAt: assistantEvent?.createdAt ?? fallback.createdAt,
+        content: mergedContent,
+    };
+}
+export function createScriptedReactor(options) {
+    const steps = Array.isArray(options.steps) ? options.steps : [];
+    if (steps.length === 0) {
+        throw new Error("createScriptedReactor: options.steps must contain at least one step.");
+    }
+    let index = 0;
+    return async (params) => {
+        const hasCurrentStep = index < steps.length;
+        if (!hasCurrentStep && !options.repeatLast) {
+            throw new Error(`createScriptedReactor: no scripted step available at index ${index}. ` +
+                `Provided steps=${steps.length}. Enable repeatLast to reuse the final step.`);
+        }
+        const stepIndex = hasCurrentStep ? index : steps.length - 1;
+        const scriptedStep = steps[stepIndex];
+        if (hasCurrentStep) {
+            index += 1;
+        }
+        const payload = typeof scriptedStep === "function"
+            ? await scriptedStep(params)
+            : scriptedStep;
+        return {
+            assistantEvent: normalizeScriptedAssistantEvent(params, payload.assistantEvent),
+            actionRequests: Array.isArray(payload.actionRequests) ? payload.actionRequests : [],
+            messagesForModel: Array.isArray(payload.messagesForModel)
+                ? payload.messagesForModel
+                : [],
+            llm: payload.llm,
+        };
+    };
+}

package/dist/reactors/types.d.ts

@@ -0,0 +1,52 @@
+import type { ModelMessage, UIMessageChunk } from "ai";
+import type { ContextEnvironment } from "../context.config.js";
+import type { ContextModelInit } from "../context.engine.js";
+import type { ContextIdentifier, StoredContext, ContextItem } from "../context.store.js";
+import type { ContextSkillPackage } from "../context.skill.js";
+import type { SerializableToolForModel } from "../tools-to-model-tools.js";
+export type ContextActionRequest = {
+    actionRef: string;
+    actionName: string;
+    input: unknown;
+};
+export type ContextReactionLLM = {
+    provider?: string;
+    model?: string;
+    promptTokens?: number;
+    promptTokensCached?: number;
+    promptTokensUncached?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    latencyMs?: number;
+    rawUsage?: unknown;
+    rawProviderMetadata?: unknown;
+};
+export type ContextReactionResult = {
+    assistantEvent: ContextItem;
+    actionRequests: ContextActionRequest[];
+    messagesForModel: ModelMessage[];
+    llm?: ContextReactionLLM;
+};
+export type ContextReactorParams<Context = unknown, Env extends ContextEnvironment = ContextEnvironment> = {
+    env: Env;
+    context: StoredContext<Context>;
+    contextIdentifier: ContextIdentifier;
+    triggerEvent: ContextItem;
+    model: ContextModelInit;
+    systemPrompt: string;
+    actions: Record<string, unknown>;
+    toolsForModel: Record<string, SerializableToolForModel>;
+    skills: ContextSkillPackage[];
+    eventId: string;
+    executionId: string;
+    contextId: string;
+    stepId: string;
+    iteration: number;
+    maxModelSteps: number;
+    sendStart: boolean;
+    silent: boolean;
+    contextStepStream?: WritableStream<string>;
+    writable?: WritableStream<UIMessageChunk>;
+    persistReactionParts?: (parts: any[]) => Promise<void>;
+};
+export type ContextReactor<Context = unknown, Env extends ContextEnvironment = ContextEnvironment> = (params: ContextReactorParams<Context, Env>) => Promise<ContextReactionResult>;

package/dist/reactors/types.js

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

package/dist/runtime.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime-only entrypoint for @ekairos/events.
+ *
+ * This file intentionally exports the "wiring" pieces that connect durable steps to a concrete
+ * store runtime (Instant/Postgres/etc).
+ *
+ * IMPORTANT:
+ * - Do NOT import this entrypoint from client/browser code.
+ * - Keep `@ekairos/events` main entrypoint safe to import from schema/domain modules.
+ */
+export { getContextRuntime, } from "./runtime.step.js";
+export { createContextStepStreamClientId, createPersistedContextStepStream, readPersistedContextStepStream, resolveContextExecutionStreamPointer, waitForContextExecutionStreamPointer, } from "./steps/stream.steps.js";
+export type { ContextEnvironment, ContextRuntime } from "./context.config.js";
+export { registerContextEnv, getContextEnv } from "./env.js";
+export { configureContextDurableWorkflow } from "./context.durable.js";
+export type RegistrableContext = {
+    key?: string;
+    register: () => void;
+};

package/dist/runtime.js

@@ -0,0 +1,26 @@
+/**
+ * Runtime-only entrypoint for @ekairos/events.
+ *
+ * This file intentionally exports the "wiring" pieces that connect durable steps to a concrete
+ * store runtime (Instant/Postgres/etc).
+ *
+ * IMPORTANT:
+ * - Do NOT import this entrypoint from client/browser code.
+ * - Keep `@ekairos/events` main entrypoint safe to import from schema/domain modules.
+ */
+if (typeof globalThis.Event === "undefined") {
+    class NodeEvent {
+        constructor(type, init) {
+            this.type = type;
+            if (init && typeof init === "object") {
+                Object.assign(this, init);
+            }
+        }
+    }
+    ;
+    globalThis.Event = NodeEvent;
+}
+export { getContextRuntime, } from "./runtime.step.js";
+export { createContextStepStreamClientId, createPersistedContextStepStream, readPersistedContextStepStream, resolveContextExecutionStreamPointer, waitForContextExecutionStreamPointer, } from "./steps/stream.steps.js";
+export { registerContextEnv, getContextEnv } from "./env.js";
+export { configureContextDurableWorkflow } from "./context.durable.js";

package/dist/runtime.step.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Internal helper to resolve Context runtime from within workflow steps.
+ *
+ * Why dynamic import?
+ * - Some bundlers (notably Turbopack step bundles) can drop/hoist static imports in "use-step" modules.
+ * - Keeping `resolveRuntime` behind a dynamic import makes symbol resolution local to step execution.
+ */
+import type { ContextEnvironment, ContextRuntime } from "./context.config.js";
+export declare function getContextRuntime(env: ContextEnvironment): Promise<ContextRuntime>;

package/dist/runtime.step.js

@@ -0,0 +1,7 @@
+import { coerceContextRuntime } from "./context.config.js";
+import { eventsDomain } from "./schema.js";
+export async function getContextRuntime(env) {
+    const { resolveRuntime } = await import("@ekairos/domain/runtime-step");
+    const resolved = await resolveRuntime(eventsDomain, env);
+    return await coerceContextRuntime(resolved);
+}

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+import { type DomainSchemaResult } from "@ekairos/domain";
+export declare const eventsDomain: DomainSchemaResult;