@dudousxd/nestjs-agent 1.19.3 → 1.21.0

package/dist/index.d.cts

@@ -1,17 +1,58 @@
-import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CKZkjlMK.cjs';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-CKZkjlMK.cjs';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CGsR40Ct.cjs';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-CGsR40Ct.cjs';
+import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
+import { AgentStore, Actor, ListActionProposals, ActionProposalMutationResult, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
+import { UiCapabilities } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import './genui/index.cjs';
 
 declare class AgentModule {
     static forRoot(options: AgentModuleOptions): DynamicModule;
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+declare class ActionProposalService {
+    private readonly store;
+    private readonly options;
+    constructor(store: AgentStore, options: Pick<AgentModuleOptions, 'approvalPolicy'>);
+    private capability;
+    private scope;
+    private mayDecide;
+    listPage(threadId: string, actor: Actor, query?: Pick<ListActionProposals, 'after'>): Promise<{
+        next?: {
+            createdAt: number;
+            id: string;
+        };
+        items: _dudousxd_nestjs_agent_core.ActionProposal[];
+    }>;
+    list(threadId: string, actor: Actor): Promise<_dudousxd_nestjs_agent_core.ActionProposal[]>;
+    decide(threadId: string, proposalId: string, actor: Actor, command: {
+        decision: 'approved' | 'rejected';
+        remember?: boolean;
+        reason?: string;
+        via?: string;
+    }): Promise<ActionProposalMutationResult>;
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: ActionProposalMutationResult;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
+    private textReceipt;
+}
+
 /**
  * What a send does when its thread already has a turn running:
  *  - `'auto'` (default) — run now when the thread is idle, else wait in the thread's queue.
@@ -39,12 +80,24 @@ type ChatSendResult = {
     runId: string;
     threadId: string;
     queued?: undefined;
-} | QueuedSend;
+} | QueuedSend | {
+    threadId: string;
+    proposalDecision: unknown;
+    text: string;
+    queued?: undefined;
+};
 interface ChatParams {
+    uiCapabilities?: UiCapabilities;
     actor: Actor;
     message: string;
     threadId?: string;
     agentName?: string;
+    /**
+     * Run this turn under one of the agent's personas (`@Agent({ personas })`), and pin it on the
+     * thread so later sends that name none keep it. Refused (400 `persona_not_found`) unless the agent
+     * declares it. Omitted → the thread's pinned persona, else the agent's `defaultPersona`, else none.
+     */
+    personaId?: string;
     /**
      * Files attached to this message (image/PDF) for a vision-capable model, named by the `mediaId`
      * the upload returned. Only the id is read: the url, content type and name are resolved from the
@@ -97,7 +150,22 @@ declare class AgentService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly queue?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, queue?: ChatQueueService | undefined);
+    private readonly proposals?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota" | "actionApprovalMode"> | undefined, queue?: ChatQueueService | undefined, proposals?: ActionProposalService | undefined);
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: _dudousxd_nestjs_agent_core.ActionProposalMutationResult;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
     /** The queue service when the bound store can hold a queue, else `undefined`. */
     private queueing;
     /** The queue service, or a 501 naming what is missing. */
@@ -143,7 +211,9 @@ declare class AgentService {
      * Send a message: start a turn, or — when its thread already has one running — queue the message
      * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
      */
-    send(params: ChatParams): Promise<ChatSendResult>;
+    send(params: ChatParams, sendOptions?: {
+        textDecisions?: boolean;
+    }): Promise<ChatSendResult>;
     /**
      * Start a turn the thread is already claimed for, under the claimed id. A runner that minted an
      * id of its own anyway gets the thread re-pointed at it; one that fails to start frees the thread.
@@ -293,6 +363,13 @@ declare class AgentService {
      * dropping the field.
      */
     updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The persona this send runs under — see {@link AgentDepsFactory.resolvePersona}. The thread's
+     * pinned persona is read only when the send names none AND the agent has personas to pick from.
+     */
+    private resolvePersona;
+    /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+    private pinThreadPersona;
     private validateTitle;
     /**
      * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
@@ -479,7 +556,24 @@ declare function agUiAdapter(options?: AgUiAdapterOptions): AgentProtocolAdapter
  */
 declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     private readonly agent;
-    constructor(agent: AgentService);
+    private readonly proposals?;
+    constructor(agent: AgentService, proposals?: ActionProposalService | undefined);
+    approveActionProposal(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        remember?: boolean;
+        decidedVia?: string;
+    }): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+    rejectActionProposal(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        reason?: string;
+        decidedVia?: string;
+    }): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
     approve(toolCallId: string, opts?: {
         executedByRef?: string;
         remember?: boolean;
@@ -492,6 +586,19 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
+/**
+ * A store that can answer a thread's pinned persona on its own, without materializing the thread —
+ * probed structurally, like `ThreadDefaultAgentReader`.
+ */
+interface ThreadPersonaReader {
+    personaForThread(threadId: string): Promise<string | null>;
+}
+/**
+ * The thread's pinned persona: one column when the store projects it ({@link ThreadPersonaReader}),
+ * else through the full read.
+ */
+declare function threadPersona(store: AgentStore, threadId: string): Promise<string | null>;
+
 /**
  * How many entries `GET /agent/attachments` returns. Fixed rather than caller-supplied: this route
  * exists so a composer can show the files someone has uploaded, and a host that needs real paging
@@ -555,6 +662,7 @@ declare class ConfigController {
 
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
+    replacementKey?: ToolSpec['replacementKey'];
     /**
      * What the model calls it. Omit → the class name, camelCased, with a trailing `Tool` dropped
      * (`GetWeatherTool` → `getWeather`).
@@ -744,6 +852,20 @@ interface AgentOptions {
      * module-wide setting.
      */
     ask?: boolean;
+    /**
+     * Named variants of THIS agent — a prompt and, optionally, a narrower tool allow-list — that a
+     * caller picks per send (`POST <base>/chat { persona }`) and that pin onto the thread. Everything
+     * else (model, access rules, handoffs, history) stays this agent's; a variant that needs those to
+     * differ is another `@Agent`.
+     *
+     * A persona's `systemPrompt` is static data. For a prompt built from injected services, leave it
+     * out and branch on `ctx.persona` in this class's `@SystemPrompt()` method instead.
+     *
+     * Omit → no personas, and nothing about a turn changes.
+     */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Omit → none. */
+    defaultPersona?: string;
 }
 declare const AGENT_METADATA: unique symbol;
 /** Marks a provider class as an agent. See {@link AgentOptions}. */
@@ -849,6 +971,12 @@ declare class AgentDiscoveryService implements OnModuleInit {
     onModuleInit(): void;
     /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
     private definitionFrom;
+    /**
+     * Refuse to boot on a persona declaration that could only fail later, per request: a default that
+     * names no persona, an id declared twice, an alias two personas claim, or an alias that is a real
+     * agent's name (which would never be reached — a registered agent always wins).
+     */
+    private assertPersonas;
     /**
      * Resolve each handoff entry to an {@link AgentDelegation} — its target's registered name, plus
      * whether that edge detaches (skipping non-agent classes). A bare name is kept for a plain edge
@@ -1288,4 +1416,24 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+declare class ActionProposalController {
+    private readonly proposals;
+    private readonly actors;
+    constructor(proposals: ActionProposalService, actors: ActorResolver);
+    list(threadId: string, request: Request, cursor: unknown, response: Response): Promise<_dudousxd_nestjs_agent_core.ActionProposal[]>;
+    approve(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+    reject(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+}
+
+declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
+    private readonly store;
+    private readonly options;
+    private readonly deps;
+    private worker;
+    private readonly logger;
+    constructor(store: AgentStore, options: AgentModuleOptions, deps: AgentDepsFactory);
+    onModuleInit(): void;
+    onModuleDestroy(): Promise<void>;
+}
+
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, type ThreadPersonaReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };

package/dist/index.d.ts

@@ -1,17 +1,58 @@
-import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CKZkjlMK.js';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-CKZkjlMK.js';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-XG9RQCjU.js';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, j as QueueSettleOutcome, k as QueuedTurn, l as QueuedTurnStarter, m as QuotaLimits, n as QuotaWindowLimits, o as delegateToolName, p as provideAgentTool, q as provideAgentTools, u as utcDay } from './chat-queue.service-XG9RQCjU.js';
+import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
+import { AgentStore, Actor, ListActionProposals, ActionProposalMutationResult, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
+import { UiCapabilities } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
+import './genui/index.js';
 
 declare class AgentModule {
     static forRoot(options: AgentModuleOptions): DynamicModule;
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+declare class ActionProposalService {
+    private readonly store;
+    private readonly options;
+    constructor(store: AgentStore, options: Pick<AgentModuleOptions, 'approvalPolicy'>);
+    private capability;
+    private scope;
+    private mayDecide;
+    listPage(threadId: string, actor: Actor, query?: Pick<ListActionProposals, 'after'>): Promise<{
+        next?: {
+            createdAt: number;
+            id: string;
+        };
+        items: _dudousxd_nestjs_agent_core.ActionProposal[];
+    }>;
+    list(threadId: string, actor: Actor): Promise<_dudousxd_nestjs_agent_core.ActionProposal[]>;
+    decide(threadId: string, proposalId: string, actor: Actor, command: {
+        decision: 'approved' | 'rejected';
+        remember?: boolean;
+        reason?: string;
+        via?: string;
+    }): Promise<ActionProposalMutationResult>;
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: ActionProposalMutationResult;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
+    private textReceipt;
+}
+
 /**
  * What a send does when its thread already has a turn running:
  *  - `'auto'` (default) — run now when the thread is idle, else wait in the thread's queue.
@@ -39,12 +80,24 @@ type ChatSendResult = {
     runId: string;
     threadId: string;
     queued?: undefined;
-} | QueuedSend;
+} | QueuedSend | {
+    threadId: string;
+    proposalDecision: unknown;
+    text: string;
+    queued?: undefined;
+};
 interface ChatParams {
+    uiCapabilities?: UiCapabilities;
     actor: Actor;
     message: string;
     threadId?: string;
     agentName?: string;
+    /**
+     * Run this turn under one of the agent's personas (`@Agent({ personas })`), and pin it on the
+     * thread so later sends that name none keep it. Refused (400 `persona_not_found`) unless the agent
+     * declares it. Omitted → the thread's pinned persona, else the agent's `defaultPersona`, else none.
+     */
+    personaId?: string;
     /**
      * Files attached to this message (image/PDF) for a vision-capable model, named by the `mediaId`
      * the upload returned. Only the id is read: the url, content type and name are resolved from the
@@ -97,7 +150,22 @@ declare class AgentService {
     private readonly quotaProvider?;
     private readonly options?;
     private readonly queue?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota"> | undefined, queue?: ChatQueueService | undefined);
+    private readonly proposals?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota" | "actionApprovalMode"> | undefined, queue?: ChatQueueService | undefined, proposals?: ActionProposalService | undefined);
+    handleTextDecision(threadId: string, actor: Actor, text: string): Promise<{
+        status: "unmatched";
+    } | {
+        threadId: string;
+        proposalDecision: _dudousxd_nestjs_agent_core.ActionProposalMutationResult;
+        text: string;
+    } | {
+        threadId: string;
+        proposalDecision: {
+            status: "ambiguous";
+            proposalIds: string[];
+        };
+        text: string;
+    }>;
     /** The queue service when the bound store can hold a queue, else `undefined`. */
     private queueing;
     /** The queue service, or a 501 naming what is missing. */
@@ -143,7 +211,9 @@ declare class AgentService {
      * Send a message: start a turn, or — when its thread already has one running — queue the message
      * to run after it (see {@link ChatSendMode}). What `POST <base>/chat` calls.
      */
-    send(params: ChatParams): Promise<ChatSendResult>;
+    send(params: ChatParams, sendOptions?: {
+        textDecisions?: boolean;
+    }): Promise<ChatSendResult>;
     /**
      * Start a turn the thread is already claimed for, under the claimed id. A runner that minted an
      * id of its own anyway gets the thread re-pointed at it; one that fails to start frees the thread.
@@ -293,6 +363,13 @@ declare class AgentService {
      * dropping the field.
      */
     updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    /**
+     * The persona this send runs under — see {@link AgentDepsFactory.resolvePersona}. The thread's
+     * pinned persona is read only when the send names none AND the agent has personas to pick from.
+     */
+    private resolvePersona;
+    /** Pin `persona` on the thread when it is not already — a no-op on a store that cannot. */
+    private pinThreadPersona;
     private validateTitle;
     /**
      * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
@@ -479,7 +556,24 @@ declare function agUiAdapter(options?: AgUiAdapterOptions): AgentProtocolAdapter
  */
 declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     private readonly agent;
-    constructor(agent: AgentService);
+    private readonly proposals?;
+    constructor(agent: AgentService, proposals?: ActionProposalService | undefined);
+    approveActionProposal(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        remember?: boolean;
+        decidedVia?: string;
+    }): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+    rejectActionProposal(actor: Actor, target: {
+        kind: 'proposal';
+        threadId: string;
+        proposalId: string;
+    }, opts?: {
+        reason?: string;
+        decidedVia?: string;
+    }): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
     approve(toolCallId: string, opts?: {
         executedByRef?: string;
         remember?: boolean;
@@ -492,6 +586,19 @@ declare class AgentApprovalPortAdapter implements AgentApprovalPort {
     }): Promise<void>;
 }
 
+/**
+ * A store that can answer a thread's pinned persona on its own, without materializing the thread —
+ * probed structurally, like `ThreadDefaultAgentReader`.
+ */
+interface ThreadPersonaReader {
+    personaForThread(threadId: string): Promise<string | null>;
+}
+/**
+ * The thread's pinned persona: one column when the store projects it ({@link ThreadPersonaReader}),
+ * else through the full read.
+ */
+declare function threadPersona(store: AgentStore, threadId: string): Promise<string | null>;
+
 /**
  * How many entries `GET /agent/attachments` returns. Fixed rather than caller-supplied: this route
  * exists so a composer can show the files someone has uploaded, and a host that needs real paging
@@ -555,6 +662,7 @@ declare class ConfigController {
 
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
+    replacementKey?: ToolSpec['replacementKey'];
     /**
      * What the model calls it. Omit → the class name, camelCased, with a trailing `Tool` dropped
      * (`GetWeatherTool` → `getWeather`).
@@ -744,6 +852,20 @@ interface AgentOptions {
      * module-wide setting.
      */
     ask?: boolean;
+    /**
+     * Named variants of THIS agent — a prompt and, optionally, a narrower tool allow-list — that a
+     * caller picks per send (`POST <base>/chat { persona }`) and that pin onto the thread. Everything
+     * else (model, access rules, handoffs, history) stays this agent's; a variant that needs those to
+     * differ is another `@Agent`.
+     *
+     * A persona's `systemPrompt` is static data. For a prompt built from injected services, leave it
+     * out and branch on `ctx.persona` in this class's `@SystemPrompt()` method instead.
+     *
+     * Omit → no personas, and nothing about a turn changes.
+     */
+    personas?: Persona[];
+    /** The persona a send runs under when neither it nor its thread names one. Omit → none. */
+    defaultPersona?: string;
 }
 declare const AGENT_METADATA: unique symbol;
 /** Marks a provider class as an agent. See {@link AgentOptions}. */
@@ -849,6 +971,12 @@ declare class AgentDiscoveryService implements OnModuleInit {
     onModuleInit(): void;
     /** Build the internal {@link AgentDefinition} from an `@Agent` instance and its options. */
     private definitionFrom;
+    /**
+     * Refuse to boot on a persona declaration that could only fail later, per request: a default that
+     * names no persona, an id declared twice, an alias two personas claim, or an alias that is a real
+     * agent's name (which would never be reached — a registered agent always wins).
+     */
+    private assertPersonas;
     /**
      * Resolve each handoff entry to an {@link AgentDelegation} — its target's registered name, plus
      * whether that edge detaches (skipping non-agent classes). A bare name is kept for a plain edge
@@ -1288,4 +1416,24 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+declare class ActionProposalController {
+    private readonly proposals;
+    private readonly actors;
+    constructor(proposals: ActionProposalService, actors: ActorResolver);
+    list(threadId: string, request: Request, cursor: unknown, response: Response): Promise<_dudousxd_nestjs_agent_core.ActionProposal[]>;
+    approve(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+    reject(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationResult>;
+}
+
+declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
+    private readonly store;
+    private readonly options;
+    private readonly deps;
+    private worker;
+    private readonly logger;
+    constructor(store: AgentStore, options: AgentModuleOptions, deps: AgentDepsFactory);
+    onModuleInit(): void;
+    onModuleDestroy(): Promise<void>;
+}
+
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, ActionProposalWorkerService, type AgUiAdapterOptions, AgUiRunHandler, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentProtocolAdapter, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, type AnonymousActorOptions, AnonymousActorResolver, type AttachmentLimits, AttachmentsController, type ChatParams, ChatQueueService, type ChatSendMode, type ChatSendResult, ConfigController, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, MAX_ATTACHMENTS_PER_MESSAGE, MemoriesController, MessagesController, ModelsController, QueueController, type QueuedSend, type RequestUserMapper, type ResolvedAiToolOptions, RunNotActiveException, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, type ThreadPersonaReader, ToolsController, agUiAdapter, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, threadPersona, toolNameFromClass };