@orkestrel/tool 0.0.13 → 0.0.15

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

@@ -1,30 +1,48 @@
-import { Failure } from '@orkestrel/contract';
-import { Success } from '@orkestrel/contract';
+import type { ContractShape } from '@orkestrel/contract';
+import type { EmitterErrorHandler } from '@orkestrel/emitter';
+import type { EmitterHooks } from '@orkestrel/emitter';
+import type { EmitterInterface } from '@orkestrel/emitter';
+import type { Failure } from '@orkestrel/contract';
+import type { Fault } from '@orkestrel/contract';
+import type { Success } from '@orkestrel/contract';
 
 /**
- * Creates an executable tool.
+ * Creates an executable tool bound to the supplied handler, returned as a
+ * `ToolInterface` so a call site holds the published contract rather than the `Tool`
+ * class.
  *
  * @param options - The advertised definition and execution handler
  * @returns A tool bound to the supplied handler
  *
- * @example
+ * @example Anatomy of a tool
  * ```ts
  * import { createTool } from '@orkestrel/tool'
  *
  * const add = createTool({
  * 	name: 'add',
- * 	description: 'Add two numbers',
- * 	execute: (args) => Number(args.a) + Number(args.b),
+ * 	description: 'Add two numeric values and return their sum. Both operands are required.',
+ * 	summary: 'Add two numbers.',
+ * 	parameters: {
+ * 		type: 'object',
+ * 		properties: {
+ * 			left: { type: 'number' },
+ * 			right: { type: 'number' },
+ * 		},
+ * 		required: ['left', 'right'],
+ * 	},
+ * 	execute: (args) => Number(args.left) + Number(args.right),
  * })
  * ```
  */
 export declare function createTool(options: ToolOptions): ToolInterface;
 
 /**
- * Creates an empty tool registry.
+ * Creates an empty registry that advertises definitions and executes calls with
+ * per-call error isolation, returned as a `ToolManagerInterface` so a caller holds the
+ * published contract rather than the `ToolManager` class.
  *
- * @returns A registry that advertises definitions and executes calls with per-call
- * error isolation
+ * @param options - The initial registry listeners and listener-error handler
+ * @returns A registry bound to no tools
  *
  * @example
  * ```ts
@@ -39,15 +57,15 @@ export declare function createTool(options: ToolOptions): ToolInterface;
  * })
  * ```
  */
-export declare function createToolManager(): ToolManagerInterface;
+export declare function createToolManager(options?: ToolManagerOptions): ToolManagerInterface;
 
 /**
- * Determines whether an unknown value is structurally a {@link ToolCall}.
+ * Determines whether an unknown value is structurally a {@link ToolCall}, staying total
+ * for malformed and adversarial input.
  *
  * @remarks
- * This total guard accepts a plain record with string `id` and `name` fields and a
- * plain-record `arguments` field. Optional caller context remains opaque and is not
- * read or verified. Adversarial values return `false`.
+ * The accepted shape is a plain record with string `id` and `name` fields and a
+ * plain-record `arguments` field. Extra fields are not read or verified.
  *
  * @param value - The value to test
  * @returns True if the value has the complete tool-call shape; false otherwise
@@ -62,11 +80,30 @@ export declare function createToolManager(): ToolManagerInterface;
  */
 export declare function isToolCall(value: unknown): value is ToolCall;
 
