@ekairos/events 1.22.23-beta.feature-events-package-refactor.0

package/README.md

@@ -0,0 +1,451 @@
+# @ekairos/thread
+
+Durable thread engine for Workflow-compatible AI agents.
+
+## Specification
+
+Normative contract and compatibility profile:
+
+- `SPEC.md`
+
+`@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.
+
+## Install
+
+```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`
+
+## 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
+createThread<Env>(key: ThreadKey)
+```
+
+Builder stages:
+
+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)
+
+Builder terminals:
+
+- `.build()` -> `ThreadInstance`
+- `.react(triggerEvent, params)`
+- `.stream(triggerEvent, params)` (deprecated alias)
+- `.register()`
+- `.config()`
+
+### `ThreadConfig<Context, Env>`
+
+Required keys:
+
+- `context`
+- `narrative`
+- `actions` (or legacy `tools`)
+
+Optional keys:
+
+- `expandEvents`
+- `model`
+- `reactor`
+- `shouldContinue`
+- `opts`
+
+### `Thread.react`
+
+Primary form:
+
+```ts
+thread.react(triggerEvent, {
+  env,
+  context: { id } | { key } | null,
+  options,
+})
+```
+
+Return shape:
+
+```ts
+{
+  contextId: string;
+  context: StoredContext<Context>;
+  triggerEventId: string;
+  reactionEventId: string;
+  executionId: string;
+}
+```
+
+### `ThreadStreamOptions`
+
+- `maxIterations?: number` (default `20`)
+- `maxModelSteps?: number` (default `1`)
+- `preventClose?: boolean` (default `false`)
+- `sendFinish?: boolean` (default `true`)
+- `silent?: boolean` (default `false`)
+- `writable?: WritableStream<UIMessageChunk>`
+
+### `ThreadOptions`
+
+Lifecycle callbacks:
+
+- `onContextCreated`
+- `onContextUpdated`
+- `onEventCreated`
+- `onToolCallExecuted`
+- `onEnd`
+
+## Reactor Specification
+
+A reactor receives the full execution context for one iteration and returns normalized assistant output + tool calls.
+
+### `ThreadReactorParams`
+
+- `env`
+- `context`
+- `contextIdentifier`
+- `triggerEvent`
+- `model`
+- `systemPrompt`
+- `actions`
+- `toolsForModel`
+- `eventId`
+- `executionId`
+- `contextId`
+- `stepId`
+- `iteration`
+- `maxModelSteps`
+- `sendStart`
+- `silent`
+- `writable`
+
+### `ThreadReactionResult`
+
+- `assistantEvent: ThreadItem`
+- `toolCalls: ThreadReactionToolCall[]`
+- `messagesForModel: ModelMessage[]`
+- `llm?: ThreadReactionLLM`
+
+## Built-in Reactors
+
+## `createAiSdkReactor` (production default)
+
+Uses AI SDK streaming + tool extraction through engine steps.
+
+```ts
+import { createAiSdkReactor } from "@ekairos/thread";
+
+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,
+});
+```
+
+Use in thread:
+
+```ts
+createThread<{ orgId: string }>("support.agent")
+  .context((stored, env) => ({ ...stored.content, orgId: env.orgId }))
+  .narrative(() => "You are a precise assistant")
+  .actions(() => ({}))
+  .reactor(reactor)
+  .build();
+```
+
+## `createScriptedReactor` (testing and deterministic local loops)
+
+No network/model calls. Returns scripted payloads per iteration.
+
+```ts
+import { createScriptedReactor } from "@ekairos/thread";
+
+const reactor = createScriptedReactor({
+  steps: [
+    {
+      assistantEvent: {
+        content: { parts: [{ type: "text", text: "Deterministic answer" }] },
+      },
+      toolCalls: [],
+      messagesForModel: [],
+    },
+  ],
+  repeatLast: true,
+});
+```
+
+Rules:
+
+- `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`
+
+## Production Pattern
+
+```ts
+import { createThread, createAiSdkReactor } from "@ekairos/thread";
+import { tool } from "ai";
+import { z } from "zod";
+
+type Env = { orgId: string; sessionId: string };
+
+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();
+```
+
+## Testing Pattern
+
+```ts
+import { createThread, createScriptedReactor } from "@ekairos/thread";
+
+type Env = { orgId: string };
+
+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();
+```
+
+## Stream Contract
+
+Thread stream events (`thread.stream.ts`) are entity-based.
+
+Hierarchy:
+
+1. context
+2. thread
+3. item
+4. step
+5. part
+6. chunk
+
+Event types:
+
+- `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`
+
+Chunk types (`THREAD_STREAM_CHUNK_TYPES`):
+
+- `data-context-id`
+- `data-context-substate`
+- `data-thread-ping`
+- `tool-output-available`
+- `tool-output-error`
+- `finish`
+
+Validation helpers:
+
+- `parseThreadStreamEvent(event)`
+- `assertThreadStreamTransitions(event)`
+- `validateThreadStreamTimeline(events)`
+
+## Transition Contract
+
+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`
+
+## Runtime and Schema
+
+- Import schema with `threadDomain` from `@ekairos/thread/schema`
+- Store integration defaults to `InstantStore`
+- Runtime must be configured via `@ekairos/domain/runtime` in host app
+
+Persisted entities:
+
+- `thread_threads`
+- `thread_contexts`
+- `thread_items`
+- `thread_executions`
+- `thread_steps`
+- `thread_parts`
+- `thread_trace_events`
+- `thread_trace_runs`
+- `thread_trace_spans`
+
+## Notes for Productive Usage
+
+- 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/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/events: env is not configured for this workflow run. " +
+        "Call registerThreadEnv(env) at workflow start or ensure the thread runtime registers env.");
+}