ModelToolCatalog

CORE · type · Type contract

A compiled entity catalog also supports the minimal stage source contract.

Import

TypeScript

import type { ModelToolCatalog } from '@jangts/agent-core';

JavaScript

/** @typedef {import('@jangts/agent-core').ModelToolCatalog} ModelToolCatalog */

Other public entry points:@jangts/agent-core, @jangts/agent-core/types, @jangts/agent-core/structs.

Definition

Type: ModelToolCatalog<Output>

Type expression

type ModelToolCatalog<Output = unknown> = ReadonlyCatalog<RegisteredModelTool<Output>> &
  ModelToolSource<Output> & {
    /** Explicit selection, optionally filtered against a host context. */
    select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>;
    /** Demand-facing active tools; no workflow node or invocation is implied. */
    withIntent(context: unknown): ModelToolCatalog<Output>;
  };

Type parameters

Type parameter	Constraint	Default type
Output	—	unknown

Field structure

Field	Type	Required	Description
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	Required	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	Required	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	Required	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	Required	Demand-facing active tools; no workflow node or invocation is implied.

Member index

Member	Purpose
ids	Ids in the same order as definitions.
values	See the overload below for full inputs and outputs.
entries	See the overload below for full inputs and outputs.
has	See the overload below for full inputs and outputs.
get	Returns the definition or undefined; the caller decides whether absence is an error.
require	Returns the definition or throws; use when the id is a required reference.
resolve	Resolves one selection; throws when the capability is absent from this source.
select	Explicit selection, optionally filtered against a host context.
withIntent	Demand-facing active tools; no workflow node or invocation is implied.

Member details

ids

Ids in the same order as definitions.

ModelToolCatalog.ids(): readonly string[]

Ids in the same order as definitions.

No call parameters.

Returns: readonly string[].

values

ModelToolCatalog.values(): IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>

No call parameters.

Returns: IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>.

entries

ModelToolCatalog.entries(): IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>

No call parameters.

Returns: IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>.

has

ModelToolCatalog.has(id: string): boolean

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

get

Returns the definition or undefined; the caller decides whether absence is an error.

ModelToolCatalog.get(id: string): Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined

Returns the definition or undefined; the caller decides whether absence is an error.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Readonly<ModelTool<unknown, Output, any>>> \| undefined.

Optional shapes of Return value: choose one shape; required fields for each branch are listed separately.

Branch 1

undefined

Branch 2

Field	Type	Required	Description
id	string	Required	Read-only. Unique id within its registry; never blank.
description	string	Required	Read-only. Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	Required	Read-only. Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
resolve	(input: unknown, context: Readonly<{ stageId: string; }>) => Output	Required	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.

require

Returns the definition or throws; use when the id is a required reference.

ModelToolCatalog.require(id: string): Readonly<Readonly<ModelTool<unknown, Output, any>>>

Returns the definition or throws; use when the id is a required reference.

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<Readonly<ModelTool<unknown, Output, any>>>.

Return value structure

Field	Type	Required	Description
id	string	Required	Read-only. Unique id within its registry; never blank.
description	string	Required	Read-only. Model-visible description explaining when the capability applies.
inputSchema	SchemaAdapter<unknown>	Required	Read-only. Schema describing the arguments; must be an object schema.
active	ToolCondition<any> | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<any> | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
resolve	(input: unknown, context: Readonly<{ stageId: string; }>) => Output	Required	Converts validated arguments into the value handed back to the caller. Runs inside the model call, so it must return synchronously; throwing rejects the selection.

resolve

Resolves one selection; throws when the capability is absent from this source.

ModelToolCatalog.resolve(selection: ModelSelection, context: Readonly<{ stageId: string; }>): Output

Resolves one selection; throws when the capability is absent from this source.

Parameter	Type	Passing	Description
selection	ModelSelection	Required	—
context	Readonly<{ stageId: string; }>	Required	—

Fields of selection

Field	Type	Required	Description
input	Record<string, unknown>	Required	Read-only. Arguments exactly as produced by the model, before schema parsing.
call	{ id: string; name: string; argumentChars: number; } | undefined	Optional	Read-only. Native function call that carried the selection, when the provider used one.
toolId	string	Required	Read-only. Capability the selection resolved to.

Fields of context

Field	Type	Required	Description
stageId	string	Required	See the type definition and usage context.

Returns: Output.

Awaited value: Awaited<Output>.

select

Explicit selection, optionally filtered against a host context.

ModelToolCatalog.select(ids: readonly string[], context?: unknown): ModelToolCatalog<Output>

