defineToolCatalog

SUPPORT · function · Runtime value

Infer the host context from existing executable definitions, without widening it to unknown. Explicit host typing remains available for contextually typed declaration lists.

Import

TypeScript

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

JavaScript

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

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

Definition

Type parameters

Type parameter	Constraint	Default type
Definitions	readonly ToolDefinition<any, any, any>[]	—

Overload 1

defineToolCatalog<const Definitions extends readonly ToolDefinition<any, any, any>[]>(definitions: Definitions): ToolCatalog<DefinitionApp<Definitions[number]>, CompiledTool<DefinitionApp<Definitions[number]>, Definitions[number]>>

Infer the host context from existing executable definitions, without widening it to unknown.

Type parameter	Constraint	Default type
Definitions	readonly ToolDefinition<any, any, any>[]	—

Parameter	Type	Passing	Description
definitions	Definitions	Required	—

Returns: ToolCatalog<DefinitionApp<Definitions[number]>, CompiledTool<DefinitionApp<Definitions[number]>, Definitions[number]>>.

Return value structure

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

Overload 2

defineToolCatalog<App, const Definitions extends readonly ToolDefinition<any, any, App>[] = readonly ToolDefinition<any, any, App>[]>(definitions: Definitions): ToolCatalog<App, CompiledTool<App, Definitions[number]>>

Explicit host typing remains available for contextually typed declaration lists.

Type parameter	Constraint	Default type
App	—	—
Definitions	readonly ToolDefinition<any, any, App>[]	readonly ToolDefinition<any, any, App>[]

Parameter	Type	Passing	Description
definitions	Definitions	Required	—

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

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

• CompiledTool
• ToolCatalog
• ToolDefinition