@ekairos/events 1.22.32-beta.development.0 → 1.22.33-beta.development.0

package/README.md

@@ -23,6 +23,67 @@ Context-first durable execution runtime for Ekairos.
 
 The aggregate is `context`. Executions, steps, parts, and items are scoped to a context.
 
+## Canonical Parts
+
+`event_parts` is the canonical content model for produced output.
+
+Rules:
+
+- `event_parts.part` is the source of truth for replay and inspection.
+- `event_items.content.parts` on output items is maintained as a compatibility mirror and is deprecated as a replay source.
+- Provider/model-specific values must live under `metadata`, never as first-class semantic fields.
+
+Canonical part kinds:
+
+- `content`
+- `reasoning`
+- `source`
+- `tool-call`
+- `tool-result`
+
+Each canonical part stores a `content` array. The entries inside that array define the payload type:
+
+- `text`
+- `file`
+- `json`
+- `source-url`
+- `source-document`
+
+Example tool result:
+
+```ts
+{
+  type: "tool-result",
+  toolCallId: "call_123",
+  toolName: "inspectCanvasRegion",
+  state: "output-available",
+  content: [
+    {
+      type: "text",
+      text: "Zoomed crop of the requested region.",
+    },
+    {
+      type: "file",
+      mediaType: "image/png",
+      filename: "inspect-region.png",
+      data: "iVBORw0KGgoAAAANSUhEUgAA...",
+    },
+  ],
+  metadata: {
+    provider: {
+      itemId: "fc_041cb...",
+    },
+  },
+}
+```
+
+The AI SDK bridge projects canonical parts to:
+
+- assistant messages with text/file/reasoning/source/tool-call parts
+- tool messages with `tool-result` or `tool-error`
+
+That means multipart tool outputs are replayed from `event_parts` instead of relying on the deprecated output-item mirror.
+
 ## Install
 
 ```bash

package/dist/context.engine.js

@@ -1,6 +1,7 @@
 import { registerContextEnv } from "./env.js";
 import { OUTPUT_ITEM_TYPE, WEB_CHANNEL } from "./context.events.js";
 import { applyToolExecutionResultToParts } from "./context.toolcalls.js";
+import { isContextPartEnvelope, normalizePartsForPersistence, } from "./context.parts.js";
 import { toolsToModelTools } from "./tools-to-model-tools.js";
 import { createAiSdkReactor, } from "./context.reactor.js";
 import { abortPersistedContextStepStream, closePersistedContextStepStream, createPersistedContextStepStream, closeContextStream, } from "./steps/stream.steps.js";
@@ -22,6 +23,20 @@ function clipPreview(value, max = 240) {
 function summarizePartPreview(part) {
     if (!part || typeof part !== "object")
         return {};
+    if (isContextPartEnvelope(part)) {
+        const preview = part.content[0]?.type === "text"
+            ? part.content[0].text
+            : JSON.stringify(part.content[0] ?? part);
+        const state = "state" in part && typeof part.state === "string" ? part.state : undefined;
+        const toolCallId = "toolCallId" in part && typeof part.toolCallId === "string"
+            ? part.toolCallId
+            : undefined;
+        return {
+            partPreview: preview ? clipPreview(preview) : undefined,
+            partState: state,
+            partToolCallId: toolCallId,
+        };
+    }
     const row = part;
     const partType = typeof row.type === "string" ? row.type : "";
     const partState = typeof row.state === "string" ? row.state : undefined;
@@ -527,7 +542,7 @@ export class ContextEngine {
                     : [];
                 let persistedReactionPartsSignature = "";
                 const persistReactionParts = async (nextParts) => {
-                    const normalizedParts = Array.isArray(nextParts) ? nextParts : [];
+                    const normalizedParts = normalizePartsForPersistence(Array.isArray(nextParts) ? nextParts : []);
                     const nextSignature = JSON.stringify(normalizedParts);
                     if (nextSignature === persistedReactionPartsSignature)
                         return;
@@ -591,7 +606,7 @@ export class ContextEngine {
                 // We intentionally do NOT persist the per-step LLM assistant event as a `context_event`.
                 // The story exposes a single visible `context_event` per turn (`reactionEventId`) so the UI
                 // doesn't render duplicate assistant messages (LLM-step + aggregated reaction).
-                const stepParts = (assistantEvent?.content?.parts ?? []);
+                const stepParts = normalizePartsForPersistence((assistantEvent?.content?.parts ?? []));
                 const assistantEventEffective = {
                     ...assistantEvent,
                     content: {
@@ -836,11 +851,9 @@ export class ContextEngine {
                     }
                 })));
                 // Merge action results into persisted parts (so next LLM call can see them)
-                let parts = Array.isArray(reactionEvent.content?.parts)
-                    ? [...reactionEvent.content.parts]
-                    : [];
+                let finalizedStepParts = Array.isArray(stepParts) ? [...stepParts] : [];
                 for (const r of actionResults) {
-                    parts = applyToolExecutionResultToParts(parts, {
+                    finalizedStepParts = applyToolExecutionResultToParts(finalizedStepParts, {
                         toolCallId: r.actionRequest.actionRef,
                         toolName: r.actionRequest.actionName,
                     }, {
@@ -849,11 +862,20 @@ export class ContextEngine {
                         message: r.errorText,
                     });
                 }
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.saveFinalStepPartsMs`, async () => await ops.saveContextPartsStep({
+                    stepId: stepCreate.stepId,
+                    parts: finalizedStepParts,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
                 reactionEvent = {
                     ...reactionEvent,
                     content: {
                         ...reactionEvent.content,
-                        parts,
+                        // Deprecated mirror for compatibility. `event_parts` are the
+                        // source of truth for replay and step inspection.
+                        parts: [...reactionPartsBeforeStep, ...finalizedStepParts],
                     },
                     status: "pending",
                 };

package/dist/context.events.d.ts

@@ -6,6 +6,26 @@ export declare const INPUT_TEXT_ITEM_TYPE = "input";
 export declare const WEB_CHANNEL = "web";
 export declare const AGENT_CHANNEL = "whatsapp";
 export declare const EMAIL_CHANNEL = "email";
+export type ContextOutputContentPart = {
+    type: "text";
+    text: string;
+} | ({
+    type: "image-data";
+    data: string;
+    mediaType: string;
+    filename?: string;
+} & Record<string, unknown>) | ({
+    type: string;
+} & Record<string, unknown>);
+export type ContextOutputPart = {
+    type: "json";
+    value: unknown;
+} | {
+    type: "content";
+    value: ContextOutputContentPart[];
+};
+export declare function isContextOutputPart(value: unknown): value is ContextOutputPart;
+export declare function normalizeContextOutputPart(value: unknown): ContextOutputPart;
 export declare function createUserItemFromUIMessages(messages: UIMessage[]): ContextItem;
 export declare function createAssistantItemFromUIMessages(itemId: string, messages: UIMessage[]): ContextItem;
 export declare function convertToUIMessage(item: ContextItem): UIMessage;

package/dist/context.events.js

@@ -1,10 +1,322 @@
 import { convertToModelMessages } from "ai";
+import { isContextPartEnvelope, normalizePartsForPersistence, } from "./context.parts.js";
 export const INPUT_ITEM_TYPE = "input";
 export const OUTPUT_ITEM_TYPE = "output";
 export const INPUT_TEXT_ITEM_TYPE = INPUT_ITEM_TYPE;
 export const WEB_CHANNEL = "web";
 export const AGENT_CHANNEL = "whatsapp";
 export const EMAIL_CHANNEL = "email";
+function asRecord(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    return value;
+}
+function isContextOutputContentPart(value) {
+    const record = asRecord(value);
+    return Boolean(record && typeof record.type === "string");
+}
+export function isContextOutputPart(value) {
+    const record = asRecord(value);
+    if (!record || typeof record.type !== "string") {
+        return false;
+    }
+    if (record.type === "json") {
+        return "value" in record;
+    }
+    if (record.type === "content") {
+        return Array.isArray(record.value) && record.value.every(isContextOutputContentPart);
+    }
+    return false;
+}
+export function normalizeContextOutputPart(value) {
+    if (isContextOutputPart(value)) {
+        return value;
+    }
+    return {
+        type: "json",
+        value,
+    };
+}
+function isToolUIPart(value) {
+    const record = asRecord(value);
+    return Boolean(record && typeof record.type === "string" && record.type.startsWith("tool-"));
+}
+function readToolNameFromPart(part) {
+    return String(part.type).split("-").slice(1).join("-");
+}
+function stripDataUrlPrefix(value) {
+    return value.replace(/^data:[^;]+;base64,/i, "");
+}
+function asCanonicalParts(parts) {
+    return normalizePartsForPersistence(parts);
+}
+function contentBlockToPrimaryUiParts(block) {
+    if (block.type === "text") {
+        return [{ type: "text", text: block.text }];
+    }
+    if (block.type === "file") {
+        const url = typeof block.url === "string" && block.url.length > 0
+            ? block.url
+            : typeof block.data === "string" && block.data.length > 0
+                ? block.data.startsWith("data:")
+                    ? block.data
+                    : `data:${block.mediaType};base64,${block.data}`
+                : typeof block.fileId === "string" && block.fileId.length > 0
+                    ? block.fileId
+                    : "";
+        if (!url) {
+            return [];
+        }
+        return [
+            {
+                type: "file",
+                mediaType: block.mediaType,
+                filename: block.filename,
+                url,
+            },
+        ];
+    }
+    if (block.type === "json") {
+        return [
+            {
+                type: "text",
+                text: JSON.stringify(block.value, null, 2),
+            },
+        ];
+    }
+    if (block.type === "source-url") {
+        return [
+            {
+                type: "source-url",
+                sourceId: block.sourceId,
+                url: block.url,
+                title: block.title,
+            },
+        ];
+    }
+    if (block.type === "source-document") {
+        return [
+            {
+                type: "source-document",
+                sourceId: block.sourceId,
+                mediaType: block.mediaType,
+                title: block.title,
+                filename: block.filename,
+            },
+        ];
+    }
+    return [];
+}
+function toolCallContentToInput(content) {
+    if (content.length === 0)
+        return undefined;
+    if (content.length === 1) {
+        const first = content[0];
+        if (first.type === "json")
+            return first.value;
+        if (first.type === "text")
+            return first.text;
+        return first;
+    }
+    return content;
+}
+function canonicalPartsToPrimaryUiParts(parts) {
+    const uiParts = [];
+    for (const part of parts) {
+        if (part.type === "content") {
+            uiParts.push(...part.content.flatMap((block) => contentBlockToPrimaryUiParts(block)));
+            continue;
+        }
+        if (part.type === "reasoning") {
+            const text = part.content
+                .filter((block) => block.type === "text")
+                .map((block) => block.text)
+                .join("\n\n");
+            if (text.trim()) {
+                uiParts.push({
+                    type: "reasoning",
+                    text,
+                    state: part.state,
+                });
+            }
+            continue;
+        }
+        if (part.type === "source") {
+            uiParts.push(...part.content.flatMap((block) => contentBlockToPrimaryUiParts(block)));
+            continue;
+        }
+        if (part.type === "tool-call") {
+            uiParts.push({
+                type: `tool-${part.toolName}`,
+                toolCallId: part.toolCallId,
+                state: part.state ?? "input-available",
+                input: toolCallContentToInput(part.content),
+            });
+        }
+    }
+    return uiParts;
+}
+function canonicalToolResultContentToOutput(content) {
+    if (content.length === 1 && content[0]?.type === "json") {
+        return {
+            type: "json",
+            value: content[0].value,
+        };
+    }
+    return {
+        type: "content",
+        value: content.map((block) => {
+            if (block.type === "text") {
+                return {
+                    type: "text",
+                    text: block.text,
+                };
+            }
+            if (block.type === "file") {
+                if (block.mediaType.startsWith("image/") &&
+                    typeof block.data === "string" &&
+                    block.data.length > 0) {
+                    return {
+                        type: "image-data",
+                        data: stripDataUrlPrefix(block.data),
+                        mediaType: block.mediaType,
+                        filename: block.filename,
+                    };
+                }
+                return {
+                    type: "file",
+                    mediaType: block.mediaType,
+                    filename: block.filename,
+                    data: typeof block.data === "string" && block.data.length > 0
+                        ? block.data
+                        : typeof block.url === "string" && block.url.length > 0
+                            ? block.url
+                            : block.fileId,
+                };
+            }
+            if (block.type === "json") {
+                return {
+                    type: "text",
+                    text: JSON.stringify(block.value, null, 2),
+                };
+            }
+            return {
+                type: "text",
+                text: JSON.stringify(block),
+            };
+        }),
+    };
+}
+function canonicalToolPartsToModelMessages(parts) {
+    const toolInputs = new Map();
+    const toolResults = [];
+    for (const part of parts) {
+        if (part.type === "tool-call") {
+            toolInputs.set(part.toolCallId, toolCallContentToInput(part.content));
+            continue;
+        }
+        if (part.type !== "tool-result") {
+            continue;
+        }
+        if (part.state === "output-error") {
+            const text = part.content
+                .filter((block) => block.type === "text")
+                .map((block) => block.text)
+                .join("\n\n");
+            toolResults.push({
+                type: "tool-error",
+                toolCallId: part.toolCallId,
+                toolName: part.toolName,
+                input: toolInputs.get(part.toolCallId),
+                error: text || "Tool execution failed.",
+            });
+            continue;
+        }
+        toolResults.push({
+            type: "tool-result",
+            toolCallId: part.toolCallId,
+            toolName: part.toolName,
+            output: canonicalToolResultContentToOutput(part.content),
+        });
+    }
+    if (toolResults.length === 0) {
+        return [];
+    }
+    return [
+        {
+            role: "tool",
+            content: toolResults,
+        },
+    ];
+}
+function canonicalPartsToModelMessages(role, parts) {
+    const uiMessage = {
+        id: "canonical-item",
+        role,
+        parts: canonicalPartsToPrimaryUiParts(parts),
+    };
+    return removeEmptyToolMessages(convertToModelMessages([uiMessage]));
+}
+function normalizeAssistantPartsForModel(parts) {
+    return parts
+        .map((part) => {
+        if (!isToolUIPart(part)) {
+            return part;
+        }
+        const next = {
+            ...part,
+            state: part.state === "output-available" || part.state === "output-error"
+                ? "input-available"
+                : part.state,
+        };
+        delete next.output;
+        delete next.errorText;
+        return next;
+    })
+        .filter(Boolean);
+}
+function buildToolResultContent(parts) {
+    const toolContent = [];
+    for (const part of parts) {
+        if (!isToolUIPart(part)) {
+            continue;
+        }
+        const toolCallId = typeof part.toolCallId === "string" ? part.toolCallId : "";
+        const toolName = readToolNameFromPart(part);
+        if (!toolCallId || !toolName) {
+            continue;
+        }
+        if (part.state === "output-available") {
+            toolContent.push({
+                type: "tool-result",
+                toolCallId,
+                toolName,
+                output: normalizeContextOutputPart(part.output),
+            });
+            continue;
+        }
+        if (part.state === "output-error") {
+            toolContent.push({
+                type: "tool-error",
+                toolCallId,
+                toolName,
+                input: part.input,
+                error: typeof part.errorText === "string" && part.errorText.trim().length > 0
+                    ? part.errorText
+                    : "Tool execution failed.",
+            });
+        }
+    }
+    return toolContent;
+}
+function removeEmptyToolMessages(messages) {
+    return messages.filter((message) => {
+        if (message.role !== "tool") {
+            return true;
+        }
+        return Array.isArray(message.content) ? message.content.length > 0 : true;
+    });
+}
 export function createUserItemFromUIMessages(messages) {
     if (!Array.isArray(messages) || messages.length === 0) {
         throw new Error("Missing messages to create item");
@@ -15,7 +327,7 @@ export function createUserItemFromUIMessages(messages) {
         type: INPUT_ITEM_TYPE,
         channel: WEB_CHANNEL,
         content: {
-            parts: lastMessage.parts,
+            parts: asCanonicalParts(lastMessage.parts),
         },
         createdAt: new Date().toISOString(),
     };
@@ -30,16 +342,17 @@ export function createAssistantItemFromUIMessages(itemId, messages) {
         type: OUTPUT_ITEM_TYPE,
         channel: WEB_CHANNEL,
         content: {
-            parts: lastMessage.parts,
+            parts: asCanonicalParts(lastMessage.parts),
         },
         createdAt: new Date().toISOString(),
     };
 }
 export function convertToUIMessage(item) {
     const role = item.type === INPUT_ITEM_TYPE ? "user" : "assistant";
-    const parts = Array.isArray(item.content.parts)
-        ? item.content.parts
-        : [];
+    const rawParts = Array.isArray(item.content.parts) ? item.content.parts : [];
+    const parts = rawParts.every(isContextPartEnvelope)
+        ? canonicalPartsToPrimaryUiParts(rawParts)
+        : rawParts;
     return {
         id: item.id,
         role,
@@ -67,8 +380,40 @@ export async function convertItemsToModelMessages(items) {
     return results.flat();
 }
 export async function convertItemToModelMessages(item) {
-    const message = convertToUIMessage(item);
-    return convertToModelMessages([message]);
+    const role = item.type === INPUT_ITEM_TYPE ? "user" : "assistant";
+    const rawParts = Array.isArray(item.content.parts) ? item.content.parts : [];
+    const canonicalParts = asCanonicalParts(rawParts);
+    if (canonicalParts.length > 0) {
+        const primary = await canonicalPartsToModelMessages(role, canonicalParts);
+        if (role !== "assistant") {
+            return primary;
+        }
+        return [
+            ...primary,
+            ...canonicalToolPartsToModelMessages(canonicalParts),
+        ];
+    }
+    const assistantParts = normalizeAssistantPartsForModel(rawParts);
+    const message = {
+        id: item.id,
+        role,
+        parts: assistantParts,
+    };
+    const modelMessages = removeEmptyToolMessages(await convertToModelMessages([message]));
+    if (role !== "assistant") {
+        return modelMessages;
+    }
+    const toolContent = buildToolResultContent(rawParts);
+    if (toolContent.length === 0) {
+        return modelMessages;
+    }
+    return [
+        ...modelMessages,
+        {
+            role: "tool",
+            content: toolContent,
+        },
+    ];
 }
 function normalizeModelMessageContentToParts(content) {
     if (Array.isArray(content))