@ekairos/events 1.22.4-beta.development.0

package/dist/context.step-stream.d.ts

@@ -0,0 +1,26 @@
+import { type ContextStreamChunkType } from "./context.contract.js";
+export declare const CONTEXT_STEP_STREAM_VERSION: 1;
+export type ContextStepStreamChunk = {
+    version: typeof CONTEXT_STEP_STREAM_VERSION;
+    at: string;
+    sequence: number;
+    chunkType: ContextStreamChunkType;
+    provider?: string;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+};
+export declare function createContextStepStreamChunk(params: {
+    at?: string;
+    sequence: number;
+    chunkType: ContextStreamChunkType;
+    provider?: string;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+}): ContextStepStreamChunk;
+export declare function parseContextStepStreamChunk(value: string | unknown): ContextStepStreamChunk;
+export declare function encodeContextStepStreamChunk(chunk: ContextStepStreamChunk): string;
+export declare function contextStreamByteLength(value: string): number;

package/dist/context.step-stream.js

@@ -0,0 +1,59 @@
+import { isContextStreamChunkType, } from "./context.contract.js";
+export const CONTEXT_STEP_STREAM_VERSION = 1;
+function assertObject(value, label) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`Invalid ${label}: expected object.`);
+    }
+}
+function assertString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Invalid ${label}: expected non-empty string.`);
+    }
+}
+function assertNumber(value, label) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`Invalid ${label}: expected number.`);
+    }
+}
+function assertOptionalString(value, label) {
+    if (typeof value === "undefined")
+        return;
+    assertString(value, label);
+}
+export function createContextStepStreamChunk(params) {
+    return {
+        version: CONTEXT_STEP_STREAM_VERSION,
+        at: params.at ?? new Date().toISOString(),
+        sequence: params.sequence,
+        chunkType: params.chunkType,
+        provider: params.provider,
+        providerChunkType: params.providerChunkType,
+        actionRef: params.actionRef,
+        data: params.data,
+        raw: params.raw,
+    };
+}
+export function parseContextStepStreamChunk(value) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    assertObject(parsed, "context step stream chunk");
+    assertNumber(parsed.version, "context step stream chunk.version");
+    if (parsed.version !== CONTEXT_STEP_STREAM_VERSION) {
+        throw new Error(`Unsupported context step stream chunk version: ${String(parsed.version)}`);
+    }
+    assertString(parsed.at, "context step stream chunk.at");
+    assertNumber(parsed.sequence, "context step stream chunk.sequence");
+    assertString(parsed.chunkType, "context step stream chunk.chunkType");
+    if (!isContextStreamChunkType(parsed.chunkType)) {
+        throw new Error(`Invalid context step stream chunk.chunkType: ${String(parsed.chunkType)}`);
+    }
+    assertOptionalString(parsed.provider, "context step stream chunk.provider");
+    assertOptionalString(parsed.providerChunkType, "context step stream chunk.providerChunkType");
+    assertOptionalString(parsed.actionRef, "context step stream chunk.actionRef");
+    return parsed;
+}
+export function encodeContextStepStreamChunk(chunk) {
+    return `${JSON.stringify(chunk)}\n`;
+}
+export function contextStreamByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}

package/dist/context.store.d.ts

@@ -0,0 +1,85 @@
+import type { ModelMessage } from "ai";
+import type { ContextStatus, ExecutionStatus, StepStatus, StepKind, ItemStatus, ItemType, Channel } from "./context.contract.js";
+export type ContextIdentifier = {
+    id: string;
+    key?: never;
+} | {
+    key: string;
+    id?: never;
+};
+export type { ContextStatus } from "./context.contract.js";
+export type StoredContext<Context> = {
+    id: string;
+    key: string | null;
+    name?: string | null;
+    status: ContextStatus;
+    createdAt: Date;
+    updatedAt?: Date;
+    content: Context | null;
+};
+export type ContextItem = {
+    id: string;
+    type: ItemType;
+    channel: Channel;
+    createdAt: string;
+    status?: ItemStatus;
+    content: {
+        /**
+         * Deprecated as the source of truth for output items.
+         * The engine maintains this field as a compatibility mirror, but
+         * step-level `event_parts` should be used for replay and inspection.
+         */
+        parts?: unknown[];
+        [key: string]: unknown;
+    };
+};
+export type ContextStep = {
+    id: string;
+    createdAt: Date;
+    updatedAt?: Date;
+    status: StepStatus;
+    iteration: number;
+    kind?: StepKind;
+    actionName?: string;
+    actionInput?: unknown;
+    actionOutput?: unknown;
+    actionError?: string;
+    actionRequests?: any;
+    actionResults?: any;
+    continueLoop?: boolean;
+    errorText?: string;
+};
+export type ContextExecution = {
+    id: string;
+    status: ExecutionStatus;
+};
+export interface ContextStore {
+    getOrCreateContext<C>(contextIdentifier: ContextIdentifier | null): Promise<StoredContext<C>>;
+    getContext<C>(contextIdentifier: ContextIdentifier): Promise<StoredContext<C> | null>;
+    updateContextContent<C>(contextIdentifier: ContextIdentifier, content: C): Promise<StoredContext<C>>;
+    updateContextStatus(contextIdentifier: ContextIdentifier, status: ContextStatus): Promise<void>;
+    saveItem(contextIdentifier: ContextIdentifier, item: ContextItem): Promise<ContextItem>;
+    updateItem(itemId: string, item: ContextItem): Promise<ContextItem>;
+    getItem(itemId: string): Promise<ContextItem | null>;
+    getItems(contextIdentifier: ContextIdentifier): Promise<ContextItem[]>;
+    createExecution(contextIdentifier: ContextIdentifier, triggerEventId: string, reactionEventId: string): Promise<{
+        id: string;
+    }>;
+    completeExecution(contextIdentifier: ContextIdentifier, executionId: string, status: Exclude<ExecutionStatus, "executing">): Promise<void>;
+    createStep(params: {
+        executionId: string;
+        iteration: number;
+    }): Promise<{
+        id: string;
+    }>;
+    updateStep(stepId: string, patch: Partial<Pick<ContextStep, "status" | "kind" | "actionName" | "actionInput" | "actionOutput" | "actionError" | "actionRequests" | "actionResults" | "continueLoop" | "errorText" | "updatedAt">>): Promise<void>;
+    saveStepParts(params: {
+        stepId: string;
+        parts: any[];
+    }): Promise<void>;
+    linkItemToExecution(params: {
+        itemId: string;
+        executionId: string;
+    }): Promise<void>;
+    itemsToModelMessages(items: ContextItem[]): Promise<ModelMessage[]>;
+}

package/dist/context.store.js

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

package/dist/context.stream.d.ts

@@ -0,0 +1,148 @@
+import type { ContextStatus, ExecutionStatus, ItemStatus, ItemType, StepKind, StepStatus, ContextStreamChunkType } from "./context.contract.js";
+type IsoDateString = string;
+type ContextStreamEventBase = {
+    type: string;
+    at: IsoDateString;
+};
+export type ContextCreatedEvent = ContextStreamEventBase & {
+    type: "context.created";
+    contextId: string;
+    status: ContextStatus;
+};
+export type ContextResolvedEvent = ContextStreamEventBase & {
+    type: "context.resolved";
+    contextId: string;
+    status: ContextStatus;
+};
+export type ContextStatusChangedEvent = ContextStreamEventBase & {
+    type: "context.status_changed";
+    contextId: string;
+    status: ContextStatus;
+};
+export type ContextContentUpdatedEvent = ContextStreamEventBase & {
+    type: "context.content_updated";
+    contextId: string;
+};
+export type ExecutionCreatedEvent = ContextStreamEventBase & {
+    type: "execution.created";
+    executionId: string;
+    contextId: string;
+    status: Extract<ExecutionStatus, "executing">;
+};
+export type ExecutionCompletedEvent = ContextStreamEventBase & {
+    type: "execution.completed";
+    executionId: string;
+    contextId: string;
+    status: Extract<ExecutionStatus, "completed">;
+};
+export type ExecutionFailedEvent = ContextStreamEventBase & {
+    type: "execution.failed";
+    executionId: string;
+    contextId: string;
+    status: Extract<ExecutionStatus, "failed">;
+};
+export type ItemCreatedEvent = ContextStreamEventBase & {
+    type: "item.created";
+    itemId: string;
+    contextId: string;
+    executionId?: string;
+    status: ItemStatus;
+    itemType?: ItemType;
+};
+export type ItemUpdatedEvent = ContextStreamEventBase & {
+    type: "item.updated";
+    itemId: string;
+    contextId: string;
+    executionId?: string;
+    status?: ItemStatus;
+};
+export type ItemPendingEvent = ContextStreamEventBase & {
+    type: "item.pending";
+    itemId: string;
+    contextId: string;
+    executionId?: string;
+    status: "pending";
+};
+export type ItemCompletedEvent = ContextStreamEventBase & {
+    type: "item.completed";
+    itemId: string;
+    contextId: string;
+    executionId?: string;
+    status: "completed";
+};
+export type StepCreatedEvent = ContextStreamEventBase & {
+    type: "step.created";
+    stepId: string;
+    executionId: string;
+    iteration: number;
+    status: "running";
+};
+export type StepUpdatedEvent = ContextStreamEventBase & {
+    type: "step.updated";
+    stepId: string;
+    executionId: string;
+    iteration?: number;
+    status?: StepStatus;
+    kind?: StepKind;
+    actionName?: string;
+};
+export type StepCompletedEvent = ContextStreamEventBase & {
+    type: "step.completed";
+    stepId: string;
+    executionId: string;
+    iteration?: number;
+    status: "completed";
+};
+export type StepFailedEvent = ContextStreamEventBase & {
+    type: "step.failed";
+    stepId: string;
+    executionId: string;
+    iteration?: number;
+    status: "failed";
+    errorText?: string;
+};
+export type PartCreatedEvent = ContextStreamEventBase & {
+    type: "part.created";
+    partKey: string;
+    stepId: string;
+    idx: number;
+    partType?: string;
+    partPreview?: string;
+    partState?: string;
+    partToolCallId?: string;
+};
+export type PartUpdatedEvent = ContextStreamEventBase & {
+    type: "part.updated";
+    partKey: string;
+    stepId: string;
+    idx: number;
+    partType?: string;
+    partPreview?: string;
+    partState?: string;
+    partToolCallId?: string;
+};
+export type ChunkEmittedEvent = ContextStreamEventBase & {
+    type: "chunk.emitted";
+    chunkType: ContextStreamChunkType;
+    contextId: string;
+    executionId?: string;
+    stepId?: string;
+    itemId?: string;
+    partKey?: string;
+    actionRef?: string;
+    provider?: string;
+    providerChunkType?: string;
+    sequence: number;
+    data?: unknown;
+    raw?: unknown;
+};
+export type ContextLifecycleEvent = ContextCreatedEvent | ContextResolvedEvent | ContextStatusChangedEvent | ContextContentUpdatedEvent;
+export type ExecutionEvent = ExecutionCreatedEvent | ExecutionCompletedEvent | ExecutionFailedEvent;
+export type ItemEvent = ItemCreatedEvent | ItemUpdatedEvent | ItemPendingEvent | ItemCompletedEvent;
+export type StepEvent = StepCreatedEvent | StepUpdatedEvent | StepCompletedEvent | StepFailedEvent;
+export type PartEvent = PartCreatedEvent | PartUpdatedEvent;
+export type ContextStreamEvent = ContextLifecycleEvent | ExecutionEvent | ItemEvent | StepEvent | PartEvent | ChunkEmittedEvent;
+export declare function parseContextStreamEvent(value: unknown): ContextStreamEvent;
+export declare function assertContextStreamTransitions(_event: ContextStreamEvent): void;
+export declare function validateContextStreamTimeline(events: readonly ContextStreamEvent[]): void;
+export {};

package/dist/context.stream.js

@@ -0,0 +1,141 @@
+import { isContextStreamChunkType } from "./context.contract.js";
+function assertObject(value, label) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`Invalid ${label}: expected object.`);
+    }
+}
+function assertString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Invalid ${label}: expected non-empty string.`);
+    }
+}
+function assertNumber(value, label) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`Invalid ${label}: expected number.`);
+    }
+}
+function assertOptionalString(value, label) {
+    if (value !== undefined) {
+        assertString(value, label);
+    }
+}
+function assertOptionalNumber(value, label) {
+    if (value !== undefined) {
+        assertNumber(value, label);
+    }
+}
+export function parseContextStreamEvent(value) {
+    assertObject(value, "context stream event");
+    assertString(value.type, "context stream event.type");
+    assertString(value.at, "context stream event.at");
+    const type = value.type;
+    switch (type) {
+        case "context.created":
+        case "context.resolved":
+        case "context.status_changed": {
+            assertString(value.contextId, `${type}.contextId`);
+            assertString(value.status, `${type}.status`);
+            return value;
+        }
+        case "context.content_updated": {
+            assertString(value.contextId, `${type}.contextId`);
+            return value;
+        }
+        case "execution.created":
+        case "execution.completed":
+        case "execution.failed": {
+            assertString(value.executionId, `${type}.executionId`);
+            assertString(value.contextId, `${type}.contextId`);
+            assertString(value.status, `${type}.status`);
+            return value;
+        }
+        case "item.created": {
+            assertString(value.itemId, `${type}.itemId`);
+            assertString(value.contextId, `${type}.contextId`);
+            assertString(value.status, `${type}.status`);
+            assertOptionalString(value.executionId, `${type}.executionId`);
+            assertOptionalString(value.itemType, `${type}.itemType`);
+            return value;
+        }
+        case "item.updated": {
+            assertString(value.itemId, `${type}.itemId`);
+            assertString(value.contextId, `${type}.contextId`);
+            assertOptionalString(value.executionId, `${type}.executionId`);
+            assertOptionalString(value.status, `${type}.status`);
+            return value;
+        }
+        case "item.pending":
+        case "item.completed": {
+            assertString(value.itemId, `${type}.itemId`);
+            assertString(value.contextId, `${type}.contextId`);
+            assertOptionalString(value.executionId, `${type}.executionId`);
+            assertString(value.status, `${type}.status`);
+            return value;
+        }
+        case "step.created": {
+            assertString(value.stepId, `${type}.stepId`);
+            assertString(value.executionId, `${type}.executionId`);
+            assertNumber(value.iteration, `${type}.iteration`);
+            assertString(value.status, `${type}.status`);
+            return value;
+        }
+        case "step.updated": {
+            assertString(value.stepId, `${type}.stepId`);
+            assertString(value.executionId, `${type}.executionId`);
+            if (value.iteration !== undefined)
+                assertNumber(value.iteration, `${type}.iteration`);
+            assertOptionalString(value.status, `${type}.status`);
+            assertOptionalString(value.kind, `${type}.kind`);
+            assertOptionalString(value.actionName, `${type}.actionName`);
+            return value;
+        }
+        case "step.completed":
+        case "step.failed": {
+            assertString(value.stepId, `${type}.stepId`);
+            assertString(value.executionId, `${type}.executionId`);
+            if (value.iteration !== undefined)
+                assertNumber(value.iteration, `${type}.iteration`);
+            assertString(value.status, `${type}.status`);
+            if (type === "step.failed")
+                assertOptionalString(value.errorText, `${type}.errorText`);
+            return value;
+        }
+        case "part.created":
+        case "part.updated": {
+            assertString(value.partKey, `${type}.partKey`);
+            assertString(value.stepId, `${type}.stepId`);
+            assertNumber(value.idx, `${type}.idx`);
+            assertOptionalString(value.partType, `${type}.partType`);
+            assertOptionalString(value.partPreview, `${type}.partPreview`);
+            assertOptionalString(value.partState, `${type}.partState`);
+            assertOptionalString(value.partToolCallId, `${type}.partToolCallId`);
+            return value;
+        }
+        case "chunk.emitted": {
+            assertString(value.chunkType, `${type}.chunkType`);
+            if (!isContextStreamChunkType(value.chunkType)) {
+                throw new Error(`Invalid ${type}.chunkType: ${String(value.chunkType)}`);
+            }
+            assertString(value.contextId, `${type}.contextId`);
+            assertOptionalString(value.executionId, `${type}.executionId`);
+            assertOptionalString(value.stepId, `${type}.stepId`);
+            assertOptionalString(value.itemId, `${type}.itemId`);
+            assertOptionalString(value.partKey, `${type}.partKey`);
+            assertOptionalString(value.actionRef, `${type}.actionRef`);
+            assertOptionalString(value.provider, `${type}.provider`);
+            assertOptionalString(value.providerChunkType, `${type}.providerChunkType`);
+            assertOptionalNumber(value.sequence, `${type}.sequence`);
+            return value;
+        }
+        default:
+            throw new Error(`Unsupported context stream event type: ${type}`);
+    }
+}
+export function assertContextStreamTransitions(_event) {
+    return;
+}
+export function validateContextStreamTimeline(events) {
+    for (const event of events) {
+        assertContextStreamTransitions(event);
+    }
+}

