@ekairos/thread 1.21.88-beta.0

package/dist/thread.reactor.d.ts

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

package/dist/thread.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/thread.registry.d.ts

@@ -0,0 +1,21 @@
+import type { ThreadEnvironment } from "./thread.config.js";
+import type { ThreadInstance } from "./thread.builder.js";
+/**
+ * Global registry for threads, similar to Inngest's function registry.
+ *
+ * Goals:
+ * - `createThread("key")` can be called many times (module reloads, tests, etc.)
+ * - Execution resolves a thread by key (`getThread("key")`) instead of importing the module directly.
+ * - Registration is intentionally **runtime-local** (per process / per serverless instance).
+ */
+export type ThreadKey = string;
+type AnyThread = ThreadInstance<any, any>;
+export type ThreadFactory = () => AnyThread;
+export declare function registerThread(key: ThreadKey, factory: ThreadFactory): void;
+export declare function hasThread(key: ThreadKey): boolean;
+export declare function getThread<Env extends ThreadEnvironment = ThreadEnvironment>(key: ThreadKey): AnyThread & {
+    __config: {};
+};
+export declare function getThreadFactory(key: ThreadKey): ThreadFactory;
+export declare function listThreads(): string[];
+export {};

package/dist/thread.registry.js

@@ -0,0 +1,30 @@
+const registry = new Map();
+export function registerThread(key, factory) {
+    if (!key || typeof key !== "string") {
+        throw new Error("registerThread: key must be a non-empty string");
+    }
+    if (typeof factory !== "function") {
+        throw new Error("registerThread: factory must be a function");
+    }
+    registry.set(key, factory);
+}
+export function hasThread(key) {
+    return registry.has(key);
+}
+export function getThread(key) {
+    const factory = registry.get(key);
+    if (!factory) {
+        throw new Error(`Thread "${key}" is not registered. Ensure the module that calls createThread("${key}") is imported during boot.`);
+    }
+    return factory();
+}
+export function getThreadFactory(key) {
+    const factory = registry.get(key);
+    if (!factory) {
+        throw new Error(`Thread "${key}" is not registered. Ensure the module that calls createThread("${key}") is imported during boot.`);
+    }
+    return factory;
+}
+export function listThreads() {
+    return Array.from(registry.keys());
+}

package/dist/thread.store.d.ts

