@jangts/agent-core 0.1.0 → 0.2.0

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

@@ -3,8 +3,18 @@ import type { ToolResult } from '../structs/invocation.js';
 import type { ToolRuntimeTypes, LifecycleTool, RegisteredLifecycleTool, ToolLifecycleOptions, 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 and delivery hooks. Domain predicates and phase names are host
+ * configuration.
+ */
 type PreparedTool<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> = RegisteredLifecycleTool<Types, Tool> & LifecycleTool<Types>;
+/**
+ * Registry of tools whose lifecycle, protocols and contributions are declared by the App.
+ *
+ * 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.
+ */
 export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types> = LifecycleTool<Types>> {
     private readonly tools;
     private readonly registered;
@@ -17,47 +27,148 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
     private activeDiagnostics?;
     private readonly invocationPorts;
     private readonly options;
+    /**
+     * @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.
+     */
     constructor(options: ToolLifecycleOptions<Types, Tool>);
+    /** Core tool events, forwarded unchanged. */
     get events(): readonly Readonly<import("../index.js").ToolExecutionEvent<PreparedTool<Types, Tool>["kind"]>>[];
+    /** Swap the diagnostics sink for later invocations; the Core registry is updated as well. */
     setDiagnostics(value: ToolRegistryPorts['diagnostics']): void;
+    /**
+     * Register and freeze one tool definition.
+     *
+     * Handlers are bound to the original object; authorization, inspection and finalization
+     * 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.
+     * @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.
+     */
     register(input: Tool): this;
     private install;
+    /** Register every tool in iteration order. */
     registerAll(tools: Iterable<Tool>): this;
+    /**
+     * Invoke one Core tool by its already-validated request.
+     *
+     * When the request carries no diagnostics, the currently active one is used, so a call made
+     * from inside a tool inherits that tool's diagnostic context.
+     */
     invoke(request: ToolInvocationRequest): ToolResult<unknown>;
+    /** Registered tools in registration order. */
     get definitions(): readonly RegisteredLifecycleTool<Types, Tool>[];
+    /** Registered tool ids, delegated to the Core registry. */
     ids(): readonly string[];
+    /** Iterate `[id, tool]` pairs. */
     entries(): IterableIterator<[string, RegisteredLifecycleTool<Types, Tool>]>;
+    /** Registered tool for `id`, or `undefined` when it is absent. */
     get(id: string): RegisteredLifecycleTool<Types, Tool> | undefined;
+    /**
+     * Registered tool for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
     require(id: string): RegisteredLifecycleTool<Types, Tool>;
+    /** Whether a tool id is registered. */
     has(name: string): boolean;
+    /** Iterate the registered tools. */
     values(): IterableIterator<RegisteredLifecycleTool<Types, Tool>>;
+    /**
+     * Install the single normalization handler.
+     *
+     * @throws An error when a handler is already installed or the registry is sealed, because a
+     *   second handler would make normalization order ambiguous.
+     */
     registerNormalizer(handler: ToolNormalizer<Types>): void;
+    /** Apply the installed normalizer, or return the value unchanged when none exists. */
     normalize(value: unknown, ...args: Types['normalizerArgs']): unknown;
+    /**
+     * Install the single reply finalizer.
+     *
+     * @throws An error when a finalizer is already installed or the registry is sealed.
+     */
     registerFinalizer(handler: ToolFinalizer<Types>): void;
+    /**
+     * Run the installed finalizer over a decision.
+     *
+     * @throws An error when no finalizer is installed, or when it does not finish synchronously.
+     */
     finish(receiver: Types['receiver'], decision: Types['decision'], context: Types['context']): Types['result'];
+    /**
+     * Execute the invocation registered for a step type.
+     *
+     * 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 context - Execution context forwarded to Core's invocation executor.
+     * @throws A configured error when the step is unknown or the tool is unavailable.
+     */
     call(step: {
         type: string;
     }, context: Types['context']): void;
+    /** Output protocols plus one protocol per registered invocation step. */
     protocols(): ProtocolRegistry<ToolProtocol<Tool>>;
+    /**
+     * Protocols exposed to the model: output protocols plus steps 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: {
         type: string;
     }): boolean;
+    /** Run contribution inspection for every tool, then the selected invocation's own check. */
     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;
+    /** Whether the selected invocation should resume rather than start fresh; defaults to false. */
     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. */
     projectContext(value: unknown): unknown;
+    /** Fold every contribution's visible-text transform over the text. */
     visibleText(text: string, context: Types['context']): string;
+    /** Fold every contribution'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.
+     */
     composition(context: Types['context']): Types['composition'] | undefined;
+    /** Run every contribution'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. */
     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;
+    /**
+     * Describe registered tools, optionally limited by audience and availability.
+     *
+     * A tool with an `available` predicate is only listed when a context is supplied and the
+     * predicate holds, so a caller that omits the context sees just the unconditional tools.
+     *
+     * @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.
+     */
     describe(audience?: string, context?: Types['context']): {
         id: Tool['id'];
         kind: Tool['kind'];
@@ -66,9 +177,18 @@ export declare class ToolLifecycleRegistry<Types extends ToolRuntimeTypes, Tool
         effect: Tool['effect'];
         intentIds: string[];
     }[];
+    /**
+     * Reinstall every registered tool, plus the finalizer and normalizer, into another registry.
+     *
+     * 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;
+    /** 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. */
     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, LifecycleTool, RegisteredLifecycleTool, ToolLifecycleOptions, Policy, ToolInvocation, ToolContribution, ToolModelField, ToolNormalizer, ToolFinalizer, ToolJournal, ToolProtocol, LifecycleProtocol, } from '../structs/kits/tools.js';
+/** The lifecycle registry is the public `Tools` Kit entry point. */
 export { ToolLifecycleRegistry as Tools };