@jangts/agent-core 0.1.0 → 0.2.0

package/dist/esm/kits/tools.js

@@ -1,3 +1,13 @@
+/**
+ * Tools Kit: a lifecycle registry for domain tools with declared invocation and contribution.
+ *
+ * Place in the package: an optional App-side library for tools that need more than a plain
+ * definition — availability, per-step protocols, output ownership, context fields, task rules
+ * and delivery hooks. Actual invocation is delegated to Core (`ToolRegistry` and
+ * `executeInvocation`); domain predicates, phase names and vocabulary stay App configuration.
+ *
+ * Exports: `ToolLifecycleRegistry` (also exported as `Tools`) and the tool lifecycle types.
+ */
 import { assertion, booleanResult, synchronous } from '../utils/synchronous.js';
 import { toolInvocation } from '../utils/invocation.js';
 import { breakWhile } from '../utils/rules.js';
@@ -7,24 +17,53 @@ import { ProtocolRegistry } from '../utils/protocol-registry.js';
 import { registrationData } from '../utils/registration.js';
 /** Pin contract methods and configuration without cloning the App services they use. */
 function snapshotLifecycleOptions(options) {
-    const { receiver, execution, errors, registration, step, outputs, modelOutputs, unavailableStep, forbidden, contextFragment, intentIds, diagnostics, signal, journal, checkpoint, receipt, receiptError } = options;
+    const { receiver, execution, errors, registration, step, outputs, modelOutputs, unavailableStep, forbidden, contextFragment, intentIds, diagnostics, signal, journal, checkpoint, receipt, receiptError, } = options;
     if (typeof intentIds !== 'function')
         throw new TypeError('An intentIds provider is required');
-    const { kinds, isValidId, audiences, effects, intentExists, protocolVersion, tags, invalidTool, invalidInvocation } = registration;
+    const { kinds, isValidId, audiences, effects, intentExists, protocolVersion, tags, invalidTool, invalidInvocation, } = registration;
     return Object.freeze({
         receiver: receiver?.bind(options),
         execution: execution && Object.freeze({ signal: execution.signal, diagnostics: execution.diagnostics }),
-        errors: errors && Object.freeze({ unavailable: errors.unavailable?.bind(errors), errorCode: errors.errorCode?.bind(errors) }),
-        registration: Object.freeze({ kinds: Object.freeze([...kinds]), audiences: Object.freeze([...audiences]), effects: Object.freeze([...effects]),
-            isValidId: isValidId.bind(registration), intentExists: intentExists.bind(registration), protocolVersion,
-            tags: tags && Object.freeze([...tags]), invalidTool: typeof invalidTool === 'function' ? invalidTool.bind(registration) : invalidTool,
-            invalidInvocation: typeof invalidInvocation === 'function' ? invalidInvocation.bind(registration) : invalidInvocation }),
-        step: step.bind(options), outputs: outputs.bind(options), modelOutputs: modelOutputs?.bind(options),
-        unavailableStep: unavailableStep?.bind(options), forbidden: forbidden?.bind(options), contextFragment: contextFragment.bind(options),
-        intentIds: intentIds.bind(options), diagnostics: diagnostics?.bind(options), signal: signal?.bind(options),
-        journal: journal?.bind(options), checkpoint: checkpoint?.bind(options), receipt: receipt?.bind(options), receiptError: receiptError?.bind(options),
+        errors: errors &&
+            Object.freeze({
+                unavailable: errors.unavailable?.bind(errors),
+                errorCode: errors.errorCode?.bind(errors),
+            }),
+        registration: Object.freeze({
+            kinds: Object.freeze([...kinds]),
+            audiences: Object.freeze([...audiences]),
+            effects: Object.freeze([...effects]),
+            isValidId: isValidId.bind(registration),
+            intentExists: intentExists.bind(registration),
+            protocolVersion,
+            tags: tags && Object.freeze([...tags]),
+            invalidTool: typeof invalidTool === 'function' ? invalidTool.bind(registration) : invalidTool,
+            invalidInvocation: typeof invalidInvocation === 'function'
+                ? invalidInvocation.bind(registration)
+                : invalidInvocation,
+        }),
+        step: step.bind(options),
+        outputs: outputs.bind(options),
+        modelOutputs: modelOutputs?.bind(options),
+        unavailableStep: unavailableStep?.bind(options),
+        forbidden: forbidden?.bind(options),
+        contextFragment: contextFragment.bind(options),
+        intentIds: intentIds.bind(options),
+        diagnostics: diagnostics?.bind(options),
+        signal: signal?.bind(options),
+        journal: journal?.bind(options),
+        checkpoint: checkpoint?.bind(options),
+        receipt: receipt?.bind(options),
+        receiptError: receiptError?.bind(options),
     });
 }