@@ -0,0 +1,121 @@
+import type { ModelMessage } from "ai";
+/**
+ * ## thread.store.ts
+ *
+ * A `ThreadStore` is the persistence boundary for threads.
+ *
+ * Workflow DevKit constraints mean **workflows must be deterministic** and all I/O must happen
+ * in steps. This library therefore models persistence as a pluggable store that can be
+ * instantiated *inside steps* (InstantDB, Postgres, etc.).
+ *
+ * The core engine should depend only on this interface (not on a specific database).
+ */
+export type ThreadIdentifier = {
+    id: string;
+    key?: never;
+} | {
+    key: string;
+    id?: never;
+};
+export type ContextIdentifier = ThreadIdentifier;
+export type ThreadStatus = "open" | "streaming" | "closed" | "failed";
+export type ContextStatus = "open" | "streaming" | "closed";
+export type StoredThread = {
+    id: string;
+    key: string | null;
+    name?: string | null;
+    status: ThreadStatus;
+    createdAt: Date;
+    updatedAt?: Date;
+};
+export type StoredContext<Context> = {
+    id: string;
+    threadId?: string;
+    key: string | null;
+    status: ContextStatus;
+    createdAt: Date;
+    updatedAt?: Date;
+    content: Context | null;
+};
+export type ThreadItem = {
+    id: string;
+    type: string;
+    channel: string;
+    createdAt: string;
+    status?: string;
+    content: any;
+};
+export type ExecutionStatus = "executing" | "completed" | "failed";
+export type ThreadStepStatus = "running" | "completed" | "failed";
+export type ThreadStep = {
+    id: string;
+    createdAt: Date;
+    updatedAt?: Date;
+    status: ThreadStepStatus;
+    iteration: number;
+    executionId: string;
+    triggerEventId?: string;
+    reactionEventId?: string;
+    eventId: string;
+    toolCalls?: any;
+    toolExecutionResults?: any;
+    continueLoop?: boolean;
+    errorText?: string;
+};
+export interface ThreadStore {
+    getOrCreateThread(threadIdentifier: ThreadIdentifier | null): Promise<StoredThread>;
+    getThread(threadIdentifier: ThreadIdentifier): Promise<StoredThread | null>;
+    updateThreadStatus(threadIdentifier: ThreadIdentifier, status: ThreadStatus): Promise<void>;
+    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: ThreadItem): Promise<ThreadItem>;
+    updateItem(itemId: string, item: ThreadItem): Promise<ThreadItem>;
+    getItem(itemId: string): Promise<ThreadItem | null>;
+    getItems(contextIdentifier: ContextIdentifier): Promise<ThreadItem[]>;
+    createExecution(contextIdentifier: ContextIdentifier, triggerEventId: string, reactionEventId: string): Promise<{
+        id: string;
+    }>;
+    completeExecution(contextIdentifier: ContextIdentifier, executionId: string, status: Exclude<ExecutionStatus, "executing">): Promise<void>;
+    /**
+     * Creates a persisted thread step (intended: one per loop iteration).
+     *
+     * IMPORTANT: IDs should be generated inside the store boundary (step runtime) to remain replay-safe.
+     */
+    createStep(params: {
+        executionId: string;
+        iteration: number;
+    }): Promise<{
+        id: string;
+        eventId: string;
+    }>;
+    /**
+     * Updates a persisted thread step with completion metadata (tools, errors, continue signal, etc).
+     */
+    updateStep(stepId: string, patch: Partial<Pick<ThreadStep, "status" | "toolCalls" | "toolExecutionResults" | "continueLoop" | "errorText" | "updatedAt">>): Promise<void>;
+    /**
+     * Persists normalized parts for a given step (parts-first).
+     * The item keeps `content.parts` for back-compat, but the source-of-truth can be `thread_parts`.
+     */
+    saveStepParts(params: {
+        stepId: string;
+        parts: any[];
+    }): Promise<void>;
+    /**
+     * Links an event to an execution so consumers can traverse:
+     * `event -> execution -> steps`
+     */
+    linkItemToExecution(params: {
+        itemId: string;
+        executionId: string;
+    }): Promise<void>;
+    /**
+     * Converts items to model messages for the next LLM call.
+     *
+     * NOTE:
+     * - Attachment/document expansion should happen earlier in the Thread loop via `expandEvents(...)`.
+     * - This method should stay focused on converting already-normalized event parts into `ModelMessage[]`.
+     */
+    itemsToModelMessages(items: ThreadItem[]): Promise<ModelMessage[]>;
+}

package/dist/thread.store.js

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

package/dist/thread.toolcalls.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ## thread.toolcalls.ts
+ *
+ * This module isolates the **tool-call plumbing** used by `thread.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 `thread.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+import type { ThreadItem } from "./thread.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 `thread.shouldContinue(...)` where you want to
+ * decide based on the persisted `reactionEvent` (not ephemeral in-memory arrays).
+ */
+export declare function didToolExecute(event: Pick<ThreadItem, "content">, toolName: string): boolean;

package/dist/thread.toolcalls.js

@@ -0,0 +1,73 @@
+/**
+ * ## thread.toolcalls.ts
+ *
+ * This module isolates the **tool-call plumbing** used by `thread.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 `thread.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+/**
+ * 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 (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) {
+    return parts.map((p) => {
+        if (p?.type === `tool-${toolCall.toolName}` && p.toolCallId === toolCall.toolCallId) {
+            if (execution.success) {
+                return { ...p, state: "output-available", output: execution.result };
+            }
+            return { ...p, state: "output-error", errorText: String(execution.message || "Error") };
+        }
+        return p;
+    });
+}
+/**
+ * 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 `thread.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;
+    return parts.some((p) => p.type === `tool-${toolName}` &&
+        (p.state === "output-available" || p.state === "output-error"));
+}

package/dist/tools-to-model-tools.d.ts

@@ -0,0 +1,19 @@
+import { type Tool } from "ai";
+/**
+ * Serializable "tool" shape to pass across the Workflow step boundary.
+ *
+ * Mirrors Workflow DevKit's DurableAgent strategy:
+ * - Keep Zod/function values out of step arguments
+ * - Convert tool input schemas to plain JSON Schema in workflow context
+ */
+export type SerializableToolForModel = {
+    description?: string;
+    inputSchema: unknown;
+};
+/**
+ * Convert AI SDK tools to a serializable representation that can be passed to `"use-step"` functions.
+ *
+ * This matches DurableAgent's internal `toolsToModelTools` behavior:
+ * `inputSchema: asSchema(tool.inputSchema).jsonSchema`
+ */
+export declare function toolsToModelTools(tools: Record<string, Tool>): Record<string, SerializableToolForModel>;

