@dudousxd/nestjs-agent-core 0.39.0 → 0.41.0

package/README.md

@@ -16,6 +16,13 @@ provider, a store, a sink) against the SPIs.
 import type { ModelProvider, AgentStore, ToolSpec, RolesPolicy } from '@dudousxd/nestjs-agent-core';
 ```
 
+## Component registries and server rendering
+
+Tools support a `present` hook in both functional and decorated class forms. Register custom components per app, share React renderers between web screens and static exports, and generate paginated PNG/PDF tables and charts for your own delivery adapters.
+
+See the [component rendering guide](../../docs/component-rendering.md) for complete examples, schemas, text fallbacks, and capture configuration.
+
+
 ## Key types
 
 - `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.

package/dist/ag-ui/index.cjs

@@ -24,6 +24,7 @@ __export(ag_ui_exports, {
   AG_UI_CUSTOM: () => AG_UI_CUSTOM,
   AG_UI_PROTOCOL_VERSION: () => AG_UI_PROTOCOL_VERSION,
   AgUiEncoder: () => AgUiEncoder,
+  actionProposalDecisionEvents: () => actionProposalDecisionEvents,
   agUiEvents: () => agUiEvents,
   agUiFramesFromNdjson: () => agUiFramesFromNdjson,
   agUiSse: () => agUiSse,
@@ -40,15 +41,21 @@ __export(ag_ui_exports, {
 module.exports = __toCommonJS(ag_ui_exports);
 
 // src/ag-ui/interrupt-id.ts
+var KIND_CODES = {
+  approval: "a",
+  elicitation: "e",
+  proposal: "p"
+};
 var PREFIX = "agora_";
 function encodeInterruptId(address) {
   const compact = [
-    address.kind === "approval" ? "a" : "e",
+    KIND_CODES[address.kind],
     address.parked,
     address.stream,
     address.toolCallId,
     address.position
   ];
+  if (address.kind === "proposal") compact.push(address.proposalId, address.threadId);
   return PREFIX + Buffer.from(JSON.stringify(compact), "utf8").toString("base64url");
 }
 __name(encodeInterruptId, "encodeInterruptId");
@@ -56,17 +63,21 @@ function decodeInterruptId(id) {
   if (typeof id !== "string" || !id.startsWith(PREFIX)) return null;
   try {
     const parsed = JSON.parse(Buffer.from(id.slice(PREFIX.length), "base64url").toString("utf8"));
-    if (!Array.isArray(parsed) || parsed.length !== 5) return null;
-    const [kind, parked, stream, toolCallId, position] = parsed;
-    if (kind !== "a" && kind !== "e" || typeof parked !== "string" || typeof stream !== "string" || typeof toolCallId !== "string" || typeof position !== "number" || !Number.isSafeInteger(position) || position < 0) {
+    if (!Array.isArray(parsed)) return null;
+    const [kind, parked, stream, toolCallId, position, proposalId, threadId] = parsed;
+    if (parsed.length !== (kind === "p" ? 7 : 5) || kind === "p" && (typeof proposalId !== "string" || typeof threadId !== "string") || kind !== "a" && kind !== "e" && kind !== "p" || typeof parked !== "string" || typeof stream !== "string" || typeof toolCallId !== "string" || typeof position !== "number" || !Number.isSafeInteger(position) || position < 0) {
       return null;
     }
     return {
-      kind: kind === "a" ? "approval" : "elicitation",
+      kind: kind === "a" ? "approval" : kind === "e" ? "elicitation" : "proposal",
       parked,
       stream,
       toolCallId,
-      position
+      position,
+      ...kind === "p" ? {
+        proposalId,
+        threadId
+      } : {}
     };
   } catch {
     return null;
@@ -90,6 +101,8 @@ var AG_UI_CUSTOM = {
   elicitation: "agora.elicitation",
   /** `{ usage, costUsd, reasoningMs }` of one model step. */
   stepUsage: "agora.step-usage",
+  /** A proposal decided by a text message or an interrupt resume, with no model run behind it. */
+  actionProposalDecision: "agora.action-proposal-decision",
   /** `{ message }` — input material this producer could not use and dropped. */
   warning: "agora.warning"
 };
@@ -277,6 +290,13 @@ var AgUiEncoder = class {
             ...event.version !== void 0 ? {
               version: event.version
             } : {},
+            // What a client that cannot draw the component shows instead.
+            ...event.fallbackText !== void 0 ? {
+              fallbackText: event.fallbackText
+            } : {},
+            ...event.componentVersions !== void 0 ? {
+              componentVersions: event.componentVersions
+            } : {},
             ...event.toolCallId !== void 0 ? {
               toolCallId: event.toolCallId
             } : {}
@@ -287,10 +307,14 @@ var AgUiEncoder = class {
         const parked = event.runId ?? this.options.streamRunId;
         const toolName = event.toolName ?? call?.name ?? "";
         const input = event.input ?? call?.input ?? null;
+        const proposal = event.target?.kind === "proposal" ? event.target : void 0;
         this.pending.set(event.id, {
-          kind: "approval",
+          kind: proposal !== void 0 ? "proposal" : "approval",
           parked,
           toolCallId: event.id,
+          ...proposal !== void 0 ? {
+            proposalId: proposal.proposalId
+          } : {},
           interrupt: {
             reason: "tool_approval",
             message: event.reason ?? (toolName.length > 0 ? `Approve ${toolName}?` : "Approve?"),
@@ -302,7 +326,10 @@ var AgUiEncoder = class {
             metadata: {
               "agora.toolName": toolName,
               "agora.input": input,
-              "agora.approver": event.approver
+              "agora.approver": event.approver,
+              ...event.target !== void 0 ? {
+                "agora.target": event.target
+              } : {}
             }
           }
         });
@@ -313,6 +340,12 @@ var AgUiEncoder = class {
             toolName,
             input,
             approver: event.approver,
+            ...event.target !== void 0 ? {
+              target: event.target
+            } : {},
+            ...event.confirmation !== void 0 ? {
+              confirmation: event.confirmation
+            } : {},
             ...event.expiresAt !== void 0 ? {
               expiresAt: event.expiresAt
             } : {},
@@ -540,7 +573,11 @@ var AgUiEncoder = class {
         parked: entry.parked,
         stream: this.options.streamRunId,
         toolCallId: entry.toolCallId,
-        position: this.position
+        position: this.position,
+        ...entry.proposalId !== void 0 ? {
+          proposalId: entry.proposalId,
+          threadId: this.options.streamThreadId ?? this.options.threadId
+        } : {}
       }),
       ...entry.interrupt
     }));
@@ -693,6 +730,31 @@ var AgUiEncoder = class {
   }
 };
 
+// src/genui/catalog.ts
+var COMPONENT_NAME = /^[A-Za-z][A-Za-z0-9]{0,63}$/;
+
+// src/genui/capabilities.ts
+function validateUiCapabilities(value) {
+  if (!record(value) || Object.keys(value).some((key) => key !== "components") || !Array.isArray(value.components)) throw new TypeError("Invalid UI capabilities");
+  const seen = /* @__PURE__ */ new Set();
+  const components = value.components.map((component) => {
+    if (!record(component) || Object.keys(component).some((key) => key !== "name" && key !== "version") || typeof component.name !== "string" || !COMPONENT_NAME.test(component.name) || !Number.isSafeInteger(component.version) || Number(component.version) <= 0 || seen.has(component.name)) throw new TypeError("Invalid UI component capability");
+    seen.add(component.name);
+    return {
+      name: component.name,
+      version: Number(component.version)
+    };
+  });
+  return {
+    components
+  };
+}
+__name(validateUiCapabilities, "validateUiCapabilities");
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+__name(record, "record");
+
 // src/ag-ui/input.ts
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -724,6 +786,13 @@ function parseRunInput(body) {
   if (body.context !== void 0 && !Array.isArray(body.context)) {
     return "context must be an array";
   }
+  if (isRecord(body.forwardedProps) && Object.hasOwn(body.forwardedProps, "uiCapabilities")) {
+    try {
+      validateUiCapabilities(body.forwardedProps.uiCapabilities);
+    } catch {
+      return "forwardedProps.uiCapabilities must be valid UI capabilities";
+    }
+  }
   return body;
 }
 __name(parseRunInput, "parseRunInput");
@@ -828,6 +897,9 @@ function readForwardedProps(forwarded) {
   const model = pick("model");
   const persona = pick("persona");
   return {
+    ...Object.hasOwn(forwarded, "uiCapabilities") ? {
+      uiCapabilities: validateUiCapabilities(forwarded.uiCapabilities)
+    } : {},
     ...agent !== void 0 ? {
       agent
     } : {},
@@ -1043,11 +1115,53 @@ async function* agUiFramesFromNdjson(chunks) {
   }
 }
 __name(agUiFramesFromNdjson, "agUiFramesFromNdjson");
+
+// src/ag-ui/proposal-decision.ts
+function actionProposalDecisionEvents(input) {
+  const messageId = `${input.runId}:proposal-decision`;
+  return [
+    {
+      type: "RUN_STARTED",
+      threadId: input.threadId,
+      runId: input.runId,
+      protocolVersion: AG_UI_PROTOCOL_VERSION
+    },
+    {
+      type: "CUSTOM",
+      name: AG_UI_CUSTOM.actionProposalDecision,
+      value: {
+        threadId: input.threadId,
+        proposalDecision: input.proposalDecision
+      }
+    },
+    {
+      type: "TEXT_MESSAGE_START",
+      messageId,
+      role: "assistant"
+    },
+    {
+      type: "TEXT_MESSAGE_CONTENT",
+      messageId,
+      delta: input.text
+    },
+    {
+      type: "TEXT_MESSAGE_END",
+      messageId
+    },
+    {
+      type: "RUN_FINISHED",
+      threadId: input.threadId,
+      runId: input.runId
+    }
+  ];
+}
+__name(actionProposalDecisionEvents, "actionProposalDecisionEvents");
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AG_UI_CUSTOM,
   AG_UI_PROTOCOL_VERSION,
   AgUiEncoder,
+  actionProposalDecisionEvents,
   agUiEvents,
   agUiFramesFromNdjson,
   agUiSse,