+/**
+ * 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 class ToolLifecycleRegistry {
     tools;
     registered = new Map();
@@ -37,9 +76,17 @@ export class ToolLifecycleRegistry {
     activeDiagnostics;
     invocationPorts;
     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) {
         this.options = snapshotLifecycleOptions(options);
-        this.tools = new ToolRegistry({ execution: this.options.execution, errors: this.options.errors });
+        this.tools = new ToolRegistry({
+            execution: this.options.execution,
+            errors: this.options.errors,
+        });
         this.diagnostics = this.options.execution?.diagnostics;
         this.invocationPorts = Object.freeze({
             diagnostics: this.options.diagnostics ?? (() => this.diagnostics),
@@ -50,22 +97,104 @@ export class ToolLifecycleRegistry {
             receiptError: this.options.receiptError,
         });
     }
-    get events() { return this.tools.events; }
-    setDiagnostics(value) { this.diagnostics = value; this.tools.setDiagnostics(value); }
+    /** Core tool events, forwarded unchanged. */
+    get events() {
+        return this.tools.events;
+    }
+    /** Swap the diagnostics sink for later invocations; the Core registry is updated as well. */
+    setDiagnostics(value) {
+        this.diagnostics = value;
+        this.tools.setDiagnostics(value);
+    }
+    /**
+     * 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) {
-        const { id, kind, description, audience, effect, intentIds, invocation, contribution, parseInput: inputParser, parseOutput: outputParser, available: availability, execute, debugSteps } = input;
+        const { id, kind, description, audience, effect, intentIds, invocation, contribution, parseInput: inputParser, parseOutput: outputParser, available: availability, execute, debugSteps, } = input;
         const parseInput = inputParser?.bind(input), parseOutput = outputParser?.bind(input);
         const available = availability?.bind(input);
         const frozenIntents = Array.isArray(intentIds) ? Object.freeze([...intentIds]) : intentIds;
-        const tool = { ...registrationData(input, ['id', 'kind', 'description', 'audience', 'effect', 'intentIds', 'invocation', 'contribution', 'parseInput', 'parseOutput', 'execute', 'debugSteps', 'available']),
-            id, kind, description, audience, effect, invocation, contribution,
-            intentIds: frozenIntents, parseInput, parseOutput,
-            debugSteps: debugSteps?.bind(input), execute: execute?.bind(input), available: available ? (context) => booleanResult(available(context), 'Tool availability must be synchronous', 'Tool availability must return boolean') : undefined };
-        const bindMethods = (value, keys, data = {}) => Object.freeze({ ...registrationData(value, [...keys, ...Reflect.ownKeys(data)]), ...data,
-            ...Object.fromEntries(keys.map(key => { const handler = value[key]; return [key, typeof handler === 'function' ? (...args) => (['authorize', 'inspect', 'finalize'].includes(String(key)) ? assertion : synchronous)(handler.apply(value, args), `Tool lifecycle ${String(key)} must finish synchronously with the declared result`) : handler]; })) });
-        const registered = Object.freeze({ ...tool,
-            ...(invocation ? { invocation: bindMethods(invocation, ['call', 'inspect', 'authorize', 'resume', 'complete'], { step: invocation.step, protocol: invocation.protocol }) } : {}),
-            ...(contribution ? { contribution: bindMethods(contribution, ['composition', 'inspect', 'recoveryContext', 'projectContext', 'visibleText', 'reviewDraft', 'finalize', 'missingInteractionAllowed', 'rules', 'modelFields', 'supportsIntent']) } : {}),
+        const tool = {
+            ...registrationData(input, [
+                'id',
+                'kind',
+                'description',
+                'audience',
+                'effect',
+                'intentIds',
+                'invocation',
+                'contribution',
+                'parseInput',
+                'parseOutput',
+                'execute',
+                'debugSteps',
+                'available',
+            ]),
+            id,
+            kind,
+            description,
+            audience,
+            effect,
+            invocation,
+            contribution,
+            intentIds: frozenIntents,
+            parseInput,
+            parseOutput,
+            debugSteps: debugSteps?.bind(input),
+            execute: execute?.bind(input),
+            available: available
+                ? (context) => booleanResult(available(context), 'Tool availability must be synchronous', 'Tool availability must return boolean')
+                : undefined,
+        };
+        const bindMethods = (value, keys, data = {}) => Object.freeze({
+            ...registrationData(value, [...keys, ...Reflect.ownKeys(data)]),
+            ...data,
+            ...Object.fromEntries(keys.map((key) => {
+                const handler = value[key];
+                return [
+                    key,
+                    typeof handler === 'function'
+                        ? (...args) => (['authorize', 'inspect', 'finalize'].includes(String(key))
+                            ? assertion
+                            : synchronous)(handler.apply(value, args), `Tool lifecycle ${String(key)} must finish synchronously with the declared result`)
+                        : handler,
+                ];
+            })),
+        });
+        const registered = Object.freeze({
+            ...tool,
+            ...(invocation
+                ? {
+                    invocation: bindMethods(invocation, ['call', 'inspect', 'authorize', 'resume', 'complete'], { step: invocation.step, protocol: invocation.protocol }),
+                }
+                : {}),
+            ...(contribution
+                ? {
+                    contribution: bindMethods(contribution, [
+                        'composition',
+                        'inspect',
+                        'recoveryContext',
+                        'projectContext',
+                        'visibleText',
+                        'reviewDraft',
+                        'finalize',
+                        'missingInteractionAllowed',
+                        'rules',
+                        'modelFields',
+                        'supportsIntent',
+                    ]),
+                }
+                : {}),
         });
         return this.install(input, registered);
     }
@@ -77,29 +206,67 @@ export class ToolLifecycleRegistry {
         const invalid = policy.invalidTool ?? 'Invalid registered tool';
         const invalidInvocation = policy.invalidInvocation ?? 'Invalid or duplicate tool invocation';
         breakWhile([
-            { occur: [() => !policy.kinds.includes(tool.kind), () => !isValidId()], error: invalid, tags: ['identity'] },
+            {
+                occur: [() => !policy.kinds.includes(tool.kind), () => !isValidId()],
+                error: invalid,
+                tags: ['identity'],
+            },
             { occur: () => !tool.description.trim(), error: invalid, tags: ['description'] },
-            { occur: [() => !policy.audiences.includes(tool.audience), () => !policy.effects.includes(tool.effect)], error: invalid, tags: ['execution-contract'] },
+            {
+                occur: [
+                    () => !policy.audiences.includes(tool.audience),
+                    () => !policy.effects.includes(tool.effect),
+                ],
+                error: invalid,
+                tags: ['execution-contract'],
+            },
             {
                 occur: [
                     () => tool.intentIds !== 'all' && !Array.isArray(tool.intentIds),
                     () => tool.intentIds !== 'all' && !tool.intentIds.length,
-                    () => tool.intentIds !== 'all' && tool.intentIds.some(goal => !booleanResult(policy.intentExists(goal), 'Intent lookup must return boolean synchronously')),
+                    () => tool.intentIds !== 'all' &&
+                        tool.intentIds.some((goal) => !booleanResult(policy.intentExists(goal), 'Intent lookup must return boolean synchronously')),
                     () => tool.intentIds !== 'all' && new Set(tool.intentIds).size !== tool.intentIds.length,
-                ], error: invalid, tags: ['intents'],
+                ],
+                error: invalid,
+                tags: ['intents'],
+            },
+            {
+                occur: () => ![tool.parseInput, tool.parseOutput, tool.execute].every((handler) => typeof handler === 'function'),
+                error: invalid,
+                tags: ['handlers'],
             },
-            { occur: () => ![tool.parseInput, tool.parseOutput, tool.execute].every(handler => typeof handler === 'function'), error: invalid, tags: ['handlers'] },
-            { occur: () => this.tools.has(tool.id), error: () => new Error(`Duplicate registered tool: ${tool.id}`), tags: ['duplicate-name'] },
-            { occur: () => tool.invocation && !tool.invocation.step, error: invalidInvocation, tags: ['invocation', 'step'] },
             {
-                occur: [() => tool.invocation && typeof tool.invocation.call !== 'function', () => tool.invocation && typeof tool.invocation.protocol?.keys !== 'function'],
-                error: invalidInvocation, tags: ['invocation', 'contract'],
+                occur: () => this.tools.has(tool.id),
+                error: () => new Error(`Duplicate registered tool: ${tool.id}`),
+                tags: ['duplicate-name'],
             },
             {
-                occur: () => tool.invocation && policy.protocolVersion !== undefined && tool.invocation.protocol.version !== undefined && tool.invocation.protocol.version !== policy.protocolVersion,
-                error: invalidInvocation, tags: ['invocation', 'version'],
+                occur: () => tool.invocation && !tool.invocation.step,
+                error: invalidInvocation,
+                tags: ['invocation', 'step'],
+            },
+            {
+                occur: [
+                    () => tool.invocation && typeof tool.invocation.call !== 'function',
+                    () => tool.invocation && typeof tool.invocation.protocol?.keys !== 'function',
+                ],
+                error: invalidInvocation,
+                tags: ['invocation', 'contract'],
+            },
+            {
+                occur: () => tool.invocation &&
+                    policy.protocolVersion !== undefined &&
+                    tool.invocation.protocol.version !== undefined &&
+                    tool.invocation.protocol.version !== policy.protocolVersion,
+                error: invalidInvocation,
+                tags: ['invocation', 'version'],
+            },
+            {
+                occur: () => tool.invocation && this.invocations.has(tool.invocation.step),
+                error: invalidInvocation,
+                tags: ['invocation', 'duplicate-step'],
             },
-            { occur: () => tool.invocation && this.invocations.has(tool.invocation.step), error: invalidInvocation, tags: ['invocation', 'duplicate-step'] },
         ], policy.tags);
         this.tools.register(tool);
         this.registered.set(tool.id, tool);
@@ -108,41 +275,115 @@ export class ToolLifecycleRegistry {
             this.invocations.set(tool.invocation.step, tool);
         return this;
     }
-    registerAll(tools) { for (const tool of tools)
-        this.register(tool); return this; }
+    /** Register every tool in iteration order. */
+    registerAll(tools) {
+        for (const tool of tools)
+            this.register(tool);
+        return 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) {
         const call = toolInvocation(request, arguments.length);
         return this.tools.invoke({ ...call, diagnostics: call.diagnostics ?? this.activeDiagnostics });
     }
