@dudousxd/nestjs-agent 1.22.0 → 1.23.0

package/dist/{chat-queue.service-CTyX_yNr.d.ts → chat-queue.service-CwxJDrBM.d.ts}

@@ -1,7 +1,7 @@
 import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
 import { GenuiCatalogResolver } from './genui/index.js';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -72,6 +72,34 @@ interface AgentDeps {
 }
 declare function utcDay(date?: Date): string;
 
+/**
+ * Something other than this library's loop that runs a turn — what `engine` on
+ * `AgentModule.forRoot` takes. An engine owns the turn end to end (the model calls, the tools, the
+ * context it keeps), and contributes the `AgentRunner` that `AGENT_RUNNER` binds to; everything
+ * around the turn stays the library's: the routes and the stream protocol, threads and the store,
+ * the sink, approvals and answers routed through `AgentService`, the queue and the quota.
+ *
+ * `openCode()` (`@dudousxd/nestjs-agent-opencode`) is the one that ships. An engine replaces the
+ * loop, so the options only the loop reads (`model`, processors, `outputSchema`, `maxSteps`,
+ * `history`, `retrieval`) do nothing under one; `model` becomes optional.
+ */
+interface AgentEngine {
+    /** For logs and diagnostics. */
+    name: string;
+    /** The providers the engine needs, its runner among them. */
+    providers: Provider[];
+    /** The token of the engine's `AgentRunner`, which `AGENT_RUNNER` is bound to. */
+    runner: InjectionToken;
+    /** Providers the app may inject too (the module is global): e.g. what an MCP surface hooks into. */
+    exports?: InjectionToken[];
+    /**
+     * Controllers the engine mounts under the agent's path (e.g. the endpoint its own runtime calls
+     * back into). Not mounted on `surface: 'engine'`, and the module's `guards` are NOT applied: an
+     * engine's controller authenticates its own callers, which are not the app's users.
+     */
+    controllers?: Type<object>[];
+}
+
 /**
  * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
  * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
@@ -284,9 +312,16 @@ interface AgentModuleOptions {
     actionProposalText?: TextActionProposalConfig;
     /**
      * The LLM provider — `aiSdkModel(openai('gpt-5-mini'))`, or `aiSdkModels({ … })` for a model
-     * picker (its catalog is used when `models` is omitted). The only required option.
+     * picker (its catalog is used when `models` is omitted). Required unless an `engine` runs the
+     * turns instead.
      */
