eve/dist/src/harness/messages.d.ts

Filesystem-first framework for durable backend AI agents that run anywhere.

import type { ModelMessage, UserContent } from "ai";
import type { ChannelDeliveryMetadataEntry, DeliverPayload, SessionAuthContext, TurnCaller } from "#channel/types.js";
import type { StepInput } from "#harness/types.js";
/** Reason a framework-authored user-role message was added to model history. */
export type FrameworkMessageKind = "context.instruction" | "context.state" | "context.compaction" | "memory.load" | "execution.background_task" | "execution.continuation" | "execution.retry";
/** Semantic classification for every user-role message in model history. */
export type UserMessageKind = "user" | "legacy.unknown" | FrameworkMessageKind;
/** A user-role message that is safe to retain in framework model history. */
export type UserModelMessage = Extract<ModelMessage, {
    readonly role: "user";
}> & {
    readonly kind: UserMessageKind;
    readonly metadata?: Record<string, unknown>;
};
/** Model message shape retained in framework history. */
export type HarnessModelMessage = Exclude<ModelMessage, {
    readonly role: "user";
}> | UserModelMessage;
type FrameworkUserMessage = UserModelMessage & {
    readonly kind: FrameworkMessageKind;
};
/** Builds a classified user-role message for model history. */
export declare function createUserMessage(kind: FrameworkMessageKind, content: UserContent, metadata?: Record<string, unknown>): FrameworkUserMessage;
export declare function createUserMessage(kind: "user", content: UserContent, metadata?: Record<string, unknown>): UserModelMessage;
/** Builds a framework-authored user-role message for model history. */
export declare function createFrameworkUserMessage(kind: FrameworkMessageKind, content: UserContent, metadata?: Record<string, unknown>): FrameworkUserMessage;
/** True when a value is a recognized classification for a user-role message. */
export declare function isUserMessageKind(value: unknown): value is UserMessageKind;
/** True when a user-role model message has the required semantic classification. */
export declare function isUserModelMessage(message: ModelMessage): message is UserModelMessage;
/** True when a user-role message was authored by the framework. */
export declare function isFrameworkUserMessage(message: ModelMessage): message is FrameworkUserMessage;
/** Validates that every user-role message is classified before history retains it. */
export declare function validateHarnessModelMessages(messages: readonly ModelMessage[]): HarnessModelMessage[];
export declare function isFrameworkMessageKind(value: unknown): value is FrameworkMessageKind;
/** Marks an execution-owned delivery so its model message retains provenance. */
export declare function markFrameworkStepInput(input: StepInput, kind: FrameworkMessageKind): StepInput;
/** Returns the framework reason for an execution-owned user message, when present. */
export declare function frameworkMessageKindForStepInput(input: StepInput | undefined): FrameworkMessageKind | undefined;
/**
 * Merges two {@link StepInput} values into one.
 *
 * Used by the harness to coalesce deferred step input with the current
 * turn's input, and by the execution layer after calling `onDeliver`
 * for each queued delivery payload.
 */
export declare function coalesceTurnInputs(a: StepInput, b: StepInput): StepInput;
/**
 * Removes text parts with no model-visible content from a user message.
 *
 * Returns `undefined` when no parts remain, allowing callers to omit the user
 * turn entirely rather than create an empty model prompt block.
 */
export declare function normalizeUserContent(content: string | UserContent | undefined): string | UserContent | undefined;
/** Removes blank text blocks that some providers reject from model-bound history. */
export declare function normalizeModelMessages(messages: readonly ModelMessage[]): ModelMessage[];
/**
 * Extracts the final visible assistant text from model response messages.
 *
 * Prefers text extracted from the last assistant message that contains visible
 * text. Falls back to the raw `text` property from the AI SDK result when no
 * assistant message contains text. Returns `null` when neither source contains
 * text.
 */
export declare function resolveAssistantStepText(messages: readonly ModelMessage[], fallback: string | undefined): string | null;
/**
 * Appends user content while preserving structured attachment parts.
 */
export declare function appendUserContent(input: {
    readonly appended: string | UserContent;
    readonly existing: string | UserContent;
}): string | UserContent;
/**
 * Structural shape of the workflow `DeliverHookPayload`. Using a
 * structural type keeps this helper decoupled from the concrete
 * runtime type.
 */
interface DeliverLike {
    readonly auth?: SessionAuthContext | null;
    readonly caller?: TurnCaller;
    readonly deliveryMetadata?: readonly ChannelDeliveryMetadataEntry[];
    readonly kind: "deliver";
    readonly payloads: readonly DeliverPayload[];
}
/**
 * Coalesces an array of deliver-like items into a single item by
 * collecting all payloads and keeping the most recent auth value.
 *
 * Used by the workflow runtime to batch follow-up deliveries that
 * arrived while a turn or subagent delegation was in progress. Each
 * payload is later passed to `onDeliver` individually so channel-
 * specific fields are never lost. A caller defines a turn boundary, so
 * callers must be partitioned before coalescing.
 */
export declare function coalesceDeliveries<T extends DeliverLike>(items: readonly T[]): T;
export {};