-    get definitions() { return Object.freeze([...this.registered.values()]); }
-    ids() { return this.tools.ids(); }
-    entries() { return this.registered.entries(); }
-    get(id) { return this.registered.get(id); }
-    require(id) { this.tools.require(id); return this.registered.get(id); }
-    has(name) { return this.tools.has(name); }
-    values() { return this.registered.values(); }
+    /** Registered tools in registration order. */
+    get definitions() {
+        return Object.freeze([...this.registered.values()]);
+    }
+    /** Registered tool ids, delegated to the Core registry. */
+    ids() {
+        return this.tools.ids();
+    }
+    /** Iterate `[id, tool]` pairs. */
+    entries() {
+        return this.registered.entries();
+    }
+    /** Registered tool for `id`, or `undefined` when it is absent. */
+    get(id) {
+        return this.registered.get(id);
+    }
+    /**
+     * Registered tool for `id`.
+     *
+     * @throws TypeError When the id is not registered.
+     */
+    require(id) {
+        this.tools.require(id);
+        return this.registered.get(id);
+    }
+    /** Whether a tool id is registered. */
+    has(name) {
+        return this.tools.has(name);
+    }
+    /** Iterate the registered tools. */
+    values() {
+        return this.registered.values();
+    }
+    /**
+     * 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) {
         breakWhile(this.sealed || this.normalizer, 'Normalizer already registered or registry sealed');
         this.normalizer = handler;
     }
+    /** Apply the installed normalizer, or return the value unchanged when none exists. */
     normalize(value, ...args) {
-        return this.normalizer ? synchronous(this.normalizer.call(this.options.receiver?.() ?? this, value, ...args), 'Tool normalization must be synchronous') : value;
+        return this.normalizer
+            ? synchronous(this.normalizer.call(this.options.receiver?.() ?? this, value, ...args), 'Tool normalization must be synchronous')
+            : value;
     }
