@better-agent/core 0.1.0-beta.1

package/dist/tools/index.d.mts

@@ -0,0 +1,5 @@
+import { TOOL_CLEANUP, TOOL_JSON_SCHEMA } from "./constants.mjs";
+import { AgentToolDefinition, BoundToolApprovalConfig, ClientToolDefinition, ExecutionToolError, ExecutionToolErrorResult, HostedToolDefinition, LazyToolLoader, LazyToolSource, LazyToolSourceResult, OnToolError, OpenString, ParseToolError, ParseToolErrorResult, RepairAction, ResultAction, RetryAction, SendToModelAction, ServerToolDefinition, SkipAction, ThrowAction, ToolApprovalConfig, ToolApprovalDecision, ToolApprovalState, ToolContract, ToolContractConfig, ToolDefinitionTarget, ToolErrorBase, ToolErrorContext, ToolErrorMode, ToolErrorPayload, ToolErrorResultFor, ToolHandler, ToolListFactory, ToolNameOf, ToolNamesOf, ToolRunContext, ToolSource, ToolSourceResult, ToolTarget, ValidationToolError, ValidationToolErrorResult } from "./types.mjs";
+import { defineTool } from "./define-tool.mjs";
+import { lazyTools } from "./lazy-tools.mjs";
+import { isCallableToolDefinition } from "./resolve-tools.mjs";

package/dist/tools/lazy-tools.d.mts

@@ -0,0 +1,49 @@
+import { Awaitable } from "../internal/types.mjs";
+import { LazyToolSource } from "./types.mjs";
+
+//#region src/tools/lazy-tools.d.ts
+type AnyLazyToolLoader = (...args: readonly unknown[]) => Awaitable<unknown>;
+type InferLazyToolContext<TLoader extends AnyLazyToolLoader> = Parameters<TLoader> extends [] ? unknown : Exclude<Parameters<TLoader>[0], undefined>;
+/**
+ * Creates a lifecycle-aware tool source that loads once, caches successes, and can be explicitly disposed.
+ *
+ * Useful for remote or expensive tool providers such as MCP servers where you want
+ * to reuse a client across runs instead of reconnecting every time.
+ *
+ * @example
+ * ```ts
+ * import { defineAgent, lazyTools } from "@better-agent/core";
+ * import { convertMCPTools, createMCPClient } from "@better-agent/core/mcp";
+ *
+ * const context7Tools = lazyTools(async () => {
+ *   const client = await createMCPClient({
+ *     transport: {
+ *       type: "http",
+ *       url: process.env.CONTEXT7_MCP_URL ?? "https://mcp.context7.com/mcp",
+ *     },
+ *   });
+ *
+ *   const listed = await client.listTools();
+ *
+ *   return {
+ *     tools: convertMCPTools(client, listed.tools, { prefix: "context7" }),
+ *     dispose: async () => {
+ *       await client.close?.();
+ *     },
+ *   };
+ * });
+ *
+ * const agent = defineAgent({
+ *   name: "docs",
+ *   model: openai.text("gpt-5.4-mini"),
+ *   tools: context7Tools,
+ * });
+ * ```
+ *
+ * Call `source.dispose()` when cached provider resources should be released, or
+ * `source.reload(...)` to force a refresh.
+ */
+declare const lazyTools: <TLoader extends AnyLazyToolLoader>(loader: TLoader) => LazyToolSource<InferLazyToolContext<TLoader>>;
+//#endregion
+export { lazyTools };
+//# sourceMappingURL=lazy-tools.d.mts.map

package/dist/tools/lazy-tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-tools.d.mts","names":[],"sources":["../../src/tools/lazy-tools.ts"],"mappings":";;;;KAGK,iBAAA,OAAwB,IAAA,yBAA6B,SAAA;AAAA,KAErD,oBAAA,iBAAqC,iBAAA,IAAqB,UAAA,CAAW,OAAA,yBAEpE,OAAA,CAAQ,UAAA,CAAW,OAAA;AANgE;;;;;AAEtB;;;;;;;;;;;;;;;;;;;;AA6CnE;;;;;;;;;;;;;;AA/CyF,cA+C5E,SAAA,mBAA6B,iBAAA,EAAiB,MAAA,EAC/C,OAAA,KACT,cAAA,CAAe,oBAAA,CAAqB,OAAA"}

package/dist/tools/lazy-tools.mjs

@@ -0,0 +1,87 @@
+//#region src/tools/lazy-tools.ts
+/**
+* Creates a lifecycle-aware tool source that loads once, caches successes, and can be explicitly disposed.
+*
+* Useful for remote or expensive tool providers such as MCP servers where you want
+* to reuse a client across runs instead of reconnecting every time.
+*
+* @example
+* ```ts
+* import { defineAgent, lazyTools } from "@better-agent/core";
+* import { convertMCPTools, createMCPClient } from "@better-agent/core/mcp";
+*
+* const context7Tools = lazyTools(async () => {
+*   const client = await createMCPClient({
+*     transport: {
+*       type: "http",
+*       url: process.env.CONTEXT7_MCP_URL ?? "https://mcp.context7.com/mcp",
+*     },
+*   });
+*
+*   const listed = await client.listTools();
+*
+*   return {
+*     tools: convertMCPTools(client, listed.tools, { prefix: "context7" }),
+*     dispose: async () => {
+*       await client.close?.();
+*     },
+*   };
+* });
+*
+* const agent = defineAgent({
+*   name: "docs",
+*   model: openai.text("gpt-5.4-mini"),
+*   tools: context7Tools,
+* });
+* ```
+*
+* Call `source.dispose()` when cached provider resources should be released, or
+* `source.reload(...)` to force a refresh.
+*/
+const lazyTools = (loader) => {
+	let loadedPromise;
+	let loadedDispose;
+	const load = async (context) => {
+		if (!loadedPromise) loadedPromise = (async () => {
+			try {
+				const value = await loader(context);
+				const resolved = typeof value === "object" && value !== null && "tools" in value ? (() => {
+					const result = value;
+					return {
+						tools: Array.isArray(result.tools) ? [...result.tools] : [result.tools],
+						dispose: result.dispose
+					};
+				})() : {
+					tools: Array.isArray(value) ? [...value] : [value],
+					dispose: void 0
+				};
+				loadedDispose = resolved.dispose;
+				return resolved;
+			} catch (error) {
+				loadedPromise = void 0;
+				loadedDispose = void 0;
+				throw error;
+			}
+		})();
+		return await loadedPromise;
+	};
+	const dispose = async () => {
+		const disposer = loadedDispose;
+		loadedPromise = void 0;
+		loadedDispose = void 0;
+		await disposer?.();
+	};
+	return {
+		kind: "lazy",
+		resolve: load,
+		dispose,
+		reload: async (context) => {
+			await dispose();
+			return await load(context);
+		}
+	};
+};
+
+//#endregion
+export { lazyTools };
+//# sourceMappingURL=lazy-tools.mjs.map