-    model: ModelProvider;
+    model?: ModelProvider;
+    /**
+     * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
+     * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
+     * wiring, like `durable` (see {@link AgentEngine}). Omit → the loop, on `model`.
+     */
+    engine?: AgentEngine;
     /**
      * The base prompt of the default agent (and of any `@Agent` that declares none) — a string, or a
      * function of the turn's `{ actor, agentName, pageContext }`. Omit → `'You are a helpful
@@ -540,6 +575,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
     /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
     adapters?: AgentProtocolAdapter[];
+    /**
+     * What runs the turns instead of the loop — see `AgentModuleOptions.engine`. STATIC, like
+     * `durable`: it decides which runner `AGENT_RUNNER` binds, before `useFactory` has resolved.
+     */
+    engine?: AgentEngine;
 }
 
 /**
@@ -760,4 +800,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 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, defineTool as o, delegateToolName as p, provideAgentTool as q, provideAgentTools as r, 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 AgentEngine as i, type AgentMemoryOptions as j, type QueueSettleOutcome as k, type QueuedTurn as l, type QueuedTurnStarter as m, type QuotaLimits as n, type QuotaWindowLimits as o, defineTool as p, delegateToolName as q, provideAgentTool as r, provideAgentTools as s, utcDay as u };

package/dist/{chat-queue.service-Dx9OsjcF.d.cts → chat-queue.service-D1z3WjFI.d.cts}

@@ -1,7 +1,7 @@
 import { ResolveToolUiCatalog, ModelProvider, AgentStore, ToolRegistry, RolesPolicy, ApprovalPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Persona, ToolTransientRetrySetting, Retriever, AgentPricingStore, HistoryPolicy, InputProcessor, OutputProcessor, AgentIntake, SkillsConfig, MemoryConfig, ToolSpec, ToolHandler, createFunctionalTool, QuotaProvider, QuotaQuery, QuotaReport, ActionApprovalMode, BackgroundActorResolver, TextActionProposalConfig, ModelCatalog, EmptyRoles, ActorResolver, AgentHistoryWindow, SkillProvider, ScopeResolver, MemoryProvider, AgentRegistry, PersonaCatalogEntry, ActionProposal, Actor, AttachmentStagingStore, ChatQueueStore, ChatQueueState, AgentRunner, AgentRunInput, AgentStreamEvent, QueuePauseReason } from '@dudousxd/nestjs-agent-core';
 import { Catalog } from '@dudousxd/nestjs-agent-core/genui';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
+import { Provider, InjectionToken, Type, FactoryProvider, CanActivate, ModuleMetadata, OptionalFactoryDependency } from '@nestjs/common';
 import { GenuiCatalogResolver } from './genui/index.cjs';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -72,6 +72,34 @@ interface AgentDeps {
 }
 declare function utcDay(date?: Date): string;
 
+/**
+ * Something other than this library's loop that runs a turn — what `engine` on
+ * `AgentModule.forRoot` takes. An engine owns the turn end to end (the model calls, the tools, the
+ * context it keeps), and contributes the `AgentRunner` that `AGENT_RUNNER` binds to; everything
+ * around the turn stays the library's: the routes and the stream protocol, threads and the store,
+ * the sink, approvals and answers routed through `AgentService`, the queue and the quota.
+ *
+ * `openCode()` (`@dudousxd/nestjs-agent-opencode`) is the one that ships. An engine replaces the
+ * loop, so the options only the loop reads (`model`, processors, `outputSchema`, `maxSteps`,
+ * `history`, `retrieval`) do nothing under one; `model` becomes optional.
+ */
+interface AgentEngine {
+    /** For logs and diagnostics. */
+    name: string;
+    /** The providers the engine needs, its runner among them. */
+    providers: Provider[];
+    /** The token of the engine's `AgentRunner`, which `AGENT_RUNNER` is bound to. */
+    runner: InjectionToken;
+    /** Providers the app may inject too (the module is global): e.g. what an MCP surface hooks into. */
+    exports?: InjectionToken[];
+    /**
+     * Controllers the engine mounts under the agent's path (e.g. the endpoint its own runtime calls
+     * back into). Not mounted on `surface: 'engine'`, and the module's `guards` are NOT applied: an
+     * engine's controller authenticates its own callers, which are not the app's users.
+     */
+    controllers?: Type<object>[];
+}
+
 /**
  * Brand stamped onto a functional-tool provider instance so `AiToolDiscoveryService` picks it up
  * when it walks every provider at boot — the declarative alternative to a manual `registry.register`.
@@ -284,9 +312,16 @@ interface AgentModuleOptions {
     actionProposalText?: TextActionProposalConfig;
     /**
      * The LLM provider — `aiSdkModel(openai('gpt-5-mini'))`, or `aiSdkModels({ … })` for a model
-     * picker (its catalog is used when `models` is omitted). The only required option.
+     * picker (its catalog is used when `models` is omitted). Required unless an `engine` runs the
+     * turns instead.
      */
-    model: ModelProvider;
+    model?: ModelProvider;
+    /**
+     * Run turns on something other than this library's loop — e.g. `openCode({ host })`. The engine
+     * binds `AGENT_RUNNER`; the routes, store, sink, approvals and queue stay the library's. STATIC
+     * wiring, like `durable` (see {@link AgentEngine}). Omit → the loop, on `model`.
+     */
+    engine?: AgentEngine;
     /**
      * The base prompt of the default agent (and of any `@Agent` that declares none) — a string, or a
      * function of the turn's `{ actor, agentName, pageContext }`. Omit → `'You are a helpful
@@ -540,6 +575,11 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     surface?: AgentSurface;
     /** Wire protocols served alongside the native one — see `AgentModuleOptions.adapters`. STATIC. */
     adapters?: AgentProtocolAdapter[];
