@dudousxd/nestjs-agent 0.8.2 → 0.9.0

package/dist/{agent-deps.factory-BlC9tumI.d.cts → agent-deps.factory-DNslT7_J.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. */
@@ -138,6 +143,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

package/dist/{agent-deps.factory-BlC9tumI.d.ts → agent-deps.factory-DNslT7_J.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. */
@@ -138,6 +143,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

package/dist/durable/index.cjs

@@ -100,23 +100,45 @@ var AgentRunSteps = class {
     }));
   }
   /**
-  * 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.
+  * 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([
@@ -591,6 +613,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
       } : {},