@ekairos/thread 1.22.1 → 1.22.2

package/README.md

@@ -1,45 +1,10 @@
-# @ekairos/thread
+# @ekairos/thread
 
-Durable AI threads for production apps.
+Durable thread engine for Workflow-compatible AI agents.
 
-`@ekairos/thread` gives you an execution model that is:
+`@ekairos/thread` is the execution layer used by Ekairos agents. It persists context, items, steps, parts, and executions, while streaming UI chunks and enforcing transition contracts.
 
-- workflow-compatible,
-- persistence-first,
-- traceable by design,
-- simple to embed in domain applications.
-
-It is the runtime used by Ekairos coding agents and domain agents.
-
-## Why Thread
-
-Most chat abstractions stop at "messages in, text out".  
-Thread models the full lifecycle:
-
-1. Persist trigger event.
-2. Create execution.
-3. Run model reaction.
-4. Persist normalized parts.
-5. Execute actions (tools).
-6. Persist tool outcomes.
-7. Decide continue or end.
-8. Emit traces for every durable step.
-
-This design supports long-running, resumable agent runs without losing state.
-
-## Core Concepts
-
-- `Thread`: durable loop orchestrator.
-- `Reactor`: pluggable reaction implementation (`AI SDK`, `Codex`, `Claude`, `Cursor`, ...).
-- `Thread Key`: stable public identifier (`thread.key`) for continuity.
-- `Context`: typed persistent state attached to a thread.
-- `Item`: normalized event (`input_text`, `output_text`, etc).
-- `Execution`: one run for a trigger/reaction pair.
-- `Step`: one loop iteration inside an execution.
-- `Part`: normalized content fragment persisted by step.
-- `Trace`: machine timeline (`thread.*`, `workflow.*`) for observability.
-
-## Installation
+## Install
 
 ```bash
 pnpm add @ekairos/thread
@@ -54,310 +19,427 @@ Optional subpaths:
 - `@ekairos/thread/mcp`
 - `@ekairos/thread/oidc`
 
-## Quick Start
-
-### 1) Configure app runtime once
-
-Thread resolves persistence through runtime.  
-Do this once in app bootstrap (`src/ekairos.ts`):
+## Package Surface (from `src/index.ts`)
+
+### Core builders and engine
+
+- `createThread`
+- `thread`
+- `Thread`
+- `type ThreadConfig`
+- `type ThreadInstance`
+- `type RegistrableThreadBuilder`
+- `type ThreadOptions`
+- `type ThreadStreamOptions`
+
+### Reactors
+
+- `createAiSdkReactor`
+- `createScriptedReactor`
+- `type ThreadReactor`
+- `type ThreadReactorParams`
+- `type ThreadReactionResult`
+- `type ThreadReactionToolCall`
+- `type ThreadReactionLLM`
+- `type CreateAiSdkReactorOptions`
+- `type CreateScriptedReactorOptions`
+- `type ScriptedReactorStep`
+
+### Contracts and transitions
+
+- `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`
+- `can*Transition`, `assert*Transition`
+- `assertThreadPartKey`
+
+### Stream and parsing
+
+- `parseThreadStreamEvent`
+- `assertThreadStreamTransitions`
+- `validateThreadStreamTimeline`
+- `type ThreadStreamEvent`
+- `type ContextCreatedEvent`
+- `type ContextResolvedEvent`
+- `type ContextStatusChangedEvent`
+- `type ThreadCreatedEvent`
+- `type ThreadResolvedEvent`
+- `type ThreadStatusChangedEvent`
+- `type ExecutionCreatedEvent`
+- `type ExecutionStatusChangedEvent`
+- `type ItemCreatedEvent`
+- `type ItemStatusChangedEvent`
+- `type StepCreatedEvent`
+- `type StepStatusChangedEvent`
+- `type PartCreatedEvent`
+- `type PartUpdatedEvent`
+- `type ChunkEmittedEvent`
+- `type ThreadFinishedEvent`
+
+### Event conversion helpers
+
+- `createUserItemFromUIMessages`
+- `createAssistantItemFromUIMessages`
+- `convertToUIMessage`
+- `convertItemToModelMessages`
+- `convertItemsToModelMessages`
+- `convertModelMessageToItem`
+- `didToolExecute`
+- `extractToolCallsFromParts`
+
+### React hook
+
+- `useThread`
+- `type UseThreadOptions`
+- `type ThreadSnapshot`
+- `type ThreadStreamChunk`
+
+### Registry / codex
+
+- `registerThread`
+- `getThread`
+- `getThreadFactory`
+- `hasThread`
+- `listThreads`
+- `createCodexThreadBuilder`
+- codex defaults/types from `codex.ts`
+
+## Thread API Specification
+
+## `createThread`
 
 ```ts
