@dudousxd/nestjs-agent-core 0.18.0 → 0.19.0

package/README.md

@@ -37,6 +37,7 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 - `settleAll(tasks)` / `SettledTask<T>` — the implementation behind the optional `AgentLoopHooks.parallel`, which is how a turn's `read` tool calls run concurrently. It invokes every task synchronously, in list order, before awaiting any of them (so a runner that takes checkpoint positions on the call keeps them in call order), and resolves only once all of them have settled (so a runner that unwinds a turn by throwing never abandons a sibling mid-dispatch). A runner that assigns positions anywhere else simply omits the hook and the loop stays sequential.
 - `AgentStreamEvent` / `encodeStreamEvent` / `decodeStreamEvent` — the live-stream vocabulary (text, reasoning, tool calls with optional `parentId` nesting, `elicitation`, `approval-requested` with `approver`/`expiresAt`, server-pushed `ui` components, `title`, `cancelled`). It is also the contract a runner that is not this loop writes to get the React client for free: see [docs/stream-protocol.md](../../docs/stream-protocol.md). `AgentUiComponent` and `AgentApprovalRequest` are the payload types.
 - `observeTurnFrames` / `withTurnFrames` — what a model turn streamed that its result does not carry: the model's thinking (`reasoning` text, and `reasoningMs` summed over each burst of consecutive reasoning frames) and pushed `ui` components (first-seen order, last props per id). The loop and the dispatched `llm` step wrap the provider's sink with it inside the model checkpoint, so every provider that streams the vocabulary gets reasoning persisted (`StoredMessage.reasoning` / `reasoningMs` / `ui`) and a replay reads the journaled numbers back. A provider may set `ModelTurnResult.reasoning` / `reasoningMs` / `ui` itself; its values win. The step's `reasoningMs` also rides the `step-finish` frame.
+- `ToolPresentation` / `ToolResultView` / `ToolCatalogEntry` — how a person-facing surface talks about a tool without naming it (`ToolSpec.presentation`, set by `@AiTool({ presentation })`; never shown to the model). `ToolRegistry.visibleSpecs(actor, policy, allowList)` returns the whole specs behind the same gates `definitionsFor` applies, which is what `GET /agent/tools` serves.
 - `runAgentLoop(deps, input, hooks)` — the loop; the NestJS package drives it from both runners
 
 ## Guardrails — `@dudousxd/nestjs-agent-core/guardrails`

package/dist/guardrails/index.d.cts

@@ -1,4 +1,4 @@
-import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-CHIw-aTx.cjs';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-Q2rmGeaG.cjs';
 import '@standard-schema/spec';
 
 /**

package/dist/guardrails/index.d.ts

@@ -1,4 +1,4 @@
-import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-CHIw-aTx.js';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-Q2rmGeaG.js';
 import '@standard-schema/spec';
 
 /**

package/dist/index.cjs

@@ -2050,6 +2050,19 @@ var ToolRegistry = class {
   * tool the allow-list has already excluded is a call whose answer nothing reads.
   */
   async definitionsFor(actor, policy, allowedTools) {
+    return (await this.visibleSpecs(actor, policy, allowedTools)).map((spec) => ({
+      name: spec.name,
+      kind: spec.kind,
+      description: spec.description,
+      inputSchema: spec.inputSchema
+    }));
+  }
+  /**
+  * The specs {@link definitionsFor} offers the model, whole — the same four gates (allow-list,
+  * enabled, role, `canUse`) in the same order. For a surface that lists what an actor can reach
+  * (`GET <base>/tools`), which must never disagree with what the model is actually shown.
+  */
+  async visibleSpecs(actor, policy, allowedTools) {
     const pinnedNames = new Set(filterToolsByAllowList(this.allSpecs(), allowedTools).map((spec) => spec.name));
     const pinned = [
       ...this.entries.values()
@@ -2058,12 +2071,7 @@ var ToolRegistry = class {
     const allowedByRole = new Set((await filterToolsByRole(live.map((entry) => entry.spec), actor, policy)).map((spec) => spec.name));
     const roleScoped = live.filter((entry) => allowedByRole.has(entry.spec.name));
     const actorScoped = await filterToolsByCanUse(roleScoped, actor);
-    return actorScoped.map(({ spec }) => ({
-      name: spec.name,
-      kind: spec.kind,
-      description: spec.description,
-      inputSchema: spec.inputSchema
-    }));
+    return actorScoped.map(({ spec }) => spec);
   }
   /**
   * Run a tool. Re-checks that the tool is enabled and that the role allows it (defense-in-depth —