@ekairos/events 1.22.4-beta.development.0

package/dist/steps/store.steps.js

@@ -0,0 +1,595 @@
+import { OUTPUT_ITEM_TYPE, WEB_CHANNEL } from "../context.events.js";
+import { writeContextTraceEvents } from "./trace.steps.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken, } from "../context.hooks.js";
+async function maybeWriteTraceEvents(env, traceEvents) {
+    if (!traceEvents?.length)
+        return;
+    try {
+        await writeContextTraceEvents({ env, events: traceEvents });
+    }
+    catch {
+        if (process.env.PLAYWRIGHT_TEST === "1") {
+            // eslint-disable-next-line no-console
+            console.warn("[context/trace] emit failed");
+        }
+    }
+}
+async function readWorkflowMetadata() {
+    try {
+        const { getWorkflowMetadata } = await import("workflow");
+        return getWorkflowMetadata?.() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveWorkflowRunId(params) {
+    let runId = "";
+    const meta = await readWorkflowMetadata();
+    if (meta && meta.workflowRunId !== undefined && meta.workflowRunId !== null) {
+        runId = String(meta.workflowRunId);
+    }
+    if (!runId && params.executionId && params.db) {
+        try {
+            const q = await params.db.query({
+                event_executions: {
+                    $: { where: { id: String(params.executionId) }, limit: 1 },
+                },
+            });
+            const row = q?.event_executions?.[0];
+            if (row?.workflowRunId) {
+                runId = String(row.workflowRunId);
+            }
+        }
+        catch {
+            // ignore
+        }
+    }
+    return { runId: runId || undefined, meta };
+}
+function inferDirection(item) {
+    const type = typeof item?.type === "string" ? String(item.type) : "";
+    if (type === "input")
+        return "inbound";
+    if (type === "output")
+        return "outbound";
+    return undefined;
+}
+function shouldDebugContextStoreSteps() {
+    return process.env.EKAIROS_CONTEXT_DEBUG === "1";
+}
+function summarizeStepError(error) {
+    const err = error;
+    return {
+        name: err?.name,
+        message: err?.message,
+        code: err?.code,
+        status: err?.status ?? err?.statusCode,
+        details: err?.details ?? err?.body ?? err?.response ?? err?.data,
+        stack: typeof err?.stack === "string"
+            ? err.stack.slice(0, 1500)
+            : undefined,
+    };
+}
+function summarizeContextIdentifierForLog(identifier) {
+    return {
+        id: identifier && typeof identifier.id === "string"
+            ? String(identifier.id)
+            : undefined,
+        key: identifier && typeof identifier.key === "string"
+            ? String(identifier.key)
+            : undefined,
+    };
+}
+function logStepDebug(message, payload) {
+    if (!shouldDebugContextStoreSteps())
+        return;
+    // eslint-disable-next-line no-console
+    console.error(`[context][store.steps] ${message}`, payload);
+}
+/**
+ * Initializes/ensures the story context exists.
+ *
+ * This is the "context init" boundary for the story engine.
+ */
+export async function initializeContext(env, contextIdentifier, opts) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(env);
+    const { store, db } = runtime;
+    // Detect creation explicitly so the engine can run onContextCreated hooks.
+    let result;
+    if (!contextIdentifier) {
+        const context = await store.getOrCreateContext(null);
+        result = { context, isNew: true };
+    }
+    else {
+        const existing = await store.getContext(contextIdentifier);
+        if (existing) {
+            result = { context: existing, isNew: false };
+        }
+        else {
+            const created = await store.getOrCreateContext(contextIdentifier);
+            result = { context: created, isNew: true };
+        }
+    }
+    const { runId } = await resolveWorkflowRunId({ env, db });
+    if (runId) {
+        await maybeWriteTraceEvents(env, [
+            {
+                workflowRunId: runId,
+                eventId: `context_entity:${String(result.context.id)}`,
+                eventKind: "context.lifecycle",
+                eventAt: new Date().toISOString(),
+                contextId: String(result.context.id),
+                contextKey: result.context.key ?? undefined,
+                payload: {
+                    ...result.context,
+                    action: result.isNew ? "created" : "updated",
+                },
+            },
+        ]);
+    }
+    return result;
+}
+export async function updateContextContent(env, contextIdentifier, content) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(env);
+    return await store.updateContextContent(contextIdentifier, content);
+}
+export async function updateContextStatus(env, contextIdentifier, status) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(env);
+    await store.updateContextStatus(contextIdentifier, status);
+}
+export async function saveTriggerItem(env, contextIdentifier, event) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(env);
+    const saved = await store.saveItem(contextIdentifier, event);
+    return saved;
+}
+export async function saveTriggerAndCreateExecution(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const { store, db } = runtime;
+    logStepDebug("saveTriggerAndCreateExecution:start", {
+        contextIdentifier: summarizeContextIdentifierForLog(params.contextIdentifier),
+        triggerEventId: params.triggerEvent?.id,
+        triggerEventType: params.triggerEvent?.type,
+        triggerEventChannel: params.triggerEvent?.channel,
+        triggerEventCreatedAt: params.triggerEvent?.createdAt,
+    });
+    let saved;
+    try {
+        saved = await store.saveItem(params.contextIdentifier, params.triggerEvent);
+    }
+    catch (error) {
+        logStepDebug("saveTriggerAndCreateExecution:saveItem:error", {
+            contextIdentifier: summarizeContextIdentifierForLog(params.contextIdentifier),
+            triggerEventId: params.triggerEvent?.id,
+            error: summarizeStepError(error),
+        });
+        throw error;
+    }
+    const uuid = globalThis.crypto?.randomUUID?.();
+    const reactionEventId = typeof uuid === "string"
+        ? uuid
+        : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const reactionShell = {
+        id: reactionEventId,
+        type: OUTPUT_ITEM_TYPE,
+        channel: typeof params.triggerEvent?.channel === "string"
+            ? params.triggerEvent.channel
+            : WEB_CHANNEL,
+        createdAt: new Date().toISOString(),
+        status: "pending",
+        content: {
+            parts: [],
+        },
+    };
+    let savedReaction;
+    try {
+        savedReaction = await store.saveItem(params.contextIdentifier, reactionShell);
+        savedReaction = await store.updateItem(savedReaction.id, {
+            ...savedReaction,
+            status: "pending",
+        });
+    }
+    catch (error) {
+        logStepDebug("saveTriggerAndCreateExecution:saveReaction:error", {
+            contextIdentifier: summarizeContextIdentifierForLog(params.contextIdentifier),
+            reactionEventId,
+            error: summarizeStepError(error),
+        });
+        throw error;
+    }
+    let execution;
+    try {
+        execution = await store.createExecution(params.contextIdentifier, saved.id, savedReaction.id);
+    }
+    catch (error) {
+        logStepDebug("saveTriggerAndCreateExecution:createExecution:error", {
+            contextIdentifier: summarizeContextIdentifierForLog(params.contextIdentifier),
+            triggerEventId: saved.id,
+            reactionEventId: savedReaction.id,
+            error: summarizeStepError(error),
+        });
+        throw error;
+    }
+    try {
+        await store.linkItemToExecution({
+            itemId: saved.id,
+            executionId: execution.id,
+        });
+        await store.linkItemToExecution({
+            itemId: savedReaction.id,
+            executionId: execution.id,
+        });
+    }
+    catch (error) {
+        logStepDebug("saveTriggerAndCreateExecution:linkItemsToExecution:error", {
+            contextIdentifier: summarizeContextIdentifierForLog(params.contextIdentifier),
+            triggerEventId: saved.id,
+            reactionEventId: savedReaction.id,
+            executionId: execution.id,
+            error: summarizeStepError(error),
+        });
+        throw error;
+    }
+    const { runId, meta } = await resolveWorkflowRunId({
+        env: params.env,
+        db,
+        executionId: execution.id,
+    });
+    if (runId && db) {
+        try {
+            await db.transact([
+                db.tx.event_executions[execution.id].update({
+                    workflowRunId: runId,
+                    updatedAt: new Date(),
+                }),
+            ]);
+        }
+        catch {
+            // ignore
+        }
+    }
+    if (runId) {
+        let contextKey;
+        let contextId;
+        try {
+            const ctx = await store.getContext(params.contextIdentifier);
+            contextKey = ctx?.key ?? undefined;
+            contextId = ctx?.id ? String(ctx.id) : undefined;
+        }
+        catch {
+            // ignore
+        }
+        const events = [
+            {
+                workflowRunId: runId,
+                eventId: `workflow_run:${String(runId)}`,
+                eventKind: "workflow.run",
+                eventAt: new Date().toISOString(),
+                payload: meta ?? null,
+            },
+            {
+                workflowRunId: runId,
+                eventId: `context_run:${String(execution.id)}`,
+                eventKind: "context.run",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(execution.id),
+                payload: {
+                    contextKey: contextKey ?? null,
+                    contextId: contextId ?? null,
+                    triggerEventId: saved.id,
+                    reactionEventId: savedReaction.id,
+                    workflowMeta: meta ?? null,
+                },
+            },
+            {
+                workflowRunId: runId,
+                eventId: `context_execution:${String(execution.id)}`,
+                eventKind: "context.execution",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(execution.id),
+                payload: {
+                    status: "started",
+                },
+            },
+            {
+                workflowRunId: runId,
+                eventId: `context_item:${String(saved.id)}`,
+                eventKind: "context.item",
+                eventAt: new Date().toISOString(),
+                contextId,
+                contextEventId: String(saved.id),
+                payload: {
+                    ...saved,
+                    direction: "inbound",
+                },
+            },
+            {
+                workflowRunId: runId,
+                eventId: `context_item:${String(savedReaction.id)}`,
+                eventKind: "context.item",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(execution.id),
+                contextEventId: String(savedReaction.id),
+                payload: {
+                    ...savedReaction,
+                    direction: "outbound",
+                },
+            },
+        ];
+        await maybeWriteTraceEvents(params.env, events);
+    }
+    return {
+        triggerEvent: saved,
+        reactionEvent: savedReaction,
+        execution: {
+            id: execution.id,
+            status: "executing",
+        },
+    };
+}
+export async function saveReactionItem(env, contextIdentifier, event, opts) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(env);
+    const { store, db } = runtime;
+    const saved = await store.saveItem(contextIdentifier, event);
+    if (opts?.executionId) {
+        await store.linkItemToExecution({
+            itemId: saved.id,
+            executionId: opts.executionId,
+        });
+    }
+    const contextId = opts?.contextId ??
+        (typeof contextIdentifier?.id === "string"
+            ? String(contextIdentifier.id)
+            : undefined);
+    const { runId, meta } = await resolveWorkflowRunId({
+        env,
+        db,
+        executionId: opts?.executionId,
+    });
+    if (runId) {
+        const events = [
+            {
+                workflowRunId: runId,
+                eventId: `context_item:${String(saved.id)}`,
+                eventKind: "context.item",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: opts?.executionId,
+                contextEventId: String(saved.id),
+                payload: {
+                    ...saved,
+                    direction: "outbound",
+                },
+            },
+        ];
+        if (opts?.executionId && opts.reviewRequests?.length) {
+            const resumeHookUrl = getClientResumeHookUrl();
+            const workflowUrl = meta && typeof meta.url === "string" && meta.url.trim()
+                ? String(meta.url)
+                : undefined;
+            for (const rr of opts.reviewRequests) {
+                const toolCallId = String(rr.toolCallId);
+                events.push({
+                    workflowRunId: runId,
+                    eventId: `context_review:${String(opts.executionId)}:${toolCallId}`,
+                    eventKind: "context.review",
+                    eventAt: new Date().toISOString(),
+                    contextId,
+                    executionId: String(opts.executionId),
+                    toolCallId,
+                    payload: {
+                        status: "in_review",
+                        toolName: rr.toolName ?? "",
+                        hookToken: toolApprovalHookToken({
+                            executionId: String(opts.executionId),
+                            toolCallId,
+                        }),
+                        webhookToken: toolApprovalWebhookToken({
+                            executionId: String(opts.executionId),
+                            toolCallId,
+                        }),
+                        resumeHookUrl,
+                        workflowUrl,
+                    },
+                });
+            }
+        }
+        await maybeWriteTraceEvents(env, events);
+    }
+    return saved;
+}
+export async function updateItem(env, eventId, event, opts) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(env);
+    const { store, db } = runtime;
+    const saved = await store.updateItem(eventId, event);
+    const { runId } = await resolveWorkflowRunId({
+        env,
+        db,
+        executionId: opts?.executionId,
+    });
+    if (runId) {
+        await maybeWriteTraceEvents(env, [
+            {
+                workflowRunId: runId,
+                eventId: `context_item:${String(saved.id)}`,
+                eventKind: "context.item",
+                eventAt: new Date().toISOString(),
+                contextId: opts?.contextId,
+                executionId: opts?.executionId,
+                contextEventId: String(saved.id),
+                payload: {
+                    ...saved,
+                    direction: inferDirection(saved),
+                },
+            },
+        ]);
+    }
+    return saved;
+}
+export async function createExecution(env, contextIdentifier, triggerEventId, reactionEventId) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(env);
+    return await store.createExecution(contextIdentifier, triggerEventId, reactionEventId);
+}
+export async function createReactionItem(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(params.env);
+    // Generate a new reaction event id inside the step boundary.
+    const uuid = globalThis.crypto?.randomUUID?.();
+    const reactionEventId = typeof uuid === "string"
+        ? uuid
+        : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    const execution = await store.createExecution(params.contextIdentifier, params.triggerEventId, reactionEventId);
+    return { reactionEventId, executionId: execution.id };
+}
+export async function completeExecution(env, contextIdentifier, executionId, status) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(env);
+    const { store, db } = runtime;
+    await store.completeExecution(contextIdentifier, executionId, status);
+    const contextId = typeof contextIdentifier?.id === "string"
+        ? String(contextIdentifier.id)
+        : undefined;
+    const { runId } = await resolveWorkflowRunId({
+        env,
+        db,
+        executionId,
+    });
+    if (runId) {
+        await maybeWriteTraceEvents(env, [
+            {
+                workflowRunId: runId,
+                eventId: `context_execution:${String(executionId)}:${status}`,
+                eventKind: "context.execution",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(executionId),
+                payload: {
+                    status,
+                },
+            },
+        ]);
+    }
+}
+export async function updateExecutionWorkflowRun(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const db = runtime?.db;
+    if (db) {
+        await db.transact([
+            db.tx.event_executions[params.executionId].update({
+                workflowRunId: params.workflowRunId,
+                updatedAt: new Date(),
+            }),
+        ]);
+    }
+}
+export async function createContextStep(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(params.env);
+    const res = await store.createStep({
+        executionId: params.executionId,
+        iteration: params.iteration,
+    });
+    return { stepId: res.id };
+}
+export async function updateContextStep(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const { store, db } = runtime;
+    await store.updateStep(params.stepId, {
+        ...params.patch,
+        updatedAt: new Date(),
+    });
+    const { runId } = await resolveWorkflowRunId({
+        env: params.env,
+        db,
+        executionId: params.executionId,
+    });
+    if (runId) {
+        await maybeWriteTraceEvents(params.env, [
+            {
+                workflowRunId: runId,
+                eventId: `context_step:${String(params.stepId)}`,
+                eventKind: "context.step",
+                eventAt: new Date().toISOString(),
+                contextId: params.contextId,
+                executionId: params.executionId,
+                stepId: String(params.stepId),
+                payload: {
+                    status: params.patch.status,
+                    kind: params.patch.kind,
+                    actionName: params.patch.actionName,
+                    actionInput: params.patch.actionInput,
+                    actionOutput: params.patch.actionOutput,
+                    actionError: params.patch.actionError,
+                    iteration: params.iteration,
+                    actionRequests: params.patch.actionRequests,
+                    actionResults: params.patch.actionResults,
+                    continueLoop: params.patch.continueLoop,
+                    errorText: params.patch.errorText,
+                },
+            },
+        ]);
+    }
+}
+export async function linkItemToExecutionStep(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const { store } = await getContextRuntime(params.env);
+    await store.linkItemToExecution({ itemId: params.itemId, executionId: params.executionId });
+}
+export async function saveContextPartsStep(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const { store, db } = runtime;
+    await store.saveStepParts({ stepId: params.stepId, parts: params.parts });
+    const { runId } = await resolveWorkflowRunId({
+        env: params.env,
+        db,
+        executionId: params.executionId,
+    });
+    if (runId && params.parts?.length) {
+        const events = [];
+        for (let idx = 0; idx < params.parts.length; idx += 1) {
+            const part = params.parts[idx];
+            events.push({
+                workflowRunId: runId,
+                eventId: `context_part:${String(params.stepId)}:${idx}`,
+                eventKind: "context.part",
+                eventAt: new Date().toISOString(),
+                contextId: params.contextId,
+                executionId: params.executionId,
+                stepId: String(params.stepId),
+                partKey: `${String(params.stepId)}:${idx}`,
+                partIdx: idx,
+                payload: part,
+            });
+        }
+        await maybeWriteTraceEvents(params.env, events);
+    }
+}

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

