@dudousxd/nestjs-agent 1.21.0 → 1.22.0

package/README.md

@@ -10,6 +10,13 @@ via signals).
 This is the NestJS module — it re-exports the entire `@dudousxd/nestjs-agent-core` surface, so you
 import tools, types, and the module from one place.
 
+## 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.
+
+
 ## Install
 
 ```bash

package/dist/{chat-queue.service-XG9RQCjU.d.ts → chat-queue.service-CTyX_yNr.d.ts}

@@ -1,4 +1,4 @@
-import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
+import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
@@ -98,6 +98,8 @@ declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool,
  * 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;
+/** Author a functional tool with inferred Standard Schema input and domain output. */
+declare const defineTool: typeof createFunctionalTool;
 
 /** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
 interface QuotaWindowLimits {
@@ -244,13 +246,42 @@ interface AgentMemoryOptions {
     maxFactChars?: number;
 }
 interface AgentModuleOptions {
+    /**
+     * How an `action` tool waits for its approval. `'blocking'` (default): the turn parks on the
+     * decision and resumes when it lands. `'independent'`: the call is recorded as an action proposal
+     * and answered at once with a receipt (`{ proposalId, status: 'pending', executed: false }`), the
+     * turn finishes, and a background worker runs the action once it is approved — decided through
+     * `POST <base>/threads/:threadId/action-proposals/:proposalId/approve|reject`, the approval port or
+     * a text command. Needs `backgroundActorResolver` and a store with the proposal capabilities
+     * (both checked at boot). See `docs/independent-approvals.md`.
+     */
     actionApprovalMode?: ActionApprovalMode;
+    /**
+     * Resolves the CURRENT actor (id, tenant, roles) for a proposal's recorded `actorRef`/`tenantRef`
+     * when the worker runs it — there is no request to read an identity from. Return `null` for an
+     * actor that no longer exists or no longer belongs to the tenant; the action then fails rather
+     * than running. Required under `actionApprovalMode: 'independent'`.
+     */
     backgroundActorResolver?: BackgroundActorResolver;
+    /**
+     * Tuning for the worker that runs approved proposals under `actionApprovalMode: 'independent'`
+     * (started with the module unless `surface: 'http'`). `pollIntervalMs` — how often it looks for
+     * queued work, default 1000; `leaseMs` — how long a claim holds before another worker may recover
+     * it, default 30000; `maxConcurrency` — proposals claimed per poll, default 1. All positive
+     * integers, and `pollIntervalMs` must stay below a third of `leaseMs`.
+     */
     actionProposalWorker?: {
         pollIntervalMs?: number;
         leaseMs?: number;
         maxConcurrency?: number;
     };
+    /**
+     * The words a chat message must consist of to approve or reject a proposal by text, and what the
+     * agent answers. English by default (`yes`/`confirm`/`approve`, `no`/`cancel`/`reject`, …); pass
+     * `ptBrActionProposalText` from `@dudousxd/nestjs-agent-core` for Portuguese, or your own — either
+     * part replaces the default it names, field by field.
+     */
+    actionProposalText?: TextActionProposalConfig;
     /**
      * The LLM provider — `aiSdkModel(openai('gpt-5-mini'))`, or `aiSdkModels({ … })` for a model
      * picker (its catalog is used when `models` is omitted). The only required option.
@@ -729,4 +760,4 @@ declare class ChatQueueService {
     private freshAttachments;
 }
 
-export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, delegateToolName as o, provideAgentTool as p, provideAgentTools as q, utcDay as u };
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, defineTool as o, delegateToolName as p, provideAgentTool as q, provideAgentTools as r, utcDay as u };

package/dist/{chat-queue.service-CGsR40Ct.d.cts → chat-queue.service-Dx9OsjcF.d.cts}

@@ -1,4 +1,4 @@
-import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
+import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
@@ -98,6 +98,8 @@ declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool,
  * 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;
+/** Author a functional tool with inferred Standard Schema input and domain output. */
+declare const defineTool: typeof createFunctionalTool;
 
 /** Ceilings for a {@link LedgerQuotaProvider} window. Either, both, or neither. */
 interface QuotaWindowLimits {
@@ -244,13 +246,42 @@ interface AgentMemoryOptions {
     maxFactChars?: number;
 }
 interface AgentModuleOptions {
+    /**
+     * How an `action` tool waits for its approval. `'blocking'` (default): the turn parks on the
+     * decision and resumes when it lands. `'independent'`: the call is recorded as an action proposal
+     * and answered at once with a receipt (`{ proposalId, status: 'pending', executed: false }`), the
+     * turn finishes, and a background worker runs the action once it is approved — decided through
+     * `POST <base>/threads/:threadId/action-proposals/:proposalId/approve|reject`, the approval port or
+     * a text command. Needs `backgroundActorResolver` and a store with the proposal capabilities
+     * (both checked at boot). See `docs/independent-approvals.md`.
+     */
     actionApprovalMode?: ActionApprovalMode;
+    /**
+     * Resolves the CURRENT actor (id, tenant, roles) for a proposal's recorded `actorRef`/`tenantRef`
+     * when the worker runs it — there is no request to read an identity from. Return `null` for an
+     * actor that no longer exists or no longer belongs to the tenant; the action then fails rather
+     * than running. Required under `actionApprovalMode: 'independent'`.
+     */
     backgroundActorResolver?: BackgroundActorResolver;
+    /**
+     * Tuning for the worker that runs approved proposals under `actionApprovalMode: 'independent'`
+     * (started with the module unless `surface: 'http'`). `pollIntervalMs` — how often it looks for
+     * queued work, default 1000; `leaseMs` — how long a claim holds before another worker may recover
+     * it, default 30000; `maxConcurrency` — proposals claimed per poll, default 1. All positive
+     * integers, and `pollIntervalMs` must stay below a third of `leaseMs`.
+     */
     actionProposalWorker?: {
         pollIntervalMs?: number;
         leaseMs?: number;
         maxConcurrency?: number;
     };
+    /**
+     * The words a chat message must consist of to approve or reject a proposal by text, and what the
+     * agent answers. English by default (`yes`/`confirm`/`approve`, `no`/`cancel`/`reject`, …); pass
+     * `ptBrActionProposalText` from `@dudousxd/nestjs-agent-core` for Portuguese, or your own — either
+     * part replaces the default it names, field by field.
+     */
+    actionProposalText?: TextActionProposalConfig;
     /**
      * The LLM provider — `aiSdkModel(openai('gpt-5-mini'))`, or `aiSdkModels({ … })` for a model
      * picker (its catalog is used when `models` is omitted). The only required option.
@@ -729,4 +760,4 @@ declare class ChatQueueService {
     private freshAttachments;
 }
 
-export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, delegateToolName as o, provideAgentTool as p, provideAgentTools as q, utcDay as u };
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, defineTool as o, delegateToolName as p, provideAgentTool as q, provideAgentTools as r, utcDay as u };