@jangts/agent-core 0.3.5 → 0.5.0

package/dist/esm/kits/tools.d.ts

@@ -1,25 +1,27 @@
 import type { ToolInvocationRequest } from '../structs/capabilities/tools.js';
 import type { ToolResult } from '../structs/invocation.js';
-import type { ToolRuntimeTypes, LifecycleTool, RegisteredLifecycleTool, ToolLifecycleOptions, ToolNormalizer, ToolFinalizer, ToolProtocol } from '../structs/kits/tools.js';
+import type { ToolRuntimeTypes, Tool, ToolRegistration, RegisteredToolDefinition, ToolsOptions, ToolNormalizer, ToolFinalizer, ToolProtocol } from '../structs/kits/tools.js';
 import type { ToolRegistryPorts } from '../structs/capabilities/tools.js';
 import { ProtocolRegistry } from '../utils/protocol-registry.js';
 /**
- * Registered lifecycle and delivery hooks. Domain predicates and phase names are host
- * configuration.
+ * Registered lifecycle hooks. Domain predicates and phase names are host configuration.
  */
-type PreparedTool<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> = RegisteredLifecycleTool<Types, Tool> & LifecycleTool<Types>;
+type PreparedTool<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types>> = RegisteredToolDefinition<Types, Declaration> & Tool<Types>;
 /**
- * Registry of tools whose lifecycle, protocols and contributions are declared by the App.
+ * Registry of tools whose lifecycle, protocols and context contributions the App declares.
  *
  * Registration is only possible before `seal()`; afterwards the catalog is read-only, so a run
- * cannot change which tools exist. Every contribution hook is optional and is applied in
- * registration order, which is why `registerAll` preserves iteration order.
+ * cannot change which tools exist. Every hook is optional and is applied in registration order,
+ * which is why `registerAll` preserves iteration order.
  */
