nestjs-langchain 1.0.2 → 2.0.0

package/dist/tools/tool-errors.middleware.js

@@ -0,0 +1,55 @@
+import { createMiddleware, toolErrorMiddleware, ToolInvocationError, } from 'langchain';
+import { unknownTool } from '../errors/messages.js';
+import { reportToolError } from '../logging/index.js';
+/**
+ * Turns a failed tool call into the text the model receives, LangChain's own,
+ * without the stack (and its server paths) LangChain puts in a schema failure.
+ * Every error is answered: past a middleware, LangChain's tool node rethrows
+ * any error left unhandled and fails the run. See #176.
+ *
+ * Also the only place that sees arguments the schema rejects, which never
+ * reach the `@Tool` wrapper: they are reported here. See #177.
+ *
+ * Once langchain-ai/langchainjs#11830 ships, LangChain's own text has no stack
+ * and `tool-errors.middleware.spec.ts` fails: the schema text can be left to
+ * LangChain, the reporting stays.
+ */
+export const toolErrors = (reporter) => toolErrorMiddleware({
+    onError: (error) => {
+        if (!ToolInvocationError.isInstance(error)) {
+            // LangChain's default for a method that throws.
+            return `${String(error)}\n Please fix your mistakes.`;
+        }
+        const { toolCall, toolError } = error;
+        reportToolError(reporter, {
+            tool: toolCall.name,
+            callId: toolCall.id ?? '',
+            reason: 'invalid-arguments',
+            error: toolError,
+            durationMs: 0,
+        });
+        return (`Error invoking tool '${toolCall.name}' with kwargs ` +
+            `${JSON.stringify(toolCall.args)} with error: ${String(toolError)}\n` +
+            ' Please fix the error and try again.');
+    },
+});
+/**
+ * Reports a call to a tool the agent does not have. LangChain's tool node
+ * answers the model itself, without throwing, so `toolErrors` never sees it.
+ */
+export const unknownTools = (reporter) => createMiddleware({
+    name: 'unknownTools',
+    wrapToolCall: (request, handler) => {
+        if (!request.tool) {
+            reportToolError(reporter, {
+                tool: request.toolCall.name,
+                callId: request.toolCall.id ?? '',
+                reason: 'unknown-tool',
+                error: new Error(unknownTool()),
+                durationMs: 0,
+            });
+        }
+        return handler(request);
+    },
+});
+//# sourceMappingURL=tool-errors.middleware.js.map

package/dist/tools/tool-errors.middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-errors.middleware.js","sourceRoot":"","sources":["../../lib/tools/tool-errors.middleware.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,WAAW,CAAC;AACnB,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAe,MAAM,qBAAqB,CAAC;AAEnE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,QAAqB,EAAE,EAAE,CAClD,mBAAmB,CAAC;IAClB,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;QACjB,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC;YAC3C,gDAAgD;YAChD,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC;QACxD,CAAC;QAED,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,KAAK,CAAC;QAEtC,eAAe,CAAC,QAAQ,EAAE;YACxB,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,MAAM,EAAE,QAAQ,CAAC,EAAE,IAAI,EAAE;YACzB,MAAM,EAAE,mBAAmB;YAC3B,KAAK,EAAE,SAAS;YAChB,UAAU,EAAE,CAAC;SACd,CAAC,CAAC;QAEH,OAAO,CACL,wBAAwB,QAAQ,CAAC,IAAI,gBAAgB;YACrD,GAAG,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,gBAAgB,MAAM,CAAC,SAAS,CAAC,IAAI;YACrE,sCAAsC,CACvC,CAAC;IACJ,CAAC;CACF,CAAC,CAAC;AAEL;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,QAAqB,EAAE,EAAE,CACpD,gBAAgB,CAAC;IACf,IAAI,EAAE,cAAc;IACpB,YAAY,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE;QACjC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAClB,eAAe,CAAC,QAAQ,EAAE;gBACxB,IAAI,EAAE,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAC3B,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE;gBACjC,MAAM,EAAE,cAAc;gBACtB,KAAK,EAAE,IAAI,KAAK,CAAC,WAAW,EAAE,CAAC;gBAC/B,UAAU,EAAE,CAAC;aACd,CAAC,CAAC;QACL,CAAC;QAED,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;CACF,CAAC,CAAC"}

package/dist/tools/tool-method.util.d.ts

