@dudousxd/nestjs-agent 1.20.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
@@ -405,6 +412,57 @@ In anonymous mode the limits apply per browser (each is its own actor).
 
 ### Who approves an action, and for how long
 
+Action handlers can implement an optional read-only `preflight(input, ctx, { phase })`. The
+registry authorizes and validates the input first. `prepare` runs before an approval is requested;
+`execute` rechecks current state inside the tool checkpoint immediately before its side effect.
+Automatic and remembered approvals still run both checks; direct registry and MCP invocations
+run the execution check too.
+
+```ts
+class RemoveSessionsTool implements ToolHandler<{ accountId: string }, { removed: number }> {
+  constructor(private readonly sessions: SessionsService) {}
+
+  async preflight(input: { accountId: string }, ctx: AiToolCtx, { phase }: ToolPreflightOptions): Promise<ToolPreflightResult<{ removed: number }>> {
+    const count = await this.sessions.countForActor(input.accountId, ctx.actor);
+    if (count === 0) return { status: 'completed', output: { removed: 0 } };
+    if (await this.sessions.isLocked(input.accountId)) {
+      return { status: 'denied', reason: 'This account is locked.' };
+    }
+    return {
+      status: 'ready',
+      confirmation: { title: `Remove ${count} sessions?`, verb: 'Remove' },
+    };
+  }
+
+  async execute(input: { accountId: string }, ctx: AiToolCtx) {
+    return this.sessions.removeForActor(input.accountId, ctx.actor, ctx.idempotencyKey);
+  }
+}
+```
+
+`ready` may supply fully resolved `ToolConfirmation` strings (`title`, `verb`, optional `detail`)
+that override the tool's presentation templates for this call, including after a history reload.
+`denied` returns a domain refusal to the model, and `completed` returns an existing result. Both
+skip approval and execution during preparation. A completed terminal action ends the turn.
+A refusal after a person approves preserves that approval while reporting that the mutation did
+not run. An exception becomes a failed tool result. Read tools ignore this hook.
+
+Functional tools use the same handler contract:
+
+```ts
+provideAgentTool({
+  spec: removeSessionsSpec,
+  handler: { preflight: checkSessions, execute: removeSessions },
+});
+```
+
+Preflight must not perform writes or emit UI. Its preparation result is journaled with the existing
+call checkpoint (and, for remote execution, first with the model worker's turn); replay uses that
+result without rerunning the check or changing its approval branch. The execution check is
+journaled inside the existing tool checkpoint. Keep domain checks inside `execute` or an atomic
+transaction as needed: a preflight check cannot eliminate concurrent changes between reads and
+writes, and it does not replace idempotency.
+
 Every `action` tool call waits on the person chatting by default. `approvalPolicy` changes that per
 call:
 

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

@@ -1,9 +1,13 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } 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 { GenuiCatalogResolver } from './genui/index.js';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {
+    resolveUiCatalog?: ResolveToolUiCatalog;
+    actionApprovalMode?: 'blocking' | 'independent';
     model: ModelProvider;
     store: AgentStore;
     registry: ToolRegistry;
@@ -94,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 {
@@ -240,6 +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.
@@ -525,7 +567,9 @@ declare class AgentDepsFactory {
     private readonly pricingStore;
     private readonly skills;
     private readonly memory;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    private readonly uiCatalog?;
+    private readonly uiCatalogResolver?;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined, uiCatalog?: Catalog | undefined, uiCatalogResolver?: GenuiCatalogResolver | undefined);
     /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
     memoryConfig(): MemoryConfig | undefined;
     /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */
@@ -558,6 +602,7 @@ declare class AgentDepsFactory {
         requested?: string;
         threadPersona?: string | null;
     }): string | undefined;
+    forProposal(proposal: ActionProposal, _actor: Actor): AgentDeps;
     forAgent(agentName?: string): AgentDeps;
     /**
      * A persona baked into an agent's deps — how a run journaled under an agent name that a persona
@@ -715,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-C0hr7dqx.d.ts → chat-queue.service-Dx9OsjcF.d.cts}

@@ -1,9 +1,13 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, QuotaProvider, QuotaQuery, QuotaReport, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason, Actor } 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 { GenuiCatalogResolver } from './genui/index.cjs';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
 interface AgentDeps {
+    resolveUiCatalog?: ResolveToolUiCatalog;
+    actionApprovalMode?: 'blocking' | 'independent';
     model: ModelProvider;
     store: AgentStore;
     registry: ToolRegistry;
@@ -94,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 {
@@ -240,6 +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.
@@ -525,7 +567,9 @@ declare class AgentDepsFactory {
     private readonly pricingStore;
     private readonly skills;
     private readonly memory;
-    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined);
+    private readonly uiCatalog?;
+    private readonly uiCatalogResolver?;
+    constructor(options: AgentModuleOptions, model: ModelProvider, store: AgentStore, sink: TokenStreamSink, rolesPolicy: RolesPolicy, registry: ToolRegistry, agents: AgentRegistry, promptContributors: PromptContributor[], pricingStore: AgentPricingStore | undefined, skills: SkillsConfig | undefined, memory: MemoryConfig | undefined, uiCatalog?: Catalog | undefined, uiCatalogResolver?: GenuiCatalogResolver | undefined);
     /** The turn's memory seam, shared with the read-back endpoint. Undefined → memory is not configured. */
     memoryConfig(): MemoryConfig | undefined;
     /** The turn's skills seam, shared with the listing endpoint. Undefined → skills are not configured. */
@@ -558,6 +602,7 @@ declare class AgentDepsFactory {
         requested?: string;
         threadPersona?: string | null;
     }): string | undefined;
+    forProposal(proposal: ActionProposal, _actor: Actor): AgentDeps;
     forAgent(agentName?: string): AgentDeps;
     /**
      * A persona baked into an agent's deps — how a run journaled under an agent name that a persona
@@ -715,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 };