@jangts/agent-core 0.3.5 → 0.5.0

package/dist/cjs/support/model/stage-transport.js

@@ -2,7 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createStageModelTransport = createStageModelTransport;
 /**
- * Stage-scoped model transport: expose only the capabilities declared for each stage.
+ * Stage-scoped model transport: expose only the tools declared for each stage.
  *
  * Static capability sources are projected once at construction; dynamic sources are re-projected
  * at the model boundary. Either way, an undeclared stage or capability is rejected rather than
@@ -19,14 +19,14 @@ const transports_js_1 = require("./transports.js");
  *
  * @param registration Transport declaration: unique ID, stage-to-capability references, interaction
  *   adapter, options and a static or per-stage capability source.
- * @returns A Core model transport with `capabilities(stage)`.
+ * @returns A Core model transport with `tools(stage)`.
  * @throws {Error} When a stage ID repeats, has no capability IDs, the declaration has no stages, a
  *   stage or capability is not registered, or a dynamic capability source is asynchronous.
  */
 function createStageModelTransport(registration) {
     const stages = new Map();
     for (const stage of registration.stages) {
-        const ids = stage.capabilityIds;
+        const ids = stage.toolIds;
         (0, rules_js_1.breakWhile)(!stage.id?.trim() ||
             stages.has(stage.id) ||
             !Array.isArray(ids) ||
@@ -35,15 +35,15 @@ function createStageModelTransport(registration) {
         stages.set(stage.id, Object.freeze([...ids]));
     }
     (0, rules_js_1.breakWhile)(!stages.size, 'Model transport requires declared stages');
-    const { id, adapter, options, requireStrictArguments, capabilities: source } = registration;
-    const project = (stage, capabilities) => {
+    const { id, adapter, options, requireStrictArguments, tools: source } = registration;
+    const project = (stage, tools) => {
         const ids = stages.get(stage);
         (0, rules_js_1.breakWhile)(!ids, `Unregistered model stage: ${id} -> ${stage}`);
-        const catalog = new model_js_1.ModelCapabilityRegistry(capabilities.values());
+        const catalog = new model_js_1.ModelToolRegistry(tools.values());
         for (const id of ids)
             (0, rules_js_1.breakWhile)(!catalog.has(id), `Unregistered model capability: ${stage} -> ${id}`);
         const selected = catalog.select(ids);
-        const resolve = capabilities.resolve.bind(capabilities);
+        const resolve = tools.resolve.bind(tools);
         return Object.freeze({
             values: () => selected.values(),
             resolve(selection, context) {
@@ -61,7 +61,7 @@ function createStageModelTransport(registration) {
         adapter,
         options,
         requireStrictArguments,
-        capabilities(stage) {
+        tools(stage) {
             (0, rules_js_1.breakWhile)(!stages.has(stage), `Unregistered model stage: ${id} -> ${stage}`);
             return fixed
                 ? fixed.get(stage)

package/dist/cjs/support/model/transports.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createModelTransport = void 0;
+exports.prepareSessionFunctions = exports.createSessionModelTransport = exports.createModelTransport = void 0;
 exports.createTextTransport = createTextTransport;
 exports.createJsonTransport = createJsonTransport;
 /**
@@ -18,6 +18,9 @@ const model_protocol_js_1 = require("../../utils/model-protocol.js");
 const transports_js_1 = require("../../model/transports.js");
 var selection_transport_js_1 = require("../../model/selection-transport.js");
 Object.defineProperty(exports, "createModelTransport", { enumerable: true, get: function () { return selection_transport_js_1.createModelTransport; } });
+var session_js_1 = require("./session.js");
+Object.defineProperty(exports, "createSessionModelTransport", { enumerable: true, get: function () { return session_js_1.createSessionModelTransport; } });
+Object.defineProperty(exports, "prepareSessionFunctions", { enumerable: true, get: function () { return session_js_1.prepareSessionFunctions; } });
 /**
  * Create a plain-text transport that trims the assembled response.
  *
@@ -25,7 +28,7 @@ Object.defineProperty(exports, "createModelTransport", { enumerable: true, get:
  * @returns A frozen Core transport definition typed as string output.
  */
 function createTextTransport(definition) {
-    return (0, transports_js_1.createPlainTextTransport)(definition.id, definition.options);
+    return (0, transports_js_1.createPlainTextTransport)(definition.id, definition.options, definition.trim);
 }
 /**
  * Create a typed JSON transport without a capability-selection envelope.

package/dist/cjs/support/tools.js

@@ -6,7 +6,7 @@ exports.defineToolCatalog = defineToolCatalog;
  * Tool support: turn typed application tool definitions into a Core-schedulable tool catalog.
  *
  * A tool declaration pairs an input schema with authorization, execution and output parsing. The
- * catalog projects those tools into model capabilities and binds them to the Core tool registry
+ * catalog projects those tools into model tools and binds them to the Core tool registry
  * when a runtime request supplies the application. Support only assembles the registration; Core
  * still performs authorization, invocation, budgets and cancellation.
  *
@@ -17,6 +17,7 @@ const tool_runtime_js_1 = require("./tool-runtime.js");
 const schema_js_1 = require("./schema.js");
 const catalog_js_1 = require("../utils/catalog.js");
 const synchronous_js_1 = require("../utils/synchronous.js");
+const tool_conditions_js_1 = require("../capabilities/tool-conditions.js");
 /**
  * Validate one tool declaration and freeze a detached copy of it.
  *
@@ -39,11 +40,24 @@ function defineTool(definition) {
         throw new TypeError('Missing tool handler');
     const inputSchema = (0, schema_js_1.defineSchema)(definition.inputSchema);
     const authorize = definition.authorize.bind(definition);
+    if (definition.active !== undefined &&
+        typeof definition.active !== 'boolean' &&
+        typeof definition.active !== 'function')
+        throw new TypeError('Invalid tool active condition');
+    const active = typeof definition.active === 'function'
+        ? definition.active.bind(definition)
+        : definition.active;
+    const asIntent = (0, tool_conditions_js_1.bindIntent)((0, tool_conditions_js_1.snapshotIntent)(typeof definition.asIntent === 'function'
+        ? definition.asIntent.bind(definition)
+        : definition.asIntent), definition);
     return Object.freeze({
         id,
         kind,
         description,
         inputSchema,
+        active,
+        asIntent,
+        resolve: definition.resolve?.bind(definition) ?? ((input) => ({ toolId: id, input })),
         authorize(input, context) {
             return (0, synchronous_js_1.maybeAssertion)(authorize(input, context), 'Authorization must return void; rejection must throw');
         },
@@ -52,22 +66,14 @@ function defineTool(definition) {
         parseOutput: definition.parseOutput.bind(definition),
     });
 }
-/**
- * Compile tool declarations into a frozen catalog with model capabilities and runtime binding.
- *
- * Each tool becomes a model capability whose resolver returns `{ toolId, input }`; the model only
- * chooses among registered tools, it never invokes them directly.
- *
- * @param definitions Tool declarations in catalog order.
- * @returns A frozen catalog with `capabilities`, `select` and `bind`.
- * @throws {TypeError} When a tool declaration is invalid or a tool ID is duplicated.
- */
 function defineToolCatalog(definitions) {
     const entries = definitions.map((definition) => defineTool(definition));
     const view = (0, catalog_js_1.readonlyCatalog)(entries, (id) => new TypeError(`Unknown tool: ${id}`));
-    const capabilities = new model_js_1.ModelCapabilityRegistry(entries.map((tool) => ({
+    const tools = new model_js_1.ModelToolRegistry(entries.map((tool) => ({
         id: tool.id,
         description: tool.description,
+        active: tool.active,
+        asIntent: tool.asIntent,
         inputSchema: (0, schema_js_1.defineSchema)({
             jsonSchema: tool.inputSchema.jsonSchema,
             parse: (input) => input,
@@ -76,7 +82,7 @@ function defineToolCatalog(definitions) {
     }))).seal();
     return Object.freeze({
         ...view,
-        capabilities,
+        tools,
         /**
          * Narrow the catalog to the given tool IDs, preserving their declaration order.
          *
@@ -84,9 +90,28 @@ function defineToolCatalog(definitions) {
          * @returns A new catalog containing only the selected tools.
          * @throws {TypeError} When an ID is not registered in this catalog.
          */
-        select(ids) {
-            capabilities.select(ids);
-            return defineToolCatalog(ids.map((id) => view.require(id)));
+        select(ids, ...context) {
+            const seen = new Set();
+            const selected = ids
+                .map((id) => {
+                if (seen.has(id))
+                    throw new TypeError(`Duplicate tool selection: ${id}`);
+                seen.add(id);
+                if (!view.has(id))
+                    throw new TypeError(`Tool is not registered: ${id}`);
+                return view.require(id);
+            })
+                .filter((tool) => !context.length || (0, tool_conditions_js_1.toolActive)(tool.active, context[0]));
+            return defineToolCatalog(selected);
+        },
+        /** Discover demand-facing executable tools while preserving their execution contracts. */
+        withIntent(context) {
+            return defineToolCatalog(entries.flatMap((tool) => {
+                if (!(0, tool_conditions_js_1.toolActive)(tool.active, context))
+                    return [];
+                const description = (0, tool_conditions_js_1.intentDescription)(tool.asIntent, tool.description, context);
+                return description === undefined ? [] : [{ ...tool, description }];
+            }));
         },
         /**
          * Bind the catalog to one application runtime request.
@@ -103,7 +128,7 @@ function defineToolCatalog(definitions) {
                 errors: request.errors,
             });
             return Object.freeze({
-                capabilities,
+                tools,
                 get events() {
                     return registry.events;
                 },

package/dist/cjs/utils/invocation.js

@@ -46,6 +46,7 @@ function toolInvocation(request, arity) {
         throw new TypeError('Use one tool request with toolId and input');
     }
     return {
+        logger: request.logger,
         toolId: request.toolId,
         input: request.input,
         diagnostics: request.diagnostics,

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

@@ -1,22 +1,17 @@
 /**
- * Capability registration surface: model capabilities, executable tools and host-selected
+ * Capability registration surface: model tools, executable tools and host-selected
  * invocations.
  *
- * These registries hold declarations only. Which capabilities a stage may use, whether a
+ * These registries hold declarations only. Which tools a stage may use, whether a
  * call is authorized, and what a payload means remain App decisions; this barrel provides
- * the mechanisms that validate, seal and execute those declarations.
+ * the mechanisms that validate, seal and execute those declarations. Optional Kit helpers
+ * such as interaction protocols and commands are imported from their own `/kits/*` entries.
  *
  * Exports: the model capability registry (`model`), the executable tool registry and its
  * sync/async invocation entry points (`tools`), host-selected invocation execution
- * (`invocation`), and the Interaction Kit's protocol, command and handler definitions that
- * shape and validate model-produced interactions.
+ * (`invocation`) and the shared protocol registry.
  */
 export * from './model.js';
 export * from './tools.js';
 export * from './invocation.js';
 export * from '../utils/protocol-registry.js';
-export { defineCommand, commandSchema } from '../kits/interaction/command.js';
-export type { Command, CommandDefinition, ProtocolCheck, ProtocolField, ProtocolReason, ProtocolPredicate, ProtocolShape, RegisteredProtocol, } from '../structs/kits/interaction.js';
-export * from '../kits/interaction/commands.js';
-export * from '../kits/interaction/transfer.js';
-export * from '../kits/interaction/handlers.js';

package/dist/esm/capabilities/index.js

@@ -1,21 +1,17 @@
 /**
- * Capability registration surface: model capabilities, executable tools and host-selected
+ * Capability registration surface: model tools, executable tools and host-selected
  * invocations.
  *
- * These registries hold declarations only. Which capabilities a stage may use, whether a
+ * These registries hold declarations only. Which tools a stage may use, whether a
  * call is authorized, and what a payload means remain App decisions; this barrel provides
- * the mechanisms that validate, seal and execute those declarations.
+ * the mechanisms that validate, seal and execute those declarations. Optional Kit helpers
+ * such as interaction protocols and commands are imported from their own `/kits/*` entries.
  *
  * Exports: the model capability registry (`model`), the executable tool registry and its
  * sync/async invocation entry points (`tools`), host-selected invocation execution
- * (`invocation`), and the Interaction Kit's protocol, command and handler definitions that
- * shape and validate model-produced interactions.
+ * (`invocation`) and the shared protocol registry.
  */
 export * from './model.js';
 export * from './tools.js';
 export * from './invocation.js';
 export * from '../utils/protocol-registry.js';
-export { defineCommand, commandSchema } from '../kits/interaction/command.js';
-export * from '../kits/interaction/commands.js';
-export * from '../kits/interaction/transfer.js';
-export * from '../kits/interaction/handlers.js';

package/dist/esm/capabilities/invocation.js

@@ -8,6 +8,7 @@
  *
  * Exports: `executeInvocation` and the invocation contracts re-exported at the bottom.
  */
+import { nativeSubFlowSync } from '../diagnostics/native-sub-flow.js';
 import { invocationId } from '../utils/invocation.js';
 import { synchronous } from '../utils/synchronous.js';
 import { diagnosticError } from '../diagnostics/index.js';
@@ -28,12 +29,30 @@ import { NodeReports } from '../execution/reporting.js';
  *   signal checks.
  */
 export function executeInvocation(invocation, input, context, ports = {}) {
+    let logger;
+    try {
+        logger = ports.logger?.(context);
+    }
+    catch {
+        /* Optional recording cannot block execution. */
+    }
+    const callId = invocationId();
+    return nativeSubFlowSync({
+        logger,
+        invocationId: callId,
+        get signal() {
+            return ports.signal?.(context);
+        },
+    }, 'invocation', invocation.id, (scopedLogger) => runInvocation(invocation, input, context, ports, scopedLogger, callId));
+}
+/** Execute the existing synchronous lifecycle without changing journal or error precedence. */
+function runInvocation(invocation, input, context, ports, logger, executionId = invocationId()) {
     const toolId = invocation.id;
     // Identify the call before touching the ports: journal and diagnostics records cannot be
     // reconciled with an anonymous handler.
     if (!toolId?.trim())
         throw new TypeError('Invalid invocation handler identity');
-    const journal = ports.journal?.(context), id = invocationId(), startedAtMs = Date.now();
+    const journal = ports.journal?.(context), id = executionId, startedAtMs = Date.now();
     const diagnostics = ports.diagnostics?.(context)?.child(id, {
         invocationId: id,
         nodeRole: 'invocation',
@@ -64,6 +83,7 @@ export function executeInvocation(invocation, input, context, ports = {}) {
         // The helper rejects a promise and drains its rejection: a handler that turns async must
         // fail here instead of escaping as an unhandled rejection.
         synchronous(invocation.call(input, context, {
+            logger,
             mode: 'sync',
             invocationId: id,
             signal: signal ?? new AbortController().signal,

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

@@ -1,7 +1,7 @@
-import type { ModelCapabilityRegistration, RegisteredModelCapability, ModelSelection } from '../structs/capabilities/model.js';
+import type { ModelToolRegistration, RegisteredModelTool, ModelSelection } from '../structs/capabilities/model.js';
 export { modelProtocolError } from '../utils/model-protocol.js';
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
-export declare class ModelCapabilityRegistry {
+export declare class ModelToolRegistry {
     /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     private readonly definitionsById;
     /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
@@ -11,7 +11,7 @@ export declare class ModelCapabilityRegistry {
      * @throws TypeError when a definition is invalid or its id is duplicated (raised by
      *   `register`).
      */
-    constructor(definitions?: Iterable<ModelCapabilityRegistration>);
+    constructor(definitions?: Iterable<ModelToolRegistration>);
     /**
      * Register one capability.
      *
@@ -21,28 +21,28 @@ export declare class ModelCapabilityRegistry {
      * @throws Error when the registry is already sealed.
      * @throws TypeError when the declaration is invalid or its id is already registered.
      */
-    register<Result>(capability: ModelCapabilityRegistration<Result>): this;
+    register<Result>(capability: ModelToolRegistration<Result>): this;
     /** Frozen snapshot of the registered definitions, in insertion order. */
-    get definitions(): readonly Readonly<RegisteredModelCapability>[];
+    get definitions(): readonly Readonly<RegisteredModelTool>[];
     /** Registered ids in declaration order. */
     ids(): readonly string[];
     /** Live iterator over `[id, definition]` pairs; it reflects only entries added before sealing. */
-    entries(): IterableIterator<readonly [string, RegisteredModelCapability]>;
+    entries(): IterableIterator<readonly [string, RegisteredModelTool]>;
     /**
-     * Register several capabilities.
+     * Register several tools.
      *
      * @param definitions Declarations applied in iteration order.
      * @returns This registry, for chaining.
      * @throws Error or TypeError under the same conditions as `register`.
      */
-    registerAll(definitions: Iterable<ModelCapabilityRegistration>): this;
+    registerAll(definitions: Iterable<ModelToolRegistration>): this;
     /**
      * @param id Capability id.
      * @returns The registered definition.
      * @throws TypeError when the id is not registered, which usually means a stage projection
      *   omitted it.
      */
-    require(id: string): RegisteredModelCapability;
+    require(id: string): RegisteredModelTool;
     /**
      * @param id Capability id.
      * @returns Whether the id is registered in this registry.
@@ -52,9 +52,9 @@ export declare class ModelCapabilityRegistry {
      * @param id Capability id.
      * @returns The registered definition, or undefined when absent.
      */
-    get(id: string): RegisteredModelCapability | undefined;
+    get(id: string): RegisteredModelTool | undefined;
     /** Live iterator over the registered definitions. */
-    values(): IterableIterator<RegisteredModelCapability>;
+    values(): IterableIterator<RegisteredModelTool>;
     /**
      * Close the registry to further registration.
      *
@@ -72,7 +72,11 @@ export declare class ModelCapabilityRegistry {
      * @throws TypeError when the selection is empty or contains a duplicate id.
      * @throws Error when an id was never registered.
      */
-    select(ids: readonly string[]): ModelCapabilityRegistry;
+    select(ids: readonly string[], context?: unknown): ModelToolRegistry;
+    /** Discover active demand-facing tools without tying the projection to a workflow entry. */
+    withIntent(context: unknown): ModelToolRegistry;
+    /** Pin the host context and recheck activation before accepting a model proposal. */
+    private bound;
     /**
      * Parse model-supplied arguments and run the selected capability.
      *
@@ -87,4 +91,4 @@ export declare class ModelCapabilityRegistry {
         stageId: string;
     }>): unknown;
 }
-export type { ModelCapability, ModelCapabilityRegistration, RegisteredModelCapability, ModelSelection, ModelCapabilitySource, ModelCapabilityCatalog, } from '../structs/capabilities/model.js';
+export type { AsIntent, IntentOptions, ToolCondition, ToolContext, ToolProposal, ModelTool, ModelToolRegistration, RegisteredModelTool, ModelSelection, ModelToolSource, ModelToolCatalog, } from '../structs/capabilities/model.js';

package/dist/esm/capabilities/model.js

@@ -1,5 +1,5 @@
 /**
- * Declarative catalog of model capabilities for a request or one stage projection.
+ * Declarative catalog of model tools for a request or one stage projection.
  *
  * A capability pairs an id and description with an input schema and a synchronous resolver,
  * letting stage code parse model-supplied arguments and produce a typed value. Registration
@@ -9,14 +9,15 @@
  * The registry is mutable until `seal()`. `select()` derives a sealed subset for a stage and
  * shares the already-frozen entries rather than re-validating or re-wrapping them.
  *
- * Exports: `ModelCapabilityRegistry`, `modelProtocolError`, and the capability types.
+ * Exports: `ModelToolRegistry`, `modelProtocolError`, and the capability types.
  */
 import { synchronous } from '../utils/synchronous.js';
 import { modelProtocolError } from '../utils/model-protocol.js';
 import { snapshotSchemaAdapter } from '../utils/schema-adapter.js';
+import { snapshotIntent, toolActive, intentDescription, bindIntent } from './tool-conditions.js';
 export { modelProtocolError } from '../utils/model-protocol.js';
 /** A request/stage projection is a sealed registry. Hosts filter availability before projection. */
-export class ModelCapabilityRegistry {
+export class ModelToolRegistry {
     /** Insertion-ordered entries; iteration order is the declaration order of the catalog. */
     definitionsById = new Map();
     /** Sealing is one-way: stage-time code must never extend the catalog it is executing. */
@@ -47,13 +48,22 @@ export class ModelCapabilityRegistry {
         if (!capability.id?.trim() ||
             !capability.description?.trim() ||
             schema?.type !== 'object' ||
-            typeof capability.resolve !== 'function' ||
+            (capability.resolve !== undefined && typeof capability.resolve !== 'function') ||
+            (capability.active !== undefined &&
+                typeof capability.active !== 'function' &&
+                typeof capability.active !== 'boolean') ||
             this.definitionsById.has(capability.id))
             throw new TypeError('Invalid or duplicate model capability');
         // Clone and freeze the schema, and pin `parse`, so the stored entry is independent of
         // the definition object the host may keep mutating.
         const inputSchema = snapshotSchemaAdapter(capability.inputSchema, 'Model input parsers must be synchronous');
-        const resolver = capability.resolve.bind(capability);
+        const resolver = capability.resolve?.bind(capability) ?? ((value) => value);
+        const asIntent = bindIntent(snapshotIntent(typeof capability.asIntent === 'function'
+            ? capability.asIntent.bind(capability)
+            : capability.asIntent), capability);
+        const active = typeof capability.active === 'function'
+            ? capability.active.bind(capability)
+            : capability.active;
         // Bind once here: a later caller cannot substitute its own receiver for the resolver.
         const resolve = (value, context) => synchronous(resolver(value, context), 'Model capability resolvers must be synchronous');
         this.definitionsById.set(capability.id, Object.freeze({
@@ -61,6 +71,8 @@ export class ModelCapabilityRegistry {
             description: capability.description,
             inputSchema,
             resolve,
+            ...(asIntent !== undefined ? { asIntent } : {}),
+            ...(active !== undefined ? { active } : {}),
         }));
         return this;
     }
@@ -77,7 +89,7 @@ export class ModelCapabilityRegistry {
         return this.definitionsById.entries();
     }
     /**
-     * Register several capabilities.
+     * Register several tools.
      *
      * @param definitions Declarations applied in iteration order.
      * @returns This registry, for chaining.
@@ -138,21 +150,53 @@ export class ModelCapabilityRegistry {
      * @throws TypeError when the selection is empty or contains a duplicate id.
      * @throws Error when an id was never registered.
      */
-    select(ids) {
+    select(ids, context) {
         if (!ids.length || new Set(ids).size !== ids.length)
             throw new TypeError('Invalid capability selection');
-        const selected = new ModelCapabilityRegistry();
+        const selected = new ModelToolRegistry();
         for (const id of ids) {
             const capability = this.definitionsById.get(id);
             if (!capability)
                 throw new Error(`Model capability is not registered: ${id}`);
+            if (arguments.length > 1) {
+                if (!toolActive(capability.active, context))
+                    continue;
+            }
+            else if (capability.active === false) {
+                // Boolean activation is evaluable without a host context; predicate activation still
+                // needs an explicit context projection.
+                continue;
+            }
             // Registration already detached/froze the schema and pinned its handlers.
             // Stage projections share those immutable entries, not another clone and
             // another layer of parser/resolver wrappers for every selection.
-            selected.definitionsById.set(id, capability);
+            selected.definitionsById.set(id, arguments.length > 1 ? this.bound(capability, context) : capability);
         }
         return selected.seal();
     }
+    /** Discover active demand-facing tools without tying the projection to a workflow entry. */
+    withIntent(context) {
+        const selected = new ModelToolRegistry();
+        for (const tool of this.definitionsById.values()) {
+            if (!toolActive(tool.active, context))
+                continue;
+            const description = intentDescription(tool.asIntent, tool.description, context);
+            if (description !== undefined)
+                selected.definitionsById.set(tool.id, Object.freeze({ ...this.bound(tool, context), description }));
+        }
+        return selected.seal();
+    }
+    /** Pin the host context and recheck activation before accepting a model proposal. */
+    bound(tool, context) {
+        return Object.freeze({
+            ...tool,
+            resolve: (input, stage) => {
+                if (!toolActive(tool.active, context))
+                    modelProtocolError('Tool is inactive');
+                return tool.resolve(input, stage);
+            },
+        });
+    }
     /**
      * Parse model-supplied arguments and run the selected capability.
      *
@@ -167,7 +211,7 @@ export class ModelCapabilityRegistry {
         const { stageId } = context;
         // Model output is untrusted: unknown ids and non-object arguments are protocol failures,
         // not ordinary `undefined` results.
-        const capability = this.definitionsById.get(selection.capabilityId) ??
+        const capability = this.definitionsById.get(selection.toolId) ??
             modelProtocolError('Model capability is unavailable in this stage');
         if (!selection.input || typeof selection.input !== 'object' || Array.isArray(selection.input))
             modelProtocolError('Model capability input must be an object');

package/dist/esm/capabilities/tool-conditions.d.ts

@@ -0,0 +1,9 @@
+import type { AsIntent, ToolCondition } from '../structs/capabilities/model.js';
+/** Validate and snapshot discovery metadata without evaluating host predicates. */
+export declare function snapshotIntent<Context>(value: AsIntent<Context> | undefined): AsIntent<Context> | undefined;
+/** Bind an optional object-form predicate to its owning Tool, without touching other forms. */
+export declare function bindIntent<Context>(value: AsIntent<Context> | undefined, owner: unknown): AsIntent<Context> | undefined;
+/** Check activation and reject asynchronous or nonboolean predicate results. */
+export declare function toolActive<Context>(condition: ToolCondition<Context> | undefined, context: Context): boolean;
+/** Resolve the demand-facing description only when discovery is enabled. */
+export declare function intentDescription<Context>(metadata: AsIntent<Context> | undefined, fallback: string, context: Context): string | undefined;

package/dist/esm/capabilities/tool-conditions.js

@@ -0,0 +1,59 @@
+/** Tool metadata validation and synchronous activation shared by registration and execution. */
+import { booleanResult } from '../utils/synchronous.js';
+/** Validate and snapshot discovery metadata without evaluating host predicates. */
+export function snapshotIntent(value) {
+    if (value === undefined || value === true || typeof value === 'function')
+        return value;
+    if (typeof value === 'string') {
+        if (!value.trim())
+            throw new TypeError('Intent description must not be blank');
+        return value;
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new TypeError('Invalid asIntent metadata');
+    if (value.description !== undefined &&
+        (typeof value.description !== 'string' || !value.description.trim()))
+        throw new TypeError('Invalid intent description');
+    if (value.when !== undefined && typeof value.when !== 'function')
+        throw new TypeError('Invalid intent predicate');
+    const delegates = value.delegates;
+    if (delegates !== undefined &&
+        (!Array.isArray(delegates) ||
+            !delegates.length ||
+            delegates.some((id) => typeof id !== 'string' || !id.trim()) ||
+            new Set(delegates).size !== delegates.length))
+        throw new TypeError('Invalid intent delegates');
+    return Object.freeze({
+        description: value.description,
+        ...(value.when !== undefined ? { when: value.when } : {}),
+        ...(delegates ? { delegates: Object.freeze([...delegates]) } : {}),
+    });
+}
+/** Bind an optional object-form predicate to its owning Tool, without touching other forms. */
+export function bindIntent(value, owner) {
+    if (!value || typeof value !== 'object' || typeof value.when !== 'function')
+        return value;
+    return Object.freeze({ ...value, when: value.when.bind(owner) });
+}
+/** Check activation and reject asynchronous or nonboolean predicate results. */
+export function toolActive(condition, context) {
+    if (condition === undefined)
+        return true;
+    if (typeof condition === 'boolean')
+        return condition;
+    if (typeof condition !== 'function')
+        throw new TypeError('Invalid tool active condition');
+    return booleanResult(condition(context), 'Tool predicates must be synchronous', 'Tool predicates must return boolean');
+}
+/** Resolve the demand-facing description only when discovery is enabled. */
+export function intentDescription(metadata, fallback, context) {
+    if (metadata === undefined)
+        return undefined;
+    if (typeof metadata === 'string')
+        return metadata;
+    if (metadata === true)
+        return fallback;
+    if (typeof metadata === 'function')
+        return toolActive(metadata, context) ? fallback : undefined;
+    return toolActive(metadata.when, context) ? (metadata.description ?? fallback) : undefined;
+}