@dudousxd/nestjs-agent 1.17.1 → 1.18.0

package/dist/{chat-queue.service-Bqq00NN1.d.cts → chat-queue.service-5LIogd9K.d.cts}

@@ -130,6 +130,24 @@ declare class LedgerQuotaProvider implements QuotaProvider {
     private window;
 }
 
+/**
+ * A wire protocol other than the native one, served over the same runs — what `adapters` on
+ * `AgentModule.forRoot` takes. An adapter contributes controllers, mounted under the agent's
+ * `path` and guarded by its `guards` exactly like the native routes; the runs, the store, the
+ * approvals and the quota are the library's, unchanged.
+ *
+ * `agUiAdapter()` is the one that ships. Write your own the same way: a controller that injects
+ * `AgentService` (and `AGENT_ACTOR_RESOLVER`) and translates.
+ */
+interface AgentProtocolAdapter {
+    /** For logs and diagnostics. */
+    name: string;
+    /** Mounted under the agent's path. Not mounted at all on `surface: 'engine'`. */
+    controllers: Type<object>[];
+    /** Extra providers the controllers inject. */
+    providers?: Provider[];
+}
+
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
  * each load `AgentModule` without either one doing the other's job:
@@ -432,6 +450,12 @@ interface AgentModuleOptions {
      * which controllers exist at module-build time, not something a request can flip.
      */
     surface?: AgentSurface;
+    /**
+     * Wire protocols served alongside the native one, over the same runs — e.g. `[agUiAdapter()]`
+     * mounts `POST <path>/ag-ui` (AG-UI 1.0). Their controllers mount under `path`, behind `guards`,
+     * and not at all on `surface: 'engine'`. STATIC, like `surface`.
+     */
+    adapters?: AgentProtocolAdapter[];
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -462,6 +486,8 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * which controllers exist. Omit → `'both'`, today's behavior with zero change.
      */
     surface?: AgentSurface;
+    /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
+    adapters?: AgentProtocolAdapter[];
 }
 
 /**
@@ -642,4 +668,4 @@ declare class ChatQueueService {
     private freshAttachments;
 }
 
-export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QueueSettleOutcome as i, type QueuedTurn as j, type QueuedTurnStarter as k, type QuotaLimits as l, type QuotaWindowLimits as m, delegateToolName as n, provideAgentTools as o, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, delegateToolName as o, provideAgentTool as p, provideAgentTools as q, utcDay as u };

package/dist/{chat-queue.service-Bqq00NN1.d.ts → chat-queue.service-5LIogd9K.d.ts}

@@ -130,6 +130,24 @@ declare class LedgerQuotaProvider implements QuotaProvider {
     private window;
 }
 
+/**
+ * A wire protocol other than the native one, served over the same runs — what `adapters` on
+ * `AgentModule.forRoot` takes. An adapter contributes controllers, mounted under the agent's
+ * `path` and guarded by its `guards` exactly like the native routes; the runs, the store, the
+ * approvals and the quota are the library's, unchanged.
+ *
+ * `agUiAdapter()` is the one that ships. Write your own the same way: a controller that injects
+ * `AgentService` (and `AGENT_ACTOR_RESOLVER`) and translates.
+ */
+interface AgentProtocolAdapter {
+    /** For logs and diagnostics. */
+    name: string;
+    /** Mounted under the agent's path. Not mounted at all on `surface: 'engine'`. */
+    controllers: Type<object>[];
+    /** Extra providers the controllers inject. */
+    providers?: Provider[];
+}
+
 /**
  * Which half of the module this process mounts — the split that lets an API pod and a WORKER pod
  * each load `AgentModule` without either one doing the other's job:
@@ -432,6 +450,12 @@ interface AgentModuleOptions {
      * which controllers exist at module-build time, not something a request can flip.
      */
     surface?: AgentSurface;
+    /**
+     * Wire protocols served alongside the native one, over the same runs — e.g. `[agUiAdapter()]`
+     * mounts `POST <path>/ag-ui` (AG-UI 1.0). Their controllers mount under `path`, behind `guards`,
+     * and not at all on `surface: 'engine'`. STATIC, like `surface`.
+     */
+    adapters?: AgentProtocolAdapter[];
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -462,6 +486,8 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * which controllers exist. Omit → `'both'`, today's behavior with zero change.
      */
     surface?: AgentSurface;
