@dudousxd/nestjs-agent-core 0.18.0 → 0.19.0

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

@@ -454,6 +454,94 @@ declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
  */
 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
@@ -573,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
@@ -1212,4 +1305,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-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 ToolKind as ab, type ToolStepCtx as ac, type ToolTransientRetryNumbers as ad, type ToolTransientRetryOptions as ae, askInputSchema as af, askToolDefinition as ag, decodeStreamEvent as ah, encodeStreamEvent as ai, invokeWithTransientRetry as aj, isTransientToolError as ak, normalizeElicitationReply as al, renderElicitationAnswers as am, resolveElicitation as an, resolveToolTransientRetryNumbers as ao, settleElicitation as ap, 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 };
+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-CHIw-aTx.d.ts → tool-Q2rmGeaG.d.ts}

@@ -454,6 +454,94 @@ declare function encodeStreamEvent(event: AgentStreamEvent): Uint8Array;
  */
 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
@@ -573,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
@@ -1212,4 +1305,4 @@ interface ToolHandler<I = unknown> {
     canUse?(actor: Actor): boolean | Promise<boolean>;
 }
 
-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 ToolKind as ab, type ToolStepCtx as ac, type ToolTransientRetryNumbers as ad, type ToolTransientRetryOptions as ae, askInputSchema as af, askToolDefinition as ag, decodeStreamEvent as ah, encodeStreamEvent as ai, invokeWithTransientRetry as aj, isTransientToolError as ak, normalizeElicitationReply as al, renderElicitationAnswers as am, resolveElicitation as an, resolveToolTransientRetryNumbers as ao, settleElicitation as ap, 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 };
+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.18.0",
+  "version": "0.19.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/DavideCarvalho/nestjs-agent.git",