@jangts/agent-core 0.3.6 → 0.5.0

package/dist/esm/kits/presentation/formats.js

@@ -0,0 +1,105 @@
+/**
+ * Presentation Kit: template-bound reply formats and their shared checks.
+ *
+ * Place in the package: part of the `presentation` Kit. A format is declared only where the App
+ * owns a template for the final reply; `resolve` returns `undefined` for every other reply, so the
+ * caller has no output-format requirement and does not re-ask the model. Apps keep their own copy,
+ * limits and checks; this module only compiles the declarations and evaluates failures.
+ *
+ * Exports: `defineReplyFormats`, `replyFormatChecks`, `mergeReplyBubbles`, and their types.
+ */
+import { breakWhile } from '../../utils/rules.js';
+const validId = (id) => typeof id === 'string' && /^[a-z][a-z0-9-]*$/.test(id);
+/**
+ * Checks shared by text replies. Limits stay with the App template; only the comparison lives here.
+ */
+export const replyFormatChecks = Object.freeze({
+    /**
+     * Every bubble is non-empty and the total (primary text included) stays within the limit.
+     *
+     * @param totalLimit - Maximum bubble count including the primary text.
+     * @returns The reusable `bubbles` check.
+     */
+    bubbles(totalLimit) {
+        breakWhile(!Number.isSafeInteger(totalLimit) || totalLimit < 1, 'Bubble limit must be a positive integer');
+        return Object.freeze({
+            id: 'bubbles',
+            description: `回复气泡总数不超过 ${totalLimit} 条且每条非空。`,
+            accepts: (bubbles) => bubbles.length >= 1 &&
+                bubbles.length <= totalLimit &&
+                bubbles.every((text) => typeof text === 'string' && !!text.trim()),
+        });
+    },
+    /**
+     * The joined reply stays within the app's text budget.
+     *
+     * @param maxChars - Maximum total characters across bubbles.
+     * @returns The reusable `text-budget` check.
+     */
+    textBudget(maxChars) {
+        breakWhile(!Number.isSafeInteger(maxChars) || maxChars < 1, 'Text budget must be a positive integer');
+        return Object.freeze({
+            id: 'text-budget',
+            description: `回复正文总长不超过 ${maxChars} 字符。`,
+            accepts: (bubbles) => bubbles.reduce((length, text) => length + (typeof text === 'string' ? text.length : 0), 0) <= maxChars,
+        });
+    },
+});
+/**
+ * Normalize a reply that has no declared format: drop blank bubbles and merge overflow into the
+ * last allowed one. Text content is preserved.
+ *
+ * @param bubbles - Primary text followed by follow-up bubbles.
+ * @param limit - Maximum number of bubbles to keep.
+ * @returns Non-empty bubbles within the limit.
+ */
+export function mergeReplyBubbles(bubbles, limit) {
+    breakWhile(!Number.isSafeInteger(limit) || limit < 1, 'Bubble limit must be a positive integer');
+    const kept = bubbles.map((text) => text.trim()).filter(Boolean);
+    // 超出部分按原顺序合并到最后一条允许的气泡，不改变正文内容。
+    if (kept.length > limit)
+        kept.push(kept.splice(limit - 1).join('\n\n'));
+    return kept;
+}
+/**
+ * Compile reply formats so that checks run only for templates the current turn uses.
+ *
+ * @param options - Declared formats and the checks their ids refer to.
+ * @returns A frozen catalog with `resolve(context)`.
+ * @throws TypeError For duplicate or invalid ids, a format without checks, an unknown check id,
+ *   or a non-function `when`/`accepts`.
+ */
+export function defineReplyFormats(options) {
+    const { formats, checks } = options;
+    breakWhile(!formats?.length || !checks?.length, 'Reply formats require formats and checks');
+    const checkMap = new Map();
+    for (const check of checks) {
+        breakWhile(!validId(check.id) || checkMap.has(check.id) || typeof check.accepts !== 'function', 'Invalid reply format check');
+        checkMap.set(check.id, Object.freeze({ ...check, accepts: check.accepts.bind(check) }));
+    }
+    const seen = new Set();
+    const compiled = formats.map((format) => {
+        breakWhile(!validId(format.id) ||
+            seen.has(format.id) ||
+            typeof format.when !== 'function' ||
+            !format.checks?.length ||
+            format.checks.some((id) => !checkMap.has(id)), 'Invalid reply format');
+        seen.add(format.id);
+        const required = Object.freeze([...format.checks]);
+        return Object.freeze({
+            id: format.id,
+            description: format.description,
+            checks: required,
+            when: format.when,
+            inspect(bubbles) {
+                return required.map((id) => checkMap.get(id)).filter((check) => !check.accepts(bubbles));
+            },
+        });
+    });
+    return Object.freeze({
+        /** The template this turn uses, or `undefined` when it has no output-format requirement. */
+        resolve(context) {
+            return compiled.find((format) => format.when(context));
+        },
+    });
+}

package/dist/esm/kits/presentation/index.d.ts

