@mastra/core/dist/agent/durable/stream-adapter.d.ts

import type { PubSub } from '../../events/pubsub.js';
import type { IMastraLogger } from '../../logger/index.js';
import type { OutputProcessorOrWorkflow } from '../../processors/index.js';
import { MastraModelOutput } from '../../stream/base/output.js';
import type { ChunkType, MastraOnFinishCallback } from '../../stream/types.js';
import { MessageList } from '../message-list/index.js';
import type { StructuredOutputOptions } from '../types.js';
import type { AgentStepFinishEventData, AgentFinishEventData, AgentSuspendedEventData, AgentAbortEventData, AgentIterationCompleteEventData } from './types.js';
/**
 * Options for creating a durable agent stream
 */
export interface DurableAgentStreamOptions<OUTPUT = undefined> {
    /** Pubsub instance to subscribe to */
    pubsub: PubSub;
    /** Run identifier */
    runId: string;
    /** Message ID for this execution */
    messageId: string;
    /** Model information for the output */
    model: {
        modelId: string | undefined;
        provider: string | undefined;
        version: 'v2' | 'v3' | 'v4';
    };
    /** Thread ID for memory */
    threadId?: string;
    /** Resource ID for memory */
    resourceId?: string;
    /**
     * Start replay from this index (0-based).
     * If undefined, uses full replay (subscribeWithReplay).
     * If specified, uses efficient indexed replay (subscribeFromOffset).
     */
    offset?: number;
    /** Callback when chunk is received */
    onChunk?: (chunk: ChunkType<OUTPUT>) => void | Promise<void>;
    /** Callback when step finishes */
    onStepFinish?: (result: AgentStepFinishEventData) => void | Promise<void>;
    /** Callback when execution finishes — routed through MastraModelOutput for rich step data */
    onFinish?: MastraOnFinishCallback<OUTPUT>;
    /** Lifecycle hook called after the FINISH event closes the stream (for cleanup scheduling) */
    onStreamFinished?: () => void | Promise<void>;
    /** Callback on error */
    onError?: ({ error }: {
        error: Error | string;
    }) => void | Promise<void>;
    /** Callback when workflow suspends */
    onSuspended?: (data: AgentSuspendedEventData) => void | Promise<void>;
    /** Callback when execution is aborted via abortSignal */
    onAbort?: (data: AgentAbortEventData) => void | Promise<void>;
    /** Callback fired after each agentic-loop iteration */
    onIterationComplete?: (data: AgentIterationCompleteEventData) => void | Promise<void>;
    /** Optional logger for structured logging */
    logger?: IMastraLogger;
    /**
     * If true, close the underlying ReadableStream when a SUSPENDED event is
     * received. Used by `generate()` / `resumeGenerate()` so that
     * `getFullOutput()` resolves on suspend instead of hanging. Streaming
     * callers leave this `false` so the stream stays open for a later resume.
     */
    closeOnSuspend?: boolean;
    /**
     * Structured output configuration with live schema. When provided,
     * `MastraModelOutput` pipes LLM text through `createObjectStreamTransformer`
     * to produce `object-result` chunks.
     */
    structuredOutput?: StructuredOutputOptions<OUTPUT>;
    /** Output processors to run in MastraModelOutput's stream pipeline */
    outputProcessors?: OutputProcessorOrWorkflow[];
    /**
     * Optional external MessageList to use instead of creating a fresh empty one.
     * When provided (e.g. the registry's live MessageList), MastraModelOutput can
     * resolve step content from messages added during the workflow execution.
     */
    messageList?: MessageList;
}
/**
 * Result from creating a durable agent stream
 */
export interface DurableAgentStreamResult<OUTPUT = undefined> {
    /** The MastraModelOutput that streams from pubsub events */
    output: MastraModelOutput<OUTPUT>;
    /** Cleanup function to unsubscribe from pubsub */
    cleanup: () => void;
    /** Promise that resolves when subscription is established */
    ready: Promise<void>;
}
/**
 * Create a MastraModelOutput that streams from pubsub events.
 *
 * This adapter subscribes to the agent stream pubsub channel and converts
 * pubsub events into a ReadableStream that MastraModelOutput can consume.
 * Callbacks are invoked as events arrive.
 */
export declare function createDurableAgentStream<OUTPUT = undefined>(options: DurableAgentStreamOptions<OUTPUT>): DurableAgentStreamResult<OUTPUT>;
/**
 * Helper to emit a chunk event to pubsub
 */
export declare function emitChunkEvent<OUTPUT = undefined>(pubsub: PubSub, runId: string, chunk: ChunkType<OUTPUT>): Promise<void>;
/**
 * Helper to emit a step start event to pubsub.
 * The `data` payload must include `type: 'step-start'` so the stream-adapter
 * consumer recognises it as a `ChunkType` and enqueues it onto the client stream.
 */
export declare function emitStepStartEvent(pubsub: PubSub, runId: string, data: {
    stepId?: string;
    request?: unknown;
    warnings?: unknown[];
}): Promise<void>;
/**
 * Helper to emit a step finish event to pubsub
 */
export declare function emitStepFinishEvent(pubsub: PubSub, runId: string, data: AgentStepFinishEventData): Promise<void>;
/**
 * Helper to emit a finish event to pubsub
 */
export declare function emitFinishEvent(pubsub: PubSub, runId: string, data: AgentFinishEventData): Promise<void>;
/**
 * Helper to emit an error event to pubsub
 */
export declare function emitErrorEvent(pubsub: PubSub, runId: string, error: Error): Promise<void>;
/**
 * Helper to emit a suspended event to pubsub
 */
export declare function emitSuspendedEvent(pubsub: PubSub, runId: string, data: AgentSuspendedEventData): Promise<void>;
/**
 * Helper to emit an abort event to pubsub
 */
export declare function emitAbortEvent(pubsub: PubSub, runId: string, data: AgentAbortEventData): Promise<void>;
/**
 * Helper to emit an iteration-complete event to pubsub
 */
export declare function emitIterationCompleteEvent(pubsub: PubSub, runId: string, data: AgentIterationCompleteEventData): Promise<void>;
//# sourceMappingURL=stream-adapter.d.ts.map