package/dist/tools/lazy-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"lazy-tools.mjs","names":[],"sources":["../../src/tools/lazy-tools.ts"],"sourcesContent":["import type { Awaitable } from \"../internal/types\";\nimport type { AgentToolDefinition, LazyToolSource, LazyToolSourceResult } from \"./types\";\n\ntype AnyLazyToolLoader = (...args: readonly unknown[]) => Awaitable<unknown>;\n\ntype InferLazyToolContext<TLoader extends AnyLazyToolLoader> = Parameters<TLoader> extends []\n    ? unknown\n    : Exclude<Parameters<TLoader>[0], undefined>;\n\n/**\n * Creates a lifecycle-aware tool source that loads once, caches successes, and can be explicitly disposed.\n *\n * Useful for remote or expensive tool providers such as MCP servers where you want\n * to reuse a client across runs instead of reconnecting every time.\n *\n * @example\n * ```ts\n * import { defineAgent, lazyTools } from \"@better-agent/core\";\n * import { convertMCPTools, createMCPClient } from \"@better-agent/core/mcp\";\n *\n * const context7Tools = lazyTools(async () => {\n *   const client = await createMCPClient({\n *     transport: {\n *       type: \"http\",\n *       url: process.env.CONTEXT7_MCP_URL ?? \"https://mcp.context7.com/mcp\",\n *     },\n *   });\n *\n *   const listed = await client.listTools();\n *\n *   return {\n *     tools: convertMCPTools(client, listed.tools, { prefix: \"context7\" }),\n *     dispose: async () => {\n *       await client.close?.();\n *     },\n *   };\n * });\n *\n * const agent = defineAgent({\n *   name: \"docs\",\n *   model: openai.text(\"gpt-5.4-mini\"),\n *   tools: context7Tools,\n * });\n * ```\n *\n * Call `source.dispose()` when cached provider resources should be released, or\n * `source.reload(...)` to force a refresh.\n */\nexport const lazyTools = <TLoader extends AnyLazyToolLoader>(\n    loader: TLoader,\n): LazyToolSource<InferLazyToolContext<TLoader>> => {\n    type TContext = InferLazyToolContext<TLoader>;\n\n    let loadedPromise: Promise<LazyToolSourceResult> | undefined;\n    let loadedDispose: (() => Awaitable<void>) | undefined;\n\n    const load = async (context: TContext | undefined): Promise<LazyToolSourceResult> => {\n        if (!loadedPromise) {\n            loadedPromise = (async (): Promise<LazyToolSourceResult> => {\n                try {\n                    const value = await (\n                        loader as (context: TContext | undefined) => Awaitable<unknown>\n                    )(context);\n                    const resolved =\n                        typeof value === \"object\" && value !== null && \"tools\" in value\n                            ? (() => {\n                                  const result = value as LazyToolSourceResult;\n                                  const tools = Array.isArray(result.tools)\n                                      ? [...result.tools]\n                                      : [result.tools];\n\n                                  return {\n                                      tools,\n                                      dispose: result.dispose,\n                                  };\n                              })()\n                            : {\n                                  tools: Array.isArray(value)\n                                      ? [...(value as readonly AgentToolDefinition<unknown>[])]\n                                      : [value as AgentToolDefinition<unknown>],\n                                  dispose: undefined,\n                              };\n                    loadedDispose = resolved.dispose;\n                    return resolved;\n                } catch (error) {\n                    loadedPromise = undefined;\n                    loadedDispose = undefined;\n                    throw error;\n                }\n            })();\n        }\n\n        return await loadedPromise;\n    };\n\n    const dispose = async () => {\n        const disposer = loadedDispose;\n        loadedPromise = undefined;\n        loadedDispose = undefined;\n        await disposer?.();\n    };\n\n    return {\n        kind: \"lazy\",\n        resolve: load,\n        dispose,\n        reload: async (context) => {\n            await dispose();\n            return await load(context);\n        },\n    };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAgDA,MAAa,aACT,WACgD;CAGhD,IAAI;CACJ,IAAI;CAEJ,MAAM,OAAO,OAAO,YAAiE;AACjF,MAAI,CAAC,cACD,kBAAiB,YAA2C;AACxD,OAAI;IACA,MAAM,QAAQ,MACV,OACF,QAAQ;IACV,MAAM,WACF,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW,eAC7C;KACH,MAAM,SAAS;AAKf,YAAO;MACH,OALU,MAAM,QAAQ,OAAO,MAAM,GACnC,CAAC,GAAG,OAAO,MAAM,GACjB,CAAC,OAAO,MAAM;MAIhB,SAAS,OAAO;MACnB;QACD,GACJ;KACI,OAAO,MAAM,QAAQ,MAAM,GACrB,CAAC,GAAI,MAAkD,GACvD,CAAC,MAAsC;KAC7C,SAAS;KACZ;AACX,oBAAgB,SAAS;AACzB,WAAO;YACF,OAAO;AACZ,oBAAgB;AAChB,oBAAgB;AAChB,UAAM;;MAEV;AAGR,SAAO,MAAM;;CAGjB,MAAM,UAAU,YAAY;EACxB,MAAM,WAAW;AACjB,kBAAgB;AAChB,kBAAgB;AAChB,QAAM,YAAY;;AAGtB,QAAO;EACH,MAAM;EACN,SAAS;EACT;EACA,QAAQ,OAAO,YAAY;AACvB,SAAM,SAAS;AACf,UAAO,MAAM,KAAK,QAAQ;;EAEjC"}

