ToolModelView

SUPPORT · interface · Type contract

Model capability view of a tool catalog, retaining the host context type.

Import

TypeScript

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

JavaScript

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

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

Definition

interface ToolModelView<App>

Extends or implements: ModelToolRegistry.

Type parameters

Type parameter	Constraint	Default type
App	—	unknown

Field structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

Member index

Member	Purpose
values	See the overload below for full inputs and outputs.
resolve	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	Narrows the capability set to ids; throws for unregistered ids.
withIntent	Discovery retains this projection's ToolProposal result contract.
register	Register one capability.
ids	Registered ids in declaration order.
entries	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	Register several tools.
require	See the overload below for full inputs and outputs.
has	See the overload below for full inputs and outputs.
get	See the overload below for full inputs and outputs.
seal	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

Member details

values

ToolModelView.values(): IterableIterator<RegisteredModelTool<ToolProposal>>

No call parameters.

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

resolve

Resolves a model selection into a proposal; throws for unknown or invalid selections.

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

Resolves a model selection into a proposal; throws for unknown or invalid selections.

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: ToolProposal.

Return value structure

Field	Type	Required	Description
toolId	string	Required	Read-only. See the type definition and usage context.
input	unknown	Required	Read-only. See the type definition and usage context.

select

Narrows the capability set to ids; throws for unregistered ids.

ToolModelView.select(ids: readonly string[], context?: App): ToolModelView<App>

Narrows the capability set to ids; throws for unregistered ids.

Parameter	Type	Passing	Description
ids	readonly string[]	Required	—
context	App | undefined	Optional	—

Returns: ToolModelView<App>.

Return value structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

withIntent

Discovery retains this projection's ToolProposal result contract.

ToolModelView.withIntent(context: App): ToolModelView<App>

Discovery retains this projection's ToolProposal result contract.

Parameter	Type	Passing	Description
context	App	Required	—

Returns: ToolModelView<App>.

Return value structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

register

Register one capability.

ToolModelView.register<Result>(capability: ModelToolRegistration<Result>): ToolModelView<App>

Register one capability.

Type parameter	Constraint	Default type
Result	—	—

Parameter	Type	Passing	Description
capability	ModelToolRegistration<Result>	Required	—

Fields of capability

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<any>	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: any, context: Readonly<{ stageId: string; }>) => Result) | undefined	Optional	Read-only. See the type definition and usage context.

Returns: ToolModelView<App>.

Return value structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

ids

Registered ids in declaration order.

ToolModelView.ids(): readonly string[]

Registered ids in declaration order.

No call parameters.

Returns: readonly string[].

entries

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

ToolModelView.entries(): IterableIterator<readonly [string, RegisteredModelTool]>

Live iterator over [id, definition] pairs; it reflects only entries added before sealing.

No call parameters.

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

registerAll

Register several tools.

ToolModelView.registerAll(definitions: Iterable<ModelToolRegistration>): ToolModelView<App>

Register several tools.

Parameter	Type	Passing	Description
definitions	Iterable<ModelToolRegistration>	Required	—

Returns: ToolModelView<App>.

Return value structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

require

ToolModelView.require(id: string): RegisteredModelTool

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<ModelTool<unknown, unknown, 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; }>) => unknown	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.

has

ToolModelView.has(id: string): boolean

Parameter	Type	Passing	Description
id	string	Required	—

Returns: boolean.

get

ToolModelView.get(id: string): RegisteredModelTool | undefined

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<ModelTool<unknown, unknown, 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; }>) => unknown	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.

seal

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

ToolModelView.seal(): ToolModelView<App>

Close the registry to further registration.

Sealing is idempotent and does not affect existing entries.

No call parameters.

Returns: ToolModelView<App>.

Return value structure

Field	Type	Required	Description
values	() => IterableIterator<RegisteredModelTool<ToolProposal>>	Required	See the type definition and usage context.
resolve	(selection: ModelSelection, context: Readonly<{ stageId: string; }>) => ToolProposal	Required	Resolves a model selection into a proposal; throws for unknown or invalid selections.
select	(ids: readonly string[], context?: App) => ToolModelView<App>	Required	Narrows the capability set to ids; throws for unregistered ids.
withIntent	(context: App) => ToolModelView<App>	Required	Discovery retains this projection's ToolProposal result contract.
register	<Result>(capability: ModelToolRegistration<Result>) => ToolModelView<App>	Required	Register one capability.
definitions	readonly Readonly<Readonly<ModelTool<unknown, unknown, any>>>[]	Required	Read-only. Frozen snapshot of the registered definitions, in insertion order.
ids	() => readonly string[]	Required	Registered ids in declaration order.
entries	() => IterableIterator<readonly [string, RegisteredModelTool]>	Required	Live iterator over [id, definition] pairs; it reflects only entries added before sealing.
registerAll	(definitions: Iterable<ModelToolRegistration>) => ToolModelView<App>	Required	Register several tools.
require	(id: string) => RegisteredModelTool	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => RegisteredModelTool | undefined	Required	See the type definition and usage context.
seal	() => ToolModelView<App>	Required	Close the registry to further registration. Sealing is idempotent and does not affect existing entries.

Examples

• Tool best practice: one definition generates the model tool and execution runtime: Register Schema, authorization, execution, and output validation once, and bind the App per request instead of maintaining two tool lists.

Define and use a read-only tool

Beginner · 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 catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
  authorize() {},
  execute() { return '服务运行正常'; },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

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 catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取服务状态', inputSchema,
        authorize() { },
        execute() { return '服务运行正常'; },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: undefined });
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);
console.log(catalog.tools.ids());

Keep the list and add this request's permissions and service dependencies

Configuration · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
import type { OperationContext } from '@jangts/agent-core/types';
type App = { allowed: boolean; readStatus(): Promise<string> };
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 catalog = Support.defineToolCatalog<App>([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
  authorize(_input: {}, { app }: OperationContext<App>) { if (!app.allowed) throw new Error('当前请求没有读取权限'); },
  execute(_input: {}, { app }: OperationContext<App>) { return app.readStatus(); },
  parseOutput(value: unknown) { if (typeof value !== 'string') throw new TypeError('需要字符串'); return value; },
}]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
  execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

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 catalog = Support.defineToolCatalog([{ id: 'get_status', kind: 'read', description: '读取状态', inputSchema,
        authorize(_input, { app }) { if (!app.allowed)
            throw new Error('当前请求没有读取权限'); },
        execute(_input, { app }) { return app.readStatus(); },
        parseOutput(value) { if (typeof value !== 'string')
            throw new TypeError('需要字符串'); return value; },
    }]);
const tools = catalog.bind({ app: { allowed: true, readStatus: async () => '服务运行正常' },
    execution: { signal: AbortSignal.timeout(10000) },
});
console.log((await tools.invoke({ toolId: 'get_status', input: {} })).value);

Related policy source

• Authorization and model tool projection come from the same definition

Related definitions

• ModelSelection
• ModelTool
• ModelToolRegistration
• ModelToolRegistry
• RegisteredModelTool
• ToolProposal