@orkestrel/tool 0.0.3 → 0.0.5

package/dist/src/core/index.cjs

@@ -425,6 +425,108 @@ var RELATION_TOOL_DESCRIPTION = [
 var RELATION_TOOL_LIMIT = 1e3;
 /** The default cap on how many `include` path segments deep a `load` / `find` call may traverse — the relation tool's default include-depth ceiling. */
 var RELATION_TOOL_DEPTH = 3;
+/**
+* The name {@link import('./factories.js').createInferTool} advertises by default — the key a
+* model calls and the `ToolManagerInterface` (`@orkestrel/agent`) registers under.
+*/
+var INFER_TOOL_NAME = "infer";
+/**
+* The lean {@link import('@orkestrel/agent').ToolInterface.summary} {@link import('./factories.js').createInferTool}
+* advertises in place of {@link INFER_TOOL_DESCRIPTION} — a `ToolManagerInterface.definitions()`
+* (`@orkestrel/agent`) advertises `summary ?? description`, so this one-sentence text stands in
+* for the full teaching description; the full text stays retrievable via
+* {@link import('./factories.js').createDescribeTool}.
+*/
+var INFER_TOOL_SUMMARY = "Infer a JSON Schema (as advertised tool parameters) from one or more example values. Call describe('infer') for the required fields.";
+var INFER_TOOL_DESCRIPTION = [
+	"Infer a JSON Schema from example values, returned in the same shape a tool advertises its parameters.",
+	"",
+	"Required:",
+	"  samples    - an array of at least one example value to infer the schema from.",
+	"Optional:",
+	"  format     - infer string formats (date-time, email, ...) from the samples. Defaults to false.",
+	"  enum       - infer enum constraints from repeated literal values across the samples. Defaults to false.",
+	"  candidates - values to check against the freshly inferred schema. When present, the result",
+	"               is wrapped as { parameters, checks } instead of the bare parameters record, one",
+	"               check per candidate (same index). Every check has the uniform shape",
+	"               { index, valid, coercible, faults? }. `valid` is a STRICT verdict (no coercion)",
+	"               — e.g. the number 7 is NOT valid against a string slot. `coercible` answers a",
+	"               separate question: would the SAME value be accepted by an endpoint tool call,",
+	"               whose enforcement NORMALIZES args (7 coerces to '7')? So 7 against a string slot",
+	"               yields { valid: false, coercible: true, faults: [] } — a strict mismatch that",
+	"               normalization would silently accept, so faults is EMPTY. `faults` only ever",
+	"               populates for a non-coercible mismatch (a wrong type normalization cannot fix,",
+	"               a missing required key, an out-of-enum value); checks never throw, regardless of",
+	"               candidate shape.",
+	"Example (no candidates):",
+	`  in:  ${JSON.stringify({ samples: [{
+		id: 1,
+		name: "Ada"
+	}, {
+		id: 2,
+		name: "Bob"
+	}] })}`,
+	`  out: ${JSON.stringify({
+		type: "object",
+		properties: {
+			id: { type: "integer" },
+			name: { type: "string" }
+		},
+		required: ["id", "name"],
+		additionalProperties: false
+	})}`,
+	"Example (with candidates):",
+	`  in:  ${JSON.stringify({
+		samples: [{
+			id: 1,
+			name: "Ada"
+		}],
+		candidates: [
+			{
+				id: 3,
+				name: "Cy"
+			},
+			{
+				id: "x",
+				name: "Cy"
+			},
+			{
+				id: 1,
+				name: 7
+			}
+		]
+	})}`,
+	`  out: ${JSON.stringify({
+		parameters: {
+			type: "object",
+			properties: {
+				id: { type: "integer" },
+				name: { type: "string" }
+			},
+			required: ["id", "name"],
+			additionalProperties: false
+		},
+		checks: [
+			{
+				index: 0,
+				valid: true,
+				coercible: true
+			},
+			{
+				index: 1,
+				valid: false,
+				coercible: false,
+				faults: "<structured faults>"
+			},
+			{
+				index: 2,
+				valid: false,
+				coercible: true,
+				faults: []
+			}
+		]
+	})}`
+].join("\n");
 //#endregion
 //#region src/core/errors.ts
 /**
@@ -458,12 +560,11 @@ var RELATION_TOOL_DEPTH = 3;
 */
 var AgentToolError = class extends Error {
 	code;
-	context;
 	constructor(code, message, context) {
 		super(message);
 		this.name = "AgentToolError";
 		this.code = code;
-		this.context = context;
+		if (context !== void 0) this.context = context;
 	}
 };
 /**
@@ -1106,6 +1207,28 @@ var relationToolShape = (0, _orkestrel_contract.unionShape)((0, _orkestrel_contr
 		description: "The \"through\" relation name."
 	})
 }));
+/**
+* The shape of {@link import('./factories.js').createInferTool}'s call arguments — one or more
+* example `samples` to infer a JSON Schema from, plus per-call `format` / `enum` toggles and an
+* optional `candidates` array to check against the inferred schema.
+*
+* @remarks
+* `samples` requires at least one element (`min: 1`) — an empty array parses to `undefined`,
+* surfaced by the handler as a typed `TOOL` {@link import('./errors.js').AgentToolError}. When
+* `candidates` is present (any array, including empty), the handler compiles a contract from the
+* freshly inferred schema and checks each candidate against it with a STRICT guard (`.is`, no
+* coercion) — the opposite of {@link import('./factories.js').createEndpointTool}'s NORMALIZING
+* `.parse` enforcement.
+*/
+var inferToolShape = (0, _orkestrel_contract.objectShape)({
+	samples: (0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), {
+		min: 1,
+		description: "The example values to infer a JSON Schema from (at least one)."
+	}),
+	format: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer string formats (date-time, email, ...) from the samples. Defaults to false." })),
+	enum: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.booleanShape)({ description: "Infer enum constraints from repeated literal values. Defaults to false." })),
+	candidates: (0, _orkestrel_contract.optionalShape)((0, _orkestrel_contract.arrayShape)((0, _orkestrel_contract.jsonShape)(), { description: "Optional values to check against the freshly inferred schema. When present, the tool returns a per-candidate verdict (strict — no coercion) alongside the inferred parameters." }))
+});
 //#endregion
 //#region src/core/helpers.ts
 /**
@@ -1420,19 +1543,6 @@ function relationToolCode(error) {
 * ```
 */
 function expandInclude(paths, depth) {
-	function merge(base, segments) {
-		const [head, ...rest] = segments;
-		const existing = base[head];
-		if (rest.length === 0) return {
-			...base,
-			[head]: existing === void 0 ? true : existing
-		};
-		const nextBase = typeof existing === "object" ? existing : {};
-		return {
-			...base,
-			[head]: merge(nextBase, rest)
-		};
-	}
 	let include = {};
 	for (const path of paths ?? []) {
 		const segments = path.split(".");
@@ -1440,7 +1550,42 @@ function expandInclude(paths, depth) {
 			path,
 			depth
 		});
-		include = merge(include, segments);
+		const ancestors = [];
+		let branch = include;
+		const last = segments.length - 1;
+		for (let index = 0; index < last; index++) {
+			const segment = segments[index];
+			if (segment === void 0) throw new AgentToolError("TOOL", `malformed include path '${path}'`, {
+				path,
+				depth
+			});
+			ancestors.push(branch);
+			const existing = branch[segment];
+			branch = typeof existing === "object" ? existing : {};
+		}
+		const leaf = segments[last];
+		if (leaf === void 0) throw new AgentToolError("TOOL", `malformed include path '${path}'`, {
+			path,
+			depth
+		});
+		const existing = branch[leaf];
+		let merged = {
+			...branch,
+			[leaf]: existing === void 0 ? true : existing
+		};
+		for (let index = last - 1; index >= 0; index--) {
+			const ancestor = ancestors[index];
+			const segment = segments[index];
+			if (ancestor === void 0 || segment === void 0) throw new AgentToolError("TOOL", `malformed include path '${path}'`, {
+				path,
+				depth
+			});
+			merged = {
+				...ancestor,
+				[segment]: merged
+			};
+		}
+		include = merged;
 	}
 	return include;
 }
