@dudousxd/nestjs-agent-core 0.16.0 → 0.18.0

package/README.md

@@ -35,6 +35,8 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 - `RunCancelledError` / `AgentLoopHooks.cancelled()` — real cancellation. The loop asks `hooks.cancelled()` at the points where stopping is safe and cheap (between steps, before the next model call, before a turn's tools are dispatched), ALWAYS from inside a checkpoint, so the answer is journaled and a cancel arriving between two replays can never change a branch a replayed position already took; the positions themselves sit behind `hooks.patched('agent:cancellation')`, so a run already in flight keeps its recorded shape. A tool already executing is never interrupted — there is no un-executing a side effect, and abandoning a dispatched step leaves a journal holding a dispatch whose result never lands. Observing a cancel throws `RunCancelledError`, which unwinds through the path a suspend already uses; the RUNNER settles it, recording the run `cancelled` (`AgentStore.recordRunEnd`'s third terminal, never `failed`) and ending the stream on a `{ kind: 'cancelled' }` frame rather than failing it, so a user pressing Stop is not in anybody's error rate.
 - `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.
 - `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-CHIw-aTx.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-CHIw-aTx.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) {
@@ -3534,12 +3635,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 +3829,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 +3895,10 @@ ${block}`;
         await writer.write(encodeStreamEvent({
           kind: "step-finish",
           usage: turn.usage,
-          costUsd
+          costUsd,
+          ...turn.reasoningMs !== void 0 ? {
+            reasoningMs: turn.reasoningMs
+          } : {}
         }));
       });
       break;
@@ -3837,7 +3951,10 @@ ${block}`;
       await writer.write(encodeStreamEvent({
         kind: "step-finish",
         usage: turn.usage,
-        costUsd
+        costUsd,
+        ...turn.reasoningMs !== void 0 ? {
+          reasoningMs: turn.reasoningMs
+        } : {}
       }));
     });
   }
@@ -3992,6 +4109,7 @@ __name(runAgentLoop, "runAgentLoop");
   memoryWriteVerdict,
   normalizeDelegation,
   normalizeElicitationReply,
+  observeTurnFrames,
   offerMemories,
   offerSkills,
   publishAgentDelegated,
@@ -4041,6 +4159,7 @@ __name(runAgentLoop, "runAgentLoop");
   withMemoryTool,
   withSkillTool,
   withToolTimeout,
+  withTurnFrames,
   writeMemory
 });
 //# sourceMappingURL=index.cjs.map