@ekairos/events 1.22.34-beta.development.0 → 1.22.35

package/README.md

@@ -2,114 +2,89 @@
 
 Context-first durable execution runtime for Ekairos.
 
-## Surface
+## What this package does
 
-- `createContext`, `context`, `ContextEngine`
-- `createAiSdkReactor`, `createScriptedReactor`
-- `useContext`
+- creates durable contexts with `createContext(...)`
+- persists executions, steps, parts, and items
+- runs direct or durable `react(...)` loops
+- adapts model/tool output into canonical `event_parts`
+
+## Main APIs
+
+- `createContext`
+- `ContextEngine`
+- `createAiSdkReactor`
+- `createScriptedReactor`
+- `runContextReactionDirect`
 - `eventsDomain`
-- `getContextRuntime`, `getContextEnv`, `registerContextEnv`
 
 ## Runtime model
 
+Canonical entities:
+
 - `event_contexts`
 - `event_items`
 - `event_executions`
 - `event_steps`
 - `event_parts`
-- `event_trace_events`
-- `event_trace_runs`
-- `event_trace_spans`
-
-The aggregate is `context`. Executions, steps, parts, and items are scoped to a context.
-
-## Canonical Parts
+- `event_trace_*`
 
-`event_parts` is the canonical content model for produced output.
+`event_parts` is the source of truth for replay.
 
-Rules:
-
-- `event_parts.part` is the source of truth for replay and inspection.
-- `event_items.content.parts` on output items is maintained as a compatibility mirror and is deprecated as a replay source.
-- Provider/model-specific values must live under `metadata`, never as first-class semantic fields.
-
-Canonical part kinds:
-
-- `content`
-- `reasoning`
-- `source`
-- `tool-call`
-- `tool-result`
+## Example
 
-Each canonical part stores a `content` array. The entries inside that array define the payload type:
+```ts
+import { createContext } from "@ekairos/events";
 
-- `text`
-- `file`
-- `json`
-- `source-url`
-- `source-document`
+const supportContext = createContext<{ orgId: string }>("support.agent")
+  .context((stored, env) => ({
+    ...stored.content,
+    orgId: env.orgId,
+  }))
+  .narrative(() => "You are a precise assistant.")
+  .actions(() => ({}))
+  .build();
+```
 
-Example tool result:
+Run directly:
 
 ```ts
-{
-  type: "tool-result",
-  toolCallId: "call_123",
-  toolName: "inspectCanvasRegion",
-  state: "output-available",
-  content: [
-    {
-      type: "text",
-      text: "Zoomed crop of the requested region.",
-    },
-    {
-      type: "file",
-      mediaType: "image/png",
-      filename: "inspect-region.png",
-      data: "iVBORw0KGgoAAAANSUhEUgAA...",
-    },
-  ],
-  metadata: {
-    provider: {
-      itemId: "fc_041cb...",
-    },
-  },
-}
-```
-
-The AI SDK bridge projects canonical parts to:
+const shell = await supportContext.react(triggerEvent, {
+  runtime,
+  context: { key: "support:org_123" },
+  durable: false,
+});
 
-- assistant messages with text/file/reasoning/source/tool-call parts
-- tool messages with `tool-result` or `tool-error`
+const final = await shell.run!;
+```
 
-That means multipart tool outputs are replayed from `event_parts` instead of relying on the deprecated output-item mirror.
+Run durably:
 
-## Install
+```ts
+const shell = await supportContext.react(triggerEvent, {
+  runtime,
+  context: { key: "support:org_123" },
+});
 
-```bash
-pnpm add @ekairos/events
+const final = await shell.run!.returnValue;
 ```
 
