@ekairos/thread 1.21.88-beta.0

package/dist/steps/store.steps.js

@@ -0,0 +1,512 @@
+import { writeThreadTraceEvents } from "./trace.steps.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken, } from "../thread.hooks.js";
+async function maybeWriteTraceEvents(env, traceEvents) {
+    if (!traceEvents?.length)
+        return;
+    try {
+        await writeThreadTraceEvents({ env, events: traceEvents });
+    }
+    catch {
+        if (process.env.PLAYWRIGHT_TEST === "1") {
+            // eslint-disable-next-line no-console
+            console.warn("[thread/trace] emit failed");
+        }
+    }
+}
+async function readWorkflowMetadata() {
+    try {
+        const { getWorkflowMetadata } = await import("workflow");
+        return getWorkflowMetadata?.() ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function parseRunIdFromTriggerId(triggerEventId) {
+    if (typeof triggerEventId !== "string")
+        return undefined;
+    if (!triggerEventId.startsWith("e2e-trigger:"))
+        return undefined;
+    const parsed = triggerEventId.slice("e2e-trigger:".length).trim();
+    return parsed || undefined;
+}
+async function resolveWorkflowRunId(params) {
+    const meta = await readWorkflowMetadata();
+    let runId = meta && meta.workflowRunId !== undefined && meta.workflowRunId !== null
+        ? String(meta.workflowRunId)
+        : "";
+    if (!runId) {
+        const envRunId = params.env?.workflowRunId;
+        if (typeof envRunId === "string" && envRunId.trim()) {
+            runId = envRunId.trim();
+        }
+    }
+    if (!runId && params.triggerEventId) {
+        const parsed = parseRunIdFromTriggerId(params.triggerEventId);
+        if (parsed)
+            runId = parsed;
+    }
+    if (!runId && params.executionId && params.db) {
+        try {
+            const q = await params.db.query({
+                thread_executions: {
+                    $: { where: { id: String(params.executionId) }, limit: 1 },
+                },
+            });
+            const row = q?.thread_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" ? item.type : "";
+    if (type.startsWith("output") || type.startsWith("tool") || type.startsWith("assistant")) {
+        return "outbound";
+    }
+    if (type.startsWith("input") || type.startsWith("user")) {
+        return "inbound";
+    }
+    return undefined;
+}
+/**
+ * Initializes/ensures the story context exists and emits a single `data-context-id` chunk.
+ *
+ * This is the "context init" boundary for the story engine.
+ */
+export async function initializeContext(env, contextIdentifier, opts) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(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 };
+        }
+    }
+    // If we're running in a non-streaming context (e.g. tests or headless usage),
+    // we skip writing stream chunks entirely.
+    if (!opts?.silent && opts?.writable) {
+        const writer = opts.writable.getWriter();
+        try {
+            await writer.write({
+                type: "data-context-id",
+                id: String(result.context.id),
+                data: { contextId: String(result.context.id) },
+            });
+        }
+        finally {
+            writer.releaseLock();
+        }
+    }
+    const { runId } = await resolveWorkflowRunId({ env, db });
+    if (runId) {
+        await maybeWriteTraceEvents(env, [
+            {
+                workflowRunId: runId,
+                eventId: `thread_context:${String(result.context.id)}`,
+                eventKind: "thread.context",
+                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 { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(env);
+    return await store.updateContextContent(contextIdentifier, content);
+}
+export async function updateContextStatus(env, contextIdentifier, status) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(env);
+    await store.updateContextStatus(contextIdentifier, status);
+}
+export async function saveTriggerItem(env, contextIdentifier, event) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(env);
+    const saved = await store.saveItem(contextIdentifier, event);
+    return saved;
+}
+export async function emitContextIdChunk(params) {
+    "use step";
+    if (!params.writable)
+        return;
+    const writer = params.writable.getWriter();
+    try {
+        await writer.write({
+            type: "data-context-id",
+            id: String(params.contextId),
+            data: { contextId: String(params.contextId) },
+        });
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function saveTriggerAndCreateExecution(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(params.env);
+    const { store, db } = runtime;
+    const saved = await store.saveItem(params.contextIdentifier, params.triggerEvent);
+    const uuid = globalThis.crypto?.randomUUID?.();
+    const reactionEventId = typeof uuid === "string"
+        ? uuid
+        : `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+    await store.updateContextStatus(params.contextIdentifier, "streaming");
+    const execution = await store.createExecution(params.contextIdentifier, saved.id, reactionEventId);
+    const { runId, meta } = await resolveWorkflowRunId({
+        env: params.env,
+        db,
+        triggerEventId: saved.id,
+        executionId: execution.id,
+    });
+    if (runId && db) {
+        try {
+            await db.transact([
+                db.tx.thread_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: `thread_run:${String(execution.id)}`,
+                eventKind: "thread.run",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(execution.id),
+                payload: {
+                    contextKey: contextKey ?? null,
+                    contextId: contextId ?? null,
+                    triggerEventId: saved.id,
+                    reactionEventId,
+                    workflowMeta: meta ?? null,
+                },
+            },
+            {
+                workflowRunId: runId,
+                eventId: `thread_execution:${String(execution.id)}`,
+                eventKind: "thread.execution",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(execution.id),
+                payload: {
+                    status: "started",
+                },
+            },
+            {
+                workflowRunId: runId,
+                eventId: `thread_item:${String(saved.id)}`,
+                eventKind: "thread.item",
+                eventAt: new Date().toISOString(),
+                contextId,
+                contextEventId: String(saved.id),
+                payload: {
+                    ...saved,
+                    direction: "inbound",
+                },
+            },
+        ];
+        await maybeWriteTraceEvents(params.env, events);
+    }
+    return {
+        triggerEvent: saved,
+        triggerEventId: saved.id,
+        reactionEventId,
+        executionId: execution.id,
+    };
+}
+export async function saveReactionItem(env, contextIdentifier, event, opts) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(env);
+    const { store, db } = runtime;
+    const saved = await store.saveItem(contextIdentifier, event);
+    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: `thread_item:${String(saved.id)}`,
+                eventKind: "thread.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: `thread_review:${String(opts.executionId)}:${toolCallId}`,
+                    eventKind: "thread.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 { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(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: `thread_item:${String(saved.id)}`,
+                eventKind: "thread.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 { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(env);
+    return await store.createExecution(contextIdentifier, triggerEventId, reactionEventId);
+}
+export async function createReactionItem(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(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)}`;
+    await store.updateContextStatus(params.contextIdentifier, "streaming");
+    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 { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(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: `thread_execution:${String(executionId)}:${status}`,
+                eventKind: "thread.execution",
+                eventAt: new Date().toISOString(),
+                contextId,
+                executionId: String(executionId),
+                payload: {
+                    status,
+                },
+            },
+        ]);
+    }
+}
+export async function updateExecutionWorkflowRun(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(params.env);
+    const db = runtime?.db;
+    if (db) {
+        await db.transact([
+            db.tx.thread_executions[params.executionId].update({
+                workflowRunId: params.workflowRunId,
+                updatedAt: new Date(),
+            }),
+        ]);
+    }
+}
+export async function createThreadStep(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(params.env);
+    const res = await store.createStep({
+        executionId: params.executionId,
+        iteration: params.iteration,
+    });
+    return { stepId: res.id, eventId: res.eventId };
+}
+export async function updateThreadStep(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(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: `thread_step:${String(params.stepId)}`,
+                eventKind: "thread.step",
+                eventAt: new Date().toISOString(),
+                contextId: params.contextId,
+                executionId: params.executionId,
+                stepId: String(params.stepId),
+                payload: {
+                    status: params.patch.status,
+                    iteration: params.iteration,
+                    toolCalls: params.patch.toolCalls,
+                    toolExecutionResults: params.patch.toolExecutionResults,
+                    continueLoop: params.patch.continueLoop,
+                    errorText: params.patch.errorText,
+                },
+            },
+        ]);
+    }
+}
+export async function linkItemToExecutionStep(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const { store } = await getThreadRuntime(params.env);
+    await store.linkItemToExecution({ itemId: params.itemId, executionId: params.executionId });
+}
+export async function saveThreadPartsStep(params) {
+    "use step";
+    const { getThreadRuntime } = await import("@ekairos/thread/runtime");
+    const runtime = await getThreadRuntime(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: `thread_part:${String(params.stepId)}:${idx}`,
+                eventKind: "thread.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,41 @@
+import type { UIMessageChunk } from "ai";
+export declare function writeContextSubstate(params: {
+    /**
+     * Ephemeral substate key for the UI (thread engine internal state).
+     *
+     * - Provide a string key like "actions" to set it
+     * - Provide null to clear it
+     */
+    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 writeThreadPing(params: {
+    /**
+     * Simple ping event to validate that the workflow stream is alive.
+     * This is intentionally generic so clients can ignore it safely.
+     */
+    label?: string;
+    writable?: WritableStream<UIMessageChunk>;
+}): Promise<void>;
+export declare function writeToolOutputs(params: {
+    results: Array<{
+        toolCallId: string;
+        success: true;
+        output: unknown;
+    } | {
+        toolCallId: string;
+        success: false;
+        errorText: string;
+    }>;
+    writable?: WritableStream<UIMessageChunk>;
+}): Promise<void>;
+export declare function closeThreadStream(params: {
+    preventClose?: boolean;
+    sendFinish?: boolean;
+    writable?: WritableStream<UIMessageChunk>;
+}): Promise<void>;

package/dist/steps/stream.steps.js

@@ -0,0 +1,99 @@
+export async function writeContextSubstate(params) {
+    "use step";
+    const writable = params.writable;
+    if (!writable)
+        return;
+    const writer = writable.getWriter();
+    try {
+        await writer.write({
+            type: "data-context-substate",
+            data: { key: params.key },
+            transient: params.transient ?? true,
+        });
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function writeContextIdChunk(params) {
+    "use step";
+    const writable = params.writable;
+    if (!writable)
+        return;
+    const writer = writable.getWriter();
+    try {
+        await writer.write({
+            type: "data-context-id",
+            id: params.contextId,
+            data: { contextId: params.contextId },
+        });
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function writeThreadPing(params) {
+    "use step";
+    const writable = params.writable;
+    if (!writable)
+        return;
+    const writer = writable.getWriter();
+    try {
+        await writer.write({
+            type: "data-thread-ping",
+            data: { label: params.label ?? "thread-ping" },
+            transient: true,
+        });
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function writeToolOutputs(params) {
+    "use step";
+    const writable = params.writable;
+    if (!writable)
+        return;
+    const writer = writable.getWriter();
+    try {
+        for (const r of params.results) {
+            if (r.success) {
+                await writer.write({
+                    type: "tool-output-available",
+                    toolCallId: r.toolCallId,
+                    output: r.output,
+                });
+            }
+            else {
+                await writer.write({
+                    type: "tool-output-error",
+                    toolCallId: r.toolCallId,
+                    errorText: r.errorText,
+                });
+            }
+        }
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function closeThreadStream(params) {
+    "use step";
+    const sendFinish = params.sendFinish ?? true;
+    const preventClose = params.preventClose ?? false;
+    const writable = params.writable;
+    if (!writable)
+        return;
+    if (sendFinish) {
+        const writer = writable.getWriter();
+        try {
+            await writer.write({ type: "finish" });
+        }
+        finally {
+            writer.releaseLock();
+        }
+    }
+    if (!preventClose) {
+        await writable.close();
+    }
+}

package/dist/steps/trace.steps.d.ts

@@ -0,0 +1,37 @@
+import "../polyfills/dom-events.js";
+import type { ThreadEnvironment } from "../thread.config.js";
+export type ThreadTraceEventWrite = {
+    workflowRunId: string;
+    eventId: string;
+    eventKind: string;
+    seq?: number;
+    eventAt?: string;
+    contextKey?: string;
+    spanId?: string;
+    parentSpanId?: string;
+    contextId?: string;
+    executionId?: string;
+    stepId?: string;
+    contextEventId?: string;
+    toolCallId?: string;
+    partKey?: string;
+    partIdx?: number;
+    isDeleted?: boolean;
+    aiProvider?: string;
+    aiModel?: string;
+    promptTokens?: number;
+    promptTokensCached?: number;
+    promptTokensUncached?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    latencyMs?: number;
+    cacheCostUsd?: number;
+    computeCostUsd?: number;
+    costUsd?: number;
+    payload?: unknown;
+    testId?: string;
+};
+export declare function writeThreadTraceEvents(params: {
+    env: ThreadEnvironment;
+    events: ThreadTraceEventWrite[];
+}): Promise<void>;