@dudousxd/nestjs-agent-react 0.13.0 → 0.15.0

package/dist/model-gHqjNjLJ.d.ts

@@ -0,0 +1,561 @@
+import { ElicitationQuestion, ElicitationInputType, ToolPresentation, ToolCatalogEntry, ToolResultField, ToolResultView, ToolPresentationTone, ElicitationInput } from '@dudousxd/nestjs-agent-core';
+import { ToolUIPart, DynamicToolUIPart, UIMessage } from 'ai';
+
+/** What a form control can hand over: a field's value, a checkbox's state, a picked date, a list. */
+type RawAnswer = string | number | boolean | Date | null | undefined | readonly RawAnswer[];
+/** The question fields {@link coerceAnswer} reads. A transcript question and a core one both fit. */
+type CoercibleQuestion = Pick<ElicitationQuestion, 'multiple'> & {
+    input?: {
+        type: ElicitationInputType;
+    } | null;
+};
+/**
+ * Turn whatever a form control produced into the `string[]` the answer route takes, in the
+ * question's canonical form: numbers as decimals, booleans as `"true"`/`"false"`, dates as
+ * `YYYY-MM-DD` (a `Date` is read as the local calendar day), trimmed where whitespace means
+ * nothing. An empty value becomes `[]` — no answer, not an empty string. A single-choice question
+ * keeps the first value.
+ *
+ * Coercion never judges: pair it with {@link validateAnswer} (the same rules the server applies) to
+ * say what is wrong before sending.
+ */
+declare function coerceAnswer(question: CoercibleQuestion, raw: RawAnswer): string[];
+
+/** Tool name → how the server said it is spoken about. */
+type ToolCatalog = Record<string, ToolPresentation>;
+/** Index `GET <base>/tools` by tool name, keeping only the tools that declared a presentation. */
+declare function toolCatalogFrom(entries: readonly ToolCatalogEntry[]): ToolCatalog;
+/** Dotted-path read. `undefined` rather than a throw, so a template can outlive a field. */
+declare function readPath(value: unknown, path: string): unknown;
+/**
+ * Fill `{dotted.path}` placeholders from `context`. A placeholder with nothing behind it collapses
+ * along with the whitespace in front of it, so "Reading {key}" degrades to "Reading" rather than
+ * printing braces at a person; a filled one keeps the whitespace the author wrote ("({n} files)").
+ */
+declare function fillTemplate(template: string, context: unknown): string;
+/**
+ * The sentence for one call: the presentation's `running` or `done` template over the call's input.
+ *
+ * Nothing here reads the tool's name. A tool the catalog does not describe — added since the catalog
+ * loaded, or declared without a presentation — is narrated generically (`fallback`), because the only
+ * other thing available to say is its identifier.
+ */
+declare function phraseFor(presentation: ToolPresentation | undefined, input: unknown, isSettled: boolean, fallback?: {
+    running: string;
+    done: string;
+}): string;
+
+/** One labelled reading of a `metrics` view. */
+interface ResolvedReading {
+    label: string;
+    /** The value as text (`—` for nothing). */
+    value: string;
+    unit: string | null;
+}
+/**
+ * A tool's output resolved through its view into plain data a renderer draws — never the payload
+ * itself. `null` from {@link resolveResultView} means "draw nothing".
+ */
+type ResolvedResultView = {
+    kind: 'metrics';
+    readings: ResolvedReading[];
+} | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string[][];
+    empty: string | null;
+} | {
+    kind: 'log';
+    lines: string[];
+} | {
+    kind: 'note';
+    text: string;
+};
+/**
+ * A view for an output whose tool declared none, from its shape: an array of flat records is a
+ * table, an array of strings a log, a flat record a set of readings. `undefined` when nothing fits —
+ * a serialized payload is what a person-facing surface exists to avoid, so failing to infer must not
+ * fall back to one.
+ */
+declare function inferResultView(output: unknown): ToolResultView | undefined;
+/**
+ * Read `output` through `view` (or one inferred from its shape when `view` is omitted and `infer` is
+ * on). `null` when there is nothing to draw: an `elsewhere` view, an empty reading set, a missing
+ * array. A table whose rows array is present but empty resolves with no rows and its `empty` line.
+ */
+declare function resolveResultView(output: unknown, view: ToolResultView | undefined, options?: {
+    infer?: boolean;
+}): ResolvedResultView | null;
+
+/**
+ * Where one call stands, as a person reads it:
+ *  - `running` — input streaming or the tool executing;
+ *  - `awaiting-approval` — an `action` call parked on a person;
+ *  - `done` / `failed` / `denied` — settled. A tool that RETURNS `{ error }` has failed just as much
+ *    as one that threw; the two arrive differently and read the same to a person.
+ */
+type ToolCallStatus = 'running' | 'awaiting-approval' | 'done' | 'failed' | 'denied';
+interface ToolCallState {
+    status: ToolCallStatus;
+    isSettled: boolean;
+    isFailed: boolean;
+    isDenied: boolean;
+    output: unknown;
+    error: string | null;
+}
+/** Whether the stream classified this call as an `action` (it parks for approval before it runs). */
+declare function isActionCall(part: AnyToolUIPart): boolean;
+declare function toolCallState(part: AnyToolUIPart): ToolCallState;
+/**
+ * Which failed calls the model went on to correct, by call id: a call that failed and was followed,
+ * in the same run, by a SUCCESS of the same tool. The operator wants to know a retry happened, not
+ * to read every attempt. A failed read is not corrected by a successful query.
+ */
+declare function correctedCallIds(parts: readonly AnyToolUIPart[]): Set<string>;
+/** Everything a surface needs to talk about one call without naming it. */
+interface ToolCallDescription {
+    status: ToolCallStatus;
+    /** "Querying orders" / "Queried orders" — or the generic fallback when the tool declared nothing. */
+    phrase: string;
+    /** The server's noun phrase for the tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    tone: ToolPresentationTone;
+    detail: string | null;
+    /** The approval prompt, templated over the call's input; `null` when the tool declared none. */
+    confirm: {
+        title: string;
+        verb: string;
+        detail: string | null;
+    } | null;
+    /** The output read through its view, once the call is `done`; `null` otherwise or when nothing to draw. */
+    result: ResolvedResultView | null;
+    error: string | null;
+    presentation: ToolPresentation | null;
+}
+interface DescribeToolCallOptions {
+    /** Words for a tool the catalog does not describe. Default `Working` / `Done`. */
+    fallback?: {
+        running: string;
+        done: string;
+    };
+    /** Infer a result view from the output's shape when the tool declared none. Default `false`. */
+    inferResult?: boolean;
+}
+declare function describeToolCall(part: AnyToolUIPart, catalog: ToolCatalog | undefined, options?: DescribeToolCallOptions): ToolCallDescription;
+/**
+ * Calls folded under one key — "Database query ×3" — with the state that matters most across them.
+ */
+interface ToolActivityGroup {
+    key: string;
+    /** The server's label for the group's tool; `null` when it declared no presentation. */
+    label: string | null;
+    icon: string | null;
+    /** Worst-first across the calls: running › awaiting-approval › failed › denied › done. */
+    status: ToolCallStatus;
+    count: number;
+    /** The phrase of the group's LATEST call — what is happening now. */
+    phrase: string;
+    calls: TranscriptToolCall[];
+    /** Calls nested under the group's calls (all depths), when nesting was not expanded. */
+    innerCount: number;
+}
+interface GroupToolActivityOptions {
+    catalog?: ToolCatalog;
+    /**
+     * What makes two calls "the same activity". Default: the tool's presentation `label`, else its
+     * name. Flippy-style source grouping passes its own (e.g. `github:search`).
+     */
+    keyOf?: (call: TranscriptToolCall, presentation: ToolPresentation | undefined) => string;
+    /**
+     * Replace a call that has nested calls with those calls (recursively), so the activity reads as
+     * what the code-mode run DID rather than "ran code". Default `false`: groups are built over the
+     * top-level calls, and `innerCount` says how much ran beneath them.
+     */
+    expandNested?: boolean;
+    /** Drop failed calls the model corrected with a later success of the same tool. Default `false`. */
+    hideCorrected?: boolean;
+    fallback?: {
+        running: string;
+        done: string;
+    };
+}
+/**
+ * Fold a tool run into activity groups, in order of first appearance. Pass `block.roots` (the
+ * transcript's call tree) so nesting is honoured; a flat `block.calls` works too and simply has
+ * nothing nested.
+ */
+declare function groupToolActivity(calls: readonly TranscriptToolCall[], options?: GroupToolActivityOptions): ToolActivityGroup[];
+
+/** A tool UI part on a `UIMessage` — a static `tool-*` part or the `dynamic-tool` part. */
+type AnyToolUIPart = ToolUIPart | DynamicToolUIPart;
+/**
+ * The AI SDK's chat status, plus `reconnecting`: a turn is in flight and its stream dropped, and the
+ * transport is re-attaching (`useAgentChat`). A busy status, like `streaming`.
+ */
+type ChatStatus = 'ready' | 'submitted' | 'streaming' | 'reconnecting' | 'error';
+/** Server-aggregated usage for an assistant turn. */
+interface MessageUsageInfo {
+    inputTokens: number;
+    outputTokens: number;
+    /**
+     * `null` when no price is on record for the model that ran the turn. Distinct from `0`, which is
+     * a turn that genuinely cost nothing — printing `$0` for an unpriced turn states a number the
+     * store never had.
+     */
+    costUsd: number | null;
+}
+/** A run of contiguous prose. `isStreaming` is the PART's own state, not the message's. */
+interface TranscriptTextBlock {
+    kind: 'text';
+    key: string;
+    text: string;
+    isStreaming: boolean;
+}
+/** One file on a message — an uploaded attachment, or one the model produced. */
+interface TranscriptFile {
+    /** Presigned or otherwise directly fetchable. Display-only: the model reads its own copy. */
+    url: string;
+    mediaType: string;
+    filename: string | null;
+    /** `image/*`, which a renderer can show inline rather than as a link. */
+    isImage: boolean;
+}
+/** A run of contiguous files. Grouped so a renderer can lay several out as one strip. */
+interface TranscriptFilesBlock {
+    kind: 'files';
+    key: string;
+    files: TranscriptFile[];
+}
+/**
+ * A run of contiguous reasoning. Carries its own disclosure state because a thread can hold many
+ * of them and each is toggled independently; `isOpen` defaults to `isStreaming` (thinking is worth
+ * watching live, worth folding away once answered) until `toggle` is called for that run.
+ */
+interface TranscriptReasoningBlock {
+    kind: 'reasoning';
+    key: string;
+    text: string;
+    isStreaming: boolean;
+    /**
+     * How long the model thought, in ms — the backend's measurement once the run closed (live) or as
+     * persisted (reloaded). `null` while it still streams, or when nothing was recorded: pair it with
+     * `useElapsed(block.isStreaming)` for a ticking label (`block.durationMs ?? elapsed`).
+     */
+    durationMs: number | null;
+    isOpen: boolean;
+    toggle: (open?: boolean) => void;
+}
+/**
+ * A decision a run is waiting on a human for, and which one a parked call is currently sending.
+ *
+ * One call settles one way at a time, and WHICH one is what lets a surface report progress on the
+ * affordance the person pressed instead of on all of them.
+ */
+type SettleAction = 'approve' | 'reject' | 'answer' | 'skip';
+/** One such decision: whether it can be made, whether it is on its way, and how to send it. */
+interface TranscriptSettleState {
+    available: boolean;
+    /** True from the click until the run resumes and settles the call. */
+    isSubmitting: boolean;
+    run: () => void;
+}
+/** How an approval stands. */
+type TranscriptApprovalStatus = 'pending' | 'approved' | 'rejected' | 'expired';
+/**
+ * Who has to settle a parked call, until when, and — once it settled — how. From the stream's
+ * `approval-requested` / `approval-settled` frames, or the same parts a reloaded thread carries.
+ * `null` on a call whose runner never said (the call can still be awaiting approval).
+ */
+interface TranscriptApproval {
+    /** Open vocabulary the host defines: `'requester'`, `'admin'`, a role… */
+    approver: string;
+    /** ISO-8601; `null` when the request never lapses. Pair with `useApprovalCountdown`. */
+    expiresAt: string | null;
+    /** Why the call needs a person, when the runner said. */
+    reason: string | null;
+    /**
+     * `pending` until a settlement arrives; then what it said. Falls back to the call's own state
+     * (denied → `rejected`, an output → `approved`) for a runner that streams no settlement.
+     */
+    status: TranscriptApprovalStatus;
+    /** The approval also covers later calls of this tool in this thread. */
+    remember: boolean;
+    /** Opaque ref of who decided; `null` while pending, on an expiry, or when the runner did not say. */
+    decidedBy: string | null;
+    /** The surface the decision came through (`'web'`, `'slack'`, `'remembered'`, …). */
+    decidedVia: string | null;
+    /** What the person said when declining. */
+    decisionReason: string | null;
+}
+/** What an approval can carry beyond yes. */
+interface ApproveOptions {
+    /** Approve later calls of the same tool in the same thread without asking again. */
+    remember?: boolean;
+}
+/** One call in a tool run, with whatever human decision it is parked on. */
+interface TranscriptToolCall {
+    part: AnyToolUIPart;
+    toolCallId: string;
+    name: string;
+    /** `read` / `action` as the stream classified the call; `null` when the backend did not say. */
+    toolKind: string | null;
+    /** The call this one ran inside (a code-mode `execute`, a delegated agent); `null` for a top-level call. */
+    parentId: string | null;
+    /**
+     * Calls nested under this one within the same block, in stream order. Always empty for a call
+     * nothing names as its parent.
+     */
+    children: TranscriptToolCall[];
+    /** Who has to decide, when the runner said so. See {@link TranscriptApproval}. */
+    approval: TranscriptApproval | null;
+    /**
+     * How to talk about this call without naming it — status, phrase, label, icon, approval prompt,
+     * resolved result — from the server's presentation when `toolCatalog` was given, generic otherwise.
+     */
+    description: ToolCallDescription;
+    /**
+     * Parked on a person. An `action` tool's input lands and its output never follows on its own —
+     * the loop waits for an approval between the two — so a settled-looking card that never settles
+     * IS the pending approval.
+     */
+    isAwaitingApproval: boolean;
+    /** `run({ remember: true })` approves this tool for the rest of the thread. */
+    approve: TranscriptSettleState & {
+        run: (options?: ApproveOptions) => void;
+    };
+    reject: TranscriptSettleState;
+    /** A failed decision — the call is still parked, so the affordance stays live. */
+    error: string | null;
+}
+/**
+ * A run of CONSECUTIVE tool parts, grouped so a UI can collapse "5 tools ran" into one affordance.
+ * Any non-tool part between two tool parts ends the run — including the AI SDK's `step-start`
+ * markers, so tools from different steps never merge into one group.
+ */
+interface TranscriptToolBlock {
+    kind: 'tools';
+    key: string;
+    parts: AnyToolUIPart[];
+    /** The same calls, each with its human-decision state. Same order as `parts`. */
+    calls: TranscriptToolCall[];
+    /**
+     * The same calls as a tree: every call whose parent is NOT in this block, each carrying its
+     * nested calls in `children`. Equal to `calls` when nothing is nested.
+     */
+    roots: TranscriptToolCall[];
+    /**
+     * The run folded into activity groups ("Database query ×3"), over `roots`, keyed by each tool's
+     * presentation label (else its name). For another grouping, call `groupToolActivity` yourself.
+     */
+    activity: ToolActivityGroup[];
+}
+/**
+ * A component the server pushed into the message (the stream's `ui` frame, or a persisted
+ * `data-ui` part). Rendered by looking `component` up in the host's own registry.
+ */
+interface TranscriptUiBlock {
+    kind: 'ui';
+    key: string;
+    /** The component's identity within the message. */
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`; `null` when the server did not stamp one. */
+    version: number | null;
+    /** The tool call that pushed it (`ctx.emitUi`); `null` for a component pushed outside a tool. */
+    toolCallId: string | null;
+}
+/** One choice a question offers, with its live selection state. */
+interface TranscriptQuestionOption {
+    value: string;
+    label: string;
+    /** A single character the request suggested as a shortcut; `null` when it suggested none. */
+    hotkey: string | null;
+    isSelected: boolean;
+    /** Pre-picked by the agent — what an untouched question submits as. */
+    isDefault: boolean;
+    /** Single choice: replaces the selection. Multiple: adds or removes this value. */
+    select: () => void;
+}
+/** One question of a set, numbered against the whole. */
+interface TranscriptQuestion {
+    id: string;
+    prompt: string;
+    /** A line of help under the prompt; `null` when the request gave none. */
+    description: string | null;
+    /**
+     * How the answer is typed — `{ type, placeholder?, required?, min?, max?, pattern? }` — or `null`
+     * for a plain pick from `options`. Render the control from `input.type`; `select` still picks
+     * from `options`.
+     */
+    input: ElicitationInput | null;
+    multiple: boolean;
+    /** 1-based. The request carries every question up front, so "Question 1 of N" is honest. */
+    position: number;
+    options: TranscriptQuestionOption[];
+    selected: string[];
+    /**
+     * The user has not touched this question, so a submission leaves it out and the server applies
+     * the same defaults it showed. Distinct from "selected happens to equal the defaults": only the
+     * first is recorded as `defaulted` rather than as a choice the user made.
+     */
+    isPristine: boolean;
+    /** The first selected value, or `''` — what a single text/number/date field shows. */
+    value: string;
+    /**
+     * Set a typed answer from whatever the control produced (a string, a number, a checkbox's
+     * boolean, a `Date`, a list); coerced to the question's canonical strings with `coerceAnswer`.
+     * `null`/`''` clears it. Does nothing once the set settled.
+     */
+    setValue: (raw: RawAnswer) => void;
+    /**
+     * Why the current selection would be refused (the server's own rules — `validateAnswer`), or
+     * `null`. A pristine required question with no default reads `requires an answer`; show it once
+     * the user tried to submit, or right away — the model does not decide that for you.
+     */
+    error: string | null;
+}
+/** How a question set settled, once it did. */
+interface TranscriptElicitationOutcome {
+    answers: Record<string, string[]>;
+    /** The user declined to answer and let the agent proceed on its own picks. */
+    skipped: boolean;
+    /** Questions filled from their own defaults rather than by the human. */
+    defaulted: string[];
+    /** The questions against the chosen labels, as the model read them back. */
+    summary: string | null;
+}
+/**
+ * A question set the run put to the user, parked until someone settles it — the intake an agent
+ * declares and the model's own `ask` produce the same block, because the loop streams the same
+ * frame for both.
+ */
+interface TranscriptElicitationBlock {
+    kind: 'elicitation';
+    key: string;
+    /** The parked tool call — what `answer`/`skip` route by. */
+    toolCallId: string;
+    preamble: string | null;
+    questions: TranscriptQuestion[];
+    questionCount: number;
+    /** Still waiting on a human. */
+    isPending: boolean;
+    /** Every question's current selection is acceptable (no question has an `error`). */
+    isValid: boolean;
+    outcome: TranscriptElicitationOutcome | null;
+    /** A failed submission — the run is still parked, so the form stays live. */
+    error: string | null;
+    answer: TranscriptSettleState;
+    skip: TranscriptSettleState;
+}
+/** One retrieved passage, as it rides a retrieval tool call's output. Mirrors core's `Passage`. */
+interface RetrievedPassage {
+    id: string;
+    text: string;
+    score: number;
+    /** Citation-facing origin — a document title, URL or row id. */
+    source?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The passages of one origin, folded together so a citation line reads once per source. */
+interface TranscriptSource {
+    /** The `source` string the retriever stamped, falling back to the passage id when it stamped none. */
+    id: string;
+    label: string;
+    passageCount: number;
+    /** Highest relevance among this source's passages; the scale is the retriever's. */
+    topScore: number;
+    passages: RetrievedPassage[];
+}
+/**
+ * The provenance behind an answer: a run of CONSECUTIVE retrieval tool parts, aggregated by origin.
+ * Detection is structural — a tool output shaped `{ passages: [{ id, text, ... }] }` — because the
+ * tool's NAME is not fixed: inject-mode retrieval persists as `retrieve`, and `createRetrievalTool`
+ * lets the host rename `search_knowledge` to anything.
+ */
+interface TranscriptSourcesBlock {
+    kind: 'sources';
+    key: string;
+    /** What was searched, when the tool call recorded a `{ query }` input. */
+    query: string | null;
+    sources: TranscriptSource[];
+    passageCount: number;
+}
+type TranscriptBlock = TranscriptTextBlock | TranscriptFilesBlock | TranscriptReasoningBlock | TranscriptToolBlock | TranscriptSourcesBlock | TranscriptElicitationBlock | TranscriptUiBlock;
+/** Where a question set's selection state is held, and where its settlement is sent. */
+interface ElicitationBlockOptions {
+    /** The values a question is showing, or `undefined` while the user has not touched it. */
+    picked: (toolCallId: string, questionId: string) => string[] | undefined;
+    pick: (toolCallId: string, questionId: string, values: string[]) => void;
+    canAnswer: boolean;
+    canSkip: boolean;
+    answer: (toolCallId: string) => void;
+    skip: (toolCallId: string) => void;
+    /** Which decision this call is sending, or `null` for none. */
+    submitting: (toolCallId: string) => SettleAction | null;
+    errorOf: (toolCallId: string) => string | null;
+}
+/** Where an approval decision is sent, and what the last one did. */
+interface ApprovalBlockOptions {
+    canApprove: boolean;
+    canReject: boolean;
+    approve: (toolCallId: string, options?: ApproveOptions) => void;
+    reject: (toolCallId: string) => void;
+    /** Which decision this call is sending, or `null` for none. */
+    submitting: (toolCallId: string) => SettleAction | null;
+    errorOf: (toolCallId: string) => string | null;
+}
+interface BuildBlocksOptions {
+    /** Disclosure lookup for a reasoning run; `isStreaming` is the fallback when untouched. */
+    isReasoningOpen: (key: string, isStreaming: boolean) => boolean;
+    toggleReasoning: (key: string, open?: boolean) => void;
+    /**
+     * Lift retrieval tool parts out of the tool run into a `sources` block. Off by default, so a
+     * renderer wired to draw tool cards keeps receiving them as the tool calls they are.
+     */
+    sources?: boolean;
+    /**
+     * Lift a question set out of the tool run into an `elicitation` block. Omitted → it stays a tool
+     * card, which is all a host that has nowhere to send an answer could render anyway.
+     */
+    elicitation?: ElicitationBlockOptions;
+    /** Wire approve/reject onto the calls parked on a human. Omitted → they are reported, not actionable. */
+    approval?: ApprovalBlockOptions;
+    /** Server-declared tool presentations (`useToolCatalog`), for each call's `description`. */
+    toolCatalog?: ToolCatalog;
+}
+/**
+ * Walk a message's parts into renderable blocks, buffering consecutive tool parts into one run and
+ * consecutive files into one strip. A `data-ui` part becomes a `ui` block. A
+ * `data-approval-requested` part is metadata about a call — it is folded into that call's
+ * `approval` and takes no position of its own. Other `data-*` parts are dropped rather than guessed
+ * at, but they still terminate a tool run — their position in the transcript is meaningful even
+ * when their content is not modelled here.
+ */
+declare function buildTranscriptBlocks(message: UIMessage, options: BuildBlocksOptions): TranscriptBlock[];
+/** The message's prose, joined for the clipboard. Reasoning is excluded — it is not the answer. */
+declare function extractMessageText(parts: UIMessage['parts'] | undefined): string;
+interface UsageSummary extends MessageUsageInfo {
+    totalTokens: number;
+    /** `$0`, `$0.0123`, `$0.012`, `$1.23` — precision follows magnitude so sub-cent turns stay legible. */
+    costLabel: string;
+    tokensLabel: string;
+}
+declare function describeUsage(usage: MessageUsageInfo): UsageSummary;
+interface TimestampInfo {
+    iso: string;
+    date: Date;
+    /** "just now" / "5 min. ago" / "Mar 3" — see {@link formatRelativeTime}. */
+    relative: string;
+    absolute: string;
+}
+/** `null` for an unparseable stamp, so a bad `created_at` renders nothing instead of "Invalid Date". */
+declare function describeTimestamp(createdAt: string | null | undefined): TimestampInfo | null;
+/**
+ * "just now" within ±10s (server `created_at` can land a few ms ahead of the client clock), a
+ * relative phrase up to a week, then a calendar date. Uses Intl.RelativeTimeFormat — no date-fns.
+ */
+declare function formatRelativeTime(date: Date): string;
+
+export { resolveResultView as $, type ApproveOptions as A, type BuildBlocksOptions as B, type ChatStatus as C, type DescribeToolCallOptions as D, type ElicitationBlockOptions as E, type TranscriptToolBlock as F, type GroupToolActivityOptions as G, type TranscriptToolCall as H, buildTranscriptBlocks as I, coerceAnswer as J, correctedCallIds as K, describeTimestamp as L, type MessageUsageInfo as M, describeToolCall as N, describeUsage as O, extractMessageText as P, fillTemplate as Q, type RawAnswer as R, type SettleAction as S, type TranscriptUiBlock as T, type UsageSummary as U, formatRelativeTime as V, groupToolActivity as W, inferResultView as X, isActionCall as Y, phraseFor as Z, readPath as _, type TranscriptBlock as a, toolCallState as a0, toolCatalogFrom as a1, type TimestampInfo as b, type ToolCatalog as c, type AnyToolUIPart as d, type TranscriptFile as e, type ApprovalBlockOptions as f, type CoercibleQuestion as g, type ResolvedReading as h, type ResolvedResultView as i, type RetrievedPassage as j, type ToolActivityGroup as k, type ToolCallDescription as l, type ToolCallState as m, type ToolCallStatus as n, type TranscriptApproval as o, type TranscriptApprovalStatus as p, type TranscriptElicitationBlock as q, type TranscriptElicitationOutcome as r, type TranscriptFilesBlock as s, type TranscriptQuestion as t, type TranscriptQuestionOption as u, type TranscriptReasoningBlock as v, type TranscriptSettleState as w, type TranscriptSource as x, type TranscriptSourcesBlock as y, type TranscriptTextBlock as z };

package/dist/types-DFD-soWU.d.cts

@@ -0,0 +1,86 @@
+import { ComponentType, ReactNode } from 'react';
+
+/** The `ui` frame component a composed tree is pushed under (`@dudousxd/nestjs-agent-genui`'s `GENUI_TREE_COMPONENT`). */
+declare const GENUI_TREE_COMPONENT = "genui:tree";
+/** One pushed component, normalized from whatever carried it (a transcript block, a `data-ui` part, a stored entry). */
+interface GenerativeUIItem {
+    id: string;
+    component: string;
+    props: Record<string, unknown>;
+    version: number | null;
+    toolCallId: string | null;
+}
+/** A node of a composed tree (`genui:tree` frames): `{ type, props, children? }`. */
+interface GenerativeUIElement {
+    type: string;
+    props: Record<string, unknown>;
+    children?: GenerativeUIElement[];
+}
+/**
+ * An app's renderer for one component: it receives the component's props spread, plus `children`
+ * when it is a layout node in a tree. Any React component — the library never styles anything.
+ */
+type GenuiRenderer<P = any> = ComponentType<P & {
+    children?: ReactNode;
+}>;
+/** Component name → the app's renderer. */
+type GenuiRegistry = Record<string, GenuiRenderer>;
+/**
+ * Resolve a component the registry does not have — typically a tenant's own component, fetched for
+ * the exact `version` a message was rendered with. Return `null`/`undefined` for "no such
+ * component". May be async; results are cached per resolver, name and version.
+ */
+type ResolveComponent = (name: string, version: number | null) => GenuiRenderer | null | undefined | Promise<GenuiRenderer | null | undefined>;
+interface GenuiIssueLike {
+    path: (string | number)[];
+    message: string;
+}
+type ValidationLike = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    issues: GenuiIssueLike[];
+};
+/**
+ * What the renderer needs from a catalog to validate props before drawing them. A
+ * `@dudousxd/nestjs-agent-genui` `Catalog` satisfies it; declared structurally so this subpath does
+ * not depend on that package.
+ */
+interface GenuiCatalogLike {
+    has(name: string): boolean;
+    validate(name: string, props: unknown): Promise<ValidationLike>;
+    validateSync?(name: string, props: unknown): ValidationLike | undefined;
+}
+interface GenerativeUIOptions {
+    registry: GenuiRegistry;
+    /** Validate props against it before rendering. Components the catalog does not know render unvalidated. */
+    catalog?: GenuiCatalogLike;
+    resolveComponent?: ResolveComponent;
+}
+/** Why an item did not render. */
+type GenerativeUIProblem = {
+    reason: 'unknown';
+    item: GenerativeUIItem;
+} | {
+    reason: 'invalid';
+    item: GenerativeUIItem;
+    issues: GenuiIssueLike[];
+} | {
+    reason: 'error';
+    item: GenerativeUIItem;
+    error: unknown;
+};
+type GenerativeUIState = {
+    status: 'ready';
+    item: GenerativeUIItem;
+    Component: GenuiRenderer;
+    props: Record<string, unknown>;
+} | {
+    status: 'loading';
+    item: GenerativeUIItem;
+} | ({
+    status: 'problem';
+} & GenerativeUIProblem);
+
+export { type GenerativeUIOptions as G, type ResolveComponent as R, type GenerativeUIItem as a, type GenerativeUIProblem as b, type GenerativeUIElement as c, type GenerativeUIState as d, GENUI_TREE_COMPONENT as e, type GenuiCatalogLike as f, type GenuiIssueLike as g, type GenuiRegistry as h, type GenuiRenderer as i };