@dudousxd/nestjs-agent-core 0.21.0 → 0.22.0

package/README.md

@@ -18,7 +18,8 @@ import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd
 
 ## Key types
 
-- `ToolSpec` — `{ name, kind: 'read' | 'action' | 'agent', description, inputSchema, roles?, ability?, targetAgent?, detached? }`. (`ToolKind` has three further members — `'ask'`, `'skill'` and `'memory'` — which no `ToolSpec` carries: they belong to the built-in tools the loop serves itself rather than from a handler. `ask` settles against a person, `skill` against the turn's journaled catalog, `remember` against the turn's journaled memory digest.) `inputSchema` is a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType); the loop validates via `~standard.validate`, throwing `ToolInputInvalidError` on failure.
+- `ToolSpec` — `{ name, kind: 'read' | 'action' | 'agent', description, inputSchema, roles?, ability?, targetAgent?, detached?, terminal? }`. (`ToolKind` has three further members — `'ask'`, `'skill'` and `'memory'` — which no `ToolSpec` carries: they belong to the built-in tools the loop serves itself rather than from a handler. `ask` settles against a person, `skill` against the turn's journaled catalog, `remember` against the turn's journaled memory digest.) `inputSchema` is a [Standard Schema](https://standardschema.dev) (Zod, Valibot, ArkType); the loop validates via `~standard.validate`, throwing `ToolInputInvalidError` on failure.
+- `AiToolCtx.emitUi(component, props, { id?, version? })` — **a tool pushes generative UI.** The `ui` frame streams live (inline, durable, and from a dispatched tool step's worker) and the component is persisted on the assistant message through the optional `AgentStore.setMessageUi`, once per step, after the step's tools settle. `id` defaults to `<toolCallId>:ui:<n>`, so a retried call replaces what it pushed. The pushes ride the tool step's journaled result (`wrapToolStepOutput` / `unwrapToolStepOutput`; the wrapper is only used when something was pushed), so a replay neither re-streams nor re-persists them. `ToolSpec.terminal` ends the turn after a successful call, settled in `persist:toolcall` like `detached`.
 - `AgentDefinition` — a named agent (`systemPrompt` string | `PromptBuilder`, `tools`, `delegatesTo`, `personas`, …) for multi-agent setups. `delegatesTo` holds `AgentDelegation` entries: a bare target name for the delegation that waits, `{ agent, detached: true }` for one that does not.
 - `detachedStarted` / `detachedDelivered` / `settleUnsettledDelegation` / `AgentLoopHooks.startAgent` / `AgentRunInput.deliverTo` — **delegation that does not block the chat.** An `agent`-kind call whose spec says `detached` is STARTED rather than awaited (`hooks.startAgent`, which the durable runner maps to `ctx.startChild` and the inline one to a loop nobody awaits), and the turn ends with a `DetachedDelegationReceipt` as the call's result instead of an answer. The started run carries a `deliverTo` address — the delegating thread and the call that started it — and posts its answer there as a message of its own, stamped with its own `runId` and `agentName`, so a client renders "the research agent finished" rather than the assistant's next reply. Whether a call detaches is settled INSIDE `persist:toolcall` alongside its kind and target, never from a live registry lookup, so a replay reads the branch back rather than re-deciding it; the loop writes the same checkpoint names either way, and only the runner's own positions (`spawn:` versus the awaited child's `signal:child:`) differ. A detached run streams into its OWN sink and its `action` tools park on its OWN run, so its approval reaches the pending-approvals surface instead of an inline card in whatever turn happens to be open. `settleUnsettledDelegation` is the runner's half: a run that crashed or was stopped posts a message saying so, because "started" is the one state a reader can neither wait on nor act on. `AgentRunInput.parentRunId` / `RecordRunStartInput.parentRunId` record the edge, so a delegation is not a run row with nothing pointing at it.
 - `RolesPolicy.can(actor, tool): boolean | Promise<boolean>` — the tool authorization seam

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-CwXibnce.cjs';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-BQqFt06V.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-CwXibnce.js';
+import { A as Actor, I as InputProcessor, O as OutputProcessor, T as ToolHandler } from '../tool-BQqFt06V.js';
 import '@standard-schema/spec';
 
 /**

package/dist/index.cjs

@@ -97,6 +97,7 @@ __export(src_exports, {
   compositeSkillProvider: () => compositeSkillProvider,
   createFrameBuffer: () => createFrameBuffer,
   createIncrementalGate: () => createIncrementalGate,
+  createUiCollector: () => createUiCollector,
   dayBoundsUtc: () => dayBoundsUtc,
   decodeStreamEvent: () => decodeStreamEvent,
   defaultCanDecide: () => defaultCanDecide,
@@ -124,6 +125,7 @@ __export(src_exports, {
   mayDecideApproval: () => mayDecideApproval,
   memoryForgetVerdict: () => memoryForgetVerdict,
   memoryWriteVerdict: () => memoryWriteVerdict,
+  mergeUi: () => mergeUi,
   normalizeDelegation: () => normalizeDelegation,
   normalizeElicitationReply: () => normalizeElicitationReply,
   observeTurnFrames: () => observeTurnFrames,
@@ -174,6 +176,7 @@ __export(src_exports, {
   traceLlmTurn: () => traceLlmTurn,
   traceToolExecution: () => traceToolExecution,
   truncateDetailContent: () => truncateDetailContent,
+  unwrapToolStepOutput: () => unwrapToolStepOutput,
   validateElicitationAnswer: () => validateElicitationAnswer,
   validateElicitationValue: () => validateElicitationValue,
   validateStructured: () => validateStructured,
@@ -183,6 +186,7 @@ __export(src_exports, {
   withSkillTool: () => withSkillTool,
   withToolTimeout: () => withToolTimeout,
   withTurnFrames: () => withTurnFrames,
+  wrapToolStepOutput: () => wrapToolStepOutput,
   writeMemory: () => writeMemory
 });
 module.exports = __toCommonJS(src_exports);
@@ -343,6 +347,95 @@ function withTurnFrames(result, frames) {
 }
 __name(withTurnFrames, "withTurnFrames");
 
+// src/tool-ui.ts
+var TOOL_STEP_UI = "@@nestjs-agent/tool-step-ui";
+function wrapToolStepOutput(output, ui) {
+  if (ui.length === 0) {
+    return output;
+  }
+  const wrapped = {
+    [TOOL_STEP_UI]: 1,
+    output,
+    ui: [
+      ...ui
+    ]
+  };
+  return wrapped;
+}
+__name(wrapToolStepOutput, "wrapToolStepOutput");
+function unwrapToolStepOutput(raw) {
+  if (typeof raw === "object" && raw !== null && raw[TOOL_STEP_UI] === 1) {
+    const wrapped = raw;
+    return {
+      output: wrapped.output,
+      ui: Array.isArray(wrapped.ui) ? wrapped.ui : []
+    };
+  }
+  return {
+    output: raw,
+    ui: []
+  };
+}
+__name(unwrapToolStepOutput, "unwrapToolStepOutput");
+function createUiCollector(toolCallId, write) {
+  const pushed = /* @__PURE__ */ new Map();
+  let next = 0;
+  const emit2 = /* @__PURE__ */ __name(async (component, props, options = {}) => {
+    if (typeof component !== "string" || component.length === 0) {
+      throw new Error("emitUi: component must be a non-empty string");
+    }
+    if (typeof props !== "object" || props === null || Array.isArray(props)) {
+      throw new Error("emitUi: props must be a JSON object");
+    }
+    let id = options.id;
+    if (id === void 0) {
+      id = `${toolCallId}:ui:${next}`;
+      next += 1;
+    }
+    const entry = {
+      id,
+      component,
+      // Snapshot: the frame and the persisted value are what the tool pushed at THIS moment, not
+      // whatever the object it handed over looks like when the step settles.
+      props: JSON.parse(JSON.stringify(props)),
+      ...options.version !== void 0 ? {
+        version: options.version
+      } : {},
+      toolCallId
+    };
+    pushed.set(id, entry);
+    await write?.({
+      kind: "ui",
+      ...entry
+    });
+    return {
+      id
+    };
+  }, "emit");
+  return {
+    emit: emit2,
+    components: /* @__PURE__ */ __name(() => [
+      ...pushed.values()
+    ], "components"),
+    restart: /* @__PURE__ */ __name(() => {
+      next = 0;
+    }, "restart")
+  };
+}
+__name(createUiCollector, "createUiCollector");
+function mergeUi(...lists) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const list of lists) {
+    for (const component of list ?? []) {
+      merged.set(component.id, component);
+    }
+  }
+  return [
+    ...merged.values()
+  ];
+}
+__name(mergeUi, "mergeUi");
+
 // src/spi/pricing-store.ts
 async function seedModelPrices(store, prices) {
   for (const price of prices) {
@@ -3357,6 +3450,11 @@ async function claimToolCall(turn, call) {
       ...spec?.detached === true ? {
         detached: true
       } : {},
+      // Same for `terminal`: absent unless declared, so a deployment with no terminal tool writes
+      // the bytes it always has, and a replay reads the branch back instead of re-deciding it.
+      ...spec?.terminal === true ? {
+        terminal: true
+      } : {},
       ...approval !== void 0 ? {
         approval
       } : {}
@@ -3378,6 +3476,9 @@ async function claimToolCall(turn, call) {
     ...persisted?.detached === true ? {
       detached: true
     } : {},
+    ...persisted?.terminal === true ? {
+      terminal: true
+    } : {},
     ...toolType === "action" && persisted?.approval !== void 0 ? {
       approval: persisted.approval
     } : {},
@@ -3544,7 +3645,7 @@ async function invokeClaimedTool(turn, claimed) {
     if (claimed.toolType === "memory") {
       return await rememberIntoTurn(turn, claimed, startedAt);
     }
-    let output;
+    let raw;
     if (hooks.dispatchTool) {
       const stepCtx = {
         actor: input.actor,
@@ -3567,28 +3668,47 @@ async function invokeClaimedTool(turn, claimed) {
         } : {},
         // Numeric-only: the handler applies withToolTimeout AND its own local `classify` — see
         // ToolStepEnvelope.transientRetry.
-        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry)
+        transientRetry: resolveToolTransientRetryNumbers(deps.toolTransientRetry),
+        // The handler hands back what the tool pushed through `ctx.emitUi` with its output.
+        collectUi: true
       };
-      output = await hooks.dispatchTool(resolvedCall, envelope);
+      raw = await hooks.dispatchTool(resolvedCall, envelope);
     } else {
-      const invocation = hooks.step(`tool:${call.id}`, () => traceToolExecution(hooks.runId, {
-        toolCallId: call.id,
-        toolName: call.name,
-        toolType
-      }, () => invokeWithTransientRetry(() => deps.registry.invoke(call.name, call.input, ctx, deps.rolesPolicy), deps.toolTransientRetry ?? {}, {
-        ...hooks.isControlFlowError !== void 0 ? {
-          isControlFlowError: hooks.isControlFlowError
-        } : {},
-        onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
-          publishAgentToolRetry({
-            toolName: call.name,
-            toolCallId: call.id,
-            attempt,
-            message: retryError instanceof Error ? retryError.message : String(retryError)
-          });
-        }, "onRetry")
-      })));
-      output = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+      const invocation = hooks.step(`tool:${call.id}`, async () => {
+        const ui2 = createUiCollector(call.id, (event) => turn.writer.write(encodeStreamEvent(event)));
+        const output2 = await traceToolExecution(hooks.runId, {
+          toolCallId: call.id,
+          toolName: call.name,
+          toolType
+        }, () => invokeWithTransientRetry(() => {
+          ui2.restart();
+          return deps.registry.invoke(call.name, call.input, {
+            ...ctx,
+            emitUi: ui2.emit
+          }, deps.rolesPolicy);
+        }, deps.toolTransientRetry ?? {}, {
+          ...hooks.isControlFlowError !== void 0 ? {
+            isControlFlowError: hooks.isControlFlowError
+          } : {},
+          onRetry: /* @__PURE__ */ __name((attempt, retryError) => {
+            publishAgentToolRetry({
+              toolName: call.name,
+              toolCallId: call.id,
+              attempt,
+              message: retryError instanceof Error ? retryError.message : String(retryError)
+            });
+          }, "onRetry")
+        }));
+        return wrapToolStepOutput(output2, ui2.components());
+      });
+      raw = deps.toolTimeoutMs !== void 0 ? await withToolTimeout(invocation, deps.toolTimeoutMs, call.name) : await invocation;
+    }
+    const { output, ui } = unwrapToolStepOutput(raw);
+    if (ui.length > 0) {
+      turn.toolUi.set(call.id, ui);
+    }
+    if (claimed.terminal === true) {
+      turn.halt.terminal = true;
     }
     return {
       status: "executed",
@@ -4486,6 +4606,10 @@ ${block}`;
       hooks,
       messageId: assistant.id,
       writer,
+      toolUi: /* @__PURE__ */ new Map(),
+      halt: {
+        terminal: false
+      },
       ...skillOffer !== void 0 ? {
         skills: skillOffer
       } : {},
@@ -4518,6 +4642,10 @@ ${block}`;
     assistantMessage.toolResults = settledResults;
     await hooks.step(`stream:tool-outputs:${i}`, async () => {
       await deps.store.setMessageToolResults(assistant.id, settledResults);
+      const toolUi = toolCallsWithKind.flatMap((call) => turnCalls.toolUi.get(call.id) ?? []);
+      if (toolUi.length > 0) {
+        await deps.store.setMessageUi?.(assistant.id, mergeUi(turn.ui, toolUi));
+      }
       for (const result of results) {
         await writer.write(encodeStreamEvent(outputFrame(result)));
       }
@@ -4532,6 +4660,9 @@ ${block}`;
         } : {}
       }));
     });
+    if (turnCalls.halt.terminal) {
+      break;
+    }
   }
   if (history.title === "" || history.title === "New chat") {
     await hooks.step("persist:title", () => deps.store.setTitle(input.threadId, deriveTitle(input.userText)));
@@ -4662,6 +4793,7 @@ __name(runAgentLoop, "runAgentLoop");
   compositeSkillProvider,
   createFrameBuffer,
   createIncrementalGate,
+  createUiCollector,
   dayBoundsUtc,
   decodeStreamEvent,
   defaultCanDecide,
@@ -4689,6 +4821,7 @@ __name(runAgentLoop, "runAgentLoop");
   mayDecideApproval,
   memoryForgetVerdict,
   memoryWriteVerdict,
+  mergeUi,
   normalizeDelegation,
   normalizeElicitationReply,
   observeTurnFrames,
@@ -4739,6 +4872,7 @@ __name(runAgentLoop, "runAgentLoop");
   traceLlmTurn,
   traceToolExecution,
   truncateDetailContent,
+  unwrapToolStepOutput,
   validateElicitationAnswer,
   validateElicitationValue,
   validateStructured,
@@ -4748,6 +4882,7 @@ __name(runAgentLoop, "runAgentLoop");
   withSkillTool,
   withToolTimeout,
   withTurnFrames,
+  wrapToolStepOutput,
   writeMemory
 });
 //# sourceMappingURL=index.cjs.map