-import "server-only";
-import { configureRuntime } from "@ekairos/domain/runtime";
-import { getOrgAdminDb } from "@/lib/admin-org-db";
-import appDomain from "@/lib/domain";
-
-export const runtimeConfig = configureRuntime({
-  runtime: async (env: { orgId: string }) => {
-    const db = await getOrgAdminDb(env.orgId, appDomain);
-    return { db };
-  },
-  domain: { domain: appDomain },
-});
+createThread<Env>(key: ThreadKey)
 ```
 
-### 2) Define a thread
+Builder stages:
 
-```ts
-import { createThread } from "@ekairos/thread";
-import { tool } from "ai";
-import { z } from "zod";
+1. `.context((storedContext, env) => context)` (required)
+2. `.expandEvents((events, context, env) => events)` (optional)
+3. `.narrative((context, env) => string)` (required)
+4. `.actions((context, env) => Record<string, ThreadTool>)` (required)
+5. `.model(modelInit | selector)` (optional)
+6. `.reactor(reactor)` (optional, default is AI SDK reactor)
+7. `.shouldContinue(({ reactionEvent, toolCalls, toolExecutionResults, ... }) => boolean)` (optional)
+8. `.opts(threadOptions)` (optional)
 
-type Env = { orgId: string; sessionId: string };
-type Ctx = { orgId: string; sessionId: string };
+Builder terminals:
 
-export const helloThread = createThread<Env>("hello.thread")
-  .context(async (stored, env) => ({
-    orgId: env.orgId,
-    sessionId: env.sessionId,
-    ...(stored.content ?? {}),
-  }))
-  .narrative((ctx) => `You are a precise assistant. Session=${ctx.content?.sessionId}`)
-  .actions(() => ({
-    ping: tool({
-      description: "Return pong",
-      inputSchema: z.object({ text: z.string().optional() }),
-      execute: async ({ text }) => ({ pong: text ?? "ok" }),
-    }),
-  }))
-  .model("openai/gpt-5.2")
-  .build();
-```
+- `.build()` -> `ThreadInstance`
+- `.react(triggerEvent, params)`
+- `.stream(triggerEvent, params)` (deprecated alias)
+- `.register()`
+- `.config()`
 
-### 2.1) Reactor model (new)
+### `ThreadConfig<Context, Env>`
 
-Thread runs through a `reactor`:
+Required keys:
 
-- default: `createAiSdkReactor()` (included in `@ekairos/thread`)
-- optional: custom/provider reactor via `.reactor(...)`
+- `context`
+- `narrative`
+- `actions` (or legacy `tools`)
 
-```ts
-import { createThread, createAiSdkReactor } from "@ekairos/thread";
+Optional keys:
 
-const thread = createThread<{ orgId: string }>("my.thread")
-  .context((stored, env) => ({ ...(stored.content ?? {}), orgId: env.orgId }))
-  .narrative(() => "System prompt")
-  .actions(() => ({}))
-  .reactor(createAiSdkReactor())
-  .build();
-```
+- `expandEvents`
+- `model`
+- `reactor`
+- `shouldContinue`
+- `opts`
 
-`createAiSdkReactor` also accepts optional per-turn config hooks:
+### `Thread.react`
 
-```ts
-import { createAiSdkReactor } from "@ekairos/thread";
+Primary form:
 
-const reactor = createAiSdkReactor({
-  resolveConfig: async ({ env }) => {
-    "use step";
-    return { model: env.model ?? "openai/gpt-5.2", maxModelSteps: 2 };
-  },
-  selectModel: ({ config, baseModel }) => config.model ?? baseModel,
-  selectMaxModelSteps: ({ config, baseMaxModelSteps }) =>
-    typeof config.maxModelSteps === "number"
-      ? config.maxModelSteps
-      : baseMaxModelSteps,
-});
+```ts
+thread.react(triggerEvent, {
+  env,
+  context: { id } | { key } | null,
+  options,
+})
 ```
 