@@ -0,0 +1,86 @@
+import type { UIMessageChunk } from "ai";
+import type { ContextEnvironment } from "../context.config.js";
+import { type ContextStepStreamChunk } from "../context.step-stream.js";
+import type { ContextStreamEvent } from "../context.stream.js";
+export declare function writeContextEvents(params: {
+    events: ContextStreamEvent[];
+    writable?: WritableStream<UIMessageChunk>;
+}): Promise<void>;
+export declare function closeContextStream(params: {
+    preventClose?: boolean;
+    sendFinish?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
+}): Promise<void>;
+export declare function createContextStepStreamClientId(stepId: string): string;
+export type PersistedContextStepStreamSession = {
+    stream: WritableStream<string>;
+    streamId: string;
+    clientId: string;
+    executionId: string;
+    stepId: string;
+};
+export declare function createPersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    executionId: string;
+    stepId: string;
+    clientId?: string;
+}): Promise<PersistedContextStepStreamSession>;
+export declare function closePersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    session: PersistedContextStepStreamSession;
+}): Promise<void>;
+export declare function abortPersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    session: PersistedContextStepStreamSession;
+    reason?: string | null;
+}): Promise<void>;
+export declare function readPersistedContextStepStream(params: {
+    db: any;
+    clientId?: string;
+    streamId?: string;
+    byteOffset?: number;
+    onChunk?: (chunk: ContextStepStreamChunk) => Promise<void> | void;
+}): Promise<{
+    chunks: ContextStepStreamChunk[];
+    byteOffset: number;
+}>;
+export declare function resolveContextExecutionStreamPointer(params: {
+    db: any;
+    contextId: string;
+}): Promise<{
+    executionId: string;
+    status: string | null;
+    source: "active";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "last";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "none";
+    clientId: null;
+    streamId: null;
+} | null>;
+export declare function waitForContextExecutionStreamPointer(params: {
+    db: any;
+    contextId: string;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    executionId: string;
+    status: string | null;
+    source: "active";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "last";
+    clientId: string | null;
+    streamId: string | null;
+} | null>;