-## Example
-
-```ts
-import { createContext, createAiSdkReactor } from "@ekairos/events";
+## Tool execution model
 
-type Env = { orgId: string };
+Context tools now receive runtime-aware execution context.
+That lets a tool do this inside `"use step"`:
 
-export const supportContext = createContext<Env>("support.agent")
-  .context((stored, env) => ({
-    orgId: env.orgId,
-    ...stored.content,
-  }))
-  .narrative(() => "You are a precise assistant.")
-  .actions(() => ({}))
-  .reactor(createAiSdkReactor())
-  .build();
+```ts
+async function execute(input, ctx) {
+  "use step";
+  const domain = await ctx.runtime.use(myDomain);
+  return await domain.actions.doSomething(input);
+}
 ```
 
-## Notes
+## Tests
 
-- Public continuity is context-based.
-- Provider-specific IDs such as `providerContextId` may still exist when an upstream provider requires them.
-- Runtime wiring for stores lives under `@ekairos/events/runtime`.
+```bash
+pnpm --filter @ekairos/events test
+pnpm --filter @ekairos/events test:workflow
+```

package/dist/codex.d.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import type { ContextEnvironment } from "./context.config.js";
-import type { ContextModelInit, ContextOptions, ContextReactParams, ContextShouldContinueArgs, ContextTool } from "./context.engine.js";
+import type { ContextModelInit, ContextOptions, ContextReactParams, ContextShouldContinueArgs } from "./context.engine.js";
+import type { ContextTool } from "./context.action.js";
 import type { ContextKey } from "./context.registry.js";
 import type { StoredContext, ContextItem } from "./context.store.js";
 import type { ContextInstance } from "./context.js";
@@ -49,6 +50,14 @@ export declare const codexToolInputSchema: z.ZodObject<{
         fileId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
 }, z.core.$strip>;
+export declare const codexToolOutputSchema: z.ZodObject<{
+    contextId: z.ZodString;
+    turnId: z.ZodString;
+    assistantText: z.ZodString;
+    reasoningText: z.ZodString;
+    diff: z.ZodString;
+    toolParts: z.ZodArray<z.ZodAny>;
+}, z.core.$strip>;
 export type CodexExecuteArgs<Context, Env extends CodexContextEnv = CodexContextEnv> = {
     context: StoredContext<Context>;
     env: Env;
@@ -61,7 +70,7 @@ export type CodexContextBuilderConfig<Context, Env extends CodexContextEnv = Cod
     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, ContextTool>> | Record<string, ContextTool>;
+    actions?: (context: StoredContext<Context>, env: Env) => Promise<Record<string, ContextTool<Context, Env>>> | Record<string, ContextTool<Context, Env>>;
     model?: ContextModelInit | ((context: StoredContext<Context>, env: Env) => ContextModelInit);
     shouldContinue?: (args: ContextShouldContinueArgs<Context, Env>) => Promise<boolean> | boolean;
     toolName?: string;

package/dist/codex.js

@@ -1,7 +1,6 @@
-import { tool } from "ai";
 import { z } from "zod";
-import { createContext } from "./context.js";
-import { didToolExecute } from "./context.toolcalls.js";
+import { createContext, defineAction } from "./context.js";
+import { didActionExecute } from "./context.action-calls.js";
 export const DEFAULT_CODEX_TOOL_NAME = "codex";
 export const DEFAULT_CODEX_MODEL = "openai/gpt-5.2";
 export const codexToolInputSchema = z.object({
@@ -17,6 +16,14 @@ export const codexToolInputSchema = z.object({
     }))
         .optional(),
 });
+export const codexToolOutputSchema = z.object({
+    contextId: z.string(),
+    turnId: z.string(),
+    assistantText: z.string(),
+    reasoningText: z.string(),
+    diff: z.string(),
+    toolParts: z.array(z.any()),
+});
 function toRecord(value) {
     if (!value || typeof value !== "object")
         return {};
@@ -47,7 +54,7 @@ export function buildDefaultCodexNarrative(content) {
     ].join("\n");
 }
 export function didCodexToolExecute(event, toolName = DEFAULT_CODEX_TOOL_NAME) {
-    return didToolExecute(event, toolName);
+    return didActionExecute(event, toolName);
 }
 export function createCodexContextBuilder(config) {
     const toolName = config.toolName ?? DEFAULT_CODEX_TOOL_NAME;
@@ -59,7 +66,7 @@ export function createCodexContextBuilder(config) {
     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));
+        ((args) => !didActionExecute(args.reactionEvent, toolName));
     let builder = createContext(config.key)
         .context(config.context)
         .narrative(narrative)
@@ -70,10 +77,11 @@ export function createCodexContextBuilder(config) {
         }
         return {
             ...additional,
-            [toolName]: tool({
+            [toolName]: defineAction({
                 description: toolDescription,
-                inputSchema: codexToolInputSchema,
-                execute: async (input) => await config.executeCodex({
+                input: codexToolInputSchema,
+                output: codexToolOutputSchema,
+                execute: async ({ input }) => await config.executeCodex({
                     context: ctx,
                     env,
                     input,

package/dist/context.action-calls.d.ts

@@ -0,0 +1,48 @@
+/**
+ * ## context.action-calls.ts
+ *
+ * This module isolates the **action-call plumbing** used by `context.engine.ts`.
+ *
+ * In our runtime, provider tool calls are normalized into semantic `action` event parts.
+ * The engine needs to:
+ * - extract a normalized list of action requests from `event.content.parts`, and
+ * - merge action execution outcomes back into those parts.
+ *
+ * Keeping this logic here helps `context.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+import type { ContextItem } from "./context.store.js";
+export type ContextActionCall = {
+    actionCallId: string;
+    actionName: string;
+    args: any;
+};
+/**
+ * Extracts action requests from an event's `parts` array.
+ *
+ * Also accepts raw AI SDK tool UI parts before persistence normalization.
+ */
+export declare function extractActionCallsFromParts(parts: any[] | undefined | null): ContextActionCall[];
+/**
+ * Applies an action execution outcome to the matching action part.
+ *
+ * This does not mutate `parts` — it returns a new array.
+ *
+ * We match by action name and action call id.
+ */
+export declare function applyActionExecutionResultToParts(parts: any[], actionCall: Pick<ContextActionCall, "actionCallId" | "actionName">, execution: {
+    success: boolean;
+    result: any;
+    message?: string;
+}): any[];
+/**
+ * Returns `true` when a given action has a **settled** execution result in an event's parts.
+ *
+ * We treat an action part as "executed" once it has either:
+ * - `state: "output-available"` (success), or
+ * - `state: "output-error"` (failure).
+ *
+ * This is useful for stop/continue logic in `context.shouldContinue(...)` where you want to
+ * decide based on the persisted `reactionEvent` (not ephemeral in-memory arrays).
+ */
+export declare function didActionExecute(event: Pick<ContextItem, "content">, actionName: string): boolean;

