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

package/dist/index.d.ts

@@ -1,9 +1,13 @@
-export { thread, createThread, createAiSdkReactor, type CreateAiSdkReactorOptions, type ThreadConfig, type ThreadInstance, type ThreadOptions, type ThreadStreamOptions, type ThreadReactor, type ThreadReactorParams, type ThreadReactionResult, type ThreadReactionToolCall, type ThreadReactionLLM, Thread, type RegistrableThreadBuilder, } from "./thread.js";
+export { thread, createThread, createAiSdkReactor, createScriptedReactor, type CreateAiSdkReactorOptions, type CreateScriptedReactorOptions, type ScriptedReactorStep, type ThreadConfig, type ThreadInstance, type ThreadOptions, type ThreadStreamOptions, type ThreadReactor, type ThreadReactorParams, type ThreadReactionResult, type ThreadReactionToolCall, type ThreadReactionLLM, Thread, type RegistrableThreadBuilder, } from "./thread.js";
 export type { ThreadStore, ThreadIdentifier, ContextIdentifier, StoredThread, StoredContext, ThreadItem, } from "./thread.store.js";
 export type { WireDate, ThreadMirrorContext, ThreadMirrorExecution, ThreadMirrorWrite, ThreadMirrorRequest, } from "./mirror.js";
 export { registerThread, getThread, getThreadFactory, hasThread, listThreads, type ThreadKey, } from "./thread.registry.js";
 export { threadDomain } from "./schema.js";
 export { didToolExecute, extractToolCallsFromParts } from "./thread.toolcalls.js";
 export { INPUT_TEXT_ITEM_TYPE, OUTPUT_TEXT_ITEM_TYPE, SYSTEM_TEXT_ITEM_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserItemFromUIMessages, createAssistantItemFromUIMessages, convertToUIMessage, convertItemToModelMessages, convertItemsToModelMessages, convertModelMessageToItem, type ResponseMessage, } from "./thread.events.js";
+export { THREAD_STATUSES, THREAD_CONTEXT_STATUSES, THREAD_EXECUTION_STATUSES, THREAD_STEP_STATUSES, THREAD_ITEM_STATUSES, THREAD_ITEM_TYPES, THREAD_CHANNELS, THREAD_TRACE_EVENT_KINDS, THREAD_STREAM_CHUNK_TYPES, THREAD_CONTEXT_SUBSTATE_KEYS, THREAD_THREAD_TRANSITIONS, THREAD_CONTEXT_TRANSITIONS, THREAD_EXECUTION_TRANSITIONS, THREAD_STEP_TRANSITIONS, THREAD_ITEM_TRANSITIONS, canThreadTransition, canContextTransition, canExecutionTransition, canStepTransition, canItemTransition, assertThreadTransition, assertContextTransition, assertExecutionTransition, assertStepTransition, assertItemTransition, assertThreadPartKey, } from "./thread.contract.js";
+export type { Transition, ThreadThreadStatus, ThreadContextStatus, ThreadExecutionStatus, ThreadStepStatus, ThreadItemStatus, ThreadItemType, ThreadChannel, ThreadTraceEventKind, ThreadStreamChunkType, ThreadContextSubstateKey, ThreadTransition, ContextTransition, ExecutionTransition, StepTransition, ItemTransition, } from "./thread.contract.js";
 export { DEFAULT_CODEX_TOOL_NAME, DEFAULT_CODEX_MODEL, codexToolInputSchema, buildDefaultCodexNarrative, didCodexToolExecute, createCodexThreadBuilder, type CodexThreadRuntimeMode, type CodexThreadReasoningLevel, type CodexThreadRuntime, type CodexThreadEnv, type CodexToolInput, type CodexToolOutput, type CodexExecuteArgs, type CodexThreadBuilderConfig, type CodexThreadBuilder, } from "./codex.js";
 export { useThread, type ThreadSnapshot, type ThreadStreamChunk, type UseThreadOptions, } from "./react.js";
+export { parseThreadStreamEvent, assertThreadStreamTransitions, validateThreadStreamTimeline, } from "./thread.stream.js";
+export type { ThreadStreamEvent, ContextCreatedEvent, ContextResolvedEvent, ContextStatusChangedEvent, ThreadCreatedEvent, ThreadResolvedEvent, ThreadStatusChangedEvent, ExecutionCreatedEvent, ExecutionStatusChangedEvent, ItemCreatedEvent, ItemStatusChangedEvent, StepCreatedEvent, StepStatusChangedEvent, PartCreatedEvent, PartUpdatedEvent, ChunkEmittedEvent, ThreadFinishedEvent, } from "./thread.stream.js";

