@orkestrel/tool 0.0.12 → 0.0.14

package/README.md

@@ -1,16 +1,14 @@
 # @orkestrel/tool
 
-The tool runtime for the `@orkestrel` line.
-
-A tool is a callable function described by a JSON Schema: a name, an optional description, an
-optional parameter schema, and the handler that runs it. That is the whole idea — a tool is an
-API call whose shape is data, so whoever calls it can discover it, present it, and invoke it
-without knowing anything about the code behind it. This package ships that shape and the
-registry around it: definitions to advertise, calls to dispatch, results to correlate, and
-per-call error isolation so one bad tool never takes down the run.
-
-Nothing here is model-specific. An agent loop, an MCP bridge, and plain application code are all
-just callers.
+> The tool runtime for the `@orkestrel` line: a `Tool` binding an advertised JSON Schema
+> definition to its handler, a `ToolManager` registry that advertises those definitions and
+> executes calls with per-call error isolation, and the correlated `ToolCall` and `ToolResult`
+> pair that travels between a caller and the registry.
+
+Build a tool with the `createTool` function, register it in a registry from the
+`createToolManager` function, hand `definitions()` to whatever chooses the call, and pass the
+call you get back to `execute`. Nothing here is model-specific — an agent loop, an MCP bridge,
+and plain application code are all callers.
 
 ## Install
 

package/dist/src/core/index.cjs

@@ -1,16 +1,48 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 let _orkestrel_contract = require("@orkestrel/contract");
+//#region src/core/helpers.ts
+/**
+* Projects a tool onto the plain definition advertised to a caller, advertising an
+* authored `summary` in place of the full description and carrying the parameter schema
+* by reference.
+*
+* @remarks
+* The projection is a fresh object carrying `name`, then `description` only when the
+* tool authored a summary or a description, then `parameters` only when the tool
+* authored a schema. The full `description` stays on the tool for direct lookup, and
+* the definition is never a live handle on the tool's handler.
+*
+* @param tool - The tool to project
+* @returns A fresh definition carrying only the fields the tool authored
+*
+* @example
+* ```ts
+* import { Tool, toolToDefinition } from '@orkestrel/tool'
+*
+* const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })
+* toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }
+* ```
+*/
+function toolToDefinition(tool) {
+	const definition = { name: tool.name };
+	const description = tool.summary ?? tool.description;
+	if (description !== void 0) definition.description = description;
+	if (tool.parameters !== void 0) definition.parameters = tool.parameters;
+	return definition;
+}
+//#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether an unknown value is structurally a {@link ToolCall}.
+* Determines whether an unknown value is structurally a {@link ToolCall}, staying total
+* for malformed and adversarial input.
 *
 * @remarks
-* This total guard accepts a plain record with string `id` and `name` fields and a
+* The accepted shape is a plain record with string `id` and `name` fields and a
 * plain-record `arguments` field. Optional caller context remains opaque and is not
-* read or verified. Adversarial values return `false`.
+* read or verified.
 *
 * @param value - The value to test
-* @returns `true` when the value has the complete tool-call shape
+* @returns True if the value has the complete tool-call shape; false otherwise
 *
 * @example
 * ```ts
@@ -26,7 +58,7 @@ function isToolCall(value) {
 //#endregion
 //#region src/core/tools/Tool.ts
 /**
-* An executable tool definition bound to a handler.
+* Binds an executable tool definition to a handler.
 *
 * @remarks
 * Schema fields, arguments, and present caller context are forwarded by reference.
@@ -69,14 +101,15 @@ var Tool = class {
 //#endregion
 //#region src/core/tools/ToolManager.ts
 /**
-* An insertion-ordered tool registry with per-call error isolation.
+* Represents an insertion-ordered tool registry with per-call error isolation.
 *
 * @remarks
 * A repeated name overwrites the registered tool without changing its insertion
 * position. Definitions advertise `summary` in place of `description` when present.
-* Unknown names and handler throws resolve to error results; batch execution preserves
-* input order and never fails as a whole because of an individual call. Optional
-* consumer-asserted caller context is forwarded without verification.
+* Unknown names and handler throws resolve to error results; a call whose `id` or `name`
+* accessor throws when read makes its call, and the batch holding it, reject. Batch
+* execution preserves input order and isolates each call whose members are plain
+* values. Optional consumer-asserted caller context is forwarded without verification.
 *
 * @example
 * ```ts
