@ekairos/events 1.22.4-beta.feature-events-package-refactor.0 → 1.22.5-beta.development.0

package/README.md

@@ -2,53 +2,87 @@
 
 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.
+- `event_trace_*`
 
-## Install
-
-```bash
-pnpm add @ekairos/events
-```
+`event_parts` is the source of truth for replay.
 
 ## Example
 
 ```ts
-import { createContext, createAiSdkReactor } from "@ekairos/events";
+import { createContext } from "@ekairos/events";
 
-type Env = { orgId: string };
-
-export const supportContext = createContext<Env>("support.agent")
+const supportContext = createContext<{ orgId: string }>("support.agent")
   .context((stored, env) => ({
-    orgId: env.orgId,
     ...stored.content,
+    orgId: env.orgId,
   }))
   .narrative(() => "You are a precise assistant.")
   .actions(() => ({}))
-  .reactor(createAiSdkReactor())
   .build();
 ```
 
-## Notes
+Run directly:
+
+```ts
+await supportContext.react(triggerEvent, {
+  runtime,
+  context: { key: "support:org_123" },
+});
+```
+
+Run durably:
+
+```ts
+const shell = await supportContext.react(triggerEvent, {
+  runtime,
+  context: { key: "support:org_123" },
+  durable: true,
+});
+
+const final = await shell.run?.returnValue;
+```
+
+## Tool execution model
+
+Context tools now receive runtime-aware execution context.
+That lets a tool do this inside `"use step"`:
 
