@ekairos/events 1.22.4-beta.development.0

package/dist/steps/stream.steps.js

@@ -0,0 +1,270 @@
+import { contextStreamByteLength, parseContextStepStreamChunk, } from "../context.step-stream.js";
+export async function writeContextEvents(params) {
+    "use step";
+    const writable = params.writable;
+    if (!writable || !params.events.length)
+        return;
+    const writer = writable.getWriter();
+    try {
+        for (const event of params.events) {
+            await writer.write({
+                type: `data-${String(event.type)}`,
+                data: event,
+            });
+        }
+    }
+    finally {
+        writer.releaseLock();
+    }
+}
+export async function closeContextStream(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();
+    }
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function createUnsetStreamLinkTx(db, executionId, label, streamId) {
+    try {
+        return db.tx.event_executions[executionId].unlink({ [label]: streamId });
+    }
+    catch {
+        return null;
+    }
+}
+export function createContextStepStreamClientId(stepId) {
+    const normalized = String(stepId ?? "").trim();
+    if (!normalized) {
+        throw new Error("createContextStepStreamClientId: stepId is required.");
+    }
+    return `event-step:${normalized}`;
+}
+export async function createPersistedContextStepStream(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const db = runtime?.db;
+    if (!db?.streams?.createWriteStream) {
+        throw new Error("InstantDB streams are not available on the configured runtime. Upgrade @instantdb/admin to a streams-capable version.");
+    }
+    const clientId = asString(params.clientId) || createContextStepStreamClientId(params.stepId);
+    const startedAt = new Date();
+    const writeStream = db.streams.createWriteStream({
+        clientId,
+    });
+    const streamId = await writeStream.streamId();
+    await db.transact([
+        db.tx.event_steps[params.stepId]
+            .update({
+            streamId,
+            streamClientId: clientId,
+            streamStartedAt: startedAt,
+            streamFinishedAt: null,
+            streamAbortReason: null,
+            updatedAt: new Date(),
+        })
+            .link({ stream: streamId }),
+        db.tx.event_executions[params.executionId]
+            .update({
+            activeStreamId: streamId,
+            activeStreamClientId: clientId,
+            lastStreamId: streamId,
+            lastStreamClientId: clientId,
+            updatedAt: new Date(),
+        })
+            .link({ activeStream: streamId, lastStream: streamId }),
+    ]);
+    return {
+        stream: writeStream,
+        streamId,
+        clientId,
+        executionId: params.executionId,
+        stepId: params.stepId,
+    };
+}
+async function finalizePersistedContextStepStream(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const db = runtime?.db;
+    const writer = params.session.stream.getWriter();
+    try {
+        if (params.mode === "abort") {
+            await writer.abort(params.abortReason ?? "aborted");
+        }
+        else {
+            await writer.close();
+        }
+    }
+    finally {
+        writer.releaseLock();
+    }
+    const now = new Date();
+    const txs = [
+        db.tx.event_steps[params.session.stepId].update({
+            streamFinishedAt: now,
+            streamAbortReason: params.mode === "abort" ? params.abortReason ?? "aborted" : null,
+            updatedAt: now,
+        }),
+        db.tx.event_executions[params.session.executionId].update({
+            activeStreamId: null,
+            activeStreamClientId: null,
+            lastStreamId: params.session.streamId,
+            lastStreamClientId: params.session.clientId,
+            updatedAt: now,
+        }),
+    ];
+    const unsetActive = createUnsetStreamLinkTx(db, params.session.executionId, "activeStream", params.session.streamId);
+    if (unsetActive)
+        txs.push(unsetActive);
+    await db.transact(txs);
+}
+export async function closePersistedContextStepStream(params) {
+    return await finalizePersistedContextStepStream({
+        env: params.env,
+        session: params.session,
+        mode: "close",
+    });
+}
+export async function abortPersistedContextStepStream(params) {
+    return await finalizePersistedContextStepStream({
+        env: params.env,
+        session: params.session,
+        mode: "abort",
+        abortReason: params.reason,
+    });
+}
+export async function readPersistedContextStepStream(params) {
+    if (!params.db?.streams?.createReadStream) {
+        throw new Error("InstantDB streams are not available on the provided runtime.");
+    }
+    const clientId = asString(params.clientId);
+    const streamId = asString(params.streamId);
+    if (!clientId && !streamId) {
+        throw new Error("readPersistedContextStepStream requires clientId or streamId.");
+    }
+    const startOffset = typeof params.byteOffset === "number" && Number.isFinite(params.byteOffset)
+        ? Math.max(0, params.byteOffset)
+        : 0;
+    const stream = params.db.streams.createReadStream({
+        clientId: clientId || undefined,
+        streamId: streamId || undefined,
+        byteOffset: startOffset,
+    });
+    const chunks = [];
+    let byteOffset = startOffset;
+    let buffer = "";
+    for await (const rawChunk of stream) {
+        const encoded = typeof rawChunk === "string" ? rawChunk : String(rawChunk ?? "");
+        if (!encoded)
+            continue;
+        byteOffset += contextStreamByteLength(encoded);
+        buffer += encoded;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            const parsed = parseContextStepStreamChunk(trimmed);
+            chunks.push(parsed);
+            await params.onChunk?.(parsed);
+        }
+    }
+    const trailing = buffer.trim();
+    if (trailing) {
+        const parsed = parseContextStepStreamChunk(trailing);
+        chunks.push(parsed);
+        await params.onChunk?.(parsed);
+    }
+    return {
+        chunks,
+        byteOffset,
+    };
+}
+export async function resolveContextExecutionStreamPointer(params) {
+    const snapshot = await params.db.query({
+        event_contexts: {
+            $: {
+                where: { id: params.contextId },
+                limit: 1,
+            },
+            currentExecution: {},
+        },
+    });
+    const contextRow = Array.isArray(snapshot?.event_contexts)
+        ? snapshot.event_contexts[0]
+        : null;
+    const executionRow = asRecord(contextRow?.currentExecution);
+    const executionId = asString(executionRow.id);
+    if (!executionId)
+        return null;
+    const activeStreamClientId = asString(executionRow.activeStreamClientId);
+    const activeStreamId = asString(executionRow.activeStreamId);
+    if (activeStreamClientId || activeStreamId) {
+        return {
+            executionId,
+            status: asString(executionRow.status) || null,
+            source: "active",
+            clientId: activeStreamClientId || null,
+            streamId: activeStreamId || null,
+        };
+    }
+    const lastStreamClientId = asString(executionRow.lastStreamClientId);
+    const lastStreamId = asString(executionRow.lastStreamId);
+    if (lastStreamClientId || lastStreamId) {
+        return {
+            executionId,
+            status: asString(executionRow.status) || null,
+            source: "last",
+            clientId: lastStreamClientId || null,
+            streamId: lastStreamId || null,
+        };
+    }
+    return {
+        executionId,
+        status: asString(executionRow.status) || null,
+        source: "none",
+        clientId: null,
+        streamId: null,
+    };
+}
+export async function waitForContextExecutionStreamPointer(params) {
+    const timeoutMs = typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs)
+        ? Math.max(0, params.timeoutMs)
+        : 15000;
+    const pollMs = typeof params.pollMs === "number" && Number.isFinite(params.pollMs)
+        ? Math.max(10, params.pollMs)
+        : 125;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const pointer = await resolveContextExecutionStreamPointer({
+            db: params.db,
+            contextId: params.contextId,
+        });
+        if (pointer && (pointer.clientId || pointer.streamId)) {
+            return pointer;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return null;
+}

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

