@dudousxd/nestjs-agent 1.17.1 → 1.18.0

package/dist/index.d.cts

@@ -1,9 +1,9 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentSkillsOptions } from './chat-queue.service-Bqq00NN1.cjs';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, i as QueueSettleOutcome, j as QueuedTurn, k as QueuedTurnStarter, l as QuotaLimits, m as QuotaWindowLimits, n as delegateToolName, p as provideAgentTool, o as provideAgentTools, u as utcDay } from './chat-queue.service-Bqq00NN1.cjs';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, 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 { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-5LIogd9K.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-5LIogd9K.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';
 export * from '@dudousxd/nestjs-agent-core';
-import { Request } from 'express';
+import { Request, Response } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -66,6 +66,12 @@ interface ChatParams {
     transient?: boolean;
     /** What to do when the thread already has a turn running — see {@link ChatSendMode}. */
     mode?: ChatSendMode;
+    /**
+     * When creating a thread (no `threadId`), ask the store to create it under this id — the id an
+     * AG-UI consumer named the conversation with. A store may ignore it (`CreateThreadInput.id`); the
+     * thread's real id is always the one on the result.
+     */
+    newThreadId?: string;
 }
 /**
  * A store that can answer a thread's default agent on its own, without materializing the thread.
@@ -257,6 +263,22 @@ declare class AgentService {
      * its word that it is, and so is one that fails to answer.
      */
     private assertRunWaiting;
+    /** Who owns the thread, or `null` when there is no such (live) thread. */
+    threadOwner(threadId: string): Promise<string | null>;
+    /**
+     * May `actor` continue the run whose stream is `runId` — the AG-UI resume? Only the actor whose
+     * thread is streaming it (`403` otherwise), and only while it still is: a run that is over is
+     * waiting on no one (`409 run_not_active`), whatever an old interrupt id says.
+     */
+    assertResumable(actor: Actor, runId: string): Promise<void>;
+    /**
+     * Everything {@link approve} / {@link reject} check before they signal — who may decide, and
+     * that the request has not lapsed — without signalling. For a caller that settles several
+     * decisions at once and must refuse all of them if one is refused (an AG-UI resume).
+     */
+    checkDecision(actor: Actor, toolCallId: string): Promise<void>;
+    /** Everything {@link answer} checks before it signals, without signalling — see {@link checkDecision}. */
+    checkAnswer(actor: Actor, toolCallId: string, answers: Record<string, string[]>): Promise<void>;
     cancel(actor: Actor, runId: string): Promise<void>;
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
@@ -391,6 +413,57 @@ declare class AgentService {
     private assertOwnsActiveStream;
 }
 
+interface AgUiAdapterOptions {
+    /** Where the route mounts, under the agent's path. Default `'ag-ui'` → `POST <path>/ag-ui`. */
+    path?: string;
+    /**
+     * How long a run that is waiting on a person AND still has other work announced may stay silent
+     * before it is reported interrupted. Default 750 ms.
+     */
+    quietMs?: number;
+}
+/**
+ * Serves the agent over AG-UI 1.0. Not mounted directly — {@link agUiAdapter} mounts a subclass at
+ * the configured path — but exported so a host can extend it under a route of its own.
+ */
+declare class AgUiRunHandler {
+    protected readonly agent: AgentService;
+    protected readonly actorResolver: ActorResolver;
+    protected readonly options: AgentModuleOptions;
+    protected readonly staging: AttachmentStagingStore | undefined;
+    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. */
+    private stage;
+    /**
+     * Deliver what a resume list decided, through the same calls the native decision routes make.
+     * Everything that can refuse — who may decide, an answer a question's rules reject, a payload that
+     * says nothing — is checked for EVERY entry before the first one is delivered, so a list with one
+     * bad entry settles nothing.
+     */
+    private settle;
+    /**
+     * Pipe a run to the client as AG-UI 1.0 over SSE: one event per `data:` line, from `RUN_STARTED`
+     * to the run's terminal event. It ends when the run stops to ask — the library run stays parked,
+     * and the request that answers re-attaches to it.
+     */
+    private pipe;
+}
+/**
+ * Serve the agent over AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0): the body of
+ * `POST <path>/ag-ui` is a `RunAgentInput`, the answer the run as AG-UI events. A run that stops to
+ * ask ends with the interrupt outcome and is continued by a later request carrying `resume`.
+ *
+ * ```ts
+ * AgentModule.forRoot({ model, adapters: [agUiAdapter()] })
+ * ```
+ *
+ * Authenticated by the module's `actorResolver`, guarded by its `guards` and owner-scoped exactly
+ * as `chat`, `chat/:runId/stream` and the `tool-call` routes are.
+ */
+declare function agUiAdapter(options?: AgUiAdapterOptions): AgentProtocolAdapter;
+
 /**
  * Binds `AGENT_APPROVAL_PORT` for the console's cross-thread approvals inbox to the SAME decision
  * path chat approvals use — `AgentService.signalToolCall` (resolve the run awaiting `toolCallId`,
@@ -1215,4 +1288,4 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, 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, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+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 };

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentSkillsOptions } from './chat-queue.service-Bqq00NN1.js';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, i as QueueSettleOutcome, j as QueuedTurn, k as QueuedTurnStarter, l as QuotaLimits, m as QuotaWindowLimits, n as delegateToolName, p as provideAgentTool, o as provideAgentTools, u as utcDay } from './chat-queue.service-Bqq00NN1.js';
-import { AgentRunner, AgentStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, AgentApprovalPort, ActorResolver, 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 { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-5LIogd9K.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-5LIogd9K.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';
 export * from '@dudousxd/nestjs-agent-core';
-import { Request } from 'express';
+import { Request, Response } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -66,6 +66,12 @@ interface ChatParams {
     transient?: boolean;
     /** What to do when the thread already has a turn running — see {@link ChatSendMode}. */
     mode?: ChatSendMode;
+    /**
+     * When creating a thread (no `threadId`), ask the store to create it under this id — the id an
+     * AG-UI consumer named the conversation with. A store may ignore it (`CreateThreadInput.id`); the
+     * thread's real id is always the one on the result.
+     */
+    newThreadId?: string;
 }
 /**
  * A store that can answer a thread's default agent on its own, without materializing the thread.
@@ -257,6 +263,22 @@ declare class AgentService {
      * its word that it is, and so is one that fails to answer.
      */
     private assertRunWaiting;
