@ekairos/thread 1.21.88-beta.0

package/dist/thread.engine.d.ts

@@ -0,0 +1,229 @@
+import type { Tool, UIMessageChunk } from "ai";
+import type { ThreadEnvironment } from "./thread.config.js";
+import type { ThreadItem, ContextIdentifier, StoredContext } from "./thread.store.js";
+import { type ThreadReactor } from "./thread.reactor.js";
+import { getClientResumeHookUrl, toolApprovalHookToken, toolApprovalWebhookToken } from "./thread.hooks.js";
+export interface ThreadOptions<Context = any, Env extends ThreadEnvironment = ThreadEnvironment> {
+    onContextCreated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onContextUpdated?: (args: {
+        env: Env;
+        context: StoredContext<Context>;
+    }) => void | Promise<void>;
+    onEventCreated?: (event: ThreadItem) => void | Promise<void>;
+    onToolCallExecuted?: (executionEvent: any) => void | Promise<void>;
+    onEnd?: (lastEvent: ThreadItem) => void | {
+        end?: boolean;
+    } | Promise<void | {
+        end?: boolean;
+    }>;
+}
+export interface ThreadStreamOptions {
+    /**
+     * Maximum loop iterations (LLM call → tool execution → repeat).
+     * Default: 20
+     */
+    maxIterations?: number;
+    /**
+     * Maximum model steps per LLM call.
+     * Default: 1 (or 5 if you override it in your implementation).
+     */
+    maxModelSteps?: number;
+    /**
+     * If true, we do not close the workflow writable stream.
+     * Default: false.
+     */
+    preventClose?: boolean;
+    /**
+     * If true, we write a `finish` chunk to the workflow stream.
+     * 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 workflow writable stream to emit UIMessageChunks into.
+     *
+     * When omitted, the story will obtain a namespaced writable automatically:
+     * `getWritable({ namespace: "context:<contextId>" })`.
+     *
+     * This allows multiple stories / contexts to stream concurrently within the same workflow run.
+     */
+    writable?: WritableStream<UIMessageChunk>;
+}
+/**
+ * Model initializer (DurableAgent-style).
+ *
+ * - `string`: Vercel AI Gateway model id (e.g. `"openai/gpt-5"`), resolved inside the LLM step.
+ * - `function`: a function that returns a model instance. For Workflow compatibility, this should
+ *   be a `"use-step"` function (so it can be serialized by reference).
+ */
+export type ThreadModelInit = string | (() => Promise<any>) | any;
+export type ThreadReactParams<Env extends ThreadEnvironment = ThreadEnvironment> = {
+    env: Env;
+    /**
+     * Context/thread selector (exclusive: `{ id }` OR `{ key }`).
+     * - `{ id }` resolves a concrete context id.
+     * - `{ key }` resolves by `thread.key`.
+     * If omitted/null, the story will create a new thread+context pair.
+     */
+    context?: ContextIdentifier | null;
+    options?: ThreadStreamOptions;
+};
+/**
+ * Payload expected to resume an auto=false tool execution.
+ *
+ * This must be serializable because it crosses the workflow hook boundary.
+ *
+ * See: https://useworkflow.dev/docs/foundations/hooks
+ */
+export type ThreadToolApprovalPayload = {
+    approved: true;
+    comment?: string;
+    args?: Record<string, unknown>;
+} | {
+    approved: false;
+    comment?: string;
+};
+export { toolApprovalHookToken, toolApprovalWebhookToken, getClientResumeHookUrl };
+/**
+ * Thread-level tool type.
+ *
+ * Allows threads to attach metadata to actions/tools (e.g. `{ auto: false }`)
+ * while remaining compatible with the AI SDK `Tool` runtime shape.
+ *
+ * Default behavior when omitted: `auto === true`.
+ */
+export type ThreadTool = 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;
+};
+/**
+ * ## Thread loop continuation signal
+ *
+ * This hook result is intentionally a **boolean** so stories can be extremely declarative:
+ *
+ * - `return true`  => **continue** the durable loop
+ * - `return false` => **finalize** the durable loop
+ *
+ * (No imports required in callers.)
+ */
+export type ShouldContinue = boolean;
+export type ThreadShouldContinueArgs<Context = any, Env extends ThreadEnvironment = ThreadEnvironment> = {
+    env: Env;
+    context: StoredContext<Context>;
+    /**
+     * The persisted reaction event **so far** for the current streaming run.
+     *
+     * This contains the assistant's streamed parts as well as merged tool execution
+     * outcomes (e.g. `state: "output-available"` / `"output-error"`).
+     *
+     * Stories can inspect `reactionEvent.content.parts` to determine stop conditions
+     * (for example: when `tool-end` has an `output-available` state).
+     */
+    reactionEvent: ThreadItem;
+    assistantEvent: ThreadItem;
+    toolCalls: any[];
+    toolExecutionResults: Array<{
+        tc: any;
+        success: boolean;
+        output: any;
+        errorText?: string;
+    }>;
+};
+export declare abstract class Thread<Context, Env extends ThreadEnvironment = ThreadEnvironment> {
+    private opts;
+    private readonly reactor;
+    constructor(opts?: ThreadOptions<Context, Env>, reactor?: ThreadReactor<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, ThreadTool>> | Record<string, ThreadTool>;
+    /**
+     * First-class event expansion stage (runs on every iteration of the durable loop).
+     *
+     * Use this to expand/normalize events before they are converted into model messages.
+     * Typical use-cases:
+     * - Expand file/document references into text (LlamaCloud/Reducto/…)
+     * - Token compaction / summarization of older parts
+     * - Attaching derived context snippets to the next model call
+     *
+     * IMPORTANT:
+     * - This stage is ALWAYS executed by the engine.
+     * - If you don't provide an implementation, the default behavior is an identity transform
+     *   (events pass through unchanged).
+     * - If your implementation performs I/O, implement it as a `"use-step"` function (provided via
+     *   the builder) so results are durable and replay-safe.
+     * - If it’s pure/deterministic, it can run in workflow context.
+     */
+    protected expandEvents(events: ThreadItem[], _context: StoredContext<Context>, _env: Env): Promise<ThreadItem[]>;
+    protected getModel(_context: StoredContext<Context>, _env: Env): ThreadModelInit;
+    protected getReactor(_context: StoredContext<Context>, _env: Env): ThreadReactor<Context, Env>;
+    /**
+     * Thread stop/continue hook.
+     *
+     * After the model streamed and tools executed, the story can decide whether the loop should
+     * continue.
+     *
+     * Default: `true` (continue).
+     */
+    protected shouldContinue(_args: ThreadShouldContinueArgs<Context, Env>): Promise<ShouldContinue>;
+    /**
+     * Workflow-first execution entrypoint.
+     *
+     * - Streaming is written to the workflow run's output stream.
+     * - All I/O is delegated to steps (store access, LLM streaming, stream writes).
+     * - This method returns metadata only.
+     */
+    /**
+     * React to an incoming event and advance the story.
+     *
+     * This is the primary workflow entrypoint.
+     */
+    react(triggerEvent: ThreadItem, params: ThreadReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    /**
+     * @deprecated Back-compat: old object-style call signature.
+     */
+    react(params: {
+        env: Env;
+        /** @deprecated Use `triggerEvent` */
+        incomingEvent?: ThreadItem;
+        triggerEvent?: ThreadItem;
+        contextIdentifier: ContextIdentifier | null;
+        options?: ThreadStreamOptions;
+    }): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    private static runLoop;
+    /**
+     * @deprecated Use `react()` instead. Kept for backwards compatibility.
+     */
+    stream(triggerEvent: ThreadItem, params: ThreadReactParams<Env>): Promise<{
+        contextId: string;
+        context: StoredContext<Context>;
+        triggerEventId: string;
+        reactionEventId: string;
+        executionId: string;
+    }>;
+    private callOnEnd;
+}