-Provider reactors live in `packages/reactors/*`:
-
-- `@ekairos/openai-reactor` (`createOpenAIReactor`, `createCodexReactor`)
-- `@ekairos/claude-reactor` (scaffold)
-- `@ekairos/cursor-reactor` (scaffold)
-
-### 3) Run from a workflow
+Return shape:
 
 ```ts
-import { getWritable } from "workflow";
-import type { UIMessageChunk } from "ai";
-import type { ThreadItem } from "@ekairos/thread";
-import { helloThread } from "./hello.thread";
-
-export async function helloWorkflow(params: {
-  env: { orgId: string; sessionId: string };
-  triggerEvent: ThreadItem;
-  threadKey?: string;
-}) {
-  "use workflow";
-
-  const writable = getWritable<UIMessageChunk>();
-  return await helloThread.react(params.triggerEvent, {
-    env: params.env,
-    context: params.threadKey ? { key: params.threadKey } : null,
-    options: { writable, maxIterations: 2, maxModelSteps: 1 },
-  });
+{
+  contextId: string;
+  context: StoredContext<Context>;
+  triggerEventId: string;
+  reactionEventId: string;
+  executionId: string;
 }
 ```
 
-## Thread Lifecycle (Detailed)
+### `ThreadStreamOptions`
 
-For each `react(...)` call:
+- `maxIterations?: number` (default `20`)
+- `maxModelSteps?: number` (default `1`)
+- `preventClose?: boolean` (default `false`)
+- `sendFinish?: boolean` (default `true`)
+- `silent?: boolean` (default `false`)
+- `writable?: WritableStream<UIMessageChunk>`
 
-1. `initializeContext` creates or loads context.
-2. `saveTriggerAndCreateExecution` persists trigger and execution.
-3. `createThreadStep` starts iteration record.
-4. `buildSystemPrompt` and `buildTools` are evaluated.
-5. `executeReaction` runs model + tool call planning.
-6. `saveThreadPartsStep` persists normalized parts.
-7. `saveReactionItem` or `updateItem` updates stable reaction item.
-8. Tool executions run and are merged into persisted parts.
-9. `shouldContinue(...)` decides next iteration or completion.
-10. `completeExecution` closes run status.
+### `ThreadOptions`
 
-All side effects are executed through workflow-safe steps.
+Lifecycle callbacks:
 
-## Event and Item Model
+- `onContextCreated`
+- `onContextUpdated`
+- `onEventCreated`
+- `onToolCallExecuted`
+- `onEnd`
 
-Key utilities:
+## Reactor Specification
 
-- `createUserItemFromUIMessages(...)`
-- `createAssistantItemFromUIMessages(...)`
-- `convertItemsToModelMessages(...)`
-- `convertModelMessageToItem(...)`
-- `didToolExecute(...)`
-- `extractToolCallsFromParts(...)`
+A reactor receives the full execution context for one iteration and returns normalized assistant output + tool calls.
 
-This keeps a stable internal representation while remaining compatible with UI/model formats.
+### `ThreadReactorParams`
 
-## Runtime and Persistence
+- `env`
+- `context`
+- `contextIdentifier`
+- `triggerEvent`
+- `model`
+- `systemPrompt`
+- `actions`
+- `toolsForModel`
+- `eventId`
+- `executionId`
+- `contextId`
+- `stepId`
+- `iteration`
+- `maxModelSteps`
+- `sendStart`
+- `silent`
+- `writable`
 
-Thread runtime resolves from `@ekairos/domain/runtime` bootstrap.
+### `ThreadReactionResult`
 
-Default persistence adapter:
+- `assistantEvent: ThreadItem`
+- `toolCalls: ThreadReactionToolCall[]`
+- `messagesForModel: ModelMessage[]`
+- `llm?: ThreadReactionLLM`
 
-- `InstantStore` (`@ekairos/thread/instant`)
+## Built-in Reactors
 
-Schema:
+## `createAiSdkReactor` (production default)
 
-- `thread_threads`
-- `thread_contexts`
-- `thread_items`
-- `thread_executions`
-- `thread_steps`
-- `thread_parts`
-- `thread_trace_events`
-- `thread_trace_runs`
-- `thread_trace_spans`
-
-Import domain schema:
+Uses AI SDK streaming + tool extraction through engine steps.
 
 ```ts
-import { threadDomain } from "@ekairos/thread/schema";
-```
+import { createAiSdkReactor } from "@ekairos/thread";
 