package/dist/tools-to-model-tools.js

@@ -0,0 +1,21 @@
+import { asSchema } from "ai";
+/**
+ * Convert AI SDK tools to a serializable representation that can be passed to `"use-step"` functions.
+ *
+ * This matches DurableAgent's internal `toolsToModelTools` behavior:
+ * `inputSchema: asSchema(tool.inputSchema).jsonSchema`
+ */
+export function toolsToModelTools(tools) {
+    const out = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        const inputSchema = tool?.inputSchema;
+        if (!inputSchema) {
+            throw new Error(`Thread: tool "${name}" is missing inputSchema (required for model tool calls)`);
+        }
+        out[name] = {
+            description: tool?.description,
+            inputSchema: asSchema(inputSchema).jsonSchema,
+        };
+    }
+    return out;
+}

package/package.json

@@ -0,0 +1,133 @@
+{
+  "name": "@ekairos/thread",
+  "version": "1.21.88-beta.0",
+  "description": "Pulzar Thread - Workflow-based AI Threads",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pulz-ar/pulzar-lib-core.git",
+    "directory": "packages/thread"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js",
+      "require": "./dist/schema.js",
+      "default": "./dist/schema.js"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.ts",
+      "import": "./dist/runtime.js",
+      "require": "./dist/runtime.js",
+      "default": "./dist/runtime.js"
+    },
+    "./reactor": {
+      "types": "./dist/thread.reactor.d.ts",
+      "import": "./dist/thread.reactor.js",
+      "require": "./dist/thread.reactor.js",
+      "default": "./dist/thread.reactor.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js",
+      "require": "./dist/mcp.js",
+      "default": "./dist/mcp.js"
+    },
+    "./oidc": {
+      "types": "./dist/oidc.d.ts",
+      "import": "./dist/oidc.js",
+      "require": "./dist/oidc.js",
+      "default": "./dist/oidc.js"
+    },
+    "./codex": {
+      "types": "./dist/codex.d.ts",
+      "import": "./dist/codex.js",
+      "require": "./dist/codex.js",
+      "default": "./dist/codex.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "import": "./dist/react.js",
+      "require": "./dist/react.js",
+      "default": "./dist/react.js"
+    },
+    "./instant": {
+      "types": "./dist/stores/instant.store.d.ts",
+      "import": "./dist/stores/instant.store.js",
+      "require": "./dist/stores/instant.store.js",
+      "default": "./dist/stores/instant.store.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "schema": [
+        "dist/schema.d.ts"
+      ],
+      "runtime": [
+        "dist/runtime.d.ts"
+      ],
+      "reactor": [
+        "dist/thread.reactor.d.ts"
+      ],
+      "mcp": [
+        "dist/mcp.d.ts"
+      ],
+      "oidc": [
+        "dist/oidc.d.ts"
+      ],
+      "codex": [
+        "dist/codex.d.ts"
+      ],
+      "react": [
+        "dist/react.d.ts"
+      ],
+      "instant": [
+        "dist/stores/instant.store.d.ts"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "watch": "tsc -p tsconfig.json --watch",
+    "clean": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^2.0.52",
+    "@ekairos/domain": "^1.21.88-beta.0",
+    "@instantdb/admin": "0.22.126",
+    "@instantdb/core": "0.22.126",
+    "@vercel/mcp-adapter": "^1.0.0",
+    "@vercel/sandbox": "^0.0.23",
+    "ai": "^5.0.95",
+    "ajv": "^8.17.1",
+    "jose": "^6.1.3",
+    "llamaindex": "^0.12.0",
+    "react": "^19.2.0",
+    "workflow": "4.1.0-beta.53",
+    "xmlbuilder2": "^3.1.1",
+    "zod": "^4.1.8"
+  },
+  "devDependencies": {
+    "@ekairos/tsconfig": "workspace:*",
+    "@types/node": "^24.5.0",
+    "@types/react": "^19.2.2",
+    "typescript": "^5.9.2"
+  }
+}