@mastra/core
Version:
Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.
223 lines • 10.7 kB
TypeScript
import type { LanguageModelV2Prompt, LanguageModelV2CallWarning } from '@ai-sdk/provider-v5';
import type { StepResult } from '../_types/@internal_ai-sdk-v5/dist/index.js';
import type { MastraDBMessage } from '../agent/message-list/index.js';
import { MessageList } from '../agent/message-list/index.js';
import type { TripWireOptions } from '../agent/trip-wire.js';
import type { IMastraLogger } from '../logger/index.js';
import { SpanType } from '../observability/index.js';
import type { ObservabilityContext, Span } from '../observability/index.js';
import type { TracingContext } from '../observability/types/index.js';
import type { RequestContext } from '../request-context/index.js';
import type { ChunkType } from '../stream/index.js';
import type { MastraModelOutput } from '../stream/base/output.js';
import type { LanguageModelUsage } from '../stream/types.js';
import type { CachedLLMStepChunk, CachedLLMStepResponse, ErrorProcessorOrWorkflow, OutputResult, ProcessInputStepResult, Processor, ProcessorMessageResult, ProcessorStreamWriter, ProcessorWorkflow, RunProcessInputStepArgs, RunProcessInputStepResult, ToolCallInfo } from './index.js';
/**
* Implementation of processor state management
*/
/**
* Tracks state for stream processing across chunks.
* Used by both legacy processors and workflow processors.
*/
export declare class ProcessorState<OUTPUT = undefined> {
private inputAccumulatedText;
private outputAccumulatedText;
private outputChunkCount;
customState: Record<string, unknown>;
streamParts: ChunkType<OUTPUT>[];
span?: Span<SpanType.PROCESSOR_RUN>;
constructor(options?: {
processorName?: string;
processorIndex?: number;
createSpan?: boolean;
} & Partial<ObservabilityContext>);
/** Track incoming chunk (before processor transformation) */
addInputPart(part: ChunkType<OUTPUT>): void;
/** Track outgoing chunk (after processor transformation) */
addOutputPart(part: ChunkType<OUTPUT> | null | undefined): void;
/** Get final output for span */
getFinalOutput(): {
totalChunks: number;
accumulatedText: string;
};
}
/**
* Union type for processor or workflow that can be used as a processor
*/
type ProcessorOrWorkflow = Processor | ProcessorWorkflow;
export declare class ProcessorRunner {
readonly inputProcessors: ProcessorOrWorkflow[];
readonly outputProcessors: ProcessorOrWorkflow[];
readonly errorProcessors: ErrorProcessorOrWorkflow[];
private readonly logger;
private readonly agentName;
/**
* Shared processor state that persists across loop iterations.
* Used by all processor methods (input and output) to share state.
* Keyed by processor ID.
*/
private readonly processorStates;
constructor({ inputProcessors, outputProcessors, errorProcessors, logger, agentName, processorStates, }: {
inputProcessors?: ProcessorOrWorkflow[];
outputProcessors?: ProcessorOrWorkflow[];
errorProcessors?: ErrorProcessorOrWorkflow[];
logger: IMastraLogger;
agentName: string;
processorStates?: Map<string, ProcessorState>;
});
/**
* Get or create ProcessorState for the given processor ID.
* This state persists across loop iterations and is shared between
* all processor methods (input and output).
*/
private getProcessorState;
/**
* Execute a workflow as a processor and handle the result.
* Returns the processed messages and any tripwire information.
*/
private executeWorkflowAsProcessor;
runOutputProcessors(messageList: MessageList, observabilityContext?: ObservabilityContext, requestContext?: RequestContext, retryCount?: number, writer?: ProcessorStreamWriter, result?: OutputResult): Promise<MessageList>;
/**
* Process a stream part through all output processors with state management
*/
processPart<OUTPUT>(part: ChunkType<OUTPUT>, processorStates: Map<string, ProcessorState<OUTPUT>>, observabilityContext?: ObservabilityContext, requestContext?: RequestContext, messageList?: MessageList, retryCount?: number, writer?: ProcessorStreamWriter): Promise<{
part: ChunkType<OUTPUT> | null | undefined;
blocked: boolean;
reason?: string;
tripwireOptions?: TripWireOptions<unknown>;
processorId?: string;
}>;
runOutputProcessorsForStream<OUTPUT = undefined>(streamResult: MastraModelOutput<OUTPUT>, observabilityContext?: ObservabilityContext, writer?: ProcessorStreamWriter): Promise<ReadableStream<any>>;
runInputProcessors(messageList: MessageList, observabilityContext?: ObservabilityContext, requestContext?: RequestContext, retryCount?: number): Promise<MessageList>;
/**
* Run processInputStep for all processors that implement it.
* Called at each step of the agentic loop, before the LLM is invoked.
*
* Unlike processInput which runs once at the start, this runs at every step
* (including tool call continuations). This is useful for:
* - Transforming message types between steps (e.g., AI SDK 'reasoning' -> Anthropic 'thinking')
* - Modifying messages based on step context
* - Implementing per-step message transformations
*
* @param args.messages - The current messages to be sent to the LLM (MastraDBMessage format)
* @param args.messageList - MessageList instance for managing message sources
* @param args.stepNumber - The current step number (0-indexed)
* @param args.tracingContext - Optional tracing context for observability
* @param args.requestContext - Optional runtime context with execution metadata
*
* @returns The processed MessageList
*/
runProcessInputStep(args: RunProcessInputStepArgs): Promise<RunProcessInputStepResult>;
/**
* Run processLLMRequest for all processors that implement it.
*
* Called *after* `MessageList` has been converted to `LanguageModelV2Prompt`
* and immediately *before* the prompt is forwarded to the provider.
* Mutations are scoped to this single call — they do not affect the
* persisted message list, memory, UI, or future model swaps.
*/
runProcessLLMRequest(args: {
prompt: LanguageModelV2Prompt;
model: unknown;
stepNumber: number;
steps: Array<StepResult<any>>;
requestContext?: RequestContext;
retryCount?: number;
abortSignal?: AbortSignal;
tracingContext?: TracingContext;
writer?: ProcessorStreamWriter;
}): Promise<{
prompt: LanguageModelV2Prompt;
response?: CachedLLMStepResponse;
}>;
/**
* Run processLLMResponse for all processors that implement it.
*
* Called *after* the LLM step completes (or after a cached response is
* replayed) and *after* output processors have collected the response
* chunks. The shared `state` object is the same instance passed to
* `processLLMRequest` for the same step, allowing processors to correlate
* pre- and post-call work (e.g. cache key stash, then cache write).
*/
runProcessLLMResponse(args: {
chunks: CachedLLMStepChunk[];
model: unknown;
stepNumber: number;
steps: Array<StepResult<any>>;
warnings?: LanguageModelV2CallWarning[];
request?: unknown;
rawResponse?: unknown;
fromCache: boolean;
requestContext?: RequestContext;
retryCount?: number;
abortSignal?: AbortSignal;
tracingContext?: TracingContext;
writer?: ProcessorStreamWriter;
}): Promise<void>;
/**
* Type guard to check if result is { messages, systemMessages }
*/
private isProcessInputResultWithSystemMessages;
/**
* Run processOutputStep for all processors that implement it.
* Called after each LLM response in the agentic loop, before tool execution.
*
* Unlike processOutputResult which runs once at the end, this runs at every step.
* This is the ideal place to implement guardrails that can trigger retries.
*
* @param args.messages - The current messages including the LLM response
* @param args.messageList - MessageList instance for managing message sources
* @param args.stepNumber - The current step number (0-indexed)
* @param args.finishReason - The finish reason from the LLM
* @param args.toolCalls - Tool calls made in this step (if any)
* @param args.text - Generated text from this step
* @param args.tracingContext - Optional tracing context for observability
* @param args.requestContext - Optional runtime context with execution metadata
* @param args.retryCount - Number of times processors have triggered retry
*
* @returns The processed MessageList
*/
runProcessOutputStep(args: {
steps: Array<StepResult<any>>;
messages: MastraDBMessage[];
messageList: MessageList;
stepNumber: number;
finishReason?: string;
toolCalls?: ToolCallInfo[];
text?: string;
usage?: LanguageModelUsage;
requestContext?: RequestContext;
retryCount?: number;
writer?: ProcessorStreamWriter;
} & Partial<ObservabilityContext>): Promise<MessageList>;
/**
* Run processAPIError on all processors that implement it.
* Called when an LLM API call fails with a non-retryable error.
* Iterates through both input and output processors.
*
* @returns { retry: boolean } indicating whether to retry the LLM call
*/
runProcessAPIError(args: {
error: unknown;
messages: MastraDBMessage[];
messageList: MessageList;
stepNumber: number;
steps: Array<StepResult<any>>;
messageId?: string;
requestContext?: RequestContext;
retryCount?: number;
writer?: ProcessorStreamWriter;
abortSignal?: AbortSignal;
rotateResponseMessageId?: () => string;
} & Partial<ObservabilityContext>): Promise<{
retry: boolean;
}>;
static applyMessagesToMessageList(messages: MastraDBMessage[], messageList: MessageList, idsBeforeProcessing: string[], check: ReturnType<MessageList['makeMessageSourceChecker']>, defaultSource?: 'input' | 'response'): void;
static validateAndFormatProcessInputStepResult(result: ProcessInputStepResult | Awaited<ProcessorMessageResult> | undefined | void, { messageList, processor, stepNumber, }: {
messageList: MessageList;
processor: Processor;
stepNumber: number;
}): Promise<RunProcessInputStepResult>;
}
export {};
//# sourceMappingURL=runner.d.ts.map