+    /** Who owns the thread, or `null` when there is no such (live) thread. */
+    threadOwner(threadId: string): Promise<string | null>;
+    /**
+     * May `actor` continue the run whose stream is `runId` — the AG-UI resume? Only the actor whose
+     * thread is streaming it (`403` otherwise), and only while it still is: a run that is over is
+     * waiting on no one (`409 run_not_active`), whatever an old interrupt id says.
+     */
+    assertResumable(actor: Actor, runId: string): Promise<void>;
+    /**
+     * Everything {@link approve} / {@link reject} check before they signal — who may decide, and
+     * that the request has not lapsed — without signalling. For a caller that settles several
+     * decisions at once and must refuse all of them if one is refused (an AG-UI resume).
+     */
+    checkDecision(actor: Actor, toolCallId: string): Promise<void>;
+    /** Everything {@link answer} checks before it signals, without signalling — see {@link checkDecision}. */
+    checkAnswer(actor: Actor, toolCallId: string, answers: Record<string, string[]>): Promise<void>;
     cancel(actor: Actor, runId: string): Promise<void>;
     listThreads(actorRef: string): Promise<ThreadSummary[]>;
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
@@ -391,6 +413,57 @@ declare class AgentService {
     private assertOwnsActiveStream;
 }
 
+interface AgUiAdapterOptions {
+    /** Where the route mounts, under the agent's path. Default `'ag-ui'` → `POST <path>/ag-ui`. */
+    path?: string;
+    /**
+     * How long a run that is waiting on a person AND still has other work announced may stay silent
+     * before it is reported interrupted. Default 750 ms.
+     */
+    quietMs?: number;
+}
+/**
+ * Serves the agent over AG-UI 1.0. Not mounted directly — {@link agUiAdapter} mounts a subclass at
+ * the configured path — but exported so a host can extend it under a route of its own.
+ */
+declare class AgUiRunHandler {
+    protected readonly agent: AgentService;
+    protected readonly actorResolver: ActorResolver;
+    protected readonly options: AgentModuleOptions;
+    protected readonly staging: AttachmentStagingStore | undefined;
+    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. */
+    private stage;
+    /**
+     * Deliver what a resume list decided, through the same calls the native decision routes make.
+     * Everything that can refuse — who may decide, an answer a question's rules reject, a payload that
+     * says nothing — is checked for EVERY entry before the first one is delivered, so a list with one
+     * bad entry settles nothing.
+     */
+    private settle;
+    /**
+     * Pipe a run to the client as AG-UI 1.0 over SSE: one event per `data:` line, from `RUN_STARTED`
+     * to the run's terminal event. It ends when the run stops to ask — the library run stays parked,
+     * and the request that answers re-attaches to it.
+     */
+    private pipe;
+}
+/**
+ * Serve the agent over AG-UI 1.0 (https://docs.ag-ui.com/spec/1.0): the body of
+ * `POST <path>/ag-ui` is a `RunAgentInput`, the answer the run as AG-UI events. A run that stops to
+ * ask ends with the interrupt outcome and is continued by a later request carrying `resume`.
+ *
+ * ```ts
+ * AgentModule.forRoot({ model, adapters: [agUiAdapter()] })
+ * ```
+ *
+ * Authenticated by the module's `actorResolver`, guarded by its `guards` and owner-scoped exactly
+ * as `chat`, `chat/:runId/stream` and the `tool-call` routes are.
+ */
+declare function agUiAdapter(options?: AgUiAdapterOptions): AgentProtocolAdapter;
+
 /**
  * Binds `AGENT_APPROVAL_PORT` for the console's cross-thread approvals inbox to the SAME decision
  * path chat approvals use — `AgentService.signalToolCall` (resolve the run awaiting `toolCallId`,
@@ -1215,4 +1288,4 @@ declare class RunNotActiveException extends ConflictException {
     constructor(runId: string);
 }
 
-export { AGENT_CHAT_QUEUE, AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, 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, attachmentLimits, declaredSkillProvider, defaultRequestUserMapper, readAgentMetadata, readAiToolMetadata, readSkillMetadata, requestUserActorResolver, resolveSkillsConfig, skillScope, toolNameFromClass };
+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 };