+    /**
+     * Install the single reply finalizer.
+     *
+     * @throws An error when a finalizer is already installed or the registry is sealed.
+     */
     registerFinalizer(handler) {
         breakWhile(this.sealed || this.finalizer, 'Finalizer already registered or registry sealed');
         this.finalizer = handler;
     }
+    /**
+     * Run the installed finalizer over a decision.
+     *
+     * @throws An error when no finalizer is installed, or when it does not finish synchronously.
+     */
     finish(receiver, decision, context) {
         breakWhile(!this.finalizer, 'No registered reply finalizer');
         return synchronous(this.finalizer.call(receiver, receiver, decision, context), 'Tool finalization must be synchronous');
     }
+    /**
+     * 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, context) {
         const tool = this.invocations.get(step.type);
         breakWhile([
-            { occur: () => !tool?.invocation, error: () => this.options.unavailableStep?.(step.type) ?? new Error(`Tool step is not registered: ${step.type}`) },
-            { occur: () => tool.available && !tool.available(context), error: () => this.options.forbidden?.() ?? new Error('Tool is not available') },
+            {
+                occur: () => !tool?.invocation,
+                error: () => this.options.unavailableStep?.(step.type) ??
+                    new Error(`Tool step is not registered: ${step.type}`),
+            },
+            {
+                occur: () => tool.available && !tool.available(context),
+                error: () => this.options.forbidden?.() ?? new Error('Tool is not available'),
+            },
         ]);
-        executeInvocation({ id: tool.id, call: (value, input, execution) => {
+        executeInvocation({
+            id: tool.id,
+            call: (value, input, execution) => {
                 const previous = this.activeDiagnostics;
                 this.activeDiagnostics = execution.diagnostics;
                 try {
@@ -151,60 +392,152 @@ export class ToolLifecycleRegistry {
                 finally {
                     this.activeDiagnostics = previous;
                 }
-            } }, step, context, this.invocationPorts);
+            },
+        }, step, context, this.invocationPorts);
     }
+    /** Output protocols plus one protocol per registered invocation step. */
     protocols() {
-        return new ProtocolRegistry([...this.options.outputs(), ...[...this.invocations].map(([step, tool]) => [step, tool.invocation.protocol])]);
+        return new ProtocolRegistry([
+            ...this.options.outputs(),
+            ...[...this.invocations].map(([step, tool]) => [step, tool.invocation.protocol]),
+        ]);
     }