package/dist/tools/resolve-tools.d.mts

@@ -0,0 +1,12 @@
+import { AgentToolDefinition } from "./types.mjs";
+
+//#region src/tools/resolve-tools.d.ts
+/**
+ * Checks whether a tool is directly callable by the runtime.
+ */
+declare const isCallableToolDefinition: <TContext>(tool: AgentToolDefinition<TContext>) => tool is Exclude<AgentToolDefinition<TContext>, {
+  kind: "hosted";
+}>;
+//#endregion
+export { isCallableToolDefinition };
+//# sourceMappingURL=resolve-tools.d.mts.map

package/dist/tools/resolve-tools.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tools.d.mts","names":[],"sources":["../../src/tools/resolve-tools.ts"],"mappings":";;;;;;cAqLa,wBAAA,aAAoC,IAAA,EACvC,mBAAA,CAAoB,QAAA,MAC3B,IAAA,IAAQ,OAAA,CAAQ,mBAAA,CAAoB,QAAA;EAAa,IAAA;AAAA"}

package/dist/tools/resolve-tools.mjs

@@ -0,0 +1,86 @@
+import { TOOL_CLEANUP } from "./constants.mjs";
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/tools/resolve-tools.ts
+/**
+* Resolves all tools available for a run and collects cleanup hooks.
+*/
+const resolveToolsForRun = async (params) => {
+	const cleanup = /* @__PURE__ */ new Set();
+	const normalize = (value) => Array.isArray(value) ? [...value] : [value];
+	const isLazyToolSourceResult = (value) => typeof value === "object" && value !== null && "tools" in value;
+	const resolveSource = async (source, context) => {
+		const resolved = typeof source === "function" ? await source(context) : typeof source === "object" && source !== null && "kind" in source && source.kind === "lazy" ? await source.resolve(context) : await source;
+		if (isLazyToolSourceResult(resolved)) return normalize(resolved.tools);
+		return normalize(resolved);
+	};
+	const resolveList = async (sources, context) => {
+		if (!sources) return [];
+		const list = Array.isArray(sources) ? sources : [sources];
+		return (await Promise.all(list.map((source) => resolveSource(source, context)))).flat();
+	};
+	const collectCleanup = (tools) => {
+		for (const tool of tools) {
+			const fn = tool[TOOL_CLEANUP];
+			if (fn) cleanup.add(fn);
+		}
+	};
+	const appTools = params.appTools ?? [];
+	const agentTools = await resolveList(params.agentTools, params.context);
+	collectCleanup(appTools);
+	collectCleanup(agentTools);
+	const resolvedTools = [...appTools, ...agentTools];
+	const seenToolNames = /* @__PURE__ */ new Set();
+	for (const [index, tool] of resolvedTools.entries()) {
+		if (!tool || typeof tool !== "object" || !("kind" in tool) || tool.kind !== "server" && tool.kind !== "client" && tool.kind !== "hosted") throw BetterAgentError.fromCode("VALIDATION_FAILED", "Invalid tool entry. Pass tool implementations, client tools, or hosted tools.", {
+			context: { index },
+			trace: [{
+				at: "core.tools.resolveToolsForRun.validate.invalidEntry",
+				data: {
+					index,
+					toolType: typeof tool
+				}
+			}]
+		});
+		const toolName = tool.kind === "hosted" ? typeof tool.name === "string" && tool.name.length > 0 ? tool.name : typeof tool.type === "string" && tool.type.length > 0 ? tool.type : void 0 : typeof tool.name === "string" && tool.name.length > 0 ? tool.name : void 0;
+		if (!toolName) throw BetterAgentError.fromCode("VALIDATION_FAILED", tool.kind === "hosted" ? "Hosted tools must define a non-empty type or name." : "Tool name must be a non-empty string.", {
+			context: { index },
+			trace: [{
+				at: "core.tools.resolveToolsForRun.validate.invalidName",
+				data: {
+					index,
+					kind: tool.kind
+				}
+			}]
+		});
+		if (seenToolNames.has(toolName)) throw BetterAgentError.fromCode("VALIDATION_FAILED", `Duplicate tool name '${toolName}' in tools list.`, {
+			context: { toolName },
+			trace: [{
+				at: "core.tools.resolveToolsForRun.validate.duplicateName",
+				data: {
+					index,
+					toolName
+				}
+			}]
+		});
+		seenToolNames.add(toolName);
+	}
+	const runCleanup = async () => {
+		if (cleanup.size === 0) return;
+		const tasks = Array.from(cleanup, async (fn) => await fn());
+		cleanup.clear();
+		await Promise.allSettled(tasks);
+	};
+	return {
+		tools: resolvedTools,
+		runCleanup
+	};
+};
+/**
+* Checks whether a tool is directly callable by the runtime.
+*/
+const isCallableToolDefinition = (tool) => tool.kind !== "hosted";
+
+//#endregion
+export { isCallableToolDefinition, resolveToolsForRun };
+//# sourceMappingURL=resolve-tools.mjs.map

