ToolCatalog

SUPPORT · interface · Type contract

Frozen tool catalog with model tools and per-request binding.

Import

TypeScript

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

JavaScript

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

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

Definition

interface ToolCatalog<App, Tool>

Extends or implements: ReadonlyCatalog<ToolCatalogEntry<App, Tool>>.

Type parameters

Type parameter	Constraint	Default type
App	—	—
Tool	ToolDefinition<unknown, unknown, App>	ToolDefinition<unknown, unknown, App>

Field structure

Field	Type	Required	Description
tools	ToolModelView<App>	Required	Read-only. See the type definition and usage context.
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	Required	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, Tool>	Required	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<Tool, App>	Required	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, Tool>>[]	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<ToolCatalogEntry<App, Tool>>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<ToolCatalogEntry<App, Tool>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, Tool>>	Required	Returns the definition or throws; use when the id is a required reference.

Member index

Member	Purpose
select	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	Active tools advertising demand-discovery use; descriptions are view-local.
bind	Binds the catalog to one App request and returns an invocable runtime.
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.

Member details

select

Narrows the catalog while preserving declaration order; throws for unknown ids.

ToolCatalog.select<const Ids extends readonly string[]>(ids: Ids, context?: App): ToolCatalog<App, SelectedTools<Tool, Ids[number]>>

Narrows the catalog while preserving declaration order; throws for unknown ids.

Type parameter	Constraint	Default type
Ids	readonly string[]	—

Parameter	Type	Passing	Description
ids	Ids	Required	—
context	App | undefined	Optional	—

Returns: ToolCatalog<App, SelectedTools<Tool, Ids[number]>>.

Return value structure

Field	Type	Required	Description
tools	ToolModelView<App>	Required	Read-only. See the type definition and usage context.
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<SelectedTools<Tool, Ids[number]>, Ids[number]>>	Required	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	Required	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<SelectedTools<Tool, Ids[number]>, App>	Required	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>[]	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<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, SelectedTools<Tool, Ids[number]>>>	Required	Returns the definition or throws; use when the id is a required reference.

withIntent

Active tools advertising demand-discovery use; descriptions are view-local.

ToolCatalog.withIntent(context: App): ToolCatalog<App, Tool>

Active tools advertising demand-discovery use; descriptions are view-local.

Parameter	Type	Passing	Description
context	App	Required	—

Returns: ToolCatalog<App, Tool>.

Return value structure

Field	Type	Required	Description
tools	ToolModelView<App>	Required	Read-only. See the type definition and usage context.
select	<const Ids extends readonly string[]>(ids: Ids, context?: App) => ToolCatalog<App, SelectedTools<Tool, Ids[number]>>	Required	Narrows the catalog while preserving declaration order; throws for unknown ids.
withIntent	(context: App) => ToolCatalog<App, Tool>	Required	Active tools advertising demand-discovery use; descriptions are view-local.
bind	(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }) => ToolRuntime<Tool, App>	Required	Binds the catalog to one App request and returns an invocable runtime.
definitions	readonly Readonly<ToolCatalogEntry<App, Tool>>[]	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<ToolCatalogEntry<App, Tool>>>	Required	See the type definition and usage context.
entries	() => IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>	Required	See the type definition and usage context.
has	(id: string) => boolean	Required	See the type definition and usage context.
get	(id: string) => Readonly<ToolCatalogEntry<App, Tool>> | undefined	Required	Returns the definition or undefined; the caller decides whether absence is an error.
require	(id: string) => Readonly<ToolCatalogEntry<App, Tool>>	Required	Returns the definition or throws; use when the id is a required reference.

bind

Binds the catalog to one App request and returns an invocable runtime.

ToolCatalog.bind(request: { app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }): ToolRuntime<Tool, App>

Binds the catalog to one App request and returns an invocable runtime.

Parameter	Type	Passing	Description
request	{ app: App; execution?: ExecutionOptions; errors?: Pick<ToolRegistryPorts, "unavailable" | "errorCode">; }	Required	—

Fields of request

Field	Type	Required	Description
app	App	Required	See the type definition and usage context.
execution	ExecutionOptions | undefined	Optional	See the type definition and usage context.
errors	Pick<ToolRegistryPorts, "unavailable" | "errorCode"> | undefined	Optional	See the type definition and usage context.

Returns: ToolRuntime<Tool, App>.

Return value structure