-- 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`.
+```ts
+async function execute(input, ctx) {
+  "use step";
+  const domain = await ctx.runtime.use(myDomain);
+  return await domain.actions.doSomething(input);
+}
+```
+
+## Tests
+
+```bash
+pnpm --filter @ekairos/events test
+pnpm --filter @ekairos/events test:workflow
+```

package/dist/context.builder.d.ts

@@ -1,4 +1,5 @@
 import type { ContextEnvironment } from "./context.config.js";
+import type { ContextSkillPackage } from "./context.skill.js";
 import { ContextEngine, type ContextModelInit, type ContextOptions, type ContextTool, type ShouldContinue, type ContextShouldContinueArgs, type ContextReactParams } from "./context.engine.js";
 import type { ContextReactor } from "./context.reactor.js";
 import type { ContextItem, StoredContext } from "./context.store.js";
@@ -7,6 +8,7 @@ export interface ContextConfig<Context, Env extends ContextEnvironment = Context
     context: (context: StoredContext<Context>, env: Env) => Promise<Context> | Context;
     expandEvents?: (events: ContextItem[], context: StoredContext<Context>, env: Env) => Promise<ContextItem[]> | ContextItem[];
     narrative: (context: StoredContext<Context>, env: Env) => Promise<string> | string;
+    skills?: (context: StoredContext<Context>, env: Env) => Promise<ContextSkillPackage[]> | ContextSkillPackage[];
     actions: (context: StoredContext<Context>, env: Env) => Promise<Record<string, ContextTool>> | Record<string, ContextTool>;
     /**
      * @deprecated Use `actions()` instead.
@@ -25,6 +27,7 @@ export declare function context<Context, Env extends ContextEnvironment = Contex
 type AnyContextInitializer<Env extends ContextEnvironment> = (context: StoredContext<any>, env: Env) => Promise<any> | any;
 type InferContextFromInitializer<I extends AnyContextInitializer<any>> = Awaited<ReturnType<I>>;
 type BuilderSystemPrompt<Context, Env extends ContextEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<string> | string;
+type BuilderSkills<Context, Env extends ContextEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<ContextSkillPackage[]> | ContextSkillPackage[];
 type BuilderTools<Context, Env extends ContextEnvironment> = (context: StoredContext<Context>, env: Env) => Promise<Record<string, ContextTool>> | Record<string, ContextTool>;
 type BuilderExpandEvents<Context, Env extends ContextEnvironment> = (events: ContextItem[], context: StoredContext<Context>, env: Env) => Promise<ContextItem[]> | ContextItem[];
 type BuilderShouldContinue<Context, Env extends ContextEnvironment> = (args: ContextShouldContinueArgs<Context, Env>) => Promise<ShouldContinue> | ShouldContinue;
@@ -38,6 +41,7 @@ type FluentContextBuilder<Context, Env extends ContextEnvironment> = {
     expandEvents(fn: BuilderExpandEvents<Context, Env>): FluentContextBuilder<Context, Env>;
     narrative(fn: BuilderSystemPrompt<Context, Env>): FluentContextBuilder<Context, Env>;
     system(fn: BuilderSystemPrompt<Context, Env>): FluentContextBuilder<Context, Env>;
+    skills(fn: BuilderSkills<Context, Env>): FluentContextBuilder<Context, Env>;
     actions(fn: BuilderTools<Context, Env>): FluentContextBuilder<Context, Env>;
     tools(fn: BuilderTools<Context, Env>): FluentContextBuilder<Context, Env>;
     model(model: BuilderModel<Context, Env>): FluentContextBuilder<Context, Env>;

package/dist/context.builder.js

@@ -22,6 +22,11 @@ export function context(config) {
                 return config.narrative(contextValue, env);
             throw new Error("Context config is missing narrative()");
         }
+        async buildSkills(contextValue, env) {
+            if (config.skills)
+                return config.skills(contextValue, env);
+            return [];
+        }
         async buildTools(contextValue, env) {
             if (config.actions)
                 return config.actions(contextValue, env);
@@ -84,6 +89,10 @@ export function createContext(key) {
                 fluentState.narrative = system;
                 return builder;
             },
+            skills(skillsFactory) {
+                fluentState.skills = skillsFactory;
+                return builder;
+            },
             actions(actionsFactory) {
                 fluentState.actions = actionsFactory;
                 return builder;

package/dist/context.d.ts

@@ -1,3 +1,4 @@
-export { ContextEngine, type ContextOptions, type ContextStreamOptions, type ShouldContinue, type ContextShouldContinueArgs, type ContextReactParams, type ContextReactResult, type ContextDurableWorkflowPayload, type ContextDurableWorkflowFunction, type ContextModelInit, type ContextTool, runContextReactionDirect, } from "./context.engine.js";
+export { ContextEngine, type ContextOptions, type ContextStreamOptions, type ShouldContinue, type ContextShouldContinueArgs, type ContextReactParams, type ContextReactResult, type ContextWorkflowRun, type ContextDurableWorkflowPayload, type ContextDurableWorkflowFunction, type ContextModelInit, type ContextTool, type ContextToolExecuteContext, runContextReactionDirect, } from "./context.engine.js";
 export { context, createContext, type ContextConfig, type ContextInstance, type RegistrableContextBuilder, } from "./context.builder.js";
 export { createAiSdkReactor, createScriptedReactor, type CreateAiSdkReactorOptions, type CreateScriptedReactorOptions, type ScriptedReactorStep, type ContextReactor, type ContextReactorParams, type ContextReactionResult, type ContextActionRequest, type ContextReactionLLM, } from "./context.reactor.js";
+export type { ContextSkillPackage, ContextSkillPackageFile, } from "./context.skill.js";

package/dist/context.engine.d.ts

@@ -1,6 +1,8 @@
-import type { Tool, UIMessageChunk } from "ai";
+import type { ModelMessage, Tool, UIMessageChunk } from "ai";
 import type { ContextEnvironment } from "./context.config.js";
+import type { ContextRuntime } from "./context.runtime.js";
 import type { ContextExecution, ContextItem, ContextIdentifier, StoredContext } from "./context.store.js";
+import type { ContextSkillPackage } from "./context.skill.js";
 import { type ContextReactor } from "./context.reactor.js";
 import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken } from "./context.hooks.js";
 export interface ContextOptions<Context = any, Env extends ContextEnvironment = ContextEnvironment> {
@@ -67,7 +69,7 @@ export interface ContextStreamOptions {
  */
 export type ContextModelInit = string | (() => Promise<any>);
 export type ContextReactParams<Env extends ContextEnvironment = ContextEnvironment> = {
-    env: Env;
+    runtime: ContextRuntime<Env>;
     /**
      * Context selector (exclusive: `{ id }` OR `{ key }`).
      * - `{ id }` resolves a concrete context id.
@@ -94,16 +96,36 @@ export type ContextReactResult<Context = any> = {
     trigger: ContextItem;
     reaction: ContextItem;
     execution: ContextExecution;
+    run?: ContextWorkflowRun<Context>;
+};
+export type ContextWorkflowRun<Context = any> = {
+    runId: string;
+    status: Promise<"pending" | "running" | "completed" | "failed" | "cancelled">;
+    returnValue: Promise<ContextReactResult<Context>>;
 };
 export type ContextDurableWorkflowPayload<Env extends ContextEnvironment = ContextEnvironment> = {
     contextKey: string;
-    env: Env;
+    runtime: ContextRuntime<Env>;
     context?: ContextIdentifier | null;
     triggerEvent: ContextItem;
     options?: Omit<ContextStreamOptions, "writable">;
     bootstrap: NonNullable<ContextReactParams<Env>["__bootstrap"]>;
 };
 export type ContextDurableWorkflowFunction<Context = any, Env extends ContextEnvironment = ContextEnvironment> = (payload: ContextDurableWorkflowPayload<Env>) => Promise<ContextReactResult<Context>>;
+export type ContextToolExecuteContext<Context = any, Env extends ContextEnvironment = ContextEnvironment> = {
+    runtime: ContextRuntime<Env>;
+    env: Env;
+    context: StoredContext<Context>;
+    contextIdentifier: ContextIdentifier;
+    toolCallId: string;
+    messages: ModelMessage[];
+    eventId: string;
+    executionId: string;
+    triggerEventId: string;
+    contextId: string;
+    stepId: string;
+    iteration: number;
+};
 export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
 /**
  * Context-level tool type.
@@ -168,6 +190,7 @@ export declare abstract class ContextEngine<Context, Env extends ContextEnvironm
     protected abstract initialize(context: StoredContext<Context>, env: Env): Promise<Context> | Context;
     protected abstract buildSystemPrompt(context: StoredContext<Context>, env: Env): Promise<string> | string;
     protected abstract buildTools(context: StoredContext<Context>, env: Env): Promise<Record<string, ContextTool>> | Record<string, ContextTool>;
+    protected buildSkills(_context: StoredContext<Context>, _env: Env): Promise<ContextSkillPackage[]>;
     /**
      * First-class event expansion stage (runs on every iteration of the durable loop).
      *

package/dist/context.engine.js

@@ -1,9 +1,10 @@
-import { registerContextEnv } from "./env.js";
+import { getContextRuntimeServices } from "./context.runtime.js";
 import { OUTPUT_ITEM_TYPE, WEB_CHANNEL } from "./context.events.js";
 import { applyToolExecutionResultToParts } from "./context.toolcalls.js";
+import { isContextPartEnvelope, normalizePartsForPersistence, } from "./context.parts.js";
 import { toolsToModelTools } from "./tools-to-model-tools.js";
 import { createAiSdkReactor, } from "./context.reactor.js";
-import { closeContextStream, } from "./steps/stream.steps.js";
+import { abortPersistedContextStepStream, closePersistedContextStepStream, createPersistedContextStepStream, closeContextStream, } from "./steps/stream.steps.js";
 import { completeExecution, createContextStep, initializeContext, saveTriggerAndCreateExecution, saveContextPartsStep, updateContextContent, updateContextStatus, updateItem, updateContextStep, } from "./steps/store.steps.js";
 import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken, } from "./context.hooks.js";
 import { getContextDurableWorkflow } from "./context.durable.js";
@@ -22,6 +23,20 @@ function clipPreview(value, max = 240) {
 function summarizePartPreview(part) {
     if (!part || typeof part !== "object")
         return {};
+    if (isContextPartEnvelope(part)) {
+        const preview = part.content[0]?.type === "text"
+            ? part.content[0].text
+            : JSON.stringify(part.content[0] ?? part);
+        const state = "state" in part && typeof part.state === "string" ? part.state : undefined;
+        const toolCallId = "toolCallId" in part && typeof part.toolCallId === "string"
+            ? part.toolCallId
+            : undefined;
+        return {
+            partPreview: preview ? clipPreview(preview) : undefined,
+            partState: state,
+            partToolCallId: toolCallId,
+        };
+    }
     const row = part;
     const partType = typeof row.type === "string" ? row.type : "";
     const partState = typeof row.state === "string" ? row.state : undefined;
@@ -74,9 +89,8 @@ async function readActiveWorkflowRunId() {
         return null;
     }
 }
-async function createRuntimeOps(env, benchmark) {
-    const { getContextRuntime } = await import("./runtime.js");
-    const runtime = await getContextRuntime(env);
+async function createRuntimeOps(runtimeHandle, benchmark) {
+    const runtime = await getContextRuntimeServices(runtimeHandle);
     const { db } = runtime;
     const { InstantStore } = await import("./stores/instant.store.js");
     const requireContextId = (contextIdentifier) => {
@@ -240,33 +254,36 @@ async function createRuntimeOps(env, benchmark) {
         },
     };
 }
-async function createWorkflowOps(env) {
+async function createWorkflowOps(runtime) {
+    const env = runtime.env;
     return {
-        initializeContext: async (contextIdentifier, opts) => await initializeContext(env, contextIdentifier, opts),
-        updateContextContent: async (contextIdentifier, content) => await updateContextContent(env, contextIdentifier, content),
-        updateContextStatus: async (contextIdentifier, status) => await updateContextStatus(env, contextIdentifier, status),
-        saveTriggerAndCreateExecution: async ({ contextIdentifier, triggerEvent }) => await saveTriggerAndCreateExecution({ env, contextIdentifier, triggerEvent }),
-        createContextStep: async ({ executionId, iteration }) => await createContextStep({ env, executionId, iteration }),
-        updateContextStep: async (params) => await updateContextStep({ env, ...params }),
-        saveContextPartsStep: async (params) => await saveContextPartsStep({ env, ...params }),
-        updateItem: async (itemId, item, opts) => await updateItem(env, itemId, item, opts),
-        completeExecution: async (contextIdentifier, executionId, status) => await completeExecution(env, contextIdentifier, executionId, status),
+        initializeContext: async (contextIdentifier, opts) => await initializeContext({ runtime, contextIdentifier, opts }),
+        updateContextContent: async (contextIdentifier, content) => await updateContextContent({ runtime, contextIdentifier, content }),
+        updateContextStatus: async (contextIdentifier, status) => await updateContextStatus({ runtime, contextIdentifier, status }),
+        saveTriggerAndCreateExecution: async ({ contextIdentifier, triggerEvent }) => await saveTriggerAndCreateExecution({ runtime, contextIdentifier, triggerEvent }),
+        createContextStep: async ({ executionId, iteration }) => await createContextStep({ runtime, executionId, iteration }),
+        updateContextStep: async (params) => await updateContextStep({ runtime, ...params }),
+        saveContextPartsStep: async (params) => await saveContextPartsStep({ runtime, ...params }),
+        updateItem: async (itemId, item, opts) => await updateItem({ runtime, eventId: itemId, event: item, opts }),
+        completeExecution: async (contextIdentifier, executionId, status) => await completeExecution({ runtime, contextIdentifier, executionId, status }),
     };
 }
-async function getContextEngineOps(env, benchmark) {
+async function getContextEngineOps(runtime, benchmark) {
+    const env = runtime.env;
     const workflowRunId = await readActiveWorkflowRunId();
     if (workflowRunId) {
-        registerContextEnv(env, workflowRunId);
-        return await createWorkflowOps(env);
+        return await createWorkflowOps(runtime);
     }
-    registerContextEnv(env);
-    return await createRuntimeOps(env, benchmark);
+    return await createRuntimeOps(runtime, benchmark);
 }
 export class ContextEngine {
     constructor(opts = {}, reactor) {
         this.opts = opts;
         this.reactor = reactor ?? createAiSdkReactor();
     }
+    async buildSkills(_context, _env) {
+        return [];
+    }
     /**
      * First-class event expansion stage (runs on every iteration of the durable loop).
      *
@@ -311,13 +328,14 @@ export class ContextEngine {
         return await ContextEngine.runDirect(this, triggerEvent, params);
     }
     static async prepareExecutionShell(story, triggerEvent, params) {
-        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.env, params.__benchmark));
+        const env = params.runtime.env;
+        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.runtime, params.__benchmark));
         const silent = params.options?.silent ?? false;
         const ctxResult = await measureBenchmark(params.__benchmark, "react.initializeContextMs", async () => await ops.initializeContext(params.context ?? null, { silent }));
         let currentContext = ctxResult.context;
         const contextSelector = { id: String(currentContext.id) };
         if (ctxResult.isNew) {
-            await story.opts.onContextCreated?.({ env: params.env, context: currentContext });
+            await story.opts.onContextCreated?.({ env, context: currentContext });
         }
         if (currentContext.status === "closed") {
             await measureBenchmark(params.__benchmark, "react.reopenClosedContextMs", async () => await ops.updateContextStatus(contextSelector, "open_idle"));
@@ -337,6 +355,7 @@ export class ContextEngine {
         };
     }
     static async startDurable(story, triggerEvent, params) {
+        const env = params.runtime.env;
         if (params.options?.writable) {
             throw new Error("ContextEngine.react: durable runs manage their own workflow stream");
         }
@@ -349,14 +368,15 @@ export class ContextEngine {
             throw new Error("ContextEngine.react: durable workflow is not configured. Call configureContextDurableWorkflow(...) in runtime bootstrap.");
         }
         const shell = await ContextEngine.prepareExecutionShell(story, triggerEvent, params);
+        let run;
         try {
             const [{ start }] = await Promise.all([
                 import("workflow/api"),
             ]);
-            const run = await start(workflow, [
+            const startedRun = await start(workflow, [
                 {
                     contextKey,
-                    env: params.env,
+                    runtime: params.runtime,
                     context: params.context ?? null,
                     triggerEvent,
                     options: {
@@ -374,16 +394,21 @@ export class ContextEngine {
                     },
                 },
             ]);
-            const runtime = await createRuntimeOps(params.env);
+            run = {
+                runId: String(startedRun.runId),
+                status: startedRun.status,
+                returnValue: startedRun.returnValue,
+            };
+            const runtime = await createRuntimeOps(params.runtime);
             await runtime.db.transact([
                 runtime.db.tx.event_executions[shell.execution.id].update({
-                    workflowRunId: run.runId,
+                    workflowRunId: startedRun.runId,
                     updatedAt: new Date(),
                 }),
             ]);
         }
         catch (error) {
-            const ops = await getContextEngineOps(params.env, params.__benchmark);
+            const ops = await getContextEngineOps(params.runtime, params.__benchmark);
             await ops.completeExecution(shell.contextSelector, shell.execution.id, "failed").catch(() => null);
             throw error;
         }
@@ -392,10 +417,12 @@ export class ContextEngine {
             trigger: shell.trigger,
             reaction: shell.reaction,
             execution: shell.execution,
+            run,
         };
     }
     static async runDirect(story, triggerEvent, params) {
-        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.env, params.__benchmark));
+        const env = params.runtime.env;
+        const ops = await measureBenchmark(params.__benchmark, "react.resolveOpsMs", async () => await getContextEngineOps(params.runtime, params.__benchmark));
         const maxIterations = params.options?.maxIterations ?? 20;
         const maxModelSteps = params.options?.maxModelSteps ?? 1;
         const preventClose = params.options?.preventClose ?? false;
@@ -422,6 +449,7 @@ export class ContextEngine {
         const executionId = execution.id;
         let updatedContext = { ...currentContext, status: "open_streaming" };
         let currentStepId = null;
+        let currentStepStream = null;
         const failExecution = async () => {
             try {
                 await ops.completeExecution(activeContextSelector, executionId, "failed");
@@ -468,6 +496,11 @@ export class ContextEngine {
                     iteration: iter,
                 }));
                 currentStepId = stepCreate.stepId;
+                currentStepStream = await createPersistedContextStepStream({
+                    runtime: params.runtime,
+                    executionId,
+                    stepId: stepCreate.stepId,
+                });
                 await emitContextEvents({
                     silent,
                     writable,
@@ -483,7 +516,7 @@ export class ContextEngine {
                     ],
                 });
                 // Hook: Context DSL `context()` (implemented by subclasses via `initialize()`)
-                const nextContent = await measureBenchmark(params.__benchmark, `${stagePrefix}.contextMs`, async () => await story.initialize(updatedContext, params.env));
+                const nextContent = await measureBenchmark(params.__benchmark, `${stagePrefix}.contextMs`, async () => await story.initialize(updatedContext, env));
                 updatedContext = await measureBenchmark(params.__benchmark, `${stagePrefix}.persistContextMs`, async () => await ops.updateContextContent(activeContextSelector, nextContent));
                 await emitContextEvents({
                     silent,
@@ -496,11 +529,12 @@ export class ContextEngine {
                         },
                     ],
                 });
-                await story.opts.onContextUpdated?.({ env: params.env, context: updatedContext });
+                await story.opts.onContextUpdated?.({ env, context: updatedContext });
                 // Hook: Context DSL `narrative()` (implemented by subclasses via `buildSystemPrompt()`)
-                const systemPrompt = await measureBenchmark(params.__benchmark, `${stagePrefix}.narrativeMs`, async () => await story.buildSystemPrompt(updatedContext, params.env));
+                const systemPrompt = await measureBenchmark(params.__benchmark, `${stagePrefix}.narrativeMs`, async () => await story.buildSystemPrompt(updatedContext, env));
                 // Hook: Context DSL `actions()` (implemented by subclasses via `buildTools()`)
-                const toolsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.actionsMs`, async () => await story.buildTools(updatedContext, params.env));
+                const toolsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.actionsMs`, async () => await story.buildTools(updatedContext, env));
+                const skillsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.skillsMs`, async () => await story.buildSkills(updatedContext, env));
                 // IMPORTANT: step args must be serializable.
                 // Match DurableAgent behavior: convert tool input schemas to plain JSON Schema in workflow context.
                 const toolsForModel = toolsToModelTools(toolsAll);
