import type { Message } from '../types/messages.js';
import type { Principal } from '../types/principal.js';
import { type ProtocolGraph } from './shared.js';
export type { ProtocolGraph, ProtocolInterrupt, ProtocolResult, ProtocolRunOptions } from './shared.js';
/** A message in AG-UI's shape. */
export interface AgUiMessage {
    /** Its id. */
    id: string;
    /** `user`, `assistant`, `system`, `developer`, or `tool`; other roles are passed over. */
    role: string;
    /** Its text, or a list of parts with text. */
    content?: unknown;
    /** The tool calls an assistant message made. */
    toolCalls?: Array<{
        id: string;
        type: 'function';
        function: {
            name: string;
            arguments: string;
        };
    }>;
    /** The call a tool message answers. */
    toolCallId?: string;
}
/** One answer to an interrupt, in a resumed run. */
export interface AgUiResumeEntry {
    /** The interrupt it answers. */
    interruptId: string;
    /** `resolved` with a payload, or `cancelled`. */
    status: 'resolved' | 'cancelled';
    /** The answer. */
    payload?: unknown;
}
/** What a frontend sends to start or resume a run: AG-UI's `RunAgentInput`. */
export interface AgUiRunInput {
    /** The conversation. */
    threadId: string;
    /** This run. */
    runId: string;
    /** The run this one continues, when it does. */
    parentRunId?: string;
    /** The whole conversation so far. */
    messages: AgUiMessage[];
    /** Tools the frontend offers. Passed to `input` for an application that uses them. */
    tools?: Array<{
        name: string;
        description: string;
        parameters: unknown;
    }>;
    /** Extra context the frontend supplies. */
    context?: Array<{
        description: string;
        value: string;
    }>;
    /** Shared state, when the frontend keeps any. */
    state?: unknown;
    /** Anything else the frontend forwards. */
    forwardedProps?: unknown;
    /** Answers to the questions a paused run asked. */
    resume?: AgUiResumeEntry[];
}
/** A question a paused run asks, in AG-UI's shape. */
export interface AgUiInterrupt {
    /** Its id, which a resume entry names. */
    id: string;
    /** `tool_call` for an approval, `input_required` for anything else. */
    reason: string;
    /** The question, for a person. */
    message?: string;
    /** The tool call awaiting approval, when it is one. */
    toolCallId?: string;
    /** What the run asked about, whole. */
    metadata?: Record<string, unknown>;
}
/** An AG-UI event, as the stream carries it. */
export type AgUiEvent = {
    type: string;
    timestamp?: number;
} & Record<string, unknown>;
/** Options for `agUiEvents()` and `agUiHandler()`. */
export interface AgUiOptions {
    /**
     * The graph input for a run. Defaults to `{ messages }`, the conversation as Nexus messages,
     * which is what an agent from `createAgent()` takes.
     */
    input?: (run: AgUiRunInput, messages: Message[]) => unknown;
    /** The answer a resume entry gives a question. Defaults to its payload, `true` when it has none, and `false` when cancelled. */
    answer?: (entry: AgUiResumeEntry) => unknown;
    /** Who the run is for, from the request: the place to authenticate a frontend's caller. */
    principal?: (request: Request) => Principal | undefined | Promise<Principal | undefined>;
    /** Adds a `STATE_SNAPSHOT` with the final state before the run finishes. Defaults to true. */
    stateSnapshot?: boolean;
    /**
     * Reports state as it changes: a `STATE_SNAPSHOT` after the first step, then a `STATE_DELTA` with
     * an RFC 6902 JSON Patch after every step that changed it. Defaults to false.
     */
    stateDeltas?: boolean;
    /** Adds a `MESSAGES_SNAPSHOT` with the whole transcript before the run finishes. Defaults to false. */
    messagesSnapshot?: boolean;
    /**
     * Offers the tools the frontend sends to the model, as client tools: when the model calls one, the
     * frontend sees the call, the run finishes, and the frontend sends the result in the next run's
     * messages. A tool of the agent's own always wins a name. Defaults to false, which passes the
     * frontend's tools only to `input`.
     */
    frontendTools?: boolean;
}
/** Options for `agUiEvents()`: everything `agUiHandler()` takes, with the caller already known. */
export interface AgUiEventsOptions extends Omit<AgUiOptions, 'principal'> {
    /** Stops the run. */
    signal?: AbortSignal;
    /** Who the run is for. */
    principal?: Principal;
}
/** The conversation from a `RunAgentInput`, as Nexus messages. */
export declare function agUiMessages(messages: readonly AgUiMessage[]): Message[];
/**
 * A run as AG-UI events, for any transport: Server-Sent Events, a WebSocket, a test. Events are
 * produced as the graph emits them; the last is `RUN_FINISHED` or `RUN_ERROR`.
 */
export declare function agUiEvents(graph: ProtocolGraph, run: AgUiRunInput, options?: AgUiEventsOptions): AsyncGenerator<AgUiEvent>;
/**
 * An HTTP handler that serves a graph to AG-UI frontends: POST a `RunAgentInput`, read the run as
 * Server-Sent Events. Mount it on any route, under any framework that speaks `Request` and
 * `Response`.
 *
 * ```ts
 * const handler = agUiHandler(agent);
 * app.post('/agent', (request) => handler(request));
 * ```
 */
export declare function agUiHandler(graph: ProtocolGraph, options?: AgUiOptions): (request: Request) => Promise<Response>;
/** One event as a Server-Sent Event: `data: <json>` and a blank line. */
export declare function encodeAgUiEvent(event: AgUiEvent): string;
/** One operation of an RFC 6902 JSON Patch, as `STATE_DELTA` carries them. */
export interface AgUiPatchOperation {
    /** `add`, `remove`, or `replace`. */
    op: 'add' | 'remove' | 'replace';
    /** An RFC 6901 pointer: `/messages/-` appends to `messages`, and an empty string is the whole state. */
    path: string;
    /** The value added or put in place. */
    value?: unknown;
}