@dudousxd/nestjs-agent 1.8.0 → 1.10.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**:
@@ -122,6 +155,111 @@ minted per turn by `resolve`), bounded to `ATTACHMENT_PAGE_SIZE`, and rides the
 `attachments: { upload: true }` flag. It takes no `threadId` filter: a thread's attachments already
 ride on its messages in `GET /agent/threads/:id`.
 
+### Attachments on nestjs-media (`@dudousxd/nestjs-agent/media`)
+
+A ready `AGENT_ATTACHMENT_STAGING` backed by [`@dudousxd/nestjs-media`](https://davidecarvalho.github.io/aviary/docs/media),
+with resumable (tus) uploads. `@dudousxd/nestjs-media` is an **optional** peer: only this subpath
+imports it, and nothing on the root entry needs it.
+
+Minimal — next to a `MediaModule` that has `store`, `uploadSessions` and `tus`:
+
+```ts
+@Module({
+  imports: [
+    MediaModule.forRoot({ /* disks, store, uploadSessions, tus */ }),
+    AgentModule.forRoot({ /* … */ }),
+    AgentMediaAttachmentsModule.forRoot(), // ← the whole integration
+  ],
+})
+// main.ts — nestjs-media's own requirement for tus PATCH bodies:
+app.useBodyParser('raw', { type: 'application/offset+octet-stream' });
+```
+
+Everything is overridable when you need it:
+
+```ts
+AgentMediaAttachmentsModule.forRoot({
+  maxBytes: 50 * 1024 * 1024,
+  allowedContentTypes: ['image/png', 'image/jpeg', 'application/pdf'],
+  collection: 'chat-files',
+  canAccess: ({ allowed, actor }) => allowed || actor.roles?.includes('support') === true,
+  resolveUrl: (record) => signMyProxyUrl(record.id), // instead of presign / public / inline
+  indexForRag: true, // see below
+  guards: [SessionGuard],
+});
+```
+
+Each attachment is a media record (`ownerType: 'agent-actor'`, `ownerId: actor.id`, collection
+`agent-attachments`). The upload never goes through the agent:
+
+| Step | Route | Who serves it |
+| --- | --- | --- |
+| 1. open | `POST /agent/attachments/uploads` `{ filename, contentType, size }` → `{ mediaId, uploadId, location }` | agent — validates type/size and opens a tus session the actor owns |
+| 2. bytes | `PATCH <location>` (tus, chunked, resumable) | **nestjs-media** |
+| 3. complete | `POST /agent/attachments/uploads/:mediaId/complete` → `MessageAttachment` | agent — checks the bytes landed at the declared size |
+| drop | `DELETE /agent/attachments/uploads/:mediaId` | agent — aborts the session, deletes bytes + record |
+
+`@dudousxd/nestjs-agent-react/media` drives all three for `useAttachments`. `POST /agent/attachments`
+(the buffered multipart route, `attachments: { upload: true }`) keeps working on the same store — its
+`stage()` writes a media record too — but it is not needed with this module; `GET
+/agent/attachments` lists either kind.
+
+`resolve` hands the model provider a presigned url when the disk can mint one (`urlExpiresInSeconds`,
+default 7 days), the disk's public `url()` with `visibility: 'public'`, or — on a disk that can do
+neither, such as local disk in development — the bytes inline as a `data:` url (logged once; that
+url is persisted with the message). `resolveUrl(record, { disk })` takes over entirely. The actor may
+use media they own, and media a message in one of their own threads already carries; anything else
+resolves `null` (`403` on the chat route).
+
+Cleanup: an upload abandoned half-way is already a record, so it shows up in `list` and ages into
+`collectableAttachments`. Delete through the store so the tus session is aborted too:
+
+```ts
+const media = app.get(MediaAttachmentStaging);
+for (const entry of await agents.collectableAttachments(actor, { olderThan })) {
+  await media.remove(entry.mediaId);
+}
+```
+
+`indexForRag: true` announces every ready attachment on `aviary:media:attach` (and its removal on
+`aviary:media:delete`) so `@dudousxd/nestjs-agent-rag-media` indexes it. Off by default — only turn
+it on where retrieval is filtered by owner (`FilteredRetriever` on `ownerType`/`ownerId`), and
+restrict rag-media's `collections` accordingly.
+
+`forRootAsync({ imports, inject, useFactory, path, guards })` takes the same options; `path` must
+match `AgentModule`'s `path` (default `agent`), and `guards` gates the upload routes.
+
+### Bring your own storage
+
+Nothing requires nestjs-media. Bind your own `AttachmentStagingStore` and upload however you like:
+
+```ts
+@Injectable()
+export class S3Staging implements AttachmentStagingStore {
+  async stage({ data, filename, contentType, actor }: StageAttachmentInput) {
+    const mediaId = randomUUID();
+    await this.s3.put(`chat/${actor.id}/${mediaId}`, data, { contentType });
+    await this.db.insert(files).values({ mediaId, owner: actor.id, filename, contentType });
+    return { mediaId, url: '', contentType, name: filename };
+  }
+  async resolve({ mediaId, actor }: ResolveAttachmentInput) {
+    const row = await this.db.query.files.findFirst({ where: eq(files.mediaId, mediaId) });
+    if (!row || row.owner !== actor.id) return null; // unknown and foreign look the same
+    const url = await this.s3.presign(`chat/${actor.id}/${mediaId}`, 3600);
+    return { mediaId, url, contentType: row.contentType, name: row.filename };
+  }
+}
+
+// alongside AgentModule, in a @Global() module (or any module AgentModule can see):
+{ provide: AGENT_ATTACHMENT_STAGING, useClass: S3Staging }
+```
+
+Then either set `attachments: { upload: true }` for the built-in `POST /agent/attachments` (which
+calls your `stage`), or upload through your own route and give the React side your own `upload`
+(`useAttachments({ upload })` / a backend's `uploadAttachment`) that resolves to a `{ mediaId, … }`
+your `resolve` recognises. `list` is optional and only needed for `GET /agent/attachments` and
+sweeping.
+
 ### Who may read a run
 
 `GET /agent/chat/:runId/stream` and `POST /agent/chat/:runId/cancel` both resolve the acting actor

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;