package/dist/tools/resolve-tools.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-tools.mjs","names":[],"sources":["../../src/tools/resolve-tools.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport type { Awaitable } from \"../internal/types\";\nimport { TOOL_CLEANUP } from \"./constants\";\nimport type { AgentToolDefinition, LazyToolSourceResult, ToolSource } from \"./types\";\n\n/**\n * Resolves all tools available for a run and collects cleanup hooks.\n */\nexport const resolveToolsForRun = async <TContext>(params: {\n    appTools?: readonly AgentToolDefinition[];\n    agentTools?: ToolSource<TContext> | readonly ToolSource<TContext>[];\n    context?: TContext;\n}): Promise<{\n    /** Tools available for this run. */\n    tools: AgentToolDefinition[];\n    /** Runs cleanup hooks registered via {@link TOOL_CLEANUP}. */\n    runCleanup: () => Awaitable<void>;\n}> => {\n    const cleanup = new Set<() => Promise<void> | void>();\n\n    const normalize = (value: readonly AgentToolDefinition[] | AgentToolDefinition) =>\n        Array.isArray(value) ? [...value] : [value];\n\n    const isLazyToolSourceResult = (value: unknown): value is LazyToolSourceResult =>\n        typeof value === \"object\" && value !== null && \"tools\" in value;\n\n    const resolveSource = async (\n        source: ToolSource<TContext>,\n        context: TContext | undefined,\n    ): Promise<AgentToolDefinition[]> => {\n        const resolved =\n            typeof source === \"function\"\n                ? await (source as (context: TContext | undefined) => Awaitable<unknown>)(context)\n                : typeof source === \"object\" &&\n                    source !== null &&\n                    \"kind\" in source &&\n                    source.kind === \"lazy\"\n                  ? await source.resolve(context)\n                  : await (source as Awaitable<unknown>);\n\n        if (isLazyToolSourceResult(resolved)) {\n            return normalize(\n                resolved.tools as readonly AgentToolDefinition[] | AgentToolDefinition,\n            );\n        }\n\n        return normalize(resolved as readonly AgentToolDefinition[] | AgentToolDefinition);\n    };\n\n    const resolveList = async (\n        sources: ToolSource<TContext> | readonly ToolSource<TContext>[] | undefined,\n        context: TContext | undefined,\n    ) => {\n        if (!sources) return [];\n        const list = Array.isArray(sources) ? sources : [sources];\n        const resolved = await Promise.all(list.map((source) => resolveSource(source, context)));\n        return resolved.flat();\n    };\n\n    const collectCleanup = (tools: readonly AgentToolDefinition[]) => {\n        for (const tool of tools) {\n            const fn = tool[TOOL_CLEANUP];\n            if (fn) cleanup.add(fn);\n        }\n    };\n\n    const appTools = params.appTools ?? [];\n    const agentTools = await resolveList(params.agentTools, params.context);\n\n    collectCleanup(appTools);\n    collectCleanup(agentTools);\n\n    const resolvedTools = [...appTools, ...agentTools];\n    const seenToolNames = new Set<string>();\n\n    for (const [index, tool] of resolvedTools.entries()) {\n        if (\n            !tool ||\n            typeof tool !== \"object\" ||\n            !(\"kind\" in tool) ||\n            (tool.kind !== \"server\" && tool.kind !== \"client\" && tool.kind !== \"hosted\")\n        ) {\n            throw BetterAgentError.fromCode(\n                \"VALIDATION_FAILED\",\n                \"Invalid tool entry. Pass tool implementations, client tools, or hosted tools.\",\n                {\n                    context: { index },\n                    trace: [\n                        {\n                            at: \"core.tools.resolveToolsForRun.validate.invalidEntry\",\n                            data: {\n                                index,\n                                toolType: typeof tool,\n                            },\n                        },\n                    ],\n                },\n            );\n        }\n\n        const toolName =\n            tool.kind === \"hosted\"\n                ? typeof tool.name === \"string\" && tool.name.length > 0\n                    ? tool.name\n                    : typeof tool.type === \"string\" && tool.type.length > 0\n                      ? tool.type\n                      : undefined\n                : typeof tool.name === \"string\" && tool.name.length > 0\n                  ? tool.name\n                  : undefined;\n\n        if (!toolName) {\n            throw BetterAgentError.fromCode(\n                \"VALIDATION_FAILED\",\n                tool.kind === \"hosted\"\n                    ? \"Hosted tools must define a non-empty type or name.\"\n                    : \"Tool name must be a non-empty string.\",\n                {\n                    context: { index },\n                    trace: [\n                        {\n                            at: \"core.tools.resolveToolsForRun.validate.invalidName\",\n                            data: { index, kind: tool.kind },\n                        },\n                    ],\n                },\n            );\n        }\n\n        if (seenToolNames.has(toolName)) {\n            throw BetterAgentError.fromCode(\n                \"VALIDATION_FAILED\",\n                `Duplicate tool name '${toolName}' in tools list.`,\n                {\n                    context: { toolName },\n                    trace: [\n                        {\n                            at: \"core.tools.resolveToolsForRun.validate.duplicateName\",\n                            data: {\n                                index,\n                                toolName,\n                            },\n                        },\n                    ],\n                },\n            );\n        }\n\n        seenToolNames.add(toolName);\n    }\n\n    const runCleanup = async () => {\n        if (cleanup.size === 0) return;\n        const tasks = Array.from(cleanup, async (fn) => await fn());\n        cleanup.clear();\n        await Promise.allSettled(tasks);\n    };\n\n    return {\n        tools: resolvedTools,\n        runCleanup,\n    };\n};\n\n/**\n * Checks whether a tool is a server tool definition.\n */\nexport const isServerToolDefinition = <TContext>(\n    tool: AgentToolDefinition<TContext>,\n): tool is Extract<AgentToolDefinition<TContext>, { kind: \"server\" }> => tool.kind === \"server\";\n\n/**\n * Checks whether a tool is a client tool definition.\n */\nexport const isClientToolDefinition = <TContext>(\n    tool: AgentToolDefinition<TContext>,\n): tool is Extract<AgentToolDefinition<TContext>, { kind: \"client\" }> => tool.kind === \"client\";\n\n/**\n * Checks whether a tool is directly callable by the runtime.\n */\nexport const isCallableToolDefinition = <TContext>(\n    tool: AgentToolDefinition<TContext>,\n): tool is Exclude<AgentToolDefinition<TContext>, { kind: \"hosted\" }> => tool.kind !== \"hosted\";\n"],"mappings":";;;;;;;AAQA,MAAa,qBAAqB,OAAiB,WAS7C;CACF,MAAM,0BAAU,IAAI,KAAiC;CAErD,MAAM,aAAa,UACf,MAAM,QAAQ,MAAM,GAAG,CAAC,GAAG,MAAM,GAAG,CAAC,MAAM;CAE/C,MAAM,0BAA0B,UAC5B,OAAO,UAAU,YAAY,UAAU,QAAQ,WAAW;CAE9D,MAAM,gBAAgB,OAClB,QACA,YACiC;EACjC,MAAM,WACF,OAAO,WAAW,aACZ,MAAO,OAAiE,QAAQ,GAChF,OAAO,WAAW,YAChB,WAAW,QACX,UAAU,UACV,OAAO,SAAS,SAChB,MAAM,OAAO,QAAQ,QAAQ,GAC7B,MAAO;AAEnB,MAAI,uBAAuB,SAAS,CAChC,QAAO,UACH,SAAS,MACZ;AAGL,SAAO,UAAU,SAAiE;;CAGtF,MAAM,cAAc,OAChB,SACA,YACC;AACD,MAAI,CAAC,QAAS,QAAO,EAAE;EACvB,MAAM,OAAO,MAAM,QAAQ,QAAQ,GAAG,UAAU,CAAC,QAAQ;AAEzD,UADiB,MAAM,QAAQ,IAAI,KAAK,KAAK,WAAW,cAAc,QAAQ,QAAQ,CAAC,CAAC,EACxE,MAAM;;CAG1B,MAAM,kBAAkB,UAA0C;AAC9D,OAAK,MAAM,QAAQ,OAAO;GACtB,MAAM,KAAK,KAAK;AAChB,OAAI,GAAI,SAAQ,IAAI,GAAG;;;CAI/B,MAAM,WAAW,OAAO,YAAY,EAAE;CACtC,MAAM,aAAa,MAAM,YAAY,OAAO,YAAY,OAAO,QAAQ;AAEvE,gBAAe,SAAS;AACxB,gBAAe,WAAW;CAE1B,MAAM,gBAAgB,CAAC,GAAG,UAAU,GAAG,WAAW;CAClD,MAAM,gCAAgB,IAAI,KAAa;AAEvC,MAAK,MAAM,CAAC,OAAO,SAAS,cAAc,SAAS,EAAE;AACjD,MACI,CAAC,QACD,OAAO,SAAS,YAChB,EAAE,UAAU,SACX,KAAK,SAAS,YAAY,KAAK,SAAS,YAAY,KAAK,SAAS,SAEnE,OAAM,iBAAiB,SACnB,qBACA,iFACA;GACI,SAAS,EAAE,OAAO;GAClB,OAAO,CACH;IACI,IAAI;IACJ,MAAM;KACF;KACA,UAAU,OAAO;KACpB;IACJ,CACJ;GACJ,CACJ;EAGL,MAAM,WACF,KAAK,SAAS,WACR,OAAO,KAAK,SAAS,YAAY,KAAK,KAAK,SAAS,IAChD,KAAK,OACL,OAAO,KAAK,SAAS,YAAY,KAAK,KAAK,SAAS,IAClD,KAAK,OACL,SACN,OAAO,KAAK,SAAS,YAAY,KAAK,KAAK,SAAS,IAClD,KAAK,OACL;AAEZ,MAAI,CAAC,SACD,OAAM,iBAAiB,SACnB,qBACA,KAAK,SAAS,WACR,uDACA,yCACN;GACI,SAAS,EAAE,OAAO;GAClB,OAAO,CACH;IACI,IAAI;IACJ,MAAM;KAAE;KAAO,MAAM,KAAK;KAAM;IACnC,CACJ;GACJ,CACJ;AAGL,MAAI,cAAc,IAAI,SAAS,CAC3B,OAAM,iBAAiB,SACnB,qBACA,wBAAwB,SAAS,mBACjC;GACI,SAAS,EAAE,UAAU;GACrB,OAAO,CACH;IACI,IAAI;IACJ,MAAM;KACF;KACA;KACH;IACJ,CACJ;GACJ,CACJ;AAGL,gBAAc,IAAI,SAAS;;CAG/B,MAAM,aAAa,YAAY;AAC3B,MAAI,QAAQ,SAAS,EAAG;EACxB,MAAM,QAAQ,MAAM,KAAK,SAAS,OAAO,OAAO,MAAM,IAAI,CAAC;AAC3D,UAAQ,OAAO;AACf,QAAM,QAAQ,WAAW,MAAM;;AAGnC,QAAO;EACH,OAAO;EACP;EACH;;;;;AAoBL,MAAa,4BACT,SACqE,KAAK,SAAS"}

