@jangts/agent-core 0.3.5 → 0.5.0

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[];
@@ -175,6 +182,8 @@ export type ModelRunnerOptions<Transports extends readonly ModelTransportDefinit
 } & ModelRunnerSettings;
 /** One model call request. The input shape selects prompt mode or message mode. */
 export type ModelCallRequest<Transport = string> = {
+    /** Record this call in the supplied logger; omission adds no sub-flow record. */
+    readonly logger?: import('../debug.js').SubFlowLogger;
     /** Additional cancellation can shorten, never replace, the Runner lifetime. */
     readonly signal?: AbortSignal;
     /** Parent observation scope for this invocation; never changes execution budget or signal. */

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

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

@@ -0,0 +1,26 @@
+import type { AssociatedRegistration, AssociationOptions } from '../structs/support/associations.js';
+/** Compile independent and owner-derived Tool declarations, validating all references eagerly. */
+export declare function defineAssociatedCatalog<Entry extends AssociatedRegistration>(entries: readonly Entry[], options?: AssociationOptions<Entry>): Readonly<{
+    tools: import("../index.js").ModelToolCatalog<any>;
+    bindings: import("../index.js").ReadonlyCatalog<{
+        id: Entry["id"];
+        toolIds: readonly string[];
+    }>;
+    sources: import("../index.js").ReadonlyCatalog<{
+        id: string;
+        sources: readonly Readonly<{
+            toolIds: readonly string[];
+            kind: "standalone" | "registration";
+            id: string;
+            description: string;
+        }>[];
+    }>;
+    definitions: readonly Readonly<Entry>[];
+    ids(): readonly string[];
+    values(): IterableIterator<Readonly<Entry>>;
+    entries(): IterableIterator<readonly [string, Readonly<Entry>]>;
+    has(id: string): boolean;
+    get(id: string): Readonly<Entry> | undefined;
+    require(id: string): Readonly<Entry>;
+}>;
+export type * from '../structs/support/associations.js';

package/dist/esm/support/associations.js

@@ -0,0 +1,76 @@
+/** Compile owner-to-tool relations without parallel intent identities or execution side effects. */
+import { readonlyCatalog } from '../utils/catalog.js';
+import { synchronous } from '../utils/synchronous.js';
+import { defineModelTools } from './model/capabilities.js';
+/** Compile independent and owner-derived Tool declarations, validating all references eagerly. */
+export function defineAssociatedCatalog(entries, options = {}) {
+    const owners = readonlyCatalog(entries, (id) => new TypeError(`Unknown tool owner: ${id}`));
+    const definitions = new Map();
+    const sources = new Map();
+    const declare = (tool, source) => {
+        if (definitions.has(tool.id))
+            throw new TypeError(`Duplicate model tool: ${tool.id}`);
+        definitions.set(tool.id, tool);
+        sources.set(tool.id, [source]);
+    };
+    const independent = new Set();
+    for (const tool of options.tools ?? []) {
+        independent.add(tool.id);
+        declare(tool, {
+            kind: 'standalone',
+            id: tool.id,
+            description: tool.description,
+            toolIds: [tool.id],
+        });
+    }
+    const bindings = owners.definitions.map((owner) => {
+        const fallback = options.toolDefaults
+            ? synchronous(options.toolDefaults(owner), 'Tool defaults must be synchronous')
+            : undefined;
+        const declarations = owner.modelTools ?? (fallback ? [{}] : []);
+        const toolIds = [];
+        for (const declaration of declarations) {
+            if (typeof declaration === 'string') {
+                if (!independent.has(declaration))
+                    throw new TypeError(`Tool reference must name an independent tool: ${owner.id} -> ${declaration}`);
+                sources.get(declaration).push({
+                    kind: 'registration',
+                    id: owner.id,
+                    description: owner.description,
+                    toolIds: [declaration],
+                });
+                toolIds.push(declaration);
+            }
+            else {
+                if (!declaration || typeof declaration !== 'object' || Array.isArray(declaration))
+                    throw new TypeError('Invalid tool association');
+                const tool = {
+                    ...fallback,
+                    ...declaration,
+                    id: declaration.id ?? fallback?.id ?? owner.id,
+                    description: declaration.description ?? fallback?.description ?? owner.description,
+                    resolve: declaration.resolve?.bind(declaration) ?? fallback?.resolve?.bind(fallback),
+                };
+                declare(tool, {
+                    kind: 'registration',
+                    id: owner.id,
+                    description: owner.description,
+                    toolIds: [tool.id],
+                });
+                toolIds.push(tool.id);
+            }
+        }
+        if (new Set(toolIds).size !== toolIds.length)
+            throw new TypeError(`Duplicate tool reference: ${owner.id}`);
+        return Object.freeze({ id: owner.id, toolIds: Object.freeze(toolIds) });
+    });
+    return Object.freeze({
+        ...owners,
+        tools: defineModelTools([...definitions.values()]),
+        bindings: readonlyCatalog(bindings, (id) => new TypeError(`Unknown tool binding: ${id}`)),
+        sources: readonlyCatalog([...sources].map(([id, values]) => Object.freeze({
+            id,
+            sources: Object.freeze(values.map((source) => Object.freeze({ ...source, toolIds: Object.freeze([...source.toolIds]) }))),
+        })), (id) => new TypeError(`Unknown tool source: ${id}`)),
+    });
+}

package/dist/esm/support/context/nodes.js

@@ -9,6 +9,7 @@
  * Main exports: `createContextProcessingNode`, `createContextSelectionNode`,
  * `createContextReductionNode` and their result/definition types.
  */
+import { nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { beginContextProcessing, finishContextProcessing, chooseSteps, applyReduction, needsReduction, watermarks, validateReductionTargets, contextPolicyCatalog, validateContextPolicy, } from './processing.js';
 import { modelRunnerDefaults } from '../../model/defaults.js';
 import { synchronous } from '../../utils/synchronous.js';
@@ -124,53 +125,55 @@ function contextNode(definition, execute) {
         onErrorRouteId: definition.onErrorRouteId,
         routes: definition.routes,
         async run(state, context) {
-            // The node timeout is an additional bound; parent cancellation still wins.
-            const signal = combineSignals(context.signal, AbortSignal.timeout(timeoutMs));
-            const prepared = selectPrepared
-                ? selectPrepared(state, context)
-                : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
-            const input = synchronous(plan(state, context), 'Context plans must be synchronous');
-            // An empty measurement reports the allowance left after transport, instruction and schema
-            // overhead, so processing must fit inside whichever limit is tighter.
-            const overhead = prepared.measure([]);
-            const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
-            const bodyLimit = fullLimit;
-            breakWhile(bodyLimit < 1, 'No input capacity for context');
-            const work = beginContextProcessing({
-                fragments: input.fragments,
-                additionalMessages: input.additionalMessages,
-                originalFragments: input.originalFragments,
-                mutableFragmentIds: input.mutableFragmentIds,
-                maxInputChars: bodyLimit,
-            }, policy, {
-                stageId: prepared.stageId,
-                signal,
-                diagnostics: context.diagnostics,
-                compressors,
-                selectors,
-                // Read lazily so handlers see the live budget rather than the value at preparation.
-                remainingCalls: () => prepared.remainingCalls,
-                callModel: (options) => context.model.invoke({
-                    ...options,
-                    modelId: options.modelId ?? prepared.modelId,
+            return nativeSubFlowAsync(context, 'context', definition.id, async () => {
+                // The node timeout is an additional bound; parent cancellation still wins.
+                const signal = combineSignals(context.signal, AbortSignal.timeout(timeoutMs));
+                const prepared = selectPrepared
+                    ? selectPrepared(state, context)
+                    : context.model.prepare(typeof request === 'function' ? request(state, context) : request);
+                const input = synchronous(plan(state, context), 'Context plans must be synchronous');
+                // An empty measurement reports the allowance left after transport, instruction and schema
+                // overhead, so processing must fit inside whichever limit is tighter.
+                const overhead = prepared.measure([]);
+                const fullLimit = Math.min(input.maxInputChars, overhead.maxInputChars);
+                const bodyLimit = fullLimit;
+                breakWhile(bodyLimit < 1, 'No input capacity for context');
+                const work = beginContextProcessing({
+                    fragments: input.fragments,
+                    additionalMessages: input.additionalMessages,
+                    originalFragments: input.originalFragments,
+                    mutableFragmentIds: input.mutableFragmentIds,
+                    maxInputChars: bodyLimit,
+                }, policy, {
+                    stageId: prepared.stageId,
                     signal,
-                }),
-                ...(overhead.counterId
-                    ? {
-                        tokenBudget: {
-                            counterId: overhead.counterId,
-                            inputLimit: overhead.inputTokenLimit,
-                            measure: (messages) => prepared.measure(messages).inputTokens,
-                        },
-                    }
-                    : {}),
+                    diagnostics: context.diagnostics,
+                    compressors,
+                    selectors,
+                    // Read lazily so handlers see the live budget rather than the value at preparation.
+                    remainingCalls: () => prepared.remainingCalls,
+                    callModel: (options) => context.model.invoke({
+                        ...options,
+                        modelId: options.modelId ?? prepared.modelId,
+                        signal,
+                    }),
+                    ...(overhead.counterId
+                        ? {
+                            tokenBudget: {
+                                counterId: overhead.counterId,
+                                inputLimit: overhead.inputTokenLimit,
+                                measure: (messages) => prepared.measure(messages).inputTokens,
+                            },
+                        }
+                        : {}),
+                });
+                context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
+                const result = await execute(work, prepared, fullLimit, state, context);
+                // Never report or commit a result produced after cancellation.
+                signal.throwIfAborted();
+                context.report({ payload: { phase: 'processed', report: work.report } });
+                return synchronous(update(result, state), 'Context node updates must be synchronous');
             });
-            context.report({ payload: { phase: 'processing', fragmentCount: input.fragments.length } });
-            const result = await execute(work, prepared, fullLimit, state, context);
-            // Never report or commit a result produced after cancellation.
-            signal.throwIfAborted();
-            context.report({ payload: { phase: 'processed', report: work.report } });
-            return synchronous(update(result, state), 'Context node updates must be synchronous');
         },
     };
 }

package/dist/esm/support/context/processing.js

@@ -11,6 +11,7 @@
  * `finishContextProcessing` (staged runs), the policy/reduction catalogs and the individual
  * validation, measurement and reduction helpers used by workflow nodes.
  */
+import { nativeSubFlowAsync } from '../../diagnostics/native-sub-flow.js';
 import { snapshotFragment, snapshotMessage } from './snapshot.js';
 import { auditContextChange as audit } from '../../context/audit.js';
 import { historyGroups, validateRecentHistory } from './history.js';
@@ -595,7 +596,9 @@ export function finishContextProcessing(state) {
  * @throws {BudgetError} When a handler exhausts its call allowance.
  */
 export async function processContext(plan, policy, ports) {
-    const state = beginContextProcessing(plan, policy, ports);
-    await contextPolicyCatalog[policy.mode].run(state);
-    return finishContextProcessing(state);
+    return nativeSubFlowAsync(ports, 'context', policy.mode, async () => {
+        const state = beginContextProcessing(plan, policy, ports);
+        await contextPolicyCatalog[policy.mode].run(state);
+        return finishContextProcessing(state);
+    });
 }

package/dist/esm/support/context/snapshot.js

@@ -17,7 +17,7 @@ export function snapshotFragment(fragment) {
  *   unsupported `detail` value.
  */
 export function snapshotMessage(message) {
-    const { role, content, images } = message;
+    const { role, content, images, toolCalls, toolCallId } = message;
     if (images !== undefined && !Array.isArray(images))
         throw new TypeError('Context images must be an array');
     return {
@@ -34,5 +34,15 @@ export function snapshotMessage(message) {
                     return { url, ...(detail === undefined ? {} : { detail }) };
                 }),
             }),
+        ...(toolCalls === undefined
+            ? {}
+            : {
+                toolCalls: toolCalls.map((call) => ({
+                    id: call.id,
+                    name: call.name,
+                    arguments: call.arguments,
+                })),
+            }),
+        ...(toolCallId === undefined ? {} : { toolCallId }),
     };
 }

package/dist/esm/support/decorators/index.d.ts

@@ -7,6 +7,7 @@ import type { AgentCoreEngineSetup } from '../../execution/engine.js';
 import type { ToolDefinition } from '../../structs/capabilities/tools.js';
 import type { ContextFragmentConfig } from '../../structs/support/context.js';
 import type { ModelRunnerOptions } from '../../structs/model/runtime.js';
+import type { AsIntent, ModelTool } from '../../structs/capabilities/model.js';
 import { type ClassDecoration, type MethodDecoration, type DecorationOptions } from './definition.js';
 import type { IdentifiedDefinition } from './pool.js';
 export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
@@ -15,14 +16,24 @@ export type { ClassDecoration, MethodDecoration, DecorationOptions } from './def
 export type { Node, Tool, Fragment, Workflow, Agent, Model } from './types.js';
 /** Method metadata describes the adapted handler, with optional external namespaces. */
 type MethodOptions<Definition extends IdentifiedDefinition, Key extends keyof Definition> = Omit<Definition, 'id' | Key> & DecorationOptions;
+/** Intent composition belongs to its own decorator, including on definition classes. */
+type WithoutIntent<Definition> = Definition extends unknown ? Omit<Definition, 'asIntent'> & {
+    readonly asIntent?: never;
+} : never;
+/** Mark a WorkflowTool for demand discovery; alone this decorator registers nothing. */
+export declare function Intent<Context = any>(metadata?: AsIntent<Context>): (value: object, context: ClassDecoratorContext | ClassMethodDecoratorContext) => void;
 /** Instantiate a node definition class once, injecting its id; graph validation stays in Workflow. */
 export declare function node<State = any, Result = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<WorkflowNode<State, Result, App>>;
 /** Bind a named host method as run without renaming or manually binding the original object. */
 export declare function node<State = any, Result = unknown, App = any>(id: string, options: MethodOptions<WorkflowNode<State, Result, App>, 'run'>): MethodDecoration<NonNullable<WorkflowNode<State, Result, App>['run']>>;
 /** Instantiate a tool definition class; schema and authorization stay with existing defineTool. */
-export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options?: DecorationOptions): ClassDecoration<ToolDefinition<Input, Output, App>>;
+export declare function tool<Input = any, Output = any, App = any>(id: string, options?: DecorationOptions): ClassDecoration<WithoutIntent<ToolDefinition<Input, Output, App> | ModelTool<Input, Output, App>>>;
 /** Bind an existing host method as the tool's execute callback. */
-export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options: MethodOptions<ToolDefinition<Input, Output, App>, 'execute'>): MethodDecoration<ToolDefinition<Input, Output, App>['execute']>;
+export declare function tool<Input = unknown, Output = unknown, App = any>(id: string, options: MethodOptions<Omit<ToolDefinition<Input, Output, App>, 'asIntent'>, 'execute'>): MethodDecoration<ToolDefinition<Input, Output, App>['execute']>;
+/** A model-only tool method provides its synchronous resolver. */
+export declare function tool<Input = unknown, Output = Input, App = any>(id: string, options: MethodOptions<Omit<ModelTool<Input, Output, App>, 'asIntent'>, 'resolve'>): MethodDecoration<ModelTool<Input, Output, App>['resolve']>;
+/** Explicit workflow names share the same implementation and pools. */
+export { tool as WorkflowTool, node as WorkflowNode };
 /** Instantiate a self-describing fragment class; the original builder owns formatting checks. */
 export declare function fragment<Input = unknown>(id: string, options?: DecorationOptions): ClassDecoration<ContextFragmentConfig<Input>>;
 /** Bind a host's formatter method into an original fragment configuration. */