@@ -0,0 +1,38 @@
+import "../polyfills/dom-events.js";
+import type { ContextEnvironment } from "../context.config.js";
+import type { TraceEventKind } from "../context.contract.js";
+export type ContextTraceEventWrite = {
+    workflowRunId: string;
+    eventId: string;
+    eventKind: TraceEventKind;
+    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 writeContextTraceEvents(params: {
+    env: ContextEnvironment;
+    events: ContextTraceEventWrite[];
+}): Promise<void>;

package/dist/steps/trace.steps.js

@@ -0,0 +1,270 @@
+import "../polyfills/dom-events.js";
+import { lookup } from "@instantdb/admin";
+function requireBaseUrl() {
+    const baseUrl = process.env.EKAIROS_CORE_BASE_URL ||
+        process.env.EKAIROS_TRACES_BASE_URL ||
+        process.env.EKAIROS_BASE_URL;
+    if (!baseUrl) {
+        throw new Error("[context/trace] Missing EKAIROS_CORE_BASE_URL (or EKAIROS_TRACES_BASE_URL)");
+    }
+    return baseUrl.replace(/\/$/, "");
+}
+function requireToken() {
+    // Preferred: Clerk org API key (opaque token) for ekairos-core.
+    const apiKey = process.env.EKAIROS_CLERK_API_KEY;
+    if (apiKey)
+        return apiKey;
+    throw new Error("[context/trace] Missing EKAIROS_CLERK_API_KEY");
+}
+let jwtCache = null;
+function parseJwtExpMs(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return null;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1].replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf-8"));
+        const exp = typeof payload?.exp === "number" ? payload.exp : null;
+        return exp ? exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function getTraceAuthHeader(baseUrl, projectId) {
+    const apiKey = requireToken();
+    const now = Date.now();
+    if (jwtCache && jwtCache.expMs - 60000 > now) {
+        return `Bearer ${jwtCache.token}`;
+    }
+    try {
+        const res = await fetch(`${baseUrl}/api/context/traces/auth`, {
+            method: "POST",
+            headers: {
+                "content-type": "application/json",
+                authorization: `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ projectId }),
+        });
+        if (res.ok) {
+            const json = (await res.json());
+            const token = typeof json?.token === "string" ? json.token : "";
+            const expMs = parseJwtExpMs(token) ?? now + 60 * 60 * 1000;
+            if (token) {
+                jwtCache = { token, expMs };
+                return `Bearer ${token}`;
+            }
+        }
+    }
+    catch {
+        // fall back to API key below
+    }
+    return `Bearer ${apiKey}`;
+}
+async function readProjectId() {
+    try {
+        const { getRuntimeProjectId } = await import("@ekairos/domain/runtime");
+        const fromConfig = String(getRuntimeProjectId?.() || "").trim();
+        if (fromConfig)
+            return fromConfig;
+    }
+    catch {
+        // ignore and fall back to env
+    }
+    const fallback = typeof process !== "undefined" && process.env
+        ? String(process.env.EKAIROS_PROJECT_ID || "").trim()
+        : "";
+    return fallback;
+}
+export async function writeContextTraceEvents(params) {
+    if (!params.events?.length)
+        return;
+    const envTrace = params.env?.traces;
+    // Tracing must NEVER break workflows by default.
+    // Use EKAIROS_TRACES_STRICT=1 if you want to fail hard.
+    const strict = envTrace?.strict === true || process.env.EKAIROS_TRACES_STRICT === "1";
+    // 1) Local trace persistence (InstantDB source of truth).
+    try {
+        const { getContextRuntime } = await import("../runtime.js");
+        const runtime = await getContextRuntime(params.env);
+        const db = runtime?.db;
+        if (db) {
+            const now = new Date();
+            const orgId = typeof params.env?.orgId === "string"
+                ? String(params.env.orgId)
+                : "";
+            const projectId = await readProjectId();
+            const byRun = new Map();
+            for (const ev of params.events) {
+                const runId = String(ev.workflowRunId || "");
+                if (!runId)
+                    continue;
+                if (!byRun.has(runId))
+                    byRun.set(runId, []);
+                byRun.get(runId).push(ev);
+            }
+            const seqByRun = new Map();
+            const existingCountByRun = new Map();
+            for (const [runId] of byRun) {
+                let existingCount = 0;
+                try {
+                    const q = await db.query({
+                        event_trace_runs: {
+                            $: { where: { workflowRunId: runId }, limit: 1 },
+                        },
+                    });
+                    const row = q?.event_trace_runs?.[0];
+                    existingCount = Number(row?.eventsCount ?? 0) || 0;
+                }
+                catch {
+                    // ignore
+                }
+                existingCountByRun.set(runId, existingCount);
+                seqByRun.set(runId, existingCount);
+            }
+            const txs = [];
+            const spanTxs = [];
+            for (const ev of params.events) {
+                const runId = String(ev.workflowRunId || "");
+                if (!runId)
+                    continue;
+                const key = `${runId}:${String(ev.eventId || "")}`;
+                if (!key.includes(":"))
+                    continue;
+                const eventAt = typeof ev.eventAt === "string" && ev.eventAt
+                    ? new Date(ev.eventAt)
+                    : undefined;
+                let seq = Number.isFinite(Number(ev.seq)) ? Number(ev.seq) : undefined;
+                if (typeof seq !== "number") {
+                    const current = seqByRun.get(runId) ?? 0;
+                    const next = current + 1;
+                    seqByRun.set(runId, next);
+                    seq = next;
+                }
+                ev.seq = seq;
+                txs.push(db.tx.event_trace_events[lookup("key", key)].update({
+                    key,
+                    workflowRunId: runId,
+                    seq,
+                    eventId: String(ev.eventId || ""),
+                    eventKind: String(ev.eventKind || ""),
+                    eventAt: eventAt ?? undefined,
+                    ingestedAt: now,
+                    orgId: orgId || undefined,
+                    projectId: projectId || undefined,
+                    contextKey: ev.contextKey,
+                    spanId: ev.spanId,
+                    parentSpanId: ev.parentSpanId,
+                    contextId: ev.contextId,
+                    executionId: ev.executionId,
+                    stepId: ev.stepId,
+                    contextEventId: ev.contextEventId,
+                    toolCallId: ev.toolCallId,
+                    partKey: ev.partKey,
+                    partIdx: ev.partIdx,
+                    isDeleted: ev.isDeleted === true,
+                    aiProvider: ev.aiProvider,
+                    aiModel: ev.aiModel,
+                    promptTokens: ev.promptTokens,
+                    promptTokensCached: ev.promptTokensCached,
+                    promptTokensUncached: ev.promptTokensUncached,
+                    completionTokens: ev.completionTokens,
+                    totalTokens: ev.totalTokens,
+                    latencyMs: ev.latencyMs,
+                    cacheCostUsd: ev.cacheCostUsd,
+                    computeCostUsd: ev.computeCostUsd,
+                    costUsd: ev.costUsd,
+                    payload: ev.payload,
+                }));
+                if (ev.eventKind === "context.step" || ev.eventKind === "workflow.step") {
+                    const spanId = String(ev.stepId || ev.eventId || key);
+                    spanTxs.push(db.tx.event_trace_spans[lookup("spanId", spanId)].update({
+                        spanId,
+                        parentSpanId: ev.parentSpanId,
+                        workflowRunId: runId,
+                        executionId: ev.executionId,
+                        stepId: ev.stepId,
+                        kind: ev.eventKind,
+                        name: ev.eventKind,
+                        status: "completed",
+                        startedAt: eventAt ?? now,
+                        endedAt: eventAt ?? now,
+                        durationMs: 0,
+                        payload: ev.payload,
+                    }));
+                }
+            }
+            if (txs.length) {
+                await db.transact(txs);
+            }
+            if (spanTxs.length) {
+                await db.transact(spanTxs);
+            }
+            for (const [runId, events] of byRun) {
+                const eventDates = events
+                    .map((e) => typeof e.eventAt === "string" && e.eventAt
+                    ? new Date(e.eventAt)
+                    : now)
+                    .filter((d) => !Number.isNaN(d.getTime()));
+                const firstEventAt = eventDates.length
+                    ? new Date(Math.min(...eventDates.map((d) => d.getTime())))
+                    : now;
+                const lastEventAt = eventDates.length
+                    ? new Date(Math.max(...eventDates.map((d) => d.getTime())))
+                    : now;
+                const existingCount = existingCountByRun.get(runId) ?? 0;
+                await db.transact([
+                    db.tx.event_trace_runs[lookup("workflowRunId", runId)].update({
+                        workflowRunId: runId,
+                        orgId: orgId || undefined,
+                        projectId: projectId || undefined,
+                        firstEventAt,
+                        lastEventAt,
+                        lastIngestedAt: now,
+                        eventsCount: existingCount + events.length,
+                    }),
+                ]);
+            }
+        }
+    }
+    catch (e) {
+        if (strict)
+            throw e;
+    }
+    let baseUrl = "";
+    try {
+        baseUrl = envTrace?.baseUrl ? String(envTrace.baseUrl).replace(/\/$/, "") : requireBaseUrl();
+    }
+    catch (e) {
+        if (strict)
+            throw e;
+        return;
+    }
+    const projectId = envTrace?.projectId ? String(envTrace.projectId).trim() : await readProjectId();
+    if (!projectId) {
+        if (strict)
+            throw new Error("[context/trace] Missing projectId (ekairosConfig or EKAIROS_PROJECT_ID)");
+        return;
+    }
+    const authHeader = envTrace?.apiKey
+        ? `Bearer ${String(envTrace.apiKey).trim()}`
+        : await getTraceAuthHeader(baseUrl, projectId);
+    const res = await fetch(`${baseUrl}/api/context/traces/ingest`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            authorization: authHeader,
+        },
+        body: JSON.stringify({ projectId, events: params.events }),
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        if (strict) {
+            throw new Error(`[context/trace] ekairos-core ingest failed (${res.status}): ${text}`);
+        }
+        if (process.env.PLAYWRIGHT_TEST === "1") {
+            // eslint-disable-next-line no-console
+            console.warn(`[context/trace] ingest failed (${res.status}): ${text}`);
+        }
+        return;
+    }
+}

package/dist/stores/instant.document-parser.d.ts

@@ -0,0 +1,6 @@
+import "../polyfills/dom-events.js";
+/**
+ * Parses a document with LlamaParse and stores it in InstantDB (document_documents + link to file).
+ * Returns the created documentId.
+ */
+export declare function parseAndStoreDocument(db: any, buffer: Buffer, fileName: string, fileId: string): Promise<string>;