@cuylabs/agent-core 0.9.0 → 0.11.0

package/dist/{runtime → execution}/index.d.ts

@@ -1,19 +1,14 @@
-import { A as AgentEvent } from '../events-CE72w8W4.js';
-import { T as TokenUsage, M as Message } from '../messages-BYWGn8TY.js';
-import { S as ScopeSnapshot } from '../types-CQL-SvTn.js';
-import { S as StepProcessingOptions, z as StepProcessingOutput, l as AgentTurnStepCommitSnapshot, r as CreateAgentTurnStepCommitBatchOptions, d as AgentTurnCommitBatch, P as PrepareModelStepOptions, u as PreparedAgentModelStep, R as RunModelStepOptions, x as RunToolBatchOptions, y as RunToolBatchResult, C as CommitOutputOptions, p as CommitStepOptions, j as AgentTurnState, n as AgentTurnStepCommitToolResult, m as AgentTurnStepCommitToolCall } from '../types-DmDwi2zI.js';
-export { A as AgentTurnActiveToolCall, a as AgentTurnBoundaryMetadata, b as AgentTurnBoundarySnapshot, c as AgentTurnCommitApplier, e as AgentTurnCommitOptions, f as AgentTurnEngine, g as AgentTurnEngineOptions, h as AgentTurnPhase, i as AgentTurnResolvedToolCall, k as AgentTurnStateAdvanceOptions, o as AgentTurnStepRuntimeConfig, q as CreateAgentTurnStateOptions, v as ProcessorOptions, w as ProcessorOutput, B as advanceAgentTurnState, E as createAgentTurnEngine, F as createAgentTurnState, G as failAgentTurnState } from '../types-DmDwi2zI.js';
-import { A as AnyInferenceResult } from '../types-BlOKk-Bb.js';
-import { ModelMessage } from 'ai';
-import '../tool-CZWN3KbO.js';
+import { e as AnyInferenceResult, cB as StepProcessingOptions, cC as StepProcessingOutput, a6 as AgentTurnStepCommitSnapshot, aF as CreateAgentTurnStepCommitBatchOptions, _ as AgentTurnCommitBatch, b$ as PrepareModelStepOptions, c0 as PreparedAgentModelStep, cb as RunModelStepOptions, A as AgentEvent, cc as RunToolBatchOptions, cd as RunToolBatchResult, av as CommitOutputOptions, aw as CommitStepOptions, dg as TokenUsage, v as ScopeSnapshot, a4 as AgentTurnState, dn as ToolMetadata, a8 as AgentTurnStepCommitToolResult, a7 as AgentTurnStepCommitToolCall, M as Message, dv as UserMessage, ar as AssistantMessage, dm as ToolMessage, cM as SystemMessage } from '../instance-DzPiv6EK.js';
+export { Q as AgentTurnActiveToolCall, X as AgentTurnBoundaryMetadata, Y as AgentTurnBoundarySnapshot, Z as AgentTurnCommitApplier, $ as AgentTurnCommitOptions, a0 as AgentTurnEngine, a1 as AgentTurnEngineOptions, a2 as AgentTurnPhase, a3 as AgentTurnResolvedToolCall, a5 as AgentTurnStateAdvanceOptions, a9 as AgentTurnStepRuntimeConfig, aE as CreateAgentTurnStateOptions, dy as advanceAgentTurnState, dC as createAgentTurnEngine, dD as createAgentTurnState, dK as failAgentTurnState } from '../instance-DzPiv6EK.js';
+import { L as Logger } from '../types-RSCv7nQ4.js';
+export { c as convertAgentMessagesToModelMessages } from '../model-messages-CJfwfzGe.js';
+import '../types-C_LCeYNg.js';
+import 'ai';
 import 'zod';
-import '../tool-DkhSCV2Y.js';
-import '../types-CHiPh8U2.js';
-import '../runner-CI-XeR16.js';
-import '../types-DTSkxakL.js';
-import '@ai-sdk/provider-utils';
-import '../types-BfNpU8NS.js';
 import '../types-CQaXbRsS.js';
+import '../types-Bj_J8u_W.js';
+import '@ai-sdk/provider-utils';
+import '../sandbox/index.js';
 import '../llm-error-D93FNNLY.js';
 
 /**
@@ -39,10 +34,6 @@ declare class ContextOverflowError extends Error {
  * Process an inference stream into runtime step events.
  */
 declare function processStepStream(stream: AnyInferenceResult, options: StepProcessingOptions): Promise<StepProcessingOutput>;
