@jangts/agent-core 0.3.6 → 0.5.0

package/dist/esm/model/index.d.ts

@@ -1,13 +1,9 @@
 /**
  * Public surface of the model protocol layer.
  *
- * Re-exports the runner, the provider and transport contracts, the interaction
- * adapters and the defaults. Everything that interprets model output passes through
- * this module, so consumers should not import the individual files.
+ * Re-exports the runner and the provider/transport contracts. Support implementations are
+ * exported from the package root or `/support`; this Core barrel stays free of Support code.
  */
 export * from './runner.js';
 export * from '../structs/model/chat-provider.js';
-export * from '../support/model/compatible-provider.js';
-export * from '../support/model/transports.js';
-export * from '../support/model/interactions/index.js';
 export { modelRunnerDefaults } from './defaults.js';

package/dist/esm/model/index.js

@@ -1,13 +1,9 @@
 /**
  * Public surface of the model protocol layer.
  *
- * Re-exports the runner, the provider and transport contracts, the interaction
- * adapters and the defaults. Everything that interprets model output passes through
- * this module, so consumers should not import the individual files.
+ * Re-exports the runner and the provider/transport contracts. Support implementations are
+ * exported from the package root or `/support`; this Core barrel stays free of Support code.
  */
 export * from './runner.js';
 export * from '../structs/model/chat-provider.js';
-export * from '../support/model/compatible-provider.js';
-export * from '../support/model/transports.js';
-export * from '../support/model/interactions/index.js';
 export { modelRunnerDefaults } from './defaults.js';

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

@@ -0,0 +1,40 @@
+/**
+ * Tool-call delta aggregation.
+ *
+ * One algorithm is shared by completion policies, session transports and direct callers:
+ * fragments are keyed by their provider index, IDs may not conflict, and a complete call
+ * requires both an ID and a name. A complete call never hides another started but incomplete one.
+ *
+ * Exports: `AggregatedToolCall`, `ToolCallCollector`, `ToolCallFailure` and
+ * `createToolCallCollector`.
+ */
+import type { ModelPart } from '../../structs/model/messages.js';
+/** One completed native tool call in provider index order. */
+export interface AggregatedToolCall {
+    readonly index: number;
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: string;
+}
+/** Report a protocol violation and stop; callers decide how the failure is classified. */
+export type ToolCallFailure = (message: string) => never;
+/** Aggregation entry point for streamed function-call deltas. */
+export interface ToolCallCollector {
+    /** Feed one part; text parts are ignored and cannot satisfy or break a call. */
+    push(part: ModelPart): void;
+    /** Calls started so far, including incomplete ones, in index order. */
+    readonly calls: readonly AggregatedToolCall[];
+    /**
+     * Finalize the calls.
+     *
+     * @throws When any started call is still missing its ID or name.
+     */
+    complete(): readonly AggregatedToolCall[];
+}
+/**
+ * Create a collector for one response.
+ *
+ * @param fail - Protocol failure factory; defaults to the Core model protocol error.
+ * @returns A collector that keeps its own state and never shares it with another response.
+ */
+export declare function createToolCallCollector(fail?: ToolCallFailure): ToolCallCollector;

package/dist/esm/model/interactions/calls.js