Explicit selection, optionally filtered against a host context.

Parameter	Type	Passing	Description
ids	readonly string[]	Required	—
context	unknown	Optional	—

Returns: ModelToolCatalog<Output>.

Return value structure

Field	Type	Required	Description
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	Required	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	Required	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	Required	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	Required	Demand-facing active tools; no workflow node or invocation is implied.

withIntent

Demand-facing active tools; no workflow node or invocation is implied.

ModelToolCatalog.withIntent(context: unknown): ModelToolCatalog<Output>

Demand-facing active tools; no workflow node or invocation is implied.

Parameter	Type	Passing	Description
context	unknown	Required	—

Returns: ModelToolCatalog<Output>.

Return value structure

Field	Type	Required	Description
definitions	readonly Readonly<Readonly<ModelTool<unknown, Output, any>>>[]	Required	Read-only. Definitions in registration order; each entry is frozen by the implementation.
ids	() => readonly string[]	Required	Ids in the same order as definitions.
values	(() => IterableIterator<Readonly<Readonly<ModelTool<unknown, Output, any>>>>) & (() => IterableIterator<Readonly<ModelTool<unknown, Output, any>>>)	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<Readonly<ModelTool<unknown, Output, any>>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<Readonly<ModelTool<unknown, Output, any>>>	Required	Returns the definition or throws; use when the id is a required reference.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => Output	Required	Resolves one selection; throws when the capability is absent from this source.
select	(ids: readonly string[], context?: unknown) => ModelToolCatalog<Output>	Required	Explicit selection, optionally filtered against a host context.
withIntent	(context: unknown) => ModelToolCatalog<Output>	Required	Demand-facing active tools; no workflow node or invocation is implied.

Examples

• Model transport and stage projection: Generate a sealed catalog and stage projections from tool definitions; native functions and JSON adapters share the same tool contract.
• Support: the aggregate entry for recommended usage: Support aggregates recommended construction, policies, and same-source configuration generation; Core execution does not depend on this namespace.

Create a named text transport

Beginner · Node.js

TypeScript

import { ModelRunner, Support } from '@jangts/agent-core';
const text = Support.createTextTransport({ id: 'brief', options: { temperature: 0.2 } });
const runner = new ModelRunner({ provider: { async *stream() { yield '服务正常'; } }, transports: [text] });
console.log((await runner.invoke({ input: '简答服务状态', transport: text })).value);

JavaScript

import { ModelRunner, Support } from '@jangts/agent-core';
const text = Support.createTextTransport({ id: 'brief', options: { temperature: 0.2 } });
const runner = new ModelRunner({ provider: { async *stream() { yield '服务正常'; } }, transports: [text] });
console.log((await runner.invoke({ input: '简答服务状态', transport: text })).value);

Generate transports for two stages from same-source tools

Configuration · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
  jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
  parse(value: unknown) {
    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length) throw new TypeError('需要空对象');
    return {};
  },
});
const tools = Support.defineModelTools([
  { id: 'greet', description: '问候', inputSchema, resolve: () => 'greet' },
  { id: 'status', description: '状态查询', inputSchema, resolve: () => 'status' },
]);
const transport = Support.createStageModelTransport({ id: 'intent', tools,
  stages: [{ id: 'recognize', toolIds: ['greet', 'status'] }, { id: 'status-only', toolIds: ['status'] }],
});
console.log(transport.prepare('status-only').schemaChars);

JavaScript

import { Support } from '@jangts/agent-core';
const inputSchema = Support.defineSchema({
    jsonSchema: { type: 'object', properties: {}, additionalProperties: false },
    parse(value) {
        if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).length)
            throw new TypeError('需要空对象');
        return {};
    },
});
const tools = Support.defineModelTools([
    { id: 'greet', description: '问候', inputSchema, resolve: () => 'greet' },
    { id: 'status', description: '状态查询', inputSchema, resolve: () => 'status' },
]);
const transport = Support.createStageModelTransport({ id: 'intent', tools,
    stages: [{ id: 'recognize', toolIds: ['greet', 'status'] }, { id: 'status-only', toolIds: ['status'] }],
});
console.log(transport.prepare('status-only').schemaChars);

Related policy source

• Stage list validation and dynamic source snapshots
• Explicit model interaction adapter catalog
• Session transport for prose and multiple tool calls

Related definitions

• ModelSelection
• ModelTool
• ModelToolSource
• ReadonlyCatalog
• RegisteredModelTool