@dudousxd/nestjs-agent 1.19.3 → 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-CKZkjlMK.d.ts → chat-queue.service-CGsR40Ct.d.cts}

@@ -1,9 +1,13 @@
-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, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, 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;
@@ -24,6 +28,8 @@ interface AgentDeps {
     maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /** The agent's personas (`@Agent({ personas })`) — read by the loop only for a run that names one. */
+    personas?: Persona[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
     /**
@@ -238,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.
@@ -523,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. */
@@ -534,7 +549,37 @@ declare class AgentDepsFactory {
      */
     defaultAgentName(): string;
     private effectiveTools;
+    /**
+     * The agent a name stands for: itself when it is a registered agent (or unknown — the bare
+     * assistant), else the agent whose persona took the name over (`Persona.aliases`) and that persona.
+     */
+    resolveAgent(name: string): {
+        agentName: string;
+        persona?: string;
+    };
+    /** `agentName`'s personas as a picker reads them. Empty when it declares none. */
+    personaCatalog(agentName: string): PersonaCatalogEntry[];
+    /** The persona `agentName` runs under when nothing names one. Undefined → none. */
+    defaultPersona(agentName: string): string | undefined;
+    /**
+     * The persona a turn of `agentName` runs under, most specific first: the one the send names
+     * (refused with `400 persona_not_found` when the agent does not declare it), else the thread's
+     * pinned one when this agent declares it, else the agent's default. Undefined → none.
+     */
+    resolvePersona(args: {
+        agentName: string;
+        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
+     * has since taken over (`Persona.aliases`) is served. That run names no persona of its own (it
+     * predates them, and its input cannot change), so the persona applies the way the old agent's own
+     * config did: as config, re-read on every replay, with no checkpoint of its own.
+     */
+    private withPersona;
     /**
      * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
      * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
@@ -591,13 +636,14 @@ declare class ChatQueueService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly staging?;
+    private readonly deps?;
     private readonly logger;
     /**
      * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
      * alive whatever the runner says — it simply has not registered the run yet.
      */
     private readonly starting;
-    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined, deps?: AgentDepsFactory | undefined);
     /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
     get supported(): boolean;
     /** The bound store as a queue store, or a 501 naming what is missing. */
@@ -673,6 +719,13 @@ declare class ChatQueueService {
      * waited. An attachment the staging store no longer resolves keeps its stored url.
      */
     private inputFor;
+    /**
+     * The agent and persona a queued message starts as. A message carries the persona its send
+     * resolved; one that carries none — queued before personas existed, or by a host that sets none —
+     * resolves it now, exactly as a send would: an agent name a persona took over, then the thread's
+     * pinned persona, then the agent's default. Never refused here: nobody is waiting on a 400.
+     */
+    private targetFor;
     private freshAttachments;
 }
 

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

@@ -1,9 +1,13 @@
-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, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, 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;
@@ -24,6 +28,8 @@ interface AgentDeps {
     maxAgentAppearances?: number;
     /** Agent-level tool allow-list. Undefined → all tools (after role filtering). */
     toolAllowList?: string[];
+    /** The agent's personas (`@Agent({ personas })`) — read by the loop only for a run that names one. */
+    personas?: Persona[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
     /**
@@ -238,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.
@@ -523,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. */
@@ -534,7 +549,37 @@ declare class AgentDepsFactory {
      */
     defaultAgentName(): string;
     private effectiveTools;
+    /**
+     * The agent a name stands for: itself when it is a registered agent (or unknown — the bare
+     * assistant), else the agent whose persona took the name over (`Persona.aliases`) and that persona.
+     */
+    resolveAgent(name: string): {
+        agentName: string;
+        persona?: string;
+    };
+    /** `agentName`'s personas as a picker reads them. Empty when it declares none. */
+    personaCatalog(agentName: string): PersonaCatalogEntry[];
+    /** The persona `agentName` runs under when nothing names one. Undefined → none. */
+    defaultPersona(agentName: string): string | undefined;
+    /**
+     * The persona a turn of `agentName` runs under, most specific first: the one the send names
+     * (refused with `400 persona_not_found` when the agent does not declare it), else the thread's
+     * pinned one when this agent declares it, else the agent's default. Undefined → none.
+     */
+    resolvePersona(args: {
+        agentName: string;
+        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
+     * has since taken over (`Persona.aliases`) is served. That run names no persona of its own (it
+     * predates them, and its input cannot change), so the persona applies the way the old agent's own
+     * config did: as config, re-read on every replay, with no checkpoint of its own.
+     */
+    private withPersona;
     /**
      * The ceiling on how much of a thread this agent's turns carry, most specific wins: the agent's
      * own `@Agent({ history })`, else a module-wide custom `historyPolicy`, else the module-wide
@@ -591,13 +636,14 @@ declare class ChatQueueService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly staging?;
+    private readonly deps?;
     private readonly logger;
     /**
      * Runs this process claimed a thread for and has not handed to a runner yet. A holder in here is
      * alive whatever the runner says — it simply has not registered the run yet.
      */
     private readonly starting;
-    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined);
+    constructor(store: AgentStore, sink: TokenStreamSink, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, staging?: AttachmentStagingStore | undefined, deps?: AgentDepsFactory | undefined);
     /** Whether the bound store can hold a queue. Without one, a busy thread is not queued. */
     get supported(): boolean;
     /** The bound store as a queue store, or a 501 naming what is missing. */
@@ -673,6 +719,13 @@ declare class ChatQueueService {
      * waited. An attachment the staging store no longer resolves keeps its stored url.
      */
     private inputFor;
+    /**
+     * The agent and persona a queued message starts as. A message carries the persona its send
+     * resolved; one that carries none — queued before personas existed, or by a host that sets none —
+     * resolves it now, exactly as a send would: an agent name a persona took over, then the thread's
+     * pinned persona, then the agent's default. Never refused here: nobody is waiting on a 400.
+     */
+    private targetFor;
     private freshAttachments;
 }