@dudousxd/nestjs-agent 0.3.2 → 0.4.0

package/dist/index.d.cts

@@ -1,8 +1,9 @@
-import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
-import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-DpVkZYCy.cjs';
-export { c as AGENT_TOOL_BRAND, d as AgentDeps, F as FunctionalTool, e as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-DpVkZYCy.cjs';
-import { AgentRunner, AgentStore, QuotaStore, Actor, PageContext, ThreadSummary, ThreadDetail, QuotaView, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaState, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
+import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-BM_RB6br.cjs';
+export { c as AGENT_TOOL_BRAND, d as AgentAttachmentsOptions, e as AgentDeps, F as FunctionalTool, f as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-BM_RB6br.cjs';
+import { AgentRunner, AgentStore, QuotaStore, Actor, MessageAttachment, PageContext, ThreadSummary, ThreadDetail, UpdateThreadInput, QuotaView, ActorResolver, AttachmentStagingStore, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
+import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -16,6 +17,8 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
+    /** Files attached to this message (image/PDF) for a vision-capable model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
     regenerate?: boolean;
@@ -44,7 +47,24 @@ declare class AgentService {
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
     deleteThread(actor: Actor, threadId: string): Promise<void>;
     forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
     renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
+    /**
+     * Rename a thread and/or set its default agent. Title-only patches work against ANY store (via
+     * the required `setTitle`); a `defaultAgent` change requires the bound store to implement the
+     * optional `updateThread` — 501 with a clear message when it doesn't, rather than silently
+     * dropping the field.
+     */
+    updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    private validateTitle;
+    /**
+     * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
+     * `defaultAgent` (if the thread exists and one is set) wins over the module's configured default.
+     * Skips the thread lookup entirely when the caller already named an agent or there's no thread yet.
+     */
+    private resolveAgentName;
+    private toSummaryView;
+    private toDetailView;
     promoteThread(actor: Actor, threadId: string): Promise<void>;
     /**
      * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
@@ -74,6 +94,34 @@ declare class AgentService {
     private assertOwnsActiveStream;
 }
 
+/** Default per-file size cap when `AgentModuleOptions.attachments.maxBytes` is omitted (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/**
+ * Default allowlist: what multimodal model providers commonly accept as native image/file parts.
+ */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/**
+ * Optional `POST /agent/attachments` upload surface — mounted only when `AgentModuleOptions
+ * .attachments.upload` (or the async config's `attachmentsUpload`) is `true` (see `agent.module.ts`).
+ * Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
+ * default storage), validated against the configured size cap + content-type allowlist, then handed
+ * to the bound {@link AttachmentStagingStore} to persist and turn into a model-fetchable URL.
+ */
+declare class AttachmentsController implements OnModuleInit {
+    private readonly options;
+    private readonly actorResolver;
+    private readonly staging;
+    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, staging: AttachmentStagingStore | undefined);
+    /**
+     * `attachments.upload: true` is what mounts this controller at all (see `agent.module.ts`), so by
+     * the time an instance exists the host clearly intends uploads to work. Fail boot loudly rather
+     * than mounting a controller that would 501 on every single request because nobody bound
+     * `AGENT_ATTACHMENT_STAGING`.
+     */
+    onModuleInit(): void;
+    upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
+}
+
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
     name: string;
@@ -284,4 +332,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, type ChatParams, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };
+export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };

package/dist/index.d.ts

@@ -1,8 +1,9 @@
-import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
-import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-DpVkZYCy.js';
-export { c as AGENT_TOOL_BRAND, d as AgentDeps, F as FunctionalTool, e as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-DpVkZYCy.js';
-import { AgentRunner, AgentStore, QuotaStore, Actor, PageContext, ThreadSummary, ThreadDetail, QuotaView, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaState, ActorResolver } from '@dudousxd/nestjs-agent-core';
+import { DynamicModule, OnModuleInit, Type, OnApplicationBootstrap } from '@nestjs/common';
+import { a as AgentModuleOptions, b as AgentModuleAsyncOptions, A as AgentDepsFactory } from './agent-deps.factory-BM_RB6br.js';
+export { c as AGENT_TOOL_BRAND, d as AgentAttachmentsOptions, e as AgentDeps, F as FunctionalTool, f as delegateToolName, p as provideAgentTool, u as utcDay } from './agent-deps.factory-BM_RB6br.js';
+import { AgentRunner, AgentStore, QuotaStore, Actor, MessageAttachment, PageContext, ThreadSummary, ThreadDetail, UpdateThreadInput, QuotaView, ActorResolver, AttachmentStagingStore, ToolRegistry, AgentRegistry, PromptContributor, AgentRunInput, Decision, TokenStreamSink, SinkWriter, QuotaState } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
+import { Request } from 'express';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { DiscoveryService, MetadataScanner } from '@nestjs/core';
 
@@ -16,6 +17,8 @@ interface ChatParams {
     message: string;
     threadId?: string;
     agentName?: string;
+    /** Files attached to this message (image/PDF) for a vision-capable model. */
+    attachments?: MessageAttachment[];
     pageContext?: PageContext;
     /** Re-run the last exchange instead of adding a new message. Requires an existing `threadId`. */
     regenerate?: boolean;
@@ -44,7 +47,24 @@ declare class AgentService {
     getThread(actor: Actor, threadId: string): Promise<ThreadDetail | null>;
     deleteThread(actor: Actor, threadId: string): Promise<void>;
     forkThread(actor: Actor, threadId: string, fromMessageId: string): Promise<ThreadSummary>;
+    /** Kept for source compatibility — a thin wrapper over the more general `updateThread`. */
     renameThread(actor: Actor, threadId: string, title: string): Promise<void>;
+    /**
+     * Rename a thread and/or set its default agent. Title-only patches work against ANY store (via
+     * the required `setTitle`); a `defaultAgent` change requires the bound store to implement the
+     * optional `updateThread` — 501 with a clear message when it doesn't, rather than silently
+     * dropping the field.
+     */
+    updateThread(actor: Actor, threadId: string, patch: UpdateThreadInput): Promise<void>;
+    private validateTitle;
+    /**
+     * Agent-selection precedence for a `chat()` call with no explicit `agentName`: the thread's own
+     * `defaultAgent` (if the thread exists and one is set) wins over the module's configured default.
+     * Skips the thread lookup entirely when the caller already named an agent or there's no thread yet.
+     */
+    private resolveAgentName;
+    private toSummaryView;
+    private toDetailView;
     promoteThread(actor: Actor, threadId: string): Promise<void>;
     /**
      * Drop a message and everything after it — the "edit and resend" / "delete from here" primitive.
@@ -74,6 +94,34 @@ declare class AgentService {
     private assertOwnsActiveStream;
 }
 
+/** Default per-file size cap when `AgentModuleOptions.attachments.maxBytes` is omitted (20 MiB). */
+declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
+/**
+ * Default allowlist: what multimodal model providers commonly accept as native image/file parts.
+ */
+declare const DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES: readonly string[];
+/**
+ * Optional `POST /agent/attachments` upload surface — mounted only when `AgentModuleOptions
+ * .attachments.upload` (or the async config's `attachmentsUpload`) is `true` (see `agent.module.ts`).
+ * Multipart single file field `'file'`, buffered in memory (no disk write — `FileInterceptor`'s
+ * default storage), validated against the configured size cap + content-type allowlist, then handed
+ * to the bound {@link AttachmentStagingStore} to persist and turn into a model-fetchable URL.
+ */
+declare class AttachmentsController implements OnModuleInit {
+    private readonly options;
+    private readonly actorResolver;
+    private readonly staging;
+    constructor(options: AgentModuleOptions, actorResolver: ActorResolver, staging: AttachmentStagingStore | undefined);
+    /**
+     * `attachments.upload: true` is what mounts this controller at all (see `agent.module.ts`), so by
+     * the time an instance exists the host clearly intends uploads to work. Fail boot loudly rather
+     * than mounting a controller that would 501 on every single request because nobody bound
+     * `AGENT_ATTACHMENT_STAGING`.
+     */
+    onModuleInit(): void;
+    upload(req: Request, file: Express.Multer.File | undefined): Promise<MessageAttachment>;
+}
+
 declare const AI_TOOL_METADATA: unique symbol;
 interface AiToolOptions {
     name: string;
@@ -284,4 +332,4 @@ declare class HeaderActorResolver implements ActorResolver {
     resolve(req: unknown): Actor;
 }
 
-export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, type ChatParams, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };
+export { AGENT_METADATA, AI_TOOL_METADATA, Agent, AgentDepsFactory, AgentDiscoveryService, AgentModule, AgentModuleAsyncOptions, AgentModuleOptions, type AgentOptions, AgentService, AiTool, AiToolDiscoveryService, type AiToolOptions, AttachmentsController, type ChatParams, DEFAULT_ALLOWED_ATTACHMENT_CONTENT_TYPES, DEFAULT_MAX_ATTACHMENT_BYTES, HeaderActorResolver, InProcessTokenStreamSink, InlineAgentRunner, LedgerQuotaStore, SYSTEM_PROMPT_CONTRIBUTOR_METADATA, SYSTEM_PROMPT_METADATA, SystemPrompt, SystemPromptContributor, readAgentMetadata, readAiToolMetadata };