package/dist/tools/types.d.mts

@@ -0,0 +1,318 @@
+import { Awaitable, BivariantFn } from "../internal/types.mjs";
+import { InferSchemaInput, ResolvableSchema } from "../schema/types.mjs";
+import { TOOL_CLEANUP, TOOL_JSON_SCHEMA } from "./constants.mjs";
+import { Event } from "../events/types.mjs";
+//#region src/tools/types.d.ts
+/**
+ * Runtime location where a tool executes.
+ */
+type ToolTarget = "server" | "client" | "hosted";
+/**
+ * Approval state for a tool call.
+ */
+type ToolApprovalState = "requested" | "approved" | "denied" | "expired";
+/**
+ * Approval decisions that can be submitted for a pending tool call.
+ */
+type ToolApprovalDecision = Extract<ToolApprovalState, "approved" | "denied">;
+/**
+ * Default handling mode for recoverable tool failures.
+ */
+type ToolErrorMode = "tool_error" | "throw";
+/**
+ * Preserves autocomplete for known string literals while allowing arbitrary strings.
+ */
+type OpenString<TKnown extends string> = TKnown | (string & {});
+/**
+ * Extracts the static `name` from a tool definition.
+ */
+type ToolNameOf<TTool> = TTool extends {
+  name: infer TName extends string;
+} ? TName : never;
+type AwaitedToolValue<TValue> = TValue extends PromiseLike<infer TResolved> ? AwaitedToolValue<TResolved> : TValue;
+/**
+ * Extracts tool-name literals from tool definitions or factories.
+ */
+type ToolNamesOf<TValue> = AwaitedToolValue<TValue> extends readonly (infer TItem)[] ? ToolNamesOf<TItem> : AwaitedToolValue<TValue> extends ((...args: infer _TArgs) => infer TResult) ? ToolNamesOf<TResult> : ToolNameOf<AwaitedToolValue<TValue>>;
+/**
+ * Tool error payload sent back to the model.
+ */
+interface ToolErrorPayload {
+  type: "tool_error";
+  toolName: string;
+  errorKind: "parse" | "validation" | "execution";
+  message: string;
+  retryable?: boolean;
+}
+/**
+ * Shared context available to all tool error hooks.
+ */
+interface ToolErrorBase {
+  toolName: string;
+  toolCallId: string;
+  error: unknown;
+  rawArguments: string;
+}
+/**
+ * Parse error context for tool argument JSON failures.
+ */
+interface ParseToolError extends ToolErrorBase {
+  errorKind: "parse";
+}
+/**
+ * Validation error context for schema validation failures.
+ */
+interface ValidationToolError extends ToolErrorBase {
+  errorKind: "validation";
+  input: unknown;
+}
+/**
+ * Execution error context for handler, client, or MCP failures.
+ */
+interface ExecutionToolError extends ToolErrorBase {
+  errorKind: "execution";
+  input: unknown;
+}
+/**
+ * Union of all recoverable tool error contexts.
+ */
+type ToolErrorContext = ParseToolError | ValidationToolError | ExecutionToolError;
+/**
+ * Sends a structured tool error result back to the model.
+ */
+interface SendToModelAction {
+  action: "send_to_model";
+  message?: string;
+  retryable?: boolean;
+}
+/**
+ * Skips the current hook layer and falls through.
+ */
+interface SkipAction {
+  action: "skip";
+}
+/**
+ * Re-throws the original recoverable tool failure and stops the run.
+ */
+interface ThrowAction {
+  action: "throw";
+}
+/**
+ * Provides replacement tool input to validate and execute again.
+ */
+interface RepairAction {
+  action: "repair";
+  input: unknown;
+}
+/**
+ * Retries the tool handler with the same validated input.
+ *
+ * Valid only for execution errors.
+ */
+interface RetryAction {
+  action: "retry";
+  maxAttempts?: number;
+}
+/**
+ * Provides a successful fallback tool result.
+ *
+ * Valid only for execution errors.
+ */
+interface ResultAction {
+  action: "result";
+  value: unknown;
+}
+/**
+ * Allowed return values for parse error hooks.
+ */
+type ParseToolErrorResult = SendToModelAction | ThrowAction | RepairAction | SkipAction | undefined;
+/**
+ * Allowed return values for schema validation error hooks.
+ */
+type ValidationToolErrorResult = SendToModelAction | ThrowAction | RepairAction | SkipAction | undefined;
+/**
+ * Allowed return values for execution error hooks.
+ */
+type ExecutionToolErrorResult = SendToModelAction | SkipAction | ThrowAction | RepairAction | RetryAction | ResultAction | undefined;
+type ToolErrorResultFor<T extends ToolErrorContext> = T extends ParseToolError ? ParseToolErrorResult : T extends ValidationToolError ? ValidationToolErrorResult : T extends ExecutionToolError ? ExecutionToolErrorResult : never;
+/**
+ * Hook for customizing recoverable tool error behavior.
+ */
+type OnToolError = <T extends ToolErrorContext>(context: T) => Awaitable<ToolErrorResultFor<T>>;
+/**
+ * Approval policy for a tool.
+ */
+type ToolApprovalConfig<TContext = any, TInput = unknown> = {
+  /** Whether approval is required before executing this tool. */required?: boolean; /** Optional timeout for approval in milliseconds. */
+  timeoutMs?: number; /** Optional metadata forwarded to approval UI or policy systems. */
+  meta?: Record<string, unknown>; /** Dynamic approval resolver based on context and input. */
+  resolve?: BivariantFn<[{
+    context: TContext;
+    input: TInput;
+    runId: string;
+    toolCallId: string;
+    toolName: string;
+    toolTarget: Exclude<ToolTarget, "hosted">;
+  }], Awaitable<{
+    required?: boolean;
+    timeoutMs?: number;
+    meta?: Record<string, unknown>;
+  }>>;
+};
+/**
+ * Approval config specialized to a validated tool input schema and run context.
+ */
+type BoundToolApprovalConfig<TContext, TSchema extends ResolvableSchema> = ToolApprovalConfig<TContext, InferSchemaInput<TSchema>>;
+/**
+ * Extra context passed to a tool handler at call time.
+ */
+interface ToolRunContext {
+  /** Abort signal for cancelling the active run. */
+  signal: AbortSignal;
+  /** Emits runtime events while the tool is running. */
+  emit: (event: Event) => Awaitable<void>;
+}
+/**
+ * Tool handler.
+ *
+ * @typeParam TInput Parsed and validated tool input type.
+ */
+type ToolHandler<TInput, TResult = unknown> = BivariantFn<[TInput, ToolRunContext], Awaitable<TResult>>;
+/**
+ * Shared tool contract shape without a concrete runtime implementation.
+ */
+interface ToolContractConfig<TSchema extends ResolvableSchema, TName extends string = string, TContext = any> {
+  /** Stable tool name exposed to the model. */
+  name: TName;
+  /** Short description shown to the model. */
+  description?: string;
+  /** Input schema used for validation and model-facing tool definitions. */
+  schema: TSchema;
+  /** When true, input validation should be strict when supported by the runtime. */
+  strict?: boolean;
+  /** Optional approval policy for this tool call. */
+  approval?: BoundToolApprovalConfig<TContext, TSchema>;
+  /** Optional default handling mode for recoverable tool failures. */
+  toolErrorMode?: ToolErrorMode;
+  /** Optional hook for customizing recoverable tool failures. */
+  onToolError?: OnToolError;
+  /** Optional per-run cleanup hook collected via {@link TOOL_CLEANUP}. */
+  [TOOL_CLEANUP]?: () => Awaitable<void>;
+  /** Optional pre-resolved JSON Schema. Skips conversion when present. */
+  [TOOL_JSON_SCHEMA]?: Record<string, unknown>;
+}
+/**
+ * Tool contract returned by `defineTool(...)`.
+ */
+type ToolContract<TSchema extends ResolvableSchema, TName extends string = string, TContext = any> = ToolContractConfig<TSchema, TName, TContext> & {
+  [TOOL_JSON_SCHEMA]: Record<string, unknown>;
+  /**
+   * Creates a server-executed implementation.
+   */
+  server: <TAs extends string | undefined = undefined, TResult = unknown>(handler: ToolHandler<InferSchemaInput<TSchema>, TResult>, options?: {
+    /**
+     * Override for the final tool `name`.
+     */
+    as?: TAs;
+  }) => ServerToolDefinition<TSchema, TAs extends string ? TAs : TName, TResult, TContext>;
+  /**
+   * Creates a client-executed declaration.
+   */
+  client: <TAs extends string | undefined = undefined>(options?: {
+    /**
+     * Override for the final tool `name`.
+     */
+    as?: TAs;
+  }) => ClientToolDefinition<TSchema, TAs extends string ? TAs : TName, TContext>;
+};
+/**
+ * Server tool definition executed by the Better Agent runtime.
+ */
+type ServerToolDefinition<TSchema extends ResolvableSchema = ResolvableSchema, TName extends string = string, TResult = unknown, TContext = any> = {
+  /** Discriminator for server-executed tools. */kind: "server"; /** Stable tool name exposed to the model. */
+  name: TName; /** Short description shown to the model. */
+  description?: string; /** Original schema value kept for reference. */
+  schema: TSchema; /** When true, input validation should be strict when supported by the runtime. */
+  strict?: boolean; /** Optional approval policy for this tool call. */
+  approval?: BoundToolApprovalConfig<TContext, TSchema>; /** Optional default handling mode for recoverable tool failures. */
+  toolErrorMode?: ToolErrorMode; /** Optional hook for customizing recoverable tool failures. */
+  onToolError?: OnToolError; /** Tool implementation. Receives validated input and runtime context. */
+  handler: ToolHandler<InferSchemaInput<TSchema>, TResult>; /** Optional per-run cleanup hook collected via {@link TOOL_CLEANUP}. */
+  [TOOL_CLEANUP]?: () => Awaitable<void>; /** Resolved JSON Schema for the tool input. */
+  [TOOL_JSON_SCHEMA]: Record<string, unknown>;
+};
+/**
+ * Provider-hosted tool definition.
+ */
+type HostedToolDefinition<TProvider extends string = string, TType extends string = string, TConfig extends Record<string, unknown> = Record<string, unknown>> = {
+  /** Discriminator for provider-executed tools. */kind: "hosted"; /** Provider id that understands this hosted tool shape. */
+  provider: TProvider; /** Provider-native tool type identifier. */
+  type: TType; /** Provider-native config payload forwarded by provider mappers. */
+  config: TConfig; /** Optional display or metadata name. */
+  name?: string; /** Optional display or metadata description. */
+  description?: string; /** Optional per-run cleanup hook collected via {@link TOOL_CLEANUP}. */
+  [TOOL_CLEANUP]?: () => Awaitable<void>;
+};
+/**
+ * Client tool definition exposed by the server runtime and executed by the client app.
+ */
+type ClientToolDefinition<TSchema extends ResolvableSchema = ResolvableSchema, TName extends string = string, TContext = any> = {
+  /** Discriminator for client-executed tools. */kind: "client"; /** Stable tool name exposed to the model. */
+  name: TName; /** Short description shown to the model. */
+  description?: string; /** Original schema value kept for reference. */
+  schema: TSchema; /** When true, input validation should be strict when supported by the runtime. */
+  strict?: boolean; /** Optional approval policy for this tool call. */
+  approval?: BoundToolApprovalConfig<TContext, TSchema>; /** Optional default handling mode for recoverable tool failures. */
+  toolErrorMode?: ToolErrorMode; /** Optional hook for customizing recoverable tool failures. */
+  onToolError?: OnToolError; /** Optional per-run cleanup hook collected via {@link TOOL_CLEANUP}. */
+  [TOOL_CLEANUP]?: () => Awaitable<void>; /** Resolved JSON Schema for the tool input. */
+  [TOOL_JSON_SCHEMA]: Record<string, unknown>;
+};
+/**
+ * Tool union used by agent and runtime APIs.
+ */
+type AgentToolDefinition<TContext = any> = ServerToolDefinition<any, string, unknown, TContext> | ClientToolDefinition<any, string, TContext> | HostedToolDefinition;
+/**
+ * Tool definitions returned by one source.
+ */
+type ToolSourceResult = readonly AgentToolDefinition[] | AgentToolDefinition;
+/**
+ * Tool definitions plus optional provider-lifecycle disposal.
+ */
+interface LazyToolSourceResult {
+  tools: ToolSourceResult;
+  /** Optional disposer for cached provider resources such as MCP clients. */
+  dispose?: () => Awaitable<void>;
+}
+/**
+ * Loader used by {@link LazyToolSource} to populate and cache tools.
+ */
+type LazyToolLoader<TContext = unknown> = BivariantFn<[] | [TContext | undefined], Awaitable<ToolSourceResult | LazyToolSourceResult>>;
+/**
+ * Lifecycle-aware tool source that caches a resolved tool set across runs.
+ */
+interface LazyToolSource<TContext = unknown> {
+  /** Internal discriminator for lazy tool sources. */
+  readonly kind: "lazy";
+  /** Resolves and caches tool definitions. Concurrent calls share one load. */
+  resolve(context: TContext | undefined): Promise<LazyToolSourceResult>;
+  /** Disposes cached resources and clears the cache. Safe to call multiple times. */
+  dispose(): Promise<void>;
+  /** Forces a reload by disposing the current cache before resolving again. */
+  reload(context: TContext | undefined): Promise<LazyToolSourceResult>;
+}
+/**
+ * Creates tool definitions from context.
+ */
+type ToolListFactory<TContext> = BivariantFn<[TContext | undefined], Awaitable<ToolSourceResult>>;
+/**
+ * Tool source accepted by agents and runtimes.
+ */
+type ToolSource<TContext> = LazyToolSource<TContext> | ToolListFactory<TContext> | Awaitable<ToolSourceResult>;
+/**
+ * Resolves the runtime target for a tool definition.
+ */
+type ToolDefinitionTarget<TTool extends AgentToolDefinition = AgentToolDefinition> = TTool["kind"] extends ToolTarget ? TTool["kind"] : ToolTarget;
+//#endregion
+export { AgentToolDefinition, BoundToolApprovalConfig, ClientToolDefinition, ExecutionToolError, ExecutionToolErrorResult, HostedToolDefinition, LazyToolLoader, LazyToolSource, LazyToolSourceResult, OnToolError, OpenString, ParseToolError, ParseToolErrorResult, RepairAction, ResultAction, RetryAction, SendToModelAction, ServerToolDefinition, SkipAction, ThrowAction, ToolApprovalConfig, ToolApprovalDecision, ToolApprovalState, ToolContract, ToolContractConfig, ToolDefinitionTarget, ToolErrorBase, ToolErrorContext, ToolErrorMode, ToolErrorPayload, ToolErrorResultFor, ToolHandler, ToolListFactory, ToolNameOf, ToolNamesOf, ToolRunContext, ToolSource, ToolSourceResult, ToolTarget, ValidationToolError, ValidationToolErrorResult };
+//# sourceMappingURL=types.d.mts.map

