@dudousxd/nestjs-agent 1.23.0 → 1.24.0

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 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-D1z3WjFI.cjs';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-D1z3WjFI.cjs';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-Crf9uwum.cjs';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-Crf9uwum.cjs';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AgentHostContext, 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';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, ActionProposalView, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -16,6 +16,20 @@ declare class AgentModule {
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+/** Default per-file size cap (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/** How many attachments one message may name. */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
+type AttachmentLimits = AgentAttachmentConfig;
+/**
+ * One source for attachment limits: the staging store's own `describe()` when it declares them
+ * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
+ */
+declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
+
 declare class ActionProposalService {
     private readonly store;
     private readonly options;
@@ -55,8 +69,10 @@ declare class ActionProposalService {
         text: string;
     }>;
     private textReceipt;
+    /** The configured words a text decision is made of (`actionProposalText.vocabulary`). */
+    textVocabulary(): TextActionProposalVocabulary;
     /** The configured reply to a decision the store answered with `result`. */
-    reply(result: ActionProposalMutationView, decision: 'approved' | 'rejected'): string;
+    reply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
 }
 
 /**
@@ -165,7 +181,7 @@ declare class AgentService {
     private readonly options?;
     private readonly queue?;
     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);
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota" | "actionApprovalMode" | "attachments"> | undefined, queue?: ChatQueueService | undefined, proposals?: ActionProposalService | undefined);
     /**
      * Decide one independent proposal through the scoped proposal service — what the native
      * `action-proposals/:id/approve|reject` routes call — and the reply to show for it. `404` when
@@ -194,6 +210,37 @@ declare class AgentService {
         };
         text: string;
     }>;
+    /** How `action` tools wait for their approval here — `AgentModule.forRoot({ actionApprovalMode })`. */
+    actionApprovalMode(): ActionApprovalMode;
+    /**
+     * The words a text decision is made of (`actionProposalText.vocabulary`, English by default) — what
+     * a surface without buttons tells the person to reply.
+     */
+    actionProposalVocabulary(): TextActionProposalVocabulary;
+    /** The configured reply (`actionProposalText.replies`) to a decision the store answered with `result`. */
+    actionProposalReply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
+    /**
+     * The proposals of a thread this actor may see — the thread's own actor, or one the policy lets
+     * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page). `404`
+     * when independent approvals are not on.
+     */
+    listActionProposals(actor: Actor, threadId: string): Promise<ActionProposalView[]>;
+    /**
+     * The attachment rules in force — what `GET <base>/config` serves and `POST <base>/attachments`
+     * enforces. `enabled: false` when no `AGENT_ATTACHMENT_STAGING` provider is bound.
+     */
+    attachmentLimits(): AttachmentLimits;
+    /**
+     * Stage a file for a later turn, held to the same limits as `POST <base>/attachments` — for a
+     * surface that receives files itself (a messaging webhook). Refuses with `501` when attachments are
+     * off, `415` for a type outside the allowlist and `413` past the size cap; send the returned
+     * `mediaId` as `attachments: [{ mediaId }]`.
+     */
+    stageAttachment(actor: Actor, file: {
+        data: Buffer;
+        contentType: string;
+        filename: string;
+    }): Promise<MessageAttachment>;
     /** 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. */