+    /**
+     * What runs the turns instead of the loop — see `AgentModuleOptions.engine`. STATIC, like
+     * `durable`: it decides which runner `AGENT_RUNNER` binds, before `useFactory` has resolved.
+     */
+    engine?: AgentEngine;
 }
 
 /**
@@ -760,4 +800,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 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, defineTool as o, delegateToolName as p, provideAgentTool as q, provideAgentTools as r, 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 AgentEngine as i, type AgentMemoryOptions as j, type QueueSettleOutcome as k, type QueuedTurn as l, type QueuedTurnStarter as m, type QuotaLimits as n, type QuotaWindowLimits as o, defineTool as p, delegateToolName as q, provideAgentTool as r, provideAgentTools as s, utcDay as u };

package/dist/durable/index.cjs

@@ -2251,6 +2251,9 @@ var ChatQueueService2 = class _ChatQueueService {
       } : {},
       ...input.uiCapabilities !== void 0 ? {
         uiCapabilities: input.uiCapabilities
+      } : {},
+      ...input.hostContext !== void 0 ? {
+        hostContext: input.hostContext
       } : {}
     });
     await store.setQueuePause(threadId, {
@@ -2336,6 +2339,9 @@ var ChatQueueService2 = class _ChatQueueService {
       ...message.uiCapabilities !== void 0 ? {
         uiCapabilities: message.uiCapabilities
       } : {},
+      ...message.hostContext !== void 0 ? {
+        hostContext: message.hostContext
+      } : {},
       ...message.model !== void 0 ? {
         model: message.model
       } : {}
@@ -2706,6 +2712,9 @@ var AgentService = class {
       }
       const created = await this.store.createThread({
         actor: params.actor,
+        ...agentName !== void 0 ? {
+          agentName
+        } : {},
         ...params.transient === true ? {
           transient: true
         } : {},
@@ -2718,7 +2727,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);
       }
@@ -2744,6 +2753,9 @@ var AgentService = class {
       ...params.uiCapabilities !== void 0 ? {
         uiCapabilities: params.uiCapabilities
       } : {},
+      ...params.hostContext !== void 0 ? {
+        hostContext: params.hostContext
+      } : {},
       ...model !== void 0 ? {
         model
       } : {}
@@ -2766,7 +2778,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
       } : {})) {
@@ -2834,6 +2846,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"
@@ -6930,11 +6945,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: import_nestjs_agent_core39.AGENT_TOOL_REGISTRY,
@@ -7065,7 +7080,12 @@ function sharedProviders(durable) {
       import_core4.ModulesContainer
     ]
   });
-  if (durable) {
+  if (engine !== void 0) {
+    providers.push(...engine.providers, {
+      provide: import_nestjs_agent_core39.AGENT_RUNNER,
+      useExisting: engine.runner
+    });
+  } else if (durable) {
     providers.push({
       provide: import_nestjs_agent_core39.AGENT_RUNNER,
       useFactory: /* @__PURE__ */ __name((durableRunner) => {
@@ -7090,8 +7110,9 @@ function sharedProviders(durable) {
   return providers;
 }
 __name(sharedProviders, "sharedProviders");
-function exportsFor() {
+function exportsFor(engine) {
   return [
+    ...engine?.exports ?? [],
     import_nestjs_agent_core39.AGENT_OPTIONS,
     import_nestjs_agent_core39.AGENT_TOOL_REGISTRY,
     import_nestjs_agent_core39.AGENT_REGISTRY,
@@ -7141,10 +7162,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");
@@ -7174,12 +7196,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,
@@ -7188,21 +7220,27 @@ var AgentModule = class _AgentModule {
         import_core4.DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersForSurface(options.surface, options.adapters),
+      controllers: controllersForSurface(options.surface, options.adapters, options.engine),
       providers: [
         {
           provide: import_nestjs_agent_core39.AGENT_OPTIONS,
           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,
@@ -7212,7 +7250,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: import_nestjs_agent_core39.AGENT_OPTIONS,
@@ -7222,18 +7260,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)
     };
   }
 };