package/dist/tools/types.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/tools/types.ts"],"mappings":"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"}

package/dist/tools/validation.mjs

@@ -0,0 +1,23 @@
+import { resolveToJsonSchema } from "../schema/resolve-json-schema.mjs";
+import { TOOL_JSON_SCHEMA } from "./constants.mjs";
+import { BetterAgentError } from "@better-agent/shared/errors";
+
+//#region src/tools/validation.ts
+/**
+* Validates a tool definition and returns the resolved JSON Schema used at runtime.
+*/
+const validateToolDefinition = (def) => {
+	if (typeof def.name !== "string" || def.name.length === 0) throw BetterAgentError.fromCode("VALIDATION_FAILED", "Tool name must be a non-empty string.", { trace: [{ at: "core.tools.validateToolDefinition.name" }] });
+	const existingSchema = def[TOOL_JSON_SCHEMA];
+	if (existingSchema !== void 0) return existingSchema;
+	const jsonSchema = resolveToJsonSchema(def.schema);
+	if (jsonSchema.isErr()) throw jsonSchema.error.at({
+		at: "core.tools.validateToolDefinition.schema",
+		data: { toolName: def.name }
+	});
+	return jsonSchema.value;
+};
+
+//#endregion
+export { validateToolDefinition };
+//# sourceMappingURL=validation.mjs.map

