nestjs-langchain 2.1.0 → 2.2.0

package/dist/interfaces/langchain-module-options.interface.d.ts

@@ -64,6 +64,12 @@ export interface LangChainModuleOptions {
     observer?: AgentObserver;
     /** LangChain-native run callbacks, for handlers written against its API. */
     callbacks?: AgentCallback[];
+    /**
+     * The most steps a run may take, each model call and each round of tool
+     * calls counting as one: LangGraph's 25 when omitted. A run's own
+     * `recursionLimit` overrides it.
+     */
+    recursionLimit?: number;
 }
 /**
  * A class building an agent's options, for `registerAsync({ useClass })` or

package/dist/interfaces/langchain-module-options.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langchain-module-options.interface.d.ts","sourceRoot":"","sources":["../../lib/interfaces/langchain-module-options.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,UAAU,aAAa;IACrB,uBAAuB;IACvB,MAAM,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,8DAA8D;IAC9D,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACtC,kCAAkC;IAClC,qBAAqB,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAEzE,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,KAAK,EAAE,WAAW,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;CAC7B;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,sBAAsB,IACpB,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC5D"}
+{"version":3,"file":"langchain-module-options.interface.d.ts","sourceRoot":"","sources":["../../lib/interfaces/langchain-module-options.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAChD,OAAO,KAAK,EACV,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,gCAAgC,CAAC;AACxC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qDAAqD;IACrD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;GAIG;AACH,UAAU,aAAa;IACrB,uBAAuB;IACvB,MAAM,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC3C,8DAA8D;IAC9D,SAAS,CAAC,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;IACtC,kCAAkC;IAClC,qBAAqB,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,OAAO,CAAC;CAClD;AAED;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,CAAC;AAEtD;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,WAAW,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;AAExE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,mBAAmB,GAAG,sBAAsB,CAAC;AAEzE,mEAAmE;AACnE,MAAM,WAAW,sBAAsB;IACrC,wEAAwE;IACxE,KAAK,EAAE,WAAW,CAAC;IACnB,4DAA4D;IAC5D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,4EAA4E;IAC5E,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;OAIG;IACH,sBAAsB,IACpB,sBAAsB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC5D"}

package/dist/interfaces/run-options.interface.d.ts

@@ -6,6 +6,7 @@ import type { ZodType } from 'zod';
  * @example
  * ```ts
  * const { output } = await agent.run(email, { output: Ticket }); // a Ticket
+ * await agent.run(question, { signal: AbortSignal.timeout(30_000) });
  *
  * const ask = (question: string, options?: RunOptions) =>
  *   agent.run(question, options); // `output` is unknown
@@ -17,5 +18,17 @@ export interface RunOptions {
      * typed from it, instead of the model's text.
      */
     output?: ZodType;
+    /**
+     * Aborts the run: `run()` throws an `AgentAbortedError`, the signal's
+     * `reason` in `cause`. A tool already running ends in the background, its
+     * result dropped.
+     */
+    signal?: AbortSignal;
+    /**
+     * The most steps the run may take, each model call and each round of tool
+     * calls counting as one, instead of the agent's `recursionLimit`. Past it,
+     * `run()` throws an `AgentRecursionLimitError`.
+     */
+    recursionLimit?: number;
 }
 //# sourceMappingURL=run-options.interface.d.ts.map