@@ -0,0 +1,21 @@
+import { ToolOptions, ToolParamMetadata } from '../decorators/tool.decorator.js';
+/** A provider method decorated with `@Tool()`, and what its decorators recorded. */
+export interface ToolMethod {
+    /** `MathService.add`, to name the method in error messages. */
+    where: string;
+    /** The method name, the tool's name when `options` gives none. */
+    method: string;
+    options: ToolOptions;
+    /** The `@ToolParam()` metadata, in declaration order. */
+    params: ToolParamMetadata[];
+    /** The declared parameter types, from TypeScript's `design:paramtypes`. */
+    paramTypes: unknown[];
+    /** Calls the method on its provider, with its arguments by position. */
+    call: (args: unknown[]) => unknown;
+}
+/**
+ * Reads `method` of a provider instance, or `undefined` if it is not a
+ * `@Tool()`. Throws when it carries a `@ToolParam()` but no `@Tool()`.
+ */
+export declare const readToolMethod: (instance: object, method: string) => ToolMethod | undefined;
+//# sourceMappingURL=tool-method.util.d.ts.map

package/dist/tools/tool-method.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-method.util.d.ts","sourceRoot":"","sources":["../../lib/tools/tool-method.util.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,WAAW,EACX,iBAAiB,EAClB,MAAM,iCAAiC,CAAC;AAKzC,oFAAoF;AACpF,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,KAAK,EAAE,MAAM,CAAC;IACd,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,WAAW,CAAC;IACrB,yDAAyD;IACzD,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,2EAA2E;IAC3E,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,wEAAwE;IACxE,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC;CACpC;AAiBD;;;GAGG;AACH,eAAO,MAAM,cAAc,GACzB,UAAU,MAAM,EAChB,QAAQ,MAAM,KACb,UAAU,GAAG,SA8Bf,CAAC"}

package/dist/tools/tool-method.util.js