package/dist/context.action-calls.js

@@ -0,0 +1,123 @@
+/**
+ * ## context.action-calls.ts
+ *
+ * This module isolates the **action-call plumbing** used by `context.engine.ts`.
+ *
+ * In our runtime, provider tool calls are normalized into semantic `action` event parts.
+ * The engine needs to:
+ * - extract a normalized list of action requests from `event.content.parts`, and
+ * - merge action execution outcomes back into those parts.
+ *
+ * Keeping this logic here helps `context.engine.ts` read like orchestration, and keeps
+ * these transformations testable and reusable.
+ */
+import { isContextPartEnvelope, normalizePartsForPersistence, } from "./context.parts.js";
+/**
+ * Extracts action requests from an event's `parts` array.
+ *
+ * Also accepts raw AI SDK tool UI parts before persistence normalization.
+ */
+export function extractActionCallsFromParts(parts) {
+    const safeParts = parts ?? [];
+    return safeParts.reduce((acc, p) => {
+        if (isContextPartEnvelope(p) && p.type === "action" && p.content.status === "started") {
+            acc.push({
+                actionCallId: p.content.actionCallId,
+                actionName: p.content.actionName,
+                args: p.content.input,
+            });
+            return acc;
+        }
+        if (typeof p?.type === "string" && p.type.startsWith("tool-")) {
+            const actionName = p.type.split("-").slice(1).join("-");
+            acc.push({ actionCallId: p.toolCallId, actionName, args: p.input });
+        }
+        return acc;
+    }, []);
+}
+/**
+ * Applies an action execution outcome to the matching action part.
+ *
+ * This does not mutate `parts` — it returns a new array.
+ *
+ * We match by action name and action call id.
+ */
+export function applyActionExecutionResultToParts(parts, actionCall, execution) {
+    const normalized = normalizePartsForPersistence(parts);
+    const next = [];
+    let insertedResult = false;
+    for (const part of normalized) {
+        next.push(part);
+        if (part.type !== "action" || part.content.status !== "started") {
+            continue;
+        }
+        if (part.content.actionCallId !== actionCall.actionCallId ||
+            part.content.actionName !== actionCall.actionName) {
+            continue;
+        }
+        next.push(execution.success
+            ? {
+                type: "action",
+                content: {
+                    status: "completed",
+                    actionCallId: actionCall.actionCallId,
+                    actionName: actionCall.actionName,
+                    output: execution.result,
+                },
+            }
+            : {
+                type: "action",
+                content: {
+                    status: "failed",
+                    actionCallId: actionCall.actionCallId,
+                    actionName: actionCall.actionName,
+                    error: {
+                        message: String(execution.message || "Error"),
+                    },
+                },
+            });
+        insertedResult = true;
+    }
+    if (!insertedResult) {
+        next.push(execution.success
+            ? {
+                type: "action",
+                content: {
+                    status: "completed",
+                    actionCallId: actionCall.actionCallId,
+                    actionName: actionCall.actionName,
+                    output: execution.result,
+                },
+            }
+            : {
+                type: "action",
+                content: {
+                    status: "failed",
+                    actionCallId: actionCall.actionCallId,
+                    actionName: actionCall.actionName,
+                    error: {
+                        message: String(execution.message || "Error"),
+                    },
+                },
+            });
+    }
+    return next;
+}
+/**
+ * Returns `true` when a given action has a **settled** execution result in an event's parts.
+ *
+ * We treat an action part as "executed" once it has either:
+ * - `state: "output-available"` (success), or
+ * - `state: "output-error"` (failure).
+ *
+ * This is useful for stop/continue logic in `context.shouldContinue(...)` where you want to
+ * decide based on the persisted `reactionEvent` (not ephemeral in-memory arrays).
+ */
+export function didActionExecute(event, actionName) {
+    const parts = (event.content.parts ?? []).flatMap((part) => isContextPartEnvelope(part) ? [part] : normalizePartsForPersistence([part]));
+    return parts.some((p) => (p.type === "action" &&
+        p.content.actionName === actionName &&
+        (p.content.status === "completed" || p.content.status === "failed")) ||
+        (p.type === `tool-${actionName}` &&
+            (p.state === "output-available" || p.state === "output-error")));
+}

