@jangts/agent-core 0.3.6 → 0.5.0

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

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

@@ -97,6 +97,13 @@ export interface ModelCallTrace extends InvocationMetadata {
         name: string;
         argumentChars: number;
     };
+    /** All calls produced by a session response; omitted for single-selection transports. */
+    calls?: readonly {
+        id: string;
+        name: string;
+        argumentChars: number;
+        toolId?: string;
+    }[];
     /** Context accounting: per-fragment usage and characters shared with the previous call. */
     context?: {
         fragmentUsage: ContextFragmentUsage[];

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

@@ -0,0 +1,29 @@
+/**
+ * Raw session response contracts: one response may carry text and several tool calls.
+ *
+ * These shapes are Core-only and deliberately contain no host tool resolution. Support's
+ * session transport adds `toolId`, parsed `input` and non-fatal `problem` fields in its own
+ * `ResolvedSessionResult` type.
+ *
+ * Exports: `ModelSessionCall`, `ModelSessionResult`.
+ */
+/** One completed tool call in a session response. */
+export interface ModelSessionCall {
+    /** Provider index used to join streamed fragments. */
+    readonly index: number;
+    /** Provider call id, echoed by the matching tool result. */
+    readonly id: string;
+    /** Declared function name exactly as returned by the model. */
+    readonly name: string;
+    /** Raw JSON argument text exactly as returned by the model. */
+    readonly arguments: string;
+    /** Characters counted for the output budget. */
+    readonly argumentChars: number;
+}
+/** Complete result of one session response. */
+export interface ModelSessionResult {
+    /** Streamed assistant prose; may be empty when the response only declares calls. */
+    readonly text: string;
+    /** Completed calls in provider index order. */
+    readonly calls: readonly ModelSessionCall[];
+}

package/dist/esm/structs/model/session.js

@@ -0,0 +1,10 @@
+/**
+ * Raw session response contracts: one response may carry text and several tool calls.
+ *
+ * These shapes are Core-only and deliberately contain no host tool resolution. Support's
+ * session transport adds `toolId`, parsed `input` and non-fatal `problem` fields in its own
+ * `ResolvedSessionResult` type.
+ *
+ * Exports: `ModelSessionCall`, `ModelSessionResult`.
+ */
+export {};

package/dist/esm/structs/support/associations.d.ts

@@ -0,0 +1,22 @@
+/** App-side associations between registered owners and model tools; no separate intent entity. */
+import type { ModelToolRegistration } from '../capabilities/model.js';
+/** Explicit tool references or inline overrides of the owner's default model interface. */
+export type ToolAssociation = string | Partial<ModelToolRegistration>;
+/** Owners retain their business fields; Support only reads model interface associations. */
+export interface AssociatedRegistration {
+    readonly id: string;
+    readonly description: string;
+    readonly modelTools?: readonly ToolAssociation[];
+}
+/** Shared independent tools and a default projection from existing contracts. */
+export interface AssociationOptions<Entry extends AssociatedRegistration> {
+    readonly tools?: readonly ModelToolRegistration[];
+    readonly toolDefaults?: (entry: Readonly<Entry>) => ModelToolRegistration | undefined;
+}
+/** Local provenance, never an extra model input requirement. */
+export interface AssociationSource {
+    readonly kind: 'standalone' | 'registration';
+    readonly id: string;
+    readonly description: string;
+    readonly toolIds: readonly string[];
+}

package/dist/esm/structs/support/associations.js

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

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

@@ -1,7 +1,7 @@
 /**
  * Stage-scoped model transport contract.
  *
- * Place in the package: Support-side registration for transports that expose only the capabilities
+ * Place in the package: Support-side registration for transports that expose only the tools
  * declared for each stage. Static sources are projected once; dynamic sources are re-projected at
  * the model boundary. Either way, an undeclared stage or capability is rejected rather than
  * silently omitted.
@@ -16,6 +16,6 @@ export interface ModelStageTransportRegistration<Result = unknown> extends Model
     /** Declared stages; each id is unique and lists non-empty, unique capability ids. */
     readonly stages: readonly {
         readonly id: string;
-        readonly capabilityIds: readonly string[];
+        readonly toolIds: readonly string[];
     }[];
 }

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

@@ -1,23 +1,16 @@
 /**
  * Provider-level message shapes for direct compatible-provider use.
  *
- * Place in the package: Support-side input for hosts that keep their own tool thread. `ModelMessage`
- * stays the Core contract and is unchanged; these shapes add the assistant tool declaration and the
- * tool result, with role and field association enforced by the union and re-checked at runtime.
+ * Place in the package: Support-side input for hosts that keep their own tool thread. Core
+ * `ModelMessage` also supports the tool thread; these stricter shapes remain for hosts that want
+ * role and field association enforced by the union and re-checked at runtime.
  *
  * Exports: `ProviderToolCall`, `ProviderSystemMessage`, `ProviderUserMessage`,
  * `ProviderAssistantMessage`, `ProviderToolMessage`, `ProviderMessage`.
  */