+    /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
+    adapters?: AgentProtocolAdapter[];
 }
 
 /**
@@ -642,4 +668,4 @@ declare class ChatQueueService {
     private freshAttachments;
 }
 
-export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentSkillsOptions as d, AGENT_TOOL_BRAND as e, type AgentAttachmentsOptions as f, type AgentDeps as g, type AgentMemoryOptions as h, type QueueSettleOutcome as i, type QueuedTurn as j, type QueuedTurnStarter as k, type QuotaLimits as l, type QuotaWindowLimits as m, delegateToolName as n, provideAgentTools as o, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, ChatQueueService as C, type FunctionalTool as F, LedgerQuotaProvider as L, type QueuePlan as Q, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, type AgentProtocolAdapter as d, type AgentSkillsOptions as e, AGENT_TOOL_BRAND as f, type AgentAttachmentsOptions as g, type AgentDeps as h, type AgentMemoryOptions as i, type QueueSettleOutcome as j, type QueuedTurn as k, type QueuedTurnStarter as l, type QuotaLimits as m, type QuotaWindowLimits as n, delegateToolName as o, provideAgentTool as p, provideAgentTools as q, utcDay as u };

package/dist/durable/index.cjs

@@ -1911,6 +1911,9 @@ var AgentService = class {
         actor: params.actor,
         ...params.transient === true ? {
           transient: true
+        } : {},
+        ...params.newThreadId !== void 0 ? {
+          id: params.newThreadId
         } : {}
       });
       threadId = created.id;
@@ -2335,6 +2338,38 @@ var AgentService = class {
     });
     throw new RunNotActiveException(runId);
   }
+  /** Who owns the thread, or `null` when there is no such (live) thread. */
+  async threadOwner(threadId) {
+    return this.store.ownerOfThread(threadId);
+  }
+  /**
+  * May `actor` continue the run whose stream is `runId` — the AG-UI resume? Only the actor whose
+  * thread is streaming it (`403` otherwise), and only while it still is: a run that is over is
+  * waiting on no one (`409 run_not_active`), whatever an old interrupt id says.
+  */
+  async assertResumable(actor, runId) {
+    const owner = await this.store.ownerOfActiveStream(runId);
+    if (owner === null) {
+      throw new RunNotActiveException(runId);
+    }
+    if (owner !== actor.id) {
+      throw new import_common8.ForbiddenException("run belongs to another actor");
+    }
+  }
+  /**
+  * Everything {@link approve} / {@link reject} check before they signal — who may decide, and
+  * that the request has not lapsed — without signalling. For a caller that settles several
+  * decisions at once and must refuse all of them if one is refused (an AG-UI resume).
+  */
+  async checkDecision(actor, toolCallId2) {
+    await this.assertMayDecide(actor, toolCallId2);
+    await this.assertNotExpired(toolCallId2);
+  }
+  /** Everything {@link answer} checks before it signals, without signalling — see {@link checkDecision}. */
+  async checkAnswer(actor, toolCallId2, answers2) {
+    await this.assertOwnsToolCall(actor, toolCallId2);
+    await this.assertAnswersFit(toolCallId2, answers2);
+  }
   async cancel(actor, runId) {
     await this.assertOwnsActiveStream(actor, runId);
     return this.runner.cancel(runId);
@@ -5877,15 +5912,28 @@ var BASE_CONTROLLERS = [
   ConfigController,
   AttachmentsController
 ];
-var GUARDABLE_CONTROLLERS = BASE_CONTROLLERS;
-function controllersForSurface(surface) {
-  return surface === "engine" ? [] : BASE_CONTROLLERS;
+function adapterControllers(adapters) {
+  return (adapters ?? []).flatMap((adapter) => adapter.controllers);
+}
+__name(adapterControllers, "adapterControllers");
+function adapterProviders(adapters) {
+  return (adapters ?? []).flatMap((adapter) => adapter.providers ?? []);
+}
+__name(adapterProviders, "adapterProviders");
+function controllersForSurface(surface, adapters) {
+  return surface === "engine" ? [] : [
+    ...BASE_CONTROLLERS,
+    ...adapterControllers(adapters)
+  ];
 }
 __name(controllersForSurface, "controllersForSurface");
 var GUARDS_METADATA = "__guards__";
-function applyGuards(guards) {
+function applyGuards(guards, adapters) {
   const resolved = guards ?? [];
-  for (const controller of GUARDABLE_CONTROLLERS) {
+  for (const controller of [
+    ...BASE_CONTROLLERS,
+    ...adapterControllers(adapters)
+  ]) {
     Reflect.defineMetadata(GUARDS_METADATA, resolved, controller);
   }
 }
@@ -5911,7 +5959,7 @@ var AgentModule = class _AgentModule {
   }
   static forRoot(options) {
     const path = options.path ?? DEFAULT_PATH;
-    applyGuards(options.guards);
+    applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
       global: true,
@@ -5919,21 +5967,22 @@ var AgentModule = class _AgentModule {
         import_core4.DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: import_nestjs_agent_core31.AGENT_OPTIONS,
           useValue: options
         },
         ...sharedProviders(options.durable ?? false),
-        ...guardProviders(options.guards)
+        ...guardProviders(options.guards),
+        ...adapterProviders(options.adapters)
       ],
       exports: exportsFor()
     };
   }
   static forRootAsync(options) {
     const path = options.path ?? DEFAULT_PATH;
-    applyGuards(options.guards);
+    applyGuards(options.guards, options.adapters);
     return {
       module: _AgentModule,
       global: true,
@@ -5942,7 +5991,7 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersForSurface(options.surface),
+      controllers: controllersForSurface(options.surface, options.adapters),
       providers: [
         {
           provide: import_nestjs_agent_core31.AGENT_OPTIONS,
@@ -5960,7 +6009,8 @@ var AgentModule = class _AgentModule {
           inject: options.inject ?? []
         },
         ...sharedProviders(options.durable ?? false),
-        ...guardProviders(options.guards)
+        ...guardProviders(options.guards),
+        ...adapterProviders(options.adapters)
       ],
       exports: exportsFor()
     };