+/**
+ * Checks whether a value is a tool error, containing hostile prototype access.
+ *
+ * @param value - The value to test
+ * @returns True if the value is an instance of the tool error class; false otherwise
+ *
+ * @example
+ * ```ts
+ * import { ToolError, isToolError } from '@orkestrel/tool'
+ *
+ * isToolError(new ToolError('ARGUMENTS', 'Invalid amount')) // true
+ * isToolError(new Error('Unrelated')) // false
+ * ```
+ */
+export declare function isToolError(value: unknown): value is ToolError;
+
 /**
  * Binds an executable tool definition to a handler.
  *
  * @remarks
- * Schema fields, arguments, and present caller context are forwarded by reference.
+ * Advertised fields and execution context are forwarded by reference.
+ * A contract derives parameters at construction and refuses parse faults before the
+ * handler runs, then forwards the parsed arguments; without a contract, arguments
+ * retain their identity. Supplying a contract and parameters throws a schema conflict.
  * Caller context is consumer-asserted and is not verified. Handler failures are not
  * caught here; {@link ToolManager} owns per-call error isolation.
  *
@@ -88,21 +125,32 @@ export declare function isToolCall(value: unknown): value is ToolCall;
 export declare class Tool implements ToolInterface {
     #private;
     readonly name: string;
+    readonly title?: string;
     readonly description?: string;
     readonly summary?: string;
     readonly parameters?: Readonly<Record<string, unknown>>;
+    readonly annotations?: ToolAnnotations;
     constructor(options: ToolOptions);
-    execute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown;
+    execute(args: Readonly<Record<string, unknown>>, context: ToolContext): Promise<unknown> | unknown;
+}
+
+/** Describes the observable effects and content of a tool. */
+export declare interface ToolAnnotations {
+    /** Reports that the tool changes no state its caller can observe. */
+    readonly pure?: boolean;
+    /** Reports that the tool's value can carry content the tool did not author. */
+    readonly untrusted?: boolean;
+    /** Reports that running the tool has a consequence a caller must confirm. */
+    readonly consequential?: boolean;
 }
 
 /**
- * Describes a call issued by a caller.
+ * Describes one request to run a named tool.
  *
  * @remarks
  * `id` correlates the call with its later {@link ToolResult}. `arguments` is the
- * caller-supplied arguments record. `caller` is optional consumer-asserted context:
- * this package forwards it without verification, so the tool or its policy layer owns
- * every trust decision.
+ * caller-supplied arguments record. Execution context travels separately from this
+ * JSON call envelope.
  */
 export declare interface ToolCall {
     /** Correlates this call with its result. */
@@ -111,7 +159,13 @@ export declare interface ToolCall {
     readonly name: string;
     /** Carries the record the caller supplied. */
     readonly arguments: Readonly<Record<string, unknown>>;
-    /** Carries consumer-asserted context, forwarded without verification. */
+}
+
+/** Carries the signal and consumer-asserted identity for an execution. */
+export declare interface ToolContext {
+    /** Aborts when the caller stops waiting for this call. */
+    readonly signal: AbortSignal;
+    /** Carries consumer-asserted caller identity, forwarded without verification. */
     readonly caller?: unknown;
 }
 
@@ -124,10 +178,41 @@ export declare interface ToolCall {
 export declare interface ToolDefinition {
     /** Identifies the tool a caller selects. */
     readonly name: string;
+    /** Holds a display title for the tool. */
+    readonly title?: string;
     /** Describes the tool's behavior. */
     readonly description?: string;
     /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
+    /** Describes the tool's observable effects and content. */
+    readonly annotations?: ToolAnnotations;
+}
+
+/**
+ * Reports a schema conflict or argument validation failure with a machine-readable code.
+ *
+ * @example
+ * ```ts
+ * import { ToolError } from '@orkestrel/tool'
+ *
+ * const error = new ToolError('SCHEMA', 'Choose contract or parameters')
+ * error.code // 'SCHEMA'
+ * ```
+ */
+export declare class ToolError extends Error {
+    readonly name: "ToolError";
+    readonly code: ToolErrorCode;
+    readonly context?: ToolErrorContext;
+    constructor(code: ToolErrorCode, message: string, context?: ToolErrorContext);
+}
+
+/** Identifies a schema conflict or an argument validation failure. */
+export declare type ToolErrorCode = 'SCHEMA' | 'ARGUMENTS';
+
+/** Carries the structured faults behind an argument validation failure. */
+export declare interface ToolErrorContext {
+    /** Holds the contract's full parse-fault report. */
+    readonly faults?: readonly Fault[];
 }
 
 /**
@@ -137,7 +222,7 @@ export declare interface ToolDefinition {
  * `error` is the failure message: an unknown tool name, an `Error`'s message, or
  * a String-converted throw. The registry carries no further structure. An
  * in-process caller needing a typed error calls `tools.tool(name)`, then
- * `tool.execute(args)` in its own `try`/`catch`.
+ * `tool.execute(args, context)` in its own `try`/`catch`.
  */
 export declare interface ToolFailure extends Failure<string> {
     /** Identifies the corresponding call. */
@@ -157,19 +242,25 @@ export declare interface ToolInterface extends ToolDefinition {
     /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
     /**
-     * Runs the tool's handler.
+     * Runs the tool's handler with the caller-supplied arguments and execution context.
      *
      * @remarks
      * Failures are not contained here: a synchronous throw propagates and an
      * asynchronous rejection rejects. {@link ToolManagerInterface.execute} is where a
-     * call becomes a result. The registry omits `caller` from the invocation when the
-     * call carries none, so a handler reading its own arity sees one argument.
+     * call becomes a result. A configured contract refuses arguments with parse faults
+     * before the handler runs, then forwards `contract.parse(args)`, an owned,
+     * normalized copy in the schema's types with undeclared keys dropped; without a
+     * contract, the raw record is forwarded unchanged.
+     * Caller identity is forwarded without verification.
+     * The second parameter is the execution context; caller identity is `context.caller`.
+     * `Tool.execute` refuses nothing on an aborted signal; the manager checks the signal
+     * before entry, and a direct caller who passes an aborted signal gets a handler that observes it.
      *
      * @param args - The caller-supplied arguments record
-     * @param caller - Optional consumer-asserted caller context, forwarded without verification
+     * @param context - The required signal and optional consumer-asserted caller identity
      * @returns The tool's synchronous or asynchronous result
      */
-    execute(args: Readonly<Record<string, unknown>>, caller?: unknown): Promise<unknown> | unknown;
+    execute(args: Readonly<Record<string, unknown>>, context: ToolContext): Promise<unknown> | unknown;
 }
 
 /**
@@ -181,7 +272,13 @@ export declare interface ToolInterface extends ToolDefinition {
  * Unknown names and handler throws resolve to error results; a call whose `id` or `name`
  * accessor throws when read makes its call, and the batch holding it, reject. Batch
  * execution preserves input order and isolates each call whose members are plain
- * values. Optional consumer-asserted caller context is forwarded without verification.
+ * values. Execution context is shared across a batch and forwarded unchanged. An
+ * omitted context receives a non-aborted signal. A signal aborted before handler
+ * entry produces an error result; later cancellation is the handler's responsibility.
+ * Registry changes publish synchronously. Replacements publish `remove`, then `add`
+ * if the map still holds that exact replacement after the removal listeners return.
+ * Destruction clears the tools before releasing listeners. A destroyed registry
+ * publishes nothing, even when later additions update its tool map.
  *
  * @example
  * ```ts
@@ -198,19 +295,45 @@ export declare interface ToolInterface extends ToolDefinition {
  */
 export declare class ToolManager implements ToolManagerInterface {
     #private;
+    constructor(options?: ToolManagerOptions);
     get count(): number;
+    get emitter(): EmitterInterface<ToolManagerEventMap>;
     add(tool: ToolInterface): void;
     add(tools: readonly ToolInterface[]): void;
     tool(name: string): ToolInterface | undefined;
     tools(): readonly ToolInterface[];
     definitions(): readonly ToolDefinition[];
-    execute(call: ToolCall): Promise<ToolResult>;
-    execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    execute(call: ToolCall, context?: ToolContext): Promise<ToolResult>;
+    execute(calls: readonly ToolCall[], context?: ToolContext): Promise<readonly ToolResult[]>;
     remove(name: string): boolean;
     remove(names: readonly string[]): boolean;
     clear(): void;
+    destroy(): void;
 }
 
+/**
+ * Names the events a tool registry publishes.
+ *
+ * @remarks
+ * Each event describes the registry at the moment it is published. A listener that
+ * mutates the registry re-enters synchronously; its events publish before the outer
+ * call resumes.
+ */
+export declare type ToolManagerEventMap = {
+    /** Fires after a tool is registered, with the registered instance. */
+    readonly add: readonly [tool: ToolInterface];
+    /**
+     * Fires after a tool is removed, with the removed instance.
+     *
+     * @remarks
+     * A replacement publishes this event with the replacement already installed.
+     * A listener must not read absence from the map to confirm a removal.
+     */
+    readonly remove: readonly [tool: ToolInterface];
+    /** Fires once per `clear`, with the tools it removed in registration order. */
+    readonly clear: readonly [tools: readonly ToolInterface[]];
+};
+
 /**
  * Represents a registry of executable tools with per-call error isolation.
  *
@@ -219,11 +342,17 @@ export declare class ToolManager implements ToolManagerInterface {
  * value without changing its position. Every call whose members are plain values
  * resolves to a {@link ToolResult}; missing tools and thrown handlers become error
  * results, and a call whose `id` or `name` accessor throws when read makes `execute`
- * reject instead. Batch execution preserves input order and isolates each such call.
+ * reject instead. Batch execution preserves input order.
+ * Registry changes publish synchronously through the owned emitter. A replacement
+ * publishes `remove` for the previous instance, then `add` if the map still holds
+ * that exact replacement after the removal listeners return.
+ * A destroyed registry publishes nothing; later additions still update its tool map.
  */
 export declare interface ToolManagerInterface {
     /** Reports how many tools are registered. */
     readonly count: number;
+    /** Publishes the registry's `add`, `remove`, and `clear` events. */
+    readonly emitter: EmitterInterface<ToolManagerEventMap>;
     /**
      * Registers one tool.
      *
@@ -242,7 +371,7 @@ export declare interface ToolManagerInterface {
      * Finds one registered tool by name.
      *
      * @param name - The registered tool name
-     * @returns The tool when found, otherwise `undefined`
+     * @returns The exact registered instance when found, otherwise `undefined`
      */
     tool(name: string): ToolInterface | undefined;
     /**
@@ -254,6 +383,7 @@ export declare interface ToolManagerInterface {
     /**
      * Lists the definitions advertised to a caller.
      *
+     * @remarks
      * The projected `description` is the tool's `summary` when one was authored,
      * advertised in place of the full description. The full text stays on the tool
      * for direct lookup.
@@ -264,17 +394,19 @@ export declare interface ToolManagerInterface {
     /**
      * Executes one call with error isolation.
      *
-     * @param call - The tool call to execute, including optional caller context
+     * @param call - The tool call to execute
+     * @param context - The execution context; omission creates a non-aborted signal
      * @returns The correlated result
      */
-    execute(call: ToolCall): Promise<ToolResult>;
+    execute(call: ToolCall, context?: ToolContext): Promise<ToolResult>;
     /**
      * Executes a batch of calls with per-call error isolation.
      *
-     * @param calls - The tool calls to execute, including optional caller context
+     * @param calls - The tool calls to execute
+     * @param context - The shared execution context; omission creates a non-aborted signal
      * @returns The correlated results in input order
      */
-    execute(calls: readonly ToolCall[]): Promise<readonly ToolResult[]>;
+    execute(calls: readonly ToolCall[], context?: ToolContext): Promise<readonly ToolResult[]>;
     /**
      * Removes one registered tool.
      *
@@ -295,6 +427,27 @@ export declare interface ToolManagerInterface {
      * @returns Nothing
      */
     clear(): void;
+    /**
+     * Removes every tool and releases the emitter's listeners.
+     *
+     * @remarks
+     * Publishes `clear` before destroying the emitter. A destroyed registry publishes
+     * nothing, including when a later `add` updates its tool map.
+     * Returns with an empty registry even if a `clear` listener adds a tool.
+     * An emission already underway delivers to its remaining snapshotted listeners,
+     * even when a listener destroys the registry before its siblings run.
+     *
+     * @returns Nothing
+     */
+    destroy(): void;
+}
+
+/** Configures a tool registry's initial listeners and error handling. */
+export declare interface ToolManagerOptions {
+    /** Registers the initial listeners for registry changes. */
+    readonly on?: EmitterHooks<ToolManagerEventMap>;
+    /** Receives listener throws with the event name, without interrupting sibling listeners. */
+    readonly error?: EmitterErrorHandler;
 }
 
 /**
@@ -303,20 +456,32 @@ export declare interface ToolManagerInterface {
  * @remarks
  * `name` identifies the tool, `description` and `parameters` define what is advertised
  * to a caller, `summary` optionally replaces the advertised description, and `execute`
- * handles the caller-supplied arguments record plus optional consumer-asserted caller
- * context. This package forwards that context without verification.
+ * handles the caller-supplied arguments record and execution context. `contract`
+ * derives the advertised parameters and checks arguments with `explain`; supplying
+ * `parameters` alongside `contract` throws a `ToolError` with code `SCHEMA`.
  */
 export declare interface ToolOptions {
     /** Identifies the tool a caller selects. */
     readonly name: string;
+    /** Holds a display title for the tool. */
+    readonly title?: string;
     /** Describes the tool's behavior in full. */
     readonly description?: string;
     /** Holds a concise description to advertise in place of the full description. */
     readonly summary?: string;
     /** Holds the JSON Schema for the tool's arguments. */
     readonly parameters?: Readonly<Record<string, unknown>>;
-    /** Handles the arguments and optional unverified caller context. */
-    readonly execute: (args: Readonly<Record<string, unknown>>, caller?: unknown) => Promise<unknown> | unknown;
+    /** Derives parameters and validates arguments before execution. */
+    readonly contract?: ContractShape;
+    /** Describes the tool's observable effects and content. */
+    readonly annotations?: ToolAnnotations;
+    /**
+     * Handles the arguments and required execution context.
+     *
+     * @remarks
+     * The second parameter is the execution context; caller identity is `context.caller`.
+     */
+    readonly execute: (args: Readonly<Record<string, unknown>>, context: ToolContext) => Promise<unknown> | unknown;
 }
 
 /**
@@ -344,15 +509,14 @@ export declare interface ToolSuccess extends Success<unknown> {
 }
 
 /**
- * Projects a tool onto the plain definition advertised to a caller.
+ * Projects a tool onto the plain definition advertised to a caller, advertising an
+ * authored `summary` in place of the full description and carrying `parameters` and
+ * `annotations` by reference.
  *
  * @remarks
- * The projection is a fresh object carrying `name`, then `description` only when the
- * tool authored a summary or a description, then `parameters` only when the tool
- * authored a schema. An authored `summary` is advertised in place of the full
- * `description`, which stays on the tool for direct lookup. The parameter schema is
- * copied by reference and never cloned, so the definition is never a live handle on
- * the tool's handler.
+ * The projection carries `name` and present `title`, `description`, `parameters`, and
+ * `annotations` fields in that order. The full `description` stays on the tool for
+ * direct lookup, and the definition is never a live handle on the tool's handler.
  *
  * @param tool - The tool to project
  * @returns A fresh definition carrying only the fields the tool authored