package/dist/context.toolcalls.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ## context.toolcalls.ts
+ *
+ * This module isolates the **tool-call plumbing** used by `context.engine.ts`.
+ *
+ * In our runtime, tool calls are represented as **event parts** produced by the AI SDK.
+ * The engine needs to:
+ * - extract a normalized list of tool calls from `event.content.parts`, and
+ * - merge tool execution outcomes back into those parts (so the persisted event reflects
+ *   `output-available` / `output-error`, etc.).
+ *
+ * Keeping this logic here helps `context.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+import type { ContextItem } from "./context.store.js";
+export type ToolCall = {
+    toolCallId: string;
+    toolName: string;
+    args: any;
+};
+/**
+ * Extracts tool calls from an event's `parts` array.
+ *
+ * Expected part shape (loosely):
+ * - `type`: string like `"tool-<toolName>"`
+ * - `toolCallId`: string
+ * - `input`: any (tool args)
+ *
+ * We intentionally treat the input as `any` because the part schema is produced by the AI SDK.
+ */
+export declare function extractToolCallsFromParts(parts: any[] | undefined | null): ToolCall[];
+/**
+ * Applies a tool execution outcome to the matching tool part.
+ *
+ * This does not mutate `parts` — it returns a new array.
+ *
+ * We match the tool part by:
+ * - `type === "tool-<toolName>"` and
+ * - `toolCallId` equality
+ *
+ * Then we set:
+ * - on success: `{ state: "output-available", output: <result> }`
+ * - on failure: `{ state: "output-error", errorText: <message> }`
+ */
+export declare function applyToolExecutionResultToParts(parts: any[], toolCall: Pick<ToolCall, "toolCallId" | "toolName">, execution: {
+    success: boolean;
+    result: any;
+    message?: string;
+}): any[];
+/**
+ * Returns `true` when a given tool has a **settled** execution result in an event's parts.
+ *
+ * We treat a tool part as "executed" once it has either:
+ * - `state: "output-available"` (success), or
+ * - `state: "output-error"` (failure).
+ *
+ * This is useful for stop/continue logic in `context.shouldContinue(...)` where you want to
+ * decide based on the persisted `reactionEvent` (not ephemeral in-memory arrays).
+ */
+export declare function didToolExecute(event: Pick<ContextItem, "content">, toolName: string): boolean;

package/dist/context.toolcalls.js

@@ -0,0 +1,117 @@
+/**
+ * ## context.toolcalls.ts
+ *
+ * This module isolates the **tool-call plumbing** used by `context.engine.ts`.
+ *
+ * In our runtime, tool calls are represented as **event parts** produced by the AI SDK.
+ * The engine needs to:
+ * - extract a normalized list of tool calls from `event.content.parts`, and
+ * - merge tool execution outcomes back into those parts (so the persisted event reflects
+ *   `output-available` / `output-error`, etc.).
+ *
+ * Keeping this logic here helps `context.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+import { isContextPartEnvelope, normalizePartsForPersistence, normalizeToolResultContentToBlocks, } from "./context.parts.js";
+/**
+ * Extracts tool calls from an event's `parts` array.
+ *
+ * Expected part shape (loosely):
+ * - `type`: string like `"tool-<toolName>"`
+ * - `toolCallId`: string
+ * - `input`: any (tool args)
+ *
+ * We intentionally treat the input as `any` because the part schema is produced by the AI SDK.
+ */
+export function extractToolCallsFromParts(parts) {
+    const safeParts = parts ?? [];
+    return safeParts.reduce((acc, p) => {
+        if (isContextPartEnvelope(p) && p.type === "tool-call") {
+            const firstContent = Array.isArray(p.content) ? p.content[0] : undefined;
+            const args = firstContent && firstContent.type === "json" ? firstContent.value : p.content;
+            acc.push({
+                toolCallId: p.toolCallId,
+                toolName: p.toolName,
+                args,
+            });
+            return acc;
+        }
+        if (typeof p?.type === "string" && p.type.startsWith("tool-")) {
+            const toolName = p.type.split("-").slice(1).join("-");
+            acc.push({ toolCallId: p.toolCallId, toolName, args: p.input });
+        }
+        return acc;
+    }, []);
+}
+/**
+ * Applies a tool execution outcome to the matching tool part.
+ *
+ * This does not mutate `parts` — it returns a new array.
+ *
+ * We match the tool part by:
+ * - `type === "tool-<toolName>"` and
+ * - `toolCallId` equality
+ *
+ * Then we set:
+ * - on success: `{ state: "output-available", output: <result> }`
+ * - on failure: `{ state: "output-error", errorText: <message> }`
+ */
+export function applyToolExecutionResultToParts(parts, toolCall, execution) {
+    const normalized = normalizePartsForPersistence(parts);
+    const next = [];
+    let insertedResult = false;
+    const resultContent = execution.success
+        ? normalizeToolResultContentToBlocks(execution.result)
+        : [
+            {
+                type: "text",
+                text: String(execution.message || "Error"),
+            },
+        ];
+    for (const part of normalized) {
+        next.push(part);
+        if (part.type !== "tool-call") {
+            continue;
+        }
+        if (part.toolCallId !== toolCall.toolCallId ||
+            part.toolName !== toolCall.toolName) {
+            continue;
+        }
+        next.push({
+            type: "tool-result",
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            state: execution.success ? "output-available" : "output-error",
+            content: resultContent,
+        });
+        insertedResult = true;
+    }
+    if (!insertedResult) {
+        next.push({
+            type: "tool-result",
+            toolCallId: toolCall.toolCallId,
+            toolName: toolCall.toolName,
+            state: execution.success ? "output-available" : "output-error",
+            content: resultContent,
+        });
+    }
+    return next;
+}
+/**
+ * Returns `true` when a given tool has a **settled** execution result in an event's parts.
+ *
+ * We treat a tool part as "executed" once it has either:
+ * - `state: "output-available"` (success), or
+ * - `state: "output-error"` (failure).
+ *
+ * This is useful for stop/continue logic in `context.shouldContinue(...)` where you want to
+ * decide based on the persisted `reactionEvent` (not ephemeral in-memory arrays).
+ */
+export function didToolExecute(event, toolName) {
+    const parts = (event.content.parts ?? []).flatMap((part) => isContextPartEnvelope(part) ? [part] : normalizePartsForPersistence([part]));
+    return parts.some((p) => (p.type === "tool-result" &&
+        p.toolName === toolName &&
+        (p.state === "output-available" || p.state === "output-error")) ||
+        (p.type === `tool-${toolName}` &&
+            (p.state === "output-available" || p.state === "output-error")));
+}

package/dist/env.d.ts

@@ -0,0 +1,3 @@
+import type { ContextEnvironment } from "./context.config.js";
+export declare function registerContextEnv(env: ContextEnvironment, runId?: string | null): void;
+export declare function getContextEnv(): Promise<ContextEnvironment>;