@dudousxd/nestjs-agent 1.23.1 → 1.24.1

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. */
@@ -677,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;
@@ -1465,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. */
@@ -677,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;
@@ -1465,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) => {