@@ -1468,7 +1613,11 @@ function relationManagerOf(managers, name) {
 		return manager;
 	}
 	const names = Object.keys(managers);
-	if (names.length === 1) return managers[names[0]];
+	const [single] = names;
+	if (names.length === 1 && single !== void 0) {
+		const manager = managers[single];
+		if (manager !== void 0) return manager;
+	}
 	throw new AgentToolError("TOOL", "no relation manager resolved for the call", { managers: names });
 }
 /**
@@ -1696,6 +1845,105 @@ var DatabaseDefinitionStore = class {
 	}
 };
 //#endregion
+//#region src/core/databases/DatabaseResolver.ts
+/**
+* Resolve database definitions into cached live handles for database tools.
+*
+* @example
+* ```ts
+* import { DatabaseResolver } from '@orkestrel/tool'
+*
+* const resolver = new DatabaseResolver(handles, drivers, key, store)
+* const database = await resolver.resolve('shop')
+* ```
+*/
+var DatabaseResolver = class {
+	#handles;
+	#drivers;
+	#key;
+	#store;
+	/**
+	* Create a database resolver over the tool's live state and optional definition store.
+	*
+	* @param handles - Initial live database handles cached by id
+	* @param drivers - Driver factories keyed by definition driver name
+	* @param key - Key generator supplied to newly created databases
+	* @param store - Optional persistent definition store
+	*/
+	constructor(handles, drivers, key, store) {
+		this.#handles = new Map(handles);
+		this.#drivers = drivers;
+		this.#key = key;
+		this.#store = store;
+	}
+	/**
+	* Determine whether a live database is cached by id.
+	*
+	* @param id - Database id
+	* @returns Whether a live handle is cached
+	*/
+	has(id) {
+		return this.#handles.has(id);
+	}
+	/**
+	* Read a cached database without consulting the definition store.
+	*
+	* @param id - Database id
+	* @returns The cached live database, or `undefined`
+	*/
+	get(id) {
+		return this.#handles.get(id);
+	}
+	/**
+	* Cache a live database by id.
+	*
+	* @param id - Database id
+	* @param database - Live database handle
+	* @returns Nothing
+	*/
+	set(id, database) {
+		this.#handles.set(id, database);
+	}
+	/**
+	* Remove a cached live database by id.
+	*
+	* @param id - Database id
+	* @returns Nothing
+	*/
+	delete(id) {
+		this.#handles.delete(id);
+	}
+	/**
+	* Resolve a cached or stored database by id.
+	*
+	* @param id - Database definition id
+	* @returns The cached or newly constructed live database
+	*/
+	async resolve(id) {
+		const cached = this.#handles.get(id);
+		if (cached !== void 0) return cached;
+		if (this.#store !== void 0) {
+			const definition = await this.#store.get(id);
+			if (definition !== void 0) {
+				const factory = this.#drivers[definition.driver];
+				if (factory === void 0) throw new AgentToolError("TOOL", `unknown driver '${definition.driver}'`, {
+					id,
+					driver: definition.driver
+				});
+				const handle = (0, _orkestrel_database.createDatabase)({
+					driver: factory(),
+					tables: expandTables(definition.tables),
+					...definition.keys === void 0 ? {} : { keys: definition.keys },
+					key: this.#key
+				});
+				this.set(id, handle);
+				return handle;
+			}
+		}
+		throw new AgentToolError("TOOL", `unknown database '${id}'`, { id });
+	}
+};
+//#endregion
 //#region src/core/factories.ts
 /**
 * Wrap a registered tool as a {@link WorkflowFunction} (`@orkestrel/workflow`) — the OPT-IN
@@ -1811,7 +2059,9 @@ function createAgentFunction(agent, options) {
 			}));
 		}
 		const signal = controller.signal;
-		const onAbort = () => agent.abort(signal.reason);
+		const onAbort = { handleEvent() {
+			agent.abort(signal.reason);
+		} };
 		if (signal.aborted) agent.abort(signal.reason);
 		else signal.addEventListener("abort", onAbort, { once: true });
 		try {
@@ -1916,12 +2166,13 @@ function createWorkflowTool(definition, runner, options) {
 	const depth = options?.depth ?? 0;
 	const ancestry = options?.ancestry ?? [];
 	const store = options?.store;
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(steps.schema);
 	return (0, _orkestrel_agent.createTool)({
 		name: WORKFLOW_TOOL_NAME,
 		description: WORKFLOW_TOOL_DESCRIPTION,
 		summary: WORKFLOW_TOOL_SUMMARY,
-		parameters: (0, _orkestrel_contract.schemaToParameters)(steps.schema),
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			let target;
 			if (Object.keys(args).length === 0) target = definition;
 			else if (Array.isArray(args.steps)) {
@@ -2005,8 +2256,8 @@ function createWorkspaceTool(options) {
 		name: options?.name ?? "workspace",
 		description: options?.description ?? WORKSPACE_TOOL_DESCRIPTION,
 		summary: WORKSPACE_TOOL_SUMMARY,
-		parameters,
-		execute: (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		execute(args) {
 			const op = contract.parse(args);
 			if (op === void 0) throw new _orkestrel_agent.WorkspaceError("TOOL", `unknown or malformed operation`, { args });
 			if (op.operation === "workspaces") {
@@ -2040,14 +2291,14 @@ function createWorkspaceTool(options) {
 				}));
 				case "has": return active?.has(op.path) ?? false;
 				case "search": return active?.search(op.query, {
-					regex: op.regex,
-					exact: op.exact,
-					limit: op.limit
+					...op.regex === void 0 ? {} : { regex: op.regex },
+					...op.exact === void 0 ? {} : { exact: op.exact },
+					...op.limit === void 0 ? {} : { limit: op.limit }
 				}) ?? [];
 				case "replace": return (active ?? manager.add()).replace(op.query, op.replacement, {
-					regex: op.regex,
-					exact: op.exact,
-					limit: op.limit
+					...op.regex === void 0 ? {} : { regex: op.regex },
+					...op.exact === void 0 ? {} : { exact: op.exact },
+					...op.limit === void 0 ? {} : { limit: op.limit }
 				});
 				case "write": {
 					const workspace = active ?? manager.add();
@@ -2147,8 +2398,8 @@ function createAgentTool(registry, options) {
 		name: options?.name ?? "agent",
 		description: options?.description ?? AGENT_TOOL_DESCRIPTION,
 		summary: AGENT_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed agent-delegation call", { args });
 			const provider = call.provider ?? options?.provider;
@@ -2219,12 +2470,13 @@ function createAgentTool(registry, options) {
 */
 function createDescribeTool(tools) {
 	const contract = (0, _orkestrel_contract.createContract)(describeToolShape);
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	return (0, _orkestrel_agent.createTool)({
 		name: DESCRIBE_TOOL_NAME,
 		description: DESCRIBE_TOOL_DESCRIPTION,
 		summary: DESCRIBE_TOOL_SUMMARY,
-		parameters: (0, _orkestrel_contract.schemaToParameters)(contract.schema),
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed describe call", { args });
 			const tool = tools.tool(call.name);
@@ -2274,8 +2526,8 @@ function createPromptTool(options) {
 		name: options.name ?? "ask",
 		description: options.description ?? PROMPT_TOOL_DESCRIPTION,
 		summary: PROMPT_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed ask call", { args });
 			if ((call.form === "select" || call.form === "checkbox") && (call.choices ?? []).length === 0) throw new AgentToolError("TOOL", "select/checkbox requires at least one choice", {
@@ -2376,8 +2628,8 @@ function createAnswerTool(options) {
 		name: options.name ?? "answer",
 		description: options.description ?? ANSWER_TOOL_DESCRIPTION,
 		summary: ANSWER_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed answer call", { args });
 			if (call.operation === "pending") return options.manager.pending(options.to).map((prompt) => ({
@@ -2509,40 +2761,17 @@ function createDatabaseTool(options = {}) {
 	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	const handles = new Map(Object.entries(options.databases ?? {}));
 	const definitions = /* @__PURE__ */ new Map();
-	const drivers = options.drivers ?? { memory: () => (0, _orkestrel_database.createMemoryDriver)() };
+	const drivers = options.drivers ?? { memory: _orkestrel_database.createMemoryDriver };
 	const key = options.key ?? _orkestrel_database.generateUUID;
 	const cap = options.limit ?? 1e3;
 	const store = options.store;
-	async function resolve(id) {
-		const cached = handles.get(id);
-		if (cached !== void 0) return cached;
-		if (store !== void 0) {
-			const definition = await store.get(id);
-			if (definition !== void 0) {
-				const factory = drivers[definition.driver];
-				if (factory === void 0) throw new AgentToolError("TOOL", `unknown driver '${definition.driver}'`, {
-					id,
-					driver: definition.driver
-				});
-				const handle = (0, _orkestrel_database.createDatabase)({
-					driver: factory(),
-					tables: expandTables(definition.tables),
-					...definition.keys === void 0 ? {} : { keys: definition.keys },
-					key
-				});
-				handles.set(id, handle);
-				definitions.set(id, definition);
-				return handle;
-			}
-		}
-		throw new AgentToolError("TOOL", `unknown database '${id}'`, { id });
-	}
+	const resolver = store === void 0 ? new DatabaseResolver(handles, drivers, key) : new DatabaseResolver(handles, drivers, key, store);
 	return (0, _orkestrel_agent.createTool)({
 		name: options.name ?? "database",
 		description: options.description ?? DATABASE_TOOL_DESCRIPTION,
 		summary: DATABASE_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed database call", { args });
 			if (options.readonly === true && DATABASE_TOOL_MUTATIONS.has(call.operation)) throw new AgentToolError("TOOL", `operation '${call.operation}' is disabled in readonly mode`, { operation: call.operation });
@@ -2550,7 +2779,7 @@ function createDatabaseTool(options = {}) {
 			try {
 				switch (call.operation) {
 					case "create": {
-						if (handles.has(call.id) || store !== void 0 && await store.get(call.id) !== void 0) throw new AgentToolError("TOOL", `database '${call.id}' already exists`, { id: call.id });
+						if (resolver.has(call.id) || store !== void 0 && await store.get(call.id) !== void 0) throw new AgentToolError("TOOL", `database '${call.id}' already exists`, { id: call.id });
 						const name = call.driver ?? "memory";
 						const factory = drivers[name];
 						if (factory === void 0) throw new AgentToolError("TOOL", `unknown driver '${name}'`, {
@@ -2565,7 +2794,7 @@ function createDatabaseTool(options = {}) {
 							...keys === void 0 ? {} : { keys },
 							key
 						});
-						handles.set(call.id, handle);
+						resolver.set(call.id, handle);
 						const definition = {
 							id: call.id,
 							driver: name,
@@ -2580,7 +2809,7 @@ function createDatabaseTool(options = {}) {
 						};
 					}
 					case "tables": {
-						const handle = await resolve(call.id);
+						const handle = await resolver.resolve(call.id);
 						return { tables: Object.keys(handle.export()).map((name) => {
 							const table = handle.table(name);
 							return {
@@ -2591,14 +2820,14 @@ function createDatabaseTool(options = {}) {
 						}) };
 					}
 					case "get": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = Array.isArray(call.key);
 						const keys = Array.isArray(call.key) ? call.key : [call.key];
 						const rows = await table.get(keys);
 						return many ? { rows } : { row: rows[0] };
 					}
 					case "records": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const { criteria: probe, limit } = clampCriteria(criteriaOf(call.criteria), cap);
 						const rows = await table.records(probe, read);
 						const truncated = rows.length > limit;
@@ -2610,24 +2839,24 @@ function createDatabaseTool(options = {}) {
 							limit
 						};
 					}
-					case "count": return { count: await (await resolve(call.id)).table(call.table).count(criteriaOf(call.criteria), read) };
-					case "aggregate": return { value: await (await resolve(call.id)).table(call.table).aggregate(call.function, call.column, criteriaOf(call.criteria), read) };
+					case "count": return { count: await (await resolver.resolve(call.id)).table(call.table).count(criteriaOf(call.criteria), read) };
+					case "aggregate": return { value: await (await resolver.resolve(call.id)).table(call.table).aggregate(call.function, call.column, criteriaOf(call.criteria), read) };
 					case "add": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = Array.isArray(call.row);
 						const rows = Array.isArray(call.row) ? call.row : [call.row];
 						const keys = await table.add(rows, read);
 						return many ? { keys } : { key: keys[0] };
 					}
 					case "set": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = Array.isArray(call.row);
 						const rows = Array.isArray(call.row) ? call.row : [call.row];
 						const keys = await table.set(rows, read);
 						return many ? { keys } : { key: keys[0] };
 					}
 					case "update": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const changes = call.changes;
 						const many = Array.isArray(call.key);
 						const keys = Array.isArray(call.key) ? call.key : [call.key];
@@ -2635,14 +2864,14 @@ function createDatabaseTool(options = {}) {
 						return many ? { updated } : { updated: updated[0] };
 					}
 					case "remove": {
-						const table = (await resolve(call.id)).table(call.table);
+						const table = (await resolver.resolve(call.id)).table(call.table);
 						const many = Array.isArray(call.key);
 						const keys = Array.isArray(call.key) ? call.key : [call.key];
 						const removed = await table.remove(keys, read);
 						return many ? { removed } : { removed: removed[0] };
 					}
 					case "migrate": {
-						const handle = await resolve(call.id);
+						const handle = await resolver.resolve(call.id);
 						const previous = handle.export();
 						const deployed = Object.entries(previous).map(([name, table]) => tableSchema(name, table));
 						const tables = call.tables;
@@ -2654,8 +2883,8 @@ function createDatabaseTool(options = {}) {
 						const declared = expandTables(tables);
 						const migrated = handle.import(declared, Object.keys(keys).length > 0 ? keys : void 0);
 						const migration = await migrated.migrate(deployed, read);
-						handles.set(call.id, migrated);
-						const tracked = definitions.get(call.id);
+						resolver.set(call.id, migrated);
+						const tracked = definitions.get(call.id) ?? (store === void 0 ? void 0 : await store.get(call.id));
 						if (tracked !== void 0) {
 							const updated = {
 								id: call.id,
@@ -2669,11 +2898,11 @@ function createDatabaseTool(options = {}) {
 						return { migration };
 					}
 					case "destroy": {
-						const cached = handles.get(call.id);
+						const cached = resolver.get(call.id);
 						const persisted = store !== void 0 && cached === void 0 ? await store.get(call.id) !== void 0 : false;
 						if (cached !== void 0) {
 							await cached.close();
-							handles.delete(call.id);
+							resolver.delete(call.id);
 						}
 						definitions.delete(call.id);
 						if (store !== void 0) await store.delete(call.id);
@@ -2753,8 +2982,8 @@ function createRelationTool(options) {
 		name: options.name ?? "relation",
 		description: options.description ?? RELATION_TOOL_DESCRIPTION,
 		summary: RELATION_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
 			const call = contract.parse(args);
 			if (call === void 0) throw new AgentToolError("TOOL", "malformed relation call", { args });
 			try {
@@ -2820,6 +3049,218 @@ function createRelationTool(options) {
 		}
 	});
 }
+/**
+* Build a standalone LLM-callable tool that infers a JSON Schema from example values — the
+* utility half of the "existing API/DB → MCP tool" bridge (the other half,
+* {@link createEndpointTool}, wraps one CONCRETE endpoint).
+*
+* @remarks
+* The universal tool-handler contract (AGENTS §14): validates the call args against
+* {@link import('./shapers.js').inferToolShape} (`samples` non-empty, `format` / `enum` optional
+* booleans, `candidates` an optional array), infers a schema via `@orkestrel/contract`'s
+* `samplesToSchema`, wraps a non-object root as `{ value: <schema> }` via `schemaToObject` (mirrors
+* the tool-parameters convention every other `create*Tool` factory advertises), and RETURNS the
+* resulting parameters record. An empty `samples` array fails `inferToolShape`'s `min: 1` bound —
+* `contract.parse` returns `undefined` and the handler throws a typed `TOOL`
+* {@link import('./errors.js').AgentToolError}.
+*
+* When `candidates` is ABSENT, the return is the bare parameters record — unchanged from before
+* this array existed. When `candidates` is PRESENT (any array, including empty), the handler
+* compiles a SEPARATE per-call contract from the RAW inferred schema (via `@orkestrel/contract`'s
+* `schemaToShape`, NOT the `schemaToObject`-wrapped parameters — a bare-value sample checks a
+* bare-value candidate) and returns `{ parameters, checks }`, one check per candidate at the same
+* index. Every entry has a UNIFORM shape — `{ index, valid, coercible }`, with `faults` added ONLY
+* when `valid` is `false`: `valid` is the STRICT guard verdict (`checker.is(candidate)`), the
+* OPPOSITE of {@link createEndpointTool}'s enforcement, which coerces (`7` becomes `'7'` for a
+* string slot) — here a conformance report answers "does this value conform AS-IS": `7` against a
+* string slot is `valid: false`, full stop. `coercible` answers a SEPARATE question — "would the
+* NORMALIZING parse accept this value", i.e. would {@link createEndpointTool}'s default enforcement
+* admit it (`checker.parse(candidate) !== undefined`) — computed for every candidate regardless of
+* `valid`; by the house parse/guard round-trip guarantee (AGENTS §14), a `valid: true` entry is
+* ALWAYS also `coercible: true`. `@orkestrel/contract` 0.0.7's `explain` mirrors the normalizing
+* `parse`'s leniency, not `is`'s strictness — so a strictly-invalid but coercible candidate (`7`
+* against a string slot) yields `{ valid: false, coercible: true, faults: [] }`: EMPTY faults, since
+* the mismatch the normalizing parse would silently fix is not one `explain` reports. `faults`
+* therefore only ever populates for a NON-coercible mismatch — a wrong type the parse can't coerce
+* (a boolean in a string slot), a missing required key, or an out-of-enum value — where
+* `coercible: false`. `checker.is` / `.parse` / `.explain` are all total over JSON-safe input — a
+* JSON-safe hostile candidate (a `__proto__`-carrying object, deeply nested data) reaches all three
+* and yields a bounded, non-throwing per-candidate verdict; a NON-JSON-safe candidate (e.g. a
+* throwing-getter `Proxy`) never reaches the checker at all — it fails the OUTER `args` parse
+* against {@link import('./shapers.js').inferToolShape} and rejects the WHOLE call with the same
+* `TOOL` {@link import('./errors.js').AgentToolError} a malformed `samples`/`format`/`enum` throws,
+* with no per-candidate verdict produced.
+*
+* @param options - Advertised `name` / `description` overrides (see
+*   {@link import('./types.js').InferToolOptions})
+* @returns A `ToolInterface` (named {@link import('./constants.js').INFER_TOOL_NAME} by default)
+*
+* @example
+* ```ts
+* import { createInferTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tool = createInferTool()
+* const tools = createToolManager()
+* tools.add(tool)
+*
+* const result = await tools.execute({
+* 	id: 'call-1',
+* 	name: 'infer',
+* 	arguments: { samples: [{ id: 1, name: 'Ada' }, { id: 2, name: 'Bob' }] },
+* })
+* // result.value -> { type: 'object', properties: { id: {...}, name: {...} }, ... }
+*
+* // with candidates, the result is wrapped with per-candidate verdicts
+* const checked = await tools.execute({
+* 	id: 'call-2',
+* 	name: 'infer',
+* 	arguments: {
+* 		samples: [{ id: 1, name: 'Ada' }],
+* 		candidates: [{ id: 2, name: 'Bob' }, { id: 'x', name: 'Cy' }],
+* 	},
+* })
+* // checked.value -> { parameters: {...}, checks: [
+* //   { index: 0, valid: true, coercible: true },
+* //   { index: 1, valid: false, coercible: false, faults: [...] },
+* // ] }
+* ```
+*/
+function createInferTool(options) {
+	const contract = (0, _orkestrel_contract.createContract)(inferToolShape);
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
+	return (0, _orkestrel_agent.createTool)({
+		name: options?.name ?? "infer",
+		description: options?.description ?? INFER_TOOL_DESCRIPTION,
+		summary: INFER_TOOL_SUMMARY,
+		...parameters === void 0 ? {} : { parameters },
+		async execute(args) {
+			const parsed = contract.parse(args);
+			if (parsed === void 0) throw new AgentToolError("TOOL", "malformed infer arguments", { args });
+			const schema = (0, _orkestrel_contract.samplesToSchema)(parsed.samples, {
+				format: parsed.format ?? false,
+				enum: parsed.enum ?? false
+			});
+			const result = (0, _orkestrel_contract.schemaToParameters)((0, _orkestrel_contract.schemaToObject)(schema));
+			if (result === void 0) throw new AgentToolError("TOOL", "could not infer a schema", { args });
+			if (parsed.candidates === void 0) return result;
+			const checker = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(schema));
+			return {
+				parameters: result,
+				checks: parsed.candidates.map((candidate, index) => {
+					const valid = checker.is(candidate);
+					const coercible = checker.parse(candidate) !== void 0;
+					return valid ? {
+						index,
+						valid,
+						coercible
+					} : {
+						index,
+						valid,
+						coercible,
+						faults: checker.explain(candidate)
+					};
+				})
+			};
+		}
+	});
+}
+/**
+* Wrap one CONCRETE endpoint ({@link import('./types.js').EndpointDefinition}) as an LLM-callable
+* `ToolInterface` — the endpoint half of the "existing API/DB → MCP tool" bridge (the other half,
+* {@link createInferTool}, is a standalone inference utility).
+*
+* @remarks
+* `parameters` is inferred ONCE at construction from `definition.samples` via
+* `@orkestrel/contract`'s `samplesToSchema` (tuned by {@link import('./types.js').EndpointToolOptions}'s
+* `format` / `enum`), wrapping a non-object root as `{ value: <schema> }` via `schemaToObject` —
+* the SAME object-rooted schema is both the ADVERTISED `parameters` and, by default
+* ({@link import('./types.js').EndpointToolOptions.validate} `true`), the ENFORCED contract:
+* `@orkestrel/contract` 0.0.7's `schemaToShape` compiles it ONCE (via `createContract`) into a
+* `ContractInterface` whose `.parse` runs on every call's `args` before `definition.invoke` — a
+* NORMALIZING parse, not a strict type check: a scalar is COERCED to its inferred type where the
+* house parsers coerce (a number to/from a numeric string, a boolean from `'1'`/`'0'`/`'true'`/
+* `'false'`/`1`/`0`), so `definition.invoke` receives the COERCED value (e.g. `7` sent for a
+* string slot arrives as `'7'`), not the raw call value. A call whose `args` fails to parse into
+* a record — a required key missing, or a value not coercible to its slot's type — THROWS a
+* typed `TOOL` {@link import('./errors.js').AgentToolError} carrying the compiled contract's
+* structured `explain` faults, and `definition.invoke` is never called. `format` annotations are
+* NEVER asserted, and a key outside the closed inferred schema is SILENTLY DROPPED rather than
+* rejected (see {@link import('./types.js').EndpointToolOptions.validate}). With
+* `validate: false`, `execute` PASSES THROUGH the model-supplied `args` to `definition.invoke`
+* WITHOUT re-validation — the pre-0.0.7 behavior, preserved as an explicit opt-out. Either way,
+* `invoke`'s return flows back as the tool call's plain result; a throw PROPAGATES uncaught,
+* isolated by the `ToolManagerInterface` (`@orkestrel/agent`) into the canonical error envelope
+* (AGENTS §14) — never caught or re-wrapped here.
+*
+* @param definition - The endpoint's identity, non-empty samples, and local handler (see
+*   {@link import('./types.js').EndpointDefinition})
+* @param options - Construction-time inference tuning + the validate opt-out (see
+*   {@link import('./types.js').EndpointToolOptions})
+* @returns A `ToolInterface` named `definition.name`
+*
+* @example
+* ```ts
+* import { createEndpointTool } from '@src/core'
+* import { createToolManager } from '@orkestrel/agent'
+*
+* const tool = createEndpointTool({
+* 	name: 'lookupUser',
+* 	description: 'Look up a user by id.',
+* 	samples: [{ id: '1', name: 'Ada' }, { id: '2', name: 'Bob' }],
+* 	invoke: (args) => ({ id: args.id, name: 'Ada' }),
+* })
+* const tools = createToolManager()
+* tools.add(tool)
+*
+* // conforming args (all required keys present) parse and reach `invoke`
+* const result = await tools.execute({
+* 	id: 'call-1',
+* 	name: 'lookupUser',
+* 	arguments: { id: '1', name: 'Ada' },
+* })
+* // result.value -> { id: '1', name: 'Ada' }
+*
+* // a nonconforming call (id is not coercible to the required string) is rejected before
+* // `invoke` runs
+* const rejected = await tools.execute({
+* 	id: 'call-2',
+* 	name: 'lookupUser',
+* 	arguments: { id: true, name: 'Ada' },
+* })
+* // rejected.error -> the TOOL AgentToolError message
+* ```
+*/
+function createEndpointTool(definition, options) {
+	if (definition.samples.length === 0) throw new AgentToolError("TOOL", "endpoint requires at least one sample", { name: definition.name });
+	const objectSchema = (0, _orkestrel_contract.schemaToObject)((0, _orkestrel_contract.samplesToSchema)(definition.samples, {
+		format: options?.format ?? false,
+		enum: options?.enum ?? false
+	}));
+	const parameters = (0, _orkestrel_contract.schemaToParameters)(objectSchema);
+	if (!(options?.validate ?? true)) return (0, _orkestrel_agent.createTool)({
+		name: definition.name,
+		description: definition.description,
+		...parameters === void 0 ? {} : { parameters },
+		execute(args) {
+			return definition.invoke(args);
+		}
+	});
+	const contract = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(objectSchema));
+	return (0, _orkestrel_agent.createTool)({
+		name: definition.name,
+		description: definition.description,
+		...parameters === void 0 ? {} : { parameters },
+		execute(args) {
+			const parsed = contract.parse(args);
+			if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new AgentToolError("TOOL", "malformed endpoint call arguments", {
+				name: definition.name,
+				faults: contract.explain(args)
+			});
+			return definition.invoke(parsed);
+		}
+	});
+}
 //#endregion
 exports.AGENT_TOOL_DEPTH = AGENT_TOOL_DEPTH;
 exports.AGENT_TOOL_DESCRIPTION = AGENT_TOOL_DESCRIPTION;
@@ -2838,6 +3279,10 @@ exports.DESCRIBE_TOOL_DESCRIPTION = DESCRIBE_TOOL_DESCRIPTION;
 exports.DESCRIBE_TOOL_NAME = DESCRIBE_TOOL_NAME;
 exports.DESCRIBE_TOOL_SUMMARY = DESCRIBE_TOOL_SUMMARY;
 exports.DatabaseDefinitionStore = DatabaseDefinitionStore;
+exports.DatabaseResolver = DatabaseResolver;
+exports.INFER_TOOL_DESCRIPTION = INFER_TOOL_DESCRIPTION;
+exports.INFER_TOOL_NAME = INFER_TOOL_NAME;
+exports.INFER_TOOL_SUMMARY = INFER_TOOL_SUMMARY;
 exports.MAX_WORKFLOW_DEPTH = MAX_WORKFLOW_DEPTH;
 exports.MemoryDefinitionStore = MemoryDefinitionStore;
 exports.PROMPT_TOOL_DESCRIPTION = PROMPT_TOOL_DESCRIPTION;
@@ -2876,6 +3321,8 @@ exports.createAnswerTool = createAnswerTool;
 exports.createDatabaseDefinitionStore = createDatabaseDefinitionStore;
 exports.createDatabaseTool = createDatabaseTool;
 exports.createDescribeTool = createDescribeTool;
+exports.createEndpointTool = createEndpointTool;
+exports.createInferTool = createInferTool;
 exports.createMemoryDefinitionStore = createMemoryDefinitionStore;
 exports.createPromptTool = createPromptTool;
 exports.createRelationTool = createRelationTool;
@@ -2892,6 +3339,7 @@ exports.expandInclude = expandInclude;
 exports.expandSteps = expandSteps;
 exports.expandTables = expandTables;
 exports.includeShape = includeShape;
+exports.inferToolShape = inferToolShape;
 exports.isAgentToolError = isAgentToolError;
 exports.isColumnKind = isColumnKind;
 exports.isColumnSpec = isColumnSpec;