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

package/dist/context.engine.d.ts

@@ -1,16 +1,22 @@
-import type { Tool, UIMessageChunk } from "ai";
+import type { ModelMessage, UIMessageChunk } from "ai";
+import type { DomainLike } from "@ekairos/domain";
 import type { ContextEnvironment } from "./context.config.js";
-import type { ContextExecution, ContextItem, ContextIdentifier, StoredContext } from "./context.store.js";
+import type { ContextTool } from "./context.action.js";
+import type { ContextRuntime, ContextRuntimeHandleForDomain, ContextRuntimeForDomain } from "./context.runtime.js";
+import { eventsDomain } from "./schema.js";
+import type { ContextExecution, ContextItem, ContextIdentifier, ContextResource, 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> {
+export interface ContextOptions<Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain> {
     onContextCreated?: (args: {
         env: Env;
+        runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>;
         context: StoredContext<Context>;
     }) => void | Promise<void>;
     onContextUpdated?: (args: {
         env: Env;
+        runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>;
         context: StoredContext<Context>;
     }) => void | Promise<void>;
     onEventCreated?: (event: ContextItem) => void | Promise<void>;
@@ -22,7 +28,7 @@ type ContextBenchmarkRecorder = {
     add?(name: string, value: number): void;
     getCurrentStage?(): string | undefined;
 };
-export declare function runContextReactionDirect<Context, Env extends ContextEnvironment = ContextEnvironment>(context: ContextEngine<Context, Env>, triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+export declare function runContextReactionDirect<Context, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>>(context: ContextEngine<Context, Env, RequiredDomain>, triggerEvent: ContextItem, params: ContextReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context>>;
 export interface ContextStreamOptions {
     /**
      * Maximum loop iterations (LLM call → tool execution → repeat).
@@ -44,14 +50,6 @@ export interface ContextStreamOptions {
      * Default: true.
      */
     sendFinish?: boolean;
-    /**
-     * If true, the story loop runs silently (no UI streaming output).
-     *
-     * Persistence (contexts/events/executions) still happens normally.
-     *
-     * Default: false.
-     */
-    silent?: boolean;
     /**
      * Optional writable stream used by direct/non-durable execution.
      *
@@ -67,8 +65,8 @@ export interface ContextStreamOptions {
  *   be a `"use-step"` function (so it can be serialized by reference).
  */
 export type ContextModelInit = string | (() => Promise<any>);
-export type ContextReactParams<Env extends ContextEnvironment = ContextEnvironment> = {
-    env: Env;
+export type ContextReactParams<Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = {
+    runtime: ContextRuntimeForDomain<Runtime, RequiredDomain>;
     /**
      * Context selector (exclusive: `{ id }` OR `{ key }`).
      * - `{ id }` resolves a concrete context id.
@@ -87,24 +85,61 @@ export type ContextReactParams<Env extends ContextEnvironment = ContextEnvironme
         trigger: ContextItem;
         reaction: ContextItem;
         execution: ContextExecution;
+        returnValueHookToken?: string | null;
     };
+    __initialContent?: unknown;
     __benchmark?: ContextBenchmarkRecorder;
 };
-export type ContextReactResult<Context = any> = {
+export type ContextDurableReactParams<Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = Omit<ContextReactParams<Env, RequiredDomain, Runtime>, "durable"> & {
+    durable?: true | undefined;
+};
+export type ContextDirectReactParams<Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = Omit<ContextReactParams<Env, RequiredDomain, Runtime>, "durable"> & {
+    durable: false;
+};
+export type ContextReactBase<Context = any> = {
     context: StoredContext<Context>;
     trigger: ContextItem;
     reaction: ContextItem;
     execution: ContextExecution;
 };
-export type ContextDurableWorkflowPayload<Env extends ContextEnvironment = ContextEnvironment> = {
+export type ContextReactFinalResult<Context = any> = ContextReactBase<Context>;
+export type ContextDirectRun<Context = any> = Promise<ContextReactFinalResult<Context>>;
+export type ContextWorkflowRun<Context = any> = {
+    runId: string;
+    status: Promise<"pending" | "running" | "completed" | "failed" | "cancelled">;
+    returnValue: Promise<ContextReactFinalResult<Context>>;
+    returnValueHook?: {
+        token: string;
+        parentWorkflowRunId: string;
+    } | null;
+};
+export type ContextReactRun<Context = any> = ContextWorkflowRun<Context> | ContextDirectRun<Context>;
+export type ContextReactResult<Context = any, Run extends ContextReactRun<Context> = ContextReactRun<Context>> = ContextReactBase<Context> & {
+    run?: Run;
+};
+export type ContextDurableWorkflowPayload<Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = {
     contextKey: string;
-    env: Env;
+    runtime: ContextRuntimeForDomain<Runtime, RequiredDomain>;
     context?: ContextIdentifier | null;
     triggerEvent: ContextItem;
     options?: Omit<ContextStreamOptions, "writable">;
-    bootstrap: NonNullable<ContextReactParams<Env>["__bootstrap"]>;
+    bootstrap: NonNullable<ContextReactParams<Env, RequiredDomain, Runtime>["__bootstrap"]>;
+};
+export type ContextDurableWorkflowFunction<Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = (payload: ContextDurableWorkflowPayload<Env, RequiredDomain, Runtime>) => Promise<ContextReactFinalResult<Context>>;
+export type ContextToolExecuteContext<Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain, Runtime extends ContextRuntime<Env> = ContextRuntime<Env>> = {
+    runtime: ContextRuntimeForDomain<Runtime, RequiredDomain>;
+    context: StoredContext<Context>;
+    contextIdentifier: ContextIdentifier;
+    toolCallId: string;
+    messages: ModelMessage[];
+    eventId: string;
+    executionId: string;
+    triggerEventId: string;
+    contextId: string;
+    stepId: string;
+    iteration: number;
+    contextStepStream?: WritableStream<string>;
 };
-export type ContextDurableWorkflowFunction<Context = any, Env extends ContextEnvironment = ContextEnvironment> = (payload: ContextDurableWorkflowPayload<Env>) => Promise<ContextReactResult<Context>>;
 export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
 /**
  * Context-level tool type.
@@ -114,13 +149,6 @@ export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl
  *
  * Default behavior when omitted: `auto === true`.
  */
-export type ContextTool = Tool & {
-    /**
-     * If `false`, this action is not intended for automatic execution by the engine.
-     * (Validation/enforcement can be added by callers; default is `true`.)
-     */
-    auto?: boolean;
-};
 /**
  * ## Context loop continuation signal
  *
@@ -132,8 +160,9 @@ export type ContextTool = Tool & {
  * (No imports required in callers.)
  */
 export type ShouldContinue = boolean;
-export type ContextShouldContinueArgs<Context = any, Env extends ContextEnvironment = ContextEnvironment> = {
+export type ContextShouldContinueArgs<Context = any, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain> = {
     env: Env;
+    runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>;
     context: StoredContext<Context>;
     /**
      * The persisted reaction event **so far** for the current streaming run.
@@ -162,14 +191,17 @@ export type ContextShouldContinueArgs<Context = any, Env extends ContextEnvironm
         errorText?: string;
     }>;
 };
-export declare abstract class ContextEngine<Context, Env extends ContextEnvironment = ContextEnvironment> {
-    protected readonly opts: ContextOptions<Context, Env>;
+export declare abstract class ContextEngine<Context, Env extends ContextEnvironment = ContextEnvironment, RequiredDomain extends DomainLike = typeof eventsDomain> {
+    protected readonly opts: ContextOptions<Context, Env, RequiredDomain>;
     private readonly reactor;
-    constructor(opts?: ContextOptions<Context, Env>, reactor?: ContextReactor<Context, Env>);
-    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[]>;
+    constructor(opts?: ContextOptions<Context, Env, RequiredDomain>, reactor?: ContextReactor<Context, Env, RequiredDomain>);
+    protected abstract initialize(context: StoredContext<Context>, env: Env, runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<Context> | Context;
+    protected abstract buildSystemPrompt(context: StoredContext<Context>, env: Env, runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<string> | string;
+    protected describeContext(_content: Context, _context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<string | null>;
+    protected defineGoal(_content: Context, _context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<string | null>;
+    protected defineResources(_content: Context, _context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<ContextResource[]>;
+    protected abstract buildTools(context: StoredContext<Context>, env: Env, runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<Record<string, ContextTool<Context, Env, RequiredDomain>>> | Record<string, ContextTool<Context, Env, RequiredDomain>>;
+    protected buildSkills(_context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<ContextSkillPackage[]>;
     /**
      * First-class event expansion stage (runs on every iteration of the durable loop).
      *
@@ -187,9 +219,9 @@ export declare abstract class ContextEngine<Context, Env extends ContextEnvironm
      *   the builder) so results are durable and replay-safe.
      * - If it’s pure/deterministic, it can run in workflow context.
      */
-    protected expandEvents(events: ContextItem[], _context: StoredContext<Context>, _env: Env): Promise<ContextItem[]>;
-    protected getModel(_context: StoredContext<Context>, _env: Env): ContextModelInit;
-    protected getReactor(_context: StoredContext<Context>, _env: Env): ContextReactor<Context, Env>;
+    protected expandEvents(events: ContextItem[], _context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): Promise<ContextItem[]>;
+    protected getModel(_context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): ContextModelInit;
+    protected getReactor(_context: StoredContext<Context>, _env: Env, _runtime: ContextRuntimeHandleForDomain<Env, RequiredDomain>): ContextReactor<Context, Env, RequiredDomain>;
     /**
      * Context stop/continue hook.
      *
@@ -198,19 +230,16 @@ export declare abstract class ContextEngine<Context, Env extends ContextEnvironm
      *
      * Default: `true` (continue).
      */
-    protected shouldContinue(_args: ContextShouldContinueArgs<Context, Env>): Promise<ShouldContinue>;
-    react(triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+    protected shouldContinue(_args: ContextShouldContinueArgs<Context, Env, RequiredDomain>): Promise<ShouldContinue>;
+    react<Runtime extends ContextRuntime<Env>>(triggerEvent: ContextItem, params: ContextDurableReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context, ContextWorkflowRun<Context>>>;
+    react<Runtime extends ContextRuntime<Env>>(triggerEvent: ContextItem, params: ContextDirectReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context, ContextDirectRun<Context>>>;
+    react<Runtime extends ContextRuntime<Env>>(triggerEvent: ContextItem, params: ContextReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context>>;
     private static prepareExecutionShell;
     private static startDurable;
-    static runDirect<Context, Env extends ContextEnvironment>(story: ContextEngine<Context, Env>, triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<{
-        context: StoredContext<Context>;
-        trigger: ContextItem;
-        reaction: ContextItem;
-        execution: ContextExecution;
-    }>;
+    static runDirect<Context, Env extends ContextEnvironment, RequiredDomain extends DomainLike, Runtime extends ContextRuntime<Env>>(story: ContextEngine<Context, Env, RequiredDomain>, triggerEvent: ContextItem, params: ContextReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context, ContextDirectRun<Context>>>;
     /**
      * @deprecated Use `react()` instead. Kept for backwards compatibility.
      */
-    stream(triggerEvent: ContextItem, params: ContextReactParams<Env>): Promise<ContextReactResult<Context>>;
+    stream<Runtime extends ContextRuntime<Env>>(triggerEvent: ContextItem, params: ContextReactParams<Env, RequiredDomain, Runtime>): Promise<ContextReactResult<Context, ContextWorkflowRun<Context>>>;
     private callOnEnd;
 }