@ekairos/thread 1.22.3 → 1.22.4-beta.feature-thread-unify.0

package/dist/thread.builder.js

@@ -1,5 +1,8 @@
 import { Thread, } from "./thread.engine.js";
 import { registerThread } from "./thread.registry.js";
+function isDynamicModelSelector(model) {
+    return typeof model === "function" && model.length >= 1;
+}
 export function thread(config) {
     class FunctionalThread extends Thread {
         constructor() {
@@ -28,7 +31,7 @@ export function thread(config) {
             throw new Error("Thread config is missing actions()");
         }
         getModel(context, env) {
-            if (typeof config.model === "function")
+            if (isDynamicModelSelector(config.model))
                 return config.model(context, env);
             return config.model ?? super.getModel(context, env);
         }

package/dist/thread.contract.d.ts

@@ -0,0 +1,45 @@
+export type Transition<From extends string, To extends string> = {
+    from: From;
+    to: To;
+};
+export declare const THREAD_STATUSES: readonly ["open", "streaming", "closed", "failed"];
+export type ThreadThreadStatus = (typeof THREAD_STATUSES)[number];
+export declare const THREAD_CONTEXT_STATUSES: readonly ["open", "streaming", "closed"];
+export type ThreadContextStatus = (typeof THREAD_CONTEXT_STATUSES)[number];
+export declare const THREAD_EXECUTION_STATUSES: readonly ["executing", "completed", "failed"];
+export type ThreadExecutionStatus = (typeof THREAD_EXECUTION_STATUSES)[number];
+export declare const THREAD_STEP_STATUSES: readonly ["running", "completed", "failed"];
+export type ThreadStepStatus = (typeof THREAD_STEP_STATUSES)[number];
+export declare const THREAD_ITEM_STATUSES: readonly ["stored", "pending", "completed"];
+export type ThreadItemStatus = (typeof THREAD_ITEM_STATUSES)[number];
+export declare const THREAD_ITEM_TYPES: readonly ["input_text", "output_text", "ekairos:system"];
+export type ThreadItemType = (typeof THREAD_ITEM_TYPES)[number];
+export declare const THREAD_CHANNELS: readonly ["web", "whatsapp", "email"];
+export type ThreadChannel = (typeof THREAD_CHANNELS)[number];
+export declare const THREAD_TRACE_EVENT_KINDS: readonly ["workflow.run", "workflow.step", "thread.run", "thread.context", "thread.execution", "thread.item", "thread.review", "thread.step", "thread.part", "thread.llm"];
+export type ThreadTraceEventKind = (typeof THREAD_TRACE_EVENT_KINDS)[number];
+export declare const THREAD_STREAM_CHUNK_TYPES: readonly ["data-context-id", "data-context-substate", "data-thread-ping", "tool-output-available", "tool-output-error", "finish"];
+export type ThreadStreamChunkType = (typeof THREAD_STREAM_CHUNK_TYPES)[number];
+export declare const THREAD_CONTEXT_SUBSTATE_KEYS: readonly ["actions"];
+export type ThreadContextSubstateKey = (typeof THREAD_CONTEXT_SUBSTATE_KEYS)[number];
+export type ThreadTransition = Transition<"open" | "streaming" | "failed", "open" | "streaming" | "closed" | "failed">;
+export type ContextTransition = Transition<"open" | "streaming", "streaming" | "open" | "closed">;
+export type ExecutionTransition = Transition<"executing", "completed" | "failed">;
+export type StepTransition = Transition<"running", "completed" | "failed">;
+export type ItemTransition = Transition<"stored" | "pending", "pending" | "completed">;
+export declare const THREAD_THREAD_TRANSITIONS: readonly ThreadTransition[];
+export declare const THREAD_CONTEXT_TRANSITIONS: readonly ContextTransition[];
+export declare const THREAD_EXECUTION_TRANSITIONS: readonly ExecutionTransition[];
+export declare const THREAD_STEP_TRANSITIONS: readonly StepTransition[];
+export declare const THREAD_ITEM_TRANSITIONS: readonly ItemTransition[];
+export declare function canThreadTransition(from: string, to: string): boolean;
+export declare function canContextTransition(from: string, to: string): boolean;
+export declare function canExecutionTransition(from: string, to: string): boolean;
+export declare function canStepTransition(from: string, to: string): boolean;
+export declare function canItemTransition(from: string, to: string): boolean;
+export declare function assertThreadTransition(from: string, to: string): void;
+export declare function assertContextTransition(from: string, to: string): void;
+export declare function assertExecutionTransition(from: string, to: string): void;
+export declare function assertStepTransition(from: string, to: string): void;
+export declare function assertItemTransition(from: string, to: string): void;
+export declare function assertThreadPartKey(stepId: string, idx: number, key: string): void;

package/dist/thread.contract.js

@@ -0,0 +1,98 @@
+export const THREAD_STATUSES = ["open", "streaming", "closed", "failed"];
+export const THREAD_CONTEXT_STATUSES = ["open", "streaming", "closed"];
+export const THREAD_EXECUTION_STATUSES = ["executing", "completed", "failed"];
+export const THREAD_STEP_STATUSES = ["running", "completed", "failed"];
+export const THREAD_ITEM_STATUSES = ["stored", "pending", "completed"];
+export const THREAD_ITEM_TYPES = ["input_text", "output_text", "ekairos:system"];
+export const THREAD_CHANNELS = ["web", "whatsapp", "email"];
+export const THREAD_TRACE_EVENT_KINDS = [
+    "workflow.run",
+    "workflow.step",
+    "thread.run",
+    "thread.context",
+    "thread.execution",
+    "thread.item",
+    "thread.review",
+    "thread.step",
+    "thread.part",
+    "thread.llm",
+];
+export const THREAD_STREAM_CHUNK_TYPES = [
+    "data-context-id",
+    "data-context-substate",
+    "data-thread-ping",
+    "tool-output-available",
+    "tool-output-error",
+    "finish",
+];
+export const THREAD_CONTEXT_SUBSTATE_KEYS = ["actions"];
+export const THREAD_THREAD_TRANSITIONS = [
+    { from: "open", to: "streaming" },
+    { from: "streaming", to: "open" },
+    { from: "streaming", to: "closed" },
+    { from: "streaming", to: "failed" },
+    { from: "failed", to: "open" },
+];
+export const THREAD_CONTEXT_TRANSITIONS = [
+    { from: "open", to: "streaming" },
+    { from: "streaming", to: "open" },
+    { from: "open", to: "closed" },
+    { from: "streaming", to: "closed" },
+];
+export const THREAD_EXECUTION_TRANSITIONS = [
+    { from: "executing", to: "completed" },
+    { from: "executing", to: "failed" },
+];
+export const THREAD_STEP_TRANSITIONS = [
+    { from: "running", to: "completed" },
+    { from: "running", to: "failed" },
+];
+export const THREAD_ITEM_TRANSITIONS = [
+    { from: "stored", to: "pending" },
+    { from: "stored", to: "completed" },
+    { from: "pending", to: "completed" },
+];
+function canTransition(transitions, from, to) {
+    return transitions.some((transition) => transition.from === from && transition.to === to);
+}
+function assertTransition(transitions, from, to, entity) {
+    if (!canTransition(transitions, from, to)) {
+        throw new Error(`Invalid ${entity} transition: ${from} -> ${to}`);
+    }
+}
+export function canThreadTransition(from, to) {
+    return canTransition(THREAD_THREAD_TRANSITIONS, from, to);
+}
+export function canContextTransition(from, to) {
+    return canTransition(THREAD_CONTEXT_TRANSITIONS, from, to);
+}
+export function canExecutionTransition(from, to) {
+    return canTransition(THREAD_EXECUTION_TRANSITIONS, from, to);
+}
+export function canStepTransition(from, to) {
+    return canTransition(THREAD_STEP_TRANSITIONS, from, to);
+}
+export function canItemTransition(from, to) {
+    return canTransition(THREAD_ITEM_TRANSITIONS, from, to);
+}
+export function assertThreadTransition(from, to) {
+    assertTransition(THREAD_THREAD_TRANSITIONS, from, to, "thread.status");
+}
+export function assertContextTransition(from, to) {
+    assertTransition(THREAD_CONTEXT_TRANSITIONS, from, to, "context.status");
+}
+export function assertExecutionTransition(from, to) {
+    assertTransition(THREAD_EXECUTION_TRANSITIONS, from, to, "execution.status");
+}
+export function assertStepTransition(from, to) {
+    assertTransition(THREAD_STEP_TRANSITIONS, from, to, "step.status");
+}
+export function assertItemTransition(from, to) {
+    assertTransition(THREAD_ITEM_TRANSITIONS, from, to, "item.status");
+}
+export function assertThreadPartKey(stepId, idx, key) {
+    const expected = `${stepId}:${idx}`;
+    if (key !== expected) {
+        throw new Error(`Invalid thread_parts.key: expected "${expected}" got "${key}"`);
+    }
+}

package/dist/thread.d.ts

@@ -1,3 +1,3 @@
 export { Thread, type ThreadOptions, type ThreadStreamOptions, type ShouldContinue, type ThreadShouldContinueArgs, } from "./thread.engine.js";
 export { thread, createThread, type ThreadConfig, type ThreadInstance, type RegistrableThreadBuilder, } from "./thread.builder.js";
-export { createAiSdkReactor, type CreateAiSdkReactorOptions, type ThreadReactor, type ThreadReactorParams, type ThreadReactionResult, type ThreadReactionToolCall, type ThreadReactionLLM, } from "./thread.reactor.js";
+export { createAiSdkReactor, createScriptedReactor, type CreateAiSdkReactorOptions, type CreateScriptedReactorOptions, type ScriptedReactorStep, type ThreadReactor, type ThreadReactorParams, type ThreadReactionResult, type ThreadReactionToolCall, type ThreadReactionLLM, } from "./thread.reactor.js";

package/dist/thread.engine.d.ts

@@ -66,7 +66,7 @@ export interface ThreadStreamOptions {
  * - `function`: a function that returns a model instance. For Workflow compatibility, this should
  *   be a `"use-step"` function (so it can be serialized by reference).
  */
-export type ThreadModelInit = string | (() => Promise<any>) | any;
+export type ThreadModelInit = string | (() => Promise<any>);
 export type ThreadReactParams<Env extends ThreadEnvironment = ThreadEnvironment> = {
     env: Env;
     /**

package/dist/thread.engine.js

@@ -100,6 +100,15 @@ export class Thread {
                 });
             }
         }
+        // Reactor/steps always receive a stream argument.
+        // In silent mode (or when no workflow writable is available), we use an in-memory sink.
+        if (!writable) {
+            writable = new WritableStream({
+                write() {
+                    // noop
+                },
+            });
+        }
         const contextSelector = params.contextIdentifier?.id
             ? { id: String(params.contextIdentifier.id) }
             : params.contextIdentifier?.key
@@ -208,6 +217,13 @@ export class Thread {
                 // 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 assistantEventEffective = {
+                    ...assistantEvent,
+                    content: {
+                        ...(assistantEvent?.content ?? {}),
+                        parts: stepParts,
+                    },
+                };
                 await saveThreadPartsStep({
                     env: params.env,
                     stepId: stepCreate.stepId,
@@ -219,7 +235,7 @@ export class Thread {
                 // Persist/append the aggregated reaction event (stable `reactionEventId` for the execution).
                 if (!reactionEvent) {
                     const reactionPayload = {
-                        ...assistantEvent,
+                        ...assistantEventEffective,
                         status: "pending",
                     };
                     reactionEvent = await saveReactionItem(params.env, contextSelector, reactionPayload, {
@@ -229,21 +245,26 @@ export class Thread {
                     });
                 }
                 else {
-                    reactionEvent = await updateItem(params.env, reactionEvent.id, {
+                    const existingReactionParts = Array.isArray(reactionEvent.content?.parts)
+                        ? reactionEvent.content.parts
+                        : [];
+                    const nextAssistantParts = Array.isArray(assistantEventEffective.content?.parts)
+                        ? assistantEventEffective.content.parts
+                        : [];
+                    const nextReactionEvent = {
                         ...reactionEvent,
                         content: {
-                            parts: [
-                                ...(reactionEvent?.content?.parts ?? []),
-                                ...(assistantEvent?.content?.parts ?? []),
-                            ],
+                            ...reactionEvent.content,
+                            parts: [...existingReactionParts, ...nextAssistantParts],
                         },
                         status: "pending",
-                    }, { executionId, contextId: String(currentContext.id) });
+                    };
+                    reactionEvent = await updateItem(params.env, reactionEvent.id, nextReactionEvent, { executionId, contextId: String(currentContext.id) });
                 }
-                story.opts.onEventCreated?.(assistantEvent);
+                story.opts.onEventCreated?.(assistantEventEffective);
                 // Done: no tool calls requested by the model
                 if (!toolCalls.length) {
-                    const endResult = await story.callOnEnd(assistantEvent);
+                    const endResult = await story.callOnEnd(assistantEventEffective);
                     if (endResult) {
                         // Mark iteration step completed (no tools)
                         await updateThreadStep({
@@ -261,7 +282,7 @@ export class Thread {
                         });
                         // Mark reaction event completed
                         await updateItem(params.env, reactionEventId, {
-                            ...reactionEvent,
+                            ...(reactionEvent ?? assistantEventEffective),
                             status: "completed",
                         }, { executionId, contextId: String(currentContext.id) });
                         await completeExecution(params.env, contextSelector, executionId, "completed");
@@ -359,7 +380,9 @@ export class Thread {
                 }
                 // Merge tool results into persisted parts (so next LLM call can see them)
                 if (reactionEvent) {
-                    let parts = reactionEvent?.content?.parts ?? [];
+                    let parts = Array.isArray(reactionEvent.content?.parts)
+                        ? [...reactionEvent.content.parts]
+                        : [];
                     for (const r of executionResults) {
                         parts = applyToolExecutionResultToParts(parts, r.tc, {
                             success: Boolean(r.success),
@@ -367,11 +390,15 @@ export class Thread {
                             message: r.errorText,
                         });
                     }
-                    reactionEvent = await updateItem(params.env, reactionEventId, {
+                    const nextReactionEvent = {
                         ...reactionEvent,
-                        content: { parts },
+                        content: {
+                            ...reactionEvent.content,
+                            parts,
+                        },
                         status: "pending",
-                    }, { executionId, contextId: String(currentContext.id) });
+                    };
+                    reactionEvent = await updateItem(params.env, reactionEventId, nextReactionEvent, { executionId, contextId: String(currentContext.id) });
                 }
                 // Callback for observability/integration
                 for (const r of executionResults) {
@@ -390,8 +417,8 @@ export class Thread {
                 const continueLoop = await story.shouldContinue({
                     env: params.env,
                     context: updatedContext,
-                    reactionEvent: reactionEvent ?? assistantEvent,
-                    assistantEvent,
+                    reactionEvent: reactionEvent ?? assistantEventEffective,
+                    assistantEvent: assistantEventEffective,
                     toolCalls,
                     toolExecutionResults: executionResults,
                 });
@@ -411,7 +438,7 @@ export class Thread {
                 });
                 if (continueLoop === false) {
                     await updateItem(params.env, reactionEventId, {
-                        ...reactionEvent,
+                        ...(reactionEvent ?? assistantEventEffective),
                         status: "completed",
                     }, { executionId, contextId: String(currentContext.id) });
                     await completeExecution(params.env, contextSelector, executionId, "completed");

package/dist/thread.events.js

@@ -46,10 +46,13 @@ export function convertToUIMessage(item) {
     else {
         role = "assistant";
     }
+    const parts = Array.isArray(item.content.parts)
+        ? item.content.parts
+        : [];
     return {
         id: item.id,
         role: role,
-        parts: item.content.parts,
+        parts,
         metadata: {
             channel: item.channel,
             type: item.type,
@@ -76,6 +79,18 @@ export async function convertItemToModelMessages(item) {
     const message = convertToUIMessage(item);
     return convertToModelMessages([message]);
 }
+function normalizeModelMessageContentToParts(content) {
+    if (Array.isArray(content))
+        return content;
+    if (typeof content === "string") {
+        if (!content.trim())
+            return [];
+        return [{ type: "text", text: content }];
+    }
+    if (content === null || content === undefined)
+        return [];
+    return [content];
+}
 export function convertModelMessageToItem(itemId, message) {
     let type;
     switch (message.message.role) {
@@ -98,7 +113,7 @@ export function convertModelMessageToItem(itemId, message) {
         type: type,
         channel: WEB_CHANNEL,
         content: {
-            parts: message.message.content,
+            parts: normalizeModelMessageContentToParts(message.message.content),
         },
         createdAt: message.timestamp.toISOString(),
     };

package/dist/thread.js

@@ -4,4 +4,4 @@ Thread, } from "./thread.engine.js";
 export { 
 // builder
 thread, createThread, } from "./thread.builder.js";
-export { createAiSdkReactor, } from "./thread.reactor.js";
+export { createAiSdkReactor, createScriptedReactor, } from "./thread.reactor.js";

package/dist/thread.reactor.d.ts

@@ -1,82 +1,3 @@
-import type { ModelMessage, UIMessageChunk } from "ai";
-import type { ThreadEnvironment } from "./thread.config.js";
-import type { ThreadModelInit } from "./thread.engine.js";
-import type { ContextIdentifier, StoredContext, ThreadItem } from "./thread.store.js";
-import type { SerializableToolForModel } from "./tools-to-model-tools.js";
-export type ThreadReactionToolCall = {
-    toolCallId: string;
-    toolName: string;
-    args: unknown;
-};
-export type ThreadReactionLLM = {
-    provider?: string;
-    model?: string;
-    promptTokens?: number;
-    promptTokensCached?: number;
-    promptTokensUncached?: number;
-    completionTokens?: number;
-    totalTokens?: number;
-    latencyMs?: number;
-    rawUsage?: unknown;
-    rawProviderMetadata?: unknown;
-};
-export type ThreadReactionResult = {
-    assistantEvent: ThreadItem;
-    toolCalls: ThreadReactionToolCall[];
-    messagesForModel: ModelMessage[];
-    llm?: ThreadReactionLLM;
-};
-export type ThreadReactorParams<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment> = {
-    env: Env;
-    context: StoredContext<Context>;
-    contextIdentifier: ContextIdentifier;
-    triggerEvent: ThreadItem;
-    model: ThreadModelInit;
-    systemPrompt: string;
-    actions: Record<string, unknown>;
-    toolsForModel: Record<string, SerializableToolForModel>;
-    eventId: string;
-    executionId: string;
-    contextId: string;
-    stepId: string;
-    iteration: number;
-    maxModelSteps: number;
-    sendStart: boolean;
-    silent: boolean;
-    writable?: WritableStream<UIMessageChunk>;
-};
-export type ThreadReactor<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment> = (params: ThreadReactorParams<Context, Env>) => Promise<ThreadReactionResult>;
-export type CreateAiSdkReactorOptions<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment, Config = unknown> = {
-    resolveConfig?: (params: {
-        env: Env;
-        context: StoredContext<Context>;
-        contextIdentifier: ContextIdentifier;
-        triggerEvent: ThreadItem;
-        model: ThreadModelInit;
-        eventId: string;
-        executionId: string;
-        contextId: string;
-        stepId: string;
-        iteration: number;
-    }) => Promise<Config> | Config;
-    selectModel?: (params: {
-        env: Env;
-        context: StoredContext<Context>;
-        triggerEvent: ThreadItem;
-        baseModel: ThreadModelInit;
-        config: Config;
-    }) => Promise<ThreadModelInit> | ThreadModelInit;
-    selectMaxModelSteps?: (params: {
-        env: Env;
-        context: StoredContext<Context>;
-        triggerEvent: ThreadItem;
-        baseMaxModelSteps: number;
-        config: Config;
-    }) => Promise<number> | number;
-};
-/**
- * Default reactor for Thread: Vercel AI SDK (`streamText`) with tool-call extraction.
- *
- * This keeps current behavior and can be replaced per-thread using `.reactor(...)`.
- */
-export declare function createAiSdkReactor<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment, Config = unknown>(options?: CreateAiSdkReactorOptions<Context, Env, Config>): ThreadReactor<Context, Env>;
+export { createAiSdkReactor, type CreateAiSdkReactorOptions, } from "./reactors/ai-sdk.reactor.js";
+export { createScriptedReactor, type CreateScriptedReactorOptions, type ScriptedReactorStep, } from "./reactors/scripted.reactor.js";
+export type { ThreadReactor, ThreadReactorParams, ThreadReactionResult, ThreadReactionToolCall, ThreadReactionLLM, } from "./reactors/types.js";

package/dist/thread.reactor.js

@@ -1,65 +1,2 @@
-import { executeReaction } from "./steps/reaction.steps.js";
-/**
- * Default reactor for Thread: Vercel AI SDK (`streamText`) with tool-call extraction.
- *
- * This keeps current behavior and can be replaced per-thread using `.reactor(...)`.
- */
-export function createAiSdkReactor(options) {
-    return async (params) => {
-        let config;
-        if (options?.resolveConfig) {
-            config = await options.resolveConfig({
-                env: params.env,
-                context: params.context,
-                contextIdentifier: params.contextIdentifier,
-                triggerEvent: params.triggerEvent,
-                model: params.model,
-                eventId: params.eventId,
-                executionId: params.executionId,
-                contextId: params.contextId,
-                stepId: params.stepId,
-                iteration: params.iteration,
-            });
-        }
-        const model = options?.selectModel && config !== undefined
-            ? await options.selectModel({
-                env: params.env,
-                context: params.context,
-                triggerEvent: params.triggerEvent,
-                baseModel: params.model,
-                config,
-            })
-            : params.model;
-        const maxSteps = options?.selectMaxModelSteps && config !== undefined
-            ? await options.selectMaxModelSteps({
-                env: params.env,
-                context: params.context,
-                triggerEvent: params.triggerEvent,
-                baseMaxModelSteps: params.maxModelSteps,
-                config,
-            })
-            : params.maxModelSteps;
-        const result = await executeReaction({
-            env: params.env,
-            contextIdentifier: params.contextIdentifier,
-            model,
-            system: params.systemPrompt,
-            tools: params.toolsForModel,
-            eventId: params.eventId,
-            iteration: params.iteration,
-            maxSteps,
-            sendStart: params.sendStart,
-            silent: params.silent,
-            writable: params.writable,
-            executionId: params.executionId,
-            contextId: params.contextId,
-            stepId: params.stepId,
-        });
-        return {
-            assistantEvent: result.assistantEvent,
-            toolCalls: result.toolCalls,
-            messagesForModel: result.messagesForModel,
-            llm: result.llm,
-        };
-    };
-}
+export { createAiSdkReactor, } from "./reactors/ai-sdk.reactor.js";
+export { createScriptedReactor, } from "./reactors/scripted.reactor.js";

package/dist/thread.store.d.ts

@@ -1,4 +1,5 @@
 import type { ModelMessage } from "ai";
+import type { ThreadThreadStatus, ThreadContextStatus, ThreadExecutionStatus, ThreadStepStatus as ContractThreadStepStatus, ThreadItemStatus, ThreadItemType, ThreadChannel } from "./thread.contract.js";
 /**
  * ## thread.store.ts
  *
@@ -18,8 +19,8 @@ export type ThreadIdentifier = {
     id?: never;
 };
 export type ContextIdentifier = ThreadIdentifier;
-export type ThreadStatus = "open" | "streaming" | "closed" | "failed";
-export type ContextStatus = "open" | "streaming" | "closed";
+export type ThreadStatus = ThreadThreadStatus;
+export type ContextStatus = ThreadContextStatus;
 export type StoredThread = {
     id: string;
     key: string | null;
@@ -39,14 +40,17 @@ export type StoredContext<Context> = {
 };
 export type ThreadItem = {
     id: string;
-    type: string;
-    channel: string;
+    type: ThreadItemType;
+    channel: ThreadChannel;
     createdAt: string;
-    status?: string;
-    content: any;
+    status?: ThreadItemStatus;
+    content: {
+        parts?: unknown[];
+        [key: string]: unknown;
+    };
 };
-export type ExecutionStatus = "executing" | "completed" | "failed";
-export type ThreadStepStatus = "running" | "completed" | "failed";
+export type ExecutionStatus = ThreadExecutionStatus;
+export type ThreadStepStatus = ContractThreadStepStatus;
 export type ThreadStep = {
     id: string;
     createdAt: Date;