@mastra/core/dist/agent/signals.d.ts

import type { FilePart, TextPart, UserModelMessage } from '../_types/@internal_ai-sdk-v5/dist/index.d.ts';
import type { MastraDBMessage, MastraProviderMetadata } from './message-list/state/types.js';
/**
 * @experimental Agent signals are experimental and may change in a future release.
 */
export type AgentSignalCategory = 'user' | 'state' | 'reactive' | 'notification';
/**
 * @experimental Agent signals are experimental and may change in a future release.
 */
export type AgentLegacySignalType = 'user-message' | 'system-reminder';
export type AgentSignalType = AgentSignalCategory | AgentLegacySignalType;
export type AgentSignalTagName = string;
export type SignalPart = TextPart | SignalFilePart;
type SignalFilePart = {
    type: 'file';
    data: string;
    mediaType: string;
    filename?: string;
    providerOptions?: MastraProviderMetadata;
};
/**
 * @experimental Agent signals are experimental and may change in a future release.
 */
export type AgentSignalContents = string | Array<TextPart | FilePart>;
export type AgentSignalAttributes = Record<string, string | number | boolean | null | undefined>;
export type AgentStateSignalMode = 'snapshot' | 'delta';
export type AgentStateSignalInput = {
    id: string;
    cacheKey: string;
    contents: AgentSignalContents;
    mode?: AgentStateSignalMode;
    value?: unknown;
    delta?: unknown;
    attributes?: AgentSignalAttributes;
    metadata?: Record<string, unknown>;
    providerOptions?: MastraProviderMetadata;
    tagName?: AgentSignalTagName;
};
export type AgentMessageInput = AgentSignalContents | {
    contents: AgentSignalContents;
    attributes?: AgentSignalAttributes;
    metadata?: Record<string, unknown>;
    providerOptions?: MastraProviderMetadata;
};
type AgentSignalInputBase = {
    id?: string;
    createdAt?: Date | string;
    acceptedAt?: Date | string;
    tagName?: AgentSignalTagName;
    contents: AgentSignalContents;
    attributes?: AgentSignalAttributes;
    metadata?: Record<string, unknown>;
    /**
     * Provider options attached to the resulting prompt turn. Surfaces as `providerOptions` on the
     * `UserModelMessage` sent to the model and as `content.providerMetadata` on the persisted DB
     * message (also visible to UI consumers via `useChat` message metadata).
     */
    providerOptions?: MastraProviderMetadata;
};
export type AgentSignalInput = (AgentSignalInputBase & {
    type: 'state';
    /**
     * State signals cannot be transient: they maintain cross-turn tracking
     * (version/cacheKey/activeCopies) that is rebuilt from persisted history, so a
     * delivery-only state signal would silently break dedupe.
     */
    transient?: never;
}) | (AgentSignalInputBase & {
    type: Exclude<AgentSignalType, 'state'>;
    /**
     * Whether this signal is transient. Defaults to `false`.
     *
     * A transient signal is delivered to the model for the current call (it appears in the prompt
     * for this turn), but it is not retained as part of the conversation: it is not written to
     * storage and never re-enters the prompt on later turns. Re-send it each turn from a processor
     * to keep a single fresh copy near the latest message instead of an accumulating history.
     *
     * Transient takes precedence over `persist` delivery behaviors: combining them means the
     * signal is dropped without being stored or delivered, and the accepted result reports
     * `action: 'discard'`.
     */
    transient?: boolean;
});
/**
 * @experimental Agent signals are experimental and may change in a future release.
 */
export type AgentSignalDataPart = {
    type: 'data-user-message' | 'data-signal';
    data: {
        id: string;
        type: AgentSignalCategory;
        tagName?: AgentSignalTagName;
        contents: AgentSignalContents;
        createdAt: string;
        acceptedAt?: string;
        attributes?: AgentSignalAttributes;
        metadata?: Record<string, unknown>;
        providerOptions?: MastraProviderMetadata;
        transient?: boolean;
    };
    transient: true;
};
type CreatedAgentSignalBase = Omit<AgentSignalInputBase, 'id' | 'createdAt' | 'acceptedAt'> & {
    __isCreatedSignal: true;
    id: string;
    createdAt: Date;
    acceptedAt?: Date;
    toDBMessage: (options?: {
        threadId?: string;
        resourceId?: string;
    }) => MastraDBMessage;
    toLLMMessage: () => UserModelMessage;
    toDataPart: () => AgentSignalDataPart;
};
/**
 * A signal created and validated by `createSignal`.
 *
 * @experimental Agent signals are experimental and may change in a future release.
 */
export type CreatedAgentSignal = (CreatedAgentSignalBase & {
    type: 'state';
    transient?: never;
}) | (CreatedAgentSignalBase & {
    type: Exclude<AgentSignalCategory, 'state'>;
    transient?: boolean;
});
export declare function isMastraSignalMessage(message: MastraDBMessage): message is MastraDBMessage & {
    role: 'signal';
};
/**
 * True for a signal DB message created with `transient: true`.
 *
 * @mastra/memory keeps a matching local predicate because its peer range includes core versions
 * without this export. Keep both copies in sync until that peer range can be tightened.
 *
 * @experimental Agent signals are experimental and may change in a future release.
 */
export declare function isTransientSignalMessage(message: MastraDBMessage): boolean;
export declare function signalToXmlMarkup(signal: Pick<AgentSignalInput, 'type' | 'tagName' | 'attributes'> & {
    contents?: string;
}): string;
export declare function isCreatedAgentSignal(input: unknown): input is CreatedAgentSignal;
export declare function createSignal(input: Extract<AgentSignalInput, {
    type: 'state';
}>): Extract<CreatedAgentSignal, {
    type: 'state';
}>;
export declare function createSignal(input: Extract<AgentSignalInput, {
    type: Exclude<AgentSignalType, 'state'>;
}>): Extract<CreatedAgentSignal, {
    type: Exclude<AgentSignalCategory, 'state'>;
}>;
export declare function createSignal(input: AgentSignalInput): CreatedAgentSignal;
/**
 * Resolve delivery option attributes into concrete `attributes` on a signal.
 * Returns a new signal with the selected branch's `attributes` merged into
 * top-level `attributes`.
 *
 * @experimental
 */
export declare function resolveDeliveryAttributes(signal: CreatedAgentSignal, attributes: AgentSignalAttributes | undefined): CreatedAgentSignal;
export declare function signalToMessage(signal: AgentSignalInput | CreatedAgentSignal): UserModelMessage;
export declare function signalToMastraDBMessage(signal: AgentSignalInput | CreatedAgentSignal, options?: {
    threadId?: string;
    resourceId?: string;
}): MastraDBMessage;
export declare function signalToDataPartFormat(signal: AgentSignalInput | CreatedAgentSignal): AgentSignalDataPart;
export declare function mastraDBMessageToSignal(message: MastraDBMessage): CreatedAgentSignal;
export declare function createMessageSignal(input: AgentMessageInput, options?: Pick<AgentSignalInput, 'id' | 'createdAt' | 'acceptedAt'>): CreatedAgentSignal;
export declare function dataPartToSignal(part: AgentSignalDataPart): CreatedAgentSignal;
export {};
//# sourceMappingURL=signals.d.ts.map