@dudousxd/nestjs-agent 0.8.2 → 0.10.0

package/README.md

@@ -41,6 +41,42 @@ The module mounts SSE + REST endpoints under `/agent` (`POST /agent/chat`, tool-
 threads, quota). Add `durable: true` + `AgentDurableModule` for the durable runner;
 `AgentModule.forFeature([…])` for multi-agent orchestration.
 
+### Deploying split API/worker pods
+
+By default `AgentModule`/`AgentDurableModule` wire everything: every controller, the `agent.run`
+durable workflow, and its dispatched steps (`AgentRunSteps.llm`/`.tool`). Fine for a single combined
+pod — but an API/dashboard pod and a worker pod each importing the FULL module means the API pod also
+registers the dispatched-step handlers, subscribing their queues and running LLM/tool work it has no
+business doing (and a worker pod mounts HTTP routes nothing ever calls).
+
+`surface: 'http' | 'engine' | 'both'` (default `'both'`) splits that in two:
+
+```ts
+// worker container: no HTTP routes, but the workflow + dispatched steps ARE registered
+imports: [
+  DurableModule.forRoot({ store, transport }),
+  AgentModule.forRoot({ model, store, actorResolver, durable: true, surface: 'engine' }),
+  AgentDurableModule.forRoot({ surface: 'engine' }),
+]
+
+// api container: every controller works, but AgentRunSteps is never registered here —
+// pair this with the durable `drive: false` enqueue-only config so this pod also never
+// polls/executes work on its own.
+imports: [
+  DurableModule.forRoot({ store, transport, drive: false }),
+  AgentModule.forRoot({ model, store, actorResolver, durable: true, surface: 'http' }),
+  AgentDurableModule.forRoot({ surface: 'http' }),
+]
+```
+
+`AgentDurableModule.forRoot({ surface })` mirrors `AgentModule`'s own `surface` — set it in both
+places (or use the `agentDurable(options)` helper, which threads one `surface` to both calls). The
+`'http'` side still registers the `agent.run` WORKFLOW (so starting a run succeeds) but never the
+step handlers, so it can never pick up LLM/tool work meant for the worker fleet. This is exactly the
+fix for a durable skew-protection crash-loop where a bare-imported module on the wrong pod type
+subscribed queues it should never have served. flip composes this the same way `APP_TYPE` composes
+its other modules: the worker container loads the `engine` surface, the API container loads `http`.
+
 See the [monorepo README](https://github.com/DavideCarvalho/aviary) for the full guide (durability,
 multi-agent, authz, governed SQL, the React frontend, diagnostics).
 

