@jangts/agent-core 0.3.5 → 0.5.0

package/dist/esm/structs/kits/{intents → domains}/registry.d.ts

@@ -1,23 +1,24 @@
 /**
- * Intent registry contract for the Intents Kit.
+ * Domain Tool registry contract for the Domain Tools Kit.
  *
- * Place in the package: an optional App-side catalog of model intents. An intent names its ordered
- * steps and optional App-declared policies; the registry checks identity, allowed vocabulary,
+ * Place in the package: an optional App-side catalog of domain Tools. An intent names its allowed
+ * delegates and optional App-declared policies; the registry checks identity, allowed vocabulary,
  * duplicate ids and sealing, while the meaning of each vocabulary value stays with the App.
  *
- * Exports: `IntentDefinition`, `IntentRegistryPolicy`, `IntentDescription`, `IntentId`,
+ * Exports: `IntentTool`, `IntentPolicy`, `IntentDescription`, `IntentId`,
  * `RegisteredIntent`.
  */
 import type { BreakReason } from '../../utils/rules.js';
 import type { RegistrationProjection } from '../../../utils/registration.js';
-/** One declarable intent. */
-export interface IntentDefinition {
-    /** Unique intent id, matched against the policy's `idPattern` when configured. */
+import type { ModelTool } from '../../capabilities/model.js';
+/** One domain Tool. */
+export interface IntentTool extends ModelTool<any, any> {
+    /** Unique Tool id, matched against the policy's `idPattern` when configured. */
     id: string;
     /** Non-blank model-facing description. */
     description: string;
-    /** Ordered step ids; non-empty, unique and, when `policy.steps` is set, drawn from it. */
-    steps: readonly string[];
+    /** Allowed delegate ids, retained in declaration order without imposing execution order; non-empty and unique. */
+    delegates?: readonly string[];
     /** App-declared scope-mode name; validated against `policy.scopeModes` when that is set. */
     scopePolicy?: string;
     /** App-declared target-mode name; validated against `policy.targetModes` when that is set. */
@@ -31,9 +32,11 @@ export interface IntentDefinition {
     /** App-declared handoff marker; validated against `policy.handoffValues` when that is set. */
     preparedHandoff?: unknown;
 }
+/** Configuration form; object arguments and a Tool proposal are the registration defaults. */
+export type IntentToolRegistration = Omit<IntentTool, 'inputSchema' | 'resolve'> & Partial<Pick<IntentTool, 'inputSchema' | 'resolve'>>;
 /** Registration rules for one intent registry. */
-export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
-    /** Pattern every intent id must match. */
+export interface IntentPolicy<Definition extends IntentToolRegistration> {
+    /** Pattern every Tool id must match. */
     readonly idPattern?: RegExp;
     /** Allowed `scopePolicy` values; `undefined` accepts any value. */
     readonly scopeModes?: readonly string[];
@@ -43,8 +46,8 @@ export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
     readonly contextTiers?: readonly string[];
     /** Allowed `planIntent` values; `undefined` accepts any value. */
     readonly actions?: readonly string[];
-    /** Allowed step ids; `undefined` accepts any non-empty step. */
-    readonly steps?: readonly string[];
+    /** Allowed delegate ids; `undefined` accepts any non-empty delegate. */
+    readonly delegates?: readonly string[];
     /** Allowed `preparedHandoff` values; `undefined` accepts any value. */
     readonly handoffValues?: readonly unknown[];
     /** Extra App assertion, called after the built-in checks; must return void synchronously. */
@@ -54,24 +57,24 @@ export interface IntentRegistryPolicy<Definition extends IntentDefinition> {
     readonly errors?: {
         readonly sealed?: BreakReason;
         readonly invalid?: BreakReason;
-        /** Builds the duplicate-id rejection; receives the intent id. */
+        /** Builds the duplicate-id rejection; receives the Tool id. */
         readonly duplicate?: (goal: string) => Error | string;
     };
 }
-/** Registered intent with its steps widened to the definition's step literals. */
-export type IntentDescription<Definition extends IntentDefinition> = Omit<RegisteredIntent<Definition>, 'steps'> & {
-    steps: Definition['steps'][number][];
+/** Registered domain Tool with its delegates widened to the definition's delegate literals. */
+export type IntentDescription<Definition extends IntentToolRegistration> = Omit<RegisteredIntent<Definition>, 'delegates'> & {
+    delegates: NonNullable<Definition['delegates']>[number][];
 };
 /** Union of the ids of a definition set, or `string` when it cannot be narrowed. */
 export type IntentId<Definition> = Definition extends {
     id: infer Id extends string;
 } ? Id : string;
-type RegisteredIntentLists<Definition extends IntentDefinition> = {
-    readonly [Key in keyof Pick<Definition, Extract<keyof Definition, 'steps' | 'auxiliaryActions'>>]: Readonly<Definition[Key]>;
+type RegisteredIntentLists<Definition extends IntentToolRegistration> = {
+    readonly [Key in keyof Pick<Definition, Extract<keyof Definition, 'delegates' | 'auxiliaryActions'>>]: Readonly<Definition[Key]>;
 };
 /** Frozen registration view: list fields are frozen copies, helper methods are dropped. */
-export type RegisteredIntent<Definition extends IntentDefinition> = Readonly<Omit<RegistrationProjection<Definition, IntentDefinition>, 'steps' | 'auxiliaryActions'> & RegisteredIntentLists<Definition> & {
+export type RegisteredIntent<Definition extends IntentToolRegistration> = Readonly<Omit<RegistrationProjection<Definition, IntentTool>, 'delegates' | 'auxiliaryActions' | 'inputSchema' | 'resolve'> & ModelTool<any, any> & RegisteredIntentLists<Definition> & {
     id: Definition['id'];
-    steps: Readonly<Definition['steps']>;
+    delegates: Readonly<NonNullable<Definition['delegates']>>;
 }>;
 export {};

package/dist/esm/structs/kits/{intents → domains}/scopes.d.ts

@@ -1,5 +1,5 @@
 /**
- * Scope registry contract for the Intents Kit.
+ * Scope registry contract for the Domain Tools Kit.
  *
  * Place in the package: an optional App-side catalog of scope definitions. A scope binds an intent
  * to the sources and tools it may use; the registry validates identity, aliases, required bindings
@@ -19,8 +19,8 @@ export interface ScopeDefinition {
     description: string;
     /** Scope category; validated against `policy.categories` when that is set. */
     category: string;
-    /** Intents this scope serves; required when the policy sets `requireIntents`. */
-    intentIds?: readonly string[];
+    /** Goals this scope serves; required when the policy sets `requireGoals`. */
+    goalIds?: readonly string[];
     /** Referenced query scopes, resolved by the App. */
     queryScopeIds?: readonly string[];
     /** Referenced knowledge topics, resolved by the App. */
@@ -36,8 +36,8 @@ export interface ScopeDefinition {
 }
 /** Registration rules for one scope registry. */
 export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
-    /** Require at least one intent id per scope. */
-    readonly requireIntents?: boolean;
+    /** Require at least one Tool id per scope. */
+    readonly requireGoals?: boolean;
     /** Require at least one query scope or knowledge topic per scope. */
     readonly requireSources?: boolean;
     /** Require at least one tool id per scope. */
@@ -49,7 +49,7 @@ export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
     /** Extra App assertion, called after the built-in checks; must return void synchronously. */
     readonly assertDefinition?: (definition: Definition) => void;
     /** Replaces the default intent membership test; must return boolean synchronously. */
-    readonly acceptsIntent?: (definition: Readonly<Definition>, goal: string) => boolean;
+    readonly acceptsTool?: (definition: Readonly<Definition>, goal: string) => boolean;
     /** Diagnostic tags attached to registration rejections. */
     readonly tags?: readonly string[];
     readonly errors?: {
@@ -59,7 +59,7 @@ export interface ScopeRegistryPolicy<Definition extends ScopeDefinition> {
 }
 /** Registered evidence entry: public data only, frozen by the registry. */
 export type RegisteredScopeEvidence<Definition extends ScopeDefinition> = Readonly<RegistrationData<NonNullable<Definition['evidence']>[number]>>;
-type ScopeListKey = 'intentIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases';
+type ScopeListKey = 'goalIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases';
 type RegisteredScopeLists<Definition extends ScopeDefinition> = {
     readonly [Key in ScopeListKey]: [NonNullable<Definition[Key]>] extends [never] ? readonly [] : NonNullable<Definition[Key]> extends readonly string[] ? Readonly<NonNullable<Definition[Key]>> : readonly string[];
 };
@@ -74,8 +74,8 @@ export type RegisteredScope<Definition extends ScopeDefinition> = Readonly<Omit<
     evidence: ScopeEvidenceList<Definition>;
 }>;
 /** Plain description with mutable arrays, for documentation and model-facing catalogs. */
-export type ScopeDescription<Definition extends ScopeDefinition> = Omit<RegisteredScope<Definition>, 'intentIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases' | 'evidence'> & {
-    intentIds: string[];
+export type ScopeDescription<Definition extends ScopeDefinition> = Omit<RegisteredScope<Definition>, 'goalIds' | 'queryScopeIds' | 'knowledgeTopicIds' | 'toolIds' | 'aliases' | 'evidence'> & {
+    goalIds: string[];
     queryScopeIds: string[];
     knowledgeTopicIds: string[];
     toolIds: string[];

package/dist/esm/structs/kits/domains/scopes.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/structs/kits/presentation/formats.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Reply-format contract for the Presentation Kit.
+ *
+ * A format exists only where the App provides a template for the final reply. Replies without a
+ * resolved format have no output-format requirement, so callers skip these checks instead of
+ * re-asking the model.
+ *
+ * Exports: `ReplyFormatCheck`, `ReplyFormatDefinition`, `CompiledReplyFormat`, `ReplyFormatOptions`.
+ */
+/** One check a template declares, evaluated against the rendered bubbles. */
+export interface ReplyFormatCheck {
+    /** Stable check id referenced by formats. */
+    readonly id: string;
+    /** Human-readable statement of the template requirement. */
+    readonly description: string;
+    /** Returns whether the reply satisfies this requirement. */
+    readonly accepts: (bubbles: readonly string[]) => boolean;
+}
+/** A template-bound reply format, matched against per-turn facts. */
+export interface ReplyFormatDefinition<Context = unknown> {
+    /** Stable format id. */
+    readonly id: string;
+    /** Human-readable statement of the template. */
+    readonly description: string;
+    /** Check ids this template requires. */
+    readonly checks: readonly string[];
+    /** Whether the current turn uses this template. */
+    readonly when: (context: Context) => boolean;
+}
+/** A resolved format with its checks bound; callers only inspect replies using it. */
+export interface CompiledReplyFormat {
+    readonly id: string;
+    readonly description: string;
+    readonly checks: readonly string[];
+    /** Checks the reply fails; empty means the template format is satisfied. */
+    readonly inspect: (bubbles: readonly string[]) => readonly ReplyFormatCheck[];
+}
+/** Declaration input for `defineReplyFormats`. */
+export interface ReplyFormatOptions<Context = unknown> {
+    readonly formats: readonly ReplyFormatDefinition<Context>[];
+    readonly checks: readonly ReplyFormatCheck[];
+}

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,25 @@
+/**
+ * Text block contract for the Text Blocks Kit.
+ *
+ * Place in the package: an optional App-side helper for splitting long plain text into
+ * structure-aware blocks before paging or retrieval. File reading, paging, search, storage
+ * and prompt wording stay with the App.
+ *
+ * Exports: `TextBlock`, `TextBlockOptions`.
+ */
+/** One structure-aware block of a long text. */
+export interface TextBlock {
+    /** One-based position in source order; stable for a given text and target size. */
+    readonly number: number;
+    /** Exact source substring, including its own line endings. */
+    readonly text: string;
+    /** Start offset in UTF-16 code units. */
+    readonly start: number;
+    /** End offset (exclusive) in UTF-16 code units; `end - start === text.length`. */
+    readonly end: number;
+}
+/** Splitting options. */
+export interface TextBlockOptions {
+    /** Target block size in characters; only a single over-long line may exceed it. */
+    readonly targetChars: number;
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Text block contract for the Text Blocks Kit.
+ *
+ * Place in the package: an optional App-side helper for splitting long plain text into
+ * structure-aware blocks before paging or retrieval. File reading, paging, search, storage
+ * and prompt wording stay with the App.
+ *
+ * Exports: `TextBlock`, `TextBlockOptions`.
+ */
+export {};

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

@@ -1,24 +1,29 @@
 /**
- * Tool lifecycle contract for the Tools Kit.
+ * Tool contract for the Tools Kit.
  *
  * Place in the package: an optional App-side library for tools that need more than a plain
- * definition — availability, per-step protocols, output ownership, model-context fields, task rules
- * and delivery hooks. Actual invocation is delegated to Core (`ToolRegistry`, `executeInvocation`);
- * domain predicates, phase names and vocabulary stay App configuration.
+ * definition — availability, one lifecycle hook set, output ownership, model-context fields,
+ * task rules and delivery hooks. Actual invocation is delegated to Core (`ToolRegistry`,
+ * `executeInvocation`); domain predicates, phase names and vocabulary stay App configuration.
  *
- * Exports: `ToolRuntimeTypes`, `ToolModelField`, `LifecycleProtocol`, `ToolInvocation`,
- * `ToolContribution`, `LifecycleTool`, `RegisteredLifecycleTool`, `Policy`, `ToolProtocol`,
- * `ToolNormalizer`, `ToolFinalizer`, `ToolLifecycleOptions`, `ToolJournal` (type re-export).
+ * A tool declares at most one `lifecycle` block. Hooks under "selected" run only for the tool a
+ * decision picks; the rest run for every registered tool; `delegate` claims one delegate id so
+ * the registry can route a decision to its handler.
+ *
+ * Exports: `ToolRuntimeTypes`, `ToolModelField`, `LifecycleProtocol`, `LifecycleHooks`, `Tool`,
+ * `ToolRegistration`, `RegisteredToolDefinition`, `Policy`, `ToolProtocol`, `ToolNormalizer`,
+ * `ToolFinalizer`, `ToolsOptions`, `ToolJournal` (type re-export).
  */
 import type { ContextFragment, ContextLifetime } from '../context/fragments.js';
 import type { BreakReason } from '../utils/rules.js';
-import type { ExecutableTool, ToolRegistryPorts } from '../capabilities/tools.js';
+import type { ErasedTool, ToolExecutionContext, ToolRegistryPorts } from '../capabilities/tools.js';
 import type { ProtocolShape } from './interaction.js';
+import type { ModelTool } from '../capabilities/model.js';
 import type { ToolInvocationPorts } from '../capabilities/invocation.js';
 import type { RegistrationProjection } from '../../utils/registration.js';
 /** One schema binds lifecycle handler types without introducing platform fields into core. */
 export interface ToolRuntimeTypes {
-    /** App decision object carried through invocation steps. */
+    /** App decision object carried through lifecycle invocations. */
     decision: unknown;
     /** App handler context for one request. */
     context: unknown;
@@ -50,52 +55,37 @@ export interface ToolModelField<Placement extends string = string> {
     /** Field value, rendered by the registry's fragment factory. */
     value: unknown;
 }
-/** Output protocol carried by a lifecycle step. */
+/** Output protocol carried by a tool lifecycle. */
 export interface LifecycleProtocol extends ProtocolShape {
     /** Protocol version; compared with the configured `protocolVersion` when present. */
     readonly version?: number;
     /** Marks an output that ends the interaction. */
     readonly terminal?: boolean;
 }
-/** One lifecycle step of a tool. */
-export interface ToolInvocation<Types extends ToolRuntimeTypes, Protocol extends LifecycleProtocol = LifecycleProtocol> {
-    /** Step id this invocation handles; must be unique across registered tools. */
-    step: string;
-    /** Output protocol of the step. */
-    protocol: Protocol;
-    /** Executes the step. Must be synchronous and return nothing. */
-    call(value: unknown, context: Types['context'], execution: import('../capabilities/tools.js').ToolExecutionContext): void;
-    /** Inspects a decision before any step runs. */
-    inspect?(decision: Types['decision'], context: Types['context']): void;
+/**
+ * Everything one tool declares for a request.
+ *
+ * Declaring `id` turns the tool into an invocation owner, so `protocol` and `call` become
+ * required in practice; the registry rejects a partial declaration. Every other hook is
+ * optional and returning nothing expresses "no opinion".
+ */
+export interface LifecycleHooks<Types extends ToolRuntimeTypes, Protocol extends LifecycleProtocol = LifecycleProtocol> {
+    /** Invocation id this tool owns; must be unique across registered tools. */
+    id?: string;
+    /** Output protocol of the invocation. */
+    protocol?: Protocol;
+    /** Executes the invocation. Must be synchronous and return nothing. */
+    call?(value: unknown, context: Types['context'], execution: ToolExecutionContext): void;
     /** Permission check for the decision; runs before execution. */
     authorize?(decision: Types['decision'], context: Types['context']): void;
-    /** Returns true when this step is a valid continuation of the decision. */
+    /** Returns true when this invocation is a valid continuation of the decision. */
     resume?(decision: Types['decision'], context: Types['context']): boolean;
-    /** Normalizes the decision after the step; returning undefined keeps it unchanged. */
+    /** Normalizes the decision after the invocation; returning undefined keeps it unchanged. */
     complete?(decision: Types['decision'], context: Types['context']): Types['decision'] | undefined;
-}
-/**
- * Non-execution hooks a tool may contribute to a request.
- *
- * Every hook is optional; one returns nothing to express "no opinion".
- */
-export interface ToolContribution<Types extends ToolRuntimeTypes> {
-    /** Builds the tool's composition value for the current context. */
-    composition?(context: Types['context']): Types['composition'] | undefined;
-    /** Observes the decision during the inspect phase. */
+    /** Observes the decision before any invocation runs. */
     inspect?(decision: Types['decision'], context: Types['context']): void;
-    /** Extra context used when recovering a previous attempt. */
-    recoveryContext?(context: Types['context']): unknown;
-    /** Projects the stored context before it is shown or persisted. */
-    projectContext?(context: unknown): unknown;
-    /** Rewrites visible text produced by this tool. */
-    visibleText?(text: string, context: Types['context']): string;
-    /** Reviews a draft before delivery. */
-    reviewDraft?(draft: unknown, context: Types['context']): unknown;
     /** Runs finalization for one phase. */
     finalize?(decision: Types['decision'], context: Types['context'], phase: Types['phase']): void;
-    /** Returns true when an absent interaction is acceptable in this phase. */
-    missingInteractionAllowed?(decision: Types['decision'], context: Types['context']): boolean;
     /** Extra rules contributed to the model context, ordered by `order`. */
     rules?(context: Types['context']): {
         order: number;
@@ -103,33 +93,42 @@ export interface ToolContribution<Types extends ToolRuntimeTypes> {
     }[];
     /** Model-context fields for one placement, ordered by `order`. */
     modelFields?(context: Types['context'], placement: Types['placement']): ToolModelField<Types['placement']>[];
-    /** Vetoes an intent by returning false; silence (undefined) means support. */
-    supportsIntent?(intentId: string, context: Types['context']): boolean | undefined;
+    /** Rewrites visible text produced by this tool. */
+    visibleText?(text: string, context: Types['context']): string;
+    /** Reviews a draft before delivery. */
+    reviewDraft?(draft: unknown, context: Types['context']): unknown;
+    /** Builds the tool's composition value for the current context. */
+    composition?(context: Types['context']): Types['composition'] | undefined;
+    /** Extra context used when recovering a previous attempt. */
+    recoveryContext?(context: Types['context']): unknown;
+    /** Projects the stored context before it is shown or persisted. */
+    projectContext?(context: unknown): unknown;
+    /** Returns true when an absent interaction is acceptable in this phase. */
+    missingInteractionAllowed?(decision: Types['decision'], context: Types['context']): boolean;
+    /** Vetoes a goal by returning false; silence (undefined) means support. */
+    supportsGoal?(goalId: string, context: Types['context']): boolean | undefined;
 }
-/** A tool with lifecycle steps and delivery contributions. */
-export interface LifecycleTool<Types extends ToolRuntimeTypes> extends ExecutableTool {
-    /** Intent ids this tool serves, or `'all'` when it is always available. */
-    readonly intentIds: 'all' | readonly string[];
+/** A registered tool: model metadata plus one optional lifecycle block. */
+export interface Tool<Types extends ToolRuntimeTypes> extends ErasedTool, ModelTool<unknown, unknown, Types['context']> {
+    /** Goal ids this tool serves, or `'all'` when it is always available. */
+    readonly goalIds: 'all' | readonly string[];
     readonly description: string;
     /** Audience this tool is described to; validated against the registry policy. */
     readonly audience: string;
     /** Declared effect class, for example read-only or mutating. */
     readonly effect: string;
-    /** Per-step invocation contract. */
-    readonly invocation?: ToolInvocation<Types>;
-    /** Non-execution hooks. */
-    readonly contribution?: ToolContribution<Types>;
-    /** Returns whether the tool may run for this context; absent means always available. */
-    available?(context: Types['context']): boolean;
+    /** Delegate id this tool answers, when a node delegates execution by name. */
+    readonly delegate?: string;
+    /** Lifecycle hooks this tool declares for a request. */
+    readonly lifecycle?: LifecycleHooks<Types>;
 }
-type RegisteredInvocation<Types extends ToolRuntimeTypes, Value> = Value extends ToolInvocation<Types> ? RegistrationProjection<Value, ToolInvocation<Types>> : Value;
-type RegisteredContribution<Types extends ToolRuntimeTypes, Value> = Value extends ToolContribution<Types> ? RegistrationProjection<Value, ToolContribution<Types>> : Value;
-type RegisteredLifecycleHooks<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> = {
-    [Key in keyof Pick<Tool, Extract<keyof Tool, 'invocation' | 'contribution'>>]: Key extends 'invocation' ? RegisteredInvocation<Types, Tool[Key]> : RegisteredContribution<Types, Tool[Key]>;
-};
-/** Registered snapshot with frozen intent ids and projected hooks. */
-export type RegisteredLifecycleTool<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types> = LifecycleTool<Types>> = Readonly<Omit<RegistrationProjection<Tool, LifecycleTool<Types>>, 'invocation' | 'contribution' | 'intentIds'> & RegisteredLifecycleHooks<Types, Tool> & {
-    intentIds: Readonly<Tool['intentIds']>;
+/** Declaration form; the registry derives the ModelTool projection from existing handlers. */
+export type ToolRegistration<Types extends ToolRuntimeTypes> = Omit<Tool<Types>, 'inputSchema' | 'resolve'> & Partial<Pick<Tool<Types>, 'inputSchema' | 'resolve'>>;
+type RegisteredLifecycle<Types extends ToolRuntimeTypes, Value> = Value extends LifecycleHooks<Types> ? RegistrationProjection<Value, LifecycleHooks<Types>> : Value;
+/** Registered snapshot with frozen goal ids and projected hooks. */
+export type RegisteredToolDefinition<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types> = ToolRegistration<Types>> = Readonly<Omit<RegistrationProjection<Declaration, Tool<Types>>, 'lifecycle' | 'goalIds'> & {
+    lifecycle?: RegisteredLifecycle<Types, Declaration['lifecycle']>;
+    goalIds: Readonly<Declaration['goalIds']>;
 }>;
 /** Registration policy shared by every tool in the registry. */
 export interface Policy<Tool> {
@@ -141,29 +140,29 @@ export interface Policy<Tool> {
     readonly audiences: readonly string[];
     /** Accepted `effect` values. */
     readonly effects: readonly string[];
-    /** Reports whether an intent id exists, for validating `intentIds` references. */
-    readonly intentExists: (goal: string) => boolean;
-    /** When set, every step protocol must declare this version. */
+    /** Reports whether a goal id exists, for validating `goalIds` references. */
+    readonly goalExists: (goal: string) => boolean;
+    /** When set, every lifecycle protocol must declare this version. */
     readonly protocolVersion?: number;
     /** Diagnostic tags attached to registration rejections. */
     readonly tags?: readonly string[];
     /** Rejection wording for an invalid tool definition. */
     readonly invalidTool?: BreakReason;
-    /** Rejection wording for an invalid or duplicate invocation step. */
+    /** Rejection wording for an invalid or duplicate invocation id. */
     readonly invalidInvocation?: BreakReason;
 }
-/** Protocol type of a tool's invocation step. */
+/** Protocol type of a tool's lifecycle invocation. */
 export type ToolProtocol<Tool extends {
-    invocation?: {
-        protocol: LifecycleProtocol;
+    lifecycle?: {
+        protocol?: LifecycleProtocol;
     };
-}> = NonNullable<Tool['invocation']>['protocol'];
+}> = NonNullable<NonNullable<Tool['lifecycle']>['protocol']>;
 /** Converts untrusted input into a decision; must be synchronous. */
 export type ToolNormalizer<Types extends ToolRuntimeTypes> = (value: unknown, ...args: Types['normalizerArgs']) => unknown;
 /** Converts an executed decision into the tool result; must be synchronous. */
 export type ToolFinalizer<Types extends ToolRuntimeTypes> = (receiver: Types['receiver'], decision: Types['decision'], context: Types['context']) => Types['result'];
-/** Construction options for a lifecycle tool registry. */
-export interface ToolLifecycleOptions<Types extends ToolRuntimeTypes, Tool extends LifecycleTool<Types>> extends ToolInvocationPorts<Types['context']> {
+/** Construction options for a tool registry. */
+export interface ToolsOptions<Types extends ToolRuntimeTypes, Declaration extends ToolRegistration<Types>> extends ToolInvocationPorts<Types['context']> {
     /** Supplies the receiver handed to the finalizer. */
     readonly receiver?: () => Types['receiver'];
     /** Execution defaults (signal and diagnostics) applied to invocations. */
@@ -171,20 +170,20 @@ export interface ToolLifecycleOptions<Types extends ToolRuntimeTypes, Tool exten
     /** Error factories shared by the registry. */
     readonly errors?: Pick<ToolRegistryPorts, 'unavailable' | 'errorCode'>;
     /** Registration policy for every tool. */
-    readonly registration: Policy<Tool>;
-    /** Maps a decision to its lifecycle step id. */
-    readonly step: (decision: Types['decision']) => string;
-    /** Output protocols by id, used to validate step outputs. */
-    readonly outputs: () => Iterable<readonly [string, ToolProtocol<Tool>]>;
+    readonly registration: Policy<Declaration>;
+    /** Maps a decision to the invocation id that should handle it. */
+    readonly invocationId: (decision: Types['decision']) => string;
+    /** Output protocols by id, used to validate invocation outputs. */
+    readonly outputs: () => Iterable<readonly [string, ToolProtocol<Declaration>]>;
     /** Optional context-dependent output protocols, exposed alongside `outputs`. */
-    readonly modelOutputs?: (context: Types['context']) => Iterable<readonly [string, ToolProtocol<Tool>]>;
-    /** Builds the error for a step with no registered tool. */
-    readonly unavailableStep?: (step: string) => Error;
+    readonly modelOutputs?: (context: Types['context']) => Iterable<readonly [string, ToolProtocol<Declaration>]>;
+    /** Builds the error for an invocation id with no registered tool. */
+    readonly unavailableInvocation?: (invocationId: string) => Error;
     /** Builds the error for a tool that is currently unavailable. */
     readonly forbidden?: () => Error;
     /** Renders a model field into a context fragment. */
-    readonly contextFragment: (tool: Tool, field: ToolModelField<Types['placement']>) => ContextFragment;
-    /** Current intent ids, used to validate `intentIds: 'all'` availability. */
-    readonly intentIds: () => readonly string[];
+    readonly contextFragment: (tool: Declaration, field: ToolModelField<Types['placement']>) => ContextFragment;
+    /** Current goal ids, used to validate `goalIds: 'all'` availability. */
+    readonly goalIds: () => readonly string[];
 }
 export type { ToolJournal } from '../capabilities/invocation.js';

package/dist/esm/structs/model/interactions.d.ts

@@ -1,7 +1,7 @@
 /**
  * Model interaction contracts: how model output is turned into a business selection.
  *
- * An adapter compiles registered capabilities into provider options plus an instruction, and
+ * An adapter compiles registered tools into provider options plus an instruction, and
  * decodes the streamed response into a `ModelSelection`. A transport registration binds one adapter
  * to a capability source, so the same business registry can be served by different wire formats.
  *
@@ -9,11 +9,18 @@
  * `ModelInteractionAdapter`, `ModelTransportRegistration`, `NativeFunctionCall`.
  */
 import type { ModelOptions, ModelPart } from './messages.js';
-import type { ModelSelection, ModelCapabilitySource, RegisteredModelCapability } from '../capabilities/model.js';
+import type { ModelSelection, ModelToolSource, RegisteredModelTool } from '../capabilities/model.js';
 /** Accumulates streamed parts for one call and resolves them into the transport's result. */
 export interface ModelResponseCollector<Result = ModelSelection> {
     /** Native function call that carried the selection, when the response used one. */
     readonly call?: ModelSelection['call'];
+    /** All native calls carried by a session response; omitted by single-selection collectors. */
+    readonly calls?: readonly {
+        id: string;
+        name: string;
+        argumentChars: number;
+        toolId?: string;
+    }[];
     /** Output characters accumulated so far, for output-budget accounting. */
     readonly outputChars: number;
     /** Appends one streamed part; parts arrive in provider order. */
@@ -23,8 +30,8 @@ export interface ModelResponseCollector<Result = ModelSelection> {
 }
 /** Adapter output for one stage, before the caller binds capability resolution. */
 export interface PreparedModelInteraction<Result = unknown> {
-    /** Provider options produced from the stage's capabilities. */
-    readonly options: Pick<ModelOptions, 'functions' | 'json'>;
+    /** Provider options produced from the stage's tools. */
+    readonly options: Pick<ModelOptions, 'functions' | 'json' | 'toolChoice' | 'parallelToolCalls'>;
     /** Characters the compiled schemas add to the input, counted against the schema budget. */
     readonly schemaChars: number;
     /** Instruction text that teaches the model how to answer; absent when the format is native. */
@@ -36,7 +43,7 @@ export interface PreparedModelInteraction<Result = unknown> {
 }
 /** Prepared transport handed to the runner, including sampling defaults. */
 export interface PreparedModelTransport<Result = unknown> {
-    readonly options: Pick<ModelOptions, 'functions' | 'json' | 'temperature'>;
+    readonly options: Pick<ModelOptions, 'functions' | 'json' | 'temperature' | 'toolChoice' | 'parallelToolCalls'>;
     readonly schemaChars: number;
     readonly instruction?: string;
     createResponse(): ModelResponseCollector<Result>;
@@ -49,19 +56,19 @@ export interface ModelInteractionAdapter {
         readonly strictArguments: boolean;
     };
     /**
-     * Compiles one stage's capabilities.
+     * Compiles one stage's tools.
      *
-     * @param capabilities - Capabilities available in this stage; must be non-empty.
+     * @param tools - Capabilities available in this stage; must be non-empty.
      * @returns Options, instruction and collector factory; the transport adds `resolve`.
      */
-    prepare(capabilities: readonly RegisteredModelCapability[]): Omit<PreparedModelInteraction, 'resolve'>;
+    prepare(tools: readonly RegisteredModelTool[]): Omit<PreparedModelInteraction, 'resolve'>;
 }
-/** Binds an adapter to the capabilities one transport serves. */
+/** Binds an adapter to the tools one transport serves. */
 export interface ModelTransportRegistration<Result = unknown> {
     /** Transport id used by call requests and reported in diagnostic events. */
     id: string;
-    /** Static capability source, or a factory that selects capabilities per stage. */
-    capabilities: ModelCapabilitySource<Result> | ((stage: string) => ModelCapabilitySource<Result>);
+    /** Static capability source, or a factory that selects tools per stage. */
+    tools: ModelToolSource<Result> | ((stage: string) => ModelToolSource<Result>);
     /** Wire-format adapter; defaults to native function calling. */
     adapter?: ModelInteractionAdapter;
     /** Sampling defaults this transport contributes to every call. */

package/dist/esm/structs/model/messages.d.ts

@@ -4,7 +4,8 @@
  * These shapes are deliberately provider-neutral: they describe text, optional images, streamed
  * parts and the options a call may carry. Provider-specific wire formats stay in `support/model`.
  *
- * Exports: `ModelImage`, `ModelMessage`, `ModelUsage`, `ModelFunction`, `FunctionCallDelta`,
+ * Exports: `ModelImage`, `ModelMessage`, `ModelToolCall`, `ModelAssistantToolMessage`,
+ * `ModelToolResultMessage`, `ModelUsage`, `ModelFunction`, `FunctionCallDelta`,
  * `ModelPart`, `ModelOptions`.
  */
 export interface ModelImage {
@@ -13,14 +14,41 @@ export interface ModelImage {
     /** Provider resolution hint; `original` asks for no downscaling where supported. */
     detail?: 'auto' | 'low' | 'high' | 'original';
 }
+/** One tool call the assistant declared, in provider order. */
+export interface ModelToolCall {
+    /** Provider call id, echoed by the matching tool result. */
+    readonly id: string;
+    /** Declared function name. */
+    readonly name: string;
+    /** Raw JSON arguments exactly as the provider produced them. */
+    readonly arguments: string;
+}
 /** One provider-neutral turn; `images` are user visual input and are not part of the text budget. */
 export interface ModelMessage {
-    role: 'system' | 'user' | 'assistant';
+    role: 'system' | 'user' | 'assistant' | 'tool';
     /** Rendered text content sent to the model. */
     content: string;
     /** User-supplied visual input. Binary payload is separate from the text character budget. */
     images?: readonly ModelImage[];
+    /** Tool declarations made by an assistant turn; rejected on every other role at runtime. */
+    toolCalls?: readonly ModelToolCall[];
+    /** Call id answered by a tool result; rejected on every other role at runtime. */
+    toolCallId?: string;
 }
+/** Assistant turn that may declare tool calls and may carry an empty text body. */
+export type ModelAssistantToolMessage = ModelMessage & {
+    readonly role: 'assistant';
+    readonly toolCalls?: readonly ModelToolCall[];
+    readonly toolCallId?: never;
+    readonly images?: never;
+};
+/** Tool result turn; `toolCallId` is required and images/tool declarations are rejected. */
+export type ModelToolResultMessage = ModelMessage & {
+    readonly role: 'tool';
+    readonly toolCallId: string;
+    readonly toolCalls?: never;
+    readonly images?: never;
+};
 /** Provider-reported token counts for one call; used for accounting, never for admission. */
 export interface ModelUsage {
     /** Input tokens billed for the call. */
@@ -69,4 +97,8 @@ export interface ModelOptions {
     onUsage?: (usage: ModelUsage) => void;
     /** Functions offered to the model for this call. */
     functions?: readonly ModelFunction[];
+    /** Tool-selection strategy; omitted keeps the provider's default. */
+    toolChoice?: 'auto' | 'required' | 'none';
+    /** Request parallel tool calls; `'omit'` leaves the wire field out entirely. */
+    parallelToolCalls?: boolean | 'omit';
 }