@dudousxd/nestjs-agent-core 0.33.0 → 0.35.0

package/dist/ag-ui/index.d.cts

@@ -0,0 +1,479 @@
+import { A as AgentStreamEvent } from '../stream-events-CgWqAI-1.cjs';
+import '@standard-schema/spec';
+
+/**
+ * The slice of AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0) this producer writes and reads. Typed by
+ * hand rather than imported: the agent package takes no dependency on an AG-UI SDK, and the wire
+ * shape is pinned by the protocol's own JSON Schema, which the tests validate every emitted event
+ * against (`src/ag-ui/fixtures/schema-1.0.json`).
+ *
+ * Optional members are OMITTED when there is nothing to say, never `null` — the protocol's
+ * "absent means absent" rule.
+ */
+/** The protocol version this producer declares on `RUN_STARTED`. */
+declare const AG_UI_PROTOCOL_VERSION = "1.0";
+type AgUiMetadata = Record<string, unknown>;
+/** One provider-and-model's token usage, in the protocol's single accounting. */
+interface AgUiTokenUsage {
+    provider?: string;
+    model?: string;
+    /** Every prompt token, cached or not. */
+    inputTokens?: number;
+    /** Every generated token, reasoning included. */
+    outputTokens?: number;
+    totalTokens?: number;
+    /** Part of `outputTokens`. */
+    reasoningTokens?: number;
+    /** Cache reads — part of `inputTokens`. */
+    cachedInputTokens?: number;
+    /** Cache writes — part of `inputTokens`, disjoint from the reads. */
+    cacheWriteInputTokens?: number;
+}
+/** What an interrupted run is waiting for; a resume entry answers it by `id`. */
+interface AgUiInterrupt {
+    id: string;
+    /** Open string. This producer writes `tool_approval` and `input_required`. */
+    reason: string;
+    message?: string;
+    toolCallId?: string;
+    responseSchema?: Record<string, unknown>;
+    expiresAt?: string;
+    metadata?: AgUiMetadata;
+}
+type AgUiRunOutcome = {
+    type: 'success';
+    pendingToolCallIds?: string[];
+} | {
+    type: 'interrupt';
+    interrupts: AgUiInterrupt[];
+} | {
+    type: 'cancelled';
+};
+interface Base {
+    metadata?: AgUiMetadata;
+}
+type AgUiEvent = (Base & {
+    type: 'RUN_STARTED';
+    threadId: string;
+    runId: string;
+    protocolVersion?: string;
+}) | (Base & {
+    type: 'RUN_FINISHED';
+    threadId: string;
+    runId: string;
+    outcome?: AgUiRunOutcome;
+    usage?: AgUiTokenUsage[];
+}) | (Base & {
+    type: 'RUN_ERROR';
+    message: string;
+    code?: string;
+    usage?: AgUiTokenUsage[];
+}) | (Base & {
+    type: 'STEP_STARTED';
+    stepName: string;
+}) | (Base & {
+    type: 'STEP_FINISHED';
+    stepName: string;
+}) | (Base & {
+    type: 'TEXT_MESSAGE_START';
+    messageId: string;
+    role: 'assistant';
+}) | (Base & {
+    type: 'TEXT_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+}) | (Base & {
+    type: 'TEXT_MESSAGE_END';
+    messageId: string;
+}) | (Base & {
+    type: 'REASONING_START';
+    messageId: string;
+}) | (Base & {
+    type: 'REASONING_MESSAGE_START';
+    messageId: string;
+    role: 'reasoning';
+}) | (Base & {
+    type: 'REASONING_MESSAGE_CONTENT';
+    messageId: string;
+    delta: string;
+}) | (Base & {
+    type: 'REASONING_MESSAGE_END';
+    messageId: string;
+}) | (Base & {
+    type: 'REASONING_END';
+    messageId: string;
+}) | (Base & {
+    type: 'TOOL_CALL_START';
+    toolCallId: string;
+    toolCallName: string;
+    parentMessageId?: string;
+}) | (Base & {
+    type: 'TOOL_CALL_ARGS';
+    toolCallId: string;
+    delta: string;
+}) | (Base & {
+    type: 'TOOL_CALL_END';
+    toolCallId: string;
+}) | (Base & {
+    type: 'TOOL_CALL_RESULT';
+    messageId: string;
+    toolCallId: string;
+    content: string;
+    role: 'tool';
+}) | (Base & {
+    type: 'CUSTOM';
+    name: string;
+    value: unknown;
+});
+/** Where a media part's bytes are. Closed set: an unknown `type` is malformed input. */
+type AgUiPartSource = {
+    type: 'data';
+    value: string;
+    mimeType: string;
+} | {
+    type: 'url';
+    value: string;
+    mimeType?: string;
+} | {
+    type: 'file';
+    value: string;
+    provider?: string;
+    mimeType?: string;
+};
+type AgUiContentPart = {
+    type: 'text';
+    text: string;
+    id?: string;
+    metadata?: unknown;
+} | {
+    type: 'image' | 'audio' | 'video' | 'document';
+    source: AgUiPartSource;
+    id?: string;
+    metadata?: unknown;
+};
+interface AgUiMessage {
+    id: string;
+    role: string;
+    content?: string | AgUiContentPart[];
+    [key: string]: unknown;
+}
+interface AgUiResumeEntry {
+    interruptId: string;
+    status: 'resolved' | 'cancelled';
+    payload?: unknown;
+    metadata?: AgUiMetadata;
+}
+interface AgUiContext {
+    description: string;
+    value: string;
+}
+/** `RunAgentInput`: the one message that travels from the application to the agent. */
+interface AgUiRunInput {
+    threadId: string;
+    runId: string;
+    protocolVersion?: string;
+    parentRunId?: string;
+    state?: unknown;
+    messages: AgUiMessage[];
+    tools?: unknown[];
+    context?: AgUiContext[];
+    forwardedProps?: unknown;
+    resume?: AgUiResumeEntry[];
+}
+/**
+ * The names of the `CUSTOM` events this producer writes for what AG-UI does not model. Prefixed, as
+ * the protocol asks of invented names; a consumer that does not know one ignores it.
+ */
+declare const AG_UI_CUSTOM: {
+    /** `{ runId, threadId }` — the library's own ids for the run behind this stream (cancel, re-attach). */
+    readonly run: "agora.run";
+    /** A generative-UI component (`AgentUiComponent`); a repeat `id` replaces. */
+    readonly ui: "agora.ui";
+    readonly title: "agora.title";
+    readonly queue: "agora.queue";
+    /** The approval request as the native protocol carries it, for a consumer that renders it live. */
+    readonly approvalRequested: "agora.approval-requested";
+    readonly approvalSettled: "agora.approval-settled";
+    /** The whole question set of an elicitation (`ElicitationRequest`). */
+    readonly elicitation: "agora.elicitation";
+    /** `{ usage, costUsd, reasoningMs }` of one model step. */
+    readonly stepUsage: "agora.step-usage";
+    /** `{ message }` — input material this producer could not use and dropped. */
+    readonly warning: "agora.warning";
+};
+/**
+ * What the encoder reads: one frame of a run's stream, in the shared vocabulary
+ * ({@link AgentStreamEvent}) — plus the terminal failure, which the NestJS sink throws and the
+ * Adonis sink writes as a frame, and three optional facts a sink may know about a parked call:
+ *  - `runId` — the run that is PARKED, when it is not the one whose stream this is (a delegated
+ *    sub-agent forwards its frames into its ancestor's stream). Absent → the stream's own run.
+ *  - `toolName`, `input` — the call being approved. Absent → read off the call's announcement.
+ *
+ * Framework-free on purpose: both servers project their own sink onto this and share one encoder.
+ */
+type AgUiSourceFrame = Exclude<AgentStreamEvent, {
+    kind: 'approval-requested';
+} | {
+    kind: 'elicitation';
+} | {
+    kind: 'ui';
+}> | (Extract<AgentStreamEvent, {
+    kind: 'approval-requested';
+}> & {
+    runId?: string;
+    toolName?: string;
+    input?: unknown;
+}) | (Extract<AgentStreamEvent, {
+    kind: 'elicitation';
+}> & {
+    runId?: string;
+})
+/** A component with no `id` is numbered by its position in the stream (`ui:<n>`). */
+ | (Omit<Extract<AgentStreamEvent, {
+    kind: 'ui';
+}>, 'id' | 'props'> & {
+    id?: string;
+    props: unknown;
+})
+/** The run failed: the AG-UI run ends with `RUN_ERROR`, and nothing follows it. */
+ | {
+    kind: 'error';
+    code: string;
+    message: string;
+};
+
+interface AgUiEncoderOptions {
+    /** The ids the consumer sent on `RunAgentInput`: every boundary event echoes them. */
+    threadId: string;
+    runId: string;
+    /** The library run whose stream is being projected (it mints interrupt ids and the `agora.run` event). */
+    streamRunId: string;
+    /** The library's thread id, when it differs from what the consumer calls the thread. */
+    streamThreadId?: string;
+    /**
+     * Frames of the library run's stream that an earlier AG-UI run already delivered (a resume). They
+     * are fed to the encoder like any other — it has to know what they opened — but produce no events.
+     */
+    skip?: number;
+    /**
+     * Tool calls a resuming request just answered. The run has not necessarily said so yet — a parked
+     * run takes a moment to wake — so without this the encoder would read them as still waiting and
+     * report the interrupt again before the answer had any effect.
+     */
+    answered?: readonly string[];
+    /** Model id for the usage entry when the step frames carry none. */
+    model?: string;
+}
+/**
+ * Projects one library run's stream ({@link AgUiSourceFrame}s, in buffer order) onto AG-UI 1.0 events.
+ *
+ * A pure state machine: the same frames always give the same events, which is what lets a resuming
+ * request — served by any replica — replay the run's buffer, skip what the interrupted AG-UI run
+ * already delivered, and continue. It writes nothing itself; {@link agUiEvents} drives it and
+ * decides when the run has stopped to ask.
+ *
+ * What maps where:
+ *  - `text` → `TEXT_MESSAGE_*` (one message per stretch of text);
+ *  - `reasoning` → a reasoning span with one reasoning message;
+ *  - `step-start`/`step-finish` → `STEP_STARTED`/`STEP_FINISHED`, the step's usage folded into the
+ *    run's `usage`;
+ *  - `tool-input-*` → `TOOL_CALL_START`/`ARGS`/`END`; `tool-output*` → `TOOL_CALL_RESULT`;
+ *  - an approval or a question set the run parks on → an `Interrupt` on the closing `RUN_FINISHED`;
+ *  - `cancelled` → the cancelled outcome; an error frame → `RUN_ERROR`;
+ *  - generative UI, title, queue and the native approval/elicitation frames → `CUSTOM` events named
+ *    in {@link AG_UI_CUSTOM}, for what AG-UI has no event for.
+ *
+ * Not mapped: sub-agent attribution (`subagentRunId`) — a delegated agent's frames are projected
+ * flat, as the protocol allows of a producer that does not attribute.
+ */
+declare class AgUiEncoder {
+    private readonly options;
+    private position;
+    private started;
+    private closed;
+    private cancelled;
+    private crossed;
+    private messageSeq;
+    private stepSeq;
+    private openText;
+    private openReasoning;
+    /** The last text message of the current step: a tool call attaches to it. */
+    private stepMessage;
+    private readonly openSteps;
+    private readonly calls;
+    private readonly pending;
+    private readonly usage;
+    constructor(options: AgUiEncoderOptions);
+    /** How many frames of the library stream this encoder has consumed. */
+    get consumed(): number;
+    /** The run is waiting on at least one approval or question set nobody has settled yet. */
+    get waiting(): boolean;
+    /**
+     * Is anything still in flight that is NOT waiting on a person — a tool call announced and neither
+     * answered nor parked? While there is, more frames are coming without anyone's help.
+     */
+    get busy(): boolean;
+    /** `RUN_STARTED`, and the library's own ids for the run. Call once, before the first frame. */
+    start(): AgUiEvent[];
+    /** The AG-UI events the next frame of the library stream stands for (possibly none). */
+    encode(frame: AgUiSourceFrame): AgUiEvent[];
+    /**
+     * The replayed frames are behind us: from here on events are written. The AG-UI run that delivered
+     * them closed everything it had open before it finished, so this run starts with nothing open, and
+     * what the resuming request answered is no longer waiting.
+     */
+    private crossBoundary;
+    private get replaying();
+    private project;
+    /**
+     * The events that end the AG-UI run: whatever is still open is closed first, then `RUN_FINISHED`
+     * with how it ended — interrupted when the run is waiting on someone, cancelled when it was
+     * stopped, success otherwise. Nothing after a `RUN_ERROR`. `ended` says the library run's stream
+     * itself ended, rather than this reader having stopped following it.
+     */
+    finish(ended?: boolean): AgUiEvent[];
+    private interrupts;
+    private custom;
+    private nextMessageId;
+    private textDelta;
+    private reasoningDelta;
+    private closeText;
+    private closeReasoning;
+    private closeStreams;
+    private callStart;
+    private result;
+    private addUsage;
+    private usageEntries;
+}
+
+/**
+ * An interrupt's id carries everything a resuming request needs, so the producer keeps NOTHING
+ * between the run that stopped to ask and the run that answers — the statelessness AG-UI lets a
+ * producer have, and what lets any replica serve the resume.
+ *
+ * It names the library run the human is answering (`parked` — a delegated sub-agent parks its OWN
+ * run), the run whose stream carries the work (`stream`), the tool call, and how many of that
+ * stream's frames the interrupted AG-UI run already delivered (`position`), which is where the
+ * resuming run picks the stream up.
+ *
+ * It is an address, not a credential: the resume route checks the caller owns the run exactly as
+ * the native approve/answer routes do.
+ */
+interface InterruptAddress {
+    kind: 'approval' | 'elicitation';
+    /** The run to settle the call on. */
+    parked: string;
+    /** The run whose buffered stream the resume re-attaches to. */
+    stream: string;
+    toolCallId: string;
+    /** Frames of `stream` already delivered when the run was reported interrupted. */
+    position: number;
+}
+declare function encodeInterruptId(address: InterruptAddress): string;
+/** The address an id names, or `null` for an id this producer did not mint. */
+declare function decodeInterruptId(id: unknown): InterruptAddress | null;
+
+/**
+ * Read a request body as a `RunAgentInput`, or say why it is not one.
+ *
+ * Only what this producer acts on is checked, and a KNOWN member with a value the schema rejects is
+ * malformed (the run never starts). A member it does not recognise is not an error — the protocol's
+ * asymmetry: a newer consumer's input must not bounce off an older producer.
+ */
+declare function parseRunInput(body: unknown): AgUiRunInput | string;
+/** A media part carried inline, ready to be staged as an attachment. */
+interface InlineMedia {
+    kind: 'image' | 'audio' | 'video' | 'document';
+    contentType: string;
+    data: Buffer;
+    filename: string;
+}
+interface UserTurn {
+    /** The text of the message the run answers. */
+    text: string;
+    media: InlineMedia[];
+    /** Why a part was not used, one sentence each — reported, never fatal. */
+    dropped: string[];
+}
+/**
+ * The turn a run answers: the LAST user message of the input. The library keeps each thread's
+ * history itself, so the earlier messages the consumer restates are not read back in — what the
+ * agent resumes from is what it stored.
+ *
+ * Multimodal parts: text parts are the message's text; a media part carried inline (`data`) becomes
+ * an attachment. A part by `url` or by provider `file` handle is dropped and said so — this producer
+ * hands the model only bytes it staged itself, never an address a caller supplied.
+ */
+declare function readUserTurn(messages: readonly AgUiMessage[]): UserTurn | null;
+/** `context` entries as the library's page context carries them, or `undefined` for none. */
+declare function readContext(context: readonly AgUiContext[] | undefined): AgUiContext[] | undefined;
+/**
+ * What the library reads from `forwardedProps` — the consumer's channel for what AG-UI does not
+ * model: which agent, which model, which persona, and the page context the tools see.
+ */
+interface ForwardedOptions {
+    agent?: string;
+    model?: string;
+    persona?: string;
+    pageContext?: Record<string, unknown>;
+}
+declare function readForwardedProps(forwarded: unknown): ForwardedOptions;
+/** One resume entry this producer can act on. */
+interface ResumeDecision {
+    address: InterruptAddress;
+    entry: AgUiResumeEntry;
+}
+interface ResumePlan {
+    decisions: ResumeDecision[];
+    /** Entries naming an interrupt this producer did not raise: skipped with a warning, never fatal. */
+    unrecognised: string[];
+}
+/**
+ * Sort a resume list into what it answers. Every recognised entry must continue the SAME library
+ * run from the SAME point — they are the interrupts of one `RUN_FINISHED` — and a list that does not
+ * is malformed (a string says why).
+ */
+declare function planResume(resume: readonly AgUiResumeEntry[]): ResumePlan | string;
+/** `{ approved, reason?, remember? }` out of an approval's resume payload. A bare boolean is accepted. */
+declare function readApprovalPayload(payload: unknown): {
+    approved: boolean;
+    reason?: string;
+    remember?: boolean;
+} | null;
+/** `questionId → string[]` out of an elicitation's resume payload (`{ answers }` or the map itself). */
+declare function readAnswersPayload(payload: unknown): Record<string, string[]> | null;
+
+interface AgUiStreamOptions extends AgUiEncoderOptions {
+    /**
+     * How long the library stream may stay silent, while the run waits on a person AND has other work
+     * announced, before the AG-UI run is reported interrupted. Default 750 ms.
+     *
+     * Only that mixed case needs a clock. A run whose every open tool call is waiting on someone is
+     * reported at once; a run waiting on no one is never cut short.
+     */
+    quietMs?: number;
+    /** Events to write right after `RUN_STARTED` (warnings about input that was dropped). */
+    preamble?: AgUiEvent[];
+}
+/**
+ * One AG-UI run over a library run's stream.
+ *
+ * AG-UI has no mid-run channel from the consumer: a run that needs an approval or an answer does not
+ * wait with the connection open — it ENDS, saying what it waits for, and a later run carries the
+ * answers. The library run underneath does wait (parked, durably when the runner is durable). So this
+ * stops reading when the run is waiting on someone and nothing else is moving, closes the AG-UI run
+ * with the interrupt outcome, and leaves the library run parked for the resume to pick up.
+ */
+declare function agUiEvents(frames: AsyncIterable<AgUiSourceFrame>, options: AgUiStreamOptions): AsyncGenerator<AgUiEvent>;
+/** One AG-UI event as an SSE frame: a single `data:` line, LF-terminated, as the binding pins. */
+declare function agUiSse(event: AgUiEvent): string;
+/**
+ * A byte sink's stream (NDJSON {@link AgentStreamEvent}s, one per line, as the NestJS sinks carry
+ * it) as the frames the encoder reads. A line that is not a stream event is bare model text — the
+ * sink is a byte channel and a provider may write raw text into it. A run that failed ends the
+ * sink with an {@link AgentStreamError}, which becomes the terminal `error` frame; anything else
+ * thrown is rethrown, for the caller to report.
+ */
+declare function agUiFramesFromNdjson(chunks: AsyncIterable<Uint8Array>): AsyncGenerator<AgUiSourceFrame>;
+
+export { AG_UI_CUSTOM, AG_UI_PROTOCOL_VERSION, type AgUiContentPart, type AgUiContext, AgUiEncoder, type AgUiEncoderOptions, type AgUiEvent, type AgUiInterrupt, type AgUiMessage, type AgUiMetadata, type AgUiPartSource, type AgUiResumeEntry, type AgUiRunInput, type AgUiRunOutcome, type AgUiSourceFrame, type AgUiStreamOptions, type AgUiTokenUsage, type ForwardedOptions, type InlineMedia, type InterruptAddress, type ResumeDecision, type ResumePlan, type UserTurn, agUiEvents, agUiFramesFromNdjson, agUiSse, decodeInterruptId, encodeInterruptId, parseRunInput, planResume, readAnswersPayload, readApprovalPayload, readContext, readForwardedProps, readUserTurn };