package/dist/index.js

@@ -1,9 +1,11 @@
 export { 
 // Thread API
-thread, createThread, createAiSdkReactor, Thread, } from "./thread.js";
+thread, createThread, createAiSdkReactor, createScriptedReactor, Thread, } from "./thread.js";
 export { registerThread, getThread, getThreadFactory, hasThread, listThreads, } from "./thread.registry.js";
 export { threadDomain } from "./schema.js";
 export { didToolExecute, extractToolCallsFromParts } from "./thread.toolcalls.js";
 export { INPUT_TEXT_ITEM_TYPE, OUTPUT_TEXT_ITEM_TYPE, SYSTEM_TEXT_ITEM_TYPE, WEB_CHANNEL, AGENT_CHANNEL, EMAIL_CHANNEL, createUserItemFromUIMessages, createAssistantItemFromUIMessages, convertToUIMessage, convertItemToModelMessages, convertItemsToModelMessages, convertModelMessageToItem, } from "./thread.events.js";
+export { THREAD_STATUSES, THREAD_CONTEXT_STATUSES, THREAD_EXECUTION_STATUSES, THREAD_STEP_STATUSES, THREAD_ITEM_STATUSES, THREAD_ITEM_TYPES, THREAD_CHANNELS, THREAD_TRACE_EVENT_KINDS, THREAD_STREAM_CHUNK_TYPES, THREAD_CONTEXT_SUBSTATE_KEYS, THREAD_THREAD_TRANSITIONS, THREAD_CONTEXT_TRANSITIONS, THREAD_EXECUTION_TRANSITIONS, THREAD_STEP_TRANSITIONS, THREAD_ITEM_TRANSITIONS, canThreadTransition, canContextTransition, canExecutionTransition, canStepTransition, canItemTransition, assertThreadTransition, assertContextTransition, assertExecutionTransition, assertStepTransition, assertItemTransition, assertThreadPartKey, } from "./thread.contract.js";
 export { DEFAULT_CODEX_TOOL_NAME, DEFAULT_CODEX_MODEL, codexToolInputSchema, buildDefaultCodexNarrative, didCodexToolExecute, createCodexThreadBuilder, } from "./codex.js";
 export { useThread, } from "./react.js";
+export { parseThreadStreamEvent, assertThreadStreamTransitions, validateThreadStreamTimeline, } from "./thread.stream.js";

package/dist/react.d.ts

@@ -1,14 +1,15 @@
+import type { ThreadContextStatus, ThreadContextSubstateKey, ThreadThreadStatus } from "./thread.contract.js";
 export type ThreadSnapshot<Context = unknown, Item = Record<string, unknown>> = {
     thread: {
         id: string;
         key: string;
-        status: string;
+        status: ThreadThreadStatus;
         createdAt: string | null;
         updatedAt: string | null;
     };
     context: {
         id: string;
-        status: string;
+        status: ThreadContextStatus;
         content: Context;
         createdAt: string | null;
         updatedAt: string | null;
@@ -24,7 +25,7 @@ export type ThreadStreamChunk = {
 } | {
     type: "data-context-substate";
     data?: {
-        key?: string | null;
+        key?: ThreadContextSubstateKey | null;
     };
     transient?: boolean;
 } | {

package/dist/reactors/ai-sdk.reactor.d.ts

@@ -0,0 +1,38 @@
+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 { ThreadReactor } from "./types.js";
+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>;

package/dist/reactors/ai-sdk.reactor.js

@@ -0,0 +1,65 @@
+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,
+        };
+    };
+}

package/dist/reactors/scripted.reactor.d.ts