Field	Type	Required	Description
tools	ToolModelView<App>	Required	Read-only. The catalog's model tools, shared with the catalog instance.
events	readonly ToolExecutionEvent<string>[]	Required	Read-only. Execution events recorded by this runtime so far, in occurrence order.
invokeSync	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): ToolResult<ToolOutput<Tool, Id>>; (request: ToolInvocationRequest): ToolResult<unknown>; }	Required	Synchronous invocation; rejects tools declared as asynchronous.
invoke	{ <const Id extends Tool["id"]>(request: ToolInvocationRequest<Id>): Promise<ToolResult<ToolOutput<Tool, Id>>>; (request: ToolInvocationRequest): Promise<ToolResult<unknown>>; }	Required	Asynchronous invocation; still bounded by the bound execution signal and errors.

ids

Ids in the same order as definitions.

ToolCatalog.ids(): readonly string[]

Ids in the same order as definitions.

No call parameters.

Returns: readonly string[].

values

ToolCatalog.values(): IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>

No call parameters.

Returns: IterableIterator<Readonly<ToolCatalogEntry<App, Tool>>>.

entries

ToolCatalog.entries(): IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>

No call parameters.

Returns: IterableIterator<readonly [string, Readonly<ToolCatalogEntry<App, Tool>>]>.

has

ToolCatalog.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.

ToolCatalog.get(id: string): Readonly<ToolCatalogEntry<App, Tool>> | undefined

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

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<ToolCatalogEntry<App, Tool>> \| 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	ToolCatalogEntry<App, Tool>["id"]	Required	Read-only. Stable id; also the name the model calls.
description	ToolCatalogEntry<App, Tool>["description"]	Required	Read-only. Model-visible explanation of when to call the tool.
resolve	ToolCatalogEntry<App, Tool>["resolve"] | undefined	Optional	Read-only. See the type definition and usage context.
inputSchema	ToolCatalogEntry<App, Tool>["inputSchema"]	Required	Read-only. Schema applied to raw model arguments before authorize and execute.
active	ToolCatalogEntry<App, Tool>["active"] | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	ToolCatalogEntry<App, Tool>["asIntent"] | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
kind	ToolCatalogEntry<App, Tool>["kind"]	Required	Read-only. Declared grouping used by registries and documentation; not an authorization boundary.
authorize	ToolCatalogEntry<App, Tool>["authorize"]	Required	Host permission check. Runs before execution and may be asynchronous.
execute	ToolCatalogEntry<App, Tool>["execute"]	Required	Executes the already-authorized input; must not repeat authorization decisions.
debugSteps	ToolCatalogEntry<App, Tool>["debugSteps"] | undefined	Optional	Optional result hook; writes through context.createSubFlowLogger() are recorded immediately.
parseOutput	ToolCatalogEntry<App, Tool>["parseOutput"]	Required	Validates untrusted output (for example a cached replay) before it is returned.

require

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

ToolCatalog.require(id: string): Readonly<ToolCatalogEntry<App, Tool>>

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

Parameter	Type	Passing	Description
id	string	Required	—

Returns: Readonly<ToolCatalogEntry<App, Tool>>.

Return value structure

Field	Type	Required	Description
id	ToolCatalogEntry<App, Tool>["id"]	Required	Read-only. Stable id; also the name the model calls.
description	ToolCatalogEntry<App, Tool>["description"]	Required	Read-only. Model-visible explanation of when to call the tool.
resolve	ToolCatalogEntry<App, Tool>["resolve"] | undefined	Optional	Read-only. See the type definition and usage context.
inputSchema	ToolCatalogEntry<App, Tool>["inputSchema"]	Required	Read-only. Schema applied to raw model arguments before authorize and execute.
active	ToolCatalogEntry<App, Tool>["active"] | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	ToolCatalogEntry<App, Tool>["asIntent"] | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
kind	ToolCatalogEntry<App, Tool>["kind"]	Required	Read-only. Declared grouping used by registries and documentation; not an authorization boundary.
authorize	ToolCatalogEntry<App, Tool>["authorize"]	Required	Host permission check. Runs before execution and may be asynchronous.
execute	ToolCatalogEntry<App, Tool>["execute"]	Required	Executes the already-authorized input; must not repeat authorization decisions.
debugSteps	ToolCatalogEntry<App, Tool>["debugSteps"] | undefined	Optional	Optional result hook; writes through context.createSubFlowLogger() are recorded immediately.
parseOutput	ToolCatalogEntry<App, Tool>["parseOutput"]	Required	Validates untrusted output (for example a cached replay) before it is returned.

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

• ExecutionOptions
• ReadonlyCatalog
• SelectedTools
• ToolCatalogEntry
• ToolDefinition
• ToolModelView
• ToolRegistryPorts
• ToolRuntime