@dudousxd/nestjs-agent 1.20.0 → 1.21.0

package/README.md

@@ -405,6 +405,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.ts → chat-queue.service-CGsR40Ct.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, 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 { 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;
@@ -240,6 +244,13 @@ interface AgentMemoryOptions {
     maxFactChars?: number;
 }
 interface AgentModuleOptions {
+    actionApprovalMode?: ActionApprovalMode;
+    backgroundActorResolver?: BackgroundActorResolver;
+    actionProposalWorker?: {
+        pollIntervalMs?: number;
+        leaseMs?: number;
+        maxConcurrency?: number;
+    };
     /**
      * 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 +536,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 +571,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

package/dist/{chat-queue.service-C0hr7dqx.d.cts → chat-queue.service-XG9RQCjU.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, 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 { 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;
@@ -240,6 +244,13 @@ interface AgentMemoryOptions {
     maxFactChars?: number;
 }
 interface AgentModuleOptions {
+    actionApprovalMode?: ActionApprovalMode;
+    backgroundActorResolver?: BackgroundActorResolver;
+    actionProposalWorker?: {
+        pollIntervalMs?: number;
+        leaseMs?: number;
+        maxConcurrency?: number;
+    };
     /**
      * 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 +536,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 +571,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