@@ -0,0 +1,58 @@
+import { modelProtocolError } from '../../utils/model-protocol.js';
+/**
+ * Create a collector for one response.
+ *
+ * @param fail - Protocol failure factory; defaults to the Core model protocol error.
+ * @returns A collector that keeps its own state and never shares it with another response.
+ */
+export function createToolCallCollector(fail = modelProtocolError) {
+    const pending = new Map();
+    const ids = new Set();
+    const calls = () => [...pending.entries()]
+        .sort(([left], [right]) => left - right)
+        .map(([index, call]) => ({ index, ...call }));
+    return {
+        push(part) {
+            if (typeof part === 'string')
+                return;
+            if (!part || typeof part !== 'object' || Array.isArray(part))
+                fail('Expected a native model call');
+            const { type, index, id, name, arguments: args } = part;
+            if (type !== 'function-call-delta')
+                fail('Expected a native model call');
+            if (!Number.isInteger(index) || index < 0)
+                fail('Invalid model call index');
+            if ((id !== undefined && (typeof id !== 'string' || !id)) ||
+                (name !== undefined && typeof name !== 'string') ||
+                (args !== undefined && typeof args !== 'string'))
+                fail('Invalid model call fields');
+            let call = pending.get(index);
+            if (!call) {
+                call = { id: '', name: '', arguments: '' };
+                pending.set(index, call);
+            }
+            if (id !== undefined) {
+                if (call.id && call.id !== id)
+                    fail('Conflicting model call IDs');
+                if (!call.id) {
+                    if (ids.has(id))
+                        fail('Duplicate model call ID');
+                    ids.add(id);
+                    call.id = id;
+                }
+            }
+            call.name += name ?? '';
+            call.arguments += args ?? '';
+        },
+        get calls() {
+            return calls();
+        },
+        complete() {
+            const completed = calls();
+            for (const call of completed)
+                if (!call.id || !call.name)
+                    fail('Incomplete model call');
+            return completed;
+        },
+    };
+}

package/dist/esm/model/interactions/json-object.js