-import type { ModelImage } from '../../model/messages.js';
-/** One tool call the assistant declared, in wire order. */
-export interface ProviderToolCall {
-    /** 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;
-}
+import type { ModelImage, ModelToolCall } from '../../model/messages.js';
+/** One tool call the assistant declared, in wire order; aliases the Core shape. */
+export type ProviderToolCall = ModelToolCall;
 /** System instruction turn; text only, so the union rejects images and tool fields here. */
 export interface ProviderSystemMessage {
     readonly role: 'system';

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

@@ -1,35 +1,33 @@
 /**
  * Tool catalog contract used by Support's tool assembly.
  *
- * Place in the package: an App-side projection of typed tool definitions into model capabilities.
+ * Place in the package: an App-side projection of typed tool definitions into model tools.
  * The model may only propose `{ toolId, input }`; authorization, invocation, budgets and
  * cancellation still happen in Core's tool registry.
  *
- * Exports: `ToolDefinition` (type re-export), `ToolProposal`, `ToolCapabilities`, `SelectedTools`,
+ * Exports: `ToolDefinition` (type re-export), `ToolProposal`, `ToolModelView`, `SelectedTools`,
  * `ToolOutput`, `CompiledTool`, `ToolRuntime`, `ToolCatalogEntry`, `ToolCatalog`.
  */
 import type { ToolResult } from '../invocation.js';
 import type { SchemaAdapter, ExecutionOptions, ReadonlyCatalog } from '../common.js';
-import type { RegisteredModelCapability, ModelSelection } from '../capabilities/model.js';
-import type { ModelCapabilityRegistry } from '../../capabilities/model.js';
-import type { ToolDefinition, ToolExecutionEvent, ToolRegistryPorts, ToolInvocationRequest } from '../capabilities/tools.js';
+import type { RegisteredModelTool, ModelSelection } from '../capabilities/model.js';
+import type { ModelToolRegistry } from '../../capabilities/model.js';
+import type { ToolDefinition, ExecutableTool, ToolExecutionEvent, ToolRegistryPorts, ToolInvocationRequest } from '../capabilities/tools.js';
 export type { ToolDefinition } from '../capabilities/tools.js';
 /** A model's proposal to call one tool; nothing has been authorized or executed yet. */
-export interface ToolProposal {
-    /** Registered tool the model selected. */
-    readonly toolId: string;
-    /** Raw arguments; schema parsing and authorization happen in Core. */
-    readonly input: unknown;
-}
-/** Model capability view of a tool catalog. */
-export interface ToolCapabilities extends ModelCapabilityRegistry {
-    values(): IterableIterator<RegisteredModelCapability<ToolProposal>>;
+export type { ToolProposal } from '../capabilities/model.js';
+import type { ToolProposal } from '../capabilities/model.js';
+/** Model capability view of a tool catalog, retaining the host context type. */
+export interface ToolModelView<App = unknown> extends ModelToolRegistry {
+    values(): IterableIterator<RegisteredModelTool<ToolProposal>>;
     /** Resolves a model selection into a proposal; throws for unknown or invalid selections. */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): ToolProposal;
     /** Narrows the capability set to `ids`; throws for unregistered ids. */
-    select(ids: readonly string[]): ToolCapabilities;
+    select(ids: readonly string[], context?: App): ToolModelView<App>;
+    /** Discovery retains this projection's ToolProposal result contract. */
+    withIntent(context: App): ToolModelView<App>;
 }
 type ResultDefinition = {
     readonly id: string;
@@ -46,13 +44,13 @@ export type CompiledTool<App, Definition> = Definition extends {
     parseOutput(value: unknown): infer Output;
 } ? Definition extends {
     readonly id: infer Id extends string;
-} ? ToolDefinition<Definition extends {
+} ? ExecutableTool<Definition extends {
     inputSchema: SchemaAdapter<infer Input>;
 } ? Input : unknown, Output, App, Id> : never : never;
 /** Catalog bound to one App request. */
-export interface ToolRuntime<Tool extends ResultDefinition = ResultDefinition> {
-    /** The catalog's model capabilities, shared with the catalog instance. */
-    readonly capabilities: ToolCapabilities;
+export interface ToolRuntime<Tool extends ResultDefinition = ResultDefinition, App = unknown> {
+    /** The catalog's model tools, shared with the catalog instance. */
+    readonly tools: ToolModelView<App>;
     /** Execution events recorded by this runtime so far, in occurrence order. */
     readonly events: readonly ToolExecutionEvent[];
     /** Synchronous invocation; rejects tools declared as asynchronous. */
@@ -64,15 +62,17 @@ export interface ToolRuntime<Tool extends ResultDefinition = ResultDefinition> {
 }
 /** Public declaration surface of one tool, without registry internals. */
 export type ToolCatalogEntry<App, Tool extends ToolDefinition<unknown, unknown, App>> = Tool extends ToolDefinition<unknown, unknown, App> ? Pick<Tool, keyof ToolDefinition<unknown, unknown, App>> : never;
-/** Frozen tool catalog with model capabilities and per-request binding. */
+/** Frozen tool catalog with model tools and per-request binding. */
 export interface ToolCatalog<App, Tool extends ToolDefinition<unknown, unknown, App> = ToolDefinition<unknown, unknown, App>> extends ReadonlyCatalog<ToolCatalogEntry<App, Tool>> {
-    readonly capabilities: ToolCapabilities;
+    readonly tools: ToolModelView<App>;
     /** Narrows the catalog while preserving declaration order; throws for unknown ids. */
-    select<const Ids extends readonly string[]>(ids: Ids): ToolCatalog<App, SelectedTools<Tool, Ids[number]>>;
+    select<const Ids extends readonly string[]>(ids: Ids, context?: App): ToolCatalog<App, SelectedTools<Tool, Ids[number]>>;
+    /** Active tools advertising demand-discovery use; descriptions are view-local. */
+    withIntent(context: App): ToolCatalog<App, Tool>;
     /** Binds the catalog to one App request and returns an invocable runtime. */
     bind(request: {
         app: App;
         execution?: ExecutionOptions;
         errors?: Pick<ToolRegistryPorts, 'unavailable' | 'errorCode'>;
-    }): ToolRuntime<Tool>;
+    }): ToolRuntime<Tool, App>;
 }