package/dist/tools/validation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.mjs","names":[],"sources":["../../src/tools/validation.ts"],"sourcesContent":["import { BetterAgentError } from \"@better-agent/shared/errors\";\nimport { resolveToJsonSchema } from \"../schema\";\nimport type { ResolvableSchema } from \"../schema\";\nimport { TOOL_JSON_SCHEMA } from \"./constants\";\n\ntype ToolValidationTarget = {\n    name?: unknown;\n    schema: ResolvableSchema;\n    [TOOL_JSON_SCHEMA]?: Record<string, unknown>;\n};\n\n/**\n * Validates a tool definition and returns the resolved JSON Schema used at runtime.\n */\nexport const validateToolDefinition = <const TTool extends ToolValidationTarget>(\n    def: TTool,\n): Record<string, unknown> => {\n    if (typeof def.name !== \"string\" || def.name.length === 0) {\n        throw BetterAgentError.fromCode(\n            \"VALIDATION_FAILED\",\n            \"Tool name must be a non-empty string.\",\n            {\n                trace: [{ at: \"core.tools.validateToolDefinition.name\" }],\n            },\n        );\n    }\n\n    const existingSchema = def[TOOL_JSON_SCHEMA];\n    if (existingSchema !== undefined) {\n        return existingSchema;\n    }\n\n    const jsonSchema = resolveToJsonSchema(def.schema);\n    if (jsonSchema.isErr()) {\n        throw jsonSchema.error.at({\n            at: \"core.tools.validateToolDefinition.schema\",\n            data: { toolName: def.name },\n        });\n    }\n\n    return jsonSchema.value;\n};\n"],"mappings":";;;;;;;;AAcA,MAAa,0BACT,QAC0B;AAC1B,KAAI,OAAO,IAAI,SAAS,YAAY,IAAI,KAAK,WAAW,EACpD,OAAM,iBAAiB,SACnB,qBACA,yCACA,EACI,OAAO,CAAC,EAAE,IAAI,0CAA0C,CAAC,EAC5D,CACJ;CAGL,MAAM,iBAAiB,IAAI;AAC3B,KAAI,mBAAmB,OACnB,QAAO;CAGX,MAAM,aAAa,oBAAoB,IAAI,OAAO;AAClD,KAAI,WAAW,OAAO,CAClB,OAAM,WAAW,MAAM,GAAG;EACtB,IAAI;EACJ,MAAM,EAAE,UAAU,IAAI,MAAM;EAC/B,CAAC;AAGN,QAAO,WAAW"}