@dudousxd/nestjs-agent-core 0.23.0 → 0.25.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, e as AiToolCtx, f as AgentStreamEvent, A as Actor, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as MessageFeedback, l as ToolCallStatus, U as UsagePurpose, m as ToolSpec, Q as QuotaState, n as AgentRunInput, H as HumanReply, o as ToolKind, p as ToolCallApproval, T as ToolHandler, q as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, r as ProcessedPrompt, s as ModelAnswer, t as PageContext, u as AgentDefinition, v as AgentDelegation, D as DetachedDelivery, w as PromptBuilder, x as PromptContributor, y as ToolTransientRetrySetting, z as AgentIntake, B as Decision, E as ElicitationRequest, L as LlmStepEnvelope, C as ToolStepEnvelope } from './tool-BdW-LV1J.cjs';
-export { F as ASK_TOOL_DESCRIPTION, G as ASK_TOOL_NAME, J as AgentApprovalRequest, K as AgentApprovalSettlement, N as AgentCatalogEntry, R as AgentHistoryWindow, V as AskToolInput, W as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, X as DEFAULT_INTAKE_PREAMBLE, Y as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Z as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, _ as ELICITATION_INPUT_TYPES, $ as ElicitationInput, a0 as ElicitationInputType, a1 as ElicitationOption, a2 as ElicitationOutcome, a3 as ElicitationQuestion, a4 as ElicitationReply, a5 as ElicitationResult, a6 as HistoryPolicyContext, a7 as HistorySelection, a8 as HistorySummary, a9 as IncrementalGating, aa as InvokeWithTransientRetryOptions, ab as MAX_ASK_QUESTIONS, ac as MessageFeedbackValue, ad as MessageRole, ae as OutputRejectedError, af as OutputVerdict, ag as ProcessorFailedError, ah as PromptContext, ai as QuotaView, aj as ToolCallApprovalStatus, ak as ToolCatalogEntry, al as ToolConfirmation, am as ToolPresentation, an as ToolPresentationTone, ao as ToolResultField, ap as ToolResultView, aq as ToolStepCtx, ar as ToolTransientRetryNumbers, as as ToolTransientRetryOptions, at as askInputSchema, au as askToolDefinition, av as decodeStreamEvent, aw as encodeStreamEvent, ax as invokeWithTransientRetry, ay as isTransientToolError, az as isTypedQuestion, aA as normalizeElicitationReply, aB as questionOptions, aC as readElicitationInput, aD as readElicitationQuestions, aE as renderElicitationAnswers, aF as resolveElicitation, aG as resolveToolTransientRetryNumbers, aH as settleElicitation, aI as validateElicitationAnswer, aJ as validateElicitationValue } from './tool-BdW-LV1J.cjs';
+import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, A as Actor, e as AiToolCtx, f as AgentStreamEvent, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as MessageFeedback, l as ToolCallStatus, U as UsagePurpose, m as ToolSpec, Q as QuotaState, n as AgentRunInput, H as HumanReply, o as ToolKind, p as ToolCallApproval, T as ToolHandler, q as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, r as ProcessedPrompt, s as ModelAnswer, t as PageContext, u as AgentDefinition, v as AgentDelegation, D as DetachedDelivery, w as PromptBuilder, x as PromptContributor, y as ToolTransientRetrySetting, z as AgentIntake, B as Decision, E as ElicitationRequest, L as LlmStepEnvelope, C as ToolStepEnvelope } from './tool-fLRLs_f3.cjs';
+export { F as ASK_TOOL_DESCRIPTION, G as ASK_TOOL_NAME, J as AgentApprovalRequest, K as AgentApprovalSettlement, N as AgentCatalogEntry, R as AgentHistoryWindow, V as AskToolInput, W as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, X as DEFAULT_INTAKE_PREAMBLE, Y as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Z as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, _ as ELICITATION_INPUT_TYPES, $ as ElicitationInput, a0 as ElicitationInputType, a1 as ElicitationOption, a2 as ElicitationOutcome, a3 as ElicitationQuestion, a4 as ElicitationReply, a5 as ElicitationResult, a6 as HistoryPolicyContext, a7 as HistorySelection, a8 as HistorySummary, a9 as IncrementalGating, aa as InvokeWithTransientRetryOptions, ab as MAX_ASK_QUESTIONS, ac as MessageFeedbackValue, ad as MessageRole, ae as OutputRejectedError, af as OutputVerdict, ag as ProcessorFailedError, ah as PromptContext, ai as QuotaView, aj as ToolCallApprovalStatus, ak as ToolCatalogEntry, al as ToolConfirmation, am as ToolPresentation, an as ToolPresentationTone, ao as ToolResultField, ap as ToolResultView, aq as ToolStepCtx, ar as ToolTransientRetryNumbers, as as ToolTransientRetryOptions, at as askInputSchema, au as askToolDefinition, av as decodeStreamEvent, aw as encodeStreamEvent, ax as invokeWithTransientRetry, ay as isTransientToolError, az as isTypedQuestion, aA as normalizeElicitationReply, aB as questionOptions, aC as readElicitationInput, aD as readElicitationQuestions, aE as renderElicitationAnswers, aF as resolveElicitation, aG as resolveToolTransientRetryNumbers, aH as settleElicitation, aI as validateElicitationAnswer, aJ as validateElicitationValue } from './tool-fLRLs_f3.cjs';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
@@ -32,6 +32,10 @@ declare const AGENT_REGISTRY: unique symbol;
 declare const AGENT_ACTOR_RESOLVER: unique symbol;
 /** The governance read-model (usage/spend/threads), consumed by the dashboard + telescope surfaces. */
 declare const AGENT_GOVERNANCE_QUERIES: unique symbol;
