@dudousxd/nestjs-agent 1.7.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**:
@@ -179,6 +212,25 @@ provider's default; the id reaches the provider as `ModelTurnArgs.model` for eve
 A model the catalog does not list as available for that actor and agent is refused with `400` —
 when pinned and again on each turn. `staticModelCatalog(view)` wraps a fixed list.
 
+### Budgets: `GET /agent/quota`
+
+`GET /agent/quota` reports `{ windows: [{ period: 'day' | 'month', usedTokens, limitTokens?,
+usedUsd, limitUsd?, resetsAt? }], blocked? }` from a `QuotaProvider`. The default,
+`LedgerQuotaProvider`, reads the usage ledger (day, plus month when the store has `usageBetween`)
+and only reports. Configure it and it also gates sends — a `blocked` report refuses `POST
+/agent/chat` with `429 { code: 'quota_exceeded', period }` before the turn starts:
+
+```ts
+AgentModule.forRoot({
+  // ceilings on the default ledger provider
+  quotaLimits: { day: { tokens: 200_000 }, month: { usd: 20 } },
+  // …or your own budget, e.g. an AI-gateway spend cap:
+  // quotaProvider: { report: async ({ actor }) => myGatewayBudget(actor.id) },
+});
+```
+
+`GET /agent/quota/today` stays as it was.
+
 ### Who approves an action, and for how long
 
 Every `action` tool call waits on the person chatting by default. `approvalPolicy` changes that per

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

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -86,6 +86,42 @@ 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 {
+    tokens?: number;
+    usd?: number;
+}
+/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+interface QuotaLimits {
+    day?: QuotaWindowLimits;
+    month?: QuotaWindowLimits;
+}
+/**
+ * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
+ *
+ * - `day` — always; `usedTokens`/limit come from the bound {@link QuotaStore} when there is one (so
+ *   the report matches what the loop enforces), spend from the ledger.
+ * - `month` — when the store implements `usageBetween`.
+ *
+ * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
+ * `blocked`.
+ */
+declare class LedgerQuotaProvider implements QuotaProvider {
+    private readonly store;
+    private readonly quota?;
+    private readonly limits;
+    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    report(query: QuotaQuery): Promise<QuotaReport>;
+    private dayWindow;
+    private window;
+}
 
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
@@ -205,6 +241,17 @@ interface AgentModuleOptions {
      * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
      */
     models?: ModelCatalog;
+    /**
+     * The actor's budget across windows, for `GET <base>/quota` — and, once set, a gate: a send whose
+     * report comes back `blocked` is refused with `429` before the turn starts. Default: a
+     * {@link LedgerQuotaProvider} over the usage ledger (reporting only, unless `quotaLimits` is set).
+     */
+    quotaProvider?: QuotaProvider;
+    /**
+     * Ceilings for the default ledger provider's windows — `{ day?: { tokens?, usd? }, month?: {
+     * tokens?, usd? } }`. Setting it turns the send gate on. Ignored when `quotaProvider` is given.
+     */
+    quotaLimits?: QuotaLimits;
     /**
      * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
      * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
@@ -479,4 +526,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, 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, delegateToolName as i, 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-CiC5Va9J.d.ts → agent-deps.factory-DuTy1UyU.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
@@ -86,6 +86,42 @@ 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 {
+    tokens?: number;
+    usd?: number;
+}
+/** Per-window ceilings: `AgentModule.forRoot({ quotaLimits })`. */
+interface QuotaLimits {
+    day?: QuotaWindowLimits;
+    month?: QuotaWindowLimits;
+}
+/**
+ * The default {@link QuotaProvider}: windows read off the usage ledger the loop already writes.
+ *
+ * - `day` — always; `usedTokens`/limit come from the bound {@link QuotaStore} when there is one (so
+ *   the report matches what the loop enforces), spend from the ledger.
+ * - `month` — when the store implements `usageBetween`.
+ *
+ * `limits` add ceilings per window (tokens and/or USD). A window that reaches one makes the report
+ * `blocked`.
+ */
+declare class LedgerQuotaProvider implements QuotaProvider {
+    private readonly store;
+    private readonly quota?;
+    private readonly limits;
+    constructor(store: AgentStore, quota?: QuotaStore | undefined, limits?: QuotaLimits);
+    report(query: QuotaQuery): Promise<QuotaReport>;
+    private dayWindow;
+    private window;
+}
 
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
@@ -205,6 +241,17 @@ interface AgentModuleOptions {
      * `ModelTurnArgs.model`. Omit → an empty catalog, and a request naming a model is refused.
      */
     models?: ModelCatalog;
+    /**
+     * The actor's budget across windows, for `GET <base>/quota` — and, once set, a gate: a send whose
+     * report comes back `blocked` is refused with `429` before the turn starts. Default: a
+     * {@link LedgerQuotaProvider} over the usage ledger (reporting only, unless `quotaLimits` is set).
+     */
+    quotaProvider?: QuotaProvider;
+    /**
+     * Ceilings for the default ledger provider's windows — `{ day?: { tokens?, usd? }, month?: {
+     * tokens?, usd? } }`. Setting it turns the send gate on. Ignored when `quotaProvider` is given.
+     */
+    quotaLimits?: QuotaLimits;
     /**
      * Daily per-actor token budget, enforced against the persisted usage ledger by the built-in
      * `LedgerQuotaStore`. A convenience over wiring a {@link QuotaStore} by hand — set this and quotas
@@ -479,4 +526,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, 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, delegateToolName as i, 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 };