-/**
- * @deprecated Use `processStepStream`.
- */
-declare const processStream: typeof processStepStream;
 
 declare function createAgentTurnStepCommitBatch(step: number, snapshot: AgentTurnStepCommitSnapshot, options?: CreateAgentTurnStepCommitBatchOptions): AgentTurnCommitBatch | undefined;
 
@@ -58,6 +49,13 @@ declare function runModelStep(options: RunModelStepOptions): AsyncGenerator<Agen
 
 /**
  * Execute planned tool calls outside the AI SDK loop.
+ *
+ * When multiple tool calls are pending, the batch is partitioned:
+ *  - Tools that declare `capabilities.parallelSafe` run concurrently
+ *  - All other tools run serially (in original order)
+ *
+ * Serial tools always run after the parallel batch completes, preserving
+ * the invariant that non-parallel-safe tools never overlap with anything.
  */
 declare function runToolBatch(options: RunToolBatchOptions): Promise<RunToolBatchResult>;
 
@@ -81,6 +79,8 @@ interface AgentTaskPayload {
 interface AgentTaskExecutionContext {
     /** Abort signal propagated to agent.chat(). */
     signal?: AbortSignal;
+    /** Stable identifier for this task execution when supplied by the caller. */
+    executionId?: string;
     /** Optional trigger descriptor from caller (for logging/routing). */
     trigger?: string;
     /**
@@ -88,6 +88,45 @@ interface AgentTaskExecutionContext {
      * For scheduled jobs, a job ID is a good candidate.
      */
     fallbackSessionKey?: string;
+    /**
+     * Optional prior execution state to resume from. When provided, the task
+     * runner restores accumulated response, usage, tool results, and step
+     * counter from this snapshot before streaming the next agent.chat() turn.
+     *
+     * This enables runtime providers (e.g. Dapr) to implement crash recovery
+     * on the direct (non-workflow) execution path: load the last checkpoint
+     * from the execution store, then re-run with `restoreFrom` so the turn
+     * continues from where it left off rather than starting fresh.
+     *
+     * The snapshot only provides accumulated bookkeeping — the actual
+     * conversation context is recovered through the session storage layer
+     * (same sessionId → same persisted messages).
+     */
+    restoreFrom?: AgentTaskResumeSnapshot;
+}
+/**
+ * Portable snapshot of prior execution state used for resume.
+ *
+ * This is intentionally a minimal subset — just enough for the task runner
+ * to restore its accumulators. The full `AgentTaskExecutionSnapshot` (with
+ * turn state, events, scope) lives in the runtime provider's execution store.
+ */
+interface AgentTaskResumeSnapshot {
+    /** Accumulated response text from prior execution. */
+    response: string;
+    /** Accumulated token usage from prior execution. */
+    usage: TokenUsage;
+    /** Tool calls completed in the prior execution. */
+    toolCalls: Array<{
+        name: string;
+        result: unknown;
+    }>;
+    /** Step counter to resume from. */
+    step: number;
+    /** Event counter to resume from. */
+    eventCount: number;
+    /** ISO timestamp of the original execution start. */
+    startedAt: string;
 }
 interface AgentTaskResult {
     response: string;
@@ -117,6 +156,7 @@ interface AgentTaskExecutionRun<TPayload extends AgentTaskPayload = AgentTaskPay
     payload: Readonly<TPayload>;
     context: Readonly<AgentTaskExecutionContext>;
     sessionId: string;
+    executionId: string;
     startedAt: string;
     scope?: ScopeSnapshot;
 }
@@ -158,7 +198,7 @@ interface AgentTaskObserver<TPayload extends AgentTaskPayload = AgentTaskPayload
      * it into activities so child spans (AI SDK, tool calls) are
      * correlated under the observer's root span.
      */
-    getOtelContext?(sessionId: string): unknown;
+    getOtelContext?(sessionId: string, executionId?: string): unknown;
     /**
      * Activate the OTel context for a session around a function call.
      *
@@ -167,7 +207,7 @@ interface AgentTaskObserver<TPayload extends AgentTaskPayload = AgentTaskPayload
      * execution mode. The observer wraps `fn` in `context.with()` so
      * that `context.active()` returns the session's trace context.
      */
-    activateContext?<T>(sessionId: string, fn: () => T): T;
+    activateContext?<T>(sessionId: string, executionId: string, fn: () => T): T;
 }
 interface AgentTaskCheckpointStrategyInput<TPayload extends AgentTaskPayload = AgentTaskPayload> {
     run: AgentTaskExecutionRun<TPayload>;
@@ -206,6 +246,8 @@ interface AgentTaskRunnerOptions<TPayload extends AgentTaskPayload = AgentTaskPa
      * `defaultAgentTaskCheckpointStrategy(...)`.
      */
     checkpointStrategy?: AgentTaskCheckpointStrategy<TPayload>;
+    /** Logger for diagnostic output. Defaults to silent. */
+    logger?: Logger;
 }
 /**
  * Create a reusable task runner that maps generic task payloads to `agent.chat()`.
@@ -256,6 +298,7 @@ interface AgentWorkflowToolMessageSnapshot {
     toolCallId: string;
     toolName: string;
     result: unknown;
+    metadata?: ToolMetadata;
     compactedAt?: number;
 }
 interface AgentWorkflowSystemMessageSnapshot {
@@ -265,7 +308,7 @@ interface AgentWorkflowSystemMessageSnapshot {
     content: string;
 }
 type AgentWorkflowMessageSnapshot = AgentWorkflowUserMessageSnapshot | AgentWorkflowAssistantMessageSnapshot | AgentWorkflowToolMessageSnapshot | AgentWorkflowSystemMessageSnapshot;
-type AgentWorkflowTurnPhase = "model-step" | "tool-batch" | "step-commit" | "output-commit" | "completed" | "failed";
+type AgentWorkflowTurnPhase = "input-commit" | "model-step" | "tool-batch" | "step-commit" | "output-commit" | "completed" | "failed";
 interface AgentWorkflowReplayDecision {
     toolCallId: string;
     toolName: string;
@@ -292,11 +335,17 @@ interface AgentWorkflowToolCallResult {
     toolResult: AgentTurnStepCommitToolResult;
     turnState?: AgentTurnState;
 }
+interface AgentWorkflowInterventionSnapshot {
+    id: string;
+    message: string;
+    createdAt: string;
+}
 interface AgentWorkflowTurnState {
     sessionId: string;
     systemPrompts: string[];
     messages: AgentWorkflowMessageSnapshot[];
     phase: AgentWorkflowTurnPhase;
+    pendingInput?: AgentWorkflowUserMessageSnapshot;
     step: number;
     maxSteps: number;
     usage?: TokenUsage;
@@ -307,6 +356,19 @@ interface AgentWorkflowTurnState {
     error?: string;
     startedAt: string;
     updatedAt: string;
+    /**
+     * Pending steering messages injected by an external client.
+     * In direct execution, the `InterventionController` handles this.
+     * In durable execution, pending messages are drained at each
+     * model-step boundary and injected as user messages.
+     */
+    pendingInterventions?: AgentWorkflowInterventionSnapshot[];
+    /**
+     * Deferred follow-up messages queued by an external client.
+     * These are held until the current turn completes and can then be
+     * surfaced by the host as candidate next-turn messages.
+     */
+    queuedFollowUps?: AgentWorkflowInterventionSnapshot[];
 }
 interface CreateAgentWorkflowTurnStateOptions {
     sessionId: string;
@@ -314,15 +376,30 @@ interface CreateAgentWorkflowTurnStateOptions {
     maxSteps: number;
     systemPrompts?: string[];
     initialMessages?: AgentWorkflowMessageSnapshot[];
+    initialInput?: AgentWorkflowUserMessageSnapshot;
     initialStep?: number;
 }
-declare function snapshotAgentWorkflowMessage(message: Message): AgentWorkflowMessageSnapshot;
-declare function snapshotAgentWorkflowMessages(messages: Message[]): AgentWorkflowMessageSnapshot[];
-declare function restoreAgentWorkflowMessage(snapshot: AgentWorkflowMessageSnapshot): Message;
-declare function restoreAgentWorkflowMessages(snapshots: AgentWorkflowMessageSnapshot[]): Message[];
 declare function createAgentWorkflowTurnState(options: CreateAgentWorkflowTurnStateOptions): AgentWorkflowTurnState;
 declare function cloneAgentWorkflowTurnState(state: AgentWorkflowTurnState): AgentWorkflowTurnState;
+declare function applyWorkflowInterventions(state: AgentWorkflowTurnState, interventions: readonly AgentWorkflowInterventionSnapshot[], updatedAt: string): AgentWorkflowTurnState;
+/**
+ * Drain pending intervention messages from the workflow state,
+ * injecting each as a user message into `state.messages`.
+ *
+ * Returns the updated state with `pendingInterventions` cleared.
+ * If there are no pending interventions, returns the state unchanged.
+ *
+ * This is the durable-execution equivalent of
+ * `InterventionController.drainImmediate()` in the direct path.
+ */
+declare function drainWorkflowInterventions(state: AgentWorkflowTurnState, updatedAt: string): AgentWorkflowTurnState;
+declare function queueWorkflowFollowUps(state: AgentWorkflowTurnState, followUps: readonly AgentWorkflowInterventionSnapshot[], updatedAt: string): AgentWorkflowTurnState;
 
+interface AgentWorkflowInputCommitPlan {
+    kind: "input-commit";
+    sessionId: string;
+    messages: AgentWorkflowMessageSnapshot[];
+}
 interface AgentWorkflowModelStepPlan {
     kind: "model-step";
     sessionId: string;
@@ -345,13 +422,21 @@ interface AgentWorkflowToolCallPlan {
     turnState: AgentWorkflowTurnState["turnState"];
     replayDecision?: AgentWorkflowReplayDecision;
 }
+interface AgentWorkflowToolBatchPlan {
+    kind: "tool-batch";
+    step: number;
+    sessionId: string;
+    toolCalls: AgentTurnStepCommitToolCall[];
+    turnState: AgentWorkflowTurnState["turnState"];
+    replayDecisions: Record<string, AgentWorkflowReplayDecision>;
+}
 interface AgentWorkflowOutputCommitPlan {
     kind: "output-commit";
     sessionId: string;
     text: string;
     usage?: TokenUsage;
 }
-type AgentWorkflowOperationPlan = AgentWorkflowModelStepPlan | AgentWorkflowToolCallPlan | AgentWorkflowStepCommitPlan | AgentWorkflowOutputCommitPlan;
+type AgentWorkflowOperationPlan = AgentWorkflowInputCommitPlan | AgentWorkflowModelStepPlan | AgentWorkflowToolCallPlan | AgentWorkflowToolBatchPlan | AgentWorkflowStepCommitPlan | AgentWorkflowOutputCommitPlan;
 
 /**
  * Decide which deterministic workflow operation should run next.
@@ -383,13 +468,13 @@ declare function recordAgentWorkflowReplayDecision(state: AgentWorkflowTurnState
  */
 declare function failAgentWorkflowTurnState(state: AgentWorkflowTurnState, error: Error, updatedAt: string): AgentWorkflowTurnState;
 
-/**
- * Convert framework messages into Vercel AI SDK model messages.
- *
- * This keeps the message translation logic reusable for workflow activities
- * and other runtime integrations without forcing those integrations to reach
- * into `Agent` internals.
- */
-declare function convertAgentMessagesToModelMessages(messages: Message[]): ModelMessage[];
+declare function snapshotAgentWorkflowMessage(message: UserMessage): AgentWorkflowUserMessageSnapshot;
+declare function snapshotAgentWorkflowMessage(message: AssistantMessage): AgentWorkflowAssistantMessageSnapshot;
+declare function snapshotAgentWorkflowMessage(message: ToolMessage): AgentWorkflowToolMessageSnapshot;
+declare function snapshotAgentWorkflowMessage(message: SystemMessage): AgentWorkflowSystemMessageSnapshot;
+declare function snapshotAgentWorkflowMessage(message: Message): AgentWorkflowMessageSnapshot;
+declare function snapshotAgentWorkflowMessages(messages: Message[]): AgentWorkflowMessageSnapshot[];
+declare function restoreAgentWorkflowMessage(snapshot: AgentWorkflowMessageSnapshot): Message;
+declare function restoreAgentWorkflowMessages(snapshots: AgentWorkflowMessageSnapshot[]): Message[];
 
-export { type AgentTaskChatAdapter, type AgentTaskCheckpointReason, type AgentTaskCheckpointStrategy, type AgentTaskCheckpointStrategyInput, type AgentTaskExecutionCheckpoint, type AgentTaskExecutionContext, type AgentTaskExecutionRun, type AgentTaskExecutionSnapshot, type AgentTaskObserver, type AgentTaskPayload, type AgentTaskResult, type AgentTaskRunner, type AgentTaskRunnerOptions, AgentTurnCommitBatch, AgentTurnState, AgentTurnStepCommitSnapshot, AgentTurnStepCommitToolCall, AgentTurnStepCommitToolResult, type AgentWorkflowAssistantMessageSnapshot, type AgentWorkflowCommitResult, type AgentWorkflowMessageSnapshot, type AgentWorkflowModelStepPlan, type AgentWorkflowModelStepResult, type AgentWorkflowOperationPlan, type AgentWorkflowOutputCommitPlan, type AgentWorkflowReplayDecision, type AgentWorkflowStepCommitPlan, type AgentWorkflowSystemMessageSnapshot, type AgentWorkflowToolBatchResult, type AgentWorkflowToolCallPlan, type AgentWorkflowToolCallResult, type AgentWorkflowToolCallSnapshot, type AgentWorkflowToolMessageSnapshot, type AgentWorkflowTurnPhase, type AgentWorkflowTurnState, type AgentWorkflowUserMessageSnapshot, CommitOutputOptions, CommitStepOptions, ContextOverflowError, CreateAgentTurnStepCommitBatchOptions, type CreateAgentWorkflowTurnStateOptions, DoomLoopError, PrepareModelStepOptions, PreparedAgentModelStep, RunModelStepOptions, RunToolBatchOptions, RunToolBatchResult, StepProcessingOptions, StepProcessingOutput, applyAgentWorkflowCommitResult, applyAgentWorkflowModelStepResult, applyAgentWorkflowToolBatchResult, applyAgentWorkflowToolCallResult, cloneAgentWorkflowTurnState, commitOutput, commitStep, convertAgentMessagesToModelMessages, createAgentTaskRunner, createAgentTurnStepCommitBatch, createAgentWorkflowTurnState, defaultAgentTaskCheckpointStrategy, failAgentWorkflowTurnState, planNextAgentWorkflowOperation, prepareModelStep, processStepStream, processStream, recordAgentWorkflowReplayDecision, restoreAgentWorkflowMessage, restoreAgentWorkflowMessages, runModelStep, runToolBatch, snapshotAgentWorkflowMessage, snapshotAgentWorkflowMessages };
+export { type AgentTaskChatAdapter, type AgentTaskCheckpointReason, type AgentTaskCheckpointStrategy, type AgentTaskCheckpointStrategyInput, type AgentTaskExecutionCheckpoint, type AgentTaskExecutionContext, type AgentTaskExecutionRun, type AgentTaskExecutionSnapshot, type AgentTaskObserver, type AgentTaskPayload, type AgentTaskResult, type AgentTaskResumeSnapshot, type AgentTaskRunner, type AgentTaskRunnerOptions, AgentTurnCommitBatch, AgentTurnState, AgentTurnStepCommitSnapshot, AgentTurnStepCommitToolCall, AgentTurnStepCommitToolResult, type AgentWorkflowAssistantMessageSnapshot, type AgentWorkflowCommitResult, type AgentWorkflowInputCommitPlan, type AgentWorkflowInterventionSnapshot, type AgentWorkflowMessageSnapshot, type AgentWorkflowModelStepPlan, type AgentWorkflowModelStepResult, type AgentWorkflowOperationPlan, type AgentWorkflowOutputCommitPlan, type AgentWorkflowReplayDecision, type AgentWorkflowStepCommitPlan, type AgentWorkflowSystemMessageSnapshot, type AgentWorkflowToolBatchPlan, type AgentWorkflowToolBatchResult, type AgentWorkflowToolCallPlan, type AgentWorkflowToolCallResult, type AgentWorkflowToolCallSnapshot, type AgentWorkflowToolMessageSnapshot, type AgentWorkflowTurnPhase, type AgentWorkflowTurnState, type AgentWorkflowUserMessageSnapshot, CommitOutputOptions, CommitStepOptions, ContextOverflowError, CreateAgentTurnStepCommitBatchOptions, type CreateAgentWorkflowTurnStateOptions, DoomLoopError, PrepareModelStepOptions, PreparedAgentModelStep, RunModelStepOptions, RunToolBatchOptions, RunToolBatchResult, StepProcessingOptions, StepProcessingOutput, applyAgentWorkflowCommitResult, applyAgentWorkflowModelStepResult, applyAgentWorkflowToolBatchResult, applyAgentWorkflowToolCallResult, applyWorkflowInterventions, cloneAgentWorkflowTurnState, commitOutput, commitStep, createAgentTaskRunner, createAgentTurnStepCommitBatch, createAgentWorkflowTurnState, defaultAgentTaskCheckpointStrategy, drainWorkflowInterventions, failAgentWorkflowTurnState, planNextAgentWorkflowOperation, prepareModelStep, processStepStream, queueWorkflowFollowUps, recordAgentWorkflowReplayDecision, restoreAgentWorkflowMessage, restoreAgentWorkflowMessages, runModelStep, runToolBatch, snapshotAgentWorkflowMessage, snapshotAgentWorkflowMessages };

package/dist/{runtime → execution}/index.js

@@ -7,22 +7,23 @@ import {
   applyAgentWorkflowModelStepResult,
   applyAgentWorkflowToolBatchResult,
   applyAgentWorkflowToolCallResult,
+  applyWorkflowInterventions,
   cloneAgentWorkflowTurnState,
   commitOutput,
   commitStep,
-  convertAgentMessagesToModelMessages,
   createAgentTaskRunner,
   createAgentTurnEngine,
   createAgentTurnState,
   createAgentTurnStepCommitBatch,
   createAgentWorkflowTurnState,
   defaultAgentTaskCheckpointStrategy,
+  drainWorkflowInterventions,
   failAgentTurnState,
   failAgentWorkflowTurnState,
   planNextAgentWorkflowOperation,
   prepareModelStep,
   processStepStream,
-  processStream,
+  queueWorkflowFollowUps,
   recordAgentWorkflowReplayDecision,
   restoreAgentWorkflowMessage,
   restoreAgentWorkflowMessages,
@@ -30,15 +31,18 @@ import {
   runToolBatch,
   snapshotAgentWorkflowMessage,
   snapshotAgentWorkflowMessages
-} from "../chunk-J4QDGZIA.js";
-import "../chunk-WWYYNWEW.js";
-import "../chunk-WKHDSSXG.js";
-import "../chunk-H3FUYU52.js";
-import "../chunk-VEKUXUVF.js";
-import "../chunk-4QFNWPIF.js";
-import "../chunk-N7P4PN3O.js";
-import "../chunk-UDCZ673N.js";
+} from "../chunk-WBPOZ7CL.js";
+import {
+  convertAgentMessagesToModelMessages
+} from "../chunk-CMYN2RCB.js";
+import "../chunk-5NVVNXPQ.js";
+import "../chunk-N3VX7FEE.js";
+import "../chunk-RN6WZEUF.js";
+import "../chunk-CJI7PVS2.js";
 import "../chunk-I6PKJ7XQ.js";
+import "../chunk-V4RFNEET.js";
+import "../chunk-FII65CN7.js";
+import "../chunk-T4UIX5D7.js";
 export {
   AgentTurnEngine,
   ContextOverflowError,
@@ -48,6 +52,7 @@ export {
   applyAgentWorkflowModelStepResult,
   applyAgentWorkflowToolBatchResult,
   applyAgentWorkflowToolCallResult,
+  applyWorkflowInterventions,
   cloneAgentWorkflowTurnState,
   commitOutput,
   commitStep,
@@ -58,12 +63,13 @@ export {
   createAgentTurnStepCommitBatch,
   createAgentWorkflowTurnState,
   defaultAgentTaskCheckpointStrategy,
+  drainWorkflowInterventions,
   failAgentTurnState,
   failAgentWorkflowTurnState,
   planNextAgentWorkflowOperation,
   prepareModelStep,
   processStepStream,
-  processStream,
+  queueWorkflowFollowUps,
   recordAgentWorkflowReplayDecision,
   restoreAgentWorkflowMessage,
   restoreAgentWorkflowMessages,