@@ -22,24 +22,24 @@ export const jsonObjectInteraction = Object.freeze({
     /**
      * Build the instruction and response collector for one stage.
      *
-     * @param capabilities - Capabilities registered for this stage; must be non-empty.
+     * @param tools - Capabilities registered for this stage; must be non-empty.
      * @returns JSON mode options, the measured instruction and the collector factory.
      */
-    prepare(capabilities) {
-        const declarations = capabilities.map(({ id, description, inputSchema }) => ({
+    prepare(tools) {
+        const declarations = tools.map(({ id, description, inputSchema }) => ({
             id,
             description,
             input: inputSchema.jsonSchema,
         }));
         // Keep the wire shape after potentially long schemas so it cannot be mistaken
         // for a schema definition or a bare capability argument object.
-        const instruction = 'Registered capabilities: ' +
+        const instruction = 'Registered tools: ' +
             JSON.stringify(declarations) +
-            '\nReturn exactly one JSON object with exactly these two fields: {"capability":"registered id","input":{...}}. ' +
-            'Choose capability from ' +
-            JSON.stringify(capabilities.map((capability) => capability.id)) +
-            "; input is the chosen capability's actual argument object matching its input schema. " +
-            'Do not return the schema, response_format, an array, multiple calls, prose or fences. The outer object must contain capability and input.';
+            '\nReturn exactly one JSON object with exactly these two fields: {"name":"registered id","input":{...}}. ' +
+            'Choose tool name from ' +
+            JSON.stringify(tools.map((capability) => capability.id)) +
+            "; input is the chosen tool's actual argument object matching its input schema. " +
+            'Do not return the schema, response_format, an array, multiple calls, prose or fences. The outer object must contain name and input.';
         return {
             options: { json: true },
             schemaChars: instruction.length,
@@ -58,10 +58,10 @@ export const jsonObjectInteraction = Object.freeze({
                     finish() {
                         const value = parse(raw);
                         if (Object.keys(value).length !== 2 ||
-                            typeof value.capability !== 'string' ||
+                            typeof value.name !== 'string' ||
                             !Object.hasOwn(value, 'input'))
                             modelProtocolError('Invalid model selection envelope');
-                        return { capabilityId: value.capability, input: object(value.input) };
+                        return { toolId: value.name, input: object(value.input) };
                     },
                 };
             },

package/dist/esm/model/interactions/native-functions.js

@@ -9,6 +9,7 @@
  */
 import { modelProtocolError } from '../../utils/model-protocol.js';
 import { parse, wireName } from './arguments.js';
+import { createToolCallCollector } from './calls.js';
 /**
  * Adapter that decodes a streamed native function call.
  *
@@ -24,15 +25,15 @@ export const nativeFunctionInteraction = Object.freeze({
      * Wire names are derived from capability ids and must stay unique after mapping;
      * a collision would make it impossible to resolve the proposed name back to an id.
      *
-     * @param capabilities - Capabilities registered for this stage; must be non-empty.
+     * @param tools - Capabilities registered for this stage; must be non-empty.
      * @returns Function declarations, the measured instruction and the collector factory.
      * @throws TypeError When two capability ids map to the same wire name.
      */
-    prepare(capabilities) {
-        const names = new Map(capabilities.map((capability) => [wireName(capability.id), capability.id]));
-        if (names.size !== capabilities.length)
+    prepare(tools) {
+        const names = new Map(tools.map((capability) => [wireName(capability.id), capability.id]));
+        if (names.size !== tools.length)
             throw new TypeError('Model wire name collision');
-        const functions = capabilities.map((capability) => ({
+        const functions = tools.map((capability) => ({
             name: wireName(capability.id),
             description: capability.description,
             parameters: capability.inputSchema.jsonSchema,
@@ -44,11 +45,12 @@ export const nativeFunctionInteraction = Object.freeze({
             schemaChars: JSON.stringify(functions).length + instruction.length,
             instruction,
             createResponse() {
+                const collector = createToolCallCollector();
                 let raw = '';
-                let call;
                 return {
                     get outputChars() {
-                        return (raw.length + (call ? call.id.length + call.name.length + call.arguments.length : 0));
+                        return (raw.length +
+                            collector.calls.reduce((sum, call) => sum + call.id.length + call.name.length + call.arguments.length, 0));
                     },
                     push(part) {
                         if (typeof part === 'string') {
@@ -57,32 +59,24 @@ export const nativeFunctionInteraction = Object.freeze({
                         }
                         if (!part || typeof part !== 'object' || Array.isArray(part))
                             modelProtocolError('Expected a native model call');
-                        const { type, index, id, name, arguments: args } = part;
+                        const { type, index } = part;
                         if (type !== 'function-call-delta')
                             modelProtocolError('Expected a native model call');
                         if (index !== 0)
                             modelProtocolError('Expected exactly one model call', 'MODEL_MULTIPLE_CALLS');
-                        if ((id !== undefined && (typeof id !== 'string' || !id)) ||
-                            (name !== undefined && typeof name !== 'string') ||
-                            (args !== undefined && typeof args !== 'string'))
-                            modelProtocolError('Invalid native model call fields');
-                        call ??= { id: '', name: '', arguments: '' };
-                        if (id !== undefined) {
-                            if (call.id && call.id !== id)
-                                modelProtocolError('Conflicting model call IDs');
-                            call.id = id;
-                        }
-                        call.name += name ?? '';
-                        call.arguments += args ?? '';
+                        collector.push(part);
                     },
                     finish() {
-                        if (!call?.id || !call.name || raw.trim())
+                        const calls = collector.complete();
+                        if (calls.length !== 1)
+                            modelProtocolError('Expected exactly one model call', 'MODEL_MULTIPLE_CALLS');
+                        if (raw.trim())
                             modelProtocolError('Expected one complete model call without prose');
-                        const completed = call;
+                        const completed = calls[0];
                         const capability = names.get(completed.name) ??
                             modelProtocolError('Model call is not registered for this stage');
                         return {
-                            capabilityId: capability,
+                            toolId: capability,
                             input: parse(completed.arguments),
                             call: {
                                 id: completed.id,

package/dist/esm/model/message-diagnostics.d.ts

@@ -1,19 +1,20 @@
 /**
  * Redaction of model messages before they are observed or persisted.
  *
- * Diagnostics may keep message text, but image bytes must never leave the process,
- * even when full content logging is enabled.
+ * Diagnostics may keep message text, but image bytes and raw tool arguments must never leave
+ * the process, even when full content logging is enabled.
  *
  * Exports: `modelMessageDiagnostics`.
  */
 import type { ModelMessage } from '../structs/model/messages.js';
 /**
- * Replace every image payload with a placeholder.
+ * Replace every image payload and raw tool argument with a placeholder.
  *
  * Only the `url` is substituted; the `detail` hint is kept because it is small and
- * explains how the image was interpreted. The input array is not mutated.
+ * explains how the image was interpreted. Tool call ids and names remain because they
+ * identify the proposal; raw arguments are redacted. The input array is not mutated.
  *
  * @param messages - Messages about to be reported.
- * @returns New message objects whose images carry a placeholder URL.
+ * @returns New message objects with redacted images and tool arguments.
  */
 export declare function modelMessageDiagnostics(messages: readonly ModelMessage[]): ModelMessage[];

package/dist/esm/model/message-diagnostics.js

@@ -1,11 +1,12 @@
 /**
- * Replace every image payload with a placeholder.
+ * Replace every image payload and raw tool argument with a placeholder.
  *
  * Only the `url` is substituted; the `detail` hint is kept because it is small and
- * explains how the image was interpreted. The input array is not mutated.
+ * explains how the image was interpreted. Tool call ids and names remain because they
+ * identify the proposal; raw arguments are redacted. The input array is not mutated.
  *
  * @param messages - Messages about to be reported.
- * @returns New message objects whose images carry a placeholder URL.
+ * @returns New message objects with redacted images and tool arguments.
  */
 export function modelMessageDiagnostics(messages) {
     return messages.map((message) => ({
@@ -15,5 +16,14 @@ export function modelMessageDiagnostics(messages) {
                 images: message.images.map((image) => ({ ...image, url: '[image omitted]' })),
             }
             : {}),
+        ...(message.toolCalls
+            ? {
+                toolCalls: message.toolCalls.map((call) => ({
+                    id: call.id,
+                    name: call.name,
+                    arguments: '[tool arguments omitted]',
+                })),
+            }
+            : {}),
     }));
 }

package/dist/esm/model/options.js

@@ -15,6 +15,8 @@ export function snapshotModelOptions(options = {}) {
         includeUsage: options.includeUsage,
         onUsage: options.onUsage?.bind(options),
         functions: options.functions,
+        toolChoice: options.toolChoice,
+        parallelToolCalls: options.parallelToolCalls,
     };
     for (const key of Object.keys(snapshot)) {
         if (!(key in options))

package/dist/esm/model/preparation.js

@@ -35,6 +35,23 @@ function snapshotImage(image) {
         (detail !== undefined && !['auto', 'low', 'high', 'original'].includes(detail)), () => new TypeError('Invalid model image'));
     return Object.freeze({ url, ...(detail === undefined ? {} : { detail }) });
 }
+/**
+ * Validate and freeze one assistant tool declaration.
+ *
+ * @param call - Candidate tool call.
+ * @returns A frozen tool call with only the declared fields.
+ * @throws TypeError When the id, name or raw arguments are invalid.
+ */
+function snapshotToolCall(call) {
+    breakWhile(!call || typeof call !== 'object' || Array.isArray(call), () => new TypeError('Invalid model tool call'));
+    const { id, name, arguments: args } = call;
+    breakWhile(typeof id !== 'string' ||
+        !id ||
+        typeof name !== 'string' ||
+        !name ||
+        typeof args !== 'string', () => new TypeError('Invalid model tool call'));
+    return Object.freeze({ id, name, arguments: args });
+}
 /**
  * Snapshot a dynamic transport once, preserving its collector factory receiver.
  *
@@ -95,19 +112,35 @@ export function preparedInputSize(base, prepared) {
     breakWhile(!Array.isArray(base), () => new TypeError('Model messages must be an array'));
     const snapshot = Array.from(base, (message) => {
         breakWhile(!message || typeof message !== 'object' || Array.isArray(message), () => new TypeError('Invalid model message'));
-        const { role, content, images } = message;
-        breakWhile(!['system', 'user', 'assistant'].includes(role) ||
+        const { role, content, images, toolCalls, toolCallId } = message;
+        const assistant = role === 'assistant';
+        const tool = role === 'tool';
+        breakWhile(!['system', 'user', 'assistant', 'tool'].includes(role) ||
             typeof content !== 'string' ||
-            (images !== undefined && !Array.isArray(images)), () => new TypeError('Invalid model message'));
+            (images !== undefined && (!Array.isArray(images) || role !== 'user')) ||
+            (toolCalls !== undefined && (!Array.isArray(toolCalls) || !assistant)) ||
+            (toolCallId !== undefined &&
+                (!tool || typeof toolCallId !== 'string' || toolCallId.length === 0)) ||
+            (tool && (typeof toolCallId !== 'string' || toolCallId.length === 0)), () => new TypeError('Invalid model message'));
         return Object.freeze({
             role,
             content,
-            ...(images === undefined ? {} : { images: Object.freeze(Array.from(images, snapshotImage)) }),
+            ...(images === undefined
+                ? {}
+                : { images: Object.freeze(Array.from(images, snapshotImage)) }),
+            ...(toolCalls === undefined
+                ? {}
+                : { toolCalls: Object.freeze(Array.from(toolCalls, snapshotToolCall)) }),
+            ...(toolCallId === undefined ? {} : { toolCallId }),
         });
     });
     const messages = Object.freeze(modelInputMessages(snapshot, prepared.instruction).map((message) => Object.freeze(message)));
-    const messageChars = snapshot.reduce((sum, message) => sum + message.content.length, 0);
-    const instructionChars = messages.reduce((sum, message) => sum + message.content.length, 0) - messageChars;
+    const contentChars = snapshot.reduce((sum, message) => sum + message.content.length, 0);
+    const messageChars = snapshot.reduce((sum, message) => sum +
+        message.content.length +
+        (message.toolCalls?.reduce((callSum, call) => callSum + call.id.length + call.name.length + call.arguments.length, 0) ?? 0) +
+        (message.toolCallId?.length ?? 0), 0);
+    const instructionChars = messages.reduce((sum, message) => sum + message.content.length, 0) - contentChars;
     const functions = prepared.options.functions;
     const schemaChars = functions
         ? (functionSizes.get(functions) ?? JSON.stringify(functions).length)

package/dist/esm/model/runner.js

@@ -628,6 +628,20 @@ export class ModelRunner {
             catch {
                 /* best-effort metadata */
             }
+            try {
+                const calls = response.calls;
+                if (calls?.length) {
+                    step.calls = calls.map((call) => ({
+                        id: call.id,
+                        name: call.name,
+                        argumentChars: call.argumentChars,
+                        ...(call.toolId === undefined ? {} : { toolId: call.toolId }),
+                    }));
+                }
+            }
+            catch {
+                /* best-effort metadata */
+            }
         };
         const accountOutput = () => {
             const outputChars = response.outputChars;

package/dist/esm/model/selection-transport.js

@@ -30,7 +30,7 @@ export function createModelTransport(registration) {
     const adapter = registration.adapter ?? nativeFunctionInteraction;
     if (registration.requireStrictArguments && !adapter.features.strictArguments)
         throw new TypeError(`Model interaction does not support strict arguments: ${adapter.id}`);
-    const source = registration.capabilities, createSource = typeof source === 'function' ? source.bind(registration) : undefined;
+    const source = registration.tools, createSource = typeof source === 'function' ? source.bind(registration) : undefined;
     const prepare = adapter.prepare.bind(adapter), options = Object.freeze(snapshotModelOptions(registration.options));
     return Object.freeze({
         id: registration.id,
@@ -40,8 +40,8 @@ export function createModelTransport(registration) {
                 : source;
             const definitions = [...catalog.values()];
             if (!definitions.length)
-                throw new TypeError('Model stage requires registered capabilities');
-            const capabilityIds = new Set(definitions.map((capability) => capability.id));
+                throw new TypeError('Model stage requires registered tools');
+            const toolIds = new Set(definitions.map((capability) => capability.id));
             const prepared = synchronous(prepare(definitions), 'Model interaction preparation must be synchronous');
             const createResponse = prepared.createResponse.bind(prepared), resolve = catalog.resolve.bind(catalog);
             return {
@@ -62,7 +62,7 @@ export function createModelTransport(registration) {
                         finish() {
                             const selection = synchronous(buffer.finish(), 'Model selection parsers must be synchronous');
                             call = selection.call;
-                            if (!capabilityIds.has(selection.capabilityId))
+                            if (!toolIds.has(selection.toolId))
                                 modelProtocolError('Model capability is unavailable in this prepared call');
                             return synchronous(resolve(selection, { stageId }), 'Model result parsers must be synchronous');
                         },

package/dist/esm/model/token-budget.js

@@ -49,6 +49,9 @@ export function countModelInput(budget, messages, options) {
     const snapshot = messages.map((message) => ({
         ...message,
         ...(message.images ? { images: message.images.map((image) => ({ ...image })) } : {}),
+        ...(message.toolCalls
+            ? { toolCalls: message.toolCalls.map((call) => ({ ...call })) }
+            : {}),
     }));
     const count = budget.countTokens({
         messages: snapshot,

package/dist/esm/model/transports.d.ts

@@ -8,9 +8,10 @@ import type { ModelTransportDefinition } from '../structs/model/runtime.js';
  *
  * @param id - Unique transport id, also used as the typed handle in `ModelRunner`.
  * @param options - Optional request options; only `temperature` is honored.
+ * @param trim - Trim surrounding whitespace from the final text; defaults to true.
  * @returns A frozen transport definition.
  */
-export declare function createPlainTextTransport<const Id extends string>(id: Id, options?: Pick<ModelOptions, 'temperature'>): ModelTransportDefinition<string> & {
+export declare function createPlainTextTransport<const Id extends string>(id: Id, options?: Pick<ModelOptions, 'temperature'>, trim?: boolean): ModelTransportDefinition<string> & {
     readonly id: Id;
 };
 /**

package/dist/esm/model/transports.js

@@ -45,16 +45,17 @@ function textResponse(decode) {
  *
  * @param id - Unique transport id, also used as the typed handle in `ModelRunner`.
  * @param options - Optional request options; only `temperature` is honored.
+ * @param trim - Trim surrounding whitespace from the final text; defaults to true.
  * @returns A frozen transport definition.
  */
-export function createPlainTextTransport(id, options = {}) {
+export function createPlainTextTransport(id, options = {}, trim = true) {
     const settings = Object.freeze({ ...snapshotModelOptions(options), json: false });
     return Object.freeze({
         id,
         prepare: (_stageId) => ({
             options: settings,
             schemaChars: 0,
-            createResponse: () => textResponse((raw) => raw.trim()),
+            createResponse: () => textResponse((raw) => (trim ? raw.trim() : raw)),
         }),
     });
 }

package/dist/esm/structs/capabilities/invocation.d.ts

@@ -47,7 +47,7 @@ export interface InvocationHandler<Input, Context> {
      */
     call(input: Input, context: Context, execution: import('./tools.js').ToolExecutionContext): void;
 }
-/** Optional capabilities the lifecycle resolves from the host context for one invocation. */
+/** Optional tools the lifecycle resolves from the host context for one invocation. */
 export interface ToolInvocationPorts<Context> {
     /** Explicit recorder selected for this invocation only. */
     readonly logger?: (context: Context) => import('../debug.js').SubFlowLogger | undefined;

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

@@ -5,18 +5,42 @@
  * host value. Registration snapshots the schema and pins the resolver, so a request can project a
  * sealed subset without cloning handlers.
  *
- * Exports: `ModelCapability`, `ModelCapabilityRegistration`, `RegisteredModelCapability`,
- * `ModelSelection`, `ModelCapabilitySource`, `ModelCapabilityCatalog`.
+ * Exports: `ModelTool`, `ModelToolRegistration`, `RegisteredModelTool`,
+ * `ModelSelection`, `ModelToolSource`, `ModelToolCatalog`.
  */
 import type { SchemaAdapter, ReadonlyCatalog } from '../common.js';
-/** One selectable model operation. */
-export interface ModelCapability<Input = unknown, Output = Input> {
+/** A model proposal, not an authorization or execution receipt. */
+export interface ToolProposal {
+    readonly toolId: string;
+    readonly input: unknown;
+}
+/** Read-only host data without changing explicit any/unknown erasure into an object constraint. */
+export type ToolContext<Context> = unknown extends Context ? Context : Readonly<Context>;
+/** Demand-facing hints attached to one Tool; no independent identity is created. */
+export interface IntentOptions<Context> {
+    /** Optional demand-facing description; otherwise the tool description is reused. */
+    readonly description?: string;
+    /** Synchronous participation predicate. */
+    readonly when?: (context: ToolContext<Context>) => boolean;
+    /** Allowed continuation delegates, not an execution sequence. */
+    readonly delegates?: readonly string[];
+}
+/** Demand-discovery metadata; it has no identity independent of its tool. */
+export type AsIntent<Context> = true | string | ((context: ToolContext<Context>) => boolean) | IntentOptions<Context>;
+/** Activation is independent of participation in demand discovery. */
+export type ToolCondition<Context> = boolean | ((context: ToolContext<Context>) => boolean);
+/** Common selectable model interface; resolution proposes a value without business execution. */
+export interface ModelTool<Input = unknown, Output = Input, Context = any> {
     /** Unique id within its registry; never blank. */
     readonly id: string;
     /** Model-visible description explaining when the capability applies. */
     readonly description: string;
     /** Schema describing the arguments; must be an object schema. */
     readonly inputSchema: SchemaAdapter<Input>;
+    /** Omitted means active. Authorization remains a separate execution boundary. */
+    readonly active?: ToolCondition<Context>;
+    /** Omitted means this tool is not advertised by withIntent(). */
+    readonly asIntent?: AsIntent<Context>;
     /**
      * Converts validated arguments into the value handed back to the caller.
      *
@@ -27,9 +51,11 @@ export interface ModelCapability<Input = unknown, Output = Input> {
     }>): Output;
 }
 /** Registration form: input typing is erased, output typing is preserved. */
-export type ModelCapabilityRegistration<Output = unknown> = ModelCapability<any, Output>;
+export type ModelToolRegistration<Output = unknown> = Omit<ModelTool<any, Output>, 'resolve'> & {
+    readonly resolve?: ModelTool<any, Output>['resolve'];
+};
 /** Frozen snapshot stored by a registry after schema validation. */
-export type RegisteredModelCapability<Output = unknown> = Readonly<ModelCapability<unknown, Output>>;
+export type RegisteredModelTool<Output = unknown> = Readonly<ModelTool<unknown, Output>>;
 /** A model's chosen capability together with its parsed arguments. */
 export type ModelSelection = {
     /** Arguments exactly as produced by the model, before schema parsing. */
@@ -41,15 +67,20 @@ export type ModelSelection = {
         argumentChars: number;
     };
     /** Capability the selection resolved to. */
-    readonly capabilityId: string;
+    readonly toolId: string;
 };
-/** Minimal source a stage needs: enumerate capabilities and resolve one selection. */
-export interface ModelCapabilitySource<Output = unknown> {
-    values(): IterableIterator<RegisteredModelCapability<Output>>;
+/** Minimal source a stage needs: enumerate tools and resolve one selection. */
+export interface ModelToolSource<Output = unknown> {
+    values(): IterableIterator<RegisteredModelTool<Output>>;
     /** Resolves one selection; throws when the capability is absent from this source. */
     resolve(selection: ModelSelection, context: Readonly<{
         stageId: string;
     }>): Output;
 }
 /** A compiled entity catalog also supports the minimal stage source contract. */
-export type ModelCapabilityCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelCapability<Output>> & ModelCapabilitySource<Output>;
+export type ModelToolCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelTool<Output>> & ModelToolSource<Output> & {
+    /** Explicit selection, optionally filtered against a host context. */
+    select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>;
+    /** Demand-facing active tools; no workflow node or invocation is implied. */
+    withIntent(context: unknown): ModelToolCatalog<Output>;
+};