@@ -511,13 +545,13 @@ export class ContextEngine {
                 // If we stream with a per-step id, the UI will render an optimistic assistant message
                 // (step id) and then a second persisted assistant message (reaction id) with the same
                 // content once InstantDB updates.
-                const reactor = story.getReactor(updatedContext, params.env);
+                const reactor = story.getReactor(updatedContext, env);
                 const reactionPartsBeforeStep = Array.isArray(reactionEvent.content?.parts)
                     ? [...reactionEvent.content.parts]
                     : [];
                 let persistedReactionPartsSignature = "";
                 const persistReactionParts = async (nextParts) => {
-                    const normalizedParts = Array.isArray(nextParts) ? nextParts : [];
+                    const normalizedParts = normalizePartsForPersistence(Array.isArray(nextParts) ? nextParts : []);
                     const nextSignature = JSON.stringify(normalizedParts);
                     if (nextSignature === persistedReactionPartsSignature)
                         return;
@@ -539,14 +573,16 @@ export class ContextEngine {
                     }, { executionId, contextId: String(currentContext.id) });
                 };
                 const { assistantEvent, actionRequests, messagesForModel } = await measureBenchmark(params.__benchmark, `${stagePrefix}.reactorMs`, async () => await reactor({
-                    env: params.env,
+                    runtime: params.runtime,
+                    env,
                     context: updatedContext,
                     contextIdentifier: activeContextSelector,
                     triggerEvent,
-                    model: story.getModel(updatedContext, params.env),
+                    model: story.getModel(updatedContext, env),
                     systemPrompt,
                     actions: toolsAll,
                     toolsForModel,
+                    skills: skillsAll,
                     eventId: reactionEventId,
                     executionId,
                     contextId: String(currentContext.id),
@@ -556,6 +592,7 @@ export class ContextEngine {
                     // Only emit a `start` chunk once per story turn.
                     sendStart: !silent && iter === 0,
                     silent,
+                    contextStepStream: currentStepStream?.stream,
                     writable,
                     persistReactionParts,
                 }));
@@ -579,7 +616,7 @@ export class ContextEngine {
                 // We intentionally do NOT persist the per-step LLM assistant event as a `context_event`.
                 // The story exposes a single visible `context_event` per turn (`reactionEventId`) so the UI
                 // doesn't render duplicate assistant messages (LLM-step + aggregated reaction).
-                const stepParts = (assistantEvent?.content?.parts ?? []);
+                const stepParts = normalizePartsForPersistence((assistantEvent?.content?.parts ?? []));
                 const assistantEventEffective = {
                     ...assistantEvent,
                     content: {
@@ -622,6 +659,13 @@ export class ContextEngine {
                     status: "pending",
                 };
                 reactionEvent = await measureBenchmark(params.__benchmark, `${stagePrefix}.persistAssistantReactionMs`, async () => await ops.updateItem(reactionEvent.id, nextReactionEvent, { executionId, contextId: String(currentContext.id) }));
+                if (currentStepStream) {
+                    await closePersistedContextStepStream({
+                        runtime: params.runtime,
+                        session: currentStepStream,
+                    });
+                    currentStepStream = null;
+                }
                 story.opts.onEventCreated?.(assistantEventEffective);
                 const firstActionRequest = actionRequests?.[0];
                 await measureBenchmark(params.__benchmark, `${stagePrefix}.markStepRunningMs`, async () => await ops.updateContextStep({
@@ -798,12 +842,18 @@ export class ContextEngine {
                             }
                         }
                         const output = await toolDef.execute(actionInput, {
+                            runtime: params.runtime,
+                            env,
+                            context: updatedContext,
+                            contextIdentifier: activeContextSelector,
                             toolCallId: actionRequest.actionRef,
                             messages: messagesForModel,
                             eventId: reactionEventId,
                             executionId,
                             triggerEventId,
                             contextId: currentContext.id,
+                            stepId: String(stepCreate.stepId),
+                            iteration: iter,
                         });
                         return { actionRequest, success: true, output };
                     }
@@ -817,11 +867,9 @@ export class ContextEngine {
                     }
                 })));
                 // Merge action results into persisted parts (so next LLM call can see them)
-                let parts = Array.isArray(reactionEvent.content?.parts)
-                    ? [...reactionEvent.content.parts]
-                    : [];
+                let finalizedStepParts = Array.isArray(stepParts) ? [...stepParts] : [];
                 for (const r of actionResults) {
-                    parts = applyToolExecutionResultToParts(parts, {
+                    finalizedStepParts = applyToolExecutionResultToParts(finalizedStepParts, {
                         toolCallId: r.actionRequest.actionRef,
                         toolName: r.actionRequest.actionName,
                     }, {
@@ -830,11 +878,20 @@ export class ContextEngine {
                         message: r.errorText,
                     });
                 }
+                await measureBenchmark(params.__benchmark, `${stagePrefix}.saveFinalStepPartsMs`, async () => await ops.saveContextPartsStep({
+                    stepId: stepCreate.stepId,
+                    parts: finalizedStepParts,
+                    executionId,
+                    contextId: String(currentContext.id),
+                    iteration: iter,
+                }));
                 reactionEvent = {
                     ...reactionEvent,
                     content: {
                         ...reactionEvent.content,
-                        parts,
+                        // Deprecated mirror for compatibility. `event_parts` are the
+                        // source of truth for replay and step inspection.
+                        parts: [...reactionPartsBeforeStep, ...finalizedStepParts],
                     },
                     status: "pending",
                 };
@@ -853,7 +910,7 @@ export class ContextEngine {
                 // IMPORTANT: we call this after tool results have been merged into the persisted `reactionEvent`,
                 // so stories can inspect `reactionEvent.content.parts` deterministically.
                 const continueLoop = await measureBenchmark(params.__benchmark, `${stagePrefix}.shouldContinueMs`, async () => await story.shouldContinue({
-                    env: params.env,
+                    env,
                     context: updatedContext,
                     reactionEvent,
                     assistantEvent: assistantEventEffective,
@@ -989,6 +1046,21 @@ export class ContextEngine {
             throw new Error(`ContextEngine: maxIterations reached (${maxIterations}) without completion`);
         }
         catch (error) {
+            if (currentStepStream) {
+                try {
+                    await abortPersistedContextStepStream({
+                        runtime: params.runtime,
+                        session: currentStepStream,
+                        reason: error instanceof Error ? error.message : String(error),
+                    });
+                }
+                catch {
+                    // noop
+                }
+                finally {
+                    currentStepStream = null;
+                }
+            }
             // Best-effort: persist failure on the current iteration step (if any)
             if (currentStepId) {
                 const failedStepId = currentStepId;

package/dist/context.events.d.ts

@@ -6,6 +6,26 @@ export declare const INPUT_TEXT_ITEM_TYPE = "input";
 export declare const WEB_CHANNEL = "web";
 export declare const AGENT_CHANNEL = "whatsapp";
 export declare const EMAIL_CHANNEL = "email";
+export type ContextOutputContentPart = {
+    type: "text";
+    text: string;
+} | ({
+    type: "image-data";
+    data: string;
+    mediaType: string;
+    filename?: string;
+} & Record<string, unknown>) | ({
+    type: string;
+} & Record<string, unknown>);
+export type ContextOutputPart = {
+    type: "json";
+    value: unknown;
+} | {
+    type: "content";
+    value: ContextOutputContentPart[];
+};
+export declare function isContextOutputPart(value: unknown): value is ContextOutputPart;
+export declare function normalizeContextOutputPart(value: unknown): ContextOutputPart;
 export declare function createUserItemFromUIMessages(messages: UIMessage[]): ContextItem;
 export declare function createAssistantItemFromUIMessages(itemId: string, messages: UIMessage[]): ContextItem;
 export declare function convertToUIMessage(item: ContextItem): UIMessage;