@@ -539,7 +586,10 @@ declare class AgUiRunHandler {
     protected readonly quietMs: number | undefined;
     constructor(agent: AgentService, actorResolver: ActorResolver, options: AgentModuleOptions, staging: AttachmentStagingStore | undefined, quietMs: number | undefined);
     handle(req: Request, res: Response, body: unknown): Promise<void>;
-    /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
+    /**
+     * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+     * through the bound store — all within the store's limits; say what was not used.
+     */
     private stage;
     /**
      * Deliver what a resume list decided, through the same calls the native decision routes make.
@@ -674,20 +724,6 @@ declare class AttachmentsController {
     upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
 }
 
-/** Default per-file size cap (20 MiB). */
-declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
-/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
-declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
-/** How many attachments one message may name. */
-declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
-/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
-type AttachmentLimits = AgentAttachmentConfig;
-/**
- * One source for attachment limits: the staging store's own `describe()` when it declares them
- * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
- */
-declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
-
 declare class ConfigController {
     private readonly options;
     private readonly actorResolver;
@@ -1462,15 +1498,26 @@ declare class ActionProposalController {
     reject(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationView>;
 }
 
+/** Called with a proposal the worker just settled (executed, or failed executing). */
+type ActionProposalSettledListener = (proposal: ActionProposal) => void | Promise<void>;
 declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
     private readonly store;
     private readonly options;
     private readonly deps;
     private worker;
     private readonly logger;
+    private readonly settledListeners;
+    /**
+     * Run `listener` after every proposal this process's worker settles — how a module relays an
+     * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
+     * `actionProposalWorker.onSettled`; a listener that throws is logged and does not stop the others.
+     * Returns the unsubscribe. Only the replicas that run the worker (not `surface: 'http'`) call it.
+     */
+    onSettled(listener: ActionProposalSettledListener): () => void;
+    private settled;
     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 };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, 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,8 +1,8 @@
 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-CwxJDrBM.js';
-export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-CwxJDrBM.js';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-ZQkqb1Yw.js';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-ZQkqb1Yw.js';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AgentHostContext, 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';
+import { AgentAttachmentConfig, AttachmentStagingStore, AgentStore, Actor, ListActionProposals, ActionProposalMutationView, TextActionProposalVocabulary, AgentRunner, ModelCatalog, QuotaProvider, ActionApprovalMode, ActionProposalView, MessageAttachment, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter, ActionProposal } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -16,6 +16,20 @@ declare class AgentModule {
     static forRootAsync(options: AgentModuleAsyncOptions): DynamicModule;
 }
 
+/** Default per-file size cap (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/** How many attachments one message may name. */
+declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
+/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
+type AttachmentLimits = AgentAttachmentConfig;
+/**
+ * One source for attachment limits: the staging store's own `describe()` when it declares them
+ * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
+ */
+declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
+
 declare class ActionProposalService {
     private readonly store;
     private readonly options;
@@ -55,8 +69,10 @@ declare class ActionProposalService {
         text: string;
     }>;
     private textReceipt;
+    /** The configured words a text decision is made of (`actionProposalText.vocabulary`). */
+    textVocabulary(): TextActionProposalVocabulary;
     /** The configured reply to a decision the store answered with `result`. */
-    reply(result: ActionProposalMutationView, decision: 'approved' | 'rejected'): string;
+    reply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
 }
 
 /**
@@ -165,7 +181,7 @@ declare class AgentService {
     private readonly options?;
     private readonly queue?;
     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);
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quota" | "actionApprovalMode" | "attachments"> | undefined, queue?: ChatQueueService | undefined, proposals?: ActionProposalService | undefined);
     /**
      * Decide one independent proposal through the scoped proposal service — what the native
      * `action-proposals/:id/approve|reject` routes call — and the reply to show for it. `404` when
@@ -194,6 +210,37 @@ declare class AgentService {
         };
         text: string;
     }>;
+    /** How `action` tools wait for their approval here — `AgentModule.forRoot({ actionApprovalMode })`. */
+    actionApprovalMode(): ActionApprovalMode;
+    /**
+     * The words a text decision is made of (`actionProposalText.vocabulary`, English by default) — what
+     * a surface without buttons tells the person to reply.
+     */
+    actionProposalVocabulary(): TextActionProposalVocabulary;
+    /** The configured reply (`actionProposalText.replies`) to a decision the store answered with `result`. */
+    actionProposalReply(result: Pick<ActionProposalMutationView, 'status' | 'proposal'>, decision: 'approved' | 'rejected'): string;
+    /**
+     * The proposals of a thread this actor may see — the thread's own actor, or one the policy lets
+     * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page). `404`
+     * when independent approvals are not on.
+     */
+    listActionProposals(actor: Actor, threadId: string): Promise<ActionProposalView[]>;
+    /**
+     * The attachment rules in force — what `GET <base>/config` serves and `POST <base>/attachments`
+     * enforces. `enabled: false` when no `AGENT_ATTACHMENT_STAGING` provider is bound.
+     */
+    attachmentLimits(): AttachmentLimits;
+    /**
+     * Stage a file for a later turn, held to the same limits as `POST <base>/attachments` — for a
+     * surface that receives files itself (a messaging webhook). Refuses with `501` when attachments are
+     * off, `415` for a type outside the allowlist and `413` past the size cap; send the returned
+     * `mediaId` as `attachments: [{ mediaId }]`.
+     */
+    stageAttachment(actor: Actor, file: {
+        data: Buffer;
+        contentType: string;
+        filename: string;
+    }): Promise<MessageAttachment>;
     /** 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. */
@@ -539,7 +586,10 @@ declare class AgUiRunHandler {
     protected readonly quietMs: number | undefined;
     constructor(agent: AgentService, actorResolver: ActorResolver, options: AgentModuleOptions, staging: AttachmentStagingStore | undefined, quietMs: number | undefined);
     handle(req: Request, res: Response, body: unknown): Promise<void>;
-    /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
+    /**
+     * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+     * through the bound store — all within the store's limits; say what was not used.
+     */
     private stage;
     /**
      * Deliver what a resume list decided, through the same calls the native decision routes make.
@@ -674,20 +724,6 @@ declare class AttachmentsController {
     upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
 }
 
-/** Default per-file size cap (20 MiB). */
-declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
-/** Default allowlist: what multimodal model providers commonly accept as native image/file parts. */
-declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
-/** How many attachments one message may name. */
-declare const MAX_ATTACHMENTS_PER_MESSAGE = 10;
-/** The attachment rules in force — `AgentAttachmentConfig`, as `GET <base>/config` serves it. */
-type AttachmentLimits = AgentAttachmentConfig;
-/**
- * One source for attachment limits: the staging store's own `describe()` when it declares them
- * (`AgentMediaAttachmentsModule` does), else `AgentModule`'s `attachments` option, else the defaults.
- */
-declare function attachmentLimits(options: Pick<AgentModuleOptions, 'attachments'> | undefined, staging: AttachmentStagingStore | undefined): AttachmentLimits;
-
 declare class ConfigController {
     private readonly options;
     private readonly actorResolver;
@@ -1462,15 +1498,26 @@ declare class ActionProposalController {
     reject(threadId: string, proposalId: string, request: Request, body: unknown): Promise<_dudousxd_nestjs_agent_core.ActionProposalMutationView>;
 }
 
+/** Called with a proposal the worker just settled (executed, or failed executing). */
+type ActionProposalSettledListener = (proposal: ActionProposal) => void | Promise<void>;
 declare class ActionProposalWorkerService implements OnModuleInit, OnModuleDestroy {
     private readonly store;
     private readonly options;
     private readonly deps;
     private worker;
     private readonly logger;
+    private readonly settledListeners;
+    /**
+     * Run `listener` after every proposal this process's worker settles — how a module relays an
+     * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
+     * `actionProposalWorker.onSettled`; a listener that throws is logged and does not stop the others.
+     * Returns the unsubscribe. Only the replicas that run the worker (not `surface: 'http'`) call it.
+     */
+    onSettled(listener: ActionProposalSettledListener): () => void;
+    private settled;
     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 };
+export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, ActionProposalController, ActionProposalService, type ActionProposalSettledListener, 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.js

@@ -565,8 +565,8 @@ AgentDepsFactory2 = _ts_decorate2([
 ], AgentDepsFactory2);
 
 // src/agent.service.ts
-import { AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_MODEL_CATALOG, AGENT_OPTIONS as AGENT_OPTIONS4, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE4, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval as mayDecideApproval2, readElicitationQuestions, settleDeadRun, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException2, ConflictException as ConflictException2, ForbiddenException as ForbiddenException2, GoneException, HttpException, HttpStatus, Inject as Inject5, Injectable as Injectable4, NotFoundException as NotFoundException2, NotImplementedException as NotImplementedException3, Optional as Optional3 } from "@nestjs/common";
+import { AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING2, AGENT_DEPS_FACTORY as AGENT_DEPS_FACTORY2, AGENT_MODEL_CATALOG, AGENT_OPTIONS as AGENT_OPTIONS4, AGENT_QUOTA_PROVIDER as AGENT_QUOTA_PROVIDER2, AGENT_RUNNER, AGENT_STORE as AGENT_STORE4, DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY as DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY2, REQUESTER_APPROVER, findCatalogModel, mayDecideApproval as mayDecideApproval2, readElicitationQuestions, settleDeadRun, textActionProposalReply as textActionProposalReply2, validateElicitationAnswer } from "@dudousxd/nestjs-agent-core";
+import { BadRequestException as BadRequestException2, ConflictException as ConflictException2, ForbiddenException as ForbiddenException2, GoneException, HttpException, HttpStatus, Inject as Inject5, Injectable as Injectable4, NotFoundException as NotFoundException2, NotImplementedException as NotImplementedException3, Optional as Optional3, PayloadTooLargeException, UnsupportedMediaTypeException } from "@nestjs/common";
 
 // src/agent-deps.ts
 function utcDay(date = /* @__PURE__ */ new Date()) {
@@ -590,6 +590,31 @@ function childSinkWriter(writer) {
 }
 __name(childSinkWriter, "childSinkWriter");
 
+// src/attachment-limits.ts
+var DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
+var DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
+  "image/png",
+  "image/jpeg",
+  "image/gif",
+  "image/webp",
+  "application/pdf",
+  "text/plain",
+  "text/csv"
+];
+var MAX_ATTACHMENTS_PER_MESSAGE = 10;
+function attachmentLimits(options, staging) {
+  const declared = staging?.describe?.();
+  const own = options?.attachments;
+  return {
+    enabled: staging !== void 0,
+    upload: staging === void 0 ? null : declared?.upload ?? "multipart",
+    maxBytes: declared?.maxBytes ?? own?.maxBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
+    allowedContentTypes: declared?.allowedContentTypes ?? own?.allowedContentTypes ?? DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES,
+    maxPerMessage: MAX_ATTACHMENTS_PER_MESSAGE
+  };
+}
+__name(attachmentLimits, "attachmentLimits");
+
 // src/proposals/action-proposal.service.ts
 import { AGENT_OPTIONS as AGENT_OPTIONS2, AGENT_STORE as AGENT_STORE2, DEFAULT_TEXT_ACTION_PROPOSAL_REPLIES, DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY, mayDecideApproval, parseTextActionProposalCommand, resolveTextActionProposalDecision, textActionProposalReply, toActionProposalMutationView, toActionProposalView } from "@dudousxd/nestjs-agent-core";
 import { ForbiddenException, Inject as Inject3, Injectable as Injectable2, NotFoundException, NotImplementedException } from "@nestjs/common";
@@ -746,6 +771,10 @@ var ActionProposalService = class {
       text: this.reply(result, decision)
     };
   }
+  /** The configured words a text decision is made of (`actionProposalText.vocabulary`). */
+  textVocabulary() {
+    return this.vocabulary;
+  }
   /** The configured reply to a decision the store answered with `result`. */
   reply(result, decision) {
     return textActionProposalReply(result, decision, this.replies);
@@ -1372,6 +1401,65 @@ var AgentService = class {
     };
     return this.proposals.handleTextDecision(threadId, actor, text);
   }
+  /** How `action` tools wait for their approval here — `AgentModule.forRoot({ actionApprovalMode })`. */
+  actionApprovalMode() {
+    return this.options?.actionApprovalMode ?? "blocking";
+  }
+  /**
+  * The words a text decision is made of (`actionProposalText.vocabulary`, English by default) — what
+  * a surface without buttons tells the person to reply.
+  */
+  actionProposalVocabulary() {
+    return this.proposals?.textVocabulary() ?? DEFAULT_TEXT_ACTION_PROPOSAL_VOCABULARY2;
+  }
+  /** The configured reply (`actionProposalText.replies`) to a decision the store answered with `result`. */
+  actionProposalReply(result, decision) {
+    return this.proposals?.reply(result, decision) ?? textActionProposalReply2(result, decision);
+  }
+  /**
+  * The proposals of a thread this actor may see — the thread's own actor, or one the policy lets
+  * decide them; what `GET <base>/threads/:threadId/action-proposals` serves (its first page). `404`
+  * when independent approvals are not on.
+  */
+  async listActionProposals(actor, threadId) {
+    if (this.options?.actionApprovalMode !== "independent" || !this.proposals) {
+      throw new NotFoundException2("Proposal not found");
+    }
+    return this.proposals.list(threadId, actor);
+  }
+  /**
+  * The attachment rules in force — what `GET <base>/config` serves and `POST <base>/attachments`
+  * enforces. `enabled: false` when no `AGENT_ATTACHMENT_STAGING` provider is bound.
+  */
+  attachmentLimits() {
+    return attachmentLimits(this.options, this.staging);
+  }
+  /**
+  * Stage a file for a later turn, held to the same limits as `POST <base>/attachments` — for a
+  * surface that receives files itself (a messaging webhook). Refuses with `501` when attachments are
+  * off, `415` for a type outside the allowlist and `413` past the size cap; send the returned
+  * `mediaId` as `attachments: [{ mediaId }]`.
+  */
+  async stageAttachment(actor, file) {
+    if (this.staging === void 0) {
+      throw new NotImplementedException3("Attachments are not configured on this server: bind AGENT_ATTACHMENT_STAGING (e.g. import AgentMediaAttachmentsModule).");
+    }
+    const { allowedContentTypes, maxBytes } = this.attachmentLimits();
+    const contentType = file.contentType.split(";")[0]?.trim().toLowerCase() ?? "";
+    if (!allowedContentTypes.includes(contentType)) {
+      throw new UnsupportedMediaTypeException(`content type "${contentType}" is not allowed (allowed: ${allowedContentTypes.join(", ")})`);
+    }
+    if (file.data.byteLength > maxBytes) {
+      throw new PayloadTooLargeException(`file exceeds the ${maxBytes}-byte limit`);
+    }
+    return this.staging.stage({
+      data: file.data,
+      filename: file.filename,
+      contentType,
+      sizeBytes: file.data.byteLength,
+      actor
+    });
+  }
   /** The queue service when the bound store can hold a queue, else `undefined`. */
   queueing() {
     return this.queue?.supported === true ? this.queue : void 0;
@@ -2653,35 +2741,8 @@ AgentsController = _ts_decorate7([
 
 // src/controller/attachments.controller.ts
 import { AGENT_ACTOR_RESOLVER, AGENT_ATTACHMENT_STAGING as AGENT_ATTACHMENT_STAGING3, AGENT_OPTIONS as AGENT_OPTIONS5 } from "@dudousxd/nestjs-agent-core";
-import { BadRequestException as BadRequestException3, Controller as Controller2, Get as Get2, Inject as Inject7, NotImplementedException as NotImplementedException5, Optional as Optional5, PayloadTooLargeException, Post, Req, UnsupportedMediaTypeException, UploadedFile, UseInterceptors } from "@nestjs/common";
+import { BadRequestException as BadRequestException3, Controller as Controller2, Get as Get2, Inject as Inject7, NotImplementedException as NotImplementedException5, Optional as Optional5, PayloadTooLargeException as PayloadTooLargeException2, Post, Req, UnsupportedMediaTypeException as UnsupportedMediaTypeException2, UploadedFile, UseInterceptors } from "@nestjs/common";
 import { FileInterceptor } from "@nestjs/platform-express";
-
-// src/attachment-limits.ts
-var DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
-var DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES = [
-  "image/png",
-  "image/jpeg",
-  "image/gif",
-  "image/webp",
-  "application/pdf",
-  "text/plain",
-  "text/csv"
-];
-var MAX_ATTACHMENTS_PER_MESSAGE = 10;
-function attachmentLimits(options, staging) {
-  const declared = staging?.describe?.();
-  const own = options?.attachments;
-  return {
-    enabled: staging !== void 0,
-    upload: staging === void 0 ? null : declared?.upload ?? "multipart",
-    maxBytes: declared?.maxBytes ?? own?.maxBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
-    allowedContentTypes: declared?.allowedContentTypes ?? own?.allowedContentTypes ?? DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES,
-    maxPerMessage: MAX_ATTACHMENTS_PER_MESSAGE
-  };
-}
-__name(attachmentLimits, "attachmentLimits");
-
-// src/controller/attachments.controller.ts
 function _ts_decorate8(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") {
@@ -2748,10 +2809,10 @@ var AttachmentsController = class {
     }
     const { allowedContentTypes, maxBytes } = attachmentLimits(this.options, this.staging);
     if (!allowedContentTypes.includes(file.mimetype)) {
-      throw new UnsupportedMediaTypeException(`content type "${file.mimetype}" is not allowed (allowed: ${allowedContentTypes.join(", ")})`);
+      throw new UnsupportedMediaTypeException2(`content type "${file.mimetype}" is not allowed (allowed: ${allowedContentTypes.join(", ")})`);
     }
     if (file.size > maxBytes) {
-      throw new PayloadTooLargeException(`file exceeds the ${maxBytes}-byte limit`);
+      throw new PayloadTooLargeException2(`file exceeds the ${maxBytes}-byte limit`);
     }
     const actor = await this.actorResolver.resolve(req);
     return this.staging.stage({
@@ -5084,6 +5145,34 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
   deps;
   worker;
   logger = new Logger5(_ActionProposalWorkerService.name);
+  settledListeners = /* @__PURE__ */ new Set();
+  /**
+  * Run `listener` after every proposal this process's worker settles — how a module relays an
+  * outcome somewhere the turn's stream no longer reaches (a text channel's conversation). Next to
+  * `actionProposalWorker.onSettled`; a listener that throws is logged and does not stop the others.
+  * Returns the unsubscribe. Only the replicas that run the worker (not `surface: 'http'`) call it.
+  */
+  onSettled(listener) {
+    this.settledListeners.add(listener);
+    return () => {
+      this.settledListeners.delete(listener);
+    };
+  }
+  async settled(proposal) {
+    const configured = this.options.actionProposalWorker?.onSettled;
+    for (const listener of [
+      ...configured ? [
+        configured
+      ] : [],
+      ...this.settledListeners
+    ]) {
+      try {
+        await listener(proposal);
+      } catch (error) {
+        this.logger.error(error);
+      }
+    }
+  }
   constructor(store, options, deps) {
     this.store = store;
     this.options = options;
@@ -5099,6 +5188,7 @@ var ActionProposalWorkerService = class _ActionProposalWorkerService {
       store: this.store,
       workerId: randomUUID(),
       ...this.options.actionProposalWorker,
+      onSettled: /* @__PURE__ */ __name((proposal) => this.settled(proposal), "onSettled"),
       executor: new ActionProposalExecutor({
         resolver,
         resolveExecution: /* @__PURE__ */ __name(async (proposal, actor) => {
@@ -6369,7 +6459,10 @@ var AgUiRunHandler = class {
     if (owner !== null && owner !== actor.id) {
       throw new ForbiddenException4("thread belongs to another actor");
     }
-    if (owner !== null && turn.media.length === 0) {
+    if (forwarded.regenerate === true && owner === null) {
+      throw invalid("invalid_input", "regenerate needs a thread that already has an exchange");
+    }
+    if (owner !== null && forwarded.regenerate !== true && turn.media.length === 0 && turn.staged.length === 0) {
       const decision = await this.agent.handleTextDecision(input.threadId, actor, turn.text);
       if ("proposalDecision" in decision) {
         this.writeEvents(res, [
@@ -6384,7 +6477,7 @@ var AgUiRunHandler = class {
         return;
       }
     }
-    const refs = await this.stage(actor, turn.media, warnings);
+    const refs = await this.stage(actor, turn.media, warnings, turn.staged);
     if (turn.text.trim().length === 0 && refs.length === 0) {
       throw invalid("no_user_message", "the user message to answer is empty");
     }
@@ -6420,6 +6513,9 @@ var AgUiRunHandler = class {
       } : {},
       ...refs.length > 0 ? {
         attachments: refs
+      } : {},
+      ...forwarded.regenerate === true ? {
+        regenerate: true
       } : {}
     });
     await this.pipe(res, started.runId, {
@@ -6431,10 +6527,25 @@ var AgUiRunHandler = class {
       preamble: warningEvents(warnings)
     });
   }
-  /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
-  async stage(actor, media, warnings) {
+  /**
+  * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+  * through the bound store — all within the store's limits; say what was not used.
+  */
+  async stage(actor, media, warnings, staged = []) {
     const refs = [];
     const limits = attachmentLimits(this.options, this.staging);
+    for (const ref of staged) {
+      const label = `The attachment ${ref.mediaId} was not used`;
+      if (this.staging === void 0) {
+        warnings.push(`${label}: attachments are not enabled on this agent.`);
+      } else if (refs.length >= limits.maxPerMessage) {
+        warnings.push(`${label}: a message carries at most ${limits.maxPerMessage} attachments.`);
+      } else {
+        refs.push({
+          mediaId: ref.mediaId
+        });
+      }
+    }
     for (const item of media) {
       const label = `The ${item.kind} "${item.filename}" was not used`;
       if (this.staging === void 0) {
@@ -6447,7 +6558,7 @@ var AgUiRunHandler = class {
         warnings.push(`${label}: it is larger than ${limits.maxBytes} bytes.`);
       } else {
         try {
-          const staged = await this.staging.stage({
+          const staged2 = await this.staging.stage({
             data: item.data,
             filename: item.filename,
             contentType: item.contentType,
@@ -6455,7 +6566,7 @@ var AgUiRunHandler = class {
             actor
           });
           refs.push({
-            mediaId: staged.mediaId
+            mediaId: staged2.mediaId
           });
         } catch {
           warnings.push(`${label}: it could not be stored.`);
@@ -6573,11 +6684,17 @@ var AgUiRunHandler = class {
     res.setHeader("X-Agent-Run-Id", runId);
     res.flushHeaders();
     let terminal = false;
+    const cursor = {
+      seq: 0
+    };
     try {
       const frames = agUiFramesFromNdjson(this.agent.subscribe(runId));
-      for await (const event of agUiEvents(frames, options)) {
+      for await (const event of agUiEvents(frames, {
+        ...options,
+        cursor
+      })) {
         if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
-        res.write(agUiSse(event));
+        res.write(agUiSse(event, cursor.seq));
       }
     } catch {
       if (!terminal) {