@dudousxd/nestjs-agent-core 0.17.0 → 0.19.0

package/dist/{tool-CL9oEytW.d.cts → tool-Q2rmGeaG.d.cts}

@@ -266,6 +266,282 @@ interface AgentHistoryWindow {
     summarize?: boolean;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ *
+ * The vocabulary is also a CONTRACT for runners that are not this library's loop: anything that
+ * writes these frames (one JSON object per SSE `data:` line) gets the React transport, transcript
+ * model and hooks for free. Two rules keep it evolvable:
+ *  - every frame is a JSON object with a string `kind`; a reader MUST tolerate kinds it does not
+ *    know (the React transport forwards them as `data-<kind>` parts rather than dropping them);
+ *  - fields are only ever added, and new fields are optional.
+ */
+
+/**
+ * A component the server pushed into the conversation: generative UI that is NOT a tool call's
+ * rendering. It is addressed by `component` (a key in the client's own component registry), never
+ * by a tool name, so a runner can emit one from anywhere — a tool body, a post-processing step, a
+ * sandboxed agent that renders through its own protocol.
+ *
+ * `id` is the component's identity within the message: a second frame with the same `id` REPLACES
+ * the first (streaming props into a chart, flipping a card from "loading" to "ready"), it never
+ * adds a second component.
+ */
+interface AgentUiComponent {
+    id: string;
+    /** Registry key the client resolves to its own renderer, e.g. `data-table`. */
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
+    version?: number;
+}
+/**
+ * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
+ * settled through the tool-call approve/reject routes, by its `toolCallId`.
+ */
+interface AgentApprovalRequest {
+    /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
+    id: string;
+    /**
+     * Who may decide. Open vocabulary the host defines — `'requester'` (the person chatting),
+     * `'admin'`, a role name, a team. A client uses it to say "waiting on an admin" instead of
+     * offering buttons the viewer cannot use.
+     */
+    approver: string;
+    /** ISO-8601 instant after which the request lapses. Absent → it never expires. */
+    expiresAt?: string;
+    /** Why this call needs a person, in words for that person. */
+    reason?: string;
+}
+type AgentStreamEvent = {
+    kind: 'step-start';
+}
+/**
+ * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
+ * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
+ * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
+ */
+ | {
+    kind: 'step-finish';
+    usage?: MessageUsage;
+    costUsd?: number | null;
+    /**
+     * How long the model spent thinking in this step, in ms — the same number persisted as
+     * `StoredMessage.reasoningMs`, so a live thread and a reloaded one read the same duration.
+     * Absent when the step had no reasoning.
+     */
+    reasoningMs?: number;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+}
+/**
+ * `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool.
+ *
+ * `parentId` nests this call under another call on the same stream: the inner calls a code-mode
+ * `execute` makes, the tools a delegated sub-agent runs. The parent must be announced first. A
+ * call's parent is fixed by its first frame that names one; later frames may omit it.
+ */
+ | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+    toolKind: 'read' | 'action';
+    parentId?: string;
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+    toolKind: 'read' | 'action';
+    /** Same as on `tool-input-start`, for a runner that announces a call without streaming its input. */
+    parentId?: string;
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+}
+/**
+ * A person was asked to approve an action tool and declined it. Its own frame, NOT
+ * `tool-output-error`: a refusal is a decision with a known outcome — nothing ran — while a
+ * failure is an outcome nobody chose and whose effects are unknown. Rendering them the same way
+ * tells an operator their own "no" was a malfunction. Maps onto the SDK's `output-denied` tool
+ * part state, which a client reads without knowing any tool's name.
+ */
+ | {
+    kind: 'tool-output-denied';
+    id: string;
+    reason?: string;
+}
+/**
+ * The run has put a question set to the user and is parked until someone answers it (or skips).
+ * Written by the LOOP for both elicitation surfaces — the configured intake and the model's `ask`
+ * tool — so a client renders one form either way rather than learning to recognise a tool name.
+ * The matching `tool-output` frame, under the same `id`, carries the settled answers.
+ */
+ | {
+    kind: 'elicitation';
+    id: string;
+    request: ElicitationRequest;
+}
+/**
+ * An action tool call (already announced by `tool-input-start`/`tool-input-available` under the
+ * same `id`) is parked on a person. Optional: a client still treats an `action` call stuck at
+ * its input as pending — this frame adds WHO has to decide and UNTIL WHEN, and moves the call
+ * into the AI SDK's native `approval-requested` state.
+ */
+ | ({
+    kind: 'approval-requested';
+} & AgentApprovalRequest)
+/**
+ * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
+ * call. See {@link AgentUiComponent}.
+ */
+ | ({
+    kind: 'ui';
+} & AgentUiComponent)
+/**
+ * The thread's title was set or changed while this run streamed (typically derived from the
+ * first exchange). Thread-level, not message content: a client updates its header/sidebar and
+ * does not render it in the transcript.
+ */
+ | {
+    kind: 'title';
+    title: string;
+}
+/**
+ * Someone stopped this run. The stream's LAST frame, written by the runner that settled the
+ * cancel, immediately before a normal `end()` — never a `fail()`, because a cancel is not an
+ * error and a client that retries on a failed stream must not retry this.
+ *
+ * A run that simply ends wrote everything it had; one that ends after this frame did not, and the
+ * difference is the whole point: without it a reader cannot tell a truncated answer from a
+ * complete one. Consumers that predate the frame ignore it and see the `end()` they always saw.
+ */
+ | {
+    kind: 'cancelled';
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+/**
+ * Read one NDJSON line back, or `null` when the line is not a stream event at all.
+ *
+ * `null` covers a genuinely opaque chunk, not just malformed JSON: the sink is a byte channel, so a
+ * model provider is free to write anything into it and some write bare text. A caller that has to
+ * CLASSIFY a chunk — the output gate, which may only forward what it can prove is not the answer —
+ * treats an unreadable frame as unclassifiable rather than guessing.
+ */
+declare function decodeStreamEvent(line: string): AgentStreamEvent | null;
+
+/**
+ * How a person-facing surface talks about a tool WITHOUT ever naming it. Declared on the server,
+ * beside the tool's input schema, because whoever changes the input is the one who has to re-word
+ * the sentence that mentions it — and a client that shipped its own name-to-sentence map would go
+ * stale the moment a tool was renamed. A tool name is an identifier, never copy.
+ *
+ * `running` / `done` (and `confirm.title`, `confirm.detail`, `result.text`) are templates:
+ * `{dotted.path}` placeholders are filled from the call's INPUT (or, for `result`, its OUTPUT), so one
+ * declaration covers every call the tool will ever receive and replays identically from history.
+ * A placeholder with nothing behind it collapses along with the space before it.
+ */
+interface ToolPresentation {
+    /** Noun phrase, for counts and headings: "Database query", "Knowledge base". */
+    label: string;
+    /** Present progressive, while the call is in flight: "Reading {bucket}". */
+    running: string;
+    /** Settled, once the output is in: "Read {bucket}". */
+    done: string;
+    /** A key into the client's own glyph map (`database`, `search`, …). Unknown keys fall back to a generic glyph there. */
+    icon?: string;
+    /** One line naming what the tool reaches, for when the activity line is opened. */
+    detail?: string;
+    /** `destructive` earns the warning treatment on an approval prompt. */
+    tone?: ToolPresentationTone;
+    /** What a person is being asked to allow when an `action` call parks for approval. */
+    confirm?: ToolConfirmation;
+    /** How the call's OUTPUT reads as content. */
+    result?: ToolResultView;
+}
+type ToolPresentationTone = 'neutral' | 'destructive';
+interface ToolConfirmation {
+    /** "Delete {count} files?" */
+    title: string;
+    /** The button: "Delete". */
+    verb: string;
+    /** A sentence under the title, when the title alone does not say what changes. */
+    detail?: string;
+}
+/** A value read out of a tool's output by dotted path, with the words to put next to it. */
+interface ToolResultField {
+    path: string;
+    label: string;
+    unit?: string;
+}
+/**
+ * How a tool's output reads as content. Every variant names dotted paths into the output rather
+ * than shapes, so a renderer never has to recognise which tool it is drawing: it receives
+ * `{ view, output }` and draws it.
+ */
+type ToolResultView = 
+/** A row of labelled readings — one result, several facets. */
+{
+    kind: 'metrics';
+    fields: ToolResultField[];
+}
+/** `rows` is a path to an array; each column's `path` is read WITHIN a row. */
+ | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string;
+    empty?: string;
+}
+/** `lines` is a path to an array of strings, drawn as a log tail. */
+ | {
+    kind: 'log';
+    lines: string;
+}
+/** One sentence, templated over the output. */
+ | {
+    kind: 'note';
+    text: string;
+}
+/** The output is drawn somewhere else on the screen already (a pushed component, a side panel). */
+ | {
+    kind: 'elsewhere';
+};
+/**
+ * One tool as `GET <base>/tools` reports it: the tools THIS actor may be offered by the chosen agent,
+ * with how each is spoken about. `presentation` is absent for a tool that declared none — a client
+ * then narrates it generically rather than falling back to its name.
+ */
+interface ToolCatalogEntry {
+    /** The wire name tool parts carry (`tool-<name>`) — the key a client looks a call up by. */
+    name: string;
+    kind: ToolKind;
+    presentation?: ToolPresentation;
+}
+
 /**
  * Transient tool-error classification + the retry loop that wraps a tool's own invocation. A
  * classified-transient error (a DB deadlock, a lock-wait timeout, a serialization failure) means
@@ -385,6 +661,11 @@ interface ToolSpec {
     name: string;
     kind: ToolKind;
     description: string;
+    /**
+     * How a person-facing surface talks about this tool (see {@link ToolPresentation}). Never shown
+     * to the model; served to clients by `GET <base>/tools`.
+     */
+    presentation?: ToolPresentation;
     /**
      * Input schema as a [Standard Schema](https://standardschema.dev) — validation-agnostic, so
      * Zod, Valibot, or ArkType all work. The loop validates input via `~standard.validate` before
@@ -750,6 +1031,19 @@ interface StoredMessage {
     usage?: MessageUsage;
     /** The run (turn) that produced this message; absent on a row written before this was recorded. */
     runId?: string;