-## Streaming
+const reactor = createAiSdkReactor({
+  resolveConfig: async ({ env, context, iteration }) => {
+    "use step";
+    return {
+      model: env.model ?? "openai/gpt-5.2",
+      maxModelSteps: iteration === 0 ? 2 : 1,
+      tenant: context.content?.orgId,
+    };
+  },
+  selectModel: ({ baseModel, config }) => config.model ?? baseModel,
+  selectMaxModelSteps: ({ baseMaxModelSteps, config }) =>
+    typeof config.maxModelSteps === "number"
+      ? config.maxModelSteps
+      : baseMaxModelSteps,
+});
+```
 
-Thread writes `UIMessageChunk` to workflow writable streams.
+Use in thread:
 
-Options:
+```ts
+createThread<{ orgId: string }>("support.agent")
+  .context((stored, env) => ({ ...stored.content, orgId: env.orgId }))
+  .narrative(() => "You are a precise assistant")
+  .actions(() => ({}))
+  .reactor(reactor)
+  .build();
+```
 
-- `writable`: custom stream.
-- `silent`: disable stream writes, keep persistence.
-- `preventClose`: do not close writer.
-- `sendFinish`: control final `finish` chunk.
+## `createScriptedReactor` (testing and deterministic local loops)
 
-Namespaced streams are supported using `context:<contextId>`.
+No network/model calls. Returns scripted payloads per iteration.
 
-## Identity Model
+```ts
+import { createScriptedReactor } from "@ekairos/thread";
+
+const reactor = createScriptedReactor({
+  steps: [
+    {
+      assistantEvent: {
+        content: { parts: [{ type: "text", text: "Deterministic answer" }] },
+      },
+      toolCalls: [],
+      messagesForModel: [],
+    },
+  ],
+  repeatLast: true,
+});
+```
 
-- `thread.key` is the functional continuity id.
-- `context.id` is internal state id for typed context persistence.
-- A thread can own one or more contexts; default runtime behavior is one active context per thread.
+Rules:
 
-### Open Responses alignment
+- `steps` must contain at least 1 entry.
+- If all steps are consumed and `repeatLast !== true`, reactor throws.
+- `assistantEvent` is normalized with fallback fields:
+  - `id = params.eventId`
+  - `type = "output_text"`
+  - `channel = triggerEvent.channel`
+  - `createdAt = now`
 
-Thread is protocol-aligned with Open Responses item/event semantics and keeps durable execution
-through Workflow.
+## Production Pattern
 
-- Public continuity id should be `thread.key`.
-- Context remains internal typed state, but can be exposed as an extension field in thread query APIs.
-- Safe extension pattern: include `context` object in thread payload while preserving standard fields.
+```ts
+import { createThread, createAiSdkReactor } from "@ekairos/thread";
+import { tool } from "ai";
+import { z } from "zod";
 
-Example shape for a thread query response:
+type Env = { orgId: string; sessionId: string };
 
-```json
-{
-  "object": "conversation",
-  "id": "thread-key-or-id",
-  "status": "completed",
-  "context": {
-    "id": "ctx_123",
-    "key": "code.agent.session.abc",
-    "status": "completed",
-    "content": {}
-  }
-}
+export const supportThread = createThread<Env>("support.agent")
+  .context((stored, env) => ({
+    orgId: env.orgId,
+    sessionId: env.sessionId,
+    ...stored.content,
+  }))
+  .narrative((context) => `Assist session ${context.content?.sessionId}`)
+  .actions(() => ({
+    ping: tool({
+      description: "Health check",
+      inputSchema: z.object({ text: z.string().optional() }),
+      execute: async ({ text }) => ({ pong: text ?? "ok" }),
+    }),
+  }))
+  .reactor(createAiSdkReactor())
+  .shouldContinue(({ reactionEvent }) => {
+    const parts = reactionEvent.content?.parts ?? [];
+    const hasTool = parts.some((part: any) => part?.type === "tool-call");
+    return hasTool;
+  })
+  .build();
 ```
 
-This extension is additive and does not break Open Responses compatibility.
+## Testing Pattern
 
-## Tracing and Observability
-
-Thread emits lifecycle traces by default through step operations.
-
-Typical namespaces:
-
-- `thread.run`
-- `thread.context`
-- `thread.execution`
-- `thread.step`
-- `thread.item`
-- `thread.part`
-- `thread.review`
-- `thread.llm`
-- `workflow.run`
-
-These traces are intended for local persistence plus optional mirror ingestion to central collectors.
-
-## Registry API
+```ts
+import { createThread, createScriptedReactor } from "@ekairos/thread";
 
-Register and resolve threads by key:
+type Env = { orgId: string };
 
-```ts
-import { registerThread, getThread } from "@ekairos/thread";
+const testThread = createThread<Env>("thread.test")
+  .context((stored, env) => ({ orgId: env.orgId, ...stored.content }))
+  .narrative(() => "Test narrative")
+  .actions(() => ({}))
+  .reactor(
+    createScriptedReactor({
+      steps: [
+        {
+          assistantEvent: {
+            content: { parts: [{ type: "text", text: "ok-1" }] },
+          },
+          toolCalls: [],
+          messagesForModel: [],
+        },
+      ],
+      repeatLast: true,
+    }),
+  )
+  .build();
 ```
 
-Builder convenience:
+## Stream Contract
 
-```ts
-const builder = createThread<Env>("my.key").context(...).narrative(...).actions(...);
-builder.register();
-```
+Thread stream events (`thread.stream.ts`) are entity-based.
 
-## Preconfigured Codex Thread
+Hierarchy:
 
-Use `@ekairos/thread/codex` to create coding threads with minimal wiring.
+1. context
+2. thread
+3. item
+4. step
+5. part
+6. chunk
 
-```ts
-import { createCodexThreadBuilder } from "@ekairos/thread/codex";
+Event types:
 