package/dist/{agent-deps.factory-BlC9tumI.d.cts → agent-deps.factory-D7GdhqdK.d.cts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -19,6 +19,11 @@ interface AgentDeps {
     toolAllowList?: string[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
+    /**
+     * Transient-tool-error retry policy (from module options). Undefined → default ON
+     * (`{ attempts: 2, backoffMs: 150 }` with the default classifier); `false` → disabled.
+     */
+    toolTransientRetry?: ToolTransientRetrySetting;
     /** How many follow-up suggestions to generate after the final turn. Undefined/0 → off. */
     followUpsCount?: number;
     /** Inject-mode retriever (from `forRoot({ retrieval })`). Undefined → no prompt augmentation. */
@@ -51,6 +56,26 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): 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:
+ *
+ * - `'both'` (default): today's behavior, unconditionally — every controller AND the full durable
+ *   engine wiring (when `durable: true`). Zero-config single-pod deployments never touch this.
+ * - `'http'`: mounts every controller (chat/threads/tool-call/quota/agents/attachments) so the HTTP
+ *   surface is fully functional, but under `durable: true` this pod must never EXECUTE agent work —
+ *   see `AgentDurableModuleOptions.surface` (`@dudousxd/nestjs-agent/durable`), which is where the
+ *   actual step-handler exclusion happens; this flag only controls the controllers here.
+ * - `'engine'`: mounts NO controllers (an API pod's routes have no business existing on a worker
+ *   pod that never receives HTTP traffic) — everything else (registry/tools/model/store/sinks, the
+ *   `agent.run` workflow, and its dispatched steps under `AgentDurableModule`) stays wired exactly
+ *   as `'both'`.
+ *
+ * A durable deployment mirrors this on `AgentDurableModule.forRoot({ surface })` too — see that
+ * module's doc for why the split can't be inferred from this option alone (Nest's static module
+ * metadata can't be computed from a runtime-injected value).
+ */
+type AgentSurface = 'http' | 'engine' | 'both';
 /**
  * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
  * `POST /agent/attachments` upload controller (see `attachments.upload`).
@@ -138,6 +163,16 @@ interface AgentModuleOptions {
      * model receives the timeout as its result and can adapt) instead of hanging the turn. Omit → none.
      */
     toolTimeoutMs?: number;
+    /**
+     * Retries a tool's own invocation, in place, when it throws a classified-transient error (a DB
+     * deadlock, a lock-wait timeout, a serialization failure) — never a new durable checkpoint, just
+     * repeated attempts inside the same tool-call step. Default ON: `{ attempts: 2, backoffMs: 150 }`
+     * with the default classifier. Set `{ classify }` to widen/narrow which errors count as transient
+     * (checked in BOTH the inline and durable-dispatched execution paths via DI, since the classify
+     * function itself can't ride a durable step's wire envelope), or `false` to disable entirely. A
+     * tool's other (non-transient) failures are unaffected — they remain a one-shot business outcome.
+     */
+    toolTransientRetry?: ToolTransientRetrySetting;
     /**
      * Suggest follow-up questions after the final turn. `true` → 3 suggestions; `{ count }` → that many.
      * Costs one extra model call per turn (recorded as `follow_ups` usage), stored on the assistant
@@ -173,6 +208,12 @@ interface AgentModuleOptions {
     guards?: Type<CanActivate>[];
     /** Bounds/allowlist for the optional attachment-upload controller. Omit → 20 MiB, the documented default types, not mounted. */
     attachments?: AgentAttachmentsOptions;
+    /**
+     * Which half of the module this process mounts (see {@link AgentSurface}). Omit → `'both'`,
+     * today's behavior with zero change. STATIC top-level field (like `durable`/`path`) — it decides
+     * which controllers exist at module-build time, not something a request can flip.
+     */
+    surface?: AgentSurface;
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -224,6 +265,12 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * only the yes/no mount decision has to live here.
      */
     attachmentsUpload?: boolean;
+    /**
+     * Which half of the module this process mounts (see {@link AgentSurface}). Same static-wiring
+     * reasoning as `attachmentsUpload`/`durable` above — `useFactory` resolves too late to decide
+     * which controllers exist. Omit → `'both'`, today's behavior with zero change.
+     */
+    surface?: AgentSurface;
 }
 
 /** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
@@ -252,4 +299,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentAttachmentsOptions as d, type AgentDeps as e, delegateToolName as f, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, AGENT_TOOL_BRAND as d, type AgentAttachmentsOptions as e, type AgentDeps as f, delegateToolName as g, provideAgentTool as p, utcDay as u };

package/dist/{agent-deps.factory-BlC9tumI.d.ts → agent-deps.factory-D7GdhqdK.d.ts}

@@ -1,4 +1,4 @@
-import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
+import { ModelProvider, AgentStore, ToolRegistry, RolesPolicy, QuotaStore, TokenStreamSink, PromptBuilder, PromptContributor, ToolTransientRetrySetting, Retriever, AgentPricingStore, ToolSpec, ToolHandler, ActorResolver, AgentRegistry } from '@dudousxd/nestjs-agent-core';
 import { Provider, FactoryProvider, Type, CanActivate, ModuleMetadata, InjectionToken, OptionalFactoryDependency } from '@nestjs/common';
 
 /** Everything `runAgentLoop` needs, minus the per-run `day` the runner stamps. */
@@ -19,6 +19,11 @@ interface AgentDeps {
     toolAllowList?: string[];
     /** Per-tool execution timeout in ms (from module options). Undefined → no timeout. */
     toolTimeoutMs?: number;
+    /**
+     * Transient-tool-error retry policy (from module options). Undefined → default ON
+     * (`{ attempts: 2, backoffMs: 150 }` with the default classifier); `false` → disabled.
+     */
+    toolTransientRetry?: ToolTransientRetrySetting;
     /** How many follow-up suggestions to generate after the final turn. Undefined/0 → off. */
     followUpsCount?: number;
     /** Inject-mode retriever (from `forRoot({ retrieval })`). Undefined → no prompt augmentation. */
@@ -51,6 +56,26 @@ interface FunctionalTool {
 declare function provideAgentTool(tool: FunctionalTool): Provider;
 declare function provideAgentTool(factory: (...deps: never[]) => FunctionalTool, inject?: FactoryProvider['inject']): 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:
+ *
+ * - `'both'` (default): today's behavior, unconditionally — every controller AND the full durable
+ *   engine wiring (when `durable: true`). Zero-config single-pod deployments never touch this.
+ * - `'http'`: mounts every controller (chat/threads/tool-call/quota/agents/attachments) so the HTTP
+ *   surface is fully functional, but under `durable: true` this pod must never EXECUTE agent work —
+ *   see `AgentDurableModuleOptions.surface` (`@dudousxd/nestjs-agent/durable`), which is where the
+ *   actual step-handler exclusion happens; this flag only controls the controllers here.
+ * - `'engine'`: mounts NO controllers (an API pod's routes have no business existing on a worker
+ *   pod that never receives HTTP traffic) — everything else (registry/tools/model/store/sinks, the
+ *   `agent.run` workflow, and its dispatched steps under `AgentDurableModule`) stays wired exactly
+ *   as `'both'`.
+ *
+ * A durable deployment mirrors this on `AgentDurableModule.forRoot({ surface })` too — see that
+ * module's doc for why the split can't be inferred from this option alone (Nest's static module
+ * metadata can't be computed from a runtime-injected value).
+ */
+type AgentSurface = 'http' | 'engine' | 'both';
 /**
  * `AgentModuleOptions.attachments` — bounds and content-type allowlist for the optional
  * `POST /agent/attachments` upload controller (see `attachments.upload`).
@@ -138,6 +163,16 @@ interface AgentModuleOptions {
      * model receives the timeout as its result and can adapt) instead of hanging the turn. Omit → none.
      */
     toolTimeoutMs?: number;
+    /**
+     * Retries a tool's own invocation, in place, when it throws a classified-transient error (a DB
+     * deadlock, a lock-wait timeout, a serialization failure) — never a new durable checkpoint, just
+     * repeated attempts inside the same tool-call step. Default ON: `{ attempts: 2, backoffMs: 150 }`
+     * with the default classifier. Set `{ classify }` to widen/narrow which errors count as transient
+     * (checked in BOTH the inline and durable-dispatched execution paths via DI, since the classify
+     * function itself can't ride a durable step's wire envelope), or `false` to disable entirely. A
+     * tool's other (non-transient) failures are unaffected — they remain a one-shot business outcome.
+     */
+    toolTransientRetry?: ToolTransientRetrySetting;
     /**
      * Suggest follow-up questions after the final turn. `true` → 3 suggestions; `{ count }` → that many.
      * Costs one extra model call per turn (recorded as `follow_ups` usage), stored on the assistant
@@ -173,6 +208,12 @@ interface AgentModuleOptions {
     guards?: Type<CanActivate>[];
     /** Bounds/allowlist for the optional attachment-upload controller. Omit → 20 MiB, the documented default types, not mounted. */
     attachments?: AgentAttachmentsOptions;
+    /**
+     * Which half of the module this process mounts (see {@link AgentSurface}). Omit → `'both'`,
+     * today's behavior with zero change. STATIC top-level field (like `durable`/`path`) — it decides
+     * which controllers exist at module-build time, not something a request can flip.
+     */
+    surface?: AgentSurface;
 }
 interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
@@ -224,6 +265,12 @@ interface AgentModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
      * only the yes/no mount decision has to live here.
      */
     attachmentsUpload?: boolean;
+    /**
+     * Which half of the module this process mounts (see {@link AgentSurface}). Same static-wiring
+     * reasoning as `attachmentsUpload`/`durable` above — `useFactory` resolves too late to decide
+     * which controllers exist. Omit → `'both'`, today's behavior with zero change.
+     */
+    surface?: AgentSurface;
 }
 
 /** The synthesized `agent`-kind tool name an orchestrator uses to hand off to `target`. */
@@ -252,4 +299,4 @@ declare class AgentDepsFactory {
     private followUpsCount;
 }
 
-export { AgentDepsFactory as A, type FunctionalTool as F, type AgentModuleOptions as a, type AgentModuleAsyncOptions as b, AGENT_TOOL_BRAND as c, type AgentAttachmentsOptions as d, type AgentDeps as e, delegateToolName as f, provideAgentTool as p, utcDay as u };
+export { AgentDepsFactory as A, type FunctionalTool as F, type AgentSurface as a, type AgentModuleOptions as b, type AgentModuleAsyncOptions as c, AGENT_TOOL_BRAND as d, type AgentAttachmentsOptions as e, type AgentDeps as f, delegateToolName as g, provideAgentTool as p, utcDay as u };