@dudousxd/nestjs-agent 1.8.0 → 1.9.0

package/README.md

@@ -70,6 +70,39 @@ tools THIS actor can reach through that agent (the default agent when omitted; `
 one), built by `ToolRegistry.visibleSpecs`, the same gates the model is offered tools through. The
 React package's `useToolCatalog` reads it. The model never sees `presentation`.
 
+### Generative UI
+
+A tool pushes a component into the answer with `ctx.emitUi(component, props)` — always present; a
+no-op where there is no conversation (MCP). To let the MODEL compose UI from a catalog, import
+`AgentGenuiModule` from `@dudousxd/nestjs-agent/genui` next to `AgentModule`:
+
+```ts
+// catalog.ts — isomorphic: the React app imports this same file
+import { defineCatalog, defineComponent } from '@dudousxd/nestjs-agent-core/genui';
+import { BUILTIN_COMPONENTS } from '@dudousxd/nestjs-agent-core/genui/builtins';
+export const catalog = defineCatalog([...BUILTIN_COMPONENTS, DealCard]);
+
+// app.module.ts
+AgentGenuiModule.forRoot({ catalog, mode: 'tree', terminal: true });
+```
+
+It registers the tools (`ui__show_<component>` per component by default, one `ui__render` in `tree`
+mode, plus a generic `ui__show` taking `{ component, props }` with `showTool: true`), validating
+every call against the catalog. Options: `mode`, `terminal`, `treeToolName`, `treeInstructions`,
+`treeLimits`, `namePrefix`, `showTool`, `showInstructions`, `roles`, `presentation`.
+`forRootAsync({ imports, inject, useFactory })` builds them from config. The catalog is injectable
+(`@InjectGenuiCatalog()`, token `GENUI_CATALOG`) and replaceable in a test with
+`overrideProvider(GENUI_CATALOG)` — the tools are built from the injected one.
+
+**Per-request catalogs.** Pass `resolver` (a class, resolved with DI, or an instance) extending
+`GenuiCatalogResolver` — `resolve({ actor, threadId, tenant, agentName }) → Catalog | Promise<Catalog>`
+(`tenant` is `actor.tenantRef`). It is consulted when a call is validated and when a turn's tool list
+is described to the model (the core's `ToolHandler.describe`), so tenant-defined, versioned
+components work without rebuilding tools at boot: the tree tool's and the show tool's descriptions
+and schemas list the tenant's components for that turn, and a pushed component carries the resolved
+definition's `version`. A tenant's own components are reached through the tree tool or
+`showTool: true` — no boot-time tool can name them. Cache inside `resolve` if it costs a round trip.
+
 ### Message attachments
 
 A chat turn attaches a file by **`mediaId` only**:

package/dist/{agent-deps.factory-Cus_RqwJ.d.cts → agent-deps.factory-DuTy1UyU.d.cts}

@@ -86,6 +86,12 @@ interface FunctionalTool {
  */
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
+/**
+ * Registers a LIST of functional tools from one factory — for a producer whose tool count is only
+ * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The
+ * factory's result is branded element by element; `AiToolDiscoveryService` registers each.
+ */
+declare function provideAgentTools(factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>, inject?: FactoryProvider['inject']): Provider;
 
 /** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
 interface QuotaWindowLimits {
@@ -520,4 +526,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTools as k, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-Cus_RqwJ.d.ts → agent-deps.factory-DuTy1UyU.d.ts}

@@ -86,6 +86,12 @@ interface FunctionalTool {
  */
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): Provider;
+/**
+ * Registers a LIST of functional tools from one factory — for a producer whose tool count is only
+ * known once its dependencies resolve (a catalog loaded from config, one tool per entry). The
+ * factory's result is branded element by element; `AiToolDiscoveryService` registers each.
+ */
+declare function provideAgentTools(factory: (...deps: never[]) => readonly FunctionalTool[] | Promise<readonly FunctionalTool[]>, inject?: FactoryProvider['inject']): Provider;
 
 /** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
 interface QuotaWindowLimits {
@@ -520,4 +526,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, LedgerQuotaProvider as L, type QuotaLimits as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QuotaWindowLimits as i, delegateToolName as j, provideAgentTools as k, provideAgentTool as p, utcDay as u };

package/dist/durable/index.cjs

@@ -100,7 +100,14 @@ var AgentRunSteps = class {
     const tools = (0, import_nestjs_agent_core.withMemoryTool)({
       tools: (0, import_nestjs_agent_core.withSkillTool)({
         tools: (0, import_nestjs_agent_core.withAskTool)({
-          tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList),
+          tools: await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList, {
+            ...input.threadId !== void 0 ? {
+              threadId: input.threadId
+            } : {},
+            ...input.agentName !== void 0 ? {
+              agentName: input.agentName
+            } : {}
+          }),
           ask: deps.ask
         }),
         enabled: deps.skills !== void 0
@@ -3497,6 +3504,14 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
       if (instance === null || instance === void 0 || typeof instance !== "object") {
         continue;
       }
+      if (Array.isArray(instance) && instance.length > 0 && instance.every((each) => typeof each === "object" && each !== null && isBrandedFunctionalTool(each))) {
+        for (const tool of instance) {
+          if (this.registerFunctionalTool(tool)) {
+            functional += 1;
+          }
+        }
+        continue;
+      }
       if (isBrandedFunctionalTool(instance)) {
         if (this.registerFunctionalTool(instance)) {
           functional += 1;
@@ -3544,6 +3559,9 @@ var AiToolDiscoveryService = class _AiToolDiscoveryService {
         } : {},
         ...typeof handler.canUse === "function" ? {
           canUse: /* @__PURE__ */ __name((actor) => instance.canUse(actor), "canUse")
+        } : {},
+        ...typeof handler.describe === "function" ? {
+          describe: /* @__PURE__ */ __name((scope) => instance.describe(scope), "describe")
         } : {}
       });
       count += 1;