@dudousxd/nestjs-agent-core 0.17.0 → 0.19.0

package/README.md

@@ -36,6 +36,8 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 - `isControlFlowSignal(error)` / `isReplayIntegrityError(error)` — recognize a durable suspend and a checkpoint refusal without importing the durable packages (a `Symbol.for` marker and a class name, respectively). Rethrow both untouched from any `catch` in a workflow body.
 - `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-CL9oEytW.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-CL9oEytW.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

@@ -119,6 +119,7 @@ __export(src_exports, {
   memoryWriteVerdict: () => memoryWriteVerdict,
   normalizeDelegation: () => normalizeDelegation,
   normalizeElicitationReply: () => normalizeElicitationReply,
+  observeTurnFrames: () => observeTurnFrames,
   offerMemories: () => offerMemories,
   offerSkills: () => offerSkills,
   publishAgentDelegated: () => publishAgentDelegated,
@@ -168,6 +169,7 @@ __export(src_exports, {
   withMemoryTool: () => withMemoryTool,
   withSkillTool: () => withSkillTool,
   withToolTimeout: () => withToolTimeout,
+  withTurnFrames: () => withTurnFrames,
   writeMemory: () => writeMemory
 });
 module.exports = __toCommonJS(src_exports);
@@ -229,6 +231,105 @@ function decodeStreamEvent(line) {
 }
 __name(decodeStreamEvent, "decodeStreamEvent");
 
+// src/turn-frames.ts
+function observeTurnFrames(writer, now = Date.now) {
+  const decoder2 = new TextDecoder();
+  let pending = "";
+  let reasoning = "";
+  let reasoningMs = 0;
+  let burstStartedAt;
+  const ui = /* @__PURE__ */ new Map();
+  function closeBurst() {
+    if (burstStartedAt !== void 0) {
+      reasoningMs += Math.max(0, now() - burstStartedAt);
+      burstStartedAt = void 0;
+    }
+  }
+  __name(closeBurst, "closeBurst");
+  function observeLine(line) {
+    if (line.trim().length === 0) {
+      return;
+    }
+    const event = decodeStreamEvent(line);
+    if (event === null) {
+      return;
+    }
+    if (event.kind === "reasoning") {
+      burstStartedAt ??= now();
+      reasoning += event.text;
+      return;
+    }
+    closeBurst();
+    if (event.kind === "ui") {
+      ui.set(event.id, {
+        id: event.id,
+        component: event.component,
+        props: event.props,
+        ...event.version !== void 0 ? {
+          version: event.version
+        } : {}
+      });
+    }
+  }
+  __name(observeLine, "observeLine");
+  function observe(chunk) {
+    pending += decoder2.decode(chunk, {
+      stream: true
+    });
+    let newline = pending.indexOf("\n");
+    while (newline !== -1) {
+      observeLine(pending.slice(0, newline));
+      pending = pending.slice(newline + 1);
+      newline = pending.indexOf("\n");
+    }
+  }
+  __name(observe, "observe");
+  return {
+    writer: {
+      write(chunk) {
+        observe(chunk);
+        return writer.write(chunk);
+      },
+      end: /* @__PURE__ */ __name(() => writer.end(), "end"),
+      fail: /* @__PURE__ */ __name((error) => writer.fail(error), "fail")
+    },
+    summary() {
+      if (pending.length > 0) {
+        observeLine(pending);
+        pending = "";
+      }
+      closeBurst();
+      return {
+        ...reasoning.length > 0 ? {
+          reasoning,
+          reasoningMs: Math.round(reasoningMs)
+        } : {},
+        ...ui.size > 0 ? {
+          ui: [
+            ...ui.values()
+          ]
+        } : {}
+      };
+    }
+  };
+}
+__name(observeTurnFrames, "observeTurnFrames");
+function withTurnFrames(result, frames) {
+  return {
+    ...result,
+    ...result.reasoning === void 0 && frames.reasoning !== void 0 ? {
+      reasoning: frames.reasoning
+    } : {},
+    ...result.reasoningMs === void 0 && frames.reasoningMs !== void 0 ? {
+      reasoningMs: frames.reasoningMs
+    } : {},
+    ...result.ui === void 0 && frames.ui !== void 0 ? {
+      ui: frames.ui
+    } : {}
+  };
+}
+__name(withTurnFrames, "withTurnFrames");
+
 // src/spi/pricing-store.ts
 async function seedModelPrices(store, prices) {
   for (const price of prices) {
@@ -1949,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()
@@ -1957,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 —
@@ -3534,12 +3643,13 @@ ${block}`;
           writer
         }) : void 0;
         const buffer = gateMode === "whole" ? createFrameBuffer() : void 0;
-        const result = stampToolKinds(await traceLlmTurn(hooks.runId, i, () => deps.model.runTurn({
+        const frames = observeTurnFrames(incremental?.writer ?? buffer?.writer ?? writer);
+        const result = stampToolKinds(withTurnFrames(await traceLlmTurn(hooks.runId, i, () => deps.model.runTurn({
           system: prompt.system,
           messages: prompt.messages,
           tools,
-          sink: incremental?.writer ?? buffer?.writer ?? writer
-        })), deps);
+          sink: frames.writer
+        })), frames.summary()), deps);
         if (incremental !== void 0) {
           await incremental.settled();
           const refusal = incremental.rejection();
@@ -3727,6 +3837,15 @@ ${block}`;
       ...input.agentName !== void 0 ? {
         agentName: input.agentName
       } : {},
+      ...turn.reasoning !== void 0 ? {
+        reasoning: turn.reasoning
+      } : {},
+      ...turn.reasoningMs !== void 0 ? {
+        reasoningMs: turn.reasoningMs
+      } : {},
+      ...turn.ui !== void 0 && turn.ui.length > 0 ? {
+        ui: turn.ui
+      } : {},
       ...messageCalls.length > 0 ? {
         toolCalls: messageCalls
       } : {},
@@ -3784,7 +3903,10 @@ ${block}`;
         await writer.write(encodeStreamEvent({
           kind: "step-finish",
           usage: turn.usage,
-          costUsd
+          costUsd,
+          ...turn.reasoningMs !== void 0 ? {
+            reasoningMs: turn.reasoningMs
+          } : {}
         }));
       });
       break;
@@ -3837,7 +3959,10 @@ ${block}`;
       await writer.write(encodeStreamEvent({
         kind: "step-finish",
         usage: turn.usage,
-        costUsd
+        costUsd,
+        ...turn.reasoningMs !== void 0 ? {
+          reasoningMs: turn.reasoningMs
+        } : {}
       }));
     });
   }
@@ -3992,6 +4117,7 @@ __name(runAgentLoop, "runAgentLoop");
   memoryWriteVerdict,
   normalizeDelegation,
   normalizeElicitationReply,
+  observeTurnFrames,
   offerMemories,
   offerSkills,
   publishAgentDelegated,
@@ -4041,6 +4167,7 @@ __name(runAgentLoop, "runAgentLoop");
   withMemoryTool,
   withSkillTool,
   withToolTimeout,
+  withTurnFrames,
   writeMemory
 });
 //# sourceMappingURL=index.cjs.map