@dudousxd/nestjs-agent 0.9.0 → 0.10.1

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-DNslT7_J.d.cts → agent-deps.factory-D7GdhqdK.d.cts}

@@ -56,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`).
@@ -188,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>;
@@ -239,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`. */
@@ -267,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-DNslT7_J.d.ts → agent-deps.factory-D7GdhqdK.d.ts}

@@ -56,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`).
@@ -188,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>;
@@ -239,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`. */
@@ -267,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/durable/index.cjs

@@ -31,10 +31,10 @@ __export(durable_exports, {
 module.exports = __toCommonJS(durable_exports);
 
 // src/durable/agent-run.workflow.ts
-var import_nestjs_agent_core2 = require("@dudousxd/nestjs-agent-core");
-var import_nestjs_durable2 = require("@dudousxd/nestjs-durable");
+var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_durable = require("@dudousxd/nestjs-durable");
 var import_nestjs_durable_core = require("@dudousxd/nestjs-durable-core");
-var import_common2 = require("@nestjs/common");
+var import_common = require("@nestjs/common");
 
 // src/agent-deps.ts
 function utcDay(date = /* @__PURE__ */ new Date()) {
@@ -52,10 +52,10 @@ function childSinkWriter(writer) {
 }
 __name(childSinkWriter, "childSinkWriter");
 
-// src/durable/agent-run.steps.ts
-var import_nestjs_agent_core = require("@dudousxd/nestjs-agent-core");
-var import_nestjs_durable = require("@dudousxd/nestjs-durable");
-var import_common = require("@nestjs/common");
+// src/durable/dispatched-steps.token.ts
+var AGENT_DISPATCHED_STEPS = Symbol.for("@dudousxd/nestjs-agent:dispatched-steps");
+
+// src/durable/agent-run.workflow.ts
 function _ts_decorate(decorators, target, key, desc) {
   var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
   if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
@@ -73,122 +73,6 @@ function _ts_param(paramIndex, decorator) {
   };
 }
 __name(_ts_param, "_ts_param");
-var AgentRunSteps = class {
-  static {
-    __name(this, "AgentRunSteps");
-  }
-  factory;
-  constructor(factory) {
-    this.factory = factory;
-  }
-  /**
-  * Retryable: every side effect (persist/quota/stream markers) happens loop-side under
-  * `hooks.step`, so a durable retry only re-runs the model call and re-streams its tokens — never
-  * double-writes. NEVER call `writer.end()`/`fail()` here: the workflow owns the stream's lifecycle,
-  * across however many turns/retries it takes.
-  */
-  async llm(input) {
-    const deps = this.factory.forAgent(input.agentName);
-    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
-    const opened = await deps.sink.open(input.sinkRunId);
-    const writer = input.childSink ? childSinkWriter(opened) : opened;
-    return (0, import_nestjs_agent_core.traceLlmTurn)(input.runId, input.step, () => deps.model.runTurn({
-      system: input.system,
-      messages: input.messages,
-      tools,
-      sink: writer
-    }));
-  }
-  /**
-  * NO DURABLE retries — a tool may not be idempotent (a bare `@Step()` carries none, unlike `llm`
-  * above). What it does retry, in place, is a CLASSIFIED-TRANSIENT error from the tool's own
-  * invocation (a DB deadlock, a lock-wait timeout — see `isTransientToolError`): the server rolled
-  * that work back, so re-invoking it is safe, and doing it here (inside this one step, never a new
-  * checkpoint) is exactly how the non-dispatched loop path handles it too. The timeout is applied
-  * HERE, handler-side, via `withToolTimeout` — never as a durable dispatch `timeoutMs`, which
-  * bounds engine liveness (retryable) rather than the tool's own business outcome — and per
-  * ATTEMPT, so a retried invocation gets its own fresh timeout window.
-  */
-  async tool(input) {
-    const deps = this.factory.forAgent(input.ctx.agentName);
-    const ctx = {
-      ...input.ctx
-    };
-    const localClassify = deps.toolTransientRetry !== false ? deps.toolTransientRetry?.classify : void 0;
-    const transientRetry = input.transientRetry === false ? false : {
-      attempts: input.transientRetry.attempts,
-      backoffMs: input.transientRetry.backoffMs,
-      ...localClassify !== void 0 ? {
-        classify: localClassify
-      } : {}
-    };
-    return (0, import_nestjs_agent_core.traceToolExecution)(input.ctx.runId, {
-      toolCallId: input.toolCallId,
-      toolName: input.toolName,
-      toolType: input.toolType
-    }, () => (0, import_nestjs_agent_core.invokeWithTransientRetry)(() => {
-      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy);
-      return input.timeoutMs !== void 0 ? (0, import_nestjs_agent_core.withToolTimeout)(invocation, input.timeoutMs, input.toolName) : invocation;
-    }, transientRetry, {
-      onRetry: /* @__PURE__ */ __name((attempt, error) => {
-        (0, import_nestjs_agent_core.publishAgentToolRetry)({
-          toolName: input.toolName,
-          toolCallId: input.toolCallId,
-          attempt,
-          message: error instanceof Error ? error.message : String(error)
-        });
-      }, "onRetry")
-    }));
-  }
-};
-_ts_decorate([
-  (0, import_nestjs_durable.Step)({
-    retries: 3
-  }),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof DispatchedLlmInput === "undefined" ? Object : DispatchedLlmInput
-  ]),
-  _ts_metadata("design:returntype", Promise)
-], AgentRunSteps.prototype, "llm", null);
-_ts_decorate([
-  (0, import_nestjs_durable.Step)(),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof DispatchedToolInput === "undefined" ? Object : DispatchedToolInput
-  ]),
-  _ts_metadata("design:returntype", Promise)
-], AgentRunSteps.prototype, "tool", null);
-AgentRunSteps = _ts_decorate([
-  (0, import_common.Injectable)(),
-  _ts_param(0, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_DEPS_FACTORY)),
-  _ts_metadata("design:type", Function),
-  _ts_metadata("design:paramtypes", [
-    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
-  ])
-], AgentRunSteps);
-
-// src/durable/dispatched-steps.token.ts
-var AGENT_DISPATCHED_STEPS = Symbol.for("@dudousxd/nestjs-agent:dispatched-steps");
-
-// src/durable/agent-run.workflow.ts
-function _ts_decorate2(decorators, target, key, desc) {
-  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
-  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
-  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
-  return c > 3 && r && Object.defineProperty(target, key, r), r;
-}
-__name(_ts_decorate2, "_ts_decorate");
-function _ts_metadata2(k, v) {
-  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-}
-__name(_ts_metadata2, "_ts_metadata");
-function _ts_param2(paramIndex, decorator) {
-  return function(target, key) {
-    decorator(target, key, paramIndex);
-  };
-}
-__name(_ts_param2, "_ts_param");
 var AgentRunWorkflow = class _AgentRunWorkflow {
   static {
     __name(this, "AgentRunWorkflow");
@@ -206,6 +90,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
   async run(ctx, input) {
     const day = input.day ?? utcDay();
     const deps = this.factory.forAgent(input.agentName);
+    const dispatchSteps = this.dispatchedSteps ? this.steps : void 0;
     if (input.sinkRunId !== void 0) {
       await ctx.localStep("activate", () => this.store.setActiveStream(input.threadId, ctx.runId));
     }
@@ -243,8 +128,8 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       // `ctx.localStep`s, so a turn isn't pinned to this workflow worker for the model call or a tool
       // execution. `sinkRunId`/`childSink` are sink routing this workflow already resolved above —
       // core's dispatchLlm signature stays sink-topology-agnostic, so we add them here, not in core.
-      ...this.dispatchedSteps ? {
-        dispatchLlm: /* @__PURE__ */ __name((index, envelope) => ctx.step(this.steps.llm, {
+      ...dispatchSteps !== void 0 ? {
+        dispatchLlm: /* @__PURE__ */ __name((index, envelope) => ctx.step(dispatchSteps.llm, {
           ...envelope,
           runId: ctx.runId,
           step: index,
@@ -256,7 +141,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         // ('agent'-kind delegations branch to runAgent earlier in the loop), so anything that
         // isn't 'action' is defensively 'read' — the same posture core takes for an
         // unresolvable `kind`.
-        dispatchTool: /* @__PURE__ */ __name((call, envelope) => ctx.step(this.steps.tool, {
+        dispatchTool: /* @__PURE__ */ __name((call, envelope) => ctx.step(dispatchSteps.tool, {
           ...envelope,
           toolCallId: call.id,
           toolType: call.kind === "action" ? "action" : "read"
@@ -264,7 +149,7 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
       } : {}
     };
     try {
-      const result = await (0, import_nestjs_agent_core2.runAgentLoop)({
+      const result = await (0, import_nestjs_agent_core.runAgentLoop)({
         ...deps,
         day
       }, input, hooks);
@@ -275,8 +160,8 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
         throw error;
       }
       const message = error instanceof Error ? error.message : String(error);
-      const code = error instanceof import_nestjs_agent_core2.QuotaExceededError ? "quota_exceeded" : "run_failed";
-      (0, import_nestjs_agent_core2.publishAgentRunFailed)({
+      const code = error instanceof import_nestjs_agent_core.QuotaExceededError ? "quota_exceeded" : "run_failed";
+      (0, import_nestjs_agent_core.publishAgentRunFailed)({
         runId: ctx.runId,
         code,
         message
@@ -297,24 +182,141 @@ var AgentRunWorkflow = class _AgentRunWorkflow {
     }
   }
 };
-AgentRunWorkflow = _ts_decorate2([
-  (0, import_common2.Injectable)(),
-  (0, import_nestjs_durable2.Workflow)({
+AgentRunWorkflow = _ts_decorate([
+  (0, import_common.Injectable)(),
+  (0, import_nestjs_durable.Workflow)({
     name: "agent.run",
     version: "1"
   }),
-  _ts_param2(0, (0, import_common2.Inject)(import_nestjs_agent_core2.AGENT_DEPS_FACTORY)),
-  _ts_param2(1, (0, import_common2.Inject)(import_nestjs_agent_core2.AGENT_STORE)),
-  _ts_param2(3, (0, import_common2.Inject)(AGENT_DISPATCHED_STEPS)),
-  _ts_metadata2("design:type", Function),
-  _ts_metadata2("design:paramtypes", [
+  _ts_param(0, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_DEPS_FACTORY)),
+  _ts_param(1, (0, import_common.Inject)(import_nestjs_agent_core.AGENT_STORE)),
+  _ts_param(2, (0, import_common.Optional)()),
+  _ts_param(3, (0, import_common.Inject)(AGENT_DISPATCHED_STEPS)),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
     typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory,
     typeof AgentStore === "undefined" ? Object : AgentStore,
-    typeof AgentRunSteps === "undefined" ? Object : AgentRunSteps,
+    Object,
     Boolean
   ])
 ], AgentRunWorkflow);
 
+// src/durable/agent-run.steps.ts
+var import_nestjs_agent_core2 = require("@dudousxd/nestjs-agent-core");
+var import_nestjs_durable2 = require("@dudousxd/nestjs-durable");
+var import_common2 = require("@nestjs/common");
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param2(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param2, "_ts_param");
+var AgentRunSteps = class {
+  static {
+    __name(this, "AgentRunSteps");
+  }
+  factory;
+  constructor(factory) {
+    this.factory = factory;
+  }
+  /**
+  * Retryable: every side effect (persist/quota/stream markers) happens loop-side under
+  * `hooks.step`, so a durable retry only re-runs the model call and re-streams its tokens — never
+  * double-writes. NEVER call `writer.end()`/`fail()` here: the workflow owns the stream's lifecycle,
+  * across however many turns/retries it takes.
+  */
+  async llm(input) {
+    const deps = this.factory.forAgent(input.agentName);
+    const tools = await deps.registry.definitionsFor(input.actor, deps.rolesPolicy, deps.toolAllowList);
+    const opened = await deps.sink.open(input.sinkRunId);
+    const writer = input.childSink ? childSinkWriter(opened) : opened;
+    return (0, import_nestjs_agent_core2.traceLlmTurn)(input.runId, input.step, () => deps.model.runTurn({
+      system: input.system,
+      messages: input.messages,
+      tools,
+      sink: writer
+    }));
+  }
+  /**
+  * NO DURABLE retries — a tool may not be idempotent (a bare `@Step()` carries none, unlike `llm`
+  * above). What it does retry, in place, is a CLASSIFIED-TRANSIENT error from the tool's own
+  * invocation (a DB deadlock, a lock-wait timeout — see `isTransientToolError`): the server rolled
+  * that work back, so re-invoking it is safe, and doing it here (inside this one step, never a new
+  * checkpoint) is exactly how the non-dispatched loop path handles it too. The timeout is applied
+  * HERE, handler-side, via `withToolTimeout` — never as a durable dispatch `timeoutMs`, which
+  * bounds engine liveness (retryable) rather than the tool's own business outcome — and per
+  * ATTEMPT, so a retried invocation gets its own fresh timeout window.
+  */
+  async tool(input) {
+    const deps = this.factory.forAgent(input.ctx.agentName);
+    const ctx = {
+      ...input.ctx
+    };
+    const localClassify = deps.toolTransientRetry !== false ? deps.toolTransientRetry?.classify : void 0;
+    const transientRetry = input.transientRetry === false ? false : {
+      attempts: input.transientRetry.attempts,
+      backoffMs: input.transientRetry.backoffMs,
+      ...localClassify !== void 0 ? {
+        classify: localClassify
+      } : {}
+    };
+    return (0, import_nestjs_agent_core2.traceToolExecution)(input.ctx.runId, {
+      toolCallId: input.toolCallId,
+      toolName: input.toolName,
+      toolType: input.toolType
+    }, () => (0, import_nestjs_agent_core2.invokeWithTransientRetry)(() => {
+      const invocation = deps.registry.invoke(input.toolName, input.input, ctx, deps.rolesPolicy);
+      return input.timeoutMs !== void 0 ? (0, import_nestjs_agent_core2.withToolTimeout)(invocation, input.timeoutMs, input.toolName) : invocation;
+    }, transientRetry, {
+      onRetry: /* @__PURE__ */ __name((attempt, error) => {
+        (0, import_nestjs_agent_core2.publishAgentToolRetry)({
+          toolName: input.toolName,
+          toolCallId: input.toolCallId,
+          attempt,
+          message: error instanceof Error ? error.message : String(error)
+        });
+      }, "onRetry")
+    }));
+  }
+};
+_ts_decorate2([
+  (0, import_nestjs_durable2.Step)({
+    retries: 3
+  }),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof DispatchedLlmInput === "undefined" ? Object : DispatchedLlmInput
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], AgentRunSteps.prototype, "llm", null);
+_ts_decorate2([
+  (0, import_nestjs_durable2.Step)(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof DispatchedToolInput === "undefined" ? Object : DispatchedToolInput
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], AgentRunSteps.prototype, "tool", null);
+AgentRunSteps = _ts_decorate2([
+  (0, import_common2.Injectable)(),
+  _ts_param2(0, (0, import_common2.Inject)(import_nestjs_agent_core2.AGENT_DEPS_FACTORY)),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentDepsFactory === "undefined" ? Object : AgentDepsFactory
+  ])
+], AgentRunSteps);
+
 // src/durable/durable-agent-runner.ts
 var import_node_crypto = require("crypto");
 var import_nestjs_durable3 = require("@dudousxd/nestjs-durable");
@@ -452,16 +454,68 @@ function _ts_decorate4(decorators, target, key, desc) {
 }
 __name(_ts_decorate4, "_ts_decorate");
 var logger = new import_common4.Logger("AgentDurableModule");
+function runnerProviders() {
+  return [
+    DurableAgentRunner,
+    {
+      provide: import_nestjs_agent_core4.AGENT_DURABLE_RUNNER,
+      useExisting: DurableAgentRunner
+    },
+    {
+      provide: AGENT_DISPATCHED_STEPS,
+      useFactory: /* @__PURE__ */ __name((options, sink) => {
+        const enabled = options.durable === true && options.dispatchedSteps !== false;
+        if (enabled && sink instanceof InProcessTokenStreamSink) {
+          logger.warn("Dispatched steps are active (the default under durable: true) with the default InProcessTokenStreamSink, which only buffers tokens in-process. A dispatched `llm` step served by a different worker cannot stream into this buffer. Wire a cross-process TokenStreamSink (e.g. a Redis pub/sub sink) via AgentModule.forRoot({ sink }) before running multi-pod, or set dispatchedSteps: false to keep the turn in-process localSteps.");
+        }
+        return enabled;
+      }, "useFactory"),
+      inject: [
+        import_nestjs_agent_core4.AGENT_OPTIONS,
+        import_nestjs_agent_core4.AGENT_SINK
+      ]
+    }
+  ];
+}
+__name(runnerProviders, "runnerProviders");
+var AgentDurableHttpModule = class AgentDurableHttpModule2 {
+  static {
+    __name(this, "AgentDurableHttpModule");
+  }
+};
+AgentDurableHttpModule = _ts_decorate4([
+  (0, import_common4.Global)(),
+  (0, import_common4.Module)({
+    providers: [
+      AgentRunWorkflow,
+      ...runnerProviders()
+    ],
+    exports: [
+      import_nestjs_agent_core4.AGENT_DURABLE_RUNNER,
+      AgentRunWorkflow,
+      AGENT_DISPATCHED_STEPS
+    ]
+  })
+], AgentDurableHttpModule);
 var AgentDurableModule = class _AgentDurableModule {
   static {
     __name(this, "AgentDurableModule");
   }
   /**
-  * The dynamic form used by the `agentDurable` helper. The module needs no configuration of its
-  * own (its providers come from the decorator above), so this just yields the module reference —
-  * importing `AgentDurableModule` directly stays equivalent.
+  * `surface: 'http'` returns the reduced `AgentDurableHttpModule` wiring (no `AgentRunSteps`);
+  * everything else (omitted, `'engine'`, `'both'`) returns this module's own full wiring — the
+  * class's `@Module` providers above merge in regardless of which DynamicModule shape a caller
+  * imports (Nest merges a class's static provider list with whatever a self-referencing
+  * `DynamicModule` adds), which is exactly why the reduced case has to be a DIFFERENT module class
+  * rather than a conditional subset of this one's own decorator.
   */
-  static forRoot() {
+  static forRoot(options) {
+    if (options?.surface === "http") {
+      return {
+        module: AgentDurableHttpModule,
+        global: true
+      };
+    }
     return {
       module: _AgentDurableModule,
       global: true
@@ -474,25 +528,7 @@ AgentDurableModule = _ts_decorate4([
     providers: [
       AgentRunWorkflow,
       AgentRunSteps,
-      DurableAgentRunner,
-      {
-        provide: import_nestjs_agent_core4.AGENT_DURABLE_RUNNER,
-        useExisting: DurableAgentRunner
-      },
-      {
-        provide: AGENT_DISPATCHED_STEPS,
-        useFactory: /* @__PURE__ */ __name((options, sink) => {
-          const enabled = options.durable === true && options.dispatchedSteps !== false;
-          if (enabled && sink instanceof InProcessTokenStreamSink) {
-            logger.warn("Dispatched steps are active (the default under durable: true) with the default InProcessTokenStreamSink, which only buffers tokens in-process. A dispatched `llm` step served by a different worker cannot stream into this buffer. Wire a cross-process TokenStreamSink (e.g. a Redis pub/sub sink) via AgentModule.forRoot({ sink }) before running multi-pod, or set dispatchedSteps: false to keep the turn in-process localSteps.");
-          }
-          return enabled;
-        }, "useFactory"),
-        inject: [
-          import_nestjs_agent_core4.AGENT_OPTIONS,
-          import_nestjs_agent_core4.AGENT_SINK
-        ]
-      }
+      ...runnerProviders()
     ],
     exports: [
       import_nestjs_agent_core4.AGENT_DURABLE_RUNNER,
@@ -2279,6 +2315,10 @@ function controllersFor(mountAttachments) {
   ] : BASE_CONTROLLERS;
 }
 __name(controllersFor, "controllersFor");
+function controllersForSurface(surface, mountAttachments) {
+  return surface === "engine" ? [] : controllersFor(mountAttachments);
+}
+__name(controllersForSurface, "controllersForSurface");
 var GUARDS_METADATA = "__guards__";
 function applyGuards(guards) {
   const resolved = guards ?? [];
@@ -2324,7 +2364,7 @@ var AgentModule = class _AgentModule {
         import_core3.DiscoveryModule,
         routerFor(path)
       ],
-      controllers: controllersFor(options.attachments?.upload === true),
+      controllers: controllersForSurface(options.surface, options.attachments?.upload === true),
       providers: [
         {
           provide: import_nestjs_agent_core17.AGENT_OPTIONS,
@@ -2349,17 +2389,21 @@ var AgentModule = class _AgentModule {
         routerFor(path),
         ...options.imports ?? []
       ],
-      controllers: controllersFor(options.attachmentsUpload === true),
+      controllers: controllersForSurface(options.surface, options.attachmentsUpload === true),
       providers: [
         {
           provide: import_nestjs_agent_core17.AGENT_OPTIONS,
-          // Stamp the STATIC wiring flags onto the factory result: `durable`/`dispatchedSteps` are
-          // authoritative on the async config object (they decided the actual wiring above), and
-          // `AgentDurableModule` derives the effective dispatched-steps value from AGENT_OPTIONS —
-          // without this stamp, an async host would get in-process localSteps despite durable: true.
+          // Stamp the STATIC wiring flags onto the factory result: `durable`/`dispatchedSteps`/
+          // `surface` are authoritative on the async config object (they decided the actual wiring
+          // above), and `AgentDurableModule` derives the effective dispatched-steps value from
+          // AGENT_OPTIONS — without this stamp, an async host would get in-process localSteps
+          // despite durable: true. `surface` isn't read back by 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",
             ...options.dispatchedSteps !== void 0 ? {
               dispatchedSteps: options.dispatchedSteps
             } : {}
@@ -2385,7 +2429,9 @@ function agentDurable(options) {
       ...options,
       durable: true
     }),
-    AgentDurableModule.forRoot()
+    AgentDurableModule.forRoot(options.surface !== void 0 ? {
+      surface: options.surface
+    } : {})
   ];
 }
 __name(agentDurable, "agentDurable");