+    /**
+     * Protocols exposed to the model: output protocols plus steps whose audience is `model` and
+     * which are currently available in `context`.
+     */
     modelProtocols(context) {
-        return new ProtocolRegistry([...(this.options.modelOutputs?.(context) ?? this.options.outputs()), ...[...this.invocations]
+        return new ProtocolRegistry([
+            ...(this.options.modelOutputs?.(context) ?? this.options.outputs()),
+            ...[...this.invocations]
                 .filter(([, tool]) => tool.audience === 'model' && (!tool.available || tool.available(context)))
-                .map(([step, tool]) => [step, tool.invocation.protocol])]);
+                .map(([step, tool]) => [step, tool.invocation.protocol]),
+        ]);
+    }
+    /** Whether the protocol registered for this step is declared terminal. */
+    isTerminal(step) {
+        return this.protocols().get(step.type)?.terminal === true;
     }
-    isTerminal(step) { return this.protocols().get(step.type)?.terminal === true; }
+    /** Run contribution inspection for every tool, then the selected invocation's own check. */
     assertDecision(decision, context) {
         for (const tool of this.registered.values())
             tool.contribution?.inspect?.(decision, context);
         this.selected(decision)?.invocation?.inspect?.(decision, context);
     }
-    authorize(decision, context) { this.selected(decision)?.invocation?.authorize?.(decision, context); }
-    resume(decision, context) { const invocation = this.selected(decision)?.invocation; return invocation?.resume ? booleanResult(invocation.resume(decision, context), 'Tool resume must return boolean synchronously') : false; }
-    complete(decision, context) { return this.selected(decision)?.invocation?.complete?.(decision, context); }
-    projectContext(value) { return [...this.registered.values()].reduce((current, tool) => tool.contribution?.projectContext?.(current) ?? current, value); }
-    visibleText(text, context) { return [...this.registered.values()].reduce((value, tool) => tool.contribution?.visibleText?.(value, context) ?? value, text); }
-    reviewDraft(draft, context) { return [...this.registered.values()].reduce((value, tool) => tool.contribution?.reviewDraft?.(value, context) ?? value, draft); }
+    /** Run the selected invocation's authorization hook, if any. */
+    authorize(decision, context) {
+        this.selected(decision)?.invocation?.authorize?.(decision, context);
+    }
+    /** Whether the selected invocation should resume rather than start fresh; defaults to false. */
+    resume(decision, context) {
+        const invocation = this.selected(decision)?.invocation;
+        return invocation?.resume
+            ? booleanResult(invocation.resume(decision, context), 'Tool resume must return boolean synchronously')
+            : false;
+    }
+    /** Let the selected invocation rewrite the decision on completion, if it declares a hook. */
+    complete(decision, context) {
+        return this.selected(decision)?.invocation?.complete?.(decision, context);
+    }
+    /** Fold every contribution's context projection over the value, in registration order. */
+    projectContext(value) {
+        return [...this.registered.values()].reduce((current, tool) => tool.contribution?.projectContext?.(current) ?? current, value);
+    }
+    /** Fold every contribution's visible-text transform over the text. */
+    visibleText(text, context) {
+        return [...this.registered.values()].reduce((value, tool) => tool.contribution?.visibleText?.(value, context) ?? value, text);
+    }
+    /** Fold every contribution's review transform over the draft. */
+    reviewDraft(draft, context) {
+        return [...this.registered.values()].reduce((value, tool) => tool.contribution?.reviewDraft?.(value, context) ?? value, draft);
+    }
+    /** Collected recovery context values; `undefined` results are omitted. */
     recoveryContext(context) {
-        return [...this.registered.values()].flatMap(tool => { const value = tool.contribution?.recoveryContext?.(context); return value === undefined ? [] : [value]; });
+        return [...this.registered.values()].flatMap((tool) => {
+            const value = tool.contribution?.recoveryContext?.(context);
+            return value === undefined ? [] : [value];
+        });
     }
