@orkestrel/tool 0.0.4 → 0.0.5

package/dist/src/core/index.cjs

@@ -560,12 +560,11 @@ var INFER_TOOL_DESCRIPTION = [
 */
 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;
 	}
 };
 /**
@@ -1544,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(".");
@@ -1564,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;
 }
@@ -1592,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 });
 }
 /**
@@ -1820,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
@@ -1935,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 {
@@ -2040,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)) {
@@ -2129,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") {
@@ -2164,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();
@@ -2271,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;
@@ -2343,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);
@@ -2398,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", {
@@ -2500,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) => ({
@@ -2633,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 });
@@ -2674,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}'`, {
@@ -2689,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,
@@ -2704,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 {
@@ -2715,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;
@@ -2734,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];
@@ -2759,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;
@@ -2778,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,
@@ -2793,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);
@@ -2877,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 {
@@ -3028,8 +3133,8 @@ function createInferTool(options) {
 		name: options?.name ?? "infer",
 		description: options?.description ?? INFER_TOOL_DESCRIPTION,
 		summary: INFER_TOOL_SUMMARY,
-		parameters,
-		execute: async (args) => {
+		...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, {
@@ -3136,15 +3241,17 @@ function createEndpointTool(definition, options) {
 	if (!(options?.validate ?? true)) return (0, _orkestrel_agent.createTool)({
 		name: definition.name,
 		description: definition.description,
-		parameters,
-		execute: (args) => definition.invoke(args)
+		...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,
-		execute: (args) => {
+		...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,
@@ -3172,6 +3279,7 @@ 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;