@@ -0,0 +1,23 @@
+import type { ModelMessage } from "ai";
+import type { ThreadEnvironment } from "../thread.config.js";
+import type { ThreadItem } from "../thread.store.js";
+import type { ThreadReactionLLM, ThreadReactionToolCall, ThreadReactor, ThreadReactorParams } from "./types.js";
+type ScriptedReactionPayload = {
+    assistantEvent?: Partial<ThreadItem>;
+    toolCalls?: ThreadReactionToolCall[];
+    messagesForModel?: ModelMessage[];
+    llm?: ThreadReactionLLM;
+};
+export type ScriptedReactorStep<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment> = ScriptedReactionPayload | ((params: ThreadReactorParams<Context, Env>) => Promise<ScriptedReactionPayload> | ScriptedReactionPayload);
+export type CreateScriptedReactorOptions<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment> = {
+    steps: ScriptedReactorStep<Context, Env>[];
+    repeatLast?: boolean;
+};
+/**
+ * Deterministic reactor used for tests and local loop iteration.
+ *
+ * - No model/network calls
+ * - Predictable scripted outputs per iteration
+ */
+export declare function createScriptedReactor<Context = unknown, Env extends ThreadEnvironment = ThreadEnvironment>(options: CreateScriptedReactorOptions<Context, Env>): ThreadReactor<Context, Env>;
+export {};

package/dist/reactors/scripted.reactor.js

@@ -0,0 +1,56 @@
+function normalizeScriptedAssistantEvent(params, assistantEvent) {
+    const fallback = {
+        id: params.eventId,
+        type: "output_text",
+        channel: params.triggerEvent.channel,
+        createdAt: new Date().toISOString(),
+        content: { parts: [] },
+    };
+    const mergedContent = {
+        ...fallback.content,
+        ...(assistantEvent?.content ?? {}),
+    };
+    return {
+        ...fallback,
+        ...assistantEvent,
+        id: assistantEvent?.id ?? fallback.id,
+        createdAt: assistantEvent?.createdAt ?? fallback.createdAt,
+        content: mergedContent,
+    };
+}
+/**
+ * Deterministic reactor used for tests and local loop iteration.
+ *
+ * - No model/network calls
+ * - Predictable scripted outputs per iteration
+ */
+export function createScriptedReactor(options) {
+    const steps = Array.isArray(options.steps) ? options.steps : [];
+    if (steps.length === 0) {
+        throw new Error("createScriptedReactor: options.steps must contain at least one step.");
+    }
+    let index = 0;
+    return async (params) => {
+        const hasCurrentStep = index < steps.length;
+        if (!hasCurrentStep && !options.repeatLast) {
+            throw new Error(`createScriptedReactor: no scripted step available at index ${index}. ` +
+                `Provided steps=${steps.length}. Enable repeatLast to reuse the final step.`);
+        }
+        const stepIndex = hasCurrentStep ? index : steps.length - 1;
+        const scriptedStep = steps[stepIndex];
+        if (hasCurrentStep) {
+            index += 1;
+        }
+        const payload = typeof scriptedStep === "function"
+            ? await scriptedStep(params)
+            : scriptedStep;
+        return {
+            assistantEvent: normalizeScriptedAssistantEvent(params, payload.assistantEvent),
+            toolCalls: Array.isArray(payload.toolCalls) ? payload.toolCalls : [],
+            messagesForModel: Array.isArray(payload.messagesForModel)
+                ? payload.messagesForModel
+                : [],
+            llm: payload.llm,
+        };
+    };
+}

package/dist/reactors/types.d.ts

@@ -0,0 +1,48 @@
+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>;

package/dist/reactors/types.js

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

package/dist/steps/do-thread-stream-step.d.ts

@@ -1,6 +1,7 @@
 import type { ModelMessage } from "ai";
 import type { ThreadItem } from "../thread.store.js";
 import type { SerializableToolForModel } from "../tools-to-model-tools.js";