+    /**
+     * 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) {
-        const values = [...this.registered.values()].flatMap(tool => { const value = tool.contribution?.composition?.(context); return value ? [value] : []; });
+        const values = [...this.registered.values()].flatMap((tool) => {
+            const value = tool.contribution?.composition?.(context);
+            return value ? [value] : [];
+        });
         breakWhile(values.length > 1, 'More than one output template owns this delivery');
         return values[0];
     }
+    /** Run every contribution's finalize hook for the given phase. */
     finalize(decision, context, phase) {
         for (const tool of this.registered.values())
             tool.contribution?.finalize?.(decision, context, phase);
     }
+    /** Whether any contribution permits the interaction to be missing. */
     missingInteractionAllowed(decision, context) {
-        return [...this.registered.values()].some(tool => tool.contribution?.missingInteractionAllowed ? booleanResult(tool.contribution.missingInteractionAllowed(decision, context), 'Missing interaction predicates must return boolean synchronously') : false);
+        return [...this.registered.values()].some((tool) => tool.contribution?.missingInteractionAllowed
+            ? booleanResult(tool.contribution.missingInteractionAllowed(decision, context), 'Missing interaction predicates must return boolean synchronously')
+            : false);
     }
+    /** Task rules ordered by their declared `order`, joined into one prompt block. */
     taskRules(context) {
-        return [...this.registered.values()].flatMap(tool => tool.contribution?.rules?.(context) ?? [])
-            .sort((left, right) => left.order - right.order).map(rule => rule.text).filter(Boolean).join('\n\n');
+        return [...this.registered.values()]
+            .flatMap((tool) => tool.contribution?.rules?.(context) ?? [])
+            .sort((left, right) => left.order - right.order)
+            .map((rule) => rule.text)
+            .filter(Boolean)
+            .join('\n\n');
     }
