@dudousxd/nestjs-agent 1.6.0 → 1.8.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-CUyVPsa1.cjs';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-CUyVPsa1.cjs';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-Cus_RqwJ.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 QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-Cus_RqwJ.cjs';
+import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -26,6 +26,11 @@ interface ChatParams {
     pageContext?: PageContext;
     /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
     regenerate?: boolean;
+    /**
+     * Run this turn on a catalog model instead of the thread's pinned one (or the provider default).
+     * Refused (400) unless the bound `ModelCatalog` lists it as available to this actor and agent.
+     */
+    model?: string;
     /**
      * When creating a thread (no `threadId`), start it transient — a scratch conversation hidden from
      * the thread list until the caller promotes it. Ignored when `threadId` is set.
@@ -42,6 +47,10 @@ interface ChatParams {
 interface ThreadDefaultAgentReader {
     defaultAgentForThread(threadId: string): Promise<string | null>;
 }
+/** Like {@link ThreadDefaultAgentReader}, for the thread's pinned model. */
+interface ThreadModelReader {
+    modelForThread(threadId: string): Promise<string | null>;
+}
 /** The orchestration facade the controllers call. */
 declare class AgentService {
     private readonly runner;
@@ -49,7 +58,35 @@ declare class AgentService {
     private readonly deps;
     private readonly quota;
     private readonly staging?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined);
+    private readonly models?;
+    private readonly quotaProvider?;
+    private readonly options?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quotaProvider" | "quotaLimits"> | undefined);
+    /**
+     * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
+     * report. Without one (a service built outside the module), a day window from the ledger.
+     */
+    quotaReport(actor: Actor): Promise<QuotaReport>;
+    /**
+     * Refuse a turn the actor's budget no longer covers — only when the host configured one
+     * (`quotaProvider` or `quotaLimits`): the default report is informational, and the daily token
+     * quota the loop enforces keeps working as it always has.
+     */
+    private assertWithinQuota;
+    /**
+     * The models `actor` may pick for `agent` (`GET <base>/models`). An empty catalog when none is
+     * bound, so a picker simply has nothing to offer.
+     */
+    listModels(actor: Actor, agent?: string): Promise<ModelCatalogView>;
+    /**
+     * `model` if the catalog offers it to this actor and agent right now, else a 400 naming why. The
+     * one gate every model choice passes — a send's own, and a thread's pinned one at the moment it is
+     * pinned and again at every turn that runs on it (availability can change in between).
+     */
+    private assertModelAllowed;
+    /** The model a turn runs on: the send's own, else the thread's pinned one, else none. */
+    private resolveModel;
+    private threadModel;
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
@@ -695,6 +732,17 @@ declare class MessagesController {
     }>;
 }
 
+declare class ModelsController {
+    private readonly agent;
+    private readonly actorResolver;
+    constructor(agent: AgentService, actorResolver: ActorResolver);
+    /**
+     * The models the caller may pick for `agent` (the default agent when omitted), grouped by
+     * provider, with badges and availability — the bound `ModelCatalog`'s answer, or an empty one.
+     */
+    list(req: Request, agent?: string): Promise<ModelCatalogView>;
+}
+
 /**
  * The tools THIS caller can reach through an agent, with how a chat surface should talk about each
  * one (`@AiTool({ presentation })`) — so a client narrates "Querying orders" instead of printing
@@ -898,4 +946,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, ModelsController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-CUyVPsa1.js';
-export { e as AGENT_TOOL_BRAND, f as AgentAttachmentsOptions, g as AgentDeps, h as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, i as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-CUyVPsa1.js';
-import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, Actor, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, d as AgentSkillsOptions } from './agent-deps.factory-Cus_RqwJ.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 QuotaLimits, i as QuotaWindowLimits, j as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-Cus_RqwJ.js';
+import { AgentRunner, AgentStore, QuotaStore, AttachmentStagingStore, ModelCatalog, QuotaProvider, Actor, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, QuotaView, AgentApprovalPort, ActorResolver, MessageAttachment, ToolPresentation, AgentHistoryWindow, AgentIntake, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
@@ -26,6 +26,11 @@ interface ChatParams {
     pageContext?: PageContext;
     /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
     regenerate?: boolean;
+    /**
+     * Run this turn on a catalog model instead of the thread's pinned one (or the provider default).
+     * Refused (400) unless the bound `ModelCatalog` lists it as available to this actor and agent.
+     */
+    model?: string;
     /**
      * When creating a thread (no `threadId`), start it transient — a scratch conversation hidden from
      * the thread list until the caller promotes it. Ignored when `threadId` is set.
@@ -42,6 +47,10 @@ interface ChatParams {
 interface ThreadDefaultAgentReader {
     defaultAgentForThread(threadId: string): Promise<string | null>;
 }
+/** Like {@link ThreadDefaultAgentReader}, for the thread's pinned model. */
+interface ThreadModelReader {
+    modelForThread(threadId: string): Promise<string | null>;
+}
 /** The orchestration facade the controllers call. */
 declare class AgentService {
     private readonly runner;
@@ -49,7 +58,35 @@ declare class AgentService {
     private readonly deps;
     private readonly quota;
     private readonly staging?;
-    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined);
+    private readonly models?;
+    private readonly quotaProvider?;
+    private readonly options?;
+    constructor(runner: AgentRunner, store: AgentStore, deps: AgentDepsFactory, quota: QuotaStore | undefined, staging?: AttachmentStagingStore | undefined, models?: ModelCatalog | undefined, quotaProvider?: QuotaProvider | undefined, options?: Pick<AgentModuleOptions, "quotaProvider" | "quotaLimits"> | undefined);
+    /**
+     * The actor's budget across windows (`GET <base>/quota`) — the bound {@link QuotaProvider}'s
+     * report. Without one (a service built outside the module), a day window from the ledger.
+     */
+    quotaReport(actor: Actor): Promise<QuotaReport>;
+    /**
+     * Refuse a turn the actor's budget no longer covers — only when the host configured one
+     * (`quotaProvider` or `quotaLimits`): the default report is informational, and the daily token
+     * quota the loop enforces keeps working as it always has.
+     */
+    private assertWithinQuota;
+    /**
+     * The models `actor` may pick for `agent` (`GET <base>/models`). An empty catalog when none is
+     * bound, so a picker simply has nothing to offer.
+     */
+    listModels(actor: Actor, agent?: string): Promise<ModelCatalogView>;
+    /**
+     * `model` if the catalog offers it to this actor and agent right now, else a 400 naming why. The
+     * one gate every model choice passes — a send's own, and a thread's pinned one at the moment it is
+     * pinned and again at every turn that runs on it (availability can change in between).
+     */
+    private assertModelAllowed;
+    /** The model a turn runs on: the send's own, else the thread's pinned one, else none. */
+    private resolveModel;
+    private threadModel;
     chat(params: ChatParams): Promise<{
         runId: string;
         threadId: string;
@@ -695,6 +732,17 @@ declare class MessagesController {
     }>;
 }
 
+declare class ModelsController {
+    private readonly agent;
+    private readonly actorResolver;
+    constructor(agent: AgentService, actorResolver: ActorResolver);
+    /**
+     * The models the caller may pick for `agent` (the default agent when omitted), grouped by
+     * provider, with badges and availability — the bound `ModelCatalog`'s answer, or an empty one.
+     */
+    list(req: Request, agent?: string): Promise<ModelCatalogView>;
+}
+
 /**
  * The tools THIS caller can reach through an agent, with how a chat surface should talk about each
  * one (`@AiTool({ presentation })`) — so a client narrates "Querying orders" instead of printing
@@ -898,4 +946,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };
+export { AGENT_METADATA, AI_TOOL_METADATA, ATTACHMENT_PAGE_SIZE, Agent, AgentApprovalPortAdapter, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AgentSkillsOptions, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, type DeclaredSkill, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, MemoriesController, MessagesController, ModelsController, SKILL_METADATA, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, Skill, type SkillBody, SkillDiscoveryService, type SkillOptions, SkillsController, SystemPrompt, SystemPromptContributor, type ThreadDefaultAgentReader, type ThreadModelReader, ToolsController, declaredSkillProvider, readAgentMetadata, readAiToolMetadata, readSkillMetadata, resolveSkillsConfig, skillScope };