@jangts/agent-core 0.3.6 → 0.5.0

package/dist/esm/kits/tools.js

@@ -1,11 +1,14 @@
 /**
- * Tools Kit: a lifecycle registry for domain tools with declared invocation and contribution.
+ * Tools Kit: a lifecycle registry for App-declared tools.
  *
  * 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
+ * definition — availability, one lifecycle hook set, 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.
  *
+ * A tool claims an invocation through `lifecycle.id` and, when a node dispatches by name, a
+ * delegate id through `delegate`. Both indexes live here, so dispatch is one lookup.
+ *
  * Exports: `ToolLifecycleRegistry` (also exported as `Tools`) and the tool lifecycle types.
  */
 import { assertion, booleanResult, synchronous } from '../utils/synchronous.js';
@@ -15,12 +18,34 @@ import { ToolRegistry } from '../capabilities/tools.js';
 import { executeInvocation } from '../capabilities/invocation.js';
 import { ProtocolRegistry } from '../utils/protocol-registry.js';
 import { registrationData } from '../utils/registration.js';
+import { ModelToolRegistry } from '../capabilities/model.js';
+import { toolActive } from '../capabilities/tool-conditions.js';
+/** Hooks that must finish with `undefined`; every other hook only rejects thenables. */
+const assertionHooks = ['authorize', 'inspect', 'finalize'];
+/** Every hook a lifecycle block may declare, in binding order. */
+const lifecycleHooks = [
+    'call',
+    'authorize',
+    'resume',
+    'complete',
+    'inspect',
+    'finalize',
+    'rules',
+    'modelFields',
+    'visibleText',
+    'reviewDraft',
+    'composition',
+    'recoveryContext',
+    'projectContext',
+    'missingInteractionAllowed',
+    'supportsGoal',
+];
 /** 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;
-    if (typeof intentIds !== 'function')
-        throw new TypeError('An intentIds provider is required');
-    const { kinds, isValidId, audiences, effects, intentExists, protocolVersion, tags, invalidTool, invalidInvocation, } = registration;
+    const { receiver, execution, errors, registration, invocationId, outputs, modelOutputs, unavailableInvocation, forbidden, contextFragment, goalIds, diagnostics, signal, journal, checkpoint, receipt, receiptError, } = options;
+    if (typeof goalIds !== 'function')
+        throw new TypeError('An goalIds provider is required');
+    const { kinds, isValidId, audiences, effects, goalExists, protocolVersion, tags, invalidTool, invalidInvocation, } = registration;
     return Object.freeze({
         receiver: receiver?.bind(options),
         execution: execution && Object.freeze({ signal: execution.signal, diagnostics: execution.diagnostics }),
@@ -34,7 +59,7 @@ function snapshotLifecycleOptions(options) {
             audiences: Object.freeze([...audiences]),
             effects: Object.freeze([...effects]),
             isValidId: isValidId.bind(registration),
-            intentExists: intentExists.bind(registration),
+            goalExists: goalExists.bind(registration),
             protocolVersion,
             tags: tags && Object.freeze([...tags]),
             invalidTool: typeof invalidTool === 'function' ? invalidTool.bind(registration) : invalidTool,
@@ -42,13 +67,13 @@ function snapshotLifecycleOptions(options) {
                 ? invalidInvocation.bind(registration)
                 : invalidInvocation,
         }),
-        step: step.bind(options),
+        invocationId: invocationId.bind(options),
         outputs: outputs.bind(options),
         modelOutputs: modelOutputs?.bind(options),
-        unavailableStep: unavailableStep?.bind(options),
+        unavailableInvocation: unavailableInvocation?.bind(options),
         forbidden: forbidden?.bind(options),
         contextFragment: contextFragment.bind(options),
-        intentIds: intentIds.bind(options),
+        goalIds: goalIds.bind(options),
         diagnostics: diagnostics?.bind(options),
         signal: signal?.bind(options),
         journal: journal?.bind(options),
@@ -57,18 +82,38 @@ function snapshotLifecycleOptions(options) {
         receiptError: receiptError?.bind(options),
     });
 }
+/** Bind every declared hook to its owner and freeze the result. */
+function bindLifecycle(value) {
+    return Object.freeze({
+        ...registrationData(value, [...lifecycleHooks, 'id', 'protocol']),
+        id: value.id,
+        protocol: value.protocol,
+        ...Object.fromEntries(lifecycleHooks.map((key) => {
+            const handler = value[key];
+            return [
+                key,
+                typeof handler === 'function'
+                    ? (...args) => (assertionHooks.includes(key) ? assertion : synchronous)(handler.apply(value, args), `Tool lifecycle ${key} must finish synchronously with the declared result`)
+                    : handler,
+            ];
+        })),
+    });
+}
 /**
- * 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 class ToolLifecycleRegistry {
     tools;
     registered = new Map();
     sources = new Map();
+    /** Tools that own an invocation id; dispatch by decision next reads this index. */
     invocations = new Map();