+    /** Model-context fragments for one placement, ordered by each field's `order`. */
     contextFields(context, placement) {
-        return [...this.registered.values()].flatMap(tool => (tool.contribution?.modelFields?.(context, placement) ?? [])
-            .filter(field => field.placement === placement).map(field => ({ tool, field })))
+        return [...this.registered.values()]
+            .flatMap((tool) => (tool.contribution?.modelFields?.(context, placement) ?? [])
+            .filter((field) => field.placement === placement)
+            .map((field) => ({ tool, field })))
             .sort((left, right) => left.field.order - right.field.order)
             .map(({ tool, field }) => this.options.contextFragment(this.sources.get(tool.id), field));
     }
-    modelFields(context, placement) { return Object.assign({}, ...this.contextFields(context, placement).map(fragment => fragment.value)); }
-    supportsIntent(intentId, context) { return [...this.registered.values()].every(tool => tool.contribution?.supportsIntent?.(intentId, context) !== false); }
+    /** Merged model-context values for one placement; later fragments win per key. */
+    modelFields(context, placement) {
+        return Object.assign({}, ...this.contextFields(context, placement).map((fragment) => fragment.value));
+    }
+    /** A contribution may veto an intent by returning `false`; silence means support. */
+    supportsIntent(intentId, context) {
+        return [...this.registered.values()].every((tool) => tool.contribution?.supportsIntent?.(intentId, context) !== false);
+    }
+    /**
+     * 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, context) {
-        return [...this.registered.values()].filter(tool => (!audience || tool.audience === audience) && (!tool.available || (!!context && tool.available(context))))
-            .map(({ id, kind, description, audience, effect, intentIds }) => ({ id, kind, description, audience, effect,
-            intentIds: intentIds === 'all' ? [...this.options.intentIds()] : [...intentIds] }));
+        return [...this.registered.values()]
+            .filter((tool) => (!audience || tool.audience === audience) &&
+            (!tool.available || (!!context && tool.available(context))))
+            .map(({ id, kind, description, audience, effect, intentIds }) => ({
+            id,
+            kind,
+            description,
+            audience,
+            effect,
+            intentIds: intentIds === 'all' ? [...this.options.intentIds()] : [...intentIds],
+        }));
     }
+    /**
+     * 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) {
         for (const tool of this.registered.values())
             target.install(this.sources.get(tool.id), tool);
@@ -213,7 +546,16 @@ export class ToolLifecycleRegistry {
         if (this.normalizer)
             target.registerNormalizer(this.normalizer);
     }
-    seal() { this.sealed = true; this.tools.seal(); return this; }
-    selected(decision) { return this.invocations.get(this.options.step(decision)); }
+    /** Freeze the registry: no further registration, normalizer or finalizer is accepted. */
+    seal() {
+        this.sealed = true;
+        this.tools.seal();
+        return this;
+    }
+    /** Tool that owns the invocation step named by the decision, if any. */
+    selected(decision) {
+        return this.invocations.get(this.options.step(decision));
+    }
 }
+/** The lifecycle registry is the public `Tools` Kit entry point. */
 export { ToolLifecycleRegistry as Tools };