package/dist/interfaces/run-options.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-options.interface.d.ts","sourceRoot":"","sources":["../../lib/interfaces/run-options.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB"}
+{"version":3,"file":"run-options.interface.d.ts","sourceRoot":"","sources":["../../lib/interfaces/run-options.interface.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB"}

package/dist/output/run-output.d.ts

@@ -16,7 +16,7 @@ export declare class RunOutput {
      */
     readonly strategy: TypedToolStrategy;
     /** The tool the model answers through. */
-    readonly toolName = "extract-output";
+    readonly toolName: "extract-output";
     private readonly prefix;
     /**
      * @param schema The run's `output` schema.

package/dist/output/run-output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-output.d.ts","sourceRoot":"","sources":["../../lib/output/run-output.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,iBAAiB,EAClB,MAAM,WAAW,CAAC;AACnB,OAAU,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAqBjC;;;;;GAKG;AACH,qBAAa,SAAS;;IAkBlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAlBxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,oBAAe;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;OAKG;gBAEgB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM;IAqChC,OAAO,CAAC,KAAK;IAUb;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAiBhC;;;;OAIG;IACH,IAAI,CAAC,kBAAkB,EAAE,OAAO,GAAG,OAAO;IAmB1C,OAAO,CAAC,OAAO;CAOhB"}
+{"version":3,"file":"run-output.d.ts","sourceRoot":"","sources":["../../lib/output/run-output.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,iBAAiB,EAClB,MAAM,WAAW,CAAC;AACnB,OAAU,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAqBjC;;;;;GAKG;AACH,qBAAa,SAAS;;IAkBlB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAlBxB;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IACrC,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,mBAAe;IAEhC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAEhC;;;;;OAKG;gBAEgB,MAAM,EAAE,OAAO,EACf,KAAK,EAAE,MAAM;IAqChC,OAAO,CAAC,KAAK;IAUb;;;;OAIG;IACH,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO;IAiBhC;;;;OAIG;IACH,IAAI,CAAC,kBAAkB,EAAE,OAAO,GAAG,OAAO;IAmB1C,OAAO,CAAC,OAAO;CAOhB"}

package/dist/run/index.d.ts

@@ -1,4 +1,5 @@
 export { answeredCalls } from './answered-calls.util.js';
+export { isRecursionLimit } from './recursion-limit.util.js';
 export { summariseRun } from './run-summary.util.js';
 export { UsageAside } from './usage-aside.js';
 export type { RunSummary } from './run-summary.util.js';

package/dist/run/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../lib/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/run/index.js

@@ -1,4 +1,5 @@
 export { answeredCalls } from './answered-calls.util.js';
+export { isRecursionLimit } from './recursion-limit.util.js';
 export { summariseRun } from './run-summary.util.js';
 export { UsageAside } from './usage-aside.js';
 //# sourceMappingURL=index.js.map

package/dist/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../lib/run/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/run/recursion-limit.util.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a `recursionLimit` is one LangGraph applies: it rejects a limit
+ * below 1, but runs on with `NaN`. See #194.
+ *
+ * @internal
+ * @param limit The option as given, from untyped JavaScript too.
+ * @returns `true` for an integer of at least 1, or no limit.
+ */
+export declare const isRecursionLimit: (limit: unknown) => boolean;
+//# sourceMappingURL=recursion-limit.util.d.ts.map

package/dist/run/recursion-limit.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursion-limit.util.d.ts","sourceRoot":"","sources":["../../lib/run/recursion-limit.util.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,OAAO,OAAO,KAAG,OAEoB,CAAC"}

package/dist/run/recursion-limit.util.js

@@ -0,0 +1,11 @@
+/**
+ * Whether a `recursionLimit` is one LangGraph applies: it rejects a limit
+ * below 1, but runs on with `NaN`. See #194.
+ *
+ * @internal
+ * @param limit The option as given, from untyped JavaScript too.
+ * @returns `true` for an integer of at least 1, or no limit.
+ */
+export const isRecursionLimit = (limit) => limit === undefined ||
+    (typeof limit === 'number' && Number.isInteger(limit) && limit >= 1);
+//# sourceMappingURL=recursion-limit.util.js.map

package/dist/run/recursion-limit.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recursion-limit.util.js","sourceRoot":"","sources":["../../lib/run/recursion-limit.util.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,KAAc,EAAW,EAAE,CAC1D,KAAK,KAAK,SAAS;IACnB,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC"}

package/lib/agent.ts

@@ -20,14 +20,15 @@ import {
 } from './tools/index.js';
 import { BaseCallbackHandler } from '@langchain/core/callbacks/base';
 import { LOG_CONTEXT, messageOf, RunReporter } from './logging/index.js';
-import { summariseRun, UsageAside } from './run/index.js';
+import { DEFAULT_RECURSION_LIMIT } from './constants.js';
+import { isRecursionLimit, summariseRun, UsageAside } from './run/index.js';
 import { outputConfig, RunOutput, structuredOutput } from './output/index.js';
-import { AgentRunError, unwrapMiddlewareError } from './errors/index.js';
+import { AgentRunError, toRunError } from './errors/index.js';
 import {
   agentNotBootstrapped,
   agentPrefix,
-  agentRunFailed,
   duplicateAgentName,
+  invalidRecursionLimit,
   modelNeverReplied,
   modelNotBuilt,
   modelReplyEmpty,
@@ -62,9 +63,6 @@ export class Agent implements OnModuleInit {
   private readonly logger = new Logger();
   private readonly prefix: string;
   private readonly reporter: RunReporter;
-  // Model failures, which only LangChain's callbacks see. Tool calls are
-  // reported by their wrapper and the tool middlewares.
-  private readonly modelErrors: BaseCallbackHandler;
 
   /** @internal Built by `LangChainModule`, never by hand. */
   constructor(
@@ -82,14 +80,6 @@ export class Agent implements OnModuleInit {
       prefix: this.prefix,
       observer: options.observer,
     });
-    this.modelErrors = BaseCallbackHandler.fromMethods({
-      handleLLMError: (error: unknown) => {
-        this.reporter.logError(`the model failed: ${messageOf(error)}`);
-        this.reporter.notify((observer) =>
-          observer.onModelError?.({ agent: agentName, error }),
-        );
-      },
-    });
   }
 
   /**
@@ -100,6 +90,12 @@ export class Agent implements OnModuleInit {
   async onModuleInit() {
     this.assertUniqueName();
 
+    const { recursionLimit } = this.options;
+
+    if (!isRecursionLimit(recursionLimit)) {
+      throw new Error(invalidRecursionLimit(this.prefix, recursionLimit));
+    }
+
     const tools = await this.toolDiscovery.getToolsFromModules(
       this.options.tools ?? [],
       this.reporter,
@@ -119,6 +115,11 @@ export class Agent implements OnModuleInit {
         toolErrors(this.reporter),
         structuredOutput(),
       ],
+    }).withConfig({
+      // Traces and callbacks tell agents apart; the unnamed one keeps
+      // LangGraph's name. See #235.
+      runName: this.agentName === UNNAMED_AGENT ? undefined : this.agentName,
+      metadata: { agent: this.agentName },
     });
 
     this.logger.log(
@@ -190,12 +191,15 @@ export class Agent implements OnModuleInit {
    * as an `AgentRunError`, the original error in its `cause`.
    *
    * @param input The user's message.
-   * @param options With `output`, the schema the answer must match.
+   * @param options With `output`, the schema the answer must match; with
+   * `signal`, what aborts the run; with `recursionLimit`, its most steps.
    * @returns The model's answer, the object `output` parses when given, the
    * tools it called and what the run cost.
    * @example
    * ```ts
-   * const { output, tools } = await agent.run('What is 6 times 7?');
+   * const { output, tools } = await agent.run('What is 6 times 7?', {
+   *   signal: AbortSignal.timeout(30_000),
+   * });
    *
    * const { output: ticket } = await agent.run(email, {
    *   output: z.object({ category: z.enum(['billing', 'bug', 'other']) }),
@@ -218,14 +222,31 @@ export class Agent implements OnModuleInit {
   ): Promise<CompletedRun<unknown>> {
     const startedAt = Date.now();
     const durationMs = () => Date.now() - startedAt;
+    // Always passed: left out, a run from another agent's tool would take
+    // that run's limit. See #315.
+    const recursionLimit =
+      options?.recursionLimit ??
+      this.options.recursionLimit ??
+      DEFAULT_RECURSION_LIMIT;
 
     try {
       // Read in the `try`, and `null` from untyped JavaScript taken as no
       // options, as LangChain takes a `null` config. See #291.
       const schema = options?.output;
+
+      if (!isRecursionLimit(recursionLimit)) {
+        throw new AgentRunError(
+          invalidRecursionLimit(this.prefix, recursionLimit),
+          this.agentName,
+        );
+      }
+
       const output = schema && new RunOutput(schema, this.agentName);
       const aside = new UsageAside();
-      const { answer, messages } = await this.complete(input, output, aside);
+      const { answer, messages } = await this.complete(input, output, aside, {
+        signal: options?.signal,
+        recursionLimit,
+      });
       const finished = {
         durationMs: durationMs(),
         ...summariseRun(messages, output?.toolName, aside.usage),
@@ -237,15 +258,12 @@ export class Agent implements OnModuleInit {
 
       return { status: 'completed', output: answer, ...finished };
     } catch (thrown) {
-      const cause = unwrapMiddlewareError(thrown);
-      const error =
-        cause instanceof AgentRunError
-          ? cause
-          : new AgentRunError(
-              agentRunFailed(this.prefix, cause),
-              this.agentName,
-              { cause },
-            );
+      const error = toRunError(thrown, {
+        agent: this.agentName,
+        prefix: this.prefix,
+        signal: options?.signal,
+        recursionLimit,
+      });
 
       this.reporter.notify((observer) =>
         observer.onRunError?.({
@@ -259,10 +277,29 @@ export class Agent implements OnModuleInit {
     }
   }
 
+  // Model failures, which only LangChain's callbacks see; tool calls are
+  // reported by their wrapper and the tool middlewares. One handler per run:
+  // a call the run's signal cuts short is no failure. See #318.
+  private modelErrors(signal: AbortSignal | undefined): BaseCallbackHandler {
+    return BaseCallbackHandler.fromMethods({
+      handleLLMError: (error: unknown) => {
+        if (signal?.aborted) {
+          return;
+        }
+
+        this.reporter.logError(`the model failed: ${messageOf(error)}`);
+        this.reporter.notify((observer) =>
+          observer.onModelError?.({ agent: this.agentName, error }),
+        );
+      },
+    });
+  }
+
   private async complete(
     input: string,
     output: RunOutput | undefined,
     aside: UsageAside,
+    run: Pick<RunOptions, 'signal' | 'recursionLimit'>,
   ): Promise<{ answer: unknown; messages: AgentState['messages'] }> {
     if (!this.#graph) {
       throw new AgentRunError(
@@ -274,8 +311,12 @@ export class Agent implements OnModuleInit {
     const state: AgentState = await this.#graph.invoke(
       { messages: [{ role: 'user', content: input }] },
       {
-        callbacks: [this.modelErrors, ...(this.options.callbacks ?? [])],
+        callbacks: [
+          this.modelErrors(run.signal),
+          ...(this.options.callbacks ?? []),
+        ],
         configurable: { ...outputConfig(output), ...aside.config },
+        ...run,
       },
     );
     const { messages } = state;

package/lib/constants.ts

@@ -11,7 +11,23 @@ export const STRUCTURED_OUTPUT_PREFIX = 'extract-';
 
 // Ours rather than LangChain's counter or the schema's title: the same tool on
 // every run, under the prefix no `@Tool` can take. See #281.
-export const OUTPUT_TOOL = `${STRUCTURED_OUTPUT_PREFIX}output`;
+/**
+ * The name of the tool a run with an `output` schema answers through: a test
+ * faking the model queues a call to it.
+ *
+ * @example
+ * ```ts
+ * const model = fakeModel().respondWithTools([
+ *   { name: OUTPUT_TOOL, args: { category: 'bug' } },
+ * ]);
+ *
+ * const { output } = await agent.run(email, { output: Ticket });
+ * ```
+ */
+export const OUTPUT_TOOL = `${STRUCTURED_OUTPUT_PREFIX}output` as const;
+
+// LangChain's default, restated: it does not export it.
+export const DEFAULT_RECURSION_LIMIT = 25;
 
 // The keys `@Module()` writes, restated: `@nestjs/common/constants` is
 // internal. See #97.

package/lib/errors/agent-aborted.error.ts

@@ -0,0 +1,22 @@
+import { AgentRunError } from './agent-run.error.js';
+
+/**
+ * The run's `signal` was aborted. Its `reason` is in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await agent.run(question, { signal: AbortSignal.timeout(30_000) });
+ * } catch (error) {
+ *   if (error instanceof AgentAbortedError) {
+ *     console.warn('gave up:', error.cause);
+ *   }
+ * }
+ * ```
+ */
+export class AgentAbortedError extends AgentRunError {
+  constructor(message: string, agent: string, options?: { cause?: unknown }) {
+    super(message, agent, options);
+    this.name = 'AgentAbortedError';
+  }
+}

package/lib/errors/agent-recursion-limit.error.ts

@@ -0,0 +1,24 @@
+import { AgentRunError } from './agent-run.error.js';
+
+/**
+ * The run took its `recursionLimit` of steps without an answer: the model kept
+ * calling tools. LangGraph's error is in `cause`.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   await agent.run(question, { recursionLimit: 10 });
+ * } catch (error) {
+ *   if (error instanceof AgentRecursionLimitError) {
+ *     return 'This question needs too many steps.';
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export class AgentRecursionLimitError extends AgentRunError {
+  constructor(message: string, agent: string, options?: { cause?: unknown }) {
+    super(message, agent, options);
+    this.name = 'AgentRecursionLimitError';
+  }
+}

package/lib/errors/index.ts

@@ -1,4 +1,7 @@
+export { AgentAbortedError } from './agent-aborted.error.js';
+export { AgentRecursionLimitError } from './agent-recursion-limit.error.js';
 export { AgentRunError } from './agent-run.error.js';
+export { toRunError } from './run-error.util.js';
 export { StructuredOutputError } from './structured-output.error.js';
 export { ToolConfigurationError } from './tool-configuration.error.js';
 export { unwrapMiddlewareError } from './unwrap-middleware-error.util.js';

package/lib/errors/messages.ts

@@ -158,6 +158,18 @@ export const modelNeverReplied = (
 export const modelReplyEmpty = (prefix: string): string =>
   `The ${prefix}agent's model replied with no text content.`;
 
+export const runAborted = (prefix: string): string =>
+  `The ${prefix}agent's run was aborted.`;
+
+export const recursionLimitReached = (prefix: string, limit: number): string =>
+  `The ${prefix}agent's run reached its recursion limit of ${limit} steps ` +
+  'without an answer. Raise `recursionLimit`, or check what makes the model ' +
+  'keep calling tools.';
+
+export const invalidRecursionLimit = (prefix: string, limit: unknown): string =>
+  `The ${prefix}agent's \`recursionLimit\` must be an integer of at least 1, ` +
+  `not ${typeof limit === 'string' ? `"${limit}"` : String(limit)}.`;
+
 export const noOutputJsonSchemaForm = (
   prefix: string,
   reason: string,

package/lib/errors/run-error.util.ts

@@ -0,0 +1,57 @@
+import { AgentAbortedError } from './agent-aborted.error.js';
+import { AgentRecursionLimitError } from './agent-recursion-limit.error.js';
+import { AgentRunError } from './agent-run.error.js';
+import {
+  agentRunFailed,
+  recursionLimitReached,
+  runAborted,
+} from './messages.js';
+import { unwrapMiddlewareError } from './unwrap-middleware-error.util.js';
+
+interface FailedRun {
+  agent: string;
+  /** Empty for the unnamed agent, `'MATH '` otherwise. */
+  prefix: string;
+  signal?: AbortSignal;
+  /** The limit the run was given. */
+  recursionLimit: number;
+}
+
+/**
+ * The `AgentRunError` `run()` throws for what the agent's graph threw.
+ *
+ * @internal
+ * @param thrown What the graph threw.
+ * @param run The run that failed.
+ * @returns The error itself when it is one already, else the subclass of its
+ * kind, the original in `cause`.
+ */
+export const toRunError = (
+  thrown: unknown,
+  { agent, prefix, signal, recursionLimit }: FailedRun,
+): AgentRunError => {
+  const cause = unwrapMiddlewareError(thrown);
+
+  if (cause instanceof AgentRunError) {
+    return cause;
+  }
+
+  // The reason itself, which LangChain may have wrapped on its way out.
+  if (signal?.aborted) {
+    return new AgentAbortedError(runAborted(prefix), agent, {
+      cause: signal.reason,
+    });
+  }
+
+  // By name, as LangGraph tells its errors apart; it is not a dependency of
+  // ours. See #194.
+  if (cause instanceof Error && cause.name === 'GraphRecursionError') {
+    return new AgentRecursionLimitError(
+      recursionLimitReached(prefix, recursionLimit),
+      agent,
+      { cause },
+    );
+  }
+
+  return new AgentRunError(agentRunFailed(prefix, cause), agent, { cause });
+};

package/lib/index.ts

@@ -3,7 +3,10 @@
 export { LangChainModule } from './langchain.module.js';
 export { getAgentToken } from './langchain.module-definition.js';
 export { Agent } from './agent.js';
+export { OUTPUT_TOOL } from './constants.js';
 export {
+  AgentAbortedError,
+  AgentRecursionLimitError,
   AgentRunError,
   StructuredOutputError,
   ToolConfigurationError,

package/lib/interfaces/langchain-module-options.interface.ts

@@ -73,6 +73,12 @@ export interface LangChainModuleOptions {
   observer?: AgentObserver;
   /** LangChain-native run callbacks, for handlers written against its API. */
   callbacks?: AgentCallback[];
+  /**
+   * The most steps a run may take, each model call and each round of tool
+   * calls counting as one: LangGraph's 25 when omitted. A run's own
+   * `recursionLimit` overrides it.
+   */
+  recursionLimit?: number;
 }
 
 /**

package/lib/interfaces/run-options.interface.ts

@@ -7,6 +7,7 @@ import type { ZodType } from 'zod';
  * @example
  * ```ts
  * const { output } = await agent.run(email, { output: Ticket }); // a Ticket
+ * await agent.run(question, { signal: AbortSignal.timeout(30_000) });
  *
  * const ask = (question: string, options?: RunOptions) =>
  *   agent.run(question, options); // `output` is unknown
@@ -18,4 +19,16 @@ export interface RunOptions {
    * typed from it, instead of the model's text.
    */
   output?: ZodType;
+  /**
+   * Aborts the run: `run()` throws an `AgentAbortedError`, the signal's
+   * `reason` in `cause`. A tool already running ends in the background, its
+   * result dropped.
+   */
+  signal?: AbortSignal;
+  /**
+   * The most steps the run may take, each model call and each round of tool
+   * calls counting as one, instead of the agent's `recursionLimit`. Past it,
+   * `run()` throws an `AgentRecursionLimitError`.
+   */
+  recursionLimit?: number;
 }

package/lib/run/index.ts

@@ -1,4 +1,5 @@
 export { answeredCalls } from './answered-calls.util.js';
+export { isRecursionLimit } from './recursion-limit.util.js';
 export { summariseRun } from './run-summary.util.js';
 export { UsageAside } from './usage-aside.js';
 export type { RunSummary } from './run-summary.util.js';

package/lib/run/recursion-limit.util.ts

@@ -0,0 +1,11 @@
+/**
+ * Whether a `recursionLimit` is one LangGraph applies: it rejects a limit
+ * below 1, but runs on with `NaN`. See #194.
+ *
+ * @internal
+ * @param limit The option as given, from untyped JavaScript too.
+ * @returns `true` for an integer of at least 1, or no limit.
+ */
+export const isRecursionLimit = (limit: unknown): boolean =>
+  limit === undefined ||
+  (typeof limit === 'number' && Number.isInteger(limit) && limit >= 1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nestjs-langchain",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "type": "module",
   "description": "AI agents for NestJS, powered by LangChain: declare agents as modules, give them your services as tools.",
   "keywords": [
@@ -70,7 +70,7 @@
     "format": "prettier --write \"{lib,tests,scripts}/**/*.{ts,mjs}\" vitest.config.ts",
     "lint": "oxlint --type-aware lib/ tests/ scripts/ vitest.config.ts --fix",
     "lint:check": "oxlint --type-aware lib/ tests/ scripts/ vitest.config.ts",
-    "test": "vitest run --typecheck",
+    "test": "vitest run && tsc --noEmit",
     "test:watch": "vitest",
     "release": "release-it",
     "release:rc": "release-it --preRelease=rc --no-plugins.@release-it/conventional-changelog.infile",
@@ -92,7 +92,7 @@
     "@nestjs/testing": "^12.0.1",
     "@release-it/conventional-changelog": "12.0.2",
     "@types/node": "^26.6.4",
-    "@vitest/coverage-v8": "^4.1.11",
+    "@vitest/coverage-v8": "^5.0.5",
     "eslint-plugin-jsdoc": "^65.2.0",
     "husky": "9.1.7",
     "langchain": "^1.5.4",
@@ -107,7 +107,7 @@
     "rxjs": "^7.8.2",
     "semver": "^7.8.5",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.11",
+    "vitest": "^5.0.5",
     "zod": "^4.0.0"
   },
   "peerDependencies": {