@ekairos/thread 1.21.88-beta.0

package/README.md

@@ -0,0 +1,363 @@
+# @ekairos/thread
+
+Durable AI threads for production apps.
+
+`@ekairos/thread` gives you an execution model that is:
+
+- 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
+
+```bash
+pnpm add @ekairos/thread
+```
+
+Optional subpaths:
+
+- `@ekairos/thread/runtime`
+- `@ekairos/thread/schema`
+- `@ekairos/thread/instant`
+- `@ekairos/thread/codex`
+- `@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`):
+
+```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 },
+});
+```
+
+### 2) Define a thread
+
+```ts
+import { createThread } from "@ekairos/thread";
+import { tool } from "ai";
+import { z } from "zod";
+
+type Env = { orgId: string; sessionId: string };
+type Ctx = { orgId: string; sessionId: string };
+
+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();
+```
+
+### 2.1) Reactor model (new)
+
+Thread runs through a `reactor`:
+
+- default: `createAiSdkReactor()` (included in `@ekairos/thread`)
+- optional: custom/provider reactor via `.reactor(...)`
+
+```ts
+import { createThread, createAiSdkReactor } from "@ekairos/thread";
+
+const thread = createThread<{ orgId: string }>("my.thread")
+  .context((stored, env) => ({ ...(stored.content ?? {}), orgId: env.orgId }))
+  .narrative(() => "System prompt")
+  .actions(() => ({}))
+  .reactor(createAiSdkReactor())
+  .build();
+```
+
+`createAiSdkReactor` also accepts optional per-turn config hooks:
+
+```ts
+import { createAiSdkReactor } from "@ekairos/thread";
+
+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,
+});
+```
+
+Provider reactors live in `packages/reactors/*`:
+
+- `@ekairos/openai-reactor` (`createOpenAIReactor`, `createCodexReactor`)
+- `@ekairos/claude-reactor` (scaffold)
+- `@ekairos/cursor-reactor` (scaffold)
+
+### 3) Run from a workflow
+
+```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 },
+  });
+}
+```
+
+## Thread Lifecycle (Detailed)
+
+For each `react(...)` call:
+
+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.
+
+All side effects are executed through workflow-safe steps.
+
+## Event and Item Model
+
+Key utilities:
+
+- `createUserItemFromUIMessages(...)`
+- `createAssistantItemFromUIMessages(...)`
+- `convertItemsToModelMessages(...)`
+- `convertModelMessageToItem(...)`
+- `didToolExecute(...)`
+- `extractToolCallsFromParts(...)`
+
+This keeps a stable internal representation while remaining compatible with UI/model formats.
+
+## Runtime and Persistence
+
+Thread runtime resolves from `@ekairos/domain/runtime` bootstrap.
+
+Default persistence adapter:
+
+- `InstantStore` (`@ekairos/thread/instant`)
+
+Schema:
+
+- `thread_threads`
+- `thread_contexts`
+- `thread_items`
+- `thread_executions`
+- `thread_steps`
+- `thread_parts`
+- `thread_trace_events`
+- `thread_trace_runs`
+- `thread_trace_spans`
+
+Import domain schema:
+
+```ts
+import { threadDomain } from "@ekairos/thread/schema";
+```
+
+## Streaming
+
+Thread writes `UIMessageChunk` to workflow writable streams.
+
+Options:
+
+- `writable`: custom stream.
+- `silent`: disable stream writes, keep persistence.
+- `preventClose`: do not close writer.
+- `sendFinish`: control final `finish` chunk.
+
+Namespaced streams are supported using `context:<contextId>`.
+
+## Identity Model
+
+- `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.
+
+### Open Responses alignment
+
+Thread is protocol-aligned with Open Responses item/event semantics and keeps durable execution
+through Workflow.
+
+- 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.
+
+Example shape for a thread query response:
+
+```json
+{
+  "object": "conversation",
+  "id": "thread-key-or-id",
+  "status": "completed",
+  "context": {
+    "id": "ctx_123",
+    "key": "code.agent.session.abc",
+    "status": "completed",
+    "content": {}
+  }
+}
+```
+
+This extension is additive and does not break Open Responses compatibility.
+
+## 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
+
+Register and resolve threads by key:
+
+```ts
+import { registerThread, getThread } from "@ekairos/thread";
+```
+
+Builder convenience:
+
+```ts
+const builder = createThread<Env>("my.key").context(...).narrative(...).actions(...);
+builder.register();
+```
+
+## Preconfigured Codex Thread
+
+Use `@ekairos/thread/codex` to create coding threads with minimal wiring.
+
+```ts
+import { createCodexThreadBuilder } from "@ekairos/thread/codex";
+
+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: [],
+    };
+  },
+});
+```
+
+What it configures for you:
+
+- `codex` action schema,
+- default model selection (`openai/gpt-5.2`),
+- default continue rule (`stop after codex action executes`),
+- default narrative fallback.
+
+For direct Codex runtime (without "tool indirection"), use
+`@ekairos/openai-reactor` + `createCodexReactor(...)`.
+
+## MCP and OIDC
+
+Utilities are exposed for protocol integration:
+
+- `@ekairos/thread/mcp`
+- `@ekairos/thread/oidc`
+
+Use these from server-side API routes when exposing thread-driven tools via MCP.
+
+## DX Guidelines
+
+- 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).
+
+## Breaking-Change Policy
+
+Thread prioritizes runtime correctness over implicit compatibility shims.
+
+When behavior conflicts with durability or protocol clarity, explicit configuration is preferred over hidden fallbacks.

package/dist/codex.d.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+import type { ThreadEnvironment } from "./thread.config.js";
+import type { ThreadModelInit, ThreadOptions, ThreadReactParams, ThreadShouldContinueArgs, ThreadTool } from "./thread.engine.js";
+import type { ThreadKey } from "./thread.registry.js";
+import type { StoredContext, ThreadItem } from "./thread.store.js";
+import type { ThreadInstance } from "./thread.js";
+export declare const DEFAULT_CODEX_TOOL_NAME = "codex";
+export declare const DEFAULT_CODEX_MODEL = "openai/gpt-5.2";
+export type CodexThreadRuntimeMode = "local" | "remote" | "sandbox";
+export type CodexThreadReasoningLevel = "off" | "low" | "medium" | "high";
+export type CodexThreadRuntime = {
+    appServerUrl?: string;
+    repoPath?: string;
+    threadId?: string;
+    mode?: CodexThreadRuntimeMode;
+    model?: string;
+    approvalPolicy?: string;
+    sandboxPolicy?: Record<string, unknown>;
+};
+export type CodexThreadEnv = ThreadEnvironment & {
+    sessionId: string;
+    runtime?: CodexThreadRuntime;
+    reasoningLevel?: CodexThreadReasoningLevel;
+    model?: string;
+};
+export type CodexToolInput = {
+    instruction: string;
+    files?: Array<{
+        url?: string;
+        path?: string;
+        mediaType?: string;
+        fileId?: string;
+    }>;
+};
+export type CodexToolOutput = {
+    threadId: string;
+    turnId: string;
+    assistantText: string;
+    reasoningText: string;
+    diff: string;
+    toolParts: any[];
+};
+export declare const codexToolInputSchema: z.ZodObject<{
+    instruction: z.ZodString;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodOptional<z.ZodString>;
+        path: z.ZodOptional<z.ZodString>;
+        mediaType: z.ZodOptional<z.ZodString>;
+        fileId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type CodexExecuteArgs<Context, Env extends CodexThreadEnv = CodexThreadEnv> = {
+    context: StoredContext<Context>;
+    env: Env;
+    input: CodexToolInput;
+    toolName: string;
+};
+export type CodexThreadBuilderConfig<Context, Env extends CodexThreadEnv = CodexThreadEnv> = {
+    key: ThreadKey;
+    context: (context: StoredContext<Context>, env: Env) => Promise<Context> | Context;
+    executeCodex: (args: CodexExecuteArgs<Context, Env>) => Promise<CodexToolOutput>;
+    narrative?: (context: StoredContext<Context>, env: Env) => Promise<string> | string;
+    system?: (context: StoredContext<Context>, env: Env) => Promise<string> | string;
+    actions?: (context: StoredContext<Context>, env: Env) => Promise<Record<string, ThreadTool>> | Record<string, ThreadTool>;
+    model?: ThreadModelInit | ((context: StoredContext<Context>, env: Env) => ThreadModelInit);
+    shouldContinue?: (args: ThreadShouldContinueArgs<Context, Env>) => Promise<boolean> | boolean;
+    toolName?: string;
+    toolDescription?: string;
+    opts?: ThreadOptions<Context, Env>;
+};
+export type CodexThreadBuilder<Context, Env extends CodexThreadEnv = CodexThreadEnv> = {
+    key: ThreadKey;
+    react(triggerEvent: ThreadItem, params: ThreadReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    stream(triggerEvent: ThreadItem, params: ThreadReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    register(): void;
+    config(): unknown;
+    build(): ThreadInstance<Context, Env>;
+};
+export declare function buildDefaultCodexNarrative(content: unknown): string;
+export declare function didCodexToolExecute(event: Pick<{
+    content: any;
+}, "content">, toolName?: string): boolean;
+export declare function createCodexThreadBuilder<Context, Env extends CodexThreadEnv = CodexThreadEnv>(config: CodexThreadBuilderConfig<Context, Env>): CodexThreadBuilder<Context, Env>;

package/dist/codex.js

@@ -0,0 +1,91 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { createThread } from "./thread.js";
+import { didToolExecute } from "./thread.toolcalls.js";
+export const DEFAULT_CODEX_TOOL_NAME = "codex";
+export const DEFAULT_CODEX_MODEL = "openai/gpt-5.2";
+export const codexToolInputSchema = z.object({
+    instruction: z
+        .string()
+        .describe("The coding instruction to execute for this request."),
+    files: z
+        .array(z.object({
+        url: z.string().optional(),
+        path: z.string().optional(),
+        mediaType: z.string().optional(),
+        fileId: z.string().optional(),
+    }))
+        .optional(),
+});
+function toRecord(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    return value;
+}
+function toString(value) {
+    if (typeof value !== "string")
+        return "";
+    return value.trim();
+}
+export function buildDefaultCodexNarrative(content) {
+    const record = toRecord(content);
+    const sessionId = toString(record.sessionId);
+    const repoUrl = toString(record.repoUrl);
+    const branchName = toString(record.branchName);
+    return [
+        "You are Codex running as an Ekairos Thread.",
+        "",
+        "Execution style:",
+        "- Execute real coding work via the `codex` action.",
+        "- Keep answers concrete and implementation-oriented.",
+        "- Preserve repository and branch continuity across turns.",
+        "",
+        "Context:",
+        `- Session: ${sessionId || "unknown"}`,
+        `- Repository: ${repoUrl || "unknown"}`,
+        `- Branch: ${branchName || "unknown"}`,
+    ].join("\n");
+}
+export function didCodexToolExecute(event, toolName = DEFAULT_CODEX_TOOL_NAME) {
+    return didToolExecute(event, toolName);
+}
+export function createCodexThreadBuilder(config) {
+    const toolName = config.toolName ?? DEFAULT_CODEX_TOOL_NAME;
+    const toolDescription = config.toolDescription ??
+        "Run the coding request using a Codex app server and stream output.";
+    const narrative = config.narrative ??
+        config.system ??
+        ((ctx) => buildDefaultCodexNarrative(ctx?.content));
+    const model = config.model ??
+        ((_ctx, env) => (typeof env.model === "string" && env.model.trim()) || DEFAULT_CODEX_MODEL);
+    const shouldContinue = config.shouldContinue ??
+        ((args) => !didToolExecute(args.reactionEvent, toolName));
+    let builder = createThread(config.key)
+        .context(config.context)
+        .narrative(narrative)
+        .actions(async (ctx, env) => {
+        const additional = config.actions ? await config.actions(ctx, env) : {};
+        if (Object.prototype.hasOwnProperty.call(additional, toolName)) {
+            throw new Error(`createCodexThreadBuilder: action "${toolName}" is reserved for Codex.`);
+        }
+        return {
+            ...additional,
+            [toolName]: tool({
+                description: toolDescription,
+                inputSchema: codexToolInputSchema,
+                execute: async (input) => await config.executeCodex({
+                    context: ctx,
+                    env,
+                    input,
+                    toolName,
+                }),
+            }),
+        };
+    })
+        .model(model)
+        .shouldContinue(shouldContinue);
+    if (config.opts) {
+        builder = builder.opts(config.opts);
+    }
+    return builder;
+}

package/dist/env.d.ts

@@ -0,0 +1,12 @@
+import type { ThreadEnvironment } from "./thread.config.js";
+/**
+ * Register the current workflow env for later use inside "use step" functions.
+ *
+ * If runId is provided, it will be stored under that run. If not, a default env is set.
+ */
+export declare function registerThreadEnv(env: ThreadEnvironment, runId?: string | null): void;
+/**
+ * Resolve the env for the current workflow/step.
+ * Falls back to the default env if no run-specific env exists.
+ */
+export declare function getThreadEnv(): Promise<ThreadEnvironment>;

package/dist/env.js

@@ -0,0 +1,62 @@
+const envByRunIdSymbol = Symbol.for("ekairos.thread.envByRunId");
+const defaultEnvSymbol = Symbol.for("ekairos.thread.defaultEnv");
+function getEnvMap() {
+    if (typeof globalThis === "undefined")
+        return new Map();
+    const existing = globalThis[envByRunIdSymbol];
+    if (existing)
+        return existing;
+    const created = new Map();
+    globalThis[envByRunIdSymbol] = created;
+    return created;
+}
+function setDefaultEnv(env) {
+    if (typeof globalThis === "undefined")
+        return;
+    globalThis[defaultEnvSymbol] = env ?? null;
+}
+function getDefaultEnv() {
+    if (typeof globalThis === "undefined")
+        return null;
+    return globalThis[defaultEnvSymbol] ?? null;
+}
+/**
+ * Register the current workflow env for later use inside "use step" functions.
+ *
+ * If runId is provided, it will be stored under that run. If not, a default env is set.
+ */
+export function registerThreadEnv(env, runId) {
+    if (runId) {
+        getEnvMap().set(String(runId), env);
+        return;
+    }
+    setDefaultEnv(env);
+}
+async function tryGetWorkflowRunId() {
+    try {
+        const mod = await import("workflow");
+        const meta = mod?.getWorkflowMetadata?.();
+        const runId = meta?.workflowRunId;
+        return runId ? String(runId) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Resolve the env for the current workflow/step.
+ * Falls back to the default env if no run-specific env exists.
+ */
+export async function getThreadEnv() {
+    const runId = await tryGetWorkflowRunId();
+    if (runId) {
+        const stored = getEnvMap().get(runId);
+        if (stored)
+            return stored;
+    }
+    const fallback = getDefaultEnv();
+    if (fallback)
+        return fallback;
+    throw new Error("@ekairos/thread: env is not configured for this workflow run. " +
+        "Call registerThreadEnv(env) at workflow start or ensure the thread runtime registers env.");
+}

package/dist/events.d.ts

@@ -0,0 +1,35 @@
+import { type ModelMessage, type UIMessage } from "ai";
+import type { ContextEvent } from "./story.store.js";
+export declare const USER_MESSAGE_TYPE = "user.message";
+export declare const ASSISTANT_MESSAGE_TYPE = "assistant.message";
+export declare const SYSTEM_MESSAGE_TYPE = "system.message";
+export declare const WEB_CHANNEL = "web";
+export declare const AGENT_CHANNEL = "whatsapp";
+export declare const EMAIL_CHANNEL = "email";
+export declare function createUserEventFromUIMessages(messages: UIMessage[]): ContextEvent;
+export declare function createAssistantEventFromUIMessages(eventId: string, messages: UIMessage[]): ContextEvent;
+export declare function convertToUIMessage(event: ContextEvent): UIMessage;
+/**
+ * Converts stored ContextEvents to AI SDK ModelMessages.
+ *
+ * IMPORTANT:
+ * - Store-agnostic and workflow-safe.
+ * - Attachment/document handling MUST happen in the store boundary:
+ *   `StoryStore.eventsToModelMessages(events)`.
+ */
+export declare function convertEventsToModelMessages(events: ContextEvent[]): Promise<ModelMessage[]>;
+export declare function convertEventToModelMessages(event: ContextEvent): Promise<ModelMessage[]>;
+export type AIMessage = {
+    id: string;
+    role: "user" | "assistant" | "system";
+    content: string;
+    createdAt: Date;
+};
+export type ResponseMessage = {
+    id: string;
+    timestamp: Date;
+    modelId: string;
+    headers?: Record<string, string>;
+    message: ModelMessage;
+};
+export declare function convertModelMessageToEvent(eventId: string, message: ResponseMessage): ContextEvent;