+import type { ThreadModelInit } from "../thread.engine.js";
 /**
  * Runs a single LLM streaming step as a Workflow step.
  *
@@ -9,7 +10,7 @@ import type { SerializableToolForModel } from "../tools-to-model-tools.js";
  * - Returns the assistant event + extracted tool calls for the workflow loop.
  */
 export declare function doThreadStreamStep(params: {
-    model: any;
+    model: ThreadModelInit;
     system: string;
     messages: ModelMessage[];
     tools: Record<string, SerializableToolForModel>;

package/dist/steps/do-thread-stream-step.js

@@ -11,7 +11,7 @@ export async function doThreadStreamStep(params) {
     const { getWritable } = await import("workflow");
     const writable = getWritable();
     const { jsonSchema, gateway, smoothStream, stepCountIs, streamText } = await import("ai");
-    const { extractToolCallsFromParts } = await import("@ekairos/thread");
+    const { extractToolCallsFromParts } = await import("../thread.toolcalls.js");
     // Match DurableAgent's model init behavior:
     // - string => AI Gateway model id, resolved via `gateway(...)` in the step runtime
     // - function => model factory (should be a `"use step"` function for workflow serialization)
@@ -19,7 +19,9 @@ export async function doThreadStreamStep(params) {
         ? gateway(params.model)
         : typeof params.model === "function"
             ? await params.model()
-            : params.model;
+            : (() => {
+                throw new Error("Invalid model init passed to doThreadStreamStep. Expected a model id string or an async model factory.");
+            })();
     // IMPORTANT:
     // `streamText` expects tools in the AI SDK ToolSet shape, where `inputSchema` is a Schema-like value.
     // We pass plain JSON schema objects across the step boundary (serializable), then wrap them here with

package/dist/steps/reaction.steps.d.ts

@@ -1,5 +1,6 @@
 import type { ModelMessage, UIMessageChunk } from "ai";
 import type { ThreadEnvironment } from "../thread.config.js";
+import type { ThreadModelInit } from "../thread.engine.js";
 import type { ThreadItem, ContextIdentifier } from "../thread.store.js";
 import type { SerializableToolForModel } from "../tools-to-model-tools.js";
 /**
@@ -12,7 +13,7 @@ import type { SerializableToolForModel } from "../tools-to-model-tools.js";
 export declare function executeReaction(params: {
     env: ThreadEnvironment;
     contextIdentifier: ContextIdentifier;
-    model: any;
+    model: ThreadModelInit;
     system: string;
     tools: Record<string, SerializableToolForModel>;
     eventId: string;
@@ -20,7 +21,7 @@ export declare function executeReaction(params: {
     maxSteps: number;
     sendStart?: boolean;
     silent?: boolean;
-    writable?: WritableStream<UIMessageChunk>;
+    writable: WritableStream<UIMessageChunk>;
     executionId?: string;
     contextId?: string;
     stepId?: string;

package/dist/steps/reaction.steps.js

@@ -100,75 +100,16 @@ export async function executeReaction(params) {
         console.error("[ekairos/story] reaction.step store.itemsToModelMessages failed", safeErrorJson(error));
         throw error;
     }
-    const writable = params.silent || !params.writable
-        ? new WritableStream({ write() { } })
-        : params.writable;
     const { jsonSchema, gateway, smoothStream, stepCountIs, streamText } = await import("ai");
-    const { extractToolCallsFromParts } = await import("@ekairos/thread");
-    const isMockModelConfig = (value) => {
-        if (!value || typeof value !== "object")
-            return false;
-        if ("specificationVersion" in value)
-            return false;
-        if (value.source === "mock")
-            return true;
-        return typeof value.provider === "string" && typeof value.modelId === "string";
-    };
-    const buildMockModel = async (config) => {
-        const toolName = typeof config.toolName === "string" && config.toolName.trim()
-            ? config.toolName.trim()
-            : Object.keys(params.tools || {})[0] || "tool";
-        const provider = config.provider ?? "mock-provider";
-        const modelId = config.modelId ?? "mock-model-id";
-        return {
-            specificationVersion: "v2",
-            provider,
-            modelId,
-            supportedUrls: {},
-            doGenerate: async () => ({
-                content: [
-                    {
-                        type: "tool-call",
-                        toolCallId: "mock-tool-call",
-                        toolName,
-                        input: JSON.stringify({ instruction: "" }),
-                    },
-                ],
-                finishReason: "tool-calls",
-                usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
-                warnings: [],
-            }),
-            doStream: async () => {
-                const toolCallId = `mock-tool-${Date.now()}`;
-                const stream = new ReadableStream({
-                    start(controller) {
-                        controller.enqueue({ type: "stream-start", warnings: [] });
-                        controller.enqueue({
-                            type: "tool-call",
-                            toolCallId,
-                            toolName,
-                            input: JSON.stringify({ instruction: "" }),
-                        });
-                        controller.enqueue({
-                            type: "finish",
-                            finishReason: "tool-calls",
-                            usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
-                        });
-                        controller.close();
-                    },
-                });
-                return { stream };
-            },
-        };
-    };
+    const { extractToolCallsFromParts } = await import("../thread.toolcalls.js");
     // Match DurableAgent-style model init behavior:
     const resolvedModel = typeof params.model === "string"
         ? gateway(params.model)
-        : isMockModelConfig(params.model)
-            ? await buildMockModel(params.model)
-            : typeof params.model === "function"
-                ? await params.model()
-                : params.model;
+        : typeof params.model === "function"
+            ? await params.model()
+            : (() => {
+                throw new Error("Invalid model init passed to executeReaction. Expected a model id string or an async model factory.");
+            })();
     // Wrap plain JSON Schema objects so the AI SDK doesn't attempt Zod conversion at runtime.
     const toolsForStreamText = {};
     for (const [name, t] of Object.entries(params.tools)) {
@@ -226,7 +167,7 @@ export async function executeReaction(params) {
             controller.enqueue(chunk);
         },
     }));
-    await uiStream.pipeTo(writable, { preventClose: true });
+    await uiStream.pipeTo(params.writable, { preventClose: true });
     const assistantEvent = await finishPromise;
     const finishedAtMs = Date.now();
     const toolCalls = extractToolCallsFromParts(assistantEvent?.content?.parts);

package/dist/steps/store.steps.js

@@ -75,8 +75,7 @@ function inferDirection(item) {
     return undefined;
 }
 function shouldDebugThreadStoreSteps() {
-    return (process.env.EKAIROS_THREAD_DEBUG === "1" ||
-        process.env.PLAYWRIGHT_TEST === "1");
+    return process.env.EKAIROS_THREAD_DEBUG === "1";
 }
 function summarizeStepError(error) {
     const err = error;

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

@@ -1,9 +1,10 @@
 import "../polyfills/dom-events.js";
 import type { ThreadEnvironment } from "../thread.config.js";
+import type { ThreadTraceEventKind } from "../thread.contract.js";
 export type ThreadTraceEventWrite = {
     workflowRunId: string;
     eventId: string;
-    eventKind: string;
+    eventKind: ThreadTraceEventKind;
     seq?: number;
     eventAt?: string;
     contextKey?: string;

package/dist/steps/trace.steps.js

@@ -61,10 +61,15 @@ async function getTraceAuthHeader(baseUrl, projectId) {
     return `Bearer ${apiKey}`;
 }
 async function readProjectId() {
-    const { getRuntimeProjectId } = await import("@ekairos/domain/runtime");
-    const fromConfig = String(getRuntimeProjectId() || "").trim();
-    if (fromConfig)
-        return fromConfig;
+    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()
         : "";

package/dist/stores/instant.documents.d.ts

@@ -10,7 +10,7 @@ export declare function expandEventsWithInstantDocuments(params: {
      */
     maxChars?: number;
     /**
-     * Event type used for derived document text. Defaults to "document.parsed".
+     * Event type used for derived document text. Defaults to "output_text".
      */
-    derivedEventType?: string;
+    derivedEventType?: ThreadItem["type"];
 }): Promise<ThreadItem[]>;

package/dist/stores/instant.documents.js

@@ -72,7 +72,7 @@ async function ensureDocumentParsedForFile(db, params) {
 export async function expandEventsWithInstantDocuments(params) {
     const db = params.db;
     const maxChars = typeof params.maxChars === "number" ? params.maxChars : 120000;
-    const derivedEventType = params.derivedEventType ?? "document.parsed";
+    const derivedEventType = params.derivedEventType ?? "output_text";
     const out = [];
     for (const event of params.events) {
         const parts = event?.content?.parts;

package/dist/stores/instant.store.js

@@ -1,6 +1,7 @@
 import "../polyfills/dom-events.js";
 import { id, lookup } from "@instantdb/admin";
 import { convertItemsToModelMessages } from "../thread.events.js";
+import { assertContextTransition, assertExecutionTransition, assertItemTransition, assertStepTransition, assertThreadTransition, } from "../thread.contract.js";
 export { parseAndStoreDocument } from "./instant.document-parser.js";
 import { expandEventsWithInstantDocuments } from "./instant.documents.js";
 export { coerceDocumentTextPages, expandEventsWithInstantDocuments, } from "./instant.documents.js";
@@ -299,6 +300,9 @@ export class InstantStore {
         const thread = await this.getThread(threadIdentifier);
         if (!thread)
             throw new Error("InstantStore: thread not found");
+        if (thread.status !== status) {
+            assertThreadTransition(thread.status, status);
+        }
         await this.db.transact([
             this.db.tx.thread_threads[thread.id].update({
                 status,
@@ -409,6 +413,9 @@ export class InstantStore {
         const context = await this.getContext(contextIdentifier);
         if (!context?.id)
             throw new Error("InstantStore: context not found");
+        if (context.status !== status) {
+            assertContextTransition(context.status, status);
+        }
         const txs = [
             this.db.tx.thread_contexts[context.id].update({
                 status,
@@ -416,8 +423,13 @@ export class InstantStore {
             }),
         ];
         if (context.threadId) {
+            const thread = await this.getThread({ id: context.threadId });
+            const nextThreadStatus = (status === "closed" ? "closed" : status);
+            if (thread && thread.status !== nextThreadStatus) {
+                assertThreadTransition(thread.status, nextThreadStatus);
+            }
             txs.push(this.db.tx.thread_threads[context.threadId].update({
-                status: (status === "closed" ? "closed" : status),
+                status: nextThreadStatus,
                 updatedAt: new Date(),
             }));
         }
@@ -440,6 +452,10 @@ export class InstantStore {
     }
     async saveItem(contextIdentifier, event) {
         const { context, thread } = await this.resolveThreadContext(contextIdentifier);
+        const existing = await this.getItem(event.id);
+        if (existing?.status && existing.status !== "stored") {
+            assertItemTransition(existing.status, "stored");
+        }
         const txs = [
             this.db.tx.thread_items[event.id].update({
                 ...event,
@@ -474,6 +490,10 @@ export class InstantStore {
         return persisted;
     }
     async updateItem(eventId, event) {
+        const current = await this.getItem(eventId);
+        if (current?.status && event.status && current.status !== event.status) {
+            assertItemTransition(current.status, event.status);
+        }
         await this.db.transact([this.db.tx.thread_items[eventId].update(event)]);
         const persisted = await this.getItem(eventId);
         if (!persisted)
@@ -571,12 +591,31 @@ export class InstantStore {
     }
     async completeExecution(contextIdentifier, executionId, status) {
         const { context, thread } = await this.resolveThreadContext(contextIdentifier);
+        const executionResult = await this.db.query({
+            thread_executions: {
+                $: { where: { id: executionId }, limit: 1 },
+            },
+        });
+        const executionRow = executionResult?.thread_executions?.[0];
+        if (!executionRow)
+            throw new Error("InstantStore: execution not found");
+        const currentExecutionStatus = String(executionRow.status ?? "executing");
+        if (currentExecutionStatus !== status) {
+            assertExecutionTransition(currentExecutionStatus, status);
+        }
+        if (context.status !== "open") {
+            assertContextTransition(context.status, "open");
+        }
+        const nextThreadStatus = status === "failed" ? "failed" : "open";
+        if (thread.status !== nextThreadStatus) {
+            assertThreadTransition(thread.status, nextThreadStatus);
+        }
         const txs = [];
         txs.push(this.db.tx.thread_executions[executionId].update({ status, updatedAt: new Date() }));
         // Update context status back to "open" when execution completes
         txs.push(this.db.tx.thread_contexts[context.id].update({ status: "open", updatedAt: new Date() }));
         txs.push(this.db.tx.thread_threads[thread.id].update({
-            status: status === "failed" ? "failed" : "open",
+            status: nextThreadStatus,
             updatedAt: new Date(),
         }));
         await this.db.transact(txs);
@@ -614,6 +653,20 @@ export class InstantStore {
         return { id: stepId, eventId };
     }
     async updateStep(stepId, patch) {
+        if (patch.status) {
+            const stepResult = await this.db.query({
+                thread_steps: {
+                    $: { where: { id: stepId }, limit: 1 },
+                },
+            });
+            const stepRow = stepResult?.thread_steps?.[0];
+            if (!stepRow)
+                throw new Error("InstantStore: step not found");
+            const currentStepStatus = String(stepRow.status ?? "running");
+            if (currentStepStatus !== patch.status) {
+                assertStepTransition(currentStepStatus, patch.status);
+            }
+        }
         const update = {
             ...patch,
             updatedAt: patch.updatedAt ?? new Date(),
@@ -708,12 +761,12 @@ export class InstantStore {
             }
         }
         // Default behavior for Instant-backed stories:
-        // - Expand file parts into derived `document.parsed` events (persisting parsed content into document_documents)
+        // - Expand file parts into derived `output_text` events (persisting parsed content into document_documents)
         // - Then convert expanded events to model messages
         const expanded = await expandEventsWithInstantDocuments({
             db: this.db,
             events: eventsWithParts,
-            derivedEventType: "document.parsed",
+            derivedEventType: "output_text",
         });
         return await convertItemsToModelMessages(expanded);
     }