@dudousxd/nestjs-agent 1.21.0 → 1.23.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-CwxJDrBM.d.ts}

@@ -1,7 +1,7 @@
-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';
+import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
 import { GenuiCatalogResolver } from './genui/index.js';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -72,6 +72,34 @@ interface AgentDeps {
 }
 declare function utcDay(date?: Date): string;
 
+/**
+ * Something other than this library's loop that runs a turn — what `engine` on
+ * `AgentModule.forRoot` takes. An engine owns the turn end to end (the model calls, the tools, the
+ * context it keeps), and contributes the `AgentRunner` that `AGENT_RUNNER` binds to; everything
+ * around the turn stays the library's: the routes and the stream protocol, threads and the store,
+ * the sink, approvals and answers routed through `AgentService`, the queue and the quota.
+ *
+ * `openCode()` (`@dudousxd/nestjs-agent-opencode`) is the one that ships. An engine replaces the
+ * loop, so the options only the loop reads (`model`, processors, `outputSchema`, `maxSteps`,
+ * `history`, `retrieval`) do nothing under one; `model` becomes optional.
+ */
+interface AgentEngine {
+    /** For logs and diagnostics. */
+    name: string;
+    /** The providers the engine needs, its runner among them. */
+    providers: Provider[];
+    /** The token of the engine's `AgentRunner`, which `AGENT_RUNNER` is bound to. */
+    runner: InjectionToken;
+    /** Providers the app may inject too (the module is global): e.g. what an MCP surface hooks into. */
+    exports?: InjectionToken[];
+    /**
+     * Controllers the engine mounts under the agent's path (e.g. the endpoint its own runtime calls
+     * back into). Not mounted on `surface: 'engine'`, and the module's `guards` are NOT applied: an
+     * engine's controller authenticates its own callers, which are not the app's users.
+     */
+    controllers?: Type<object>[];
+}
+
 /**
  * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
  * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
@@ -98,6 +126,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,18 +274,54 @@ 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.
+     * picker (its catalog is used when `models` is omitted). Required unless an `engine` runs the
+     * turns instead.
      */
-    model: ModelProvider;
+    model?: ModelProvider;
+    /**
+     * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
+     * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
+     * wiring, like `durable` (see {@link AgentEngine}). Omit → the loop, on `model`.
+     */
+    engine?: AgentEngine;
     /**
      * The base prompt of the default agent (and of any `@Agent` that declares none) — a string, or a
      * function of the turn's `{ actor, agentName, pageContext }`. Omit → `'You are a helpful
@@ -509,6 +575,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
     /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
     adapters?: AgentProtocolAdapter[];
+    /**
+     * What runs the turns instead of the loop — see `AgentModuleOptions.engine`. STATIC, like
+     * `durable`: it decides which runner `AGENT_RUNNER` binds, before `useFactory` has resolved.
+     */
+    engine?: AgentEngine;
 }
 
 /**
@@ -729,4 +800,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 AgentEngine as i, type AgentMemoryOptions as j, type QueueSettleOutcome as k, type QueuedTurn as l, type QueuedTurnStarter as m, type QuotaLimits as n, type QuotaWindowLimits as o, defineTool as p, delegateToolName as q, provideAgentTool as r, provideAgentTools as s, utcDay as u };

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

@@ -1,7 +1,7 @@
-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';
+import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
 import { GenuiCatalogResolver } from './genui/index.cjs';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -72,6 +72,34 @@ interface AgentDeps {
 }
 declare function utcDay(date?: Date): string;
 
+/**
+ * Something other than this library's loop that runs a turn — what `engine` on
+ * `AgentModule.forRoot` takes. An engine owns the turn end to end (the model calls, the tools, the
+ * context it keeps), and contributes the `AgentRunner` that `AGENT_RUNNER` binds to; everything
+ * around the turn stays the library's: the routes and the stream protocol, threads and the store,
+ * the sink, approvals and answers routed through `AgentService`, the queue and the quota.
+ *
+ * `openCode()` (`@dudousxd/nestjs-agent-opencode`) is the one that ships. An engine replaces the
+ * loop, so the options only the loop reads (`model`, processors, `outputSchema`, `maxSteps`,
+ * `history`, `retrieval`) do nothing under one; `model` becomes optional.
+ */
+interface AgentEngine {
+    /** For logs and diagnostics. */
+    name: string;
+    /** The providers the engine needs, its runner among them. */
+    providers: Provider[];
+    /** The token of the engine's `AgentRunner`, which `AGENT_RUNNER` is bound to. */
+    runner: InjectionToken;
+    /** Providers the app may inject too (the module is global): e.g. what an MCP surface hooks into. */
+    exports?: InjectionToken[];
+    /**
+     * Controllers the engine mounts under the agent's path (e.g. the endpoint its own runtime calls
+     * back into). Not mounted on `surface: 'engine'`, and the module's `guards` are NOT applied: an
+     * engine's controller authenticates its own callers, which are not the app's users.
+     */
+    controllers?: Type<object>[];
+}
+
 /**
  * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
  * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
@@ -98,6 +126,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,18 +274,54 @@ 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.
+     * picker (its catalog is used when `models` is omitted). Required unless an `engine` runs the
+     * turns instead.
      */
-    model: ModelProvider;
+    model?: ModelProvider;
+    /**
+     * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
+     * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
+     * wiring, like `durable` (see {@link AgentEngine}). Omit → the loop, on `model`.
+     */
+    engine?: AgentEngine;
     /**
      * The base prompt of the default agent (and of any `@Agent` that declares none) — a string, or a
      * function of the turn's `{ actor, agentName, pageContext }`. Omit → `'You are a helpful
@@ -509,6 +575,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
     /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
     adapters?: AgentProtocolAdapter[];
+    /**
+     * What runs the turns instead of the loop — see `AgentModuleOptions.engine`. STATIC, like
+     * `durable`: it decides which runner `AGENT_RUNNER` binds, before `useFactory` has resolved.
+     */
+    engine?: AgentEngine;
 }
 
 /**
@@ -729,4 +800,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 AgentEngine as i, type AgentMemoryOptions as j, type QueueSettleOutcome as k, type QueuedTurn as l, type QueuedTurnStarter as m, type QuotaLimits as n, type QuotaWindowLimits as o, defineTool as p, delegateToolName as q, provideAgentTool as r, provideAgentTools as s, utcDay as u };