CompiledTool

SUPPORT · type · Type contract

Tool definition type derived from a declaration literal, preserving input/output/id.

Import

TypeScript

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

JavaScript

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

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

Definition

Type: CompiledTool<App, Definition>

Type expression

type CompiledTool<App, Definition> = Definition extends {
  parseOutput(value: unknown): infer Output;
}
  ? Definition extends { readonly id: infer Id extends string }
    ? ExecutableTool<
        Definition extends { inputSchema: SchemaAdapter<infer Input> } ? Input : unknown,
        Output,
        App,
        Id
      >
    : never
  : never;

Type parameters

Type parameter	Constraint	Default type
App	—	—
Definition	—	—

Field structure

Field	Type	Required	Description
id	string	Required	Read-only. Stable id; also the name the model calls.
kind	string	Required	Read-only. Declared grouping used by registries and documentation; not an authorization boundary.
description	string	Required	Read-only. Model-visible explanation of when to call the tool.
inputSchema	SchemaAdapter<Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown>	Required	Read-only. Schema applied to raw model arguments before authorize and execute.
authorize	(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: OperationContext<App>) => MaybePromise<void>	Required	Host permission check. Runs before execution and may be asynchronous.
execute	(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: OperationContext<App> & NodeReportingContext) => unknown	Required	Executes the already-authorized input; must not repeat authorization decisions.
debugSteps	((result: unknown, context: import("../debug.js").NodeReportingContext) => void) | undefined	Optional	Optional result hook; writes through context.createSubFlowLogger() are recorded immediately.
parseOutput	(value: unknown) => unknown	Required	Validates untrusted output (for example a cached replay) before it is returned.
active	ToolCondition<App> | undefined	Optional	Read-only. Omitted means active. Authorization remains a separate execution boundary.
asIntent	AsIntent<App> | undefined	Optional	Read-only. Omitted means this tool is not advertised by withIntent().
resolve	(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: Readonly<{ stageId: string; }>) => ToolProposal	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.

Member index

Member	Purpose
authorize	Host permission check. Runs before execution and may be asynchronous.
execute	Executes the already-authorized input; must not repeat authorization decisions.
parseOutput	Validates untrusted output (for example a cached replay) before it is returned.
resolve	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.

Member details

authorize

Host permission check. Runs before execution and may be asynchronous.

CompiledTool.authorize(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: OperationContext<App>): MaybePromise<void>

Host permission check. Runs before execution and may be asynchronous.

Parameter	Type	Passing	Description
input	Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown	Required	—
context	OperationContext<App>	Required	—

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Returns: MaybePromise<void>.

Awaited value: void.

execute

Executes the already-authorized input; must not repeat authorization decisions.

CompiledTool.execute(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: OperationContext<App> & NodeReportingContext): unknown

Executes the already-authorized input; must not repeat authorization decisions.

Parameter	Type	Passing	Description
input	Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown	Required	—
context	OperationContext<App> & NodeReportingContext	Required	—

Fields of context

Field	Type	Required	Description
app	unknown extends App ? App : Readonly<App>	Required	Read-only. See the type definition and usage context.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.
report	(update: import("./execution/workflow.js").WorkflowNodeReport) => void	Required	Reports progress for the active node; Core supplies the execution identity.
createSubFlowLogger	() => SubFlowLogger	Required	Bound to this context and owned by runtime; repeated calls in one visit return the same instance.

Returns: unknown.

parseOutput

Validates untrusted output (for example a cached replay) before it is returned.

CompiledTool.parseOutput(value: unknown): unknown

Validates untrusted output (for example a cached replay) before it is returned.

Parameter	Type	Passing	Description
value	unknown	Required	—

Returns: unknown.

resolve

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.

CompiledTool.resolve(input: Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown, context: Readonly<{ stageId: string; }>): ToolProposal

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.

Parameter	Type	Passing	Description
input	Definition extends { inputSchema: SchemaAdapter<infer Input>; } ? Input : unknown	Required	—
context	Readonly<{ stageId: string; }>	Required	—

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.

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

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

• ExecutableTool
• IntentOptions
• MaybePromise
• NodeReportingContext
• OperationContext
• SchemaAdapter
• ToolProposal