@jangts/agent-core 0.3.6 → 0.5.0

package/dist/esm/support/model/preview-rules.js

@@ -80,29 +80,29 @@ function previewSnapshot(preview) {
  * Capabilities without preview metadata are skipped even when their stage opts in. Default paths
  * are `text` and `bubbles[*]`, each kept only when the capability schema declares it.
  *
- * @param options Stage declarations and the capabilities they may reference.
+ * @param options Stage declarations and the tools they may reference.
  * @returns Frozen rules in stage order, each with deep-frozen paths and eligibility.
  * @throws {Error} When a capability or stage ID repeats, a stage references an unknown capability,
  *   a preview mode is unknown, or a preview path or eligibility field is absent from the schema.
  */
 export function createReplyPreviewRules(options) {
-    const capabilities = new Map();
-    for (const capability of options.capabilities) {
+    const tools = new Map();
+    for (const capability of options.tools) {
         const id = capability.id;
-        breakWhile(!id || capabilities.has(id), 'Duplicate preview capability declaration');
+        breakWhile(!id || tools.has(id), 'Duplicate preview capability declaration');
         const preview = previewSnapshot(capability.preview);
         // Validate and emit the same canonical snapshot, never reread App getters.
         const jsonSchema = preview ? structuredClone(capability.jsonSchema) : {};
-        capabilities.set(id, { id, preview, jsonSchema });
+        tools.set(id, { id, preview, jsonSchema });
     }
     const stages = new Set(), rules = [];
     for (const stage of options.stages) {
-        const { id: stageId, preview, capabilityIds } = stage;
+        const { id: stageId, preview, toolIds } = stage;
         breakWhile(!stageId || stages.has(stageId), 'Duplicate preview stage declaration');
         stages.add(stageId);
-        const ids = capabilityIds === undefined ? [] : stringList(capabilityIds, 'capability IDs');
-        breakWhile(new Set(ids).size !== ids.length || ids.some((id) => !capabilities.has(id)), 'Preview stage references an unknown capability');
-        breakWhile(preview !== undefined && !['text', 'capabilities'].includes(preview), 'Unknown preview stage mode');
+        const ids = toolIds === undefined ? [] : stringList(toolIds, 'capability IDs');
+        breakWhile(new Set(ids).size !== ids.length || ids.some((id) => !tools.has(id)), 'Preview stage references an unknown capability');
+        breakWhile(preview !== undefined && !['text', 'tools'].includes(preview), 'Unknown preview stage mode');
         if (!preview)
             continue;
         if (preview === 'text') {
@@ -111,7 +111,7 @@ export function createReplyPreviewRules(options) {
             continue;
         }
         for (const id of ids) {
-            const capability = capabilities.get(id);
+            const capability = tools.get(id);
             if (!capability.preview)
                 continue;
             const source = capability.preview === true ? {} : capability.preview;
@@ -127,7 +127,7 @@ export function createReplyPreviewRules(options) {
                 Object.freeze({ path: Object.freeze(when.path), values: Object.freeze(when.values) });
             rules.push(Object.freeze({
                 stageId,
-                capabilityId: wireName(id),
+                toolId: wireName(id),
                 paths: emittedPaths,
                 ...(emittedWhen ? { when: emittedWhen } : {}),
             }));

package/dist/esm/support/model/reply-preview.d.ts

@@ -2,11 +2,11 @@ import type { ModelOutputEvent } from '../../structs/model/runtime.js';
 /**
  * One projection rule: which stage/capability it matches and which prose fields may be shown.
  *
- * A rule without `capabilityId` may only match a registered plain-text stage.
+ * A rule without `toolId` may only match a registered plain-text stage.
  */
 export interface ReplyPreviewRule {
     /** Native function wire name. Omit only for a registered plain-text stage. */
-    capabilityId?: string;
+    toolId?: string;
     /** Restrict the rule to one stage; omitted matches any stage producing this capability. */
     stageId?: string;
     /** JSON paths to project, where `*` matches any array index; defaults to text/bubble paths. */

package/dist/esm/support/model/reply-preview.js

@@ -196,7 +196,7 @@ export function createReplyPreview(options) {
     if (!Number.isSafeInteger(maxChars) || maxChars < 1)
         throw new TypeError('Invalid reply preview budget');
     const rules = options.rules.map((rule) => Object.freeze({
-        capabilityId: rule.capabilityId,
+        toolId: rule.toolId,
         stageId: rule.stageId,
         paths: rule.paths === undefined ? undefined : structuredClone(rule.paths),
         when: rule.when === undefined ? undefined : structuredClone(rule.when),
@@ -258,7 +258,7 @@ export function createReplyPreview(options) {
             return;
         }
         if (typeof part === 'string') {
-            const rule = rules.find((rule) => !rule.capabilityId && rule.stageId === event.payload.stageId);
+            const rule = rules.find((rule) => !rule.toolId && rule.stageId === event.payload.stageId);
             if (!rule) {
                 if (part.trim()) {
                     disabled = true;
@@ -276,7 +276,7 @@ export function createReplyPreview(options) {
             return;
         }
         name += part.name ?? '';
-        const rule = rules.find((rule) => rule.capabilityId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
+        const rule = rules.find((rule) => rule.toolId === name && (!rule.stageId || rule.stageId === event.payload.stageId));
         if (!rule) {
             if (selected) {
                 disabled = true;

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

@@ -0,0 +1,61 @@
+import type { ModelToolSource, RegisteredModelTool } from '../../structs/capabilities/model.js';
+import type { ModelResponseCollector } from '../../structs/model/interactions.js';
+import type { ModelOptions } from '../../structs/model/messages.js';
+import type { ModelTransportDefinition } from '../../structs/model/runtime.js';
+import type { ModelSessionCall, ModelSessionResult } from '../../structs/model/session.js';
+/** One completed call with host-facing resolution; unknown tools and bad JSON stay non-fatal. */
+export interface ResolvedSessionCall extends ModelSessionCall {
+    /** Registered tool id, absent when the name is unknown to this stage. */
+    readonly toolId?: string;
+    /** Parsed arguments, absent when parsing failed or the tool is unknown. */
+    readonly input?: Record<string, unknown>;
+    /** Non-fatal problem the workflow should turn into a tool error message. */
+    readonly problem?: 'unknown-tool' | 'invalid-arguments';
+}
+/** Complete result of one session response after host-facing resolution. */
+export interface ResolvedSessionResult extends Omit<ModelSessionResult, 'calls'> {
+    readonly calls: readonly ResolvedSessionCall[];
+}
+/** Prepared session transport handed to the runner. */
+export interface PreparedSessionTransport {
+    readonly options: Pick<ModelOptions, 'functions' | 'json' | 'temperature' | 'toolChoice' | 'parallelToolCalls'>;
+    readonly schemaChars: number;
+    readonly instruction: string;
+    createResponse(): ModelResponseCollector<ResolvedSessionResult>;
+}
+/** Options a session transport may pass through to provider options. */
+export interface SessionFunctionOptions {
+    readonly temperature?: number;
+    readonly toolChoice?: 'auto' | 'required' | 'none';
+    readonly parallelToolCalls?: boolean | 'omit';
+}
+/** Registration for one session transport. */
+export interface SessionModelTransportRegistration {
+    /** Transport id used by call requests and diagnostics. */
+    readonly id: string;
+    /** Tools advertised to the model for this stage. */
+    readonly tools: ModelToolSource;
+    /** Sampling and tool-selection settings. */
+    readonly options?: SessionFunctionOptions;
+}
+/**
+ * Build the session policy for one stage.
+ *
+ * @param tools - Registered tools available in this stage; must be non-empty.
+ * @param options - Sampling and tool-selection settings.
+ * @returns A prepared transport whose collector returns text and every completed call.
+ * @throws TypeError When the tool list is empty or two ids collide on the wire name.
+ */
+export declare function prepareSessionFunctions(tools: readonly RegisteredModelTool[], options?: SessionFunctionOptions): PreparedSessionTransport;
+/**
+ * Create a session transport.
+ *
+ * @param registration - Transport id, tool source and optional settings.
+ * @returns A frozen transport definition whose result contains text and every completed call.
+ * @throws TypeError When the id is blank.
+ */
+export declare function createSessionModelTransport<const Id extends string>(registration: SessionModelTransportRegistration & {
+    readonly id: Id;
+}): ModelTransportDefinition<ResolvedSessionResult> & {
+    readonly id: Id;
+};

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

@@ -0,0 +1,148 @@
+/**
+ * Session transport policy: one response may contain prose and several tool calls.
+ *
+ * Core owns the raw `ModelSessionResult`; this Support module adds the host-facing
+ * resolution fields (`toolId`, parsed `input`, non-fatal `problem`) and the transport
+ * that advertises the stage's tools. Keeping the resolution policy here prevents Core
+ * from depending on tool catalogs or business error categories.
+ *
+ * Exports: `ResolvedSessionCall`, `ResolvedSessionResult`, `PreparedSessionTransport`,
+ * `SessionFunctionOptions`, `SessionModelTransportRegistration`, `prepareSessionFunctions`
+ * and `createSessionModelTransport`.
+ */
+import { wireName } from '../../model/interactions/arguments.js';
+import { createToolCallCollector } from '../../model/interactions/calls.js';
+import { snapshotModelOptions } from '../../model/options.js';
+import { modelProtocolError } from '../../utils/model-protocol.js';
+/**
+ * Parse one call's raw arguments without failing the whole response.
+ *
+ * @param raw - Raw JSON text; an empty string means an empty argument object.
+ * @returns The parsed object, or undefined when the text is not a JSON object.
+ */
+function parseArguments(raw) {
+    try {
+        const value = JSON.parse(raw === '' ? '{}' : raw);
+        return value && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build the session policy for one stage.
+ *
+ * @param tools - Registered tools available in this stage; must be non-empty.
+ * @param options - Sampling and tool-selection settings.
+ * @returns A prepared transport whose collector returns text and every completed call.
+ * @throws TypeError When the tool list is empty or two ids collide on the wire name.
+ */
+export function prepareSessionFunctions(tools, options = {}) {
+    if (!tools.length)
+        throw new TypeError('Session transport requires registered tools');
+    const names = new Map(tools.map((tool) => [wireName(tool.id), tool.id]));
+    if (names.size !== tools.length)
+        throw new TypeError('Model wire name collision');
+    const functions = tools.map((tool) => ({
+        name: wireName(tool.id),
+        description: tool.description,
+        parameters: tool.inputSchema.jsonSchema,
+        strict: false,
+    }));
+    const instruction = 'You may answer directly or call one or more registered tools. Prose and calls may appear together. A call is a proposal, not proof of execution.';
+    return {
+        options: {
+            json: false,
+            functions,
+            toolChoice: options.toolChoice ?? 'auto',
+            ...(options.parallelToolCalls === undefined
+                ? {}
+                : { parallelToolCalls: options.parallelToolCalls }),
+            ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+        },
+        schemaChars: JSON.stringify(functions).length + instruction.length,
+        instruction,
+        createResponse() {
+            const collector = createToolCallCollector();
+            let text = '';
+            return {
+                get outputChars() {
+                    return (text.length +
+                        collector.calls.reduce((sum, call) => sum + call.id.length + call.name.length + call.arguments.length, 0));
+                },
+                get calls() {
+                    try {
+                        return collector.complete().map((call) => ({
+                            id: call.id,
+                            name: call.name,
+                            argumentChars: call.arguments.length,
+                            toolId: names.get(call.name),
+                        }));
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                push(part) {
+                    if (typeof part === 'string') {
+                        text += part;
+                        return;
+                    }
+                    collector.push(part);
+                },
+                finish() {
+                    const completed = collector.complete();
+                    if (text.trim() === '' && completed.length === 0)
+                        modelProtocolError('Model response is empty', 'MODEL_INCOMPLETE');
+                    const calls = completed.map((call) => {
+                        const toolId = names.get(call.name);
+                        const input = parseArguments(call.arguments);
+                        return {
+                            index: call.index,
+                            id: call.id,
+                            name: call.name,
+                            arguments: call.arguments,
+                            argumentChars: call.arguments.length,
+                            ...(toolId === undefined ? {} : { toolId }),
+                            ...(input === undefined ? {} : { input }),
+                            ...(toolId === undefined
+                                ? { problem: 'unknown-tool' }
+                                : input === undefined
+                                    ? { problem: 'invalid-arguments' }
+                                    : {}),
+                        };
+                    });
+                    return { text, calls };
+                },
+            };
+        },
+    };
+}
+/**
+ * Create a session transport.
+ *
+ * @param registration - Transport id, tool source and optional settings.
+ * @returns A frozen transport definition whose result contains text and every completed call.
+ * @throws TypeError When the id is blank.
+ */
+export function createSessionModelTransport(registration) {
+    const id = registration.id;
+    if (typeof id !== 'string' || !id.trim())
+        throw new TypeError('Session transport requires an ID');
+    const source = registration.tools;
+    const options = snapshotModelOptions(registration.options ?? {});
+    return Object.freeze({
+        id,
+        prepare() {
+            return prepareSessionFunctions([...source.values()], {
+                ...(options.temperature === undefined ? {} : { temperature: options.temperature }),
+                ...(options.toolChoice === undefined ? {} : { toolChoice: options.toolChoice }),
+                ...(options.parallelToolCalls === undefined
+                    ? {}
+                    : { parallelToolCalls: options.parallelToolCalls }),
+            });
+        },
+    });
+}

package/dist/esm/support/model/stage-transport.d.ts

@@ -4,7 +4,7 @@ import type { ModelStageTransportRegistration } from '../../structs/support/mode
  *
  * @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.
  */

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

@@ -1,5 +1,5 @@
 /**
- * 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
@@ -8,7 +8,7 @@
  * Main export: `createStageModelTransport`.
  */
 import { synchronous } from '../../utils/synchronous.js';
-import { ModelCapabilityRegistry } from '../../capabilities/model.js';
+import { ModelToolRegistry } from '../../capabilities/model.js';
 import { breakWhile } from '../../utils/rules.js';
 import { createModelTransport } from './transports.js';
 /**
@@ -16,14 +16,14 @@ import { createModelTransport } from './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.
  */
 export function createStageModelTransport(registration) {
     const stages = new Map();
     for (const stage of registration.stages) {
-        const ids = stage.capabilityIds;
+        const ids = stage.toolIds;
         breakWhile(!stage.id?.trim() ||
             stages.has(stage.id) ||
             !Array.isArray(ids) ||
@@ -32,15 +32,15 @@ export function createStageModelTransport(registration) {
         stages.set(stage.id, Object.freeze([...ids]));
     }
     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);
         breakWhile(!ids, `Unregistered model stage: ${id} -> ${stage}`);
-        const catalog = new ModelCapabilityRegistry(capabilities.values());
+        const catalog = new ModelToolRegistry(tools.values());
         for (const id of ids)
             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) {
@@ -58,7 +58,7 @@ export function createStageModelTransport(registration) {
         adapter,
         options,
         requireStrictArguments,
-        capabilities(stage) {
+        tools(stage) {
             breakWhile(!stages.has(stage), `Unregistered model stage: ${id} -> ${stage}`);
             return fixed
                 ? fixed.get(stage)

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

@@ -1,6 +1,7 @@
 import type { ModelOptions } from '../../structs/model/messages.js';
 import type { ModelTransportDefinition } from '../../structs/model/runtime.js';
 export { createModelTransport } from '../../model/selection-transport.js';
+export { createSessionModelTransport, prepareSessionFunctions, type PreparedSessionTransport, type ResolvedSessionCall, type ResolvedSessionResult, type SessionFunctionOptions, type SessionModelTransportRegistration, } from './session.js';
 /**
  * Create a plain-text transport that trims the assembled response.
  *
@@ -10,6 +11,7 @@ export { createModelTransport } from '../../model/selection-transport.js';
 export declare function createTextTransport<const Id extends string>(definition: {
     readonly id: Id;
     readonly options?: Pick<ModelOptions, 'temperature'>;
+    readonly trim?: boolean;
 }): ModelTransportDefinition<string> & {
     readonly id: Id;
 };

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

@@ -12,6 +12,7 @@ import { snapshotModelOptions } from '../../model/options.js';
 import { modelProtocolError } from '../../utils/model-protocol.js';
 import { createPlainTextTransport } from '../../model/transports.js';
 export { createModelTransport } from '../../model/selection-transport.js';
+export { createSessionModelTransport, prepareSessionFunctions, } from './session.js';
 /**
  * Create a plain-text transport that trims the assembled response.
  *
@@ -19,7 +20,7 @@ export { createModelTransport } from '../../model/selection-transport.js';
  * @returns A frozen Core transport definition typed as string output.
  */
 export function createTextTransport(definition) {
-    return createPlainTextTransport(definition.id, definition.options);
+    return createPlainTextTransport(definition.id, definition.options, definition.trim);
 }
 /**
  * Create a typed JSON transport without a capability-selection envelope.

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

@@ -1,3 +1,5 @@
+import type { OperationContext } from '../structs/common.js';
+import type { ExecutableTool } from '../structs/capabilities/tools.js';
 import type { ToolDefinition, ToolCatalog, CompiledTool } from '../structs/support/tools.js';
 /**
  * Validate one tool declaration and freeze a detached copy of it.
@@ -13,16 +15,22 @@ import type { ToolDefinition, ToolCatalog, CompiledTool } from '../structs/suppo
  */
 export declare function defineTool<Input, Output, App, const Id extends string = string>(definition: ToolDefinition<Input, Output, App> & {
     readonly id: Id;
-}): ToolDefinition<Input, Output, App, Id>;
+}): ExecutableTool<Input, Output, App, Id>;
 /**
- * Compile tool declarations into a frozen catalog with model capabilities and runtime binding.
+ * Compile tool declarations into a frozen catalog with model tools 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`.
+ * @returns A frozen catalog with `tools`, `select` and `bind`.
  * @throws {TypeError} When a tool declaration is invalid or a tool ID is duplicated.
  */
+type DefinitionApp<Definition> = Definition extends {
+    authorize(input: any, context: OperationContext<infer App>): unknown;
+} ? App : unknown;
+/** Infer the host context from existing executable definitions, without widening it to unknown. */
+export declare function defineToolCatalog<const Definitions extends readonly ToolDefinition<any, any, any>[]>(definitions: Definitions): ToolCatalog<DefinitionApp<Definitions[number]>, CompiledTool<DefinitionApp<Definitions[number]>, Definitions[number]>>;
+/** Explicit host typing remains available for contextually typed declaration lists. */
 export declare function defineToolCatalog<App, const Definitions extends readonly ToolDefinition<any, any, App>[] = readonly ToolDefinition<any, any, App>[]>(definitions: Definitions): ToolCatalog<App, CompiledTool<App, Definitions[number]>>;
 export type * from '../structs/support/tools.js';

package/dist/esm/support/tools.js

@@ -2,17 +2,18 @@
  * 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.
  *
  * Main exports: `defineTool` and `defineToolCatalog`.
  */
-import { ModelCapabilityRegistry } from '../capabilities/model.js';
+import { ModelToolRegistry } from '../capabilities/model.js';
 import { createToolRegistry } from './tool-runtime.js';
 import { defineSchema } from './schema.js';
 import { readonlyCatalog } from '../utils/catalog.js';
 import { maybeAssertion } from '../utils/synchronous.js';
+import { snapshotIntent, toolActive, intentDescription, bindIntent, } from '../capabilities/tool-conditions.js';
 /**
  * Validate one tool declaration and freeze a detached copy of it.
  *
@@ -35,11 +36,24 @@ export function defineTool(definition) {
         throw new TypeError('Missing tool handler');
     const inputSchema = 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 = bindIntent(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 maybeAssertion(authorize(input, context), 'Authorization must return void; rejection must throw');
         },
@@ -48,22 +62,14 @@ export 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.
- */
 export function defineToolCatalog(definitions) {
     const entries = definitions.map((definition) => defineTool(definition));
     const view = readonlyCatalog(entries, (id) => new TypeError(`Unknown tool: ${id}`));
-    const capabilities = new ModelCapabilityRegistry(entries.map((tool) => ({
+    const tools = new ModelToolRegistry(entries.map((tool) => ({
         id: tool.id,
         description: tool.description,
+        active: tool.active,
+        asIntent: tool.asIntent,
         inputSchema: defineSchema({
             jsonSchema: tool.inputSchema.jsonSchema,
             parse: (input) => input,
@@ -72,7 +78,7 @@ export function defineToolCatalog(definitions) {
     }))).seal();
     return Object.freeze({
         ...view,
-        capabilities,
+        tools,
         /**
          * Narrow the catalog to the given tool IDs, preserving their declaration order.
          *
@@ -80,9 +86,28 @@ export 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 || 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 (!toolActive(tool.active, context))
+                    return [];
+                const description = intentDescription(tool.asIntent, tool.description, context);
+                return description === undefined ? [] : [{ ...tool, description }];
+            }));
         },
         /**
          * Bind the catalog to one application runtime request.
@@ -99,7 +124,7 @@ export function defineToolCatalog(definitions) {
                 errors: request.errors,
             });
             return Object.freeze({
-                capabilities,
+                tools,
                 get events() {
                     return registry.events;
                 },

package/dist/esm/utils/catalog.d.ts

@@ -1,7 +1,7 @@
 /**
  * Immutable id-keyed catalog snapshot.
  *
- * Modules that own registrable definitions (tools, capabilities, prompts) publish the
+ * Modules that own registrable definitions (tools, tools, prompts) publish the
  * snapshot produced here instead of exposing their mutable `Map`, so later mutations
  * by the owner cannot be observed and no consumer can mutate the registry.
  *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jangts/agent-core",
-  "version": "0.3.6",
+  "version": "0.5.0",
   "type": "commonjs",
   "license": "Apache-2.0",
   "description": "Platform-independent agent runtime and configurable modules for evidence, delivery, policies and interactions",
@@ -162,10 +162,10 @@
       "import": "./dist/esm/kits/interaction/index.js",
       "require": "./dist/cjs/kits/interaction/index.js"
     },
-    "./kits/intents": {
-      "types": "./dist/esm/kits/intents/index.d.ts",
-      "import": "./dist/esm/kits/intents/index.js",
-      "require": "./dist/cjs/kits/intents/index.js"
+    "./kits/domains": {
+      "types": "./dist/esm/kits/domains/index.d.ts",
+      "import": "./dist/esm/kits/domains/index.js",
+      "require": "./dist/cjs/kits/domains/index.js"
     },
     "./kits/tools": {
       "types": "./dist/esm/kits/tools.d.ts",
@@ -197,6 +197,11 @@
       "import": "./dist/esm/kits/search.js",
       "require": "./dist/cjs/kits/search.js"
     },
+    "./kits/text-blocks": {
+      "types": "./dist/esm/kits/text-blocks.d.ts",
+      "import": "./dist/esm/kits/text-blocks.js",
+      "require": "./dist/cjs/kits/text-blocks.js"
+    },
     "./kits/inference": {
       "types": "./dist/esm/kits/inference.d.ts",
       "import": "./dist/esm/kits/inference.js",
@@ -250,15 +255,24 @@
   },
   "scripts": {
     "build": "node scripts/clean.mjs && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finalize.mjs",
+    "build:dev": "tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node scripts/finalize.mjs",
     "test": "node --test test/*.test.mjs",
     "docs:api": "node scripts/api-reference.mjs"
   },
   "dependencies": {
     "@jangts/streaming": "^0.1.2",
-    "@jangts/mock-gpt": "0.2.2",
     "minisearch": "^7.2.0"
   },
+  "peerDependencies": {
+    "@jangts/mock-gpt": "0.2.2"
+  },
+  "peerDependenciesMeta": {
+    "@jangts/mock-gpt": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@jangts/mock-gpt": "0.2.2",
     "typescript": "~6.0.2",
     "esbuild": "0.28.2"
   },