package/dist/context.action.d.ts

@@ -0,0 +1,55 @@
+import type { DomainLike } from "@ekairos/domain";
+import type { z } from "zod";
+import type { ContextEnvironment } from "./context.config.js";
+import type { ContextToolExecuteContext } from "./context.engine.js";
+import type { ContextRuntime } from "./context.runtime.js";
+import { eventsDomain } from "./schema.js";
+type MaybePromise<T> = T | Promise<T>;
+export type ContextActionSchema = z.ZodType;
+export type ContextActionBase = {
+    type?: "function";
+    description?: string;
+    providerOptions?: unknown;
+    auto?: boolean;
+};
+export type ContextProviderDefinedAction = {
+    type: "provider-defined";
+    id: string;
+    name?: string;
+    args?: Record<string, unknown>;
+    auto?: boolean;
+};
+export type ContextActionExecuteParams<TInput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = ContextToolExecuteContext<Context, Env, RequiredDomain, Runtime> & {
+    input: z.output<TInput>;
+};
+export type DefineContextActionExecute<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = (params: ContextActionExecuteParams<TInput, Context, Env, RequiredDomain, Runtime>) => MaybePromise<z.output<TOutput>>;
+export type ContextActionExecute<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = DefineContextActionExecute<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+export type LegacyContextActionExecute<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = (input: z.output<TInput>, context: ContextToolExecuteContext<Context, Env, RequiredDomain, Runtime>) => MaybePromise<z.output<TOutput>>;
+export type DefineContextActionDefinition<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = ContextActionBase & {
+    input: TInput;
+    output: TOutput;
+    execute: DefineContextActionExecute<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+};
+export type LegacyContextActionDefinition<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = ContextActionBase & {
+    input: TInput;
+    output: TOutput;
+    execute: LegacyContextActionExecute<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+};
+export type ContextActionDefinition<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = DefineContextActionDefinition<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+export type ContextAction<TInput extends ContextActionSchema = ContextActionSchema, TOutput extends ContextActionSchema = ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = ContextActionBase & {
+    input: TInput;
+    output: TOutput;
+    inputSchema: TInput;
+    outputSchema: TOutput;
+    execute: LegacyContextActionExecute<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+};
+export type AnyContextAction = ContextAction<ContextActionSchema, ContextActionSchema, any, any, any, any>;
+export type ContextTool<Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = ContextAction<ContextActionSchema, ContextActionSchema, Context, Env, RequiredDomain, Runtime> | ContextProviderDefinedAction;
+export type ContextActionInput<TAction> = TAction extends ContextAction<infer TInput, any, any, any> ? z.output<TInput> : never;
+export type ContextActionOutput<TAction> = TAction extends ContextAction<any, infer TOutput, any, any> ? z.output<TOutput> : never;
+export declare function defineAction<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>>(definition: DefineContextActionDefinition<TInput, TOutput, Context, Env, RequiredDomain, Runtime>): ContextAction<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+/**
+ * @deprecated Use defineAction().
+ */
+export declare function action<TInput extends ContextActionSchema, TOutput extends ContextActionSchema, Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>>(definition: LegacyContextActionDefinition<TInput, TOutput, Context, Env, RequiredDomain, Runtime>): ContextAction<TInput, TOutput, Context, Env, RequiredDomain, Runtime>;
+export {};

package/dist/context.action.js

@@ -0,0 +1,25 @@
+function createContextAction(definition, invoke) {
+    const execute = async (input, context) => {
+        const parsedInput = definition.input.parse(input);
+        const result = await invoke(parsedInput, context);
+        return definition.output.parse(result);
+    };
+    return {
+        ...definition,
+        inputSchema: definition.input,
+        outputSchema: definition.output,
+        execute,
+    };
+}
+export function defineAction(definition) {
+    return createContextAction(definition, async (input, context) => await definition.execute({
+        ...context,
+        input,
+    }));
+}
+/**
+ * @deprecated Use defineAction().
+ */
+export function action(definition) {
+    return createContextAction(definition, async (input, context) => await definition.execute(input, context));
+}