@ekairos/events 1.22.30-beta.development.0 → 1.22.31-beta.development.0

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 { 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,7 @@
 import type { Tool, UIMessageChunk } from "ai";
 import type { ContextEnvironment } from "./context.config.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> {
@@ -168,6 +169,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

@@ -3,7 +3,7 @@ import { OUTPUT_ITEM_TYPE, WEB_CHANNEL } from "./context.events.js";
 import { applyToolExecutionResultToParts } from "./context.toolcalls.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";
@@ -267,6 +267,9 @@ export class ContextEngine {
         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).
      *
@@ -422,6 +425,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 +472,11 @@ export class ContextEngine {
                     iteration: iter,
                 }));
                 currentStepId = stepCreate.stepId;
+                currentStepStream = await createPersistedContextStepStream({
+                    env: params.env,
+                    executionId,
+                    stepId: stepCreate.stepId,
+                });
                 await emitContextEvents({
                     silent,
                     writable,
@@ -501,6 +510,7 @@ export class ContextEngine {
                 const systemPrompt = await measureBenchmark(params.__benchmark, `${stagePrefix}.narrativeMs`, async () => await story.buildSystemPrompt(updatedContext, params.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 skillsAll = await measureBenchmark(params.__benchmark, `${stagePrefix}.skillsMs`, async () => await story.buildSkills(updatedContext, params.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);
@@ -547,6 +557,7 @@ export class ContextEngine {
                     systemPrompt,
                     actions: toolsAll,
                     toolsForModel,
+                    skills: skillsAll,
                     eventId: reactionEventId,
                     executionId,
                     contextId: String(currentContext.id),
@@ -556,6 +567,7 @@ export class ContextEngine {
                     // Only emit a `start` chunk once per story turn.
                     sendStart: !silent && iter === 0,
                     silent,
+                    contextStepStream: currentStepStream?.stream,
                     writable,
                     persistReactionParts,
                 }));
@@ -622,6 +634,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({
+                        env: params.env,
+                        session: currentStepStream,
+                    });
+                    currentStepStream = null;
+                }
                 story.opts.onEventCreated?.(assistantEventEffective);
                 const firstActionRequest = actionRequests?.[0];
                 await measureBenchmark(params.__benchmark, `${stagePrefix}.markStepRunningMs`, async () => await ops.updateContextStep({
@@ -989,6 +1008,21 @@ export class ContextEngine {
             throw new Error(`ContextEngine: maxIterations reached (${maxIterations}) without completion`);
         }
         catch (error) {
+            if (currentStepStream) {
+                try {
+                    await abortPersistedContextStepStream({
+                        env: params.env,
+                        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.skill.d.ts

@@ -0,0 +1,9 @@
+export type ContextSkillPackageFile = {
+    path: string;
+    contentBase64: string;
+};
+export type ContextSkillPackage = {
+    name: string;
+    description?: string;
+    files: ContextSkillPackageFile[];
+};

package/dist/context.skill.js

@@ -0,0 +1 @@
+export {};

package/dist/context.step-stream.d.ts

@@ -0,0 +1,26 @@
+import { type ContextStreamChunkType } from "./context.contract.js";
+export declare const CONTEXT_STEP_STREAM_VERSION: 1;
+export type ContextStepStreamChunk = {
+    version: typeof CONTEXT_STEP_STREAM_VERSION;
+    at: string;
+    sequence: number;
+    chunkType: ContextStreamChunkType;
+    provider?: string;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+};
+export declare function createContextStepStreamChunk(params: {
+    at?: string;
+    sequence: number;
+    chunkType: ContextStreamChunkType;
+    provider?: string;
+    providerChunkType?: string;
+    actionRef?: string;
+    data?: unknown;
+    raw?: unknown;
+}): ContextStepStreamChunk;
+export declare function parseContextStepStreamChunk(value: string | unknown): ContextStepStreamChunk;
+export declare function encodeContextStepStreamChunk(chunk: ContextStepStreamChunk): string;
+export declare function contextStreamByteLength(value: string): number;

package/dist/context.step-stream.js

@@ -0,0 +1,59 @@
+import { isContextStreamChunkType, } from "./context.contract.js";
+export const CONTEXT_STEP_STREAM_VERSION = 1;
+function assertObject(value, label) {
+    if (!value || typeof value !== "object") {
+        throw new Error(`Invalid ${label}: expected object.`);
+    }
+}
+function assertString(value, label) {
+    if (typeof value !== "string" || value.length === 0) {
+        throw new Error(`Invalid ${label}: expected non-empty string.`);
+    }
+}
+function assertNumber(value, label) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        throw new Error(`Invalid ${label}: expected number.`);
+    }
+}
+function assertOptionalString(value, label) {
+    if (typeof value === "undefined")
+        return;
+    assertString(value, label);
+}
+export function createContextStepStreamChunk(params) {
+    return {
+        version: CONTEXT_STEP_STREAM_VERSION,
+        at: params.at ?? new Date().toISOString(),
+        sequence: params.sequence,
+        chunkType: params.chunkType,
+        provider: params.provider,
+        providerChunkType: params.providerChunkType,
+        actionRef: params.actionRef,
+        data: params.data,
+        raw: params.raw,
+    };
+}
+export function parseContextStepStreamChunk(value) {
+    const parsed = typeof value === "string" ? JSON.parse(value) : value;
+    assertObject(parsed, "context step stream chunk");
+    assertNumber(parsed.version, "context step stream chunk.version");
+    if (parsed.version !== CONTEXT_STEP_STREAM_VERSION) {
+        throw new Error(`Unsupported context step stream chunk version: ${String(parsed.version)}`);
+    }
+    assertString(parsed.at, "context step stream chunk.at");
+    assertNumber(parsed.sequence, "context step stream chunk.sequence");
+    assertString(parsed.chunkType, "context step stream chunk.chunkType");
+    if (!isContextStreamChunkType(parsed.chunkType)) {
+        throw new Error(`Invalid context step stream chunk.chunkType: ${String(parsed.chunkType)}`);
+    }
+    assertOptionalString(parsed.provider, "context step stream chunk.provider");
+    assertOptionalString(parsed.providerChunkType, "context step stream chunk.providerChunkType");
+    assertOptionalString(parsed.actionRef, "context step stream chunk.actionRef");
+    return parsed;
+}
+export function encodeContextStepStreamChunk(chunk) {
+    return `${JSON.stringify(chunk)}\n`;
+}
+export function contextStreamByteLength(value) {
+    return new TextEncoder().encode(value).length;
+}

package/dist/index.d.ts

@@ -10,4 +10,7 @@ export type { Transition, ContextStatus, ExecutionStatus, StepStatus, StepKind,
 export { DEFAULT_CODEX_TOOL_NAME, DEFAULT_CODEX_MODEL, codexToolInputSchema, buildDefaultCodexNarrative, didCodexToolExecute, createCodexContextBuilder, type CodexContextRuntimeMode, type CodexContextReasoningLevel, type CodexContextRuntime, type CodexContextEnv, type CodexToolInput, type CodexToolOutput, type CodexExecuteArgs, type CodexContextBuilderConfig, type CodexContextBuilder, } from "./codex.js";
 export { useContext, type ContextSnapshot, type ContextStreamChunk, type UseContextOptions, } from "./react.js";
 export { parseContextStreamEvent, assertContextStreamTransitions, validateContextStreamTimeline, } from "./context.stream.js";
+export { CONTEXT_STEP_STREAM_VERSION, createContextStepStreamChunk, parseContextStepStreamChunk, encodeContextStepStreamChunk, } from "./context.step-stream.js";
 export type { ContextStreamEvent, ContextCreatedEvent, ContextResolvedEvent, ContextStatusChangedEvent, ContextContentUpdatedEvent, ExecutionCreatedEvent, ExecutionCompletedEvent, ExecutionFailedEvent, ItemCreatedEvent, ItemUpdatedEvent, ItemPendingEvent, ItemCompletedEvent, StepCreatedEvent, StepUpdatedEvent, StepCompletedEvent, StepFailedEvent, PartCreatedEvent, PartUpdatedEvent, ChunkEmittedEvent, } from "./context.stream.js";
+export type { ContextStepStreamChunk } from "./context.step-stream.js";
+export type { ContextSkillPackage, ContextSkillPackageFile } from "./context.skill.js";

package/dist/index.js

@@ -7,3 +7,4 @@ export { CONTEXT_STATUSES, EXECUTION_STATUSES, STEP_STATUSES, STEP_KINDS, ITEM_S
 export { DEFAULT_CODEX_TOOL_NAME, DEFAULT_CODEX_MODEL, codexToolInputSchema, buildDefaultCodexNarrative, didCodexToolExecute, createCodexContextBuilder, } from "./codex.js";
 export { useContext, } from "./react.js";
 export { parseContextStreamEvent, assertContextStreamTransitions, validateContextStreamTimeline, } from "./context.stream.js";
+export { CONTEXT_STEP_STREAM_VERSION, createContextStepStreamChunk, parseContextStepStreamChunk, encodeContextStepStreamChunk, } from "./context.step-stream.js";

package/dist/reactors/ai-sdk.reactor.js

@@ -1,4 +1,4 @@
-import { executeReaction } from "../steps/reaction.steps.js";
+import { executeAiSdkReaction } from "./ai-sdk.step.js";
 export function createAiSdkReactor(options) {
     return async (params) => {
         let config;
@@ -34,7 +34,7 @@ export function createAiSdkReactor(options) {
                 config,
             })
             : params.maxModelSteps;
-        const result = await executeReaction({
+        const result = await executeAiSdkReaction({
             env: params.env,
             contextIdentifier: params.contextIdentifier,
             model,
@@ -45,6 +45,7 @@ export function createAiSdkReactor(options) {
             maxSteps,
             sendStart: params.sendStart,
             silent: params.silent,
+            contextStepStream: params.contextStepStream,
             writable: params.writable,
             executionId: params.executionId,
             contextId: params.contextId,

package/dist/{steps/reaction.steps.d.ts → reactors/ai-sdk.step.d.ts}

@@ -4,13 +4,16 @@ import type { ContextModelInit } from "../context.engine.js";
 import type { ContextItem, ContextIdentifier } from "../context.store.js";
 import type { SerializableToolForModel } from "../tools-to-model-tools.js";
 /**
- * Executes a full "reaction" inside a single workflow step:
- * - load events from store
- * - convert events to model messages
- * - run the streaming model call and emit chunks
- * - extract tool calls from the resulting assistant event
+ * AI SDK-backed reaction execution inside a single workflow step.
+ *
+ * Provider-specific responsibilities live here:
+ * - load items from store
+ * - build model messages
+ * - stream through the AI SDK
+ * - map provider chunks to the Context stream contract
+ * - emit UI chunks and persist step stream chunks
  */
-export declare function executeReaction(params: {
+export declare function executeAiSdkReaction(params: {
     env: ContextEnvironment;
     contextIdentifier: ContextIdentifier;
     model: ContextModelInit;
@@ -21,6 +24,7 @@ export declare function executeReaction(params: {
     maxSteps: number;
     sendStart?: boolean;
     silent?: boolean;
+    contextStepStream?: WritableStream<string>;
     writable?: WritableStream<UIMessageChunk>;
     executionId?: string;
     contextId?: string;

package/dist/{steps/reaction.steps.js → reactors/ai-sdk.step.js}

@@ -1,6 +1,7 @@
 import { OUTPUT_ITEM_TYPE } from "../context.events.js";
-import { mapAiSdkChunkToContextEvent } from "../reactors/ai-sdk.chunk-map.js";
-import { writeContextTraceEvents } from "./trace.steps.js";
+import { createContextStepStreamChunk, encodeContextStepStreamChunk, } from "../context.step-stream.js";
+import { mapAiSdkChunkToContextEvent } from "./ai-sdk.chunk-map.js";
+import { writeContextTraceEvents } from "../steps/trace.steps.js";
 async function readWorkflowMetadata() {
     try {
         const { getWorkflowMetadata } = await import("workflow");
@@ -70,13 +71,16 @@ function safeErrorJson(error) {
     }
 }
 /**
- * Executes a full "reaction" inside a single workflow step:
- * - load events from store
- * - convert events to model messages
- * - run the streaming model call and emit chunks
- * - extract tool calls from the resulting assistant event
+ * AI SDK-backed reaction execution inside a single workflow step.
+ *
+ * Provider-specific responsibilities live here:
+ * - load items from store
+ * - build model messages
+ * - stream through the AI SDK
+ * - map provider chunks to the Context stream contract
+ * - emit UI chunks and persist step stream chunks
  */
-export async function executeReaction(params) {
+export async function executeAiSdkReaction(params) {
     "use step";
     const { getContextRuntime } = await import("../runtime.js");
     const { store } = await getContextRuntime(params.env);
@@ -85,7 +89,7 @@ export async function executeReaction(params) {
         events = await store.getItems(params.contextIdentifier);
     }
     catch (error) {
-        console.error("[ekairos/story] reaction.step store.getItems failed");
+        console.error("[ekairos/story] ai-sdk.step store.getItems failed");
         throw error;
     }
     let messagesForModel;
@@ -93,20 +97,18 @@ export async function executeReaction(params) {
         messagesForModel = (await store.itemsToModelMessages(events));
     }
     catch (error) {
-        console.error("[ekairos/story] reaction.step store.itemsToModelMessages failed", safeErrorJson(error));
+        console.error("[ekairos/story] ai-sdk.step store.itemsToModelMessages failed", safeErrorJson(error));
         throw error;
     }
     const { jsonSchema, gateway, smoothStream, stepCountIs, streamText } = await import("ai");
     const { extractToolCallsFromParts } = await import("../context.toolcalls.js");
-    // Match DurableAgent-style model init behavior:
     const resolvedModel = typeof params.model === "string"
         ? gateway(params.model)
         : typeof params.model === "function"
             ? await params.model()
             : (() => {
-                throw new Error("Invalid model init passed to executeReaction. Expected a model id string or an async model factory.");
+                throw new Error("Invalid model init passed to executeAiSdkReaction. Expected a model id string or an async model factory.");
             })();
-    // Wrap plain JSON Schema objects so the AI SDK doesn't attempt Zod conversion at runtime.
     const toolsForStreamText = {};
     for (const [name, t] of Object.entries(params.tools)) {
         toolsForStreamText[name] = {
@@ -124,7 +126,6 @@ export async function executeReaction(params) {
         stopWhen: stepCountIs(params.maxSteps),
         experimental_transform: smoothStream({ delayInMs: 30, chunking: "word" }),
     });
-    // Ensure the underlying stream is consumed (AI SDK requirement)
     result.consumeStream();
     let resolveFinish;
     let rejectFinish;
@@ -135,76 +136,96 @@ export async function executeReaction(params) {
     });
     const modelId = typeof params.model === "string" ? params.model : "";
     const mappedProvider = modelId.includes("/") ? modelId.split("/")[0] : undefined;
-    const uiStream = result
-        .toUIMessageStream({
-        sendStart: Boolean(params.sendStart),
-        generateMessageId: () => params.eventId,
-        messageMetadata() {
-            return { eventId: params.eventId };
-        },
-        onFinish: ({ messages }) => {
-            const lastMessage = messages[messages.length - 1];
-            const event = {
-                id: params.eventId,
-                type: OUTPUT_ITEM_TYPE,
-                channel: "web",
-                createdAt: new Date().toISOString(),
-                content: { parts: lastMessage?.parts ?? [] },
-            };
-            resolveFinish(event);
-        },
-        onError: (e) => {
-            rejectFinish(e);
-            return e instanceof Error ? e.message : String(e);
-        },
-    })
-        // Filter out per-step finish boundary. Workflow will emit a single finish.
-        .pipeThrough(new TransformStream({
-        transform(chunk, controller) {
-            const contextId = typeof params.contextId === "string" && params.contextId.length > 0
-                ? params.contextId
-                : undefined;
-            if (contextId) {
-                const mapped = mapAiSdkChunkToContextEvent({
-                    chunk,
-                    contextId,
-                    executionId: params.executionId,
-                    stepId: params.stepId,
-                    itemId: params.eventId,
-                    provider: mappedProvider,
-                    sequence: ++chunkSequence,
-                });
-                controller.enqueue({
-                    type: "data-chunk.emitted",
-                    data: mapped,
-                });
+    const contextStepStreamWriter = params.contextStepStream?.getWriter();
+    try {
+        const uiStream = result
+            .toUIMessageStream({
+            sendStart: Boolean(params.sendStart),
+            generateMessageId: () => params.eventId,
+            messageMetadata() {
+                return { eventId: params.eventId };
+            },
+            onFinish: ({ messages }) => {
+                const lastMessage = messages[messages.length - 1];
+                const event = {
+                    id: params.eventId,
+                    type: OUTPUT_ITEM_TYPE,
+                    channel: "web",
+                    createdAt: new Date().toISOString(),
+                    content: { parts: lastMessage?.parts ?? [] },
+                };
+                resolveFinish(event);
+            },
+            onError: (e) => {
+                rejectFinish(e);
+                return e instanceof Error ? e.message : String(e);
+            },
+        })
+            .pipeThrough(new TransformStream({
+            async transform(chunk, controller) {
+                const contextId = typeof params.contextId === "string" && params.contextId.length > 0
+                    ? params.contextId
+                    : undefined;
+                if (contextId) {
+                    const mapped = mapAiSdkChunkToContextEvent({
+                        chunk,
+                        contextId,
+                        executionId: params.executionId,
+                        stepId: params.stepId,
+                        itemId: params.eventId,
+                        provider: mappedProvider,
+                        sequence: ++chunkSequence,
+                    });
+                    const persistedChunk = createContextStepStreamChunk({
+                        at: mapped.at,
+                        sequence: mapped.sequence,
+                        chunkType: mapped.chunkType,
+                        provider: mapped.provider,
+                        providerChunkType: mapped.providerChunkType,
+                        actionRef: mapped.actionRef,
+                        data: mapped.data && typeof mapped.data === "object"
+                            ? mapped.data
+                            : undefined,
+                        raw: mapped.raw && typeof mapped.raw === "object"
+                            ? mapped.raw
+                            : undefined,
+                    });
+                    if (contextStepStreamWriter) {
+                        await contextStepStreamWriter.write(encodeContextStepStreamChunk(persistedChunk));
+                    }
+                    controller.enqueue({
+                        type: "data-chunk.emitted",
+                        data: mapped,
+                    });
+                }
+                if (chunk.type === "finish")
+                    return;
+                controller.enqueue(chunk);
+            },
+        }));
+        if (params.writable) {
+            await uiStream.pipeTo(params.writable, { preventClose: true });
+        }
+        else {
+            const reader = uiStream.getReader();
+            try {
+                while (true) {
+                    const { done } = await reader.read();
+                    if (done)
+                        break;
+                }
             }
-            if (chunk.type === "finish")
-                return;
-            controller.enqueue(chunk);
-        },
-    }));
-    if (params.writable) {
-        await uiStream.pipeTo(params.writable, { preventClose: true });
-    }
-    else {
-        const reader = uiStream.getReader();
-        try {
-            while (true) {
-                const { done } = await reader.read();
-                if (done)
-                    break;
+            finally {
+                reader.releaseLock();
             }
         }
-        finally {
-            reader.releaseLock();
-        }
+    }
+    finally {
+        contextStepStreamWriter?.releaseLock();
     }
     const assistantEvent = await finishPromise;
     const finishedAtMs = Date.now();
     const toolCalls = extractToolCallsFromParts(assistantEvent?.content?.parts);
-    // Best-effort usage extraction (AI SDK provider dependent).
-    // We keep this loose because providers differ and SDK evolves quickly.
     const latencyMs = Math.max(0, finishedAtMs - startedAtMs);
     let usage = undefined;
     let providerMetadata = undefined;
@@ -226,8 +247,6 @@ export async function executeReaction(params) {
     catch {
         providerMetadata = undefined;
     }
-    // Workflow steps must return serializable values. Provider SDKs may include
-    // classes/streams/etc in metadata, so we defensively sanitize.
     function toPlainJson(value) {
         if (typeof value === "undefined")
             return undefined;
@@ -240,10 +259,8 @@ export async function executeReaction(params) {
     }
     const usageJson = toPlainJson(usage);
     const providerMetadataJson = toPlainJson(providerMetadata);
-    // Derive provider/model from gateway id when available.
     const provider = modelId.includes("/") ? modelId.split("/")[0] : providerMetadata?.provider;
     const model = modelId.includes("/") ? modelId.split("/").slice(1).join("/") : providerMetadata?.model;
-    // Token accounting: attempt to read cached prompt tokens from OpenAI-like usage shapes.
     const promptTokens = Number(usage?.promptTokens ?? usage?.prompt_tokens ?? usage?.inputTokens ?? 0) || 0;
     const completionTokens = Number(usage?.completionTokens ?? usage?.completion_tokens ?? usage?.outputTokens ?? 0) || 0;
     const totalTokens = Number(usage?.totalTokens ?? usage?.total_tokens ?? 0) || (promptTokens + completionTokens);

package/dist/reactors/types.d.ts

@@ -2,6 +2,7 @@ import type { ModelMessage, UIMessageChunk } from "ai";
 import type { ContextEnvironment } from "../context.config.js";
 import type { ContextModelInit } from "../context.engine.js";
 import type { ContextIdentifier, StoredContext, ContextItem } from "../context.store.js";
+import type { ContextSkillPackage } from "../context.skill.js";
 import type { SerializableToolForModel } from "../tools-to-model-tools.js";
 export type ContextActionRequest = {
     actionRef: string;
@@ -35,6 +36,7 @@ export type ContextReactorParams<Context = unknown, Env extends ContextEnvironme
     systemPrompt: string;
     actions: Record<string, unknown>;
     toolsForModel: Record<string, SerializableToolForModel>;
+    skills: ContextSkillPackage[];
     eventId: string;
     executionId: string;
     contextId: string;
@@ -43,6 +45,7 @@ export type ContextReactorParams<Context = unknown, Env extends ContextEnvironme
     maxModelSteps: number;
     sendStart: boolean;
     silent: boolean;
+    contextStepStream?: WritableStream<string>;
     writable?: WritableStream<UIMessageChunk>;
     persistReactionParts?: (parts: any[]) => Promise<void>;
 };

package/dist/runtime.d.ts

@@ -9,6 +9,7 @@
  * - Keep `@ekairos/events` main entrypoint safe to import from schema/domain modules.
  */
 export { getContextRuntime, } from "./runtime.step.js";
+export { createContextStepStreamClientId, createPersistedContextStepStream, readPersistedContextStepStream, resolveContextExecutionStreamPointer, waitForContextExecutionStreamPointer, } from "./steps/stream.steps.js";
 export type { ContextEnvironment, ContextRuntime } from "./context.config.js";
 export { registerContextEnv, getContextEnv } from "./env.js";
 export { configureContextDurableWorkflow } from "./context.durable.js";

package/dist/runtime.js

@@ -21,5 +21,6 @@ if (typeof globalThis.Event === "undefined") {
     globalThis.Event = NodeEvent;
 }
 export { getContextRuntime, } from "./runtime.step.js";
+export { createContextStepStreamClientId, createPersistedContextStepStream, readPersistedContextStepStream, resolveContextExecutionStreamPointer, waitForContextExecutionStreamPointer, } from "./steps/stream.steps.js";
 export { registerContextEnv, getContextEnv } from "./env.js";
 export { configureContextDurableWorkflow } from "./context.durable.js";

package/dist/runtime.step.js

@@ -1,7 +1,7 @@
 import { coerceContextRuntime } from "./context.config.js";
 import { eventsDomain } from "./schema.js";
 export async function getContextRuntime(env) {
-    const { resolveRuntime } = await import("@ekairos/domain/runtime");
+    const { resolveRuntime } = await import("@ekairos/domain/runtime-step");
     const resolved = await resolveRuntime(eventsDomain, env);
     return await coerceContextRuntime(resolved);
 }

package/dist/schema.js

@@ -23,6 +23,10 @@ export const eventsDomain = domain("events")
             updatedAt: i.date().optional(),
             status: i.string().optional().indexed(), // executing | completed | failed
             workflowRunId: i.string().optional().indexed(),
+            activeStreamId: i.string().optional().indexed(),
+            activeStreamClientId: i.string().optional().indexed(),
+            lastStreamId: i.string().optional().indexed(),
+            lastStreamClientId: i.string().optional().indexed(),
         }),
         event_steps: i.entity({
             createdAt: i.date().indexed(),
@@ -38,6 +42,11 @@ export const eventsDomain = domain("events")
             actionResults: i.any().optional(),
             continueLoop: i.boolean().optional(),
             errorText: i.string().optional(),
+            streamId: i.string().optional().indexed(),
+            streamClientId: i.string().optional().indexed(),
+            streamStartedAt: i.date().optional().indexed(),
+            streamFinishedAt: i.date().optional().indexed(),
+            streamAbortReason: i.string().optional(),
         }),
         event_parts: i.entity({
             key: i.string().unique().indexed(), // `${stepId}:${idx}`
@@ -152,6 +161,18 @@ export const eventsDomain = domain("events")
             forward: { on: "event_parts", has: "one", label: "step" },
             reverse: { on: "event_steps", has: "many", label: "parts" },
         },
+        contextStepStream: {
+            forward: { on: "event_steps", has: "one", label: "stream" },
+            reverse: { on: "$streams", has: "many", label: "step" },
+        },
+        contextExecutionActiveStream: {
+            forward: { on: "event_executions", has: "one", label: "activeStream" },
+            reverse: { on: "$streams", has: "many", label: "activeOf" },
+        },
+        contextExecutionLastStream: {
+            forward: { on: "event_executions", has: "one", label: "lastStream" },
+            reverse: { on: "$streams", has: "many", label: "lastOf" },
+        },
         documentFile: {
             forward: {
                 on: "document_documents",

package/dist/steps/stream.steps.d.ts

@@ -1,4 +1,6 @@
 import type { UIMessageChunk } from "ai";
+import type { ContextEnvironment } from "../context.config.js";
+import { type ContextStepStreamChunk } from "../context.step-stream.js";
 import type { ContextStreamEvent } from "../context.stream.js";
 export declare function writeContextEvents(params: {
     events: ContextStreamEvent[];
@@ -9,3 +11,76 @@ export declare function closeContextStream(params: {
     sendFinish?: boolean;
     writable?: WritableStream<UIMessageChunk>;
 }): Promise<void>;
+export declare function createContextStepStreamClientId(stepId: string): string;
+export type PersistedContextStepStreamSession = {
+    stream: WritableStream<string>;
+    streamId: string;
+    clientId: string;
+    executionId: string;
+    stepId: string;
+};
+export declare function createPersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    executionId: string;
+    stepId: string;
+    clientId?: string;
+}): Promise<PersistedContextStepStreamSession>;
+export declare function closePersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    session: PersistedContextStepStreamSession;
+}): Promise<void>;
+export declare function abortPersistedContextStepStream(params: {
+    env: ContextEnvironment;
+    session: PersistedContextStepStreamSession;
+    reason?: string | null;
+}): Promise<void>;
+export declare function readPersistedContextStepStream(params: {
+    db: any;
+    clientId?: string;
+    streamId?: string;
+    byteOffset?: number;
+    onChunk?: (chunk: ContextStepStreamChunk) => Promise<void> | void;
+}): Promise<{
+    chunks: ContextStepStreamChunk[];
+    byteOffset: number;
+}>;
+export declare function resolveContextExecutionStreamPointer(params: {
+    db: any;
+    contextId: string;
+}): Promise<{
+    executionId: string;
+    status: string | null;
+    source: "active";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "last";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "none";
+    clientId: null;
+    streamId: null;
+} | null>;
+export declare function waitForContextExecutionStreamPointer(params: {
+    db: any;
+    contextId: string;
+    timeoutMs?: number;
+    pollMs?: number;
+}): Promise<{
+    executionId: string;
+    status: string | null;
+    source: "active";
+    clientId: string | null;
+    streamId: string | null;
+} | {
+    executionId: string;
+    status: string | null;
+    source: "last";
+    clientId: string | null;
+    streamId: string | null;
+} | null>;

package/dist/steps/stream.steps.js

@@ -1,3 +1,4 @@
+import { contextStreamByteLength, parseContextStepStreamChunk, } from "../context.step-stream.js";
 export async function writeContextEvents(params) {
     "use step";
     const writable = params.writable;
@@ -36,3 +37,244 @@ export async function closeContextStream(params) {
         await writable.close();
     }
 }
+function readWaitUntil(env) {
+    const candidate = typeof env?.waitUntil === "function"
+        ? env.waitUntil
+        : typeof env?.after === "function"
+            ? env.after
+            : undefined;
+    return typeof candidate === "function" ? candidate : undefined;
+}
+function asRecord(value) {
+    return value && typeof value === "object" ? value : {};
+}
+function asString(value) {
+    return typeof value === "string" ? value.trim() : "";
+}
+function createUnsetStreamLinkTx(db, executionId, label, streamId) {
+    try {
+        return db.tx.event_executions[executionId].unlink({ [label]: streamId });
+    }
+    catch {
+        return null;
+    }
+}
+export function createContextStepStreamClientId(stepId) {
+    const normalized = String(stepId ?? "").trim();
+    if (!normalized) {
+        throw new Error("createContextStepStreamClientId: stepId is required.");
+    }
+    return `event-step:${normalized}`;
+}
+export async function createPersistedContextStepStream(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const db = runtime?.db;
+    if (!db?.streams?.createWriteStream) {
+        throw new Error("InstantDB streams are not available on the configured runtime. Upgrade @instantdb/admin to a streams-capable version.");
+    }
+    const clientId = asString(params.clientId) || createContextStepStreamClientId(params.stepId);
+    const startedAt = new Date();
+    const waitUntil = readWaitUntil(params.env);
+    const writeStream = db.streams.createWriteStream({
+        clientId,
+        waitUntil,
+    });
+    const streamId = await writeStream.streamId();
+    await db.transact([
+        db.tx.event_steps[params.stepId]
+            .update({
+            streamId,
+            streamClientId: clientId,
+            streamStartedAt: startedAt,
+            streamFinishedAt: null,
+            streamAbortReason: null,
+            updatedAt: new Date(),
+        })
+            .link({ stream: streamId }),
+        db.tx.event_executions[params.executionId]
+            .update({
+            activeStreamId: streamId,
+            activeStreamClientId: clientId,
+            lastStreamId: streamId,
+            lastStreamClientId: clientId,
+            updatedAt: new Date(),
+        })
+            .link({ activeStream: streamId, lastStream: streamId }),
+    ]);
+    return {
+        stream: writeStream,
+        streamId,
+        clientId,
+        executionId: params.executionId,
+        stepId: params.stepId,
+    };
+}
+async function finalizePersistedContextStepStream(params) {
+    "use step";
+    const { getContextRuntime } = await import("../runtime.js");
+    const runtime = await getContextRuntime(params.env);
+    const db = runtime?.db;
+    const writer = params.session.stream.getWriter();
+    try {
+        if (params.mode === "abort") {
+            await writer.abort(params.abortReason ?? "aborted");
+        }
+        else {
+            await writer.close();
+        }
+    }
+    finally {
+        writer.releaseLock();
+    }
+    const now = new Date();
+    const txs = [
+        db.tx.event_steps[params.session.stepId].update({
+            streamFinishedAt: now,
+            streamAbortReason: params.mode === "abort" ? params.abortReason ?? "aborted" : null,
+            updatedAt: now,
+        }),
+        db.tx.event_executions[params.session.executionId].update({
+            activeStreamId: null,
+            activeStreamClientId: null,
+            lastStreamId: params.session.streamId,
+            lastStreamClientId: params.session.clientId,
+            updatedAt: now,
+        }),
+    ];
+    const unsetActive = createUnsetStreamLinkTx(db, params.session.executionId, "activeStream", params.session.streamId);
+    if (unsetActive)
+        txs.push(unsetActive);
+    await db.transact(txs);
+}
+export async function closePersistedContextStepStream(params) {
+    return await finalizePersistedContextStepStream({
+        env: params.env,
+        session: params.session,
+        mode: "close",
+    });
+}
+export async function abortPersistedContextStepStream(params) {
+    return await finalizePersistedContextStepStream({
+        env: params.env,
+        session: params.session,
+        mode: "abort",
+        abortReason: params.reason,
+    });
+}
+export async function readPersistedContextStepStream(params) {
+    if (!params.db?.streams?.createReadStream) {
+        throw new Error("InstantDB streams are not available on the provided runtime.");
+    }
+    const clientId = asString(params.clientId);
+    const streamId = asString(params.streamId);
+    if (!clientId && !streamId) {
+        throw new Error("readPersistedContextStepStream requires clientId or streamId.");
+    }
+    const startOffset = typeof params.byteOffset === "number" && Number.isFinite(params.byteOffset)
+        ? Math.max(0, params.byteOffset)
+        : 0;
+    const stream = params.db.streams.createReadStream({
+        clientId: clientId || undefined,
+        streamId: streamId || undefined,
+        byteOffset: startOffset,
+    });
+    const chunks = [];
+    let byteOffset = startOffset;
+    let buffer = "";
+    for await (const rawChunk of stream) {
+        const encoded = typeof rawChunk === "string" ? rawChunk : String(rawChunk ?? "");
+        if (!encoded)
+            continue;
+        byteOffset += contextStreamByteLength(encoded);
+        buffer += encoded;
+        const lines = buffer.split("\n");
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            const parsed = parseContextStepStreamChunk(trimmed);
+            chunks.push(parsed);
+            await params.onChunk?.(parsed);
+        }
+    }
+    const trailing = buffer.trim();
+    if (trailing) {
+        const parsed = parseContextStepStreamChunk(trailing);
+        chunks.push(parsed);
+        await params.onChunk?.(parsed);
+    }
+    return {
+        chunks,
+        byteOffset,
+    };
+}
+export async function resolveContextExecutionStreamPointer(params) {
+    const snapshot = await params.db.query({
+        event_contexts: {
+            $: {
+                where: { id: params.contextId },
+                limit: 1,
+            },
+            currentExecution: {},
+        },
+    });
+    const contextRow = Array.isArray(snapshot?.event_contexts)
+        ? snapshot.event_contexts[0]
+        : null;
+    const executionRow = asRecord(contextRow?.currentExecution);
+    const executionId = asString(executionRow.id);
+    if (!executionId)
+        return null;
+    const activeStreamClientId = asString(executionRow.activeStreamClientId);
+    const activeStreamId = asString(executionRow.activeStreamId);
+    if (activeStreamClientId || activeStreamId) {
+        return {
+            executionId,
+            status: asString(executionRow.status) || null,
+            source: "active",
+            clientId: activeStreamClientId || null,
+            streamId: activeStreamId || null,
+        };
+    }
+    const lastStreamClientId = asString(executionRow.lastStreamClientId);
+    const lastStreamId = asString(executionRow.lastStreamId);
+    if (lastStreamClientId || lastStreamId) {
+        return {
+            executionId,
+            status: asString(executionRow.status) || null,
+            source: "last",
+            clientId: lastStreamClientId || null,
+            streamId: lastStreamId || null,
+        };
+    }
+    return {
+        executionId,
+        status: asString(executionRow.status) || null,
+        source: "none",
+        clientId: null,
+        streamId: null,
+    };
+}
+export async function waitForContextExecutionStreamPointer(params) {
+    const timeoutMs = typeof params.timeoutMs === "number" && Number.isFinite(params.timeoutMs)
+        ? Math.max(0, params.timeoutMs)
+        : 15000;
+    const pollMs = typeof params.pollMs === "number" && Number.isFinite(params.pollMs)
+        ? Math.max(10, params.pollMs)
+        : 125;
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() <= deadline) {
+        const pointer = await resolveContextExecutionStreamPointer({
+            db: params.db,
+            contextId: params.contextId,
+        });
+        if (pointer && (pointer.clientId || pointer.streamId)) {
+            return pointer;
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+    return null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ekairos/events",
-  "version": "1.22.30-beta.development.0",
+  "version": "1.22.31-beta.development.0",
   "description": "Ekairos Events - Context-first workflow runtime",
   "type": "module",
   "main": "dist/index.js",
@@ -108,15 +108,17 @@
     "clean": "node -e \"require('fs').rmSync('dist', {recursive:true, force:true})\"",
     "typecheck": "tsc --noEmit",
     "test": "vitest run -c vitest.config.mts",
+    "pretest:ai-sdk-reactor": "pnpm --filter @ekairos/domain build",
     "test:ai-sdk-reactor": "vitest run -c vitest.config.mts src/tests/context.ai-sdk-reactor.instant.test.ts",
     "test:ai-sdk-reactor:real": "vitest run -c vitest.config.mts src/tests/context.ai-sdk-reactor.real.instant.test.ts",
+    "pretest:scripted-reactor": "pnpm --filter @ekairos/domain build",
     "test:scripted-reactor": "vitest run -c vitest.config.mts src/tests/context.scripted-reactor.instant.test.ts"
   },
   "dependencies": {
     "@ai-sdk/openai": "^2.0.52",
-    "@ekairos/domain": "^1.22.30-beta.development.0",
-    "@instantdb/admin": "0.22.126",
-    "@instantdb/core": "0.22.126",
+    "@ekairos/domain": "^1.22.31-beta.development.0",
+    "@instantdb/admin": "0.22.158",
+    "@instantdb/core": "0.22.142",
     "@vercel/mcp-adapter": "^1.0.0",
     "@vercel/sandbox": "^0.0.23",
     "ai": "^5.0.95",