package/dist/esm/support/decorators/index.js

@@ -1,18 +1,48 @@
 import { defineTool } from '../tools.js';
+import { defineModelTools } from '../model/capabilities.js';
+import { snapshotIntent } from '../../capabilities/tool-conditions.js';
 import { defineWorkflow } from '../../execution/workflow.js';
 import { defineContextFragments } from '../context/assembly.js';
 import { snapshotModelBinding } from '../../model/binding.js';
 import { classDecoration, methodDecoration, } from './definition.js';
 export { nodePool, toolPool, fragmentPool, workflowPool, agentPool, modelPool } from './pool.js';
+/** Metadata follows the actual decorated target, independently of decorator order. */
+const intentKey = Symbol.for('@jangts/agent-core/tool-intent-metadata/v1');
+const realm = globalThis;
+const intentMetadata = realm[intentKey] ?? new WeakMap();
+if (!realm[intentKey])
+    Object.defineProperty(globalThis, intentKey, { value: intentMetadata });
+/** Mark a WorkflowTool for demand discovery; alone this decorator registers nothing. */
+export function Intent(metadata = true) {
+    const normalized = snapshotIntent(metadata);
+    return (value, context) => {
+        if (context.kind !== 'class' && context.kind !== 'method')
+            throw new TypeError('Intent requires a class or method');
+        if (intentMetadata.has(value))
+            throw new TypeError('Duplicate Intent decoration');
+        intentMetadata.set(value, normalized);
+    };
+}
 /** Internal conversion shared by node/tool/fragment; never a public free-function adapter. */
 function decorate(kind, id, options, key, compile) {
     return (value, context) => {
+        const convert = (definition) => {
+            if (kind !== 'tool')
+                return compile(definition);
+            if ('asIntent' in definition)
+                throw new TypeError('Use @Intent instead of asIntent in @WorkflowTool');
+            const metadata = intentMetadata.get(value);
+            // Intent metadata is collected before class/method initializers compile definitions.
+            if (metadata !== undefined)
+                Object.defineProperty(definition, 'asIntent', { value: metadata, enumerable: true });
+            return compile(definition);
+        };
         if (context?.kind === 'class') {
-            classDecoration(kind, id, options, compile)(value, context);
+            classDecoration(kind, id, options, convert)(value, context);
         }
         else {
             const { ns, ...metadata } = options;
-            methodDecoration(kind, id, metadata, key, { ns }, compile)(value, context);
+            methodDecoration(kind, id, metadata, key, { ns }, convert)(value, context);
         }
     };
 }
@@ -20,8 +50,15 @@ export function node(id, options = {}) {
     return decorate('node', id, options, 'run', (value) => value);
 }
 export function tool(id, options = {}) {
-    return decorate('tool', id, options, 'execute', (value) => defineTool(value));
+    if ('asIntent' in options)
+        throw new TypeError('Use @Intent instead of asIntent in @WorkflowTool');
+    const handlerKey = 'inputSchema' in options && !('authorize' in options) ? 'resolve' : 'execute';
+    return decorate('tool', id, options, handlerKey, (value) => 'kind' in value || 'authorize' in value || 'execute' in value
+        ? defineTool(value)
+        : defineModelTools([value]).require(value.id));
 }
+/** Explicit workflow names share the same implementation and pools. */
+export { tool as WorkflowTool, node as WorkflowNode };
 export function fragment(id, options = {}) {
     return decorate('fragment', id, options, 'format', (value) => {
         defineContextFragments([value]);