-const builder = createCodexThreadBuilder({
-  key: "code.agent",
-  context: async (stored, env) => ({ ...(stored.content ?? {}), ...env }),
-  executeCodex: async ({ input, env }) => {
-    // Call Codex app server here (usually in a use-step function)
-    return {
-      threadId: "t_123",
-      turnId: "turn_123",
-      assistantText: "done",
-      reasoningText: "",
-      diff: "",
-      toolParts: [],
-    };
-  },
-});
-```
+- `context.created`
+- `context.resolved`
+- `context.status.changed`
+- `thread.created`
+- `thread.resolved`
+- `thread.status.changed`
+- `execution.created`
+- `execution.status.changed`
+- `item.created`
+- `item.status.changed`
+- `step.created`
+- `step.status.changed`
+- `part.created`
+- `part.updated`
+- `chunk.emitted`
+- `thread.finished`
 
-What it configures for you:
+Chunk types (`THREAD_STREAM_CHUNK_TYPES`):
 
-- `codex` action schema,
-- default model selection (`openai/gpt-5.2`),
-- default continue rule (`stop after codex action executes`),
-- default narrative fallback.
+- `data-context-id`
+- `data-context-substate`
+- `data-thread-ping`
+- `tool-output-available`
+- `tool-output-error`
+- `finish`
 
-For direct Codex runtime (without "tool indirection"), use
-`@ekairos/openai-reactor` + `createCodexReactor(...)`.
+Validation helpers:
 
-## MCP and OIDC
+- `parseThreadStreamEvent(event)`
+- `assertThreadStreamTransitions(event)`
+- `validateThreadStreamTimeline(events)`
 
-Utilities are exposed for protocol integration:
+## Transition Contract
 
-- `@ekairos/thread/mcp`
-- `@ekairos/thread/oidc`
+Allowed status transitions are exported as constants and enforced by assertion helpers.
+
+- Thread: `open -> streaming -> (open | closed | failed)`, `failed -> open`
+- Context: `open <-> streaming`, `(open | streaming) -> closed`
+- Execution: `executing -> (completed | failed)`
+- Step: `running -> (completed | failed)`
+- Item: `stored -> (pending | completed)`, `pending -> completed`
 
-Use these from server-side API routes when exposing thread-driven tools via MCP.
+## Runtime and Schema
 
-## DX Guidelines
+- Import schema with `threadDomain` from `@ekairos/thread/schema`
+- Store integration defaults to `InstantStore`
+- Runtime must be configured via `@ekairos/domain/runtime` in host app
 
-- Keep `env` serializable.
-- Keep thread definition declarative.
-- Put DB/network side effects inside step functions.
-- Prefer `context.id` for deterministic resume.
-- Use explicit thread keys (`domain.agent.name` format).
+Persisted entities:
 
-## Breaking-Change Policy
+- `thread_threads`
+- `thread_contexts`
+- `thread_items`
+- `thread_executions`
+- `thread_steps`
+- `thread_parts`
+- `thread_trace_events`
+- `thread_trace_runs`
+- `thread_trace_spans`
 
-Thread prioritizes runtime correctness over implicit compatibility shims.
+## Notes for Productive Usage
 
-When behavior conflicts with durability or protocol clarity, explicit configuration is preferred over hidden fallbacks.
+- Always pass explicit `env`.
+- Prefer `context: { key }` for stable continuation and `context: { id }` for deterministic resume.
+- Keep IO in workflow steps.
+- Use `createScriptedReactor` for deterministic regression tests and component demos.
+- Validate stream timelines with `validateThreadStreamTimeline` when consuming SSE externally.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/thread",
-  "version": "1.22.1",
+  "version": "1.22.2",
   "description": "Pulzar Thread - Workflow-based AI Threads",
   "type": "module",
   "main": "dist/index.js",
@@ -110,7 +110,7 @@
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.52",
-    "@ekairos/domain": "^1.22.1",
+    "@ekairos/domain": "^1.22.2",
     "@instantdb/admin": "0.22.126",
     "@instantdb/core": "0.22.126",
     "@vercel/mcp-adapter": "^1.0.0",