@dudousxd/nestjs-agent 0.8.2 → 0.10.0

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,100 +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 retries — a tool may not be idempotent (a bare `@Step()` carries none, unlike `llm` above).
-  * 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.
-  */
-  async tool(input) {
-    const deps = this.factory.forAgent(input.ctx.agentName);
-    const ctx = {
-      ...input.ctx
-    };
-    return (0, import_nestjs_agent_core.traceToolExecution)(input.ctx.runId, {
-      toolCallId: input.toolCallId,
-      toolName: input.toolName,
-      toolType: input.toolType
-    }, () => {
-      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;
-    });
-  }
-};
-_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");
@@ -184,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));
     }
@@ -221,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,
@@ -234,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"
@@ -242,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);
@@ -253,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
@@ -275,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");
@@ -430,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
@@ -452,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,
@@ -591,6 +649,9 @@ var AgentDepsFactory2 = class {
       ...this.options.toolTimeoutMs !== void 0 ? {
         toolTimeoutMs: this.options.toolTimeoutMs
       } : {},
+      ...this.options.toolTransientRetry !== void 0 ? {
+        toolTransientRetry: this.options.toolTransientRetry
+      } : {},
       ...followUpsCount !== void 0 ? {
         followUpsCount
       } : {},
@@ -2254,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 ?? [];
@@ -2299,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,
@@ -2324,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
             } : {}
@@ -2360,7 +2429,9 @@ function agentDurable(options) {
       ...options,
       durable: true
     }),
-    AgentDurableModule.forRoot()
+    AgentDurableModule.forRoot(options.surface !== void 0 ? {
+      surface: options.surface
+    } : {})
   ];
 }
 __name(agentDurable, "agentDurable");