+/** The `QuotaProvider` behind `GET <base>/quota` (and, when the host binds one, the send gate). */
+declare const AGENT_QUOTA_PROVIDER: unique symbol;
+/** The `ModelCatalog` behind `GET <base>/models` and the model a send may name. Optional. */
+declare const AGENT_MODEL_CATALOG: unique symbol;
 /** The pricing WRITE side (`AgentPricingStore`) — seeds/updates the per-model rates cost is priced against. */
 declare const AGENT_PRICING_STORE: unique symbol;
 /** The RAG retrieval seam (`Retriever`) — vector/keyword search behind the agentic tool or inject mode. */
@@ -134,6 +138,12 @@ interface ModelTurnArgs {
      * the reply against the same schema either way, so ignoring it costs reliability, not safety.
      */
     outputSchema?: StandardSchemaV1;
+    /**
+     * The model the caller picked for this turn — a {@link import('./model-catalog.js').ModelCatalogEntry}
+     * id the server already checked against the catalog (a per-send `model`, else the thread's pinned
+     * one). Absent → the provider's own default. A provider serving a single model may ignore it.
+     */
+    model?: string;
 }
 /** The outcome of ONE assistant turn. The loop — not the model — drives tool execution. */
 interface ModelTurnResult {
@@ -211,6 +221,61 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/** One model a caller may pick. */
+interface ModelCatalogEntry {
+    /** What a client sends as `model` — and what the {@link ModelProvider} receives as `args.model`. */
+    id: string;
+    label: string;
+    description?: string;
+    /** Short tags a picker can render as chips — `'fast'`, `'reasoning'`, `'vision'`, `'new'`, … */
+    badges?: string[];
+    /** `false` → listed but not selectable right now (plan, quota, outage); a send naming it is refused. */
+    available: boolean;
+    /** Why it is unavailable, in words a picker can show. */
+    unavailableReason?: string;
+    /** Context window, in tokens, when the host knows it. */
+    contextWindow?: number;
+}
+/** Models grouped under the provider that serves them. */
+interface ModelCatalogProviderGroup {
+    id: string;
+    label: string;
+    models: ModelCatalogEntry[];
+}
+/** What `GET <base>/models` answers. */
+interface ModelCatalogView {
+    providers: ModelCatalogProviderGroup[];
+    /** The model a turn runs on when nobody picked one; `null` when the provider decides. */
+    default: string | null;
+}
+interface ModelCatalogQuery {
+    actor: Actor;
+    /** The agent the picker is for; omitted → the default agent. */
+    agent?: string;
+}
+/**
+ * Which models a caller may run a turn on — the picker's data and the send's gate. The server
+ * refuses a `model` (on a send, or pinned on a thread) that this does not list as `available` for
+ * the actor and agent, so a client cannot pick a model the host did not offer it.
+ *
+ * Bind with `AgentModule.forRoot({ models })`. Without one, `GET <base>/models` answers an empty
+ * catalog and a request naming a model is refused.
+ */
+interface ModelCatalog {
+    list(query: ModelCatalogQuery): ModelCatalogView | Promise<ModelCatalogView>;
+}
+/** A catalog that answers the same view to everyone — for a fixed list of models. */
+declare function staticModelCatalog(view: ModelCatalogView): ModelCatalog;
+/** The entry `id` names in `view`, or `undefined`. */
+declare function findCatalogModel(view: ModelCatalogView, id: string): ModelCatalogEntry | undefined;
+/**
+ * A provider that runs every turn on `model` — what the loop wraps the bound provider in when a
+ * turn has a selected model, so every call it makes (the answer, a structured-output pass, the
+ * follow-up suggestions) goes to the same one. A provider that does not read `args.model` runs its
+ * own default, unchanged.
+ */
+declare function withSelectedModel(provider: ModelProvider, model: string): ModelProvider;
+
 /** What a model turn streamed that the persisted message keeps, beyond its text and tool calls. */
 interface TurnFrameSummary {
     reasoning?: string;
@@ -344,6 +409,8 @@ interface UpdateThreadInput {
     title?: string;
     /** `null` clears the thread's default agent (falls back to the module default). */
     defaultAgent?: string | null;
+    /** `null` unpins the thread's model (turns run on the provider default). */
+    model?: string | null;
 }
 interface RecordUsageInput {
     threadId: string;
@@ -579,6 +646,15 @@ interface AgentStore {
         usedTokens: number;
         costUsd: number;
     }>;
+    /**
+     * OPTIONAL: the actor's spend over the UTC days `fromDay`..`toDay` (`YYYY-MM-DD`, inclusive) —
+     * {@link quotaToday} over a range. Feeds the monthly window of `GET <base>/quota`; absent → that
+     * window is left out.
+     */
+    usageBetween?(actorRef: string, fromDay: string, toDay: string): Promise<{
+        usedTokens: number;
+        costUsd: number;
+    }>;
 }
 
 /**
@@ -603,6 +679,57 @@ interface QuotaStore {
     bump(actorRef: string, day: string, tokens: number): Promise<void>;
 }
 
+/** The span a quota window counts over, in UTC. */
+type QuotaPeriod = 'day' | 'month';
+/** One budget window: what was spent in it, and the ceiling when there is one. */
+interface QuotaWindow {
+    period: QuotaPeriod;
+    usedTokens: number;
+    /** Absent → no token ceiling on this window. */
+    limitTokens?: number;
+    usedUsd: number;
+    /** Absent → no spend ceiling on this window. */
+    limitUsd?: number;
+    /** ISO-8601 instant the window starts over (next UTC midnight, first of next month). */
+    resetsAt?: string;
+}
+/** Which window stopped the actor, when one did. */
+interface QuotaBlock {
+    period: QuotaPeriod;
+    /** Words a client can show ("Monthly AI budget reached"). */
+    reason?: string;
+}
+/** What `GET <base>/quota` answers. */
+interface QuotaReport {
+    windows: QuotaWindow[];
+    /** Present when a window is exhausted — a send will be refused until it resets. */
+    blocked?: QuotaBlock;
+}
+interface QuotaQuery {
+    actor: Actor;
+    /** The instant to report for; defaults to now. */
+    now?: Date;
+}
+/**
+ * The actor's budget across windows — the read behind `GET <base>/quota` and, when the host binds
+ * one (`AgentModule.forRoot({ quotaProvider })`), the gate a send passes: a report with `blocked`
+ * refuses the turn with `429` before it starts.
+ *
+ * The default reads the usage ledger (`LedgerQuotaProvider` in `@dudousxd/nestjs-agent`); a host
+ * with its own budget (an AI-gateway spend cap, a plan's monthly allowance) implements this.
+ */
+interface QuotaProvider {
+    report(query: QuotaQuery): Promise<QuotaReport>;
+}
+/** The first window whose token or spend ceiling is reached, as a {@link QuotaBlock}. */
+declare function exhaustedWindow(windows: readonly QuotaWindow[]): QuotaBlock | undefined;
+/** The UTC day range (`YYYY-MM-DD`, inclusive) and reset instant of `period` around `now`. */
+declare function quotaPeriodRange(period: QuotaPeriod, now: Date): {
+    fromDay: string;
+    toDay: string;
+    resetsAt: string;
+};
+
 /**
  * The WRITE side of the pricing table the {@link import('./governance-queries.js').AgentGovernanceQueries}
  * read-model prices usage against. Cost is $0 for an unpriced model, so an app seeds its models'
@@ -3109,7 +3236,7 @@ interface AgentLoopResult<TOutput = unknown> {
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
  * hooks that make the same loop body either in-process or a replay-safe durable workflow.
  */
-declare function runAgentLoop<TOutput = unknown>(deps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
+declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
 
 /** Payloads carried on each `aviary:agent:*` channel. */
 interface AgentRunStarted {
@@ -3343,4 +3470,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, e as AiToolCtx, f as AgentStreamEvent, A as Actor, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as MessageFeedback, l as ToolCallStatus, U as UsagePurpose, m as ToolSpec, Q as QuotaState, n as AgentRunInput, H as HumanReply, o as ToolKind, p as ToolCallApproval, T as ToolHandler, q as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, r as ProcessedPrompt, s as ModelAnswer, t as PageContext, u as AgentDefinition, v as AgentDelegation, D as DetachedDelivery, w as PromptBuilder, x as PromptContributor, y as ToolTransientRetrySetting, z as AgentIntake, B as Decision, E as ElicitationRequest, L as LlmStepEnvelope, C as ToolStepEnvelope } from './tool-BdW-LV1J.js';
-export { F as ASK_TOOL_DESCRIPTION, G as ASK_TOOL_NAME, J as AgentApprovalRequest, K as AgentApprovalSettlement, N as AgentCatalogEntry, R as AgentHistoryWindow, V as AskToolInput, W as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, X as DEFAULT_INTAKE_PREAMBLE, Y as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Z as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, _ as ELICITATION_INPUT_TYPES, $ as ElicitationInput, a0 as ElicitationInputType, a1 as ElicitationOption, a2 as ElicitationOutcome, a3 as ElicitationQuestion, a4 as ElicitationReply, a5 as ElicitationResult, a6 as HistoryPolicyContext, a7 as HistorySelection, a8 as HistorySummary, a9 as IncrementalGating, aa as InvokeWithTransientRetryOptions, ab as MAX_ASK_QUESTIONS, ac as MessageFeedbackValue, ad as MessageRole, ae as OutputRejectedError, af as OutputVerdict, ag as ProcessorFailedError, ah as PromptContext, ai as QuotaView, aj as ToolCallApprovalStatus, ak as ToolCatalogEntry, al as ToolConfirmation, am as ToolPresentation, an as ToolPresentationTone, ao as ToolResultField, ap as ToolResultView, aq as ToolStepCtx, ar as ToolTransientRetryNumbers, as as ToolTransientRetryOptions, at as askInputSchema, au as askToolDefinition, av as decodeStreamEvent, aw as encodeStreamEvent, ax as invokeWithTransientRetry, ay as isTransientToolError, az as isTypedQuestion, aA as normalizeElicitationReply, aB as questionOptions, aC as readElicitationInput, aD as readElicitationQuestions, aE as renderElicitationAnswers, aF as resolveElicitation, aG as resolveToolTransientRetryNumbers, aH as settleElicitation, aI as validateElicitationAnswer, aJ as validateElicitationValue } from './tool-BdW-LV1J.js';
+import { M as ModelMessage, a as ToolDefinition, b as ToolCallRequest, c as MessageUsage, d as AgentUiComponent, A as Actor, e as AiToolCtx, f as AgentStreamEvent, g as ThreadSummary, h as ThreadDetail, S as StoredMessage, i as ToolResult, j as MessageAttachment, k as MessageFeedback, l as ToolCallStatus, U as UsagePurpose, m as ToolSpec, Q as QuotaState, n as AgentRunInput, H as HumanReply, o as ToolKind, p as ToolCallApproval, T as ToolHandler, q as HistoryPolicy, O as OutputProcessor, P as ProcessorContext, I as InputProcessor, r as ProcessedPrompt, s as ModelAnswer, t as PageContext, u as AgentDefinition, v as AgentDelegation, D as DetachedDelivery, w as PromptBuilder, x as PromptContributor, y as ToolTransientRetrySetting, z as AgentIntake, B as Decision, E as ElicitationRequest, L as LlmStepEnvelope, C as ToolStepEnvelope } from './tool-fLRLs_f3.js';
+export { F as ASK_TOOL_DESCRIPTION, G as ASK_TOOL_NAME, J as AgentApprovalRequest, K as AgentApprovalSettlement, N as AgentCatalogEntry, R as AgentHistoryWindow, V as AskToolInput, W as DEFAULT_INCREMENTAL_LOOKBACK_CHARS, X as DEFAULT_INTAKE_PREAMBLE, Y as DEFAULT_TOOL_TRANSIENT_RETRY_ATTEMPTS, Z as DEFAULT_TOOL_TRANSIENT_RETRY_BACKOFF_MS, _ as ELICITATION_INPUT_TYPES, $ as ElicitationInput, a0 as ElicitationInputType, a1 as ElicitationOption, a2 as ElicitationOutcome, a3 as ElicitationQuestion, a4 as ElicitationReply, a5 as ElicitationResult, a6 as HistoryPolicyContext, a7 as HistorySelection, a8 as HistorySummary, a9 as IncrementalGating, aa as InvokeWithTransientRetryOptions, ab as MAX_ASK_QUESTIONS, ac as MessageFeedbackValue, ad as MessageRole, ae as OutputRejectedError, af as OutputVerdict, ag as ProcessorFailedError, ah as PromptContext, ai as QuotaView, aj as ToolCallApprovalStatus, ak as ToolCatalogEntry, al as ToolConfirmation, am as ToolPresentation, an as ToolPresentationTone, ao as ToolResultField, ap as ToolResultView, aq as ToolStepCtx, ar as ToolTransientRetryNumbers, as as ToolTransientRetryOptions, at as askInputSchema, au as askToolDefinition, av as decodeStreamEvent, aw as encodeStreamEvent, ax as invokeWithTransientRetry, ay as isTransientToolError, az as isTypedQuestion, aA as normalizeElicitationReply, aB as questionOptions, aC as readElicitationInput, aD as readElicitationQuestions, aE as renderElicitationAnswers, aF as resolveElicitation, aG as resolveToolTransientRetryNumbers, aH as settleElicitation, aI as validateElicitationAnswer, aJ as validateElicitationValue } from './tool-fLRLs_f3.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { ChannelRegistry } from '@dudousxd/nestjs-diagnostics';
 
@@ -32,6 +32,10 @@ declare const AGENT_REGISTRY: unique symbol;
 declare const AGENT_ACTOR_RESOLVER: unique symbol;
 /** The governance read-model (usage/spend/threads), consumed by the dashboard + telescope surfaces. */
 declare const AGENT_GOVERNANCE_QUERIES: unique symbol;
+/** The `QuotaProvider` behind `GET <base>/quota` (and, when the host binds one, the send gate). */
+declare const AGENT_QUOTA_PROVIDER: unique symbol;
+/** The `ModelCatalog` behind `GET <base>/models` and the model a send may name. Optional. */
+declare const AGENT_MODEL_CATALOG: unique symbol;
 /** The pricing WRITE side (`AgentPricingStore`) — seeds/updates the per-model rates cost is priced against. */
 declare const AGENT_PRICING_STORE: unique symbol;
 /** The RAG retrieval seam (`Retriever`) — vector/keyword search behind the agentic tool or inject mode. */
@@ -134,6 +138,12 @@ interface ModelTurnArgs {
      * the reply against the same schema either way, so ignoring it costs reliability, not safety.
      */
     outputSchema?: StandardSchemaV1;
+    /**
+     * The model the caller picked for this turn — a {@link import('./model-catalog.js').ModelCatalogEntry}
+     * id the server already checked against the catalog (a per-send `model`, else the thread's pinned
+     * one). Absent → the provider's own default. A provider serving a single model may ignore it.
+     */
+    model?: string;
 }
 /** The outcome of ONE assistant turn. The loop — not the model — drives tool execution. */
 interface ModelTurnResult {
@@ -211,6 +221,61 @@ interface ModelProvider {
     runTurn(args: ModelTurnArgs): Promise<ModelTurnResult>;
 }
 
+/** One model a caller may pick. */
+interface ModelCatalogEntry {
+    /** What a client sends as `model` — and what the {@link ModelProvider} receives as `args.model`. */
+    id: string;
+    label: string;
+    description?: string;
+    /** Short tags a picker can render as chips — `'fast'`, `'reasoning'`, `'vision'`, `'new'`, … */
+    badges?: string[];
+    /** `false` → listed but not selectable right now (plan, quota, outage); a send naming it is refused. */
+    available: boolean;
+    /** Why it is unavailable, in words a picker can show. */
+    unavailableReason?: string;
+    /** Context window, in tokens, when the host knows it. */
+    contextWindow?: number;
+}
+/** Models grouped under the provider that serves them. */
+interface ModelCatalogProviderGroup {
+    id: string;
+    label: string;
+    models: ModelCatalogEntry[];
+}
+/** What `GET <base>/models` answers. */
+interface ModelCatalogView {
+    providers: ModelCatalogProviderGroup[];
+    /** The model a turn runs on when nobody picked one; `null` when the provider decides. */
+    default: string | null;
+}
+interface ModelCatalogQuery {
+    actor: Actor;
+    /** The agent the picker is for; omitted → the default agent. */
+    agent?: string;
+}
+/**
+ * Which models a caller may run a turn on — the picker's data and the send's gate. The server
+ * refuses a `model` (on a send, or pinned on a thread) that this does not list as `available` for
+ * the actor and agent, so a client cannot pick a model the host did not offer it.
+ *
+ * Bind with `AgentModule.forRoot({ models })`. Without one, `GET <base>/models` answers an empty
+ * catalog and a request naming a model is refused.
+ */
+interface ModelCatalog {
+    list(query: ModelCatalogQuery): ModelCatalogView | Promise<ModelCatalogView>;
+}
+/** A catalog that answers the same view to everyone — for a fixed list of models. */
+declare function staticModelCatalog(view: ModelCatalogView): ModelCatalog;
+/** The entry `id` names in `view`, or `undefined`. */
+declare function findCatalogModel(view: ModelCatalogView, id: string): ModelCatalogEntry | undefined;
+/**
+ * A provider that runs every turn on `model` — what the loop wraps the bound provider in when a
+ * turn has a selected model, so every call it makes (the answer, a structured-output pass, the
+ * follow-up suggestions) goes to the same one. A provider that does not read `args.model` runs its
+ * own default, unchanged.
+ */
+declare function withSelectedModel(provider: ModelProvider, model: string): ModelProvider;
+
 /** What a model turn streamed that the persisted message keeps, beyond its text and tool calls. */
 interface TurnFrameSummary {
     reasoning?: string;
@@ -344,6 +409,8 @@ interface UpdateThreadInput {
     title?: string;
     /** `null` clears the thread's default agent (falls back to the module default). */
     defaultAgent?: string | null;
+    /** `null` unpins the thread's model (turns run on the provider default). */
+    model?: string | null;
 }
 interface RecordUsageInput {
     threadId: string;
@@ -579,6 +646,15 @@ interface AgentStore {
         usedTokens: number;
         costUsd: number;
     }>;
+    /**
+     * OPTIONAL: the actor's spend over the UTC days `fromDay`..`toDay` (`YYYY-MM-DD`, inclusive) —
+     * {@link quotaToday} over a range. Feeds the monthly window of `GET <base>/quota`; absent → that
+     * window is left out.
+     */
+    usageBetween?(actorRef: string, fromDay: string, toDay: string): Promise<{
+        usedTokens: number;
+        costUsd: number;
+    }>;
 }
 
 /**
@@ -603,6 +679,57 @@ interface QuotaStore {
     bump(actorRef: string, day: string, tokens: number): Promise<void>;
 }
 
+/** The span a quota window counts over, in UTC. */
+type QuotaPeriod = 'day' | 'month';
+/** One budget window: what was spent in it, and the ceiling when there is one. */
+interface QuotaWindow {
+    period: QuotaPeriod;
+    usedTokens: number;
+    /** Absent → no token ceiling on this window. */
+    limitTokens?: number;
+    usedUsd: number;
+    /** Absent → no spend ceiling on this window. */
+    limitUsd?: number;
+    /** ISO-8601 instant the window starts over (next UTC midnight, first of next month). */
+    resetsAt?: string;
+}
+/** Which window stopped the actor, when one did. */
+interface QuotaBlock {
+    period: QuotaPeriod;
+    /** Words a client can show ("Monthly AI budget reached"). */
+    reason?: string;
+}
+/** What `GET <base>/quota` answers. */
+interface QuotaReport {
+    windows: QuotaWindow[];
+    /** Present when a window is exhausted — a send will be refused until it resets. */
+    blocked?: QuotaBlock;
+}
+interface QuotaQuery {
+    actor: Actor;
+    /** The instant to report for; defaults to now. */
+    now?: Date;
+}
+/**
+ * The actor's budget across windows — the read behind `GET <base>/quota` and, when the host binds
+ * one (`AgentModule.forRoot({ quotaProvider })`), the gate a send passes: a report with `blocked`
+ * refuses the turn with `429` before it starts.
+ *
+ * The default reads the usage ledger (`LedgerQuotaProvider` in `@dudousxd/nestjs-agent`); a host
+ * with its own budget (an AI-gateway spend cap, a plan's monthly allowance) implements this.
+ */
+interface QuotaProvider {
+    report(query: QuotaQuery): Promise<QuotaReport>;
+}
+/** The first window whose token or spend ceiling is reached, as a {@link QuotaBlock}. */
+declare function exhaustedWindow(windows: readonly QuotaWindow[]): QuotaBlock | undefined;
+/** The UTC day range (`YYYY-MM-DD`, inclusive) and reset instant of `period` around `now`. */
+declare function quotaPeriodRange(period: QuotaPeriod, now: Date): {
+    fromDay: string;
+    toDay: string;
+    resetsAt: string;
+};
+
 /**
  * The WRITE side of the pricing table the {@link import('./governance-queries.js').AgentGovernanceQueries}
  * read-model prices usage against. Cost is $0 for an unpriced model, so an app seeds its models'
@@ -3109,7 +3236,7 @@ interface AgentLoopResult<TOutput = unknown> {
  * It drives the model→tools→model iteration; the runner supplies the `step`/`awaitApproval`
  * hooks that make the same loop body either in-process or a replay-safe durable workflow.
  */
-declare function runAgentLoop<TOutput = unknown>(deps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
+declare function runAgentLoop<TOutput = unknown>(boundDeps: AgentLoopDeps<TOutput>, input: AgentRunInput, hooks: AgentLoopHooks): Promise<AgentLoopResult<TOutput>>;
 
 /** Payloads carried on each `aviary:agent:*` channel. */
 interface AgentRunStarted {
@@ -3343,4 +3470,4 @@ type AgentDiagnosticKey = `agent:${AgentDiagnosticEvent}`;
  */
 declare function agentDiagnosticKey(event: AgentDiagnosticEvent): AgentDiagnosticKey;
 
-export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, QuotaExceededError, QuotaState, type QuotaStore, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };
+export { AGENT_ACTOR_DIRECTORY, AGENT_ACTOR_RESOLVER, AGENT_APPROVAL_PORT, AGENT_ATTACHMENT_STAGING, AGENT_DEPS_FACTORY, AGENT_DIAGNOSTIC_EVENTS, AGENT_DURABLE_RUNNER, AGENT_EMBEDDING_PROVIDER, AGENT_GOVERNANCE_QUERIES, AGENT_MEMORY, AGENT_MODEL, AGENT_MODEL_CATALOG, AGENT_OPTIONS, AGENT_PRICING_STORE, AGENT_PROMPT_CONTRIBUTORS, AGENT_QUOTA_PROVIDER, AGENT_QUOTA_STORE, AGENT_REGISTRY, AGENT_RETRIEVER, AGENT_ROLES_POLICY, AGENT_RUNNER, AGENT_SINK, AGENT_SKILLS, AGENT_SKILL_SOURCES, AGENT_SPAN_EVENTS, AGENT_STORE, AGENT_TOOL_REGISTRY, APPROVAL_EXPIRED_REASON, Actor, type ActorDirectory, type ActorResolver, type ActorSpendRow, type AgentApprovalPort, AgentDefinition, type AgentDelegated, AgentDelegation, type AgentDiagnosticEvent, type AgentDiagnosticKey, type AgentFollowUpsSpan, type AgentGovernanceQueries, AgentIntake, type AgentLlmTurnSpan, type AgentLoopDeps, type AgentLoopHooks, type AgentLoopResult, type AgentMemoryResolved, type AgentMemoryWritten, type AgentMessageEvent, type AgentPricingStore, type AgentQuotaExceeded, AgentRegistry, type AgentRetrievalSpan, type AgentRetrieved, type AgentRunFailed, type AgentRunFinished, AgentRunInput, type AgentRunStarted, type AgentRunner, type AgentSkillsResolved, type AgentSpanEvent, type AgentStore, AgentStreamError, AgentStreamEvent, type AgentStructuredOutputSpan, type AgentToolCallEvent, type AgentToolExecutionSpan, type AgentToolRetry, AgentUiComponent, AiToolCtx, type AppendMessageInput, type ApprovalDecisionRef, type ApprovalPolicy, type ApprovalRequirement, type ApprovalThreadRef, type ApprovalToolRef, type ApprovalWhere, type AttachmentRef, type AttachmentStagingStore, type BufferedModelTurnResult, type BuildMemoryBlockInput, type CostUsage, type CreateThreadInput, type CurrentModelPrice, DEFAULT_HISTORY_SUMMARY_INSTRUCTION, DEFAULT_MAX_FACT_CHARS, DEFAULT_MAX_MEMORIES, DEFAULT_MAX_SKILLS, DEFAULT_REFUSAL_REASON, DEFAULT_STRUCTURED_OUTPUT_INSTRUCTION, Decision, DefaultApprovalPolicy, DefaultRolesPolicy, type DetachedDelegationOutcome, type DetachedDelegationReceipt, DetachedDelivery, type DetailThreadRef, ElicitationRequest, type EmbeddingProvider, type EmitUi, type ForgetMemoryInput, type FrameBuffer, GLOBAL_SCOPE, type GovernancePage, type GovernancePageQuery, type GovernanceRange, type GovernanceRunDetail, type GovernanceThreadDetail, type GovernanceThreadDetailQuery, type GovernanceUsageInput, HistoryPolicy, HumanReply, type IncrementalGate, InputProcessor, type ListMemoriesInput, type ListSkillsInput, type ListStagedAttachmentsInput, LlmStepEnvelope, type LoadSkillInput, type MemoryAuthor, type MemoryConfig, type MemoryDigest, type MemoryDigestEntry, type MemoryFact, type MemoryForgetRequest, type MemoryOrigin, type MemoryProvider, type MemoryRecord, type MemoryVerdict, type MemoryWriteOutcome, type MemoryWriteRequest, MessageAttachment, MessageFeedback, MessageUsage, ModelAnswer, type ModelCatalog, type ModelCatalogEntry, type ModelCatalogProviderGroup, type ModelCatalogQuery, type ModelCatalogView, ModelMessage, type ModelPrice, type ModelPriceInput, type ModelProvider, type ModelSpendRow, type ModelTurnArgs, type ModelTurnResult, type ObservedTurnFrames, type OfferMemoriesInput, type OutputGateMode, type OutputGateResult, OutputProcessor, type OverriddenMemory, PageContext, type Passage, type PendingApprovalRow, ProcessedPrompt, ProcessorContext, PromptBuilder, PromptContributor, type QuotaBlock, QuotaExceededError, type QuotaPeriod, type QuotaProvider, type QuotaQuery, type QuotaReport, QuotaState, type QuotaStore, type QuotaWindow, REMEMBER_TOOL_DESCRIPTION, REMEMBER_TOOL_NAME, REQUESTER_APPROVER, type RecentRunRow, type RecordRunEndInput, type RecordRunStartInput, type RecordToolCallInput, type RecordUsageInput, type RememberToolInput, type RerankOptions, type Reranker, type ResolveAttachmentInput, type ResolveMemoryDigestInput, type ResolvedDelegation, type RetrieveOptions, type Retriever, type RolesPolicy, type RunAgentBreakdownRow, RunCancelledError, type RunErrorBreakdownRow, type RunMetrics, type RunToolCallRow, type RunTrendPoint, type RunWhere, SKILL_TOOL_DESCRIPTION, SKILL_TOOL_NAME, type ScopeContext, type ScopeResolver, type SearchMemoriesInput, type SettledTask, type SinkWriter, type Skill, type SkillAuthor, type SkillCatalogEntry, type SkillContext, type SkillLoadOutcome, type SkillOffer, type SkillProvider, type SkillSummary, type SkillToolInput, type SkillWriteRequest, type SkillWriteVerdict, type SkillsConfig, type StageAttachmentInput, type StagedAttachment, type StoreMemoryInput, StoredMessage, type StreamError, type StructuredOutcome, StructuredOutputError, THREAD_DETAIL_CONTENT_CHARS, type ThreadActivityRow, ThreadDetail, type ThreadMessageRow, type ThreadMeta, type ThreadSpendRow, ThreadSummary, type ThreadTurnPage, type ThreadTurnQuery, type ThreadTurnReader, type ThreadUsageRollup, type ThreadWhere, type TokenStreamSink, type ToolCallActivityRow, ToolCallApproval, type ToolCallApprovalColumns, type ToolCallApprovalState, ToolCallRequest, ToolCallStatus, type ToolCallWhere, ToolDefinition, ToolDisabledError, ToolForbiddenError, ToolHandler, ToolInputInvalidError, ToolKind, type ToolKindDeps, ToolNotFoundError, ToolRegistry, ToolResult, ToolSpec, type ToolStatRow, ToolStepEnvelope, ToolTransientRetrySetting, type TurnFrameSummary, type UiCollector, type UpdateThreadInput, type UpdateToolCallInput, UsagePurpose, type UsageTrendPoint, type WindowHistoryOptions, type WithMemoryToolInput, type WriteMemoryInput, actorScope, agentDiagnosticKey, agentFailureCode, bucketByActor, bucketByModel, bucketByThread, bucketUsageTrend, buildMemoryBlock, buildSkillsBlock, canActorUseTool, compositeSkillProvider, createFrameBuffer, createIncrementalGate, createUiCollector, dayBoundsUtc, defaultCanDecide, defaultScopeResolver, detachedDelivered, detachedStarted, detachedUnsettled, estimateCost, estimateMessageTokens, exhaustedWindow, extractJson, filterToolsByAllowList, filterToolsByCanUse, filterToolsByEnabled, filterToolsByRole, findCatalogModel, gateFollowUps, gateTail, isControlFlowSignal, isReplayIntegrityError, isToolEnabled, loadSkill, mayDecideApproval, memoryForgetVerdict, memoryWriteVerdict, mergeUi, normalizeDelegation, observeTurnFrames, offerMemories, offerSkills, publishAgentDelegated, publishAgentMemoryResolved, publishAgentMemoryWritten, publishAgentMessage, publishAgentQuotaExceeded, publishAgentRetrieved, publishAgentRunFailed, publishAgentRunFinished, publishAgentRunStarted, publishAgentSkillsResolved, publishAgentToolCall, publishAgentToolRetry, quotaPeriodRange, releaseGatedFrames, rememberInputSchema, rememberToolDefinition, repairInstruction, resolveGateLookback, resolveMemoryDigest, resolveOutputGateMode, resolveSkillCatalog, rollupThreadUsage, runAgentLoop, runInputProcessors, runOutputProcessors, seedModelPrices, settleAll, settleUnsettledDelegation, skillInputSchema, skillToolDefinition, skillWriteVerdict, stampToolKinds, staticModelCatalog, staticSkillProvider, summarizeWithModel, tenantScope, toolCallApprovalFromRow, traceLlmTurn, traceToolExecution, truncateDetailContent, unwrapToolStepOutput, validateStructured, windowHistory, withAskTool, withMemoryTool, withSelectedModel, withSkillTool, withToolTimeout, withTurnFrames, wrapToolStepOutput, writeMemory };

package/dist/index.js

@@ -14,6 +14,8 @@ var AGENT_TOOL_REGISTRY = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:too
 var AGENT_REGISTRY = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:agent-registry");
 var AGENT_ACTOR_RESOLVER = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:actor-resolver");
 var AGENT_GOVERNANCE_QUERIES = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:governance-queries");
+var AGENT_QUOTA_PROVIDER = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:quota-provider");
+var AGENT_MODEL_CATALOG = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:model-catalog");
 var AGENT_PRICING_STORE = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:pricing-store");
 var AGENT_RETRIEVER = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:retriever");
 var AGENT_EMBEDDING_PROVIDER = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:embedding-provider");
@@ -26,6 +28,31 @@ var AGENT_SKILLS = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:skills");
 var AGENT_MEMORY = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:memory");
 var AGENT_SKILL_SOURCES = /* @__PURE__ */ Symbol.for("@dudousxd/nestjs-agent:skill-sources");
 
+// src/spi/model-catalog.ts
+function staticModelCatalog(view) {
+  return {
+    list: /* @__PURE__ */ __name(() => view, "list")
+  };
+}
+__name(staticModelCatalog, "staticModelCatalog");
+function findCatalogModel(view, id) {
+  for (const group of view.providers) {
+    const found = group.models.find((model) => model.id === id);
+    if (found !== void 0) return found;
+  }
+  return void 0;
+}
+__name(findCatalogModel, "findCatalogModel");
+function withSelectedModel(provider, model) {
+  return {
+    runTurn: /* @__PURE__ */ __name((args) => provider.runTurn({
+      ...args,
+      model
+    }), "runTurn")
+  };
+}
+__name(withSelectedModel, "withSelectedModel");
+
 // src/spi/token-stream-sink.ts
 var AgentStreamError = class extends Error {
   static {
@@ -246,6 +273,43 @@ function mergeUi(...lists) {
 }
 __name(mergeUi, "mergeUi");
 
+// src/spi/quota-provider.ts
+function exhaustedWindow(windows) {
+  for (const window of windows) {
+    const tokensOut = window.limitTokens !== void 0 && window.usedTokens >= window.limitTokens;
+    const spendOut = window.limitUsd !== void 0 && window.usedUsd >= window.limitUsd;
+    if (tokensOut || spendOut) {
+      return {
+        period: window.period,
+        reason: `${window.period === "day" ? "Daily" : "Monthly"} ${spendOut ? "spend" : "token"} limit reached`
+      };
+    }
+  }
+  return void 0;
+}
+__name(exhaustedWindow, "exhaustedWindow");
+function quotaPeriodRange(period, now) {
+  const year = now.getUTCFullYear();
+  const month = now.getUTCMonth();
+  const day = now.toISOString().slice(0, 10);
+  if (period === "day") {
+    const next = new Date(Date.UTC(year, month, now.getUTCDate() + 1));
+    return {
+      fromDay: day,
+      toDay: day,
+      resetsAt: next.toISOString()
+    };
+  }
+  const first = new Date(Date.UTC(year, month, 1));
+  const last = new Date(Date.UTC(year, month + 1, 0));
+  return {
+    fromDay: first.toISOString().slice(0, 10),
+    toDay: last.toISOString().slice(0, 10),
+    resetsAt: new Date(Date.UTC(year, month + 1, 1)).toISOString()
+  };
+}
+__name(quotaPeriodRange, "quotaPeriodRange");
+
 // src/spi/pricing-store.ts
 async function seedModelPrices(store, prices) {
   for (const price of prices) {
@@ -3922,7 +3986,12 @@ async function invokeClaimedToolsTogether(turn, parallel, claimed) {
   return results;
 }
 __name(invokeClaimedToolsTogether, "invokeClaimedToolsTogether");
-async function runAgentLoop(deps, input, hooks) {
+async function runAgentLoop(boundDeps, input, hooks) {
+  const deps = input.model === void 0 ? boundDeps : {
+    ...boundDeps,
+    model: withSelectedModel(boundDeps.model, input.model),
+    modelId: input.model
+  };
   const maxSteps = deps.maxSteps ?? 8;
   let system = await resolveSystemPrompt(deps, input);
   const inputProcessors = deps.inputProcessors ?? [];
@@ -4119,6 +4188,9 @@ ${block}`;
         actor: input.actor,
         ...gated ? {
           bufferOutput: true
+        } : {},
+        ...input.model !== void 0 ? {
+          model: input.model
         } : {}
       });
     } else {
@@ -4537,9 +4609,11 @@ export {
   AGENT_GOVERNANCE_QUERIES,
   AGENT_MEMORY,
   AGENT_MODEL,
+  AGENT_MODEL_CATALOG,
   AGENT_OPTIONS,
   AGENT_PRICING_STORE,
   AGENT_PROMPT_CONTRIBUTORS,
+  AGENT_QUOTA_PROVIDER,
   AGENT_QUOTA_STORE,
   AGENT_REGISTRY,
   AGENT_RETRIEVER,
@@ -4613,11 +4687,13 @@ export {
   encodeStreamEvent,
   estimateCost,
   estimateMessageTokens,
+  exhaustedWindow,
   extractJson,
   filterToolsByAllowList,
   filterToolsByCanUse,
   filterToolsByEnabled,
   filterToolsByRole,
+  findCatalogModel,
   gateFollowUps,
   gateTail,
   invokeWithTransientRetry,
@@ -4649,6 +4725,7 @@ export {
   publishAgentToolCall,
   publishAgentToolRetry,
   questionOptions,
+  quotaPeriodRange,
   readElicitationInput,
   readElicitationQuestions,
   releaseGatedFrames,
@@ -4674,6 +4751,7 @@ export {
   skillToolDefinition,
   skillWriteVerdict,
   stampToolKinds,
+  staticModelCatalog,
   staticSkillProvider,
   summarizeWithModel,
   tenantScope,
@@ -4688,6 +4766,7 @@ export {
   windowHistory,
   withAskTool,
   withMemoryTool,
+  withSelectedModel,
   withSkillTool,
   withToolTimeout,
   withTurnFrames,