@@ -1,26 +1,35 @@
 /**
- * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
- * reply/chunk event stream.
+ * Presentation Kit entry: output contracts, text templates, semantic slots, reply formats,
+ * variants and the reply/chunk event stream.
  *
  * Place in the package: an optional App-side library for shaping what the user finally sees.
  * The App owns copy, styling and transport; this directory owns contract validation, template
- * substitution, variant selection and the bubble/chunk protocol.
+ * substitution, format checks, variant selection and the bubble/chunk protocol.
  *
- * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
- * plus the `Presentation` namespace object.
+ * Exports: everything from `./outputs.js`, `./formats.js`, `./variants.js`, `./templates.js` and
+ * `./events.js`, plus the `Presentation` namespace object.
  */
 export * from './outputs.js';
+export * from './formats.js';
 export * from './variants.js';
 export type * from '../../structs/kits/presentation/outputs.js';
+export type * from '../../structs/kits/presentation/formats.js';
 export * from './templates.js';
 export * from './events.js';
 import { defineOutputCatalog } from './outputs.js';
+import { defineReplyFormats, mergeReplyBubbles } from './formats.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
 import { replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents } from './events.js';
 /** Namespace object for callers that prefer one import over named helpers. */
 export declare const Presentation: Readonly<{
     defineOutputCatalog: typeof defineOutputCatalog;
+    defineReplyFormats: typeof defineReplyFormats;
+    replyFormatChecks: Readonly<{
+        bubbles(totalLimit: number): import("./formats.js").ReplyFormatCheck;
+        textBudget(maxChars: number): import("./formats.js").ReplyFormatCheck;
+    }>;
+    mergeReplyBubbles: typeof mergeReplyBubbles;
     defineTextTemplate: typeof defineTextTemplate;
     defineSemanticSlots: typeof defineSemanticSlots;
     selectVariant: typeof selectVariant;

package/dist/esm/kits/presentation/index.js

@@ -1,25 +1,30 @@
 /**
- * Presentation Kit entry: output contracts, text templates, semantic slots, variants and the
- * reply/chunk event stream.
+ * Presentation Kit entry: output contracts, text templates, semantic slots, reply formats,
+ * variants and the reply/chunk event stream.
  *
  * Place in the package: an optional App-side library for shaping what the user finally sees.
  * The App owns copy, styling and transport; this directory owns contract validation, template
- * substitution, variant selection and the bubble/chunk protocol.
+ * substitution, format checks, variant selection and the bubble/chunk protocol.
  *
- * Exports: everything from `./outputs.js`, `./variants.js`, `./templates.js` and `./events.js`,
- * plus the `Presentation` namespace object.
+ * Exports: everything from `./outputs.js`, `./formats.js`, `./variants.js`, `./templates.js` and
+ * `./events.js`, plus the `Presentation` namespace object.
  */
 export * from './outputs.js';
+export * from './formats.js';
 export * from './variants.js';
 export * from './templates.js';
 export * from './events.js';
 import { defineOutputCatalog } from './outputs.js';
+import { defineReplyFormats, mergeReplyBubbles, replyFormatChecks } from './formats.js';
 import { defineTextTemplate, defineSemanticSlots } from './templates.js';
 import { selectVariant, resolvePreference } from './variants.js';
 import { REPLY_BUBBLE_BOUNDARY, replyBubbleTexts, publishReplyEvents, serializeOutputEvents, textOutputEvents, } from './events.js';
 /** Namespace object for callers that prefer one import over named helpers. */
 export const Presentation = Object.freeze({
     defineOutputCatalog,
+    defineReplyFormats,
+    replyFormatChecks,
+    mergeReplyBubbles,
     defineTextTemplate,
     defineSemanticSlots,
     selectVariant,

package/dist/esm/kits/reflection.js

@@ -11,7 +11,7 @@
  */
 import { AgentCoreEngine } from '../execution/engine.js';
 import { defineToolCatalog } from '../support/tools.js';
-import { defineModelCapabilities } from '../support/model/capabilities.js';
+import { defineModelTools } from '../support/model/capabilities.js';
 import { createModelTransport } from '../model/selection-transport.js';
 import { jsonObjectInteraction } from '../model/interactions/json-object.js';
 import { coreEventCatalog } from '../diagnostics/catalog.js';
@@ -225,7 +225,7 @@ export function defineReflection(definition) {
                 ...extraTools,
             ];
             const catalog = defineToolCatalog(toolDefinitions);
-            const capabilities = defineModelCapabilities([
+            const modelTools = defineModelTools([
                 ...catalog.definitions.map((tool) => ({
                     id: tool.id,
                     description: tool.description,
@@ -244,7 +244,7 @@ export function defineReflection(definition) {
             ]);
             const transport = createModelTransport({
                 id: 'core:reflection',
-                capabilities,
+                tools: modelTools,
                 adapter: jsonObjectInteraction,
             });
             const child = model.createChild({

package/dist/esm/kits/text-blocks.d.ts

@@ -0,0 +1,24 @@
+import type { TextBlock, TextBlockOptions } from '../structs/kits/text-blocks.js';
+/**
+ * Split long plain text on structural boundaries.
+ *
+ * Headings and horizontal rules start a new block, blank lines end the current one, and all
+ * other lines break only when the target size would be exceeded. A single line longer than
+ * the target becomes its own block so that paging can cut it into fragments later without
+ * splitting the line into unrelated sections. Concatenating every block reproduces the input
+ * exactly: no truncation, padding or dropped whitespace.
+ *
+ * The input must be plain text; binaries and rich documents are read elsewhere.
+ *
+ * @param text - Decoded source text.
+ * @param options - Target block size in characters.
+ * @returns Blocks in source order, each with one-based `number` and source offsets. Empty
+ *   text returns an empty list.
+ * @throws TypeError When the text is not a string or `targetChars` is not a positive integer.
+ */
+export declare function splitTextBlocks(text: string, options: TextBlockOptions): TextBlock[];
+/** Namespace form of the Kit, for callers that prefer one aggregate entry. */
+export declare const TextBlocks: {
+    readonly split: typeof splitTextBlocks;
+};
+export type { TextBlock, TextBlockOptions } from '../structs/kits/text-blocks.js';

package/dist/esm/kits/text-blocks.js

@@ -0,0 +1,97 @@
+/**
+ * Text Blocks Kit: structure-aware splitting for long plain text.
+ *
+ * Place in the package: an optional App-side helper used before a long document is paged
+ * into a model or indexed for retrieval. The Kit owns boundary selection, block numbering
+ * and exact reassembly; file reading, paging, search, storage and prompt wording stay with
+ * the App. No model call or Core dependency is involved.
+ *
+ * Exports: `splitTextBlocks`, `TextBlocks` and the block option/result types.
+ */
+import { breakWhile } from '../utils/rules.js';
+/**
+ * Whether one line starts a new structural section.
+ *
+ * @param line - A full line including its trailing newline.
+ * @returns `true` for Markdown headings and horizontal rules.
+ */
+function headingLine(line) {
+    return /^\s*#{1,6}\s/.test(line) || /^\s*(?:[-*_]{3,}|={3,})\s*$/.test(line);
+}
+/**
+ * Split long plain text on structural boundaries.
+ *
+ * Headings and horizontal rules start a new block, blank lines end the current one, and all
+ * other lines break only when the target size would be exceeded. A single line longer than
+ * the target becomes its own block so that paging can cut it into fragments later without
+ * splitting the line into unrelated sections. Concatenating every block reproduces the input
+ * exactly: no truncation, padding or dropped whitespace.
+ *
+ * The input must be plain text; binaries and rich documents are read elsewhere.
+ *
+ * @param text - Decoded source text.
+ * @param options - Target block size in characters.
+ * @returns Blocks in source order, each with one-based `number` and source offsets. Empty
+ *   text returns an empty list.
+ * @throws TypeError When the text is not a string or `targetChars` is not a positive integer.
+ */
+export function splitTextBlocks(text, options) {
+    breakWhile(typeof text !== 'string' ||
+        !options ||
+        !Number.isSafeInteger(options.targetChars) ||
+        options.targetChars < 1, 'Text block splitting requires text and a positive integer target size');
+    const targetChars = options.targetChars;
+    const blocks = [];
+    let buffer = '';
+    let bufferStart = 0;
+    let cursor = 0;
+    const flush = () => {
+        if (!buffer)
+            return;
+        const previous = blocks.at(-1);
+        if (!buffer.trim() && previous) {
+            // Whitespace-only blocks carry no section, so they stay attached to the previous block
+            // instead of becoming a block the reader has to page through.
+            blocks[blocks.length - 1] = {
+                ...previous,
+                text: previous.text + buffer,
+                end: previous.end + buffer.length,
+            };
+        }
+        else {
+            blocks.push({ number: blocks.length + 1, text: buffer, start: bufferStart, end: cursor });
+        }
+        buffer = '';
+    };
+    // Keeping a line's trailing newline makes every block reassemble into the original text,
+    // including CRLF input.
+    for (const line of text.match(/[^\n]*\n|[^\n]+$/g) ?? []) {
+        if (line.length > targetChars) {
+            flush();
+            blocks.push({
+                number: blocks.length + 1,
+                text: line,
+                start: cursor,
+                end: cursor + line.length,
+            });
+            cursor += line.length;
+            continue;
+        }
+        if (headingLine(line))
+            flush();
+        if (buffer.length + line.length > targetChars)
+            flush();
+        if (!buffer)
+            bufferStart = cursor;
+        buffer += line;
+        cursor += line.length;
+        if ((!line.trim() || headingLine(line)) && buffer.length >= targetChars / 2)
+            flush();
+        else if (buffer.length >= targetChars)
+            flush();
+    }
+    flush();
+    return blocks;
+}
+/** Namespace form of the Kit, for callers that prefer one aggregate entry. */
+export const TextBlocks = { split: splitTextBlocks };

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 };