@@ -0,0 +1,39 @@
+import { PARAM_TYPES_METADATA, TOOL_METADATA, TOOL_PARAMS_METADATA, } from '../constants.js';
+import { toolParamWithoutTool } from '../errors/messages.js';
+// The prototype that defines `method`: its metadata belongs to the function
+// `instance[method]` resolves to, the one carrying `@Tool()` or not.
+const definingPrototype = (instance, method) => {
+    let prototype = Object.getPrototypeOf(instance);
+    while (prototype &&
+        !Object.prototype.hasOwnProperty.call(prototype, method)) {
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return prototype ?? instance;
+};
+/**
+ * Reads `method` of a provider instance, or `undefined` if it is not a
+ * `@Tool()`. Throws when it carries a `@ToolParam()` but no `@Tool()`.
+ */
+export const readToolMethod = (instance, method) => {
+    const provider = instance;
+    const options = Reflect.getMetadata(TOOL_METADATA, provider[method]);
+    const owner = definingPrototype(instance, method);
+    const declared = Reflect.getOwnMetadata(TOOL_PARAMS_METADATA, owner, method) ?? [];
+    const where = `${instance.constructor.name}.${method}`;
+    if (!options) {
+        if (declared.length > 0) {
+            throw new Error(toolParamWithoutTool(where));
+        }
+        return undefined;
+    }
+    return {
+        where,
+        method,
+        options,
+        // Parameter decorators run right to left.
+        params: [...declared].sort((a, b) => a.index - b.index),
+        paramTypes: Reflect.getOwnMetadata(PARAM_TYPES_METADATA, owner, method) ?? [],
+        call: (args) => provider[method](...args),
+    };
+};
+//# sourceMappingURL=tool-method.util.js.map

package/dist/tools/tool-method.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-method.util.js","sourceRoot":"","sources":["../../lib/tools/tool-method.util.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AAKzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAmB7D,4EAA4E;AAC5E,qEAAqE;AACrE,MAAM,iBAAiB,GAAG,CAAC,QAAgB,EAAE,MAAc,EAAU,EAAE;IACrE,IAAI,SAAS,GAAkB,MAAM,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAE/D,OACE,SAAS;QACT,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,EACxD,CAAC;QACD,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,SAAS,CAAC,CAAC;IAC/C,CAAC;IAED,OAAO,SAAS,IAAI,QAAQ,CAAC;AAC/B,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,QAAgB,EAChB,MAAc,EACU,EAAE;IAC1B,MAAM,QAAQ,GAAG,QAAoB,CAAC;IACtC,MAAM,OAAO,GAA4B,OAAO,CAAC,WAAW,CAC1D,aAAa,EACb,QAAQ,CAAC,MAAM,CAAC,CACjB,CAAC;IAEF,MAAM,KAAK,GAAG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAClD,MAAM,QAAQ,GACZ,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;IACpE,MAAM,KAAK,GAAG,GAAG,QAAQ,CAAC,WAAW,CAAC,IAAI,IAAI,MAAM,EAAE,CAAC;IAEvD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/C,CAAC;QAED,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO;QACL,KAAK;QACL,MAAM;QACN,OAAO;QACP,0CAA0C;QAC1C,MAAM,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC;QACvD,UAAU,EACR,OAAO,CAAC,cAAc,CAAC,oBAAoB,EAAE,KAAK,EAAE,MAAM,CAAC,IAAI,EAAE;QACnE,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC;KAC1C,CAAC;AACJ,CAAC,CAAC"}

package/dist/tools/tool-modules.util.d.ts

@@ -0,0 +1,14 @@
+import { Type } from '@nestjs/common';
+import { ToolModule } from '../interfaces/langchain-module-options.interface.js';
+interface ToolModules {
+    modules: Set<Type>;
+    problems: string[];
+}
+/**
+ * Split the `tools` entries into the modules discovery can match and the
+ * problems to report. `inContext` counts the modules Nest registered per
+ * class: one per plain import, one per dynamic module.
+ */
+export declare const resolveToolModules: (entries: readonly ToolModule[], inContext: ReadonlyMap<Type, number>) => Promise<ToolModules>;
+export {};
+//# sourceMappingURL=tool-modules.util.d.ts.map

package/dist/tools/tool-modules.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-modules.util.d.ts","sourceRoot":"","sources":["../../lib/tools/tool-modules.util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAOvE,OAAO,EAAE,UAAU,EAAE,MAAM,qDAAqD,CAAC;AAqDjF,UAAU,WAAW;IACnB,OAAO,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;IACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,SAAS,UAAU,EAAE,EAC9B,WAAW,WAAW,CAAC,IAAI,EAAE,MAAM,CAAC,KACnC,OAAO,CAAC,WAAW,CA8BrB,CAAC"}

package/dist/tools/tool-modules.util.js

@@ -0,0 +1,61 @@
+import { MODULE_METADATA_KEYS } from '../constants.js';
+import { notAToolModule, severalToolModuleInstances, toolModuleNotImported, } from '../errors/messages.js';
+// `@Module({})` writes no metadata at all, so an unimported empty module and a
+// plain class are indistinguishable. Only used to sharpen the message.
+const looksLikeAModule = (entry) => MODULE_METADATA_KEYS.some((key) => Reflect.getMetadata(key, entry) !== undefined);
+/**
+ * Reduce an entry to the class Nest registered it under, the way the scanner
+ * resolves `imports`: await it, call a forward reference, take `module` off a
+ * dynamic module.
+ */
+const toModuleClass = async (entry) => {
+    const awaited = await entry;
+    if (typeof awaited === 'function') {
+        return { type: awaited, declaresItself: false };
+    }
+    if (typeof awaited !== 'object' || awaited === null) {
+        return { declaresItself: false };
+    }
+    const reference = awaited;
+    if (typeof reference.forwardRef === 'function') {
+        return toModuleClass(reference.forwardRef());
+    }
+    const dynamic = awaited;
+    if (!dynamic.module) {
+        return { declaresItself: false };
+    }
+    return { ...(await toModuleClass(dynamic.module)), declaresItself: true };
+};
+// Only reached when the entry resolved to no class at all.
+const describeEntry = (entry) => entry === null || entry === undefined
+    ? String(entry)
+    : `an entry of type ${typeof entry}`;
+/**
+ * Split the `tools` entries into the modules discovery can match and the
+ * problems to report. `inContext` counts the modules Nest registered per
+ * class: one per plain import, one per dynamic module.
+ */
+export const resolveToolModules = async (entries, inContext) => {
+    const modules = new Set();
+    const problems = [];
+    for (const entry of entries) {
+        // A circular import resolves to `undefined` here rather than to a class.
+        const { type, declaresItself } = await toModuleClass(entry);
+        const instances = type ? (inContext.get(type) ?? 0) : 0;
+        if (type && instances === 1) {
+            modules.add(type);
+            continue;
+        }
+        // Tools are matched by class, which would merge the instances' tools.
+        // See #234.
+        if (type && instances > 1) {
+            problems.push(severalToolModuleInstances(type.name, instances));
+            continue;
+        }
+        const name = type?.name ?? describeEntry(entry);
+        const isModule = type && (declaresItself || looksLikeAModule(type));
+        problems.push(isModule ? toolModuleNotImported(name) : notAToolModule(name));
+    }
+    return { modules, problems };
+};
+//# sourceMappingURL=tool-modules.util.js.map

package/dist/tools/tool-modules.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-modules.util.js","sourceRoot":"","sources":["../../lib/tools/tool-modules.util.ts"],"names":[],"mappings":"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"}

package/dist/tools/tool-name.util.d.ts

@@ -0,0 +1,10 @@
+export declare const resolveToolName: (declared: string | undefined, method: string, where: string) => string;
+/**
+ * One problem per tool whose name an earlier tool already took, naming both
+ * methods. `where` is the method each tool was built from.
+ */
+export declare const findDuplicateToolNames: (tools: {
+    name: string;
+    where: string;
+}[]) => string[];
+//# sourceMappingURL=tool-name.util.d.ts.map

package/dist/tools/tool-name.util.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.util.d.ts","sourceRoot":"","sources":["../../lib/tools/tool-name.util.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,eAAe,GAC1B,UAAU,MAAM,GAAG,SAAS,EAC5B,QAAQ,MAAM,EACd,OAAO,MAAM,KACZ,MAcF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,sBAAsB,GACjC,OAAO;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,KACvC,MAAM,EAgBR,CAAC"}

package/dist/tools/tool-name.util.js

@@ -0,0 +1,35 @@
+import { duplicateToolName, invalidToolName, reservedToolName, } from '../errors/messages.js';
+// OpenAI's limit, the strictest published, restated: no provider SDK exports
+// it. See #90.
+const TOOL_NAME = /^[a-zA-Z0-9_-]{1,64}$/;
+// The agent routes a call with this prefix to structured output, never to the
+// tool. Restated: LangChain does not export it. See #213.
+const STRUCTURED_OUTPUT_PREFIX = 'extract-';
+export const resolveToolName = (declared, method, where) => {
+    const name = declared ?? method;
+    if (!TOOL_NAME.test(name)) {
+        throw new Error(invalidToolName(where, name, String(TOOL_NAME), declared === undefined));
+    }
+    if (name.startsWith(STRUCTURED_OUTPUT_PREFIX)) {
+        throw new Error(reservedToolName(where, name, STRUCTURED_OUTPUT_PREFIX));
+    }
+    return name;
+};
+/**
+ * One problem per tool whose name an earlier tool already took, naming both
+ * methods. `where` is the method each tool was built from.
+ */
+export const findDuplicateToolNames = (tools) => {
+    const seen = new Map();
+    const problems = [];
+    tools.forEach(({ name, where }) => {
+        const first = seen.get(name);
+        if (first) {
+            problems.push(duplicateToolName(name, first, where));
+            return;
+        }
+        seen.set(name, where);
+    });
+    return problems;
+};
+//# sourceMappingURL=tool-name.util.js.map

package/dist/tools/tool-name.util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-name.util.js","sourceRoot":"","sources":["../../lib/tools/tool-name.util.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,6EAA6E;AAC7E,eAAe;AACf,MAAM,SAAS,GAAG,uBAAuB,CAAC;AAE1C,8EAA8E;AAC9E,0DAA0D;AAC1D,MAAM,wBAAwB,GAAG,UAAU,CAAC;AAE5C,MAAM,CAAC,MAAM,eAAe,GAAG,CAC7B,QAA4B,EAC5B,MAAc,EACd,KAAa,EACL,EAAE;IACV,MAAM,IAAI,GAAG,QAAQ,IAAI,MAAM,CAAC;IAEhC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,SAAS,CAAC,EAAE,QAAQ,KAAK,SAAS,CAAC,CACxE,CAAC;IACJ,CAAC;IAED,IAAI,IAAI,CAAC,UAAU,CAAC,wBAAwB,CAAC,EAAE,CAAC;QAC9C,MAAM,IAAI,KAAK,CAAC,gBAAgB,CAAC,KAAK,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC,CAAC;IAC3E,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,KAAwC,EAC9B,EAAE;IACZ,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAC;IACvC,MAAM,QAAQ,GAAa,EAAE,CAAC;IAE9B,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE;QAChC,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAE7B,IAAI,KAAK,EAAE,CAAC;YACV,QAAQ,CAAC,IAAI,CAAC,iBAAiB,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC;YACrD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACxB,CAAC,CAAC,CAAC;IAEH,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC"}

package/dist/tools/tool-schema.factory.d.ts

@@ -0,0 +1,4 @@
+import { ZodObject } from 'zod';
+import { ToolParamMetadata } from '../decorators/tool.decorator.js';
+export declare const buildToolSchema: (params: ToolParamMetadata[], paramTypes: unknown[], where: string) => ZodObject;
+//# sourceMappingURL=tool-schema.factory.d.ts.map

package/dist/tools/tool-schema.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.factory.d.ts","sourceRoot":"","sources":["../../lib/tools/tool-schema.factory.ts"],"names":[],"mappings":"AAEA,OAAU,EAAE,SAAS,EAAW,MAAM,KAAK,CAAC;AAC5C,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AAwGpE,eAAO,MAAM,eAAe,GAC1B,QAAQ,iBAAiB,EAAE,EAC3B,YAAY,OAAO,EAAE,EACrB,OAAO,MAAM,KACZ,SA8BF,CAAC"}

package/dist/tools/tool-schema.factory.js

@@ -0,0 +1,87 @@
+import { toJsonSchema } from '@langchain/core/utils/json_schema';
+import z from 'zod';
+import { cannotInferSchema, duplicateParamName, noJsonSchemaForm, schemaContradictsSignature, } from '../errors/messages.js';
+import { messageOf } from '../logging/index.js';
+const INFERRED = new Map([
+    [String, () => z.string()],
+    [Number, () => z.number()],
+    [Boolean, () => z.boolean()],
+]);
+// The JSON Schema types each primitive signature accepts, the first naming it.
+// `integer` is a subset of `number`.
+const JSON_SCHEMA_TYPES = new Map([
+    [String, ['string']],
+    [Number, ['number', 'integer']],
+    [Boolean, ['boolean']],
+]);
+const resolveSchema = (param, paramType, where) => {
+    if (param.schema) {
+        return param.schema;
+    }
+    const inferred = INFERRED.get(paramType);
+    if (!inferred) {
+        const declared = paramType?.name ?? 'unknown';
+        throw new Error(cannotInferSchema(where, param.name, declared));
+    }
+    return inferred();
+};
+// The JSON Schema types a schema allows, from its `type` or from the branches
+// of its `anyOf`: zod 4 gives a union either form (see #137). `undefined` when
+// it has no JSON Schema form, or a branch names no type.
+const typesOf = (schema) => {
+    let node;
+    try {
+        node = z.toJSONSchema(schema);
+    }
+    catch {
+        return undefined;
+    }
+    const branches = node.type === undefined && node.anyOf ? node.anyOf : [node];
+    if (branches.some((branch) => branch.type === undefined)) {
+        return undefined;
+    }
+    return branches.flatMap((branch) => branch.type ?? []);
+};
+// A declared schema LangChain cannot convert to the JSON Schema a provider
+// receives. Wrapped in an object, as LangChain converts a tool's schema: only
+// there does it read the input side of a `.transform()`.
+const checkJsonSchemaForm = (param, schema, where) => {
+    try {
+        toJsonSchema(z.object({ [param.name]: schema }));
+    }
+    catch (error) {
+        throw new Error(noJsonSchemaForm(where, param.name, messageOf(error)));
+    }
+};
+// A declared schema that contradicts a primitive signature. Skipped for any
+// other signature, where the schema is the only source of truth.
+const checkAgainstSignature = (param, paramType, schema, where) => {
+    const accepted = JSON_SCHEMA_TYPES.get(paramType);
+    const types = accepted && typesOf(schema);
+    if (!accepted || !types || types.some((type) => accepted.includes(type))) {
+        return;
+    }
+    throw new Error(schemaContradictsSignature(where, param.name, types, accepted[0]));
+};
+export const buildToolSchema = (params, paramTypes, where) => {
+    const shape = {};
+    const indexes = new Map();
+    params.forEach((param) => {
+        const first = indexes.get(param.name);
+        if (first !== undefined) {
+            throw new Error(duplicateParamName(where, param.name, first, param.index));
+        }
+        indexes.set(param.name, param.index);
+        const resolved = resolveSchema(param, paramTypes[param.index], where);
+        if (param.schema) {
+            checkJsonSchemaForm(param, resolved, where);
+            checkAgainstSignature(param, paramTypes[param.index], resolved, where);
+        }
+        const described = param.description
+            ? resolved.describe(param.description)
+            : resolved;
+        shape[param.name] = param.optional ? described.optional() : described;
+    });
+    return z.object(shape);
+};
+//# sourceMappingURL=tool-schema.factory.js.map

package/dist/tools/tool-schema.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-schema.factory.js","sourceRoot":"","sources":["../../lib/tools/tool-schema.factory.ts"],"names":[],"mappings":"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"}

package/dist/tools/tool.factory.d.ts

@@ -0,0 +1,9 @@
+import { DynamicStructuredTool } from 'langchain';
+import { RunReporter } from '../logging/index.js';
+import { ToolMethod } from './tool-method.util.js';
+/**
+ * Builds the LangChain tool that calls a `@Tool()` method and reports each
+ * call to `reporter`. Throws when the name or a parameter schema is invalid.
+ */
+export declare const buildTool: ({ where, method, options, params, paramTypes, call }: ToolMethod, reporter: RunReporter) => DynamicStructuredTool;
+//# sourceMappingURL=tool.factory.d.ts.map

package/dist/tools/tool.factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.factory.d.ts","sourceRoot":"","sources":["../../lib/tools/tool.factory.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAmB,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAGnE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAsBnD;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,sDAAsD,UAAU,EAChE,UAAU,WAAW,KACpB,qBAmBF,CAAC"}

package/dist/tools/tool.factory.js

@@ -0,0 +1,34 @@
+// From `langchain`, not `@langchain/core`: core's declaration gives an
+// identity `createAgent` rejects. See #52.
+import { DynamicStructuredTool } from 'langchain';
+import { observeToolCall } from '../logging/index.js';
+import { buildToolSchema } from './tool-schema.factory.js';
+import { resolveToolName } from './tool-name.util.js';
+// Placed by index: an omitted optional leaves a hole rather than shifting the
+// arguments after it.
+const toPositional = (params, values) => {
+    const args = [];
+    params.forEach((param) => {
+        args[param.index] = values[param.name];
+    });
+    return args;
+};
+/**
+ * Builds the LangChain tool that calls a `@Tool()` method and reports each
+ * call to `reporter`. Throws when the name or a parameter schema is invalid.
+ */
+export const buildTool = ({ where, method, options, params, paramTypes, call }, reporter) => {
+    const name = resolveToolName(options.name, method, where);
+    return new DynamicStructuredTool({
+        name,
+        description: options.description,
+        schema: buildToolSchema(params, paramTypes, where),
+        func: (values, _runManager, config) => observeToolCall(reporter, {
+            tool: name,
+            // Empty only for a tool invoked outside an agent.
+            callId: config?.toolCall?.id ?? '',
+            args: values,
+        }, () => call(toPositional(params, values))),
+    });
+};
+//# sourceMappingURL=tool.factory.js.map

package/dist/tools/tool.factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.factory.js","sourceRoot":"","sources":["../../lib/tools/tool.factory.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,2CAA2C;AAC3C,OAAO,EAAE,qBAAqB,EAAE,MAAM,WAAW,CAAC;AAElD,OAAO,EAAE,eAAe,EAAe,MAAM,qBAAqB,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAQtD,8EAA8E;AAC9E,sBAAsB;AACtB,MAAM,YAAY,GAAG,CACnB,MAA2B,EAC3B,MAA+B,EACpB,EAAE;IACb,MAAM,IAAI,GAAc,EAAE,CAAC;IAE3B,MAAM,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE;QACvB,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACzC,CAAC,CAAC,CAAC;IAEH,OAAO,IAAI,CAAC;AACd,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CACvB,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAc,EAChE,QAAqB,EACE,EAAE;IACzB,MAAM,IAAI,GAAG,eAAe,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IAE1D,OAAO,IAAI,qBAAqB,CAAC;QAC/B,IAAI;QACJ,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,MAAM,EAAE,eAAe,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC;QAClD,IAAI,EAAE,CAAC,MAA+B,EAAE,WAAW,EAAE,MAAM,EAAE,EAAE,CAC7D,eAAe,CACb,QAAQ,EACR;YACE,IAAI,EAAE,IAAI;YACV,kDAAkD;YAClD,MAAM,EAAG,MAAqC,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE;YAClE,IAAI,EAAE,MAAM;SACb,EACD,GAAG,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CACzC;KACJ,CAAC,CAAC;AACL,CAAC,CAAC"}