+    /**
+     * The model's thinking for this step, as it streamed (`reasoning` frames), so a reloaded thread
+     * shows it where the live one did. Absent when the model produced none, or on a row written
+     * before this was recorded.
+     */
+    reasoning?: string;
+    /** How long the model spent thinking in this step, in ms — what a "Thought for 4s" label reads. */
+    reasoningMs?: number;
+    /**
+     * Components the server pushed into this step (`ui` frames), in first-seen order with the last
+     * props for each `id` — a reloaded thread replays them as `data-ui` parts.
+     */
+    ui?: AgentUiComponent[];
     createdAt: string;
 }
 interface ThreadDetail extends ThreadSummary {
@@ -1011,4 +1305,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-export { type IncrementalGating as $, type Actor as A, type AgentHistoryWindow as B, type AskToolInput as C, type DetachedDelivery as D, type ElicitationRequest as E, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as F, DEFAULT_INTAKE_PREAMBLE as G, type HumanReply as H, type InputProcessor as I, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as J, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as K, type LlmStepEnvelope as L, type ModelMessage as M, type ElicitationOption as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type ElicitationOutcome as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, type ElicitationQuestion as V, type ElicitationReply as W, type ElicitationResult as X, type HistoryPolicyContext as Y, type HistorySelection as Z, type HistorySummary as _, type ToolDefinition as a, type InvokeWithTransientRetryOptions as a0, MAX_ASK_QUESTIONS as a1, type MessageRole as a2, OutputRejectedError as a3, type OutputVerdict as a4, ProcessorFailedError as a5, type PromptContext as a6, type QuotaView as a7, type ToolKind as a8, type ToolStepCtx as a9, type ToolTransientRetryNumbers as aa, type ToolTransientRetryOptions as ab, askInputSchema as ac, askToolDefinition as ad, invokeWithTransientRetry as ae, isTransientToolError as af, normalizeElicitationReply as ag, renderElicitationAnswers as ah, resolveElicitation as ai, resolveToolTransientRetryNumbers as aj, settleElicitation as ak, type ToolCallRequest as b, type MessageUsage as c, type ThreadSummary as d, type ThreadDetail as e, type ToolResult as f, type MessageAttachment as g, type ToolCallStatus as h, type ToolSpec as i, type AgentRunInput as j, type HistoryPolicy as k, type ProcessedPrompt as l, type ModelAnswer as m, type PageContext as n, type AgentDefinition as o, type AgentDelegation as p, type AiToolCtx as q, type PromptBuilder as r, type PromptContributor as s, type ToolTransientRetrySetting as t, type AgentIntake as u, type Decision as v, type ToolStepEnvelope as w, ASK_TOOL_DESCRIPTION as x, ASK_TOOL_NAME as y, type AgentCatalogEntry as z };
+export { type HistoryPolicyContext as $, type Actor as A, type AgentApprovalRequest as B, type AgentCatalogEntry as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentHistoryWindow as F, type AgentStreamEvent as G, type HumanReply as H, type InputProcessor as I, type AskToolInput as J, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as K, type LlmStepEnvelope as L, type ModelMessage as M, DEFAULT_INTAKE_PREAMBLE as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as V, type ElicitationOption as W, type ElicitationOutcome as X, type ElicitationQuestion as Y, type ElicitationReply as Z, type ElicitationResult as _, type ToolDefinition as a, type HistorySelection as a0, type HistorySummary as a1, type IncrementalGating as a2, type InvokeWithTransientRetryOptions as a3, MAX_ASK_QUESTIONS as a4, type MessageRole as a5, OutputRejectedError as a6, type OutputVerdict as a7, ProcessorFailedError as a8, type PromptContext as a9, type QuotaView as aa, type ToolCatalogEntry as ab, type ToolConfirmation as ac, type ToolKind as ad, type ToolPresentation as ae, type ToolPresentationTone as af, type ToolResultField as ag, type ToolResultView as ah, type ToolStepCtx as ai, type ToolTransientRetryNumbers as aj, type ToolTransientRetryOptions as ak, askInputSchema as al, askToolDefinition as am, decodeStreamEvent as an, encodeStreamEvent as ao, invokeWithTransientRetry as ap, isTransientToolError as aq, normalizeElicitationReply as ar, renderElicitationAnswers as as, resolveElicitation as at, resolveToolTransientRetryNumbers as au, settleElicitation as av, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type HistoryPolicy as l, type ProcessedPrompt as m, type ModelAnswer as n, type PageContext as o, type AgentDefinition as p, type AgentDelegation as q, type AiToolCtx as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, ASK_TOOL_DESCRIPTION as y, ASK_TOOL_NAME as z };

package/dist/{tool-CL9oEytW.d.ts → tool-Q2rmGeaG.d.ts}

@@ -266,6 +266,282 @@ interface AgentHistoryWindow {
     summarize?: boolean;
 }
 
+/**
+ * The structured live-stream vocabulary carried over the {@link SinkWriter} byte channel.
+ *
+ * The model turn (via the AI-SDK adapter) and the agent loop write these events as NDJSON — one
+ * `JSON.stringify(event)\n` per {@link SinkWriter.write}. The HTTP layer forwards each line as an
+ * SSE `data:` frame, and the client transport maps them back to the AI SDK UI-message chunk
+ * protocol so the browser renders text, reasoning, and tool cards (input + output) LIVE — the same
+ * rich rendering a raw `streamText().toUIMessageStream()` would give, but reconstructed on the
+ * client so the sink stays a format-agnostic byte buffer (durable buffering/replay is untouched).
+ *
+ * Keeping this vocabulary neutral (not AI-SDK `UIMessageChunk`) means core never depends on `ai`:
+ * the adapter owns model-parts → event, the transport owns event → UI-chunk.
+ *
+ * The vocabulary is also a CONTRACT for runners that are not this library's loop: anything that
+ * writes these frames (one JSON object per SSE `data:` line) gets the React transport, transcript
+ * model and hooks for free. Two rules keep it evolvable:
+ *  - every frame is a JSON object with a string `kind`; a reader MUST tolerate kinds it does not
+ *    know (the React transport forwards them as `data-<kind>` parts rather than dropping them);
+ *  - fields are only ever added, and new fields are optional.
+ */
+
+/**
+ * A component the server pushed into the conversation: generative UI that is NOT a tool call's
+ * rendering. It is addressed by `component` (a key in the client's own component registry), never
+ * by a tool name, so a runner can emit one from anywhere — a tool body, a post-processing step, a
+ * sandboxed agent that renders through its own protocol.
+ *
+ * `id` is the component's identity within the message: a second frame with the same `id` REPLACES
+ * the first (streaming props into a chart, flipping a card from "loading" to "ready"), it never
+ * adds a second component.
+ */
+interface AgentUiComponent {
+    id: string;
+    /** Registry key the client resolves to its own renderer, e.g. `data-table`. */
+    component: string;
+    props: Record<string, unknown>;
+    /** Schema version of `props`, so a client can keep rendering components persisted by an older server. */
+    version?: number;
+}
+/**
+ * Who has to settle an action tool call, and until when. Metadata only: the call itself is still
+ * settled through the tool-call approve/reject routes, by its `toolCallId`.
+ */
+interface AgentApprovalRequest {
+    /** The tool call awaiting the decision — the `id` of a call already announced on this stream. */
+    id: string;
+    /**
+     * Who may decide. Open vocabulary the host defines — `'requester'` (the person chatting),
+     * `'admin'`, a role name, a team. A client uses it to say "waiting on an admin" instead of
+     * offering buttons the viewer cannot use.
+     */
+    approver: string;
+    /** ISO-8601 instant after which the request lapses. Absent → it never expires. */
+    expiresAt?: string;
+    /** Why this call needs a person, in words for that person. */
+    reason?: string;
+}
+type AgentStreamEvent = {
+    kind: 'step-start';
+}
+/**
+ * Closes the step opened by the matching `step-start`. Carries the model call's token usage and
+ * `costUsd` (an estimate from the bound pricing store, or `null` when unpriced/unbound — never a
+ * fabricated `0`) so a live client can render running cost without waiting for a thread re-fetch.
+ */
+ | {
+    kind: 'step-finish';
+    usage?: MessageUsage;
+    costUsd?: number | null;
+    /**
+     * How long the model spent thinking in this step, in ms — the same number persisted as
+     * `StoredMessage.reasoningMs`, so a live thread and a reloaded one read the same duration.
+     * Absent when the step had no reasoning.
+     */
+    reasoningMs?: number;
+} | {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'reasoning';
+    text: string;
+}
+/**
+ * `toolKind` collapses `ToolKind`'s `'agent'` into `'read'` — delegation tools auto-execute like a read tool.
+ *
+ * `parentId` nests this call under another call on the same stream: the inner calls a code-mode
+ * `execute` makes, the tools a delegated sub-agent runs. The parent must be announced first. A
+ * call's parent is fixed by its first frame that names one; later frames may omit it.
+ */
+ | {
+    kind: 'tool-input-start';
+    id: string;
+    name: string;
+    toolKind: 'read' | 'action';
+    parentId?: string;
+} | {
+    kind: 'tool-input-delta';
+    id: string;
+    delta: string;
+} | {
+    kind: 'tool-input-available';
+    id: string;
+    name: string;
+    input: unknown;
+    toolKind: 'read' | 'action';
+    /** Same as on `tool-input-start`, for a runner that announces a call without streaming its input. */
+    parentId?: string;
+} | {
+    kind: 'tool-output';
+    id: string;
+    output: unknown;
+} | {
+    kind: 'tool-output-error';
+    id: string;
+    error: string;
+}
+/**
+ * A person was asked to approve an action tool and declined it. Its own frame, NOT
+ * `tool-output-error`: a refusal is a decision with a known outcome — nothing ran — while a
+ * failure is an outcome nobody chose and whose effects are unknown. Rendering them the same way
+ * tells an operator their own "no" was a malfunction. Maps onto the SDK's `output-denied` tool
+ * part state, which a client reads without knowing any tool's name.
+ */
+ | {
+    kind: 'tool-output-denied';
+    id: string;
+    reason?: string;
+}
+/**
+ * The run has put a question set to the user and is parked until someone answers it (or skips).
+ * Written by the LOOP for both elicitation surfaces — the configured intake and the model's `ask`
+ * tool — so a client renders one form either way rather than learning to recognise a tool name.
+ * The matching `tool-output` frame, under the same `id`, carries the settled answers.
+ */
+ | {
+    kind: 'elicitation';
+    id: string;
+    request: ElicitationRequest;
+}
+/**
+ * An action tool call (already announced by `tool-input-start`/`tool-input-available` under the
+ * same `id`) is parked on a person. Optional: a client still treats an `action` call stuck at
+ * its input as pending — this frame adds WHO has to decide and UNTIL WHEN, and moves the call
+ * into the AI SDK's native `approval-requested` state.
+ */
+ | ({
+    kind: 'approval-requested';
+} & AgentApprovalRequest)
+/**
+ * Server-pushed generative UI, positioned in the message where it arrives. Not tied to a tool
+ * call. See {@link AgentUiComponent}.
+ */
+ | ({
+    kind: 'ui';
+} & AgentUiComponent)
+/**
+ * The thread's title was set or changed while this run streamed (typically derived from the
+ * first exchange). Thread-level, not message content: a client updates its header/sidebar and
+ * does not render it in the transcript.
+ */
+ | {
+    kind: 'title';
+    title: string;
+}
+/**
+ * Someone stopped this run. The stream's LAST frame, written by the runner that settled the
+ * cancel, immediately before a normal `end()` — never a `fail()`, because a cancel is not an
+ * error and a client that retries on a failed stream must not retry this.
+ *
+ * A run that simply ends wrote everything it had; one that ends after this frame did not, and the
+ * difference is the whole point: without it a reader cannot tell a truncated answer from a
+ * complete one. Consumers that predate the frame ignore it and see the `end()` they always saw.
+ */
+ | {
+    kind: 'cancelled';
+};
+/** Encode one event as an NDJSON line (`{...}\n`) for {@link SinkWriter.write}. */
+declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
+/**
+ * Read one NDJSON line back, or `null` when the line is not a stream event at all.
+ *
+ * `null` covers a genuinely opaque chunk, not just malformed JSON: the sink is a byte channel, so a
+ * model provider is free to write anything into it and some write bare text. A caller that has to
+ * CLASSIFY a chunk — the output gate, which may only forward what it can prove is not the answer —
+ * treats an unreadable frame as unclassifiable rather than guessing.
+ */
+declare function decodeStreamEvent(line: string): AgentStreamEvent | null;
+
+/**
+ * How a person-facing surface talks about a tool WITHOUT ever naming it. Declared on the server,
+ * beside the tool's input schema, because whoever changes the input is the one who has to re-word
+ * the sentence that mentions it — and a client that shipped its own name-to-sentence map would go
+ * stale the moment a tool was renamed. A tool name is an identifier, never copy.
+ *
+ * `running` / `done` (and `confirm.title`, `confirm.detail`, `result.text`) are templates:
+ * `{dotted.path}` placeholders are filled from the call's INPUT (or, for `result`, its OUTPUT), so one
+ * declaration covers every call the tool will ever receive and replays identically from history.
+ * A placeholder with nothing behind it collapses along with the space before it.
+ */
+interface ToolPresentation {
+    /** Noun phrase, for counts and headings: "Database query", "Knowledge base". */
+    label: string;
+    /** Present progressive, while the call is in flight: "Reading {bucket}". */
+    running: string;
+    /** Settled, once the output is in: "Read {bucket}". */
+    done: string;
+    /** A key into the client's own glyph map (`database`, `search`, …). Unknown keys fall back to a generic glyph there. */
+    icon?: string;
+    /** One line naming what the tool reaches, for when the activity line is opened. */
+    detail?: string;
+    /** `destructive` earns the warning treatment on an approval prompt. */
+    tone?: ToolPresentationTone;
+    /** What a person is being asked to allow when an `action` call parks for approval. */
+    confirm?: ToolConfirmation;
+    /** How the call's OUTPUT reads as content. */
+    result?: ToolResultView;
+}
+type ToolPresentationTone = 'neutral' | 'destructive';
+interface ToolConfirmation {
+    /** "Delete {count} files?" */
+    title: string;
+    /** The button: "Delete". */
+    verb: string;
+    /** A sentence under the title, when the title alone does not say what changes. */
+    detail?: string;
+}
+/** A value read out of a tool's output by dotted path, with the words to put next to it. */
+interface ToolResultField {
+    path: string;
+    label: string;
+    unit?: string;
+}
+/**
+ * How a tool's output reads as content. Every variant names dotted paths into the output rather
+ * than shapes, so a renderer never has to recognise which tool it is drawing: it receives
+ * `{ view, output }` and draws it.
+ */
+type ToolResultView = 
+/** A row of labelled readings — one result, several facets. */
+{
+    kind: 'metrics';
+    fields: ToolResultField[];
+}
+/** `rows` is a path to an array; each column's `path` is read WITHIN a row. */
+ | {
+    kind: 'table';
+    columns: ToolResultField[];
+    rows: string;
+    empty?: string;
+}
+/** `lines` is a path to an array of strings, drawn as a log tail. */
+ | {
+    kind: 'log';
+    lines: string;
+}
+/** One sentence, templated over the output. */
+ | {
+    kind: 'note';
+    text: string;
+}
+/** The output is drawn somewhere else on the screen already (a pushed component, a side panel). */
+ | {
+    kind: 'elsewhere';
+};
+/**
+ * One tool as `GET <base>/tools` reports it: the tools THIS actor may be offered by the chosen agent,
+ * with how each is spoken about. `presentation` is absent for a tool that declared none — a client
+ * then narrates it generically rather than falling back to its name.
+ */
+interface ToolCatalogEntry {
+    /** The wire name tool parts carry (`tool-<name>`) — the key a client looks a call up by. */
+    name: string;
+    kind: ToolKind;
+    presentation?: ToolPresentation;
+}
+
 /**
  * Transient tool-error classification + the retry loop that wraps a tool's own invocation. A
  * classified-transient error (a DB deadlock, a lock-wait timeout, a serialization failure) means
@@ -385,6 +661,11 @@ interface ToolSpec {
     name: string;
     kind: ToolKind;
     description: string;
+    /**
+     * How a person-facing surface talks about this tool (see {@link ToolPresentation}). Never shown
+     * to the model; served to clients by `GET <base>/tools`.
+     */
+    presentation?: ToolPresentation;
     /**
      * Input schema as a [Standard Schema](https://standardschema.dev) — validation-agnostic, so
      * Zod, Valibot, or ArkType all work. The loop validates input via `~standard.validate` before
@@ -750,6 +1031,19 @@ interface StoredMessage {
     usage?: MessageUsage;
     /** The run (turn) that produced this message; absent on a row written before this was recorded. */
     runId?: string;
+    /**
+     * The model's thinking for this step, as it streamed (`reasoning` frames), so a reloaded thread
+     * shows it where the live one did. Absent when the model produced none, or on a row written
+     * before this was recorded.
+     */
+    reasoning?: string;
+    /** How long the model spent thinking in this step, in ms — what a "Thought for 4s" label reads. */
+    reasoningMs?: number;
+    /**
+     * Components the server pushed into this step (`ui` frames), in first-seen order with the last
+     * props for each `id` — a reloaded thread replays them as `data-ui` parts.
+     */
+    ui?: AgentUiComponent[];
     createdAt: string;
 }
 interface ThreadDetail extends ThreadSummary {
@@ -1011,4 +1305,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-export { type IncrementalGating as $, type Actor as A, type AgentHistoryWindow as B, type AskToolInput as C, type DetachedDelivery as D, type ElicitationRequest as E, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as F, DEFAULT_INTAKE_PREAMBLE as G, type HumanReply as H, type InputProcessor as I, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as J, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as K, type LlmStepEnvelope as L, type ModelMessage as M, type ElicitationOption as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, type ElicitationOutcome as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, type ElicitationQuestion as V, type ElicitationReply as W, type ElicitationResult as X, type HistoryPolicyContext as Y, type HistorySelection as Z, type HistorySummary as _, type ToolDefinition as a, type InvokeWithTransientRetryOptions as a0, MAX_ASK_QUESTIONS as a1, type MessageRole as a2, OutputRejectedError as a3, type OutputVerdict as a4, ProcessorFailedError as a5, type PromptContext as a6, type QuotaView as a7, type ToolKind as a8, type ToolStepCtx as a9, type ToolTransientRetryNumbers as aa, type ToolTransientRetryOptions as ab, askInputSchema as ac, askToolDefinition as ad, invokeWithTransientRetry as ae, isTransientToolError as af, normalizeElicitationReply as ag, renderElicitationAnswers as ah, resolveElicitation as ai, resolveToolTransientRetryNumbers as aj, settleElicitation as ak, type ToolCallRequest as b, type MessageUsage as c, type ThreadSummary as d, type ThreadDetail as e, type ToolResult as f, type MessageAttachment as g, type ToolCallStatus as h, type ToolSpec as i, type AgentRunInput as j, type HistoryPolicy as k, type ProcessedPrompt as l, type ModelAnswer as m, type PageContext as n, type AgentDefinition as o, type AgentDelegation as p, type AiToolCtx as q, type PromptBuilder as r, type PromptContributor as s, type ToolTransientRetrySetting as t, type AgentIntake as u, type Decision as v, type ToolStepEnvelope as w, ASK_TOOL_DESCRIPTION as x, ASK_TOOL_NAME as y, type AgentCatalogEntry as z };
+export { type HistoryPolicyContext as $, type Actor as A, type AgentApprovalRequest as B, type AgentCatalogEntry as C, type DetachedDelivery as D, type ElicitationRequest as E, type AgentHistoryWindow as F, type AgentStreamEvent as G, type HumanReply as H, type InputProcessor as I, type AskToolInput as J, DEFAULT_INCREMENTAL_LOOKBACK_CHARS as K, type LlmStepEnvelope as L, type ModelMessage as M, DEFAULT_INTAKE_PREAMBLE as N, type OutputProcessor as O, type ProcessorContext as P, type QuotaState as Q, DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS as R, type StoredMessage as S, type ToolHandler as T, type UsagePurpose as U, DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS as V, type ElicitationOption as W, type ElicitationOutcome as X, type ElicitationQuestion as Y, type ElicitationReply as Z, type ElicitationResult as _, type ToolDefinition as a, type HistorySelection as a0, type HistorySummary as a1, type IncrementalGating as a2, type InvokeWithTransientRetryOptions as a3, MAX_ASK_QUESTIONS as a4, type MessageRole as a5, OutputRejectedError as a6, type OutputVerdict as a7, ProcessorFailedError as a8, type PromptContext as a9, type QuotaView as aa, type ToolCatalogEntry as ab, type ToolConfirmation as ac, type ToolKind as ad, type ToolPresentation as ae, type ToolPresentationTone as af, type ToolResultField as ag, type ToolResultView as ah, type ToolStepCtx as ai, type ToolTransientRetryNumbers as aj, type ToolTransientRetryOptions as ak, askInputSchema as al, askToolDefinition as am, decodeStreamEvent as an, encodeStreamEvent as ao, invokeWithTransientRetry as ap, isTransientToolError as aq, normalizeElicitationReply as ar, renderElicitationAnswers as as, resolveElicitation as at, resolveToolTransientRetryNumbers as au, settleElicitation as av, type ToolCallRequest as b, type MessageUsage as c, type AgentUiComponent as d, type ThreadSummary as e, type ThreadDetail as f, type ToolResult as g, type MessageAttachment as h, type ToolCallStatus as i, type ToolSpec as j, type AgentRunInput as k, type HistoryPolicy as l, type ProcessedPrompt as m, type ModelAnswer as n, type PageContext as o, type AgentDefinition as p, type AgentDelegation as q, type AiToolCtx as r, type PromptBuilder as s, type PromptContributor as t, type ToolTransientRetrySetting as u, type AgentIntake as v, type Decision as w, type ToolStepEnvelope as x, ASK_TOOL_DESCRIPTION as y, ASK_TOOL_NAME as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dudousxd/nestjs-agent-core",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",