@orkestrel/toolbox 0.0.13 → 0.0.15

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

@@ -10,6 +10,7 @@ import type { ConversationStoreInterface } from '@orkestrel/agent';
 import type { DatabaseErrorCode } from '@orkestrel/database';
 import type { DatabaseInterface } from '@orkestrel/database';
 import type { DriverInterface } from '@orkestrel/database';
+import type { Guard } from '@orkestrel/contract';
 import type { Include } from '@orkestrel/relation';
 import type { IndexMap } from '@orkestrel/database';
 import { JSONShape } from '@orkestrel/contract';
@@ -29,6 +30,7 @@ import { StringShape } from '@orkestrel/contract';
 import type { TableInterface } from '@orkestrel/database';
 import type { TableMap } from '@orkestrel/database';
 import type { TerminalManagerInterface } from '@orkestrel/terminal';
+import type { ToolContext } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
 import { UnionShape } from '@orkestrel/contract';
@@ -571,11 +573,14 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * 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 },
+ * )
  * ```
  */
 export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolInterface;
@@ -638,8 +643,10 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * 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.
  *
@@ -862,7 +869,10 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * 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 },
+ * )
  * ```
  */
 export declare function createRelationTool(options: RelationToolOptions): ToolInterface;
@@ -876,7 +886,9 @@ export declare function createRelationTool(options: RelationToolOptions): ToolIn
  * (`{ 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`.
  *
@@ -1561,12 +1573,19 @@ export declare interface EndpointDefinition {
 
 /**
  * Represents the handler {@link EndpointDefinition.execute} implements — it mirrors
- * `@orkestrel/tool`'s `ToolOptions.execute` signature exactly (the same
- * `Readonly<Record<string, unknown>>` argument, the same `Promise<unknown> | unknown` return), so
- * `execute: (args) => definition.execute(args)` typechecks with zero assertions in
- * {@link import('./factories.js').createEndpointTool}.
+ * `@orkestrel/tool`'s `ToolOptions.execute` signature exactly, so
+ * {@link import('./factories.js').createEndpointTool} forwards the execution context it receives
+ * to the handler unchanged and a handler that reads `context.signal` observes the caller's
+ * cancellation.
+ *
+ * @remarks
+ * The mirrored signature is the same `Readonly<Record<string, unknown>>` argument, the same
+ * `ToolContext` second parameter, and the same `Promise<unknown> | unknown` return. A handler that
+ * declares `args` alone still satisfies the type, the way a function declaring fewer parameters
+ * than its contract does, so an endpoint definition written against the argument alone keeps
+ * typechecking and reads no signal.
  */
-export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> | unknown;
 
 /**
  * Represents the construction-time tuning for {@link import('./factories.js').createEndpointTool} —
@@ -1782,7 +1801,7 @@ export declare function isAgentFunction(value: unknown): value is AgentFunction;
  * @param value - The value to inspect
  * @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
  */
-export declare function isColumnPrimitive(value: unknown): value is ColumnPrimitive;
+export declare const isColumnPrimitive: Guard<ColumnPrimitive>;
 
 /**
  * Narrows an unknown value to a {@link ColumnSpec}.
@@ -2349,7 +2368,7 @@ timeout: OptionalShape<NumberShape>;
  * @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.
  *

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

@@ -10,6 +10,7 @@ import type { ConversationStoreInterface } from '@orkestrel/agent';
 import type { DatabaseErrorCode } from '@orkestrel/database';
 import type { DatabaseInterface } from '@orkestrel/database';
 import type { DriverInterface } from '@orkestrel/database';
+import type { Guard } from '@orkestrel/contract';
 import type { Include } from '@orkestrel/relation';
 import type { IndexMap } from '@orkestrel/database';
 import { JSONShape } from '@orkestrel/contract';
@@ -29,6 +30,7 @@ import { StringShape } from '@orkestrel/contract';
 import type { TableInterface } from '@orkestrel/database';
 import type { TableMap } from '@orkestrel/database';
 import type { TerminalManagerInterface } from '@orkestrel/terminal';
+import type { ToolContext } from '@orkestrel/tool';
 import type { ToolInterface } from '@orkestrel/tool';
 import type { ToolManagerInterface } from '@orkestrel/tool';
 import { UnionShape } from '@orkestrel/contract';
@@ -571,11 +573,14 @@ export declare function createDatabaseDefinitionStore(driver?: DriverInterface):
  * 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 },
+ * )
  * ```
  */
 export declare function createDatabaseTool(options?: DatabaseToolOptions): ToolInterface;
@@ -638,8 +643,10 @@ export declare function createDescribeTool(tools: ToolManagerInterface): ToolInt
  * 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.
  *
@@ -862,7 +869,10 @@ export declare function createPromptTool(options: PromptToolOptions): ToolInterf
  * 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 },
+ * )
  * ```
  */
 export declare function createRelationTool(options: RelationToolOptions): ToolInterface;
@@ -876,7 +886,9 @@ export declare function createRelationTool(options: RelationToolOptions): ToolIn
  * (`{ 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`.
  *
@@ -1561,12 +1573,19 @@ export declare interface EndpointDefinition {
 
 /**
  * Represents the handler {@link EndpointDefinition.execute} implements — it mirrors
- * `@orkestrel/tool`'s `ToolOptions.execute` signature exactly (the same
- * `Readonly<Record<string, unknown>>` argument, the same `Promise<unknown> | unknown` return), so
- * `execute: (args) => definition.execute(args)` typechecks with zero assertions in
- * {@link import('./factories.js').createEndpointTool}.
+ * `@orkestrel/tool`'s `ToolOptions.execute` signature exactly, so
+ * {@link import('./factories.js').createEndpointTool} forwards the execution context it receives
+ * to the handler unchanged and a handler that reads `context.signal` observes the caller's
+ * cancellation.
+ *
+ * @remarks
+ * The mirrored signature is the same `Readonly<Record<string, unknown>>` argument, the same
+ * `ToolContext` second parameter, and the same `Promise<unknown> | unknown` return. A handler that
+ * declares `args` alone still satisfies the type, the way a function declaring fewer parameters
+ * than its contract does, so an endpoint definition written against the argument alone keeps
+ * typechecking and reads no signal.
  */
-export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>) => Promise<unknown> | unknown;
+export declare type EndpointHandler = (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> | unknown;
 
 /**
  * Represents the construction-time tuning for {@link import('./factories.js').createEndpointTool} —
@@ -1782,7 +1801,7 @@ export declare function isAgentFunction(value: unknown): value is AgentFunction;
  * @param value - The value to inspect
  * @returns True if `value` is `'string'`, `'integer'`, `'number'`, or `'boolean'`; false otherwise
  */
-export declare function isColumnPrimitive(value: unknown): value is ColumnPrimitive;
+export declare const isColumnPrimitive: Guard<ColumnPrimitive>;
 
 /**
  * Narrows an unknown value to a {@link ColumnSpec}.
@@ -2349,7 +2368,7 @@ timeout: OptionalShape<NumberShape>;
  * @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.
  *

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { arrayShape, attempt, booleanShape, cloneJSONRecord, createContract, integerShape, isFiniteNumber, isNonEmptyString, isRecord, isString, jsonShape, literalShape, numberShape, objectShape, optionalShape, parseJSONValue, rawShape, recordShape, samplesToSchema, schemaToObject, schemaToParameters, schemaToShape, stringShape, unionShape } from "@orkestrel/contract";
+import { arrayShape, attempt, booleanShape, cloneJSONRecord, createContract, integerShape, isArray, isBoolean, isError, isFiniteNumber, isFunction, isInstance, isNonEmptyString, isNumber, isObject, isRecord, isString, jsonShape, literalOf, literalShape, numberShape, objectShape, optionalShape, parseJSONValue, rawShape, recordShape, samplesToSchema, schemaToObject, schemaToParameters, schemaToShape, stringShape, unionShape } from "@orkestrel/contract";
 import { MAX_TIMER_MS, createWorkflowContract } from "@orkestrel/workflow";
 import { isTerminalError } from "@orkestrel/terminal";
 import { createDatabase, createMemoryDriver, isDatabaseError } from "@orkestrel/database";
@@ -590,7 +590,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.
 *
@@ -632,7 +632,7 @@ var ToolboxError = class extends Error {
 * ```
 */
 function isToolboxError(value) {
-	return value instanceof ToolboxError;
+	return isInstance(value, ToolboxError);
 }
 //#endregion
 //#region src/core/validators.ts
@@ -644,7 +644,7 @@ function isToolboxError(value) {
 */
 function isWorkflowLineage(value) {
 	const inspected = attempt(() => {
-		if (!Array.isArray(value)) return false;
+		if (!isArray(value)) return false;
 		const seen = /* @__PURE__ */ new Set();
 		for (const [index, tag] of value.entries()) {
 			if (!isString(tag)) return false;
@@ -664,7 +664,7 @@ function isWorkflowLineage(value) {
 */
 function isAgentFunction(value) {
 	const inspected = attempt(() => {
-		if (typeof value !== "function" || !Object.isFrozen(value)) return false;
+		if (!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);
@@ -680,7 +680,7 @@ function isAgentFunction(value) {
 function isColumnSpec(value) {
 	if (isColumnPrimitive(value)) return true;
 	if (!isRecord(value)) return false;
-	return isColumnPrimitive(value.primitive) && (value.optional === void 0 || typeof value.optional === "boolean");
+	return isColumnPrimitive(value.primitive) && (value.optional === void 0 || isBoolean(value.optional));
 }
 /**
 * Narrows an unknown value to a {@link ColumnPrimitive}.
@@ -688,9 +688,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 = 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
@@ -717,9 +715,9 @@ function isDatabaseDefinition(value) {
 	if (value.indexes !== void 0) {
 		if (!isRecord(value.indexes)) return false;
 		for (const groups of Object.values(value.indexes)) {
-			if (!Array.isArray(groups)) return false;
+			if (!isArray(groups)) return false;
 			for (const group of groups) {
-				if (!Array.isArray(group) || group.length === 0) return false;
+				if (!isArray(group) || group.length === 0) return false;
 				for (const column of group) if (!isNonEmptyString(column)) return false;
 			}
 		}
@@ -1575,7 +1573,7 @@ function expandInclude(paths, depth) {
 			});
 			ancestors.push(branch);
 			const existing = branch[segment];
-			branch = typeof existing === "object" ? existing : {};
+			branch = isObject(existing) ? existing : {};
 		}
 		const leaf = segments[last];
 		if (leaf === void 0) throw new ToolboxError("TOOL", `malformed include path '${path}'`, {
@@ -2058,7 +2056,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`.
 *
@@ -2083,7 +2083,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 = parseJSONValue(await tool.execute(controller.input));
+		const result = 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;
 	};
@@ -2208,7 +2208,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 (!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;
 	}
@@ -2337,7 +2337,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 (isArray(owned.steps)) {
 				const flat = steps.parse(owned);
 				target = flat === void 0 ? void 0 : expandSteps(flat);
 			} else {
@@ -2885,15 +2885,18 @@ function createDatabaseDefinitionStore(driver = createMemoryDriver()) {
 * 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 || !isNumber(options.timeout) || !Number.isSafeInteger(options.timeout))) throw new ToolboxError("TOOL", "database timeout must be a nonnegative safe integer", { timeout: options.timeout });
 	const contract = createContract(databaseToolShape);
 	const parameters = schemaToParameters(contract.schema);
 	const handles = new Map(Object.entries(options.databases ?? {}));
@@ -2963,8 +2966,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 = isArray(call.key);
+						const keys = isArray(call.key) ? call.key : [call.key];
 						const rows = await table.get(keys);
 						return many ? { rows } : { row: rows[0] };
 					}
@@ -2985,30 +2988,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 = isArray(call.row);
+						const rows = 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 = isArray(call.row);
+						const rows = 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 = isArray(call.key);
+						const keys = 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 = isArray(call.key);
+						const keys = isArray(call.key) ? call.key : [call.key];
 						const removed = await table.remove(keys, read);
 						return many ? { removed } : { removed: removed[0] };
 					}
@@ -3030,7 +3033,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", isError(error) ? error.message : String(error), {
 					code,
 					operation: call.operation,
 					id: call.id,
@@ -3085,7 +3088,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) {
@@ -3106,7 +3112,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 (isString(call.key) || isNumber(call.key)) return { row: await model.load(call.key, include) };
 						return { rows: await model.load(call.key, include) };
 					}
 					case "find": {
@@ -3149,7 +3155,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", isError(error) ? error.message : String(error), {
 					code: relation,
 					operation: call.operation,
 					model: call.model,
@@ -3157,7 +3163,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", isError(error) ? error.message : String(error), {
 					code: database,
 					operation: call.operation
 				});
@@ -3304,8 +3310,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.
 *
@@ -3358,8 +3366,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 = createContract(schemaToShape(objectSchema));
@@ -3367,13 +3375,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 || !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);
 		}
 	});
 }