+    /** Tools that answer a delegate id; dispatch by node reads this index. */
+    delegateIndex = new Map();
     normalizer;
     finalizer;
     sealed = false;
@@ -79,7 +124,7 @@ export class ToolLifecycleRegistry {
     /**
      * @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) {
         this.options = snapshotLifecycleOptions(options);
@@ -114,17 +159,31 @@ export class ToolLifecycleRegistry {
      * 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) {
-        const { id, kind, description, audience, effect, intentIds, invocation, contribution, parseInput: inputParser, parseOutput: outputParser, available: availability, execute, debugSteps, } = input;
+        const { id, kind, description, audience, effect, goalIds, delegate, lifecycle, parseInput: inputParser, parseOutput: outputParser, active: 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 available = typeof availability === 'function' ? availability.bind(input) : availability;
+        const frozenGoalIds = Array.isArray(goalIds) ? Object.freeze([...goalIds]) : goalIds;
+        // Validate the declaration before projecting it into a model tool: a sealed or invalid
+        // registration must report its configured error instead of a schema-projection failure.
+        this.assertRegistration(input, { parseInput, parseOutput, execute });
+        const modelTool = new ModelToolRegistry([
+            {
+                id,
+                description,
+                inputSchema: input.inputSchema ?? { jsonSchema: { type: 'object' }, parse: parseInput },
+                resolve: input.resolve?.bind(input) ?? ((value) => ({ toolId: id, input: value })),
+                active: typeof input.active === 'function' ? input.active.bind(input) : input.active,
+                asIntent: typeof input.asIntent === 'function' ? input.asIntent.bind(input) : input.asIntent,
+            },
+        ]).require(id);
         const tool = {
             ...registrationData(input, [
                 'id',
@@ -132,148 +191,148 @@ export class ToolLifecycleRegistry {
                 'description',
                 'audience',
                 'effect',
-                'intentIds',
-                'invocation',
-                'contribution',
+                'goalIds',
+                'delegate',
+                'lifecycle',
                 'parseInput',
                 'parseOutput',
                 'execute',
                 'debugSteps',
-                'available',
+                'active',
             ]),
+            ...modelTool,
             id,
             kind,
             description,
             audience,
             effect,
-            invocation,
-            contribution,
-            intentIds: frozenIntents,
+            delegate,
+            lifecycle,
+            goalIds: frozenGoalIds,
             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,
+            active: available,
         };
-        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',
-                    ]),
-                }
-                : {}),
+            ...(lifecycle ? { lifecycle: bindLifecycle(lifecycle) } : {}),
         });
-        return this.install(input, registered);
+        return this.install(input, registered, true);
     }
-    install(input, tool) {
-        breakWhile(this.sealed, 'Tool registry is sealed');
+    /** Validate one declaration in the fixed order documented by `register`. */
+    assertRegistration(input, handlers) {
         const policy = this.options.registration;
         const identityPredicate = policy.isValidId;
         const isValidId = () => booleanResult(identityPredicate(input), 'Tool identity predicates must be synchronous', 'Tool identity predicates must return boolean');
         const invalid = policy.invalidTool ?? 'Invalid registered tool';
         const invalidInvocation = policy.invalidInvocation ?? 'Invalid or duplicate tool invocation';
+        const { lifecycle } = input;
+        // A lifecycle block may declare hooks only. Declaring any invocation part makes all three
+        // required, so a partial declaration fails instead of silently never running.
+        const ownsInvocation = !!lifecycle &&
+            (lifecycle.id !== undefined ||
+                lifecycle.protocol !== undefined ||
+                lifecycle.call !== undefined);
+        const { parseInput, parseOutput, execute } = handlers;
         breakWhile([
+            { occur: () => this.sealed, error: 'Tool registry is sealed', tags: ['sealed'] },
             {
-                occur: [() => !policy.kinds.includes(tool.kind), () => !isValidId()],
+                occur: [() => !policy.kinds.includes(input.kind), () => !isValidId()],
                 error: invalid,
                 tags: ['identity'],
             },
-            { occur: () => !tool.description.trim(), error: invalid, tags: ['description'] },
+            {
+                occur: () => typeof input.description !== 'string' || !input.description.trim(),
+                error: invalid,
+                tags: ['description'],
+            },
+            {
+                occur: () => input.active !== undefined &&
+                    typeof input.active !== 'boolean' &&
+                    typeof input.active !== 'function',
+                error: invalid,
+                tags: ['active'],
+            },
             {
                 occur: [
-                    () => !policy.audiences.includes(tool.audience),
-                    () => !policy.effects.includes(tool.effect),
+                    () => !policy.audiences.includes(input.audience),
+                    () => !policy.effects.includes(input.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' && new Set(tool.intentIds).size !== tool.intentIds.length,
+                    () => input.goalIds !== 'all' && !Array.isArray(input.goalIds),
+                    () => input.goalIds !== 'all' && !input.goalIds.length,
+                    () => input.goalIds !== 'all' &&
+                        input.goalIds.some((goal) => !booleanResult(policy.goalExists(goal), 'Goal lookup must return boolean synchronously')),
+                    () => input.goalIds !== 'all' && new Set(input.goalIds).size !== input.goalIds.length,
                 ],
                 error: invalid,
-                tags: ['intents'],
+                tags: ['goals'],
             },
             {
-                occur: () => ![tool.parseInput, tool.parseOutput, tool.execute].every((handler) => typeof handler === 'function'),
+                occur: () => ![parseInput, parseOutput, execute].every((handler) => typeof handler === 'function'),
                 error: invalid,
                 tags: ['handlers'],
             },
             {
-                occur: () => this.tools.has(tool.id),
-                error: () => new Error(`Duplicate registered tool: ${tool.id}`),
+                occur: () => this.tools.has(input.id),
+                error: () => new Error(`Duplicate registered tool: ${input.id}`),
                 tags: ['duplicate-name'],
             },
             {
-                occur: () => tool.invocation && !tool.invocation.step,
+                occur: () => !!input.delegate && this.delegateIndex.has(input.delegate),
+                error: () => new Error(`Duplicate registered delegate: ${input.delegate}`),
+                tags: ['delegate', 'duplicate-id'],
+            },
+            {
+                occur: () => ownsInvocation && !lifecycle.id,
                 error: invalidInvocation,
-                tags: ['invocation', 'step'],
+                tags: ['lifecycle', 'identity'],
             },
             {
-                occur: [
-                    () => tool.invocation && typeof tool.invocation.call !== 'function',
-                    () => tool.invocation && typeof tool.invocation.protocol?.keys !== 'function',
-                ],
+                occur: () => ownsInvocation && typeof lifecycle.call !== 'function',
+                error: invalidInvocation,
+                tags: ['lifecycle', 'contract'],
+            },
+            {
+                occur: () => ownsInvocation && typeof lifecycle.protocol?.keys !== 'function',
                 error: invalidInvocation,
-                tags: ['invocation', 'contract'],
+                tags: ['lifecycle', 'contract'],
             },
             {
-                occur: () => tool.invocation &&
+                occur: () => ownsInvocation &&
                     policy.protocolVersion !== undefined &&
-                    tool.invocation.protocol.version !== undefined &&
-                    tool.invocation.protocol.version !== policy.protocolVersion,
+                    lifecycle.protocol?.version !== undefined &&
+                    lifecycle.protocol.version !== policy.protocolVersion,
                 error: invalidInvocation,
-                tags: ['invocation', 'version'],
+                tags: ['lifecycle', 'version'],
             },
             {
-                occur: () => tool.invocation && this.invocations.has(tool.invocation.step),
+                occur: () => !!lifecycle?.id && this.invocations.has(lifecycle.id),
                 error: invalidInvocation,
-                tags: ['invocation', 'duplicate-step'],
+                tags: ['lifecycle', 'duplicate-id'],
             },
         ], policy.tags);
+    }
+    install(input, tool, validated = false) {
+        if (!validated)
+            this.assertRegistration(input, {
+                parseInput: tool.parseInput,
+                parseOutput: tool.parseOutput,
+                execute: tool.execute,
+            });
         this.tools.register(tool);
         this.registered.set(tool.id, tool);
         this.sources.set(tool.id, input);
-        if (tool.invocation)
-            this.invocations.set(tool.invocation.step, tool);
+        if (tool.lifecycle?.id)
+            this.invocations.set(tool.lifecycle.id, tool);
+        if (tool.delegate)
+            this.delegateIndex.set(tool.delegate, tool);
         return this;
     }
     /** Register every tool in iteration order. */
@@ -325,6 +384,10 @@ export class ToolLifecycleRegistry {
     values() {
         return this.registered.values();
     }
+    /** Whether a delegate id is claimed by a registered tool. */
+    hasDelegate(id) {
+        return this.delegateIndex.has(id);
+    }
     /**
      * Install the single normalization handler.
      *
@@ -360,134 +423,142 @@ export class ToolLifecycleRegistry {
         return synchronous(this.finalizer.call(receiver, receiver, decision, context), 'Tool finalization must be synchronous');
     }
     /**
-     * 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, context) {
-        const tool = this.invocations.get(step.type);
+    call(next, context) {
+        const tool = this.delegateIndex.get(next.type) ?? this.invocations.get(next.type);
         breakWhile([
             {
-                occur: () => !tool?.invocation,
-                error: () => this.options.unavailableStep?.(step.type) ??
-                    new Error(`Tool step is not registered: ${step.type}`),
+                occur: () => !tool?.lifecycle,
+                error: () => this.options.unavailableInvocation?.(next.type) ??
+                    new Error(`Tool invocation is not registered: ${next.type}`),
             },
             {
-                occur: () => tool.available && !tool.available(context),
+                occur: () => !toolActive(tool.active, context),
                 error: () => this.options.forbidden?.() ?? new Error('Tool is not available'),
             },
         ]);
         executeInvocation({
             id: tool.id,
-            call: (value, input, execution) => {
+            call: (input, executionContext, execution) => {
                 const previous = this.activeDiagnostics;
                 this.activeDiagnostics = execution.diagnostics;
                 try {
-                    tool.invocation.call(value, input, execution);
+                    tool.lifecycle.call(input, executionContext, execution);
                 }
                 finally {
                     this.activeDiagnostics = previous;
                 }
             },
-        }, step, context, this.invocationPorts);
+        }, next, context, this.invocationPorts);
     }
-    /** Output protocols plus one protocol per registered invocation step. */
+    /** Output protocols plus one protocol per registered invocation. */
     protocols() {
-        return new ProtocolRegistry([
-            ...this.options.outputs(),
-            ...[...this.invocations].map(([step, tool]) => [step, tool.invocation.protocol]),
-        ]);
+        return new ProtocolRegistry([...this.options.outputs(), ...this.invocationProtocols()]);
     }
     /**
-     * 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) {
         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]),
+            ...this.invocationProtocols((tool) => tool.audience === 'model' && toolActive(tool.active, context)),
         ]);
     }
-    /** Whether the protocol registered for this step is declared terminal. */
-    isTerminal(step) {
-        return this.protocols().get(step.type)?.terminal === true;
+    /** Whether the protocol registered for this invocation is declared terminal. */
+    isTerminal(next) {
+        return this.protocols().get(next.type)?.terminal === true;
+    }
+    /** `[invocationId, protocol]` pairs, optionally filtered by the owning tool. */
+    invocationProtocols(keep) {
+        return [...this.invocations]
+            .filter(([, tool]) => !keep || keep(tool))
+            .map(([id, tool]) => [id, tool.lifecycle.protocol]);
     }
-    /** Run contribution inspection for every tool, then the selected invocation's own check. */
+    /**
+     * 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, context) {
         for (const tool of this.registered.values())
-            tool.contribution?.inspect?.(decision, context);
-        this.selected(decision)?.invocation?.inspect?.(decision, context);
+            tool.lifecycle?.inspect?.(decision, context);
     }
     /** Run the selected invocation's authorization hook, if any. */
     authorize(decision, context) {
-        this.selected(decision)?.invocation?.authorize?.(decision, context);
+        this.selected(decision)?.lifecycle?.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')
+        const lifecycle = this.selected(decision)?.lifecycle;
+        return lifecycle?.resume
+            ? booleanResult(lifecycle.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);
+        return this.selected(decision)?.lifecycle?.complete?.(decision, context);
     }
-    /** 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) {
-        return [...this.registered.values()].reduce((current, tool) => tool.contribution?.projectContext?.(current) ?? current, value);
+        return [...this.registered.values()].reduce((current, tool) => tool.lifecycle?.projectContext?.(current) ?? current, value);
     }
-    /** Fold every contribution's visible-text transform over the text. */
+    /** Fold every tool's visible-text transform over the text. */
     visibleText(text, context) {
-        return [...this.registered.values()].reduce((value, tool) => tool.contribution?.visibleText?.(value, context) ?? value, text);
+        return [...this.registered.values()].reduce((value, tool) => tool.lifecycle?.visibleText?.(value, context) ?? value, text);
     }
-    /** Fold every contribution's review transform over the draft. */
+    /** Fold every tool's review transform over the draft. */
     reviewDraft(draft, context) {
-        return [...this.registered.values()].reduce((value, tool) => tool.contribution?.reviewDraft?.(value, context) ?? value, draft);
+        return [...this.registered.values()].reduce((value, tool) => tool.lifecycle?.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);
+            const value = tool.lifecycle?.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.
+     * @throws An error when more than one tool 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);
+            const value = tool.lifecycle?.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. */
+    /** Run every tool's finalize hook for the given phase. */
     finalize(decision, context, phase) {
         for (const tool of this.registered.values())
-            tool.contribution?.finalize?.(decision, context, phase);
+            tool.lifecycle?.finalize?.(decision, context, phase);
     }
-    /** Whether any contribution permits the interaction to be missing. */
+    /** Whether any tool 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')
+        return [...this.registered.values()].some((tool) => tool.lifecycle?.missingInteractionAllowed
+            ? booleanResult(tool.lifecycle.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) ?? [])
+            .flatMap((tool) => tool.lifecycle?.rules?.(context) ?? [])
             .sort((left, right) => left.order - right.order)
             .map((rule) => rule.text)
             .filter(Boolean)
@@ -496,7 +567,7 @@ export class ToolLifecycleRegistry {
     /** 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) ?? [])
+            .flatMap((tool) => (tool.lifecycle?.modelFields?.(context, placement) ?? [])
             .filter((field) => field.placement === placement)
             .map((field) => ({ tool, field })))
             .sort((left, right) => left.field.order - right.field.order)
@@ -504,11 +575,25 @@ export class ToolLifecycleRegistry {
     }
     /** 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);
+        const fields = {};
+        for (const { value } of this.contextFields(context, placement)) {
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                continue;
+            for (const [key, entry] of Object.entries(value))
+                // Own data properties keep keys such as `__proto__` from rewriting the merged result's
+                // prototype, matching how context assembly writes structured fields.
+                Object.defineProperty(fields, key, {
+                    value: entry,
+                    enumerable: true,
+                    configurable: true,
+                    writable: true,
+                });
+        }
+        return fields;
+    }
+    /** A tool may veto a goal by returning `false`; silence means support. */
+    supportsGoal(intentId, context) {
+        return [...this.registered.values()].every((tool) => tool.lifecycle?.supportsGoal?.(intentId, context) !== false);
     }
     /**
      * Describe registered tools, optionally limited by audience and availability.
@@ -518,19 +603,22 @@ export class ToolLifecycleRegistry {
      *
      * @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, context) {
         return [...this.registered.values()]
             .filter((tool) => (!audience || tool.audience === audience) &&
-            (!tool.available || (!!context && tool.available(context))))
-            .map(({ id, kind, description, audience, effect, intentIds }) => ({
+            (tool.active === undefined ||
+                (typeof tool.active === 'boolean'
+                    ? toolActive(tool.active, context)
+                    : !!context && toolActive(tool.active, context))))
+            .map(({ id, kind, description, audience, effect, goalIds }) => ({
             id,
             kind,
             description,
             audience,
             effect,
-            intentIds: intentIds === 'all' ? [...this.options.intentIds()] : [...intentIds],
+            goalIds: goalIds === 'all' ? [...this.options.goalIds()] : [...goalIds],
         }));
     }
     /**
@@ -553,9 +641,9 @@ export class ToolLifecycleRegistry {
         this.tools.seal();
         return 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. */
     selected(decision) {
-        return this.invocations.get(this.options.step(decision));
+        return this.invocations.get(this.options.invocationId(decision));
     }
 }
 /** The lifecycle registry is the public `Tools` Kit entry point. */