@orkestrel/toolbox 0.0.13 → 0.0.14

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

@@ -29,6 +29,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 +572,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 +642,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 +868,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 +885,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 +1572,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} —
@@ -2349,7 +2367,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

@@ -29,6 +29,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 +572,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 +642,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 +868,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 +885,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 +1572,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} —
@@ -2349,7 +2367,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

@@ -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.
 *
@@ -2058,7 +2058,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 +2085,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;
 	};
@@ -2885,11 +2887,14 @@ 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 = {}) {
@@ -3085,7 +3090,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) {
@@ -3304,8 +3312,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 +3368,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 +3377,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);
 		}
 	});
 }