@@ -110,7 +143,7 @@ var ToolManager = class {
 		return [...this.#tools.values()];
 	}
 	definitions() {
-		return [...this.#tools.values()].map((tool) => this.#definition(tool));
+		return [...this.#tools.values()].map((tool) => toolToDefinition(tool));
 	}
 	execute(call) {
 		if ((0, _orkestrel_contract.isArray)(call)) return Promise.all(call.map((one) => this.#run(one)));
@@ -118,8 +151,8 @@ var ToolManager = class {
 	}
 	remove(names) {
 		if ((0, _orkestrel_contract.isArray)(names)) {
-			let removed = false;
-			for (const name of names) if (this.#tools.delete(name)) removed = true;
+			let removed = true;
+			for (const name of names) if (!this.#tools.delete(name)) removed = false;
 			return removed;
 		}
 		return this.#tools.delete(names);
@@ -154,30 +187,34 @@ var ToolManager = class {
 			};
 		}
 	}
-	#definition(tool) {
-		const definition = { name: tool.name };
-		const description = tool.summary ?? tool.description;
-		if (description !== void 0) definition.description = description;
-		if (tool.parameters !== void 0) definition.parameters = tool.parameters;
-		return definition;
-	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create an executable tool.
+* Creates an executable tool bound to the supplied handler, returned as a
+* `ToolInterface` so a call site holds the published contract rather than the `Tool`
+* class.
 *
 * @param options - The advertised definition and execution handler
 * @returns A tool bound to the supplied handler
 *
-* @example
+* @example Anatomy of a tool
 * ```ts
 * import { createTool } from '@orkestrel/tool'
 *
 * const add = createTool({
 * 	name: 'add',
-* 	description: 'Add two numbers',
-* 	execute: (args) => Number(args.a) + Number(args.b),
+* 	description: 'Add two numeric values and return their sum. Both operands are required.',
+* 	summary: 'Add two numbers.',
+* 	parameters: {
+* 		type: 'object',
+* 		properties: {
+* 			left: { type: 'number' },
+* 			right: { type: 'number' },
+* 		},
+* 		required: ['left', 'right'],
+* 	},
+* 	execute: (args) => Number(args.left) + Number(args.right),
 * })
 * ```
 */
@@ -185,10 +222,11 @@ function createTool(options) {
 	return new Tool(options);
 }
 /**
-* Create an empty tool registry.
+* Creates an empty registry that advertises definitions and executes calls with
+* per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the
+* published contract rather than the `ToolManager` class.
 *
-* @returns A registry that advertises definitions and executes calls with per-call
-* error isolation
+* @returns A registry bound to no tools
 *
 * @example
 * ```ts
@@ -212,5 +250,6 @@ exports.ToolManager = ToolManager;
 exports.createTool = createTool;
 exports.createToolManager = createToolManager;
 exports.isToolCall = isToolCall;
+exports.toolToDefinition = toolToDefinition;
 
 //# sourceMappingURL=index.cjs.map

package/dist/src/core/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","names":["#execute","#tools","#definition","#run"],"sources":["../../../src/core/validators.ts","../../../src/core/tools/Tool.ts","../../../src/core/tools/ToolManager.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { ToolCall } from './types.js'\nimport { holds, isRecord, isString } from '@orkestrel/contract'\n\n/**\n * Determine whether an unknown value is structurally a {@link ToolCall}.\n *\n * @remarks\n * This total guard accepts a plain record with string `id` and `name` fields and a\n * plain-record `arguments` field. Optional caller context remains opaque and is not\n * read or verified. Adversarial values return `false`.\n *\n * @param value - The value to test\n * @returns `true` when the value has the complete tool-call shape\n *\n * @example\n * ```ts\n * import { isToolCall } from '@orkestrel/tool'\n *\n * isToolCall({ id: '1', name: 'search', arguments: { query: 'birds' } }) // true\n * isToolCall({ id: '1', name: 'search', arguments: [] }) // false\n * ```\n */\nexport function isToolCall(value: unknown): value is ToolCall {\n\treturn holds(\n\t\t() =>\n\t\t\tisRecord(value) && isString(value.id) && isString(value.name) && isRecord(value.arguments),\n\t)\n}\n","import type { ToolInterface, ToolOptions } from '../types.js'\n\n/**\n * An executable tool definition bound to a handler.\n *\n * @remarks\n * Schema fields, arguments, and present caller context are forwarded by reference.\n * Caller context is consumer-asserted and is not verified. Handler failures are not\n * caught here; {@link ToolManager} owns per-call error isolation.\n *\n * @example\n * ```ts\n * import { Tool } from '@orkestrel/tool'\n *\n * const tool = new Tool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: { a: { type: 'number' }, b: { type: 'number' } },\n * \t},\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport class Tool implements ToolInterface {\n\treadonly name: string\n\treadonly description?: string\n\treadonly summary?: string\n\treadonly parameters?: Readonly<Record<string, unknown>>\n\treadonly #execute: (\n\t\targs: Readonly<Record<string, unknown>>,\n\t\tcaller?: unknown,\n\t) => Promise<unknown> | unknown\n\n\tconstructor(options: ToolOptions) {\n\t\tthis.name = options.name\n\t\tif (options.description !== undefined) this.description = options.description\n\t\tif (options.summary !== undefined) this.summary = options.summary\n\t\tif (options.parameters !== undefined) this.parameters = options.parameters\n\t\tthis.#execute = options.execute\n\t}\n\n\texecute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown {\n\t\tif (caller === undefined) return this.#execute(args)\n\t\treturn this.#execute(args, caller)\n\t}\n}\n","import type {\n\tToolCall,\n\tToolDefinition,\n\tToolInterface,\n\tToolManagerInterface,\n\tToolResult,\n} from '../types.js'\nimport { attempt, isArray } from '@orkestrel/contract'\n\n/**\n * An insertion-ordered tool registry with per-call error isolation.\n *\n * @remarks\n * A repeated name overwrites the registered tool without changing its insertion\n * position. Definitions advertise `summary` in place of `description` when present.\n * Unknown names and handler throws resolve to error results; batch execution preserves\n * input order and never fails as a whole because of an individual call. Optional\n * consumer-asserted caller context is forwarded without verification.\n *\n * @example\n * ```ts\n * import { Tool, ToolManager } from '@orkestrel/tool'\n *\n * const tools = new ToolManager()\n * tools.add(new Tool({ name: 'add', execute: (args) => Number(args.x) + Number(args.y) }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'add',\n * \targuments: { x: 1, y: 2 },\n * })\n * ```\n */\nexport class ToolManager implements ToolManagerInterface {\n\treadonly #tools = new Map<string, ToolInterface>()\n\n\tget count(): number {\n\t\treturn this.#tools.size\n\t}\n\n\tadd(tool: ToolInterface): void\n\tadd(tools: readonly ToolInterface[]): void\n\tadd(tools: ToolInterface | readonly ToolInterface[]): void {\n\t\tif (isArray(tools)) {\n\t\t\tfor (const tool of tools) this.#tools.set(tool.name, tool)\n\t\t\treturn\n\t\t}\n\t\tthis.#tools.set(tools.name, tools)\n\t}\n\n\ttool(name: string): ToolInterface | undefined {\n\t\treturn this.#tools.get(name)\n\t}\n\n\ttools(): readonly ToolInterface[] {\n\t\treturn [...this.#tools.values()]\n\t}\n\n\tdefinitions(): readonly ToolDefinition[] {\n\t\treturn [...this.#tools.values()].map((tool) => this.#definition(tool))\n\t}\n\n\texecute(call: ToolCall): Promise<ToolResult>\n\texecute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>\n\texecute(call: ToolCall | readonly ToolCall[]): Promise<ToolResult | readonly ToolResult[]> {\n\t\tif (isArray(call)) return Promise.all(call.map((one) => this.#run(one)))\n\t\treturn this.#run(call)\n\t}\n\n\tremove(name: string): boolean\n\tremove(names: readonly string[]): boolean\n\tremove(names: string | readonly string[]): boolean {\n\t\tif (isArray(names)) {\n\t\t\tlet removed = false\n\t\t\tfor (const name of names) {\n\t\t\t\tif (this.#tools.delete(name)) removed = true\n\t\t\t}\n\t\t\treturn removed\n\t\t}\n\t\treturn this.#tools.delete(names)\n\t}\n\n\tclear(): void {\n\t\tthis.#tools.clear()\n\t}\n\n\tasync #run(call: ToolCall): Promise<ToolResult> {\n\t\tconst tool = this.#tools.get(call.name)\n\t\tif (tool === undefined) {\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `tool not found: ${call.name}`,\n\t\t\t}\n\t\t}\n\t\ttry {\n\t\t\tconst caller = call.caller\n\t\t\tconst value = await (caller === undefined\n\t\t\t\t? tool.execute(call.arguments)\n\t\t\t\t: tool.execute(call.arguments, caller))\n\t\t\treturn { id: call.id, name: call.name, success: true, value }\n\t\t} catch (error) {\n\t\t\tconst message = attempt(() =>\n\t\t\t\terror instanceof Error ? String(error.message) : String(error),\n\t\t\t)\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: message.success ? message.value : 'Unknown thrown value',\n\t\t\t}\n\t\t}\n\t}\n\n\t#definition(tool: ToolInterface): ToolDefinition {\n\t\tconst definition: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tparameters?: Readonly<Record<string, unknown>>\n\t\t} = {\n\t\t\tname: tool.name,\n\t\t}\n\t\tconst description = tool.summary ?? tool.description\n\t\tif (description !== undefined) definition.description = description\n\t\tif (tool.parameters !== undefined) definition.parameters = tool.parameters\n\t\treturn definition\n\t}\n}\n","import type { ToolInterface, ToolManagerInterface, ToolOptions } from './types.js'\nimport { Tool } from './tools/Tool.js'\nimport { ToolManager } from './tools/ToolManager.js'\n\n/**\n * Create an executable tool.\n *\n * @param options - The advertised definition and execution handler\n * @returns A tool bound to the supplied handler\n *\n * @example\n * ```ts\n * import { createTool } from '@orkestrel/tool'\n *\n * const add = createTool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport function createTool(options: ToolOptions): ToolInterface {\n\treturn new Tool(options)\n}\n\n/**\n * Create an empty tool registry.\n *\n * @returns A registry that advertises definitions and executes calls with per-call\n * error isolation\n *\n * @example\n * ```ts\n * import { createTool, createToolManager } from '@orkestrel/tool'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'echo', execute: (args) => args.value }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'echo',\n * \targuments: { value: 'hello' },\n * })\n * ```\n */\nexport function createToolManager(): ToolManagerInterface {\n\treturn new ToolManager()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WAAW,OAAmC;CAC7D,QAAA,GAAO,oBAAA,MAAA,QAAA,GAEL,oBAAA,SAAA,CAAS,KAAK,MAAA,GAAK,oBAAA,SAAA,CAAS,MAAM,EAAE,MAAA,GAAK,oBAAA,SAAA,CAAS,MAAM,IAAI,MAAA,GAAK,oBAAA,SAAA,CAAS,MAAM,SAAS,CAC3F;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;ACFA,IAAa,OAAb,MAA2C;CAC1C;CACA;CACA;CACA;CACA;CAKA,YAAY,SAAsB;EACjC,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,gBAAgB,KAAA,GAAW,KAAK,cAAc,QAAQ;EAClE,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,eAAe,KAAA,GAAW,KAAK,aAAa,QAAQ;EAChE,KAAKA,WAAW,QAAQ;CACzB;CAEA,QAAQ,MAAyC,QAA8C;EAC9F,IAAI,WAAW,KAAA,GAAW,OAAO,KAAKA,SAAS,IAAI;EACnD,OAAO,KAAKA,SAAS,MAAM,MAAM;CAClC;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;ACfA,IAAa,cAAb,MAAyD;CACxD,yBAAkB,IAAI,IAA2B;CAEjD,IAAI,QAAgB;EACnB,OAAO,KAAKC,OAAO;CACpB;CAIA,IAAI,OAAuD;EAC1D,KAAA,GAAI,oBAAA,QAAA,CAAQ,KAAK,GAAG;GACnB,KAAK,MAAM,QAAQ,OAAO,KAAKA,OAAO,IAAI,KAAK,MAAM,IAAI;GACzD;EACD;EACA,KAAKA,OAAO,IAAI,MAAM,MAAM,KAAK;CAClC;CAEA,KAAK,MAAyC;EAC7C,OAAO,KAAKA,OAAO,IAAI,IAAI;CAC5B;CAEA,QAAkC;EACjC,OAAO,CAAC,GAAG,KAAKA,OAAO,OAAO,CAAC;CAChC;CAEA,cAAyC;EACxC,OAAO,CAAC,GAAG,KAAKA,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,KAAKC,YAAY,IAAI,CAAC;CACtE;CAIA,QAAQ,MAAmF;EAC1F,KAAA,GAAI,oBAAA,QAAA,CAAQ,IAAI,GAAG,OAAO,QAAQ,IAAI,KAAK,KAAK,QAAQ,KAAKC,KAAK,GAAG,CAAC,CAAC;EACvE,OAAO,KAAKA,KAAK,IAAI;CACtB;CAIA,OAAO,OAA4C;EAClD,KAAA,GAAI,oBAAA,QAAA,CAAQ,KAAK,GAAG;GACnB,IAAI,UAAU;GACd,KAAK,MAAM,QAAQ,OAClB,IAAI,KAAKF,OAAO,OAAO,IAAI,GAAG,UAAU;GAEzC,OAAO;EACR;EACA,OAAO,KAAKA,OAAO,OAAO,KAAK;CAChC;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,MAAME,KAAK,MAAqC;EAC/C,MAAM,OAAO,KAAKF,OAAO,IAAI,KAAK,IAAI;EACtC,IAAI,SAAS,KAAA,GACZ,OAAO;GACN,IAAI,KAAK;GACT,MAAM,KAAK;GACX,SAAS;GACT,OAAO,mBAAmB,KAAK;EAChC;EAED,IAAI;GACH,MAAM,SAAS,KAAK;GACpB,MAAM,QAAQ,OAAO,WAAW,KAAA,IAC7B,KAAK,QAAQ,KAAK,SAAS,IAC3B,KAAK,QAAQ,KAAK,WAAW,MAAM;GACtC,OAAO;IAAE,IAAI,KAAK;IAAI,MAAM,KAAK;IAAM,SAAS;IAAM;GAAM;EAC7D,SAAS,OAAO;GACf,MAAM,WAAA,GAAU,oBAAA,QAAA,OACf,iBAAiB,QAAQ,OAAO,MAAM,OAAO,IAAI,OAAO,KAAK,CAC9D;GACA,OAAO;IACN,IAAI,KAAK;IACT,MAAM,KAAK;IACX,SAAS;IACT,OAAO,QAAQ,UAAU,QAAQ,QAAQ;GAC1C;EACD;CACD;CAEA,YAAY,MAAqC;EAChD,MAAM,aAIF,EACH,MAAM,KAAK,KACZ;EACA,MAAM,cAAc,KAAK,WAAW,KAAK;EACzC,IAAI,gBAAgB,KAAA,GAAW,WAAW,cAAc;EACxD,IAAI,KAAK,eAAe,KAAA,GAAW,WAAW,aAAa,KAAK;EAChE,OAAO;CACR;AACD;;;;;;;;;;;;;;;;;;;;AC1GA,SAAgB,WAAW,SAAqC;CAC/D,OAAO,IAAI,KAAK,OAAO;AACxB;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,oBAA0C;CACzD,OAAO,IAAI,YAAY;AACxB"}
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/validators.ts","../../../src/core/tools/Tool.ts","../../../src/core/tools/ToolManager.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { ToolDefinition, ToolInterface } from './types.js'\n\n/**\n * Projects a tool onto the plain definition advertised to a caller, advertising an\n * authored `summary` in place of the full description and carrying the parameter schema\n * by reference.\n *\n * @remarks\n * The projection is a fresh object carrying `name`, then `description` only when the\n * tool authored a summary or a description, then `parameters` only when the tool\n * authored a schema. The full `description` stays on the tool for direct lookup, and\n * the definition is never a live handle on the tool's handler.\n *\n * @param tool - The tool to project\n * @returns A fresh definition carrying only the fields the tool authored\n *\n * @example\n * ```ts\n * import { Tool, toolToDefinition } from '@orkestrel/tool'\n *\n * const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })\n * toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }\n * ```\n */\nexport function toolToDefinition(tool: ToolInterface): ToolDefinition {\n\tconst definition: {\n\t\tname: string\n\t\tdescription?: string\n\t\tparameters?: Readonly<Record<string, unknown>>\n\t} = {\n\t\tname: tool.name,\n\t}\n\tconst description = tool.summary ?? tool.description\n\tif (description !== undefined) definition.description = description\n\tif (tool.parameters !== undefined) definition.parameters = tool.parameters\n\treturn definition\n}\n","import type { ToolCall } from './types.js'\nimport { holds, isRecord, isString } from '@orkestrel/contract'\n\n/**\n * Determines whether an unknown value is structurally a {@link ToolCall}, staying total\n * for malformed and adversarial input.\n *\n * @remarks\n * The accepted shape is a plain record with string `id` and `name` fields and a\n * plain-record `arguments` field. Optional caller context remains opaque and is not\n * read or verified.\n *\n * @param value - The value to test\n * @returns True if the value has the complete tool-call shape; false otherwise\n *\n * @example\n * ```ts\n * import { isToolCall } from '@orkestrel/tool'\n *\n * isToolCall({ id: '1', name: 'search', arguments: { query: 'birds' } }) // true\n * isToolCall({ id: '1', name: 'search', arguments: [] }) // false\n * ```\n */\nexport function isToolCall(value: unknown): value is ToolCall {\n\treturn holds(\n\t\t() =>\n\t\t\tisRecord(value) && isString(value.id) && isString(value.name) && isRecord(value.arguments),\n\t)\n}\n","import type { ToolInterface, ToolOptions } from '../types.js'\n\n/**\n * Binds an executable tool definition to a handler.\n *\n * @remarks\n * Schema fields, arguments, and present caller context are forwarded by reference.\n * Caller context is consumer-asserted and is not verified. Handler failures are not\n * caught here; {@link ToolManager} owns per-call error isolation.\n *\n * @example\n * ```ts\n * import { Tool } from '@orkestrel/tool'\n *\n * const tool = new Tool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: { a: { type: 'number' }, b: { type: 'number' } },\n * \t},\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport class Tool implements ToolInterface {\n\treadonly name: string\n\treadonly description?: string\n\treadonly summary?: string\n\treadonly parameters?: Readonly<Record<string, unknown>>\n\treadonly #execute: (\n\t\targs: Readonly<Record<string, unknown>>,\n\t\tcaller?: unknown,\n\t) => Promise<unknown> | unknown\n\n\tconstructor(options: ToolOptions) {\n\t\tthis.name = options.name\n\t\tif (options.description !== undefined) this.description = options.description\n\t\tif (options.summary !== undefined) this.summary = options.summary\n\t\tif (options.parameters !== undefined) this.parameters = options.parameters\n\t\tthis.#execute = options.execute\n\t}\n\n\texecute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown {\n\t\tif (caller === undefined) return this.#execute(args)\n\t\treturn this.#execute(args, caller)\n\t}\n}\n","import type {\n\tToolCall,\n\tToolDefinition,\n\tToolInterface,\n\tToolManagerInterface,\n\tToolResult,\n} from '../types.js'\nimport { attempt, isArray } from '@orkestrel/contract'\nimport { toolToDefinition } from '../helpers.js'\n\n/**\n * Represents an insertion-ordered tool registry with per-call error isolation.\n *\n * @remarks\n * A repeated name overwrites the registered tool without changing its insertion\n * position. Definitions advertise `summary` in place of `description` when present.\n * Unknown names and handler throws resolve to error results; a call whose `id` or `name`\n * accessor throws when read makes its call, and the batch holding it, reject. Batch\n * execution preserves input order and isolates each call whose members are plain\n * values. Optional consumer-asserted caller context is forwarded without verification.\n *\n * @example\n * ```ts\n * import { Tool, ToolManager } from '@orkestrel/tool'\n *\n * const tools = new ToolManager()\n * tools.add(new Tool({ name: 'add', execute: (args) => Number(args.x) + Number(args.y) }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'add',\n * \targuments: { x: 1, y: 2 },\n * })\n * ```\n */\nexport class ToolManager implements ToolManagerInterface {\n\treadonly #tools = new Map<string, ToolInterface>()\n\n\tget count(): number {\n\t\treturn this.#tools.size\n\t}\n\n\tadd(tool: ToolInterface): void\n\tadd(tools: readonly ToolInterface[]): void\n\tadd(tools: ToolInterface | readonly ToolInterface[]): void {\n\t\tif (isArray(tools)) {\n\t\t\tfor (const tool of tools) this.#tools.set(tool.name, tool)\n\t\t\treturn\n\t\t}\n\t\tthis.#tools.set(tools.name, tools)\n\t}\n\n\ttool(name: string): ToolInterface | undefined {\n\t\treturn this.#tools.get(name)\n\t}\n\n\ttools(): readonly ToolInterface[] {\n\t\treturn [...this.#tools.values()]\n\t}\n\n\tdefinitions(): readonly ToolDefinition[] {\n\t\treturn [...this.#tools.values()].map((tool) => toolToDefinition(tool))\n\t}\n\n\texecute(call: ToolCall): Promise<ToolResult>\n\texecute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>\n\texecute(call: ToolCall | readonly ToolCall[]): Promise<ToolResult | readonly ToolResult[]> {\n\t\tif (isArray(call)) return Promise.all(call.map((one) => this.#run(one)))\n\t\treturn this.#run(call)\n\t}\n\n\tremove(name: string): boolean\n\tremove(names: readonly string[]): boolean\n\tremove(names: string | readonly string[]): boolean {\n\t\tif (isArray(names)) {\n\t\t\tlet removed = true\n\t\t\tfor (const name of names) {\n\t\t\t\tif (!this.#tools.delete(name)) removed = false\n\t\t\t}\n\t\t\treturn removed\n\t\t}\n\t\treturn this.#tools.delete(names)\n\t}\n\n\tclear(): void {\n\t\tthis.#tools.clear()\n\t}\n\n\tasync #run(call: ToolCall): Promise<ToolResult> {\n\t\tconst tool = this.#tools.get(call.name)\n\t\tif (tool === undefined) {\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `tool not found: ${call.name}`,\n\t\t\t}\n\t\t}\n\t\ttry {\n\t\t\tconst caller = call.caller\n\t\t\tconst value = await (caller === undefined\n\t\t\t\t? tool.execute(call.arguments)\n\t\t\t\t: tool.execute(call.arguments, caller))\n\t\t\treturn { id: call.id, name: call.name, success: true, value }\n\t\t} catch (error) {\n\t\t\tconst message = attempt(() =>\n\t\t\t\terror instanceof Error ? String(error.message) : String(error),\n\t\t\t)\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: message.success ? message.value : 'Unknown thrown value',\n\t\t\t}\n\t\t}\n\t}\n}\n","import type { ToolInterface, ToolManagerInterface, ToolOptions } from './types.js'\nimport { Tool } from './tools/Tool.js'\nimport { ToolManager } from './tools/ToolManager.js'\n\n/**\n * Creates an executable tool bound to the supplied handler, returned as a\n * `ToolInterface` so a call site holds the published contract rather than the `Tool`\n * class.\n *\n * @param options - The advertised definition and execution handler\n * @returns A tool bound to the supplied handler\n *\n * @example Anatomy of a tool\n * ```ts\n * import { createTool } from '@orkestrel/tool'\n *\n * const add = createTool({\n * \tname: 'add',\n * \tdescription: 'Add two numeric values and return their sum. Both operands are required.',\n * \tsummary: 'Add two numbers.',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: {\n * \t\t\tleft: { type: 'number' },\n * \t\t\tright: { type: 'number' },\n * \t\t},\n * \t\trequired: ['left', 'right'],\n * \t},\n * \texecute: (args) => Number(args.left) + Number(args.right),\n * })\n * ```\n */\nexport function createTool(options: ToolOptions): ToolInterface {\n\treturn new Tool(options)\n}\n\n/**\n * Creates an empty registry that advertises definitions and executes calls with\n * per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the\n * published contract rather than the `ToolManager` class.\n *\n * @returns A registry bound to no tools\n *\n * @example\n * ```ts\n * import { createTool, createToolManager } from '@orkestrel/tool'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'echo', execute: (args) => args.value }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'echo',\n * \targuments: { value: 'hello' },\n * })\n * ```\n */\nexport function createToolManager(): ToolManagerInterface {\n\treturn new ToolManager()\n}\n"],"mappings":"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"}

package/dist/src/core/index.d.cts

@@ -1,30 +1,42 @@
-import { Failure } from '@orkestrel/contract';
-import { Success } from '@orkestrel/contract';
+import type { Failure } from '@orkestrel/contract';
+import type { Success } from '@orkestrel/contract';
 
 /**
- * Create an executable tool.
+ * Creates an executable tool bound to the supplied handler, returned as a
+ * `ToolInterface` so a call site holds the published contract rather than the `Tool`
+ * class.
  *
  * @param options - The advertised definition and execution handler
  * @returns A tool bound to the supplied handler
  *
- * @example
+ * @example Anatomy of a tool
  * ```ts
  * import { createTool } from '@orkestrel/tool'
  *
  * const add = createTool({
  * 	name: 'add',
- * 	description: 'Add two numbers',
- * 	execute: (args) => Number(args.a) + Number(args.b),
+ * 	description: 'Add two numeric values and return their sum. Both operands are required.',
+ * 	summary: 'Add two numbers.',
+ * 	parameters: {
+ * 		type: 'object',
+ * 		properties: {
+ * 			left: { type: 'number' },
+ * 			right: { type: 'number' },
+ * 		},
+ * 		required: ['left', 'right'],
+ * 	},
+ * 	execute: (args) => Number(args.left) + Number(args.right),
  * })
  * ```
  */
 export declare function createTool(options: ToolOptions): ToolInterface;
 
 /**
- * Create an empty tool registry.
+ * Creates an empty registry that advertises definitions and executes calls with
+ * per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the
+ * published contract rather than the `ToolManager` class.
  *
- * @returns A registry that advertises definitions and executes calls with per-call
- * error isolation
+ * @returns A registry bound to no tools
  *
  * @example
  * ```ts
@@ -42,15 +54,16 @@ export declare function createTool(options: ToolOptions): ToolInterface;
 export declare function createToolManager(): ToolManagerInterface;
 
 /**
- * Determine whether an unknown value is structurally a {@link ToolCall}.
+ * Determines whether an unknown value is structurally a {@link ToolCall}, staying total
+ * for malformed and adversarial input.
  *
  * @remarks
- * This total guard accepts a plain record with string `id` and `name` fields and a
+ * The accepted shape is a plain record with string `id` and `name` fields and a
  * plain-record `arguments` field. Optional caller context remains opaque and is not
- * read or verified. Adversarial values return `false`.
+ * read or verified.
  *
  * @param value - The value to test
- * @returns `true` when the value has the complete tool-call shape
+ * @returns True if the value has the complete tool-call shape; false otherwise
  *
  * @example
  * ```ts
@@ -63,7 +76,7 @@ export declare function createToolManager(): ToolManagerInterface;
 export declare function isToolCall(value: unknown): value is ToolCall;
 
 /**
- * An executable tool definition bound to a handler.
+ * Binds an executable tool definition to a handler.
  *
  * @remarks
  * Schema fields, arguments, and present caller context are forwarded by reference.
@@ -96,7 +109,7 @@ export declare class Tool implements ToolInterface {
 }
 
 /**
- * A tool call issued by a caller.
+ * Describes one request to run a named tool.
  *
  * @remarks
  * `id` correlates the call with its later {@link ToolResult}. `arguments` is the
@@ -105,33 +118,33 @@ export declare class Tool implements ToolInterface {
  * every trust decision.
  */
 export declare interface ToolCall {
-    /** The identifier that correlates this call with its result. */
+    /** Correlates this call with its result. */
     readonly id: string;
-    /** The name of the tool to execute. */
+    /** Selects the tool to execute. */
     readonly name: string;
-    /** The caller-supplied arguments record. */
+    /** Carries the record the caller supplied. */
     readonly arguments: Readonly<Record<string, unknown>>;
-    /** Consumer-asserted caller context, forwarded without verification. */
+    /** Carries consumer-asserted context, forwarded without verification. */
     readonly caller?: unknown;
 }
 
 /**
- * A tool definition advertised to a caller.
+ * Describes a tool as advertised to a caller.
  *
  * @remarks
  * `parameters` is an open JSON Schema record describing the arguments the tool accepts.
  */
 export declare interface ToolDefinition {
-    /** The name a caller uses to select the tool. */
+    /** Identifies the tool a caller selects. */
     readonly name: string;
-    /** A description of the tool's behavior. */
+    /** Describes the tool's behavior. */
     readonly description?: string;
-    /** The JSON Schema for the tool's arguments. */
+    /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * The failed outcome of executing a {@link ToolCall}.
+ * Reports the failed outcome of executing a {@link ToolCall}.
  *
  * @remarks
  * `error` is the failure message: an unknown tool name, an `Error`'s message, or
@@ -140,24 +153,31 @@ export declare interface ToolDefinition {
  * `tool.execute(args)` in its own `try`/`catch`.
  */
 export declare interface ToolFailure extends Failure<string> {
-    /** The identifier of the corresponding call. */
+    /** Identifies the corresponding call. */
     readonly id: string;
-    /** The name of the called tool. */
+    /** Identifies the called tool. */
     readonly name: string;
 }
 
 /**
- * An executable tool: its advertised definition plus its local handler.
+ * Represents an executable tool: its advertised definition plus its local handler.
  *
  * @remarks
  * `summary`, when present, is advertised in place of the full `description` by a
  * {@link ToolManagerInterface}. The full description remains available on the tool.
  */
 export declare interface ToolInterface extends ToolDefinition {
-    /** A concise description to advertise in place of the full description. */
+    /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
     /**
-     * Execute the tool.
+     * Runs the tool's handler with the caller-supplied arguments and any consumer-asserted
+     * caller context.
+     *
+     * @remarks
+     * Failures are not contained here: a synchronous throw propagates and an
+     * asynchronous rejection rejects. {@link ToolManagerInterface.execute} is where a
+     * call becomes a result. The registry omits `caller` from the invocation when the
+     * call carries none, so a handler reading its own arity sees one argument.
      *
      * @param args - The caller-supplied arguments record
      * @param caller - Optional consumer-asserted caller context, forwarded without verification
@@ -167,14 +187,15 @@ export declare interface ToolInterface extends ToolDefinition {
 }
 
 /**
- * An insertion-ordered tool registry with per-call error isolation.
+ * Represents an insertion-ordered tool registry with per-call error isolation.
  *
  * @remarks
  * A repeated name overwrites the registered tool without changing its insertion
  * position. Definitions advertise `summary` in place of `description` when present.
- * Unknown names and handler throws resolve to error results; batch execution preserves
- * input order and never fails as a whole because of an individual call. Optional
- * consumer-asserted caller context is forwarded without verification.
+ * Unknown names and handler throws resolve to error results; a call whose `id` or `name`
+ * accessor throws when read makes its call, and the batch holding it, reject. Batch
+ * execution preserves input order and isolates each call whose members are plain
+ * values. Optional consumer-asserted caller context is forwarded without verification.
  *
  * @example
  * ```ts
@@ -205,47 +226,49 @@ export declare class ToolManager implements ToolManagerInterface {
 }
 
 /**
- * A registry of executable tools with per-call error isolation.
+ * Represents a registry of executable tools with per-call error isolation.
  *
  * @remarks
  * Tools are keyed by name in insertion order. Adding an existing name overwrites its
- * value without changing its position. Every call resolves to a {@link ToolResult};
- * missing tools and thrown handlers become error results. Batch execution preserves
- * input order and isolates each call.
+ * value without changing its position. Every call whose members are plain values
+ * resolves to a {@link ToolResult}; missing tools and thrown handlers become error
+ * results, and a call whose `id` or `name` accessor throws when read makes `execute`
+ * reject instead. Batch execution preserves input order.
  */
 export declare interface ToolManagerInterface {
-    /** The number of registered tools. */
+    /** Reports how many tools are registered. */
     readonly count: number;
     /**
-     * Register one tool.
+     * Registers one tool.
      *
      * @param tool - The tool to register
      * @returns Nothing
      */
     add(tool: ToolInterface): void;
     /**
-     * Register a batch of tools.
+     * Registers a batch of tools.
      *
      * @param tools - The tools to register
      * @returns Nothing
      */
     add(tools: readonly ToolInterface[]): void;
     /**
-     * Find one registered tool by name.
+     * Finds one registered tool by name.
      *
      * @param name - The registered tool name
-     * @returns The tool when found, otherwise `undefined`
+     * @returns The exact registered instance when found, otherwise `undefined`
      */
     tool(name: string): ToolInterface | undefined;
     /**
-     * List the registered tools in insertion order.
+     * Lists the registered tools in insertion order.
      *
      * @returns A new readonly array of registered tools
      */
     tools(): readonly ToolInterface[];
     /**
-     * List the definitions advertised to a caller.
+     * Lists the definitions advertised to a caller.
      *
+     * @remarks
      * The projected `description` is the tool's `summary` when one was authored,
      * advertised in place of the full description. The full text stays on the tool
      * for direct lookup.
@@ -254,35 +277,35 @@ export declare interface ToolManagerInterface {
      */
     definitions(): readonly ToolDefinition[];
     /**
-     * Execute one call with error isolation.
+     * Executes one call with error isolation.
      *
      * @param call - The tool call to execute, including optional caller context
      * @returns The correlated result
      */
     execute(call: ToolCall): Promise<ToolResult>;
     /**
-     * Execute a batch of calls with per-call error isolation.
+     * Executes a batch of calls with per-call error isolation.
      *
      * @param calls - The tool calls to execute, including optional caller context
      * @returns The correlated results in input order
      */
     execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
     /**
-     * Remove one registered tool.
+     * Removes one registered tool.
      *
      * @param name - The tool name to remove
-     * @returns Whether the tool was present
+     * @returns True if the tool was present; false otherwise
      */
     remove(name: string): boolean;
     /**
-     * Remove a batch of registered tools.
+     * Removes a batch of registered tools.
      *
      * @param names - The tool names to remove
-     * @returns Whether any named tool was present
+     * @returns True if every named tool was present; false otherwise
      */
     remove(names: readonly string[]): boolean;
     /**
-     * Remove every registered tool.
+     * Removes every registered tool.
      *
      * @returns Nothing
      */
@@ -290,7 +313,7 @@ export declare interface ToolManagerInterface {
 }
 
 /**
- * Options for creating an executable tool.
+ * Configures an executable tool.
  *
  * @remarks
  * `name` identifies the tool, `description` and `parameters` define what is advertised
@@ -299,38 +322,64 @@ export declare interface ToolManagerInterface {
  * context. This package forwards that context without verification.
  */
 export declare interface ToolOptions {
-    /** The name a caller uses to select the tool. */
+    /** Identifies the tool a caller selects. */
     readonly name: string;
-    /** The full description of the tool's behavior. */
+    /** Describes the tool's behavior in full. */
     readonly description?: string;
-    /** A concise description to advertise in place of the full description. */
+    /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
-    /** The JSON Schema for the tool's arguments. */
+    /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
-    /** The handler that receives arguments and optional unverified caller context. */
+    /** Handles the arguments and optional unverified caller context. */
     readonly execute: (args: Readonly<Record<string, unknown>>, caller?: unknown) => Promise<unknown> | unknown;
 }
 
 /**
- * The outcome of executing a {@link ToolCall}.
+ * Represents the outcome of executing a {@link ToolCall}.
  *
  * @remarks
- * Always a result and never a throw. Narrow on `success`.
+ * Always a result and never a throw for a call whose members are plain values. A call
+ * whose `id` or `name` accessor throws when read makes `execute` reject instead, because
+ * no correlated result can be built without them. Narrow on `success`.
  */
 export declare type ToolResult = ToolSuccess | ToolFailure;
 
 /**
- * The successful outcome of executing a {@link ToolCall}.
+ * Reports the successful outcome of executing a {@link ToolCall}.
  *
  * @remarks
  * `value` is whatever the handler returned — including `undefined`, `null`, `0`,
  * `''`, or `false`. A present value never implies a meaningful one.
  */
 export declare interface ToolSuccess extends Success<unknown> {
-    /** The identifier of the corresponding call. */
+    /** Identifies the corresponding call. */
     readonly id: string;
-    /** The name of the called tool. */
+    /** Identifies the called tool. */
     readonly name: string;
 }
 
+/**
+ * Projects a tool onto the plain definition advertised to a caller, advertising an
+ * authored `summary` in place of the full description and carrying the parameter schema
+ * by reference.
+ *
+ * @remarks
+ * The projection is a fresh object carrying `name`, then `description` only when the
+ * tool authored a summary or a description, then `parameters` only when the tool
+ * authored a schema. The full `description` stays on the tool for direct lookup, and
+ * the definition is never a live handle on the tool's handler.
+ *
+ * @param tool - The tool to project
+ * @returns A fresh definition carrying only the fields the tool authored
+ *
+ * @example
+ * ```ts
+ * import { Tool, toolToDefinition } from '@orkestrel/tool'
+ *
+ * const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })
+ * toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }
+ * ```
+ */
+export declare function toolToDefinition(tool: ToolInterface): ToolDefinition;
+
 export { }

package/dist/src/core/index.d.ts

@@ -1,30 +1,42 @@
-import { Failure } from '@orkestrel/contract';
-import { Success } from '@orkestrel/contract';
+import type { Failure } from '@orkestrel/contract';
+import type { Success } from '@orkestrel/contract';
 
 /**
- * Create an executable tool.
+ * Creates an executable tool bound to the supplied handler, returned as a
+ * `ToolInterface` so a call site holds the published contract rather than the `Tool`
+ * class.
  *
  * @param options - The advertised definition and execution handler
  * @returns A tool bound to the supplied handler
  *
- * @example
+ * @example Anatomy of a tool
  * ```ts
  * import { createTool } from '@orkestrel/tool'
  *
  * const add = createTool({
  * 	name: 'add',
- * 	description: 'Add two numbers',
- * 	execute: (args) => Number(args.a) + Number(args.b),
+ * 	description: 'Add two numeric values and return their sum. Both operands are required.',
+ * 	summary: 'Add two numbers.',
+ * 	parameters: {
+ * 		type: 'object',
+ * 		properties: {
+ * 			left: { type: 'number' },
+ * 			right: { type: 'number' },
+ * 		},
+ * 		required: ['left', 'right'],
+ * 	},
+ * 	execute: (args) => Number(args.left) + Number(args.right),
  * })
  * ```
  */
 export declare function createTool(options: ToolOptions): ToolInterface;
 
 /**
- * Create an empty tool registry.
+ * Creates an empty registry that advertises definitions and executes calls with
+ * per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the
+ * published contract rather than the `ToolManager` class.
  *
- * @returns A registry that advertises definitions and executes calls with per-call
- * error isolation
+ * @returns A registry bound to no tools
  *
  * @example
  * ```ts
@@ -42,15 +54,16 @@ export declare function createTool(options: ToolOptions): ToolInterface;
 export declare function createToolManager(): ToolManagerInterface;
 
 /**
- * Determine whether an unknown value is structurally a {@link ToolCall}.
+ * Determines whether an unknown value is structurally a {@link ToolCall}, staying total
+ * for malformed and adversarial input.
  *
  * @remarks
- * This total guard accepts a plain record with string `id` and `name` fields and a
+ * The accepted shape is a plain record with string `id` and `name` fields and a
  * plain-record `arguments` field. Optional caller context remains opaque and is not
- * read or verified. Adversarial values return `false`.
+ * read or verified.
  *
  * @param value - The value to test
- * @returns `true` when the value has the complete tool-call shape
+ * @returns True if the value has the complete tool-call shape; false otherwise
  *
  * @example
  * ```ts
@@ -63,7 +76,7 @@ export declare function createToolManager(): ToolManagerInterface;
 export declare function isToolCall(value: unknown): value is ToolCall;
 
 /**
- * An executable tool definition bound to a handler.
+ * Binds an executable tool definition to a handler.
  *
  * @remarks
  * Schema fields, arguments, and present caller context are forwarded by reference.
@@ -96,7 +109,7 @@ export declare class Tool implements ToolInterface {
 }
 
 /**
- * A tool call issued by a caller.
+ * Describes one request to run a named tool.
  *
  * @remarks
  * `id` correlates the call with its later {@link ToolResult}. `arguments` is the
@@ -105,33 +118,33 @@ export declare class Tool implements ToolInterface {
  * every trust decision.
  */
 export declare interface ToolCall {
-    /** The identifier that correlates this call with its result. */
+    /** Correlates this call with its result. */
     readonly id: string;
-    /** The name of the tool to execute. */
+    /** Selects the tool to execute. */
     readonly name: string;
-    /** The caller-supplied arguments record. */
+    /** Carries the record the caller supplied. */
     readonly arguments: Readonly<Record<string, unknown>>;
-    /** Consumer-asserted caller context, forwarded without verification. */
+    /** Carries consumer-asserted context, forwarded without verification. */
     readonly caller?: unknown;
 }
 
 /**
- * A tool definition advertised to a caller.
+ * Describes a tool as advertised to a caller.
  *
  * @remarks
  * `parameters` is an open JSON Schema record describing the arguments the tool accepts.
  */
 export declare interface ToolDefinition {
-    /** The name a caller uses to select the tool. */
+    /** Identifies the tool a caller selects. */
     readonly name: string;
-    /** A description of the tool's behavior. */
+    /** Describes the tool's behavior. */
     readonly description?: string;
-    /** The JSON Schema for the tool's arguments. */
+    /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
 }
 
 /**
- * The failed outcome of executing a {@link ToolCall}.
+ * Reports the failed outcome of executing a {@link ToolCall}.
  *
  * @remarks
  * `error` is the failure message: an unknown tool name, an `Error`'s message, or
@@ -140,24 +153,31 @@ export declare interface ToolDefinition {
  * `tool.execute(args)` in its own `try`/`catch`.
  */
 export declare interface ToolFailure extends Failure<string> {
-    /** The identifier of the corresponding call. */
+    /** Identifies the corresponding call. */
     readonly id: string;
-    /** The name of the called tool. */
+    /** Identifies the called tool. */
     readonly name: string;
 }
 
 /**
- * An executable tool: its advertised definition plus its local handler.
+ * Represents an executable tool: its advertised definition plus its local handler.
  *
  * @remarks
  * `summary`, when present, is advertised in place of the full `description` by a
  * {@link ToolManagerInterface}. The full description remains available on the tool.
  */
 export declare interface ToolInterface extends ToolDefinition {
-    /** A concise description to advertise in place of the full description. */
+    /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
     /**
-     * Execute the tool.
+     * Runs the tool's handler with the caller-supplied arguments and any consumer-asserted
+     * caller context.
+     *
+     * @remarks
+     * Failures are not contained here: a synchronous throw propagates and an
+     * asynchronous rejection rejects. {@link ToolManagerInterface.execute} is where a
+     * call becomes a result. The registry omits `caller` from the invocation when the
+     * call carries none, so a handler reading its own arity sees one argument.
      *
      * @param args - The caller-supplied arguments record
      * @param caller - Optional consumer-asserted caller context, forwarded without verification
@@ -167,14 +187,15 @@ export declare interface ToolInterface extends ToolDefinition {
 }
 
 /**
- * An insertion-ordered tool registry with per-call error isolation.
+ * Represents an insertion-ordered tool registry with per-call error isolation.
  *
  * @remarks
  * A repeated name overwrites the registered tool without changing its insertion
  * position. Definitions advertise `summary` in place of `description` when present.
- * Unknown names and handler throws resolve to error results; batch execution preserves
- * input order and never fails as a whole because of an individual call. Optional
- * consumer-asserted caller context is forwarded without verification.
+ * Unknown names and handler throws resolve to error results; a call whose `id` or `name`
+ * accessor throws when read makes its call, and the batch holding it, reject. Batch
+ * execution preserves input order and isolates each call whose members are plain
+ * values. Optional consumer-asserted caller context is forwarded without verification.
  *
  * @example
  * ```ts
@@ -205,47 +226,49 @@ export declare class ToolManager implements ToolManagerInterface {
 }
 
 /**
- * A registry of executable tools with per-call error isolation.
+ * Represents a registry of executable tools with per-call error isolation.
  *
  * @remarks
  * Tools are keyed by name in insertion order. Adding an existing name overwrites its
- * value without changing its position. Every call resolves to a {@link ToolResult};
- * missing tools and thrown handlers become error results. Batch execution preserves
- * input order and isolates each call.
+ * value without changing its position. Every call whose members are plain values
+ * resolves to a {@link ToolResult}; missing tools and thrown handlers become error
+ * results, and a call whose `id` or `name` accessor throws when read makes `execute`
+ * reject instead. Batch execution preserves input order.
  */
 export declare interface ToolManagerInterface {
-    /** The number of registered tools. */
+    /** Reports how many tools are registered. */
     readonly count: number;
     /**
-     * Register one tool.
+     * Registers one tool.
      *
      * @param tool - The tool to register
      * @returns Nothing
      */
     add(tool: ToolInterface): void;
     /**
-     * Register a batch of tools.
+     * Registers a batch of tools.
      *
      * @param tools - The tools to register
      * @returns Nothing
      */
     add(tools: readonly ToolInterface[]): void;
     /**
-     * Find one registered tool by name.
+     * Finds one registered tool by name.
      *
      * @param name - The registered tool name
-     * @returns The tool when found, otherwise `undefined`
+     * @returns The exact registered instance when found, otherwise `undefined`
      */
     tool(name: string): ToolInterface | undefined;
     /**
-     * List the registered tools in insertion order.
+     * Lists the registered tools in insertion order.
      *
      * @returns A new readonly array of registered tools
      */
     tools(): readonly ToolInterface[];
     /**
-     * List the definitions advertised to a caller.
+     * Lists the definitions advertised to a caller.
      *
+     * @remarks
      * The projected `description` is the tool's `summary` when one was authored,
      * advertised in place of the full description. The full text stays on the tool
      * for direct lookup.
@@ -254,35 +277,35 @@ export declare interface ToolManagerInterface {
      */
     definitions(): readonly ToolDefinition[];
     /**
-     * Execute one call with error isolation.
+     * Executes one call with error isolation.
      *
      * @param call - The tool call to execute, including optional caller context
      * @returns The correlated result
      */
     execute(call: ToolCall): Promise<ToolResult>;
     /**
-     * Execute a batch of calls with per-call error isolation.
+     * Executes a batch of calls with per-call error isolation.
      *
      * @param calls - The tool calls to execute, including optional caller context
      * @returns The correlated results in input order
      */
     execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
     /**
-     * Remove one registered tool.
+     * Removes one registered tool.
      *
      * @param name - The tool name to remove
-     * @returns Whether the tool was present
+     * @returns True if the tool was present; false otherwise
      */
     remove(name: string): boolean;
     /**
-     * Remove a batch of registered tools.
+     * Removes a batch of registered tools.
      *
      * @param names - The tool names to remove
-     * @returns Whether any named tool was present
+     * @returns True if every named tool was present; false otherwise
      */
     remove(names: readonly string[]): boolean;
     /**
-     * Remove every registered tool.
+     * Removes every registered tool.
      *
      * @returns Nothing
      */
@@ -290,7 +313,7 @@ export declare interface ToolManagerInterface {
 }
 
 /**
- * Options for creating an executable tool.
+ * Configures an executable tool.
  *
  * @remarks
  * `name` identifies the tool, `description` and `parameters` define what is advertised
@@ -299,38 +322,64 @@ export declare interface ToolManagerInterface {
  * context. This package forwards that context without verification.
  */
 export declare interface ToolOptions {
-    /** The name a caller uses to select the tool. */
+    /** Identifies the tool a caller selects. */
     readonly name: string;
-    /** The full description of the tool's behavior. */
+    /** Describes the tool's behavior in full. */
     readonly description?: string;
-    /** A concise description to advertise in place of the full description. */
+    /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
-    /** The JSON Schema for the tool's arguments. */
+    /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
-    /** The handler that receives arguments and optional unverified caller context. */
+    /** Handles the arguments and optional unverified caller context. */
     readonly execute: (args: Readonly<Record<string, unknown>>, caller?: unknown) => Promise<unknown> | unknown;
 }
 
 /**
- * The outcome of executing a {@link ToolCall}.
+ * Represents the outcome of executing a {@link ToolCall}.
  *
  * @remarks
- * Always a result and never a throw. Narrow on `success`.
+ * Always a result and never a throw for a call whose members are plain values. A call
+ * whose `id` or `name` accessor throws when read makes `execute` reject instead, because
+ * no correlated result can be built without them. Narrow on `success`.
  */
 export declare type ToolResult = ToolSuccess | ToolFailure;
 
 /**
- * The successful outcome of executing a {@link ToolCall}.
+ * Reports the successful outcome of executing a {@link ToolCall}.
  *
  * @remarks
  * `value` is whatever the handler returned — including `undefined`, `null`, `0`,
  * `''`, or `false`. A present value never implies a meaningful one.
  */
 export declare interface ToolSuccess extends Success<unknown> {
-    /** The identifier of the corresponding call. */
+    /** Identifies the corresponding call. */
     readonly id: string;
-    /** The name of the called tool. */
+    /** Identifies the called tool. */
     readonly name: string;
 }
 
+/**
+ * Projects a tool onto the plain definition advertised to a caller, advertising an
+ * authored `summary` in place of the full description and carrying the parameter schema
+ * by reference.
+ *
+ * @remarks
+ * The projection is a fresh object carrying `name`, then `description` only when the
+ * tool authored a summary or a description, then `parameters` only when the tool
+ * authored a schema. The full `description` stays on the tool for direct lookup, and
+ * the definition is never a live handle on the tool's handler.
+ *
+ * @param tool - The tool to project
+ * @returns A fresh definition carrying only the fields the tool authored
+ *
+ * @example
+ * ```ts
+ * import { Tool, toolToDefinition } from '@orkestrel/tool'
+ *
+ * const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })
+ * toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }
+ * ```
+ */
+export declare function toolToDefinition(tool: ToolInterface): ToolDefinition;
+
 export { }

package/dist/src/core/index.js

@@ -1,15 +1,47 @@
 import { attempt, holds, isArray, isRecord, isString } from "@orkestrel/contract";
+//#region src/core/helpers.ts
+/**
+* Projects a tool onto the plain definition advertised to a caller, advertising an
+* authored `summary` in place of the full description and carrying the parameter schema
+* by reference.
+*
+* @remarks
+* The projection is a fresh object carrying `name`, then `description` only when the
+* tool authored a summary or a description, then `parameters` only when the tool
+* authored a schema. The full `description` stays on the tool for direct lookup, and
+* the definition is never a live handle on the tool's handler.
+*
+* @param tool - The tool to project
+* @returns A fresh definition carrying only the fields the tool authored
+*
+* @example
+* ```ts
+* import { Tool, toolToDefinition } from '@orkestrel/tool'
+*
+* const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })
+* toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }
+* ```
+*/
+function toolToDefinition(tool) {
+	const definition = { name: tool.name };
+	const description = tool.summary ?? tool.description;
+	if (description !== void 0) definition.description = description;
+	if (tool.parameters !== void 0) definition.parameters = tool.parameters;
+	return definition;
+}
+//#endregion
 //#region src/core/validators.ts
 /**
-* Determine whether an unknown value is structurally a {@link ToolCall}.
+* Determines whether an unknown value is structurally a {@link ToolCall}, staying total
+* for malformed and adversarial input.
 *
 * @remarks
-* This total guard accepts a plain record with string `id` and `name` fields and a
+* The accepted shape is a plain record with string `id` and `name` fields and a
 * plain-record `arguments` field. Optional caller context remains opaque and is not
-* read or verified. Adversarial values return `false`.
+* read or verified.
 *
 * @param value - The value to test
-* @returns `true` when the value has the complete tool-call shape
+* @returns True if the value has the complete tool-call shape; false otherwise
 *
 * @example
 * ```ts
@@ -25,7 +57,7 @@ function isToolCall(value) {
 //#endregion
 //#region src/core/tools/Tool.ts
 /**
-* An executable tool definition bound to a handler.
+* Binds an executable tool definition to a handler.
 *
 * @remarks
 * Schema fields, arguments, and present caller context are forwarded by reference.
@@ -68,14 +100,15 @@ var Tool = class {
 //#endregion
 //#region src/core/tools/ToolManager.ts
 /**
-* An insertion-ordered tool registry with per-call error isolation.
+* Represents an insertion-ordered tool registry with per-call error isolation.
 *
 * @remarks
 * A repeated name overwrites the registered tool without changing its insertion
 * position. Definitions advertise `summary` in place of `description` when present.
-* Unknown names and handler throws resolve to error results; batch execution preserves
-* input order and never fails as a whole because of an individual call. Optional
-* consumer-asserted caller context is forwarded without verification.
+* Unknown names and handler throws resolve to error results; a call whose `id` or `name`
+* accessor throws when read makes its call, and the batch holding it, reject. Batch
+* execution preserves input order and isolates each call whose members are plain
+* values. Optional consumer-asserted caller context is forwarded without verification.
 *
 * @example
 * ```ts
@@ -109,7 +142,7 @@ var ToolManager = class {
 		return [...this.#tools.values()];
 	}
 	definitions() {
-		return [...this.#tools.values()].map((tool) => this.#definition(tool));
+		return [...this.#tools.values()].map((tool) => toolToDefinition(tool));
 	}
 	execute(call) {
 		if (isArray(call)) return Promise.all(call.map((one) => this.#run(one)));
@@ -117,8 +150,8 @@ var ToolManager = class {
 	}
 	remove(names) {
 		if (isArray(names)) {
-			let removed = false;
-			for (const name of names) if (this.#tools.delete(name)) removed = true;
+			let removed = true;
+			for (const name of names) if (!this.#tools.delete(name)) removed = false;
 			return removed;
 		}
 		return this.#tools.delete(names);
@@ -153,30 +186,34 @@ var ToolManager = class {
 			};
 		}
 	}
-	#definition(tool) {
-		const definition = { name: tool.name };
-		const description = tool.summary ?? tool.description;
-		if (description !== void 0) definition.description = description;
-		if (tool.parameters !== void 0) definition.parameters = tool.parameters;
-		return definition;
-	}
 };
 //#endregion
 //#region src/core/factories.ts
 /**
-* Create an executable tool.
+* Creates an executable tool bound to the supplied handler, returned as a
+* `ToolInterface` so a call site holds the published contract rather than the `Tool`
+* class.
 *
 * @param options - The advertised definition and execution handler
 * @returns A tool bound to the supplied handler
 *
-* @example
+* @example Anatomy of a tool
 * ```ts
 * import { createTool } from '@orkestrel/tool'
 *
 * const add = createTool({
 * 	name: 'add',
-* 	description: 'Add two numbers',
-* 	execute: (args) => Number(args.a) + Number(args.b),
+* 	description: 'Add two numeric values and return their sum. Both operands are required.',
+* 	summary: 'Add two numbers.',
+* 	parameters: {
+* 		type: 'object',
+* 		properties: {
+* 			left: { type: 'number' },
+* 			right: { type: 'number' },
+* 		},
+* 		required: ['left', 'right'],
+* 	},
+* 	execute: (args) => Number(args.left) + Number(args.right),
 * })
 * ```
 */
@@ -184,10 +221,11 @@ function createTool(options) {
 	return new Tool(options);
 }
 /**
-* Create an empty tool registry.
+* Creates an empty registry that advertises definitions and executes calls with
+* per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the
+* published contract rather than the `ToolManager` class.
 *
-* @returns A registry that advertises definitions and executes calls with per-call
-* error isolation
+* @returns A registry bound to no tools
 *
 * @example
 * ```ts
@@ -206,6 +244,6 @@ function createToolManager() {
 	return new ToolManager();
 }
 //#endregion
-export { Tool, ToolManager, createTool, createToolManager, isToolCall };
+export { Tool, ToolManager, createTool, createToolManager, isToolCall, toolToDefinition };
 
 //# sourceMappingURL=index.js.map

package/dist/src/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":["#execute","#tools","#definition","#run"],"sources":["../../../src/core/validators.ts","../../../src/core/tools/Tool.ts","../../../src/core/tools/ToolManager.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { ToolCall } from './types.js'\nimport { holds, isRecord, isString } from '@orkestrel/contract'\n\n/**\n * Determine whether an unknown value is structurally a {@link ToolCall}.\n *\n * @remarks\n * This total guard accepts a plain record with string `id` and `name` fields and a\n * plain-record `arguments` field. Optional caller context remains opaque and is not\n * read or verified. Adversarial values return `false`.\n *\n * @param value - The value to test\n * @returns `true` when the value has the complete tool-call shape\n *\n * @example\n * ```ts\n * import { isToolCall } from '@orkestrel/tool'\n *\n * isToolCall({ id: '1', name: 'search', arguments: { query: 'birds' } }) // true\n * isToolCall({ id: '1', name: 'search', arguments: [] }) // false\n * ```\n */\nexport function isToolCall(value: unknown): value is ToolCall {\n\treturn holds(\n\t\t() =>\n\t\t\tisRecord(value) && isString(value.id) && isString(value.name) && isRecord(value.arguments),\n\t)\n}\n","import type { ToolInterface, ToolOptions } from '../types.js'\n\n/**\n * An executable tool definition bound to a handler.\n *\n * @remarks\n * Schema fields, arguments, and present caller context are forwarded by reference.\n * Caller context is consumer-asserted and is not verified. Handler failures are not\n * caught here; {@link ToolManager} owns per-call error isolation.\n *\n * @example\n * ```ts\n * import { Tool } from '@orkestrel/tool'\n *\n * const tool = new Tool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: { a: { type: 'number' }, b: { type: 'number' } },\n * \t},\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport class Tool implements ToolInterface {\n\treadonly name: string\n\treadonly description?: string\n\treadonly summary?: string\n\treadonly parameters?: Readonly<Record<string, unknown>>\n\treadonly #execute: (\n\t\targs: Readonly<Record<string, unknown>>,\n\t\tcaller?: unknown,\n\t) => Promise<unknown> | unknown\n\n\tconstructor(options: ToolOptions) {\n\t\tthis.name = options.name\n\t\tif (options.description !== undefined) this.description = options.description\n\t\tif (options.summary !== undefined) this.summary = options.summary\n\t\tif (options.parameters !== undefined) this.parameters = options.parameters\n\t\tthis.#execute = options.execute\n\t}\n\n\texecute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown {\n\t\tif (caller === undefined) return this.#execute(args)\n\t\treturn this.#execute(args, caller)\n\t}\n}\n","import type {\n\tToolCall,\n\tToolDefinition,\n\tToolInterface,\n\tToolManagerInterface,\n\tToolResult,\n} from '../types.js'\nimport { attempt, isArray } from '@orkestrel/contract'\n\n/**\n * An insertion-ordered tool registry with per-call error isolation.\n *\n * @remarks\n * A repeated name overwrites the registered tool without changing its insertion\n * position. Definitions advertise `summary` in place of `description` when present.\n * Unknown names and handler throws resolve to error results; batch execution preserves\n * input order and never fails as a whole because of an individual call. Optional\n * consumer-asserted caller context is forwarded without verification.\n *\n * @example\n * ```ts\n * import { Tool, ToolManager } from '@orkestrel/tool'\n *\n * const tools = new ToolManager()\n * tools.add(new Tool({ name: 'add', execute: (args) => Number(args.x) + Number(args.y) }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'add',\n * \targuments: { x: 1, y: 2 },\n * })\n * ```\n */\nexport class ToolManager implements ToolManagerInterface {\n\treadonly #tools = new Map<string, ToolInterface>()\n\n\tget count(): number {\n\t\treturn this.#tools.size\n\t}\n\n\tadd(tool: ToolInterface): void\n\tadd(tools: readonly ToolInterface[]): void\n\tadd(tools: ToolInterface | readonly ToolInterface[]): void {\n\t\tif (isArray(tools)) {\n\t\t\tfor (const tool of tools) this.#tools.set(tool.name, tool)\n\t\t\treturn\n\t\t}\n\t\tthis.#tools.set(tools.name, tools)\n\t}\n\n\ttool(name: string): ToolInterface | undefined {\n\t\treturn this.#tools.get(name)\n\t}\n\n\ttools(): readonly ToolInterface[] {\n\t\treturn [...this.#tools.values()]\n\t}\n\n\tdefinitions(): readonly ToolDefinition[] {\n\t\treturn [...this.#tools.values()].map((tool) => this.#definition(tool))\n\t}\n\n\texecute(call: ToolCall): Promise<ToolResult>\n\texecute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>\n\texecute(call: ToolCall | readonly ToolCall[]): Promise<ToolResult | readonly ToolResult[]> {\n\t\tif (isArray(call)) return Promise.all(call.map((one) => this.#run(one)))\n\t\treturn this.#run(call)\n\t}\n\n\tremove(name: string): boolean\n\tremove(names: readonly string[]): boolean\n\tremove(names: string | readonly string[]): boolean {\n\t\tif (isArray(names)) {\n\t\t\tlet removed = false\n\t\t\tfor (const name of names) {\n\t\t\t\tif (this.#tools.delete(name)) removed = true\n\t\t\t}\n\t\t\treturn removed\n\t\t}\n\t\treturn this.#tools.delete(names)\n\t}\n\n\tclear(): void {\n\t\tthis.#tools.clear()\n\t}\n\n\tasync #run(call: ToolCall): Promise<ToolResult> {\n\t\tconst tool = this.#tools.get(call.name)\n\t\tif (tool === undefined) {\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `tool not found: ${call.name}`,\n\t\t\t}\n\t\t}\n\t\ttry {\n\t\t\tconst caller = call.caller\n\t\t\tconst value = await (caller === undefined\n\t\t\t\t? tool.execute(call.arguments)\n\t\t\t\t: tool.execute(call.arguments, caller))\n\t\t\treturn { id: call.id, name: call.name, success: true, value }\n\t\t} catch (error) {\n\t\t\tconst message = attempt(() =>\n\t\t\t\terror instanceof Error ? String(error.message) : String(error),\n\t\t\t)\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: message.success ? message.value : 'Unknown thrown value',\n\t\t\t}\n\t\t}\n\t}\n\n\t#definition(tool: ToolInterface): ToolDefinition {\n\t\tconst definition: {\n\t\t\tname: string\n\t\t\tdescription?: string\n\t\t\tparameters?: Readonly<Record<string, unknown>>\n\t\t} = {\n\t\t\tname: tool.name,\n\t\t}\n\t\tconst description = tool.summary ?? tool.description\n\t\tif (description !== undefined) definition.description = description\n\t\tif (tool.parameters !== undefined) definition.parameters = tool.parameters\n\t\treturn definition\n\t}\n}\n","import type { ToolInterface, ToolManagerInterface, ToolOptions } from './types.js'\nimport { Tool } from './tools/Tool.js'\nimport { ToolManager } from './tools/ToolManager.js'\n\n/**\n * Create an executable tool.\n *\n * @param options - The advertised definition and execution handler\n * @returns A tool bound to the supplied handler\n *\n * @example\n * ```ts\n * import { createTool } from '@orkestrel/tool'\n *\n * const add = createTool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport function createTool(options: ToolOptions): ToolInterface {\n\treturn new Tool(options)\n}\n\n/**\n * Create an empty tool registry.\n *\n * @returns A registry that advertises definitions and executes calls with per-call\n * error isolation\n *\n * @example\n * ```ts\n * import { createTool, createToolManager } from '@orkestrel/tool'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'echo', execute: (args) => args.value }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'echo',\n * \targuments: { value: 'hello' },\n * })\n * ```\n */\nexport function createToolManager(): ToolManagerInterface {\n\treturn new ToolManager()\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,WAAW,OAAmC;CAC7D,OAAO,YAEL,SAAS,KAAK,KAAK,SAAS,MAAM,EAAE,KAAK,SAAS,MAAM,IAAI,KAAK,SAAS,MAAM,SAAS,CAC3F;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;ACFA,IAAa,OAAb,MAA2C;CAC1C;CACA;CACA;CACA;CACA;CAKA,YAAY,SAAsB;EACjC,KAAK,OAAO,QAAQ;EACpB,IAAI,QAAQ,gBAAgB,KAAA,GAAW,KAAK,cAAc,QAAQ;EAClE,IAAI,QAAQ,YAAY,KAAA,GAAW,KAAK,UAAU,QAAQ;EAC1D,IAAI,QAAQ,eAAe,KAAA,GAAW,KAAK,aAAa,QAAQ;EAChE,KAAKA,WAAW,QAAQ;CACzB;CAEA,QAAQ,MAAyC,QAA8C;EAC9F,IAAI,WAAW,KAAA,GAAW,OAAO,KAAKA,SAAS,IAAI;EACnD,OAAO,KAAKA,SAAS,MAAM,MAAM;CAClC;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;ACfA,IAAa,cAAb,MAAyD;CACxD,yBAAkB,IAAI,IAA2B;CAEjD,IAAI,QAAgB;EACnB,OAAO,KAAKC,OAAO;CACpB;CAIA,IAAI,OAAuD;EAC1D,IAAI,QAAQ,KAAK,GAAG;GACnB,KAAK,MAAM,QAAQ,OAAO,KAAKA,OAAO,IAAI,KAAK,MAAM,IAAI;GACzD;EACD;EACA,KAAKA,OAAO,IAAI,MAAM,MAAM,KAAK;CAClC;CAEA,KAAK,MAAyC;EAC7C,OAAO,KAAKA,OAAO,IAAI,IAAI;CAC5B;CAEA,QAAkC;EACjC,OAAO,CAAC,GAAG,KAAKA,OAAO,OAAO,CAAC;CAChC;CAEA,cAAyC;EACxC,OAAO,CAAC,GAAG,KAAKA,OAAO,OAAO,CAAC,CAAC,CAAC,KAAK,SAAS,KAAKC,YAAY,IAAI,CAAC;CACtE;CAIA,QAAQ,MAAmF;EAC1F,IAAI,QAAQ,IAAI,GAAG,OAAO,QAAQ,IAAI,KAAK,KAAK,QAAQ,KAAKC,KAAK,GAAG,CAAC,CAAC;EACvE,OAAO,KAAKA,KAAK,IAAI;CACtB;CAIA,OAAO,OAA4C;EAClD,IAAI,QAAQ,KAAK,GAAG;GACnB,IAAI,UAAU;GACd,KAAK,MAAM,QAAQ,OAClB,IAAI,KAAKF,OAAO,OAAO,IAAI,GAAG,UAAU;GAEzC,OAAO;EACR;EACA,OAAO,KAAKA,OAAO,OAAO,KAAK;CAChC;CAEA,QAAc;EACb,KAAKA,OAAO,MAAM;CACnB;CAEA,MAAME,KAAK,MAAqC;EAC/C,MAAM,OAAO,KAAKF,OAAO,IAAI,KAAK,IAAI;EACtC,IAAI,SAAS,KAAA,GACZ,OAAO;GACN,IAAI,KAAK;GACT,MAAM,KAAK;GACX,SAAS;GACT,OAAO,mBAAmB,KAAK;EAChC;EAED,IAAI;GACH,MAAM,SAAS,KAAK;GACpB,MAAM,QAAQ,OAAO,WAAW,KAAA,IAC7B,KAAK,QAAQ,KAAK,SAAS,IAC3B,KAAK,QAAQ,KAAK,WAAW,MAAM;GACtC,OAAO;IAAE,IAAI,KAAK;IAAI,MAAM,KAAK;IAAM,SAAS;IAAM;GAAM;EAC7D,SAAS,OAAO;GACf,MAAM,UAAU,cACf,iBAAiB,QAAQ,OAAO,MAAM,OAAO,IAAI,OAAO,KAAK,CAC9D;GACA,OAAO;IACN,IAAI,KAAK;IACT,MAAM,KAAK;IACX,SAAS;IACT,OAAO,QAAQ,UAAU,QAAQ,QAAQ;GAC1C;EACD;CACD;CAEA,YAAY,MAAqC;EAChD,MAAM,aAIF,EACH,MAAM,KAAK,KACZ;EACA,MAAM,cAAc,KAAK,WAAW,KAAK;EACzC,IAAI,gBAAgB,KAAA,GAAW,WAAW,cAAc;EACxD,IAAI,KAAK,eAAe,KAAA,GAAW,WAAW,aAAa,KAAK;EAChE,OAAO;CACR;AACD;;;;;;;;;;;;;;;;;;;;AC1GA,SAAgB,WAAW,SAAqC;CAC/D,OAAO,IAAI,KAAK,OAAO;AACxB;;;;;;;;;;;;;;;;;;;;AAqBA,SAAgB,oBAA0C;CACzD,OAAO,IAAI,YAAY;AACxB"}
+{"version":3,"file":"index.js","names":[],"sources":["../../../src/core/helpers.ts","../../../src/core/validators.ts","../../../src/core/tools/Tool.ts","../../../src/core/tools/ToolManager.ts","../../../src/core/factories.ts"],"sourcesContent":["import type { ToolDefinition, ToolInterface } from './types.js'\n\n/**\n * Projects a tool onto the plain definition advertised to a caller, advertising an\n * authored `summary` in place of the full description and carrying the parameter schema\n * by reference.\n *\n * @remarks\n * The projection is a fresh object carrying `name`, then `description` only when the\n * tool authored a summary or a description, then `parameters` only when the tool\n * authored a schema. The full `description` stays on the tool for direct lookup, and\n * the definition is never a live handle on the tool's handler.\n *\n * @param tool - The tool to project\n * @returns A fresh definition carrying only the fields the tool authored\n *\n * @example\n * ```ts\n * import { Tool, toolToDefinition } from '@orkestrel/tool'\n *\n * const echo = new Tool({ name: 'echo', summary: 'Echo a value.', execute: (args) => args.value })\n * toolToDefinition(echo) // { name: 'echo', description: 'Echo a value.' }\n * ```\n */\nexport function toolToDefinition(tool: ToolInterface): ToolDefinition {\n\tconst definition: {\n\t\tname: string\n\t\tdescription?: string\n\t\tparameters?: Readonly<Record<string, unknown>>\n\t} = {\n\t\tname: tool.name,\n\t}\n\tconst description = tool.summary ?? tool.description\n\tif (description !== undefined) definition.description = description\n\tif (tool.parameters !== undefined) definition.parameters = tool.parameters\n\treturn definition\n}\n","import type { ToolCall } from './types.js'\nimport { holds, isRecord, isString } from '@orkestrel/contract'\n\n/**\n * Determines whether an unknown value is structurally a {@link ToolCall}, staying total\n * for malformed and adversarial input.\n *\n * @remarks\n * The accepted shape is a plain record with string `id` and `name` fields and a\n * plain-record `arguments` field. Optional caller context remains opaque and is not\n * read or verified.\n *\n * @param value - The value to test\n * @returns True if the value has the complete tool-call shape; false otherwise\n *\n * @example\n * ```ts\n * import { isToolCall } from '@orkestrel/tool'\n *\n * isToolCall({ id: '1', name: 'search', arguments: { query: 'birds' } }) // true\n * isToolCall({ id: '1', name: 'search', arguments: [] }) // false\n * ```\n */\nexport function isToolCall(value: unknown): value is ToolCall {\n\treturn holds(\n\t\t() =>\n\t\t\tisRecord(value) && isString(value.id) && isString(value.name) && isRecord(value.arguments),\n\t)\n}\n","import type { ToolInterface, ToolOptions } from '../types.js'\n\n/**\n * Binds an executable tool definition to a handler.\n *\n * @remarks\n * Schema fields, arguments, and present caller context are forwarded by reference.\n * Caller context is consumer-asserted and is not verified. Handler failures are not\n * caught here; {@link ToolManager} owns per-call error isolation.\n *\n * @example\n * ```ts\n * import { Tool } from '@orkestrel/tool'\n *\n * const tool = new Tool({\n * \tname: 'add',\n * \tdescription: 'Add two numbers',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: { a: { type: 'number' }, b: { type: 'number' } },\n * \t},\n * \texecute: (args) => Number(args.a) + Number(args.b),\n * })\n * ```\n */\nexport class Tool implements ToolInterface {\n\treadonly name: string\n\treadonly description?: string\n\treadonly summary?: string\n\treadonly parameters?: Readonly<Record<string, unknown>>\n\treadonly #execute: (\n\t\targs: Readonly<Record<string, unknown>>,\n\t\tcaller?: unknown,\n\t) => Promise<unknown> | unknown\n\n\tconstructor(options: ToolOptions) {\n\t\tthis.name = options.name\n\t\tif (options.description !== undefined) this.description = options.description\n\t\tif (options.summary !== undefined) this.summary = options.summary\n\t\tif (options.parameters !== undefined) this.parameters = options.parameters\n\t\tthis.#execute = options.execute\n\t}\n\n\texecute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown {\n\t\tif (caller === undefined) return this.#execute(args)\n\t\treturn this.#execute(args, caller)\n\t}\n}\n","import type {\n\tToolCall,\n\tToolDefinition,\n\tToolInterface,\n\tToolManagerInterface,\n\tToolResult,\n} from '../types.js'\nimport { attempt, isArray } from '@orkestrel/contract'\nimport { toolToDefinition } from '../helpers.js'\n\n/**\n * Represents an insertion-ordered tool registry with per-call error isolation.\n *\n * @remarks\n * A repeated name overwrites the registered tool without changing its insertion\n * position. Definitions advertise `summary` in place of `description` when present.\n * Unknown names and handler throws resolve to error results; a call whose `id` or `name`\n * accessor throws when read makes its call, and the batch holding it, reject. Batch\n * execution preserves input order and isolates each call whose members are plain\n * values. Optional consumer-asserted caller context is forwarded without verification.\n *\n * @example\n * ```ts\n * import { Tool, ToolManager } from '@orkestrel/tool'\n *\n * const tools = new ToolManager()\n * tools.add(new Tool({ name: 'add', execute: (args) => Number(args.x) + Number(args.y) }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'add',\n * \targuments: { x: 1, y: 2 },\n * })\n * ```\n */\nexport class ToolManager implements ToolManagerInterface {\n\treadonly #tools = new Map<string, ToolInterface>()\n\n\tget count(): number {\n\t\treturn this.#tools.size\n\t}\n\n\tadd(tool: ToolInterface): void\n\tadd(tools: readonly ToolInterface[]): void\n\tadd(tools: ToolInterface | readonly ToolInterface[]): void {\n\t\tif (isArray(tools)) {\n\t\t\tfor (const tool of tools) this.#tools.set(tool.name, tool)\n\t\t\treturn\n\t\t}\n\t\tthis.#tools.set(tools.name, tools)\n\t}\n\n\ttool(name: string): ToolInterface | undefined {\n\t\treturn this.#tools.get(name)\n\t}\n\n\ttools(): readonly ToolInterface[] {\n\t\treturn [...this.#tools.values()]\n\t}\n\n\tdefinitions(): readonly ToolDefinition[] {\n\t\treturn [...this.#tools.values()].map((tool) => toolToDefinition(tool))\n\t}\n\n\texecute(call: ToolCall): Promise<ToolResult>\n\texecute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>\n\texecute(call: ToolCall | readonly ToolCall[]): Promise<ToolResult | readonly ToolResult[]> {\n\t\tif (isArray(call)) return Promise.all(call.map((one) => this.#run(one)))\n\t\treturn this.#run(call)\n\t}\n\n\tremove(name: string): boolean\n\tremove(names: readonly string[]): boolean\n\tremove(names: string | readonly string[]): boolean {\n\t\tif (isArray(names)) {\n\t\t\tlet removed = true\n\t\t\tfor (const name of names) {\n\t\t\t\tif (!this.#tools.delete(name)) removed = false\n\t\t\t}\n\t\t\treturn removed\n\t\t}\n\t\treturn this.#tools.delete(names)\n\t}\n\n\tclear(): void {\n\t\tthis.#tools.clear()\n\t}\n\n\tasync #run(call: ToolCall): Promise<ToolResult> {\n\t\tconst tool = this.#tools.get(call.name)\n\t\tif (tool === undefined) {\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: `tool not found: ${call.name}`,\n\t\t\t}\n\t\t}\n\t\ttry {\n\t\t\tconst caller = call.caller\n\t\t\tconst value = await (caller === undefined\n\t\t\t\t? tool.execute(call.arguments)\n\t\t\t\t: tool.execute(call.arguments, caller))\n\t\t\treturn { id: call.id, name: call.name, success: true, value }\n\t\t} catch (error) {\n\t\t\tconst message = attempt(() =>\n\t\t\t\terror instanceof Error ? String(error.message) : String(error),\n\t\t\t)\n\t\t\treturn {\n\t\t\t\tid: call.id,\n\t\t\t\tname: call.name,\n\t\t\t\tsuccess: false,\n\t\t\t\terror: message.success ? message.value : 'Unknown thrown value',\n\t\t\t}\n\t\t}\n\t}\n}\n","import type { ToolInterface, ToolManagerInterface, ToolOptions } from './types.js'\nimport { Tool } from './tools/Tool.js'\nimport { ToolManager } from './tools/ToolManager.js'\n\n/**\n * Creates an executable tool bound to the supplied handler, returned as a\n * `ToolInterface` so a call site holds the published contract rather than the `Tool`\n * class.\n *\n * @param options - The advertised definition and execution handler\n * @returns A tool bound to the supplied handler\n *\n * @example Anatomy of a tool\n * ```ts\n * import { createTool } from '@orkestrel/tool'\n *\n * const add = createTool({\n * \tname: 'add',\n * \tdescription: 'Add two numeric values and return their sum. Both operands are required.',\n * \tsummary: 'Add two numbers.',\n * \tparameters: {\n * \t\ttype: 'object',\n * \t\tproperties: {\n * \t\t\tleft: { type: 'number' },\n * \t\t\tright: { type: 'number' },\n * \t\t},\n * \t\trequired: ['left', 'right'],\n * \t},\n * \texecute: (args) => Number(args.left) + Number(args.right),\n * })\n * ```\n */\nexport function createTool(options: ToolOptions): ToolInterface {\n\treturn new Tool(options)\n}\n\n/**\n * Creates an empty registry that advertises definitions and executes calls with\n * per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the\n * published contract rather than the `ToolManager` class.\n *\n * @returns A registry bound to no tools\n *\n * @example\n * ```ts\n * import { createTool, createToolManager } from '@orkestrel/tool'\n *\n * const tools = createToolManager()\n * tools.add(createTool({ name: 'echo', execute: (args) => args.value }))\n * const result = await tools.execute({\n * \tid: '1',\n * \tname: 'echo',\n * \targuments: { value: 'hello' },\n * })\n * ```\n */\nexport function createToolManager(): ToolManagerInterface {\n\treturn new ToolManager()\n}\n"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@orkestrel/tool",
-	"version": "0.0.12",
+	"version": "0.0.14",
 	"description": "The tool runtime for the @orkestrel line — JSON-Schema tool definitions, calls, results, executable tools, and a registry with per-call error isolation. Part of the @orkestrel line.",
 	"keywords": [
 		"agent",
@@ -45,40 +45,43 @@
 		"clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
 		"copy": "node -e \"const fs=require('node:fs'),p=require('node:path'),a=process.argv[1],b=process.argv[2];fs.mkdirSync(p.dirname(b),{recursive:true});fs.cpSync(a,b,{force:true});console.log('Copied: '+a+' to '+b)\"",
 		"scaffold": "scaffold",
-		"lint": "oxlint --config .oxlintrc.json --fix --deny-warnings .",
+		"lint": "oxlint --config .oxlintrc.json --fix .",
 		"check": "tsc --noEmit --project tsconfig.json && npm run check:src",
 		"check:src": "npm run check:src:core",
 		"check:src:core": "tsc --noEmit -p configs/src/tsconfig.core.json",
 		"format": "oxfmt --config .oxfmtrc.json --write .",
 		"format:check": "oxfmt --config .oxfmtrc.json --check .",
 		"lint:check": "oxlint --config .oxlintrc.json --deny-warnings .",
-		"test": "npm run test:src && npm run test:policy && npm run test:config && npm run test:guides",
+		"test": "npm run test:src && npm run test:policy && npm run test:config && npm run test:setup && npm run test:guides",
 		"test:src": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:src:core": "vitest run --config vite.config.ts --no-cache --reporter=dot --project src:core",
 		"test:policy": "vitest run --config vite.config.ts --no-cache --reporter=dot --project policy",
 		"test:config": "vitest run --config vite.config.ts --no-cache --reporter=dot --project config",
-		"test:guides": "vitest run --config vite.config.ts --reporter=dot --project guides",
+		"test:guides": "node --experimental-strip-types tests/guides.test.ts",
 		"build": "npm run clean && npm run build:src",
 		"build:src": "npm run build:src:core",
 		"build:src:core": "vite build --config configs/src/vite.core.config.ts && npm run copy dist/src/core/index.d.ts dist/src/core/index.d.cts",
-		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test"
+		"prepublishOnly": "npm run format:check && npm run lint:check && npm run check && npm run build && npm test && npm run test:distribution -- --mode release",
+		"test:distribution": "vitest run --config vite.config.ts --no-cache --reporter=dot --project distribution",
+		"test:probe": "vitest run --config vite.config.ts --no-cache --reporter=verbose --project probe",
+		"test:bench": "vitest bench --config vite.config.ts --no-cache --project probe",
+		"prepack": "npm run build",
+		"test:setup": "vitest run --config vite.config.ts --no-cache --reporter=dot --project setup"
 	},
 	"dependencies": {
-		"@orkestrel/contract": "^0.0.13"
+		"@orkestrel/contract": "^0.0.17"
 	},
 	"devDependencies": {
 		"@microsoft/api-extractor": "^7.59.0",
-		"@orkestrel/guide": "^0.0.12",
-		"@orkestrel/probe": "^0.0.3",
-		"@orkestrel/scaffold": "^0.0.49",
-		"@orkestrel/test": "^0.0.11",
-		"@types/node": "^26.2.0",
-		"@vitest/browser-playwright": "^4.1.11",
-		"oxfmt": "^0.64.0",
-		"oxlint": "^1.79.0",
+		"@orkestrel/guide": "^0.0.17",
+		"@orkestrel/probe": "^0.0.12",
+		"@orkestrel/scaffold": "^0.0.63",
+		"@orkestrel/test": "^0.0.14",
+		"@types/node": "^26.4.1",
+		"oxfmt": "^0.66.0",
+		"oxlint": "^1.81.0",
 		"typescript": "^6.0.3",
 		"vite": "^8.2.2",
-		"vite-plugin-dts": "^5.0.3",
 		"vitest": "^4.1.11"
 	},
 	"engines": {