-export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types> = LifecycleTool<Types>> {
+export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types> = ToolRegistration<Types>> {
     private readonly tools;
     private readonly registered;
     private readonly sources;
+    /** Tools that own an invocation id; dispatch by decision next reads this index. */
     private readonly invocations;
+    /** Tools that answer a delegate id; dispatch by node reads this index. */
+    private readonly delegateIndex;
     private normalizer?;
     private finalizer?;
     private sealed;
@@ -30,11 +32,11 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
     /**
      * @param options - Receiver, execution context, error wording, registration policy, protocol
      *   providers and optional journal/receipt ports; contract methods are bound to their owner.
-     * @throws TypeError When no `intentIds` provider is supplied.
+     * @throws TypeError When no `goalIds` provider is supplied.
      */
-    constructor(options: ToolLifecycleOptions<Types, Tool>);
+    constructor(options: ToolsOptions<Types, Declaration>);
     /** Core tool events, forwarded unchanged. */
-    get events(): readonly Readonly<import("../index.js").ToolExecutionEvent<PreparedTool<Types, Tool>["kind"]>>[];
+    get events(): readonly Readonly<import("../index.js").ToolExecutionEvent<PreparedTool<Types, Declaration>["kind"]>>[];
     /** Swap the diagnostics sink for later invocations; the Core registry is updated as well. */
     setDiagnostics(value: ToolRegistryPorts['diagnostics']): void;
     /**
@@ -44,16 +46,19 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
      * hooks must return `void` synchronously, while the remaining handlers are checked for
      * accidental thenables only.
      *
-     * @param input - Tool definition with identity, audience, effect and its handlers.
+     * @param input - Tool definition with identity, audience, effect and its hooks.
      * @returns This registry, for chaining.
      * @throws A configured registration error for a sealed registry, invalid identity,
-     *   description, audience, effect, intent ids, missing handlers, duplicate tool id,
-     *   incomplete invocation contract, protocol version mismatch or duplicate invocation step.
+     *   description, audience, effect, goal ids, missing handlers, duplicate tool id,
+     *   duplicate delegate id, incomplete lifecycle contract, protocol version mismatch or
+     *   duplicate invocation id.
      */
-    register(input: Tool): this;
+    register(input: Declaration): this;
+    /** Validate one declaration in the fixed order documented by `register`. */
+    private assertRegistration;
     private install;
     /** Register every tool in iteration order. */
-    registerAll(tools: Iterable<Tool>): this;
+    registerAll(tools: Iterable<Declaration>): this;
     /**
      * Invoke one Core tool by its already-validated request.
      *
@@ -62,23 +67,25 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
      */
     invoke(request: ToolInvocationRequest): ToolResult<unknown>;
     /** Registered tools in registration order. */
-    get definitions(): readonly RegisteredLifecycleTool<Types, Tool>[];
+    get definitions(): readonly RegisteredToolDefinition<Types, Declaration>[];
     /** Registered tool ids, delegated to the Core registry. */
     ids(): readonly string[];
     /** Iterate `[id, tool]` pairs. */
-    entries(): IterableIterator<[string, RegisteredLifecycleTool<Types, Tool>]>;
+    entries(): IterableIterator<[string, RegisteredToolDefinition<Types, Declaration>]>;
     /** Registered tool for `id`, or `undefined` when it is absent. */
-    get(id: string): RegisteredLifecycleTool<Types, Tool> | undefined;
+    get(id: string): RegisteredToolDefinition<Types, Declaration> | undefined;
     /**
      * Registered tool for `id`.
      *
      * @throws TypeError When the id is not registered.
      */
-    require(id: string): RegisteredLifecycleTool<Types, Tool>;
+    require(id: string): RegisteredToolDefinition<Types, Declaration>;
     /** Whether a tool id is registered. */
     has(name: string): boolean;
     /** Iterate the registered tools. */
-    values(): IterableIterator<RegisteredLifecycleTool<Types, Tool>>;
+    values(): IterableIterator<RegisteredToolDefinition<Types, Declaration>>;
+    /** Whether a delegate id is claimed by a registered tool. */
+    hasDelegate(id: string): boolean;
     /**
      * Install the single normalization handler.
      *
@@ -101,30 +108,40 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
      */
     finish(receiver: Types['receiver'], decision: Types['decision'], context: Types['context']): Types['result'];
     /**
-     * Execute the invocation registered for a step type.
+     * Run the invocation that answers one decision next.
+     *
+     * Delegation is the App's choice; this method only executes the tool that claimed the id, so a
+     * purely programmatic node, a model choice and a mixed pipeline all dispatch the same way.
      *
      * Diagnostics are swapped to the invocation's own sink for the duration of the call and
      * restored afterwards, so nested tool calls report under the innermost scope.
      *
-     * @param step - Step carrying the registered `type`.
+     * @param next - Decision next carrying the claimed delegate id in `type`.
      * @param context - Execution context forwarded to Core's invocation executor.
-     * @throws A configured error when the step is unknown or the tool is unavailable.
+     * @throws A configured error when the delegate is unknown or the tool is unavailable.
      */
-    call(step: {
+    call(next: {
         type: string;
     }, context: Types['context']): void;
-    /** Output protocols plus one protocol per registered invocation step. */
-    protocols(): ProtocolRegistry<ToolProtocol<Tool>>;
+    /** Output protocols plus one protocol per registered invocation. */
+    protocols(): ProtocolRegistry<ToolProtocol<Declaration>>;
     /**
-     * Protocols exposed to the model: output protocols plus steps whose audience is `model` and
+     * Protocols exposed to the model: output protocols plus invocations whose audience is `model` and
      * which are currently available in `context`.
      */
-    modelProtocols(context: Types['context']): ProtocolRegistry<ToolProtocol<Tool>>;
-    /** Whether the protocol registered for this step is declared terminal. */
-    isTerminal(step: {
+    modelProtocols(context: Types['context']): ProtocolRegistry<ToolProtocol<Declaration>>;
+    /** Whether the protocol registered for this invocation is declared terminal. */
+    isTerminal(next: {
         type: string;
     }): boolean;
-    /** Run contribution inspection for every tool, then the selected invocation's own check. */
+    /** `[invocationId, protocol]` pairs, optionally filtered by the owning tool. */
+    private invocationProtocols;
+    /**
+     * Run `inspect` for every registered tool in registration order.
+     *
+     * `inspect` belongs to the all-tools group, so the selected tool participates exactly once
+     * through the same loop rather than through a second selected-only pass.
+     */
     assertDecision(decision: Types['decision'], context: Types['context']): void;
     /** Run the selected invocation's authorization hook, if any. */
     authorize(decision: Types['decision'], context: Types['context']): void;
@@ -132,33 +149,33 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
     resume(decision: Types['decision'], context: Types['context']): boolean;
     /** Let the selected invocation rewrite the decision on completion, if it declares a hook. */
     complete(decision: Types['decision'], context: Types['context']): Types['decision'] | undefined;
-    /** Fold every contribution's context projection over the value, in registration order. */
+    /** Fold every tool's context projection over the value, in registration order. */
     projectContext(value: unknown): unknown;
-    /** Fold every contribution's visible-text transform over the text. */
+    /** Fold every tool's visible-text transform over the text. */
     visibleText(text: string, context: Types['context']): string;
-    /** Fold every contribution's review transform over the draft. */
+    /** Fold every tool's review transform over the draft. */
     reviewDraft(draft: unknown, context: Types['context']): unknown;
     /** Collected recovery context values; `undefined` results are omitted. */
     recoveryContext(context: Types['context']): unknown[];
     /**
      * The single output template that owns this delivery.
      *
-     * @throws An error when more than one contribution claims composition, because delivery
-     *   would otherwise depend on registration order.
+     * @throws An error when more than one tool claims composition, because delivery would
+     *   otherwise depend on registration order.
      */
     composition(context: Types['context']): Types['composition'] | undefined;
-    /** Run every contribution's finalize hook for the given phase. */
+    /** Run every tool's finalize hook for the given phase. */
     finalize(decision: Types['decision'], context: Types['context'], phase: Types['phase']): void;
-    /** Whether any contribution permits the interaction to be missing. */
+    /** Whether any tool permits the interaction to be missing. */
     missingInteractionAllowed(decision: Types['decision'], context: Types['context']): boolean;
     /** Task rules ordered by their declared `order`, joined into one prompt block. */
     taskRules(context: Types['context']): string;
     /** Model-context fragments for one placement, ordered by each field's `order`. */
     contextFields(context: Types['context'], placement: Types['placement']): import("../index.js").ContextFragment[];
     /** Merged model-context values for one placement; later fragments win per key. */
-    modelFields(context: Types['context'], placement: Types['placement']): any;
-    /** A contribution may veto an intent by returning `false`; silence means support. */
-    supportsIntent(intentId: string, context: Types['context']): boolean;
+    modelFields(context: Types['context'], placement: Types['placement']): Record<string, unknown>;
+    /** A tool may veto a goal by returning `false`; silence means support. */
+    supportsGoal(intentId: string, context: Types['context']): boolean;
     /**
      * Describe registered tools, optionally limited by audience and availability.
      *
@@ -167,15 +184,15 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
      *
      * @param audience - Audience to keep; omit to include every audience.
      * @param context - Context for availability checks.
-     * @returns Plain metadata; `intentIds: 'all'` is expanded to the current intent ids.
+     * @returns Plain metadata; `goalIds: 'all'` is expanded to the current goal ids.
      */
     describe(audience?: string, context?: Types['context']): {
-        id: Tool['id'];
-        kind: Tool['kind'];
-        description: Tool['description'];
-        audience: Tool['audience'];
-        effect: Tool['effect'];
-        intentIds: string[];
+        id: Declaration['id'];
+        kind: Declaration['kind'];
+        description: Declaration['description'];
+        audience: Declaration['audience'];
+        effect: Declaration['effect'];
+        goalIds: string[];
     }[];
     /**
      * Reinstall every registered tool, plus the finalizer and normalizer, into another registry.
@@ -183,12 +200,12 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
      * The original definitions are reused rather than the compiled views, so the target applies
      * its own policy checks and binding exactly as it would for a first registration.
      */
-    copyTo(target: ToolLifecycleRegistry<Types, Tool>): void;
+    copyTo(target: ToolLifecycleRegistry<Types, Declaration>): void;
     /** Freeze the registry: no further registration, normalizer or finalizer is accepted. */
     seal(): this;
-    /** Tool that owns the invocation step named by the decision, if any. */
+    /** Tool that owns the invocation id named by the decision, if any. */
     private selected;
 }
-export type { ToolRuntimeTypes, LifecycleTool, RegisteredLifecycleTool, ToolLifecycleOptions, Policy, ToolInvocation, ToolContribution, ToolModelField, ToolNormalizer, ToolFinalizer, ToolJournal, ToolProtocol, LifecycleProtocol, } from '../structs/kits/tools.js';
+export type { ToolRuntimeTypes, Tool, ToolRegistration, RegisteredToolDefinition, ToolsOptions, Policy, LifecycleHooks, LifecycleProtocol, ToolModelField, ToolNormalizer, ToolFinalizer, ToolJournal, ToolProtocol, } from '../structs/kits/tools.js';
 /** The lifecycle registry is the public `Tools` Kit entry point. */
 export { ToolLifecycleRegistry as Tools };