@orkestrel/toolbox 0.0.13 → 0.0.15

package/dist/src/core/index.cjs

@@ -591,7 +591,7 @@ var INFER_TOOL_DESCRIPTION = [
 * @remarks
 * Carries a machine-readable `code` (see {@link import('./types.js').ToolboxErrorCode}) and
 * an optional `context` bag for structured diagnostics. They are readable through an in-process
-* catch, including around a direct `tool.execute(args)` call. The `ToolManagerInterface`
+* catch, including around a direct `tool.execute(args, context)` call. The `ToolManagerInterface`
 * (`@orkestrel/tool`) instead flattens every throw to the canonical tool result's top-level
 * `error` message string under AGENTS' “narrow untrusted input with guards” rule.
 *
@@ -633,7 +633,7 @@ var ToolboxError = class extends Error {
 * ```
 */
 function isToolboxError(value) {
-	return value instanceof ToolboxError;
+	return (0, _orkestrel_contract.isInstance)(value, ToolboxError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -645,7 +645,7 @@ function isToolboxError(value) {
 */
 function isWorkflowLineage(value) {
 	const inspected = (0, _orkestrel_contract.attempt)(() => {
-		if (!Array.isArray(value)) return false;
+		if (!(0, _orkestrel_contract.isArray)(value)) return false;
 		const seen = /* @__PURE__ */ new Set();
 		for (const [index, tag] of value.entries()) {
 			if (!(0, _orkestrel_contract.isString)(tag)) return false;
@@ -665,7 +665,7 @@ function isWorkflowLineage(value) {
 */
 function isAgentFunction(value) {
 	const inspected = (0, _orkestrel_contract.attempt)(() => {
-		if (typeof value !== "function" || !Object.isFrozen(value)) return false;
+		if (!(0, _orkestrel_contract.isFunction)(value) || !Object.isFrozen(value)) return false;
 		const category = Reflect.getOwnPropertyDescriptor(value, "category");
 		const lineage = Reflect.getOwnPropertyDescriptor(value, "lineage");
 		return category?.value === "agent" && lineage !== void 0 && "value" in lineage && Object.isFrozen(lineage.value) && isWorkflowLineage(lineage.value);
@@ -681,7 +681,7 @@ function isAgentFunction(value) {
 function isColumnSpec(value) {
 	if (isColumnPrimitive(value)) return true;
 	if (!(0, _orkestrel_contract.isRecord)(value)) return false;
-	return isColumnPrimitive(value.primitive) && (value.optional === void 0 || typeof value.optional === "boolean");
+	return isColumnPrimitive(value.primitive) && (value.optional === void 0 || (0, _orkestrel_contract.isBoolean)(value.optional));
 }
 /**
 * Narrows an unknown value to a {@link ColumnPrimitive}.
@@ -689,9 +689,7 @@ function isColumnSpec(value) {
 * @param value - The value to inspect
 * @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
 */
-function isColumnPrimitive(value) {
-	return value === "string" || value === "integer" || value === "number" || value === "boolean";
-}
+var isColumnPrimitive = (0, _orkestrel_contract.literalOf)("string", "integer", "number", "boolean");
 /**
 * Narrows an unknown value to a {@link DatabaseDefinition} — a non-empty `id` and `driver`, a
 * `tables` record whose every value is `{ columns: record of valid ColumnSpec }`, plus optional
@@ -718,9 +716,9 @@ function isDatabaseDefinition(value) {
 	if (value.indexes !== void 0) {
 		if (!(0, _orkestrel_contract.isRecord)(value.indexes)) return false;
 		for (const groups of Object.values(value.indexes)) {
-			if (!Array.isArray(groups)) return false;
+			if (!(0, _orkestrel_contract.isArray)(groups)) return false;
 			for (const group of groups) {
-				if (!Array.isArray(group) || group.length === 0) return false;
+				if (!(0, _orkestrel_contract.isArray)(group) || group.length === 0) return false;
 				for (const column of group) if (!(0, _orkestrel_contract.isNonEmptyString)(column)) return false;
 			}
 		}
@@ -1576,7 +1574,7 @@ function expandInclude(paths, depth) {
 			});
 			ancestors.push(branch);
 			const existing = branch[segment];
-			branch = typeof existing === "object" ? existing : {};
+			branch = (0, _orkestrel_contract.isObject)(existing) ? existing : {};
 		}
 		const leaf = segments[last];
 		if (leaf === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
@@ -2059,7 +2057,9 @@ var DatabaseResolver = class {
 * (`{ publish: createToolFunction(tools, 'publish') }`); the pure workflow runner has no
 * knowledge of tools itself. The returned function executes `name` against `tools` with the
 * task's `controller.input` as the call arguments. The adapter resolves the live tool, calls its
-* `execute` method directly, and deep-gates the returned unknown through `parseJSONValue`.
+* `execute` method directly, and deep-gates the returned unknown through `parseJSONValue`. The
+* execution context it passes carries the task's own `controller.signal`, so a handler that
+* reads `context.signal` observes the caller's cancellation.
 * Genuine execution throws retain identity. An unregistered name or non-JSON return throws this
 * package's typed `TOOL` `ToolboxError`.
 *
@@ -2084,7 +2084,7 @@ function createToolFunction(tools, name) {
 	return async (controller) => {
 		const tool = tools.tool(name);
 		if (tool === void 0) throw new ToolboxError("TOOL", `tool '${name}' is not registered`, { tool: name });
-		const result = (0, _orkestrel_contract.parseJSONValue)(await tool.execute(controller.input));
+		const result = (0, _orkestrel_contract.parseJSONValue)(await tool.execute(controller.input, { signal: controller.signal }));
 		if (result === void 0) throw new ToolboxError("TOOL", `tool '${name}' returned a non-JSON value`, { tool: name });
 		return result;
 	};
@@ -2209,7 +2209,7 @@ function createWorkflowFunctions(runner, options) {
 	const composed = {};
 	Object.setPrototypeOf(composed, null);
 	for (const [name, fn] of Object.entries(functions)) {
-		if (typeof fn !== "function") throw new ToolboxError("TOOL", `workflow function '${name}' is not callable`, { function: name });
+		if (!(0, _orkestrel_contract.isFunction)(fn)) throw new ToolboxError("TOOL", `workflow function '${name}' is not callable`, { function: name });
 		if (isAgentFunction(fn)) throw new ToolboxError("TOOL", `agent function '${name}' must be supplied through agents`, { function: name });
 		composed[name] = fn;
 	}
@@ -2338,7 +2338,7 @@ function createWorkflowTool(definition, runner, options) {
 			const owned = cloned.value;
 			let target;
 			if (Object.keys(owned).length === 0) target = definition;
-			else if (Array.isArray(owned.steps)) {
+			else if ((0, _orkestrel_contract.isArray)(owned.steps)) {
 				const flat = steps.parse(owned);
 				target = flat === void 0 ? void 0 : expandSteps(flat);
 			} else {
@@ -2886,15 +2886,18 @@ function createDatabaseDefinitionStore(driver = (0, _orkestrel_database.createMe
 * import { createDatabaseTool } from '@src/core'
 *
 * const tool = createDatabaseTool()
-* await tool.execute({
-* 	operation: 'create',
-* 	id: 'shop',
-* 	tables: { products: { columns: { name: 'string', price: 'number' } } },
-* })
+* await tool.execute(
+* 	{
+* 		operation: 'create',
+* 		id: 'shop',
+* 		tables: { products: { columns: { name: 'string', price: 'number' } } },
+* 	},
+* 	{ signal: new AbortController().signal },
+* )
 * ```
 */
 function createDatabaseTool(options = {}) {
-	if (options.timeout !== void 0 && (options.timeout < 0 || !Number.isSafeInteger(options.timeout))) throw new ToolboxError("TOOL", "database timeout must be a nonnegative safe integer", { timeout: options.timeout });
+	if (options.timeout !== void 0 && (options.timeout < 0 || !(0, _orkestrel_contract.isNumber)(options.timeout) || !Number.isSafeInteger(options.timeout))) throw new ToolboxError("TOOL", "database timeout must be a nonnegative safe integer", { timeout: options.timeout });
 	const contract = (0, _orkestrel_contract.createContract)(databaseToolShape);
 	const parameters = (0, _orkestrel_contract.schemaToParameters)(contract.schema);
 	const handles = new Map(Object.entries(options.databases ?? {}));
@@ -2964,8 +2967,8 @@ function createDatabaseTool(options = {}) {
 					}
 					case "get": {
 						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 many = (0, _orkestrel_contract.isArray)(call.key);
+						const keys = (0, _orkestrel_contract.isArray)(call.key) ? call.key : [call.key];
 						const rows = await table.get(keys);
 						return many ? { rows } : { row: rows[0] };
 					}
@@ -2986,30 +2989,30 @@ function createDatabaseTool(options = {}) {
 					case "aggregate": return { value: await (await resolver.resolve(call.id)).table(call.table).aggregate(call.function, call.column, normalizeQuery(call.query), read) };
 					case "add": {
 						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 many = (0, _orkestrel_contract.isArray)(call.row);
+						const rows = (0, _orkestrel_contract.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 resolver.resolve(call.id)).table(call.table);
-						const many = Array.isArray(call.row);
-						const rows = Array.isArray(call.row) ? call.row : [call.row];
+						const many = (0, _orkestrel_contract.isArray)(call.row);
+						const rows = (0, _orkestrel_contract.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 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];
+						const many = (0, _orkestrel_contract.isArray)(call.key);
+						const keys = (0, _orkestrel_contract.isArray)(call.key) ? call.key : [call.key];
 						const updated = await table.update(keys, changes, read);
 						return many ? { updated } : { updated: updated[0] };
 					}
 					case "remove": {
 						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 many = (0, _orkestrel_contract.isArray)(call.key);
+						const keys = (0, _orkestrel_contract.isArray)(call.key) ? call.key : [call.key];
 						const removed = await table.remove(keys, read);
 						return many ? { removed } : { removed: removed[0] };
 					}
@@ -3031,7 +3034,7 @@ function createDatabaseTool(options = {}) {
 				if (isToolboxError(error)) throw error;
 				const code = inferDatabaseCode(error);
 				if (code === void 0) throw error;
-				throw new ToolboxError("DATABASE", error instanceof Error ? error.message : String(error), {
+				throw new ToolboxError("DATABASE", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
 					code,
 					operation: call.operation,
 					id: call.id,
@@ -3086,7 +3089,10 @@ function createDatabaseTool(options = {}) {
 * import { createRelationTool } from '@src/core'
 *
 * const tool = createRelationTool({ managers: { shop: manager } })
-* await tool.execute({ operation: 'load', model: 'accounts', key: 'acc1', include: ['contacts'] })
+* await tool.execute(
+* 	{ operation: 'load', model: 'accounts', key: 'acc1', include: ['contacts'] },
+* 	{ signal: new AbortController().signal },
+* )
 * ```
 */
 function createRelationTool(options) {
@@ -3107,7 +3113,7 @@ function createRelationTool(options) {
 				switch (call.operation) {
 					case "load": {
 						const include = expandInclude(call.include, depth);
-						if (typeof call.key === "string" || typeof call.key === "number") return { row: await model.load(call.key, include) };
+						if ((0, _orkestrel_contract.isString)(call.key) || (0, _orkestrel_contract.isNumber)(call.key)) return { row: await model.load(call.key, include) };
 						return { rows: await model.load(call.key, include) };
 					}
 					case "find": {
@@ -3150,7 +3156,7 @@ function createRelationTool(options) {
 			} catch (error) {
 				if (isToolboxError(error)) throw error;
 				const relation = inferRelationCode(error);
-				if (relation !== void 0) throw new ToolboxError("RELATION", error instanceof Error ? error.message : String(error), {
+				if (relation !== void 0) throw new ToolboxError("RELATION", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
 					code: relation,
 					operation: call.operation,
 					model: call.model,
@@ -3158,7 +3164,7 @@ function createRelationTool(options) {
 				});
 				const database = inferDatabaseCode(error);
 				if (database === void 0) throw error;
-				throw new ToolboxError("DATABASE", error instanceof Error ? error.message : String(error), {
+				throw new ToolboxError("DATABASE", (0, _orkestrel_contract.isError)(error) ? error.message : String(error), {
 					code: database,
 					operation: call.operation
 				});
@@ -3305,8 +3311,10 @@ function createInferTool(options) {
 * 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`, the tool's `execute` passes through the model-supplied `args` to
-* `definition.execute` without re-validation — the raw-passthrough opt-out. Either way, the
-* definition's return flows back as the tool call's plain result; a throw propagates uncaught,
+* `definition.execute` without re-validation — the raw-passthrough opt-out. The execution context
+* the tool's `execute` receives reaches `definition.execute` unchanged whichever way `args` are
+* handled, so a handler that reads `context.signal` observes the caller's cancellation. Either way,
+* the definition's return flows back as the tool call's plain result; a throw propagates uncaught,
 * isolated by the `ToolManagerInterface` (`@orkestrel/tool`) into the canonical error envelope
 * — never caught or re-wrapped here.
 *
@@ -3359,8 +3367,8 @@ function createEndpointTool(definition, options) {
 		name: definition.name,
 		description: definition.description,
 		...parameters === void 0 ? {} : { parameters },
-		execute(args) {
-			return definition.execute(args);
+		execute(args, context) {
+			return definition.execute(args, context);
 		}
 	});
 	const contract = (0, _orkestrel_contract.createContract)((0, _orkestrel_contract.schemaToShape)(objectSchema));
@@ -3368,13 +3376,13 @@ function createEndpointTool(definition, options) {
 		name: definition.name,
 		description: definition.description,
 		...parameters === void 0 ? {} : { parameters },
-		execute(args) {
+		execute(args, context) {
 			const parsed = contract.parse(args);
 			if (parsed === void 0 || !(0, _orkestrel_contract.isRecord)(parsed)) throw new ToolboxError("TOOL", "malformed endpoint call arguments", {
 				name: definition.name,
 				faults: contract.explain(args)
 			});
-			return definition.execute(parsed);
+			return definition.execute(parsed, context);
 		}
 	});
 }