@dudousxd/nestjs-agent 1.22.0 → 1.23.1

package/dist/index.d.cts

@@ -1,8 +1,8 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-Dx9OsjcF.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 defineTool, p as delegateToolName, q as provideAgentTool, r as provideAgentTools, u as utcDay } from './chat-queue.service-Dx9OsjcF.cjs';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-D1z3WjFI.cjs';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-D1z3WjFI.cjs';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -96,6 +96,14 @@ interface ChatParams {
     uiCapabilities?: UiCapabilities;
     actor: Actor;
     message: string;
+    /** The host's own facts about this send — see `AgentRunInput.hostContext`. */
+    hostContext?: AgentHostContext;
+    /**
+     * The HOST already decided this actor may write this thread — a chat-app thread several people
+     * share, where anyone in it may continue the conversation. Skips the thread-ownership check of a
+     * send; never set it from a request's own claim.
+     */
+    authorized?: boolean;
     threadId?: string;
     agentName?: string;
     /**
@@ -531,7 +539,10 @@ declare class AgUiRunHandler {
     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. */
+    /**
+     * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+     * through the bound store — all within the store's limits; say what was not used.
+     */
     private stage;
     /**
      * Deliver what a resume list decided, through the same calls the native decision routes make.

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { DynamicModule, Type, OnApplicationBootstrap, OnModuleInit, ConflictException, OnModuleDestroy } from '@nestjs/common';
-import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CTyX_yNr.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 defineTool, p as delegateToolName, q as provideAgentTool, r as provideAgentTools, u as utcDay } from './chat-queue.service-CTyX_yNr.js';
+import { b as AgentModuleOptions, c as AgentModuleAsyncOptions, A as AgentDepsFactory, C as ChatQueueService, d as AgentProtocolAdapter, e as AgentSkillsOptions } from './chat-queue.service-CwxJDrBM.js';
+export { f as AGENT_TOOL_BRAND, g as AgentAttachmentsOptions, h as AgentDeps, i as AgentEngine, j as AgentMemoryOptions, a as AgentSurface, F as FunctionalTool, L as LedgerQuotaProvider, Q as QueuePlan, k as QueueSettleOutcome, l as QueuedTurn, m as QueuedTurnStarter, n as QuotaLimits, o as QuotaWindowLimits, p as defineTool, q as delegateToolName, r as provideAgentTool, s as provideAgentTools, u as utcDay } from './chat-queue.service-CwxJDrBM.js';
 import * as _dudousxd_nestjs_agent_core from '@dudousxd/nestjs-agent-core';
-import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
+import { AgentStore, Actor, ListActionProposals, ActionProposalMutationView, AgentRunner, AttachmentStagingStore, ModelCatalog, QuotaProvider, QuotaReport, ModelCatalogView, AgentHostContext, AttachmentRef, PageContext, ChatQueueState, HumanReply, ThreadSummary, ThreadDetail, UpdateThreadInput, MessageFeedbackValue, MessageFeedback, StagedAttachment, ActorResolver, AgentApprovalPort, MessageAttachment, AgentAttachmentConfig, AgentClientConfig, ToolSpec, ToolPresentation, AgentHistoryWindow, AgentIntake, Persona, SkillContext, ToolRegistry, AgentRegistry, PromptContributor, SkillsConfig, SkillCatalogEntry, ToolCatalogEntry, MemoryConfig, MemoryDigestEntry, SkillProvider, AgentRunInput, AgentRunStartOptions, TokenStreamSink, SinkWriter } from '@dudousxd/nestjs-agent-core';
 export * from '@dudousxd/nestjs-agent-core';
 export { FunctionalToolDefinition } from '@dudousxd/nestjs-agent-core';
 import { Request, Response } from 'express';
@@ -96,6 +96,14 @@ interface ChatParams {
     uiCapabilities?: UiCapabilities;
     actor: Actor;
     message: string;
+    /** The host's own facts about this send — see `AgentRunInput.hostContext`. */
+    hostContext?: AgentHostContext;
+    /**
+     * The HOST already decided this actor may write this thread — a chat-app thread several people
+     * share, where anyone in it may continue the conversation. Skips the thread-ownership check of a
+     * send; never set it from a request's own claim.
+     */
+    authorized?: boolean;
     threadId?: string;
     agentName?: string;
     /**
@@ -531,7 +539,10 @@ declare class AgUiRunHandler {
     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. */
+    /**
+     * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+     * through the bound store — all within the store's limits; say what was not used.
+     */
     private stage;
     /**
      * Deliver what a resume list decided, through the same calls the native decision routes make.

package/dist/index.js

@@ -1092,6 +1092,9 @@ var ChatQueueService = class _ChatQueueService {
       } : {},
       ...input.uiCapabilities !== void 0 ? {
         uiCapabilities: input.uiCapabilities
+      } : {},
+      ...input.hostContext !== void 0 ? {
+        hostContext: input.hostContext
       } : {}
     });
     await store.setQueuePause(threadId, {
@@ -1177,6 +1180,9 @@ var ChatQueueService = class _ChatQueueService {
       ...message.uiCapabilities !== void 0 ? {
         uiCapabilities: message.uiCapabilities
       } : {},
+      ...message.hostContext !== void 0 ? {
+        hostContext: message.hostContext
+      } : {},
       ...message.model !== void 0 ? {
         model: message.model
       } : {}
@@ -1547,6 +1553,9 @@ var AgentService = class {
       }
       const created = await this.store.createThread({
         actor: params.actor,
+        ...agentName !== void 0 ? {
+          agentName
+        } : {},
         ...params.transient === true ? {
           transient: true
         } : {},
@@ -1559,7 +1568,7 @@ var AgentService = class {
       });
       threadId = created.id;
     } else {
-      await this.assertOwnsThread(params.actor, threadId);
+      if (params.authorized !== true) await this.assertOwnsThread(params.actor, threadId);
       if (params.personaId !== void 0) {
         await this.pinThreadPersona(threadId, params.personaId);
       }
@@ -1585,6 +1594,9 @@ var AgentService = class {
       ...params.uiCapabilities !== void 0 ? {
         uiCapabilities: params.uiCapabilities
       } : {},
+      ...params.hostContext !== void 0 ? {
+        hostContext: params.hostContext
+      } : {},
       ...model !== void 0 ? {
         model
       } : {}
@@ -1607,7 +1619,7 @@ var AgentService = class {
       });
     }
     if (live === null && mode !== "queue") {
-      const runId = crypto.randomUUID();
+      const runId = this.runner.runIdFor?.(input) ?? crypto.randomUUID();
       if (await queue.queueStore().claimActiveStream(threadId, runId, stale !== null ? {
         replacing: stale
       } : {})) {
@@ -1675,6 +1687,9 @@ var AgentService = class {
       ...input.uiCapabilities !== void 0 ? {
         uiCapabilities: input.uiCapabilities
       } : {},
+      ...input.hostContext !== void 0 ? {
+        hostContext: input.hostContext
+      } : {},
       ...interrupting !== void 0 ? {
         interrupt: true,
         at: "head"
@@ -5886,11 +5901,11 @@ function isQuotaProvider(quota) {
 __name(isQuotaProvider, "isQuotaProvider");
 function resolveCatalog(options) {
   if (options.models !== void 0) return options.models;
-  const carried = options.model.catalog;
+  const carried = options.model?.catalog;
   return carried !== void 0 && typeof carried.list === "function" ? carried : void 0;
 }
 __name(resolveCatalog, "resolveCatalog");
-function sharedProviders(durable) {
+function sharedProviders(durable, engine) {
   const providers = [
     {
       provide: AGENT_TOOL_REGISTRY3,
@@ -6021,7 +6036,12 @@ function sharedProviders(durable) {
       ModulesContainer
     ]
   });
-  if (durable) {
+  if (engine !== void 0) {
+    providers.push(...engine.providers, {
+      provide: AGENT_RUNNER2,
+      useExisting: engine.runner
+    });
+  } else if (durable) {
     providers.push({
       provide: AGENT_RUNNER2,
       useFactory: /* @__PURE__ */ __name((durableRunner) => {
@@ -6046,8 +6066,9 @@ function sharedProviders(durable) {
   return providers;
 }
 __name(sharedProviders, "sharedProviders");
-function exportsFor() {
+function exportsFor(engine) {
   return [
+    ...engine?.exports ?? [],
     AGENT_OPTIONS9,
     AGENT_TOOL_REGISTRY3,
     AGENT_REGISTRY6,
@@ -6097,10 +6118,11 @@ function adapterProviders(adapters) {
   return (adapters ?? []).flatMap((adapter) => adapter.providers ?? []);
 }
 __name(adapterProviders, "adapterProviders");
-function controllersForSurface(surface, adapters) {
+function controllersForSurface(surface, adapters, engine) {
   return surface === "engine" ? [] : [
     ...BASE_CONTROLLERS,
-    ...adapterControllers(adapters)
+    ...adapterControllers(adapters),
+    ...engine?.controllers ?? []
   ];
 }
 __name(controllersForSurface, "controllersForSurface");
@@ -6130,12 +6152,22 @@ function routerFor(path) {
   ]);
 }
 __name(routerFor, "routerFor");
+function assertRunnable(options) {
+  if (options.engine !== void 0 && options.durable === true) {
+    throw new Error(`AgentModule: \`durable: true\` runs turns on the library's loop, but the \`${options.engine.name}\` engine runs them instead. Drop \`durable\` (the engine decides how its turns survive a restart).`);
+  }
+  if (options.engine === void 0 && options.model === void 0) {
+    throw new Error("AgentModule: set `model` (the loop runs the turns) or `engine` (something else does).");
+  }
+}
+__name(assertRunnable, "assertRunnable");
 var AgentModule = class _AgentModule {
   static {
     __name(this, "AgentModule");
   }
   static forRoot(options) {
     const path = options.path ?? DEFAULT_PATH;
+    assertRunnable(options);
     applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
@@ -6144,21 +6176,27 @@ var AgentModule = class _AgentModule {
         DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface, options.adapters),
+      controllers: controllersForSurface(options.surface, options.adapters, options.engine),
       providers: [
         {
           provide: AGENT_OPTIONS9,
           useValue: options
         },
-        ...sharedProviders(options.durable ?? false),
+        ...sharedProviders(options.durable ?? false, options.engine),
         ...guardProviders(options.guards),
         ...adapterProviders(options.adapters)
       ],
-      exports: exportsFor()
+      exports: exportsFor(options.engine)
     };
   }
   static forRootAsync(options) {
     const path = options.path ?? DEFAULT_PATH;
+    if (options.engine !== void 0) {
+      assertRunnable({
+        engine: options.engine,
+        durable: options.durable ?? false
+      });
+    }
     applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
@@ -6168,7 +6206,7 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersForSurface(options.surface, options.adapters),
+      controllers: controllersForSurface(options.surface, options.adapters, options.engine),
       providers: [
         {
           provide: AGENT_OPTIONS9,
@@ -6178,18 +6216,25 @@ var AgentModule = class _AgentModule {
           // anything today (AgentDurableModule takes its own mirror option — see its doc for why),
           // but it's stamped here too so the EFFECTIVE value is always observable off
           // AGENT_OPTIONS, sync or async alike.
-          useFactory: /* @__PURE__ */ __name(async (...args) => ({
-            ...await options.useFactory(...args),
-            durable: options.durable ?? false,
-            surface: options.surface ?? "both"
-          }), "useFactory"),
+          useFactory: /* @__PURE__ */ __name(async (...args) => {
+            const resolved = {
+              ...await options.useFactory(...args),
+              durable: options.durable ?? false,
+              surface: options.surface ?? "both",
+              ...options.engine !== void 0 ? {
+                engine: options.engine
+              } : {}
+            };
+            assertRunnable(resolved);
+            return resolved;
+          }, "useFactory"),
           inject: options.inject ?? []
         },
-        ...sharedProviders(options.durable ?? false),
+        ...sharedProviders(options.durable ?? false, options.engine),
         ...guardProviders(options.guards),
         ...adapterProviders(options.adapters)
       ],
-      exports: exportsFor()
+      exports: exportsFor(options.engine)
     };
   }
 };
@@ -6324,7 +6369,10 @@ var AgUiRunHandler = class {
     if (owner !== null && owner !== actor.id) {
       throw new ForbiddenException4("thread belongs to another actor");
     }
-    if (owner !== null && turn.media.length === 0) {
+    if (forwarded.regenerate === true && owner === null) {
+      throw invalid("invalid_input", "regenerate needs a thread that already has an exchange");
+    }
+    if (owner !== null && forwarded.regenerate !== true && turn.media.length === 0 && turn.staged.length === 0) {
       const decision = await this.agent.handleTextDecision(input.threadId, actor, turn.text);
       if ("proposalDecision" in decision) {
         this.writeEvents(res, [
@@ -6339,7 +6387,7 @@ var AgUiRunHandler = class {
         return;
       }
     }
-    const refs = await this.stage(actor, turn.media, warnings);
+    const refs = await this.stage(actor, turn.media, warnings, turn.staged);
     if (turn.text.trim().length === 0 && refs.length === 0) {
       throw invalid("no_user_message", "the user message to answer is empty");
     }
@@ -6375,6 +6423,9 @@ var AgUiRunHandler = class {
       } : {},
       ...refs.length > 0 ? {
         attachments: refs
+      } : {},
+      ...forwarded.regenerate === true ? {
+        regenerate: true
       } : {}
     });
     await this.pipe(res, started.runId, {
@@ -6386,10 +6437,25 @@ var AgUiRunHandler = class {
       preamble: warningEvents(warnings)
     });
   }
-  /** Stage the turn's inline media through the bound store, within its limits; say what was not used. */
-  async stage(actor, media, warnings) {
+  /**
+  * The turn's attachments: the ones already staged (by mediaId), then its inline media staged
+  * through the bound store — all within the store's limits; say what was not used.
+  */
+  async stage(actor, media, warnings, staged = []) {
     const refs = [];
     const limits = attachmentLimits(this.options, this.staging);
+    for (const ref of staged) {
+      const label = `The attachment ${ref.mediaId} was not used`;
+      if (this.staging === void 0) {
+        warnings.push(`${label}: attachments are not enabled on this agent.`);
+      } else if (refs.length >= limits.maxPerMessage) {
+        warnings.push(`${label}: a message carries at most ${limits.maxPerMessage} attachments.`);
+      } else {
+        refs.push({
+          mediaId: ref.mediaId
+        });
+      }
+    }
     for (const item of media) {
       const label = `The ${item.kind} "${item.filename}" was not used`;
       if (this.staging === void 0) {
@@ -6402,7 +6468,7 @@ var AgUiRunHandler = class {
         warnings.push(`${label}: it is larger than ${limits.maxBytes} bytes.`);
       } else {
         try {
-          const staged = await this.staging.stage({
+          const staged2 = await this.staging.stage({
             data: item.data,
             filename: item.filename,
             contentType: item.contentType,
@@ -6410,7 +6476,7 @@ var AgUiRunHandler = class {
             actor
           });
           refs.push({
-            mediaId: staged.mediaId
+            mediaId: staged2.mediaId
           });
         } catch {
           warnings.push(`${label}: it could not be stored.`);
@@ -6528,11 +6594,17 @@ var AgUiRunHandler = class {
     res.setHeader("X-Agent-Run-Id", runId);
     res.flushHeaders();
     let terminal = false;
+    const cursor = {
+      seq: 0
+    };
     try {
       const frames = agUiFramesFromNdjson(this.agent.subscribe(runId));
-      for await (const event of agUiEvents(frames, options)) {
+      for await (const event of agUiEvents(frames, {
+        ...options,
+        cursor
+      })) {
         if (event.type === "RUN_FINISHED" || event.type === "RUN_ERROR") terminal = true;
-        res.write(agUiSse(event));
+        res.write(agUiSse(event, cursor.seq));
       }
     } catch {
       if (!terminal) {