@jangts/agent-core 0.3.6 → 0.5.0

package/development/docs/api/support.en.md

@@ -42,7 +42,7 @@ catalog.bind({ app, execution }): ToolRuntime
 runtime.invoke({ toolId, input }): Promise<ToolResult<InferredOutput>>
 ```
 
-catalog.capabilities projects the same jsonSchema from the tool declarations; its capability adapter checks only the raw parameter object and the selection contract, resolve returns `{ toolId, input }`, and input keeps the raw parameters. It does not run the tool's business inputSchema.parse early; the tool parses once in the real invoke before authorization and execution, avoiding repeated runs of transforming parsers. A custom model stage may register its own parsing and resolve, but a converted value must not be passed off again as the tool's raw input.
+catalog.tools projects the same jsonSchema from the tool declarations; its capability adapter checks only the raw parameter object and the selection contract, resolve returns `{ toolId, input }`, and input keeps the raw parameters. It does not run the tool's business inputSchema.parse early; the tool parses once in the real invoke before authorization and execution, avoiding repeated runs of transforming parsers. A custom model stage may register its own parsing and resolve, but a converted value must not be passed off again as the tool's raw input.
 
 Catalog implements the shared read-only collection interface. After a static selection, the inferred tool IDs and result types narrow together; dynamic IDs go through the unknown boundary. Context/App do not enter the model schema and cannot be overridden by model parameters.
 
@@ -69,8 +69,8 @@ The composition layer only verifies references and assembly and does not underst
 ```ts
 Support.createTextTransport({ id, options? }): ModelTransportDefinition<string>
 Support.createJsonTransport({ id, outputSchema, options? }): ModelTransportDefinition<Output>
-Support.createModelTransport({ id, capabilities, adapter?, options?, requireStrictArguments? }): ModelTransportDefinition
-Support.createStageModelTransport({ id, capabilities, stages, adapter?, options? }): ModelTransportDefinition
+Support.createModelTransport({ id, tools, adapter?, options?, requireStrictArguments? }): ModelTransportDefinition
+Support.createStageModelTransport({ id, tools, stages, adapter?, options? }): ModelTransportDefinition
 ```
 
 `createJsonTransport` is used to generate JSON values that conform to a Schema directly, such as summaries, classification results, or tabular data. `outputSchema` is an ordinary `SchemaAdapter<Output>` containing `jsonSchema` and a synchronous `parse(value)`; it can be provided directly, built with a Support Schema factory, or passed as a stateful class implementation. The parser is called after JSON decoding; declaring a JSON Schema does not replace runtime validation.
@@ -90,9 +90,9 @@ console.log(result.value.text, result.invocation);
 
 The ID keeps its literal type; after registration the original transport handle or the ID can be used for calls. Each call creates a new collector, and parts accumulate only within that call. Invalid JSON, Schema parser rejection, asynchronous parsers, and function-call parts all propagate as failures and produce no deliverable success value. Input/output/Schema budgets, cancellation, and call limits continue to be enforced by the same Runner.
 
-It requires no capability list and introduces no capability/input envelope; when a model must choose among registered capabilities, use `createModelTransport` or `createStageModelTransport`. The JSON request mode and the JSON value types a provider actually supports are decided by the Provider. Output remains uniformly `{ value, invocation }` and does not become a bare object in JSON mode. `options` accepts only temperature overrides and does not relax Provider and Runner constraints.
+It requires no capability list and introduces no capability/input envelope; when a model must choose among registered tools, use `createModelTransport` or `createStageModelTransport`. The JSON request mode and the JSON value types a provider actually supports are decided by the Provider. Output remains uniformly `{ value, invocation }` and does not become a bare object in JSON mode. `options` accepts only temperature overrides and does not relax Provider and Runner constraints.
 
-capabilities is a ModelCapabilitySource or a source factory read by stageId. A stages item uses `{ id, capabilityIds }`. Static sources validate all references at assembly, and dynamic sources refresh when the interaction is prepared for this call. An unknown stage does not invoke a dynamic source and does not extend to other stages.
+tools is a ModelToolSource or a source factory read by stageId. A stages item uses `{ id, toolIds }`. Static sources validate all references at assembly, and dynamic sources refresh when the interaction is prepared for this call. An unknown stage does not invoke a dynamic source and does not extend to other stages.
 
 prepare(stageId) returns the unified collector protocol; a prepared interaction fixes the resolver and receiver for this call, and the next dynamic preparation can obtain a new source. Native and JSON adapters consume the same capability projection. The native adapter validates the object shape, index, ID, name, and argument strings of neutral function-call-delta values; invalid parts do not enter capability execution. The collector's outputChars counting and call metadata reading boundaries follow the [Core transport contract](core.md). Fallback is chosen explicitly by the App and is not guessed implicitly from model names or URLs.
 
@@ -102,7 +102,7 @@ prepare(stageId) returns the unified collector protocol; a prepared interaction
 Support.createModelStrategy({ model, models?, reasoning?, reasoningOptions?, budget?, ...coreSettings }): ModelRunnerOptions
 ```
 
-`model` accepts a model definition or an ID in `models`. `reasoning` selects a configuration explicitly registered in `reasoningOptions`; for example, high/off correspond to a Provider already configured with provider reasoning parameters. Unknown IDs or reasoning schemes raise errors, and model capabilities are not inferred from names.
+`model` accepts a model definition or an ID in `models`. `reasoning` selects a configuration explicitly registered in `reasoningOptions`; for example, high/off correspond to a Provider already configured with provider reasoning parameters. Unknown IDs or reasoning schemes raise errors, and model tools are not inferred from names.
 
 The budget defaults to medium. These are overridable local task budgets, not guarantees of provider capacity or performance:
 
@@ -161,7 +161,7 @@ If no budget is configured or passed with the request, construction raises an er
 
 modelInteractionCatalog selects a native function or JSON adapter by an explicitly registered interaction ID; the App supplies selection metadata, can override explicitly, and does not infer capability from brand, model name, or URL.
 
-Preview rules use stageId and capabilityId; previews are transient and cannot authorize, persist, or execute model proposals. ModelOutputEvent goes to the sink and ProviderObservation goes to the observer; they are not mixed.
+Preview rules use stageId and toolId; previews are transient and cannot authorize, persist, or execute model proposals. ModelOutputEvent goes to the sink and ProviderObservation goes to the observer; they are not mixed.
 
 External SSE/wire types can keep standard fields and are converted at the Support boundary; the protocol itself is not changed to standardize SDK spelling.
 
@@ -171,7 +171,7 @@ Completion determination is selected through `ports.completionPolicy` and defaul
 
 `Support.createToolCallCollector` aggregates call parts by index, and the completion policy and direct callers share the same implementation. Conflicting part IDs, duplicate IDs across indices, and incomplete calls are rejected as protocol errors, and one complete call does not mask another incomplete call.
 
-The protocol layer never restricts receiving multiple call parts, and `parallel_tool_calls` is only a send field that expresses neither execution authorization nor scheduling policy. The single-proposal limit on the Agent path is decided by the `nativeFunctionInteraction` collector; using the Provider directly is not subject to that limit and does not thereby gain tool execution, authorization, or loop capabilities.
+The protocol layer never restricts receiving multiple call parts, and `parallel_tool_calls` is only a send field that expresses neither execution authorization nor scheduling policy. The single-proposal limit on the Agent path is decided by the `nativeFunctionInteraction` collector; using the Provider directly is not subject to that limit and does not thereby gain tool execution, authorization, or loop tools.
 
 `ProviderMessage` provides the `tool` result and assistant `toolCalls` shapes needed for direct connection, and `chatCompletionMessages` maps them explicitly to `tool_call_id` and nested `tool_calls`; mismatched roles or fields and incomplete call fields are rejected as `TypeError`. Only declared fields are sent, and extra fields (including raw wire fields) are not passed through; `toolCallId` must be a non-empty string, and `role` and `content` are validated per the message contract. The Core `ModelMessage` and `ChatProvider` abstract signatures are unchanged.
 
@@ -222,7 +222,7 @@ request.callModel({ stageId, input, maxOutputTokens, transport }): Promise<Model
 
 request provides stageId and the fragments to compress or candidates to select; the result parser handles only the returned value. Policies reference handlers by handlerId; callModel takes a named request and returns a ModelResult. The cancellation signal is read from the second context. Processing nodes connect these callbacks through the Workflow model port; for original-text protection, history grouping, watermarks, reserved calls, and audit rules, see [Context nodes](context-processing.md).
 
-createReplyPreview uses `{ rules, sink, render?, maxChars? }`; rules use stageId and capabilityId (native adaptation maps the latter to the function wire name). The sink is awaited in order, and render is synchronous. Rule data is copied as a snapshot and callbacks fix the original receiver; a preview never authorizes or executes tools.
+createReplyPreview uses `{ rules, sink, render?, maxChars? }`; rules use stageId and toolId (native adaptation maps the latter to the function wire name). The sink is awaited in order, and render is synchronous. Rule data is copied as a snapshot and callbacks fix the original receiver; a preview never authorizes or executes tools.
 
 When a selector omits `instruction`, it uses the built-in trimming selection instruction, which requires the model to return `{ stepIds }` and explicitly treats fragment excerpts as data. A custom parser must provide the corresponding instruction as well.
 
@@ -250,3 +250,49 @@ const settings = Support.createModelStrategy({ model: { provider }, maxOutputTok
 ```
 
 JSON value transports enable `json` mode by default. This mode in CompatibleModelProvider uses `json_object`; when an array or scalar is needed and the provider does not support the corresponding mode, set `json: false` explicitly in the same `options` while keeping full JSON decoding and outputSchema validation.
+
+## Model Tools and demand discovery
+
+`Support.defineModelTools(definitions)` compiles BaseTool declarations. Each has id, description, inputSchema and a synchronous resolve. When resolve is omitted, Support uses the parsed input as the result. ExecutableTool adds authorization, execution and output validation; `defineToolCatalog` derives its model view as `catalog.tools` without requiring a separate capability declaration.
+
+```ts
+const tools = Support.defineModelTools([{
+  id: 'manage_memo',
+  description: 'Process a memo draft',
+  inputSchema: memoSchema,
+  asIntent: {
+    description: 'Remember something or set a reminder',
+    when: context => context.features.memos,
+    delegates: ['read', 'final'],
+  },
+  active: context => context.services.memos != null,
+  resolve: input => input,
+}]);
+const discovery = tools.withIntent(context);
+const explicit = tools.select(['manage_memo'], context);
+```
+
+`asIntent` accepts true, a nonblank description, a synchronous boolean predicate, or `{ description?, when?, delegates? }`. Omission means not participating in demand discovery; no static false is needed. Missing description reuses the Tool description. Missing when enables discovery. Delegates are an optional allowed set, validated against domain vocabulary when using a domain registry, not an execution order. Intent has no independent identity or registry. Similar descriptions on different tools remain separate.
+
+`active` accepts a boolean or synchronous predicate and defaults to true. Selection filters activation; prepared projections and execution recheck it before accepting or performing work. Activation does not replace authorization. Node code owns candidate selection and can use withIntent at any stage; Engine does not automatically publish tools based on this metadata.
+
+## Delegates and dispatch
+
+A delegate is one optional tool field: `delegate: 'query'` claims that id. The tool registry keeps a unique `delegateId → tool` index, so a node only calls `registry.call(next, context)` and the registry resolves `next.type` to its implementation.
+
+A delegate creates no second Tool identity and no second execution path: the matched tool still runs the same `execute`, authorization and lifecycle. The allowed delegate set stays in the domain declaration (for example a GoalTool's `delegates`); it lists the next steps a model may pick and is not an execution order.
+
+## Associated Tool registration
+
+```ts
+const linked = Support.defineAssociatedCatalog(owners, {
+  tools: independentTools,
+  toolDefaults: owner => existingTools.require(owner.id),
+});
+// owner.modelTools: an array of inline Tool overrides or independent Tool IDs.
+// linked.tools: normalized model Tool catalog.
+// linked.bindings: owner ID -> toolIds.
+// linked.sources: local provenance; not automatically sent to the model.
+```
+
+References name explicitly declared independent tools, never a tool accidentally contributed by another owner. Duplicate identities, repeated references and missing contracts are rejected. An empty modelTools array suppresses default projection. Tool descriptions are not aggregated into Intent entities. Decorator conversion does not accept parallel asIntent configuration: combine WorkflowTool and a separate Intent decorator on the same target. See [the complete runnable comparison](configuration-in-workflow.en.md).

package/development/docs/api/support.md

@@ -69,8 +69,8 @@ Support.defineRegistrationCatalog(definitions): RegistrationCatalog
 ```ts
 Support.createTextTransport({ id, options? }): ModelTransportDefinition<string>
 Support.createJsonTransport({ id, outputSchema, options? }): ModelTransportDefinition<Output>
-Support.createModelTransport({ id, capabilities, adapter?, options?, requireStrictArguments? }): ModelTransportDefinition
-Support.createStageModelTransport({ id, capabilities, stages, adapter?, options? }): ModelTransportDefinition
+Support.createModelTransport({ id, tools, adapter?, options?, requireStrictArguments? }): ModelTransportDefinition
+Support.createStageModelTransport({ id, tools, stages, adapter?, options? }): ModelTransportDefinition
 ```
 
 `createJsonTransport` 用于直接生成符合 Schema 的 JSON 值，例如摘要、分类结果或表格数据。`outputSchema` 是普通 `SchemaAdapter<Output>`，包含 `jsonSchema` 和同步 `parse(value)`；可直接提供、使用 Support Schema 工厂，或传入有状态的类实现。JSON 解码后再调用该 parser；声明 JSON Schema 不替代运行时校验。
@@ -92,7 +92,7 @@ ID 保留字面量类型；登记后可用原 transport 句柄或 ID 调用。
 
 它不要求能力清单，也不引入 capability/input envelope；需要模型从已注册能力中作选择时，使用 `createModelTransport` 或 `createStageModelTransport`。JSON 请求方式及供应商实际支持的 JSON 值类型由 Provider 决定。输出仍统一为 `{ value, invocation }`，不会因 JSON 模式变成裸对象。`options` 只接受温度覆盖，不放宽 Provider 和 Runner 的约束。
 
-capabilities是ModelCapabilitySource或按stageId读取的source工厂。stages项使用`{ id, capabilityIds }`。静态source装配时校验全部引用，动态source在本次准备交互时刷新。未知阶段不调用动态source，不扩大到其他阶段。
+capabilities是ModelToolSource或按stageId读取的source工厂。stages项使用`{ id, toolIds }`。静态source装配时校验全部引用，动态source在本次准备交互时刷新。未知阶段不调用动态source，不扩大到其他阶段。
 
 prepare(stageId)返回统一的collector协议；准备好的交互固定本次resolver及接收者；下一次动态准备可取得新source。native与JSON adapter消费同一能力投影。原生 adapter 校验中立 function-call-delta 的对象形状、index、ID、名称和参数字符串；非法分片不进入能力执行。collector 的 outputChars 计数和 call 元数据读取边界遵守 [Core 传输合同](core.md)。回退由App显式选择，不按模型名或URL隐式猜测。
 
@@ -161,7 +161,7 @@ Support 的策略模式是 `validate | reduce | audit`。`createContextProcessin
 
 modelInteractionCatalog 按明确登记的交互 ID 选择原生函数或 JSON adapter；App 提供选择元数据，可明确覆盖，不按品牌、模型名或 URL 推断能力。
 
-预览规则使用stageId与capabilityId；预览是暂态，不能授权、持久化或执行模型提议。ModelOutputEvent进sink，ProviderObservation进observer，不混用。
+预览规则使用stageId与toolId；预览是暂态，不能授权、持久化或执行模型提议。ModelOutputEvent进sink，ProviderObservation进observer，不混用。
 
 外部SSE/wire类型可以保留标准字段，并在Support边界转换；不为统一SDK拼写修改协议本身。
 
@@ -171,9 +171,9 @@ modelInteractionCatalog 按明确登记的交互 ID 选择原生函数或 JSON a
 
 `Support.createToolCallCollector` 按 index 聚合调用分片，完成策略与直接调用方共用同一实现。分片 ID 冲突、跨 index 重复 ID 与残缺调用都按协议错误拒绝，一个完整调用不会掩盖另一个残缺调用。
 
-协议层从不限制接收多个调用分片，`parallel_tool_calls` 只是发送字段，不表达执行授权或调度策略。Agent 路径的单提案限制由 `nativeFunctionInteraction` 的 collector 决定；直接使用 Provider 不受该限制，也不因此获得工具执行、授权或循环能力。
+协议层从不限制接收多个调用分片，`parallel_tool_calls` 只是发送字段，不表达执行授权或调度策略。Agent 路径的单提案限制由 `nativeFunctionInteraction` 的 collector 决定；直接使用 Provider 不受该限制，也不因此获得工具执行、授权或循环能力。需要正文 + 多调用时使用 `Support.createSessionModelTransport`，它复用同一聚合 collector，但不改变 `nativeFunctionInteraction` 的单提案合同。`createSessionModelTransport` 返回 `ResolvedSessionResult`，每个调用的 `toolId`、解析后的 `input` 与非致命 `problem` 都由 Support 解析；Core 只提供原始 `ModelSessionResult`。
 
-`ProviderMessage` 提供直连所需的 `tool` 结果与 assistant `toolCalls` 形状，`chatCompletionMessages` 显式映射为 `tool_call_id` 与嵌套 `tool_calls`；角色与字段不匹配、调用字段不完整时按 `TypeError` 拒绝。只发送声明字段，额外字段（包括原始 wire 字段）不透传；`toolCallId` 必须是非空字符串，`role` 与 `content` 按消息合同校验。Core `ModelMessage` 与 `ChatProvider` 抽象签名不变。
+`ProviderMessage` 提供直连所需的 `tool` 结果与 assistant `toolCalls` 形状，`chatCompletionMessages` 显式映射为 `tool_call_id` 与嵌套 `tool_calls`；角色与字段不匹配、调用字段不完整时按 `TypeError` 拒绝。只发送声明字段，额外字段（包括原始 wire 字段）不透传；`toolCallId` 必须是非空字符串，`role` 与 `content` 按消息合同校验。Core `ModelMessage` 现已支持 assistant `toolCalls` 与 `role:'tool'` 字段；`ChatProvider` 抽象签名仍为 `readonly ModelMessage[]`。
 
 直连工具线程使用声明字段，assistant 的 `content` 可以为空字符串；工具结果通过同一个调用 ID 关联：
 
@@ -222,7 +222,7 @@ request.callModel({ stageId, input, maxOutputTokens, transport }): Promise<Model
 
 request 提供 stageId 及压缩片段／选择候选；结果 parser 只处理返回的 value。策略引用使用 handlerId；callModel 接收命名请求并返回 ModelResult。取消信号从第二个 context 读取。处理节点通过 Workflow 模型端口接入这些回调，保护原文、历史分组、水位、预留调用和审计规则见[上下文节点](context-processing.md)。
 
-createReplyPreview使用`{ rules, sink, render?, maxChars? }`；规则使用stageId和capabilityId（native适配将其映射为函数wire name）。sink按序等待，render同步。规则数据快照复制，回调固定原接收者；预览永不授权或执行工具。
+createReplyPreview使用`{ rules, sink, render?, maxChars? }`；规则使用stageId和toolId（native适配将其映射为函数wire name）。sink按序等待，render同步。规则数据快照复制，回调固定原接收者；预览永不授权或执行工具。
 
 选择器省略 `instruction` 时使用内置的裁切选择指令，要求模型返回 `{ stepIds }`，并明确将片段摘录视为数据。自定义解析器须同时提供对应指令。
 
@@ -250,3 +250,49 @@ const settings = Support.createModelStrategy({ model: { provider }, maxOutputTok
 ```
 
 JSON 值传输缺省启用 `json` 模式。CompatibleModelProvider 的该模式使用 `json_object`；需要数组／标量而供应商不支持对应模式时，可在同一 `options` 中显式设 `json: false`，仍保留完整 JSON 解码和 outputSchema 校验。
+
+## 模型 Tool、用途与激活
+
+`Support.defineModelTools(definitions)` 编译 BaseTool 声明：id、description、inputSchema 和同步 resolve。省略 resolve 时，Support 将已解析输入作为结果。ExecutableTool 在 BaseTool 上增加授权、执行与结果校验；`defineToolCatalog` 从同一声明生成 `catalog.tools` 模型视图，无需另配 Capability。
+
+```ts
+const tools = Support.defineModelTools([{
+  id: 'manage_memo',
+  description: 'Process a memo draft',
+  inputSchema: memoSchema,
+  asIntent: {
+    description: 'Remember something or set a reminder',
+    when: context => context.features.memos,
+    delegates: ['read', 'final'],
+  },
+  active: context => context.services.memos != null,
+  resolve: input => input,
+}]);
+const discovery = tools.withIntent(context);
+const explicit = tools.select(['manage_memo'], context);
+```
+
+`asIntent` 接受 true、非空描述、同步布尔判断函数或 `{ description?, when?, delegates? }`。省略表示不参与需求识别，不提供静态 false。描述省略时复用 Tool 描述，when 省略时参与。delegates 可选，表示允许集合，由领域注册器校验词汇，不表示执行顺序。Intent 没有独立身份或注册表；不同 Tool 的相似描述分别保留。
+
+`active` 接受布尔值或同步判断函数，省略默认激活。获取时筛选，已准备视图与执行入口在处理时复核；激活不能代替鉴权。节点自主组织候选，任何阶段都可以使用 withIntent；Engine 不依据标记自动投放工具。
+
+## delegate 与分派
+
+delegate 是工具上的一个可选字段：`delegate: 'query'` 表示该工具认领这个 id。工具注册表维护 `delegateId → tool` 索引并在注册时保证唯一，节点分发时只需 `registry.call(next, context)`，由注册表按 `next.type` 找到实现。
+
+delegate 不创建第二个 Tool 身份，也不改变执行入口：命中后仍走同一个 `execute`、鉴权与生命周期。delegates 的允许集合仍由领域声明（例如 GoalTool 的 `delegates`）提供，只表示模型可选的下一步，不表示执行顺序。
+
+## Tool 关联注册
+
+```ts
+const linked = Support.defineAssociatedCatalog(owners, {
+  tools: independentTools,
+  toolDefaults: owner => existingTools.require(owner.id),
+});
+// owner.modelTools: an array of inline Tool overrides or independent Tool IDs.
+// linked.tools: normalized model Tool catalog.
+// linked.bindings: owner ID -> toolIds.
+// linked.sources: local provenance; not automatically sent to the model.
+```
+
+引用只指向显式独立 Tool，不隐式依赖另一个 owner 恰好贡献的工具。重名、重复引用和缺失合同拒绝；modelTools 空数组关闭该 owner 的缺省投影。不会把工具描述聚合为 Intent 实体。装饰器转换不接收并联 asIntent：同一目标分别使用 WorkflowTool 和 Intent 装饰器。完整代码见[独立配置与关联配置](configuration-in-workflow.md)。

package/development/docs/api/types.en.md

@@ -1,5 +1,39 @@
 # Shared types and behavior contracts
 
+## Common Tool contract and extensions
+
+BaseTool is the common model-facing interface. Subtypes add actual contracts rather than names for different uses.
+
+```ts
+interface BaseTool<Input = unknown, Selection = Input, Context = any> {
+  readonly id: string;
+  readonly description: string;
+  readonly inputSchema: SchemaAdapter<Input>;
+  readonly active?: boolean | ((context: Readonly<Context>) => boolean);
+  readonly asIntent?: true | string
+    | ((context: Readonly<Context>) => boolean)
+    | {
+        readonly description?: string;
+        readonly when?: (context: Readonly<Context>) => boolean;
+        readonly delegates?: readonly string[];
+      };
+  resolve(input: Input, context: Readonly<{ stageId: string }>): Selection;
+}
+
+interface ExecutableTool<Input, Output, App>
+  extends BaseTool<Input, ToolProposal, App> {
+  readonly kind: string;
+  authorize(input: Input, context: OperationContext<App>): MaybePromise<void>;
+  execute(input: Input, context: OperationContext<App> & NodeReportingContext): MaybePromise<Output>;
+  parseOutput(value: unknown): Output;
+  debugSteps?(result: Output, context: NodeReportingContext): void;
+}
+```
+
+ExecutableTool adds execution, Tool adds one optional lifecycle block for invocation and delivery hooks, IntentTool adds optional domain policies, and Support.PreviewTool adds streaming presentation. Lifecycle execution uses a different context from typed execution, so both extend the common ModelTool rather than forcing identical handlers. Cafe's GoalTool narrows domain policies in the App.
+
+There is no independent Intent identity. asIntent marks discovery use and optionally supplies a demand-facing description, condition and allowed delegates. active conditions remain distinct from authorization. Normalized tools always have resolve; Support fills identity mappings or executable Tool proposals when omitted in configuration. Neither mapping executes a business operation. See [Support](support.en.md) and [Public Symbol Reference](reference.en.md) for the full registration and subtype signatures.
+
 [Back to API handbook](README.md). This page describes the base types and invocation rules shared by all modules.
 
 ## Identity, configuration, and time
@@ -47,7 +81,7 @@ interface OperationContext<App> {
 Core supplies the actual signal when it creates a request instance; the signal received by a registered handler always exists. `app` is the business dependency supplied by the caller, and models cannot override it. A Kit may define a local execution context that extends this contract, but it cannot require other Kits to fill its fields.
 
 - A request instance binds execution at construction, so later invoke calls do not need to pass signal again.
-- Reusable capabilities receive context on every run/read/resolve.
+- Reusable tools receive context on every run/read/resolve.
 - App service identity, budget, and cancellation travel along the real call chain; nesting a Kit never grants new budget.
 
 ## Schema and parsing

package/development/docs/api/types.md

@@ -2,6 +2,49 @@
 
 [返回 API 手册](README.md)。本页说明各模块共用的基础类型与调用规则。
 
+## Tool 的共同接口与扩展
+
+模型可选择的接口统一使用 BaseTool；只有确实增加合同的类型才继承，不为每种用途建立同义子类。
+
+```ts
+interface BaseTool<Input = unknown, Selection = Input, Context = any> {
+  readonly id: string;
+  readonly description: string;
+  readonly inputSchema: SchemaAdapter<Input>;
+  readonly active?: boolean | ((context: Readonly<Context>) => boolean);
+  readonly asIntent?: true | string
+    | ((context: Readonly<Context>) => boolean)
+    | {
+        readonly description?: string;
+        readonly when?: (context: Readonly<Context>) => boolean;
+        readonly delegates?: readonly string[];
+      };
+  resolve(input: Input, context: Readonly<{ stageId: string }>): Selection;
+}
+
+interface ExecutableTool<Input, Output, App>
+  extends BaseTool<Input, ToolProposal, App> {
+  readonly kind: string;
+  authorize(input: Input, context: OperationContext<App>): MaybePromise<void>;
+  execute(input: Input, context: OperationContext<App> & NodeReportingContext): MaybePromise<Output>;
+  parseOutput(value: unknown): Output;
+  debugSteps?(result: Output, context: NodeReportingContext): void;
+}
+```
+
+```text
+ModelTool
+├─ ExecutableTool：授权、执行、输出校验
+├─ Tool：一个可选 lifecycle 块，覆盖调用、上下文与交付
+├─ IntentTool：领域策略与允许 delegate
+│  └─ GoalTool：Cafe 的具体枚举及约束
+└─ Support.PreviewTool：模型输出的流式预览
+```
+
+Tool 与 ExecutableTool 的执行上下文不同，分别继承共同模型合同，保留各自真实执行边界。IntentTool 使用相同 Tool 身份、Schema 与 resolver，不是独立 Intent 实体；delegates 可以从关联推导或由 asIntent.delegates 覆盖。GoalTool 属于应用，不成为 Core 的必填配置。
+
+resolve 在规范化合同中必定存在；Support 配置入口允许省略恒等映射。执行 Tool 的默认映射产生 `{ toolId, input }`，不是直接执行。active 与 asIntent 的回调只在本地求值；Schema、名称及投影后的描述才提交给模型。完整子类字段和注册形式见[公开符号参考](reference.md)，选取方法见[Support](support.md)。
+
 ## 身份、配置和时间
 
 ```ts

package/development/docs/basic-usage.en.md

@@ -45,7 +45,7 @@ const double = Support.defineTool({
   },
 });
 const catalog = Support.defineToolCatalog([double]);
-const selection = Support.createModelTransport({ id: 'choose-tool', capabilities: catalog.capabilities });
+const selection = Support.createModelTransport({ id: 'choose-tool', tools: catalog.tools });
 ```
 
 inputSchema contains both the model-visible jsonSchema and the real parser. The selection stage keeps only the raw proposed parameters; when the tool executes they are parsed once, so a converting parser does not run twice. authorize may only return void or throw; asynchronous authorization uses the asynchronous run entry. Permissions come from server-side context, not from model parameters.

package/development/docs/basic-usage.md

@@ -45,7 +45,7 @@ const double = Support.defineTool({
   },
 });
 const catalog = Support.defineToolCatalog([double]);
-const selection = Support.createModelTransport({ id: 'choose-tool', capabilities: catalog.capabilities });
+const selection = Support.createModelTransport({ id: 'choose-tool', tools: catalog.tools });
 ```
 
 inputSchema同时包含模型可见jsonSchema和真实parser。选择阶段仅保留原始提议参数；工具执行时解析一次，转换型parser不会被运行两遍。authorize只能返回void或抛错，异步授权使用异步运行入口；权限来自服务端上下文，不从模型参数取得。

package/development/docs/create-app.en.md

@@ -73,4 +73,4 @@ node SDK_PATH/development/skills/agent-core-app/scripts/create-app.mjs ./my-agen
 
 This mode compares the current digests of managed files, the generation baseline, and the template digests of the selected SDK, and reports modified, missing, symlink, and changes to the template itself. It checks only the code/configuration paths defined by the template, does not read `.env` or candidate knowledge body text, and does not modify the project. Keep the generation receipt as the basis for upgrades; when a new template must be adopted, generate in another directory and review the merge, and existing user code is never overwritten.
 
-Advanced capabilities use the existing Core/Support/Kit configuration: extend the same manifests, handlers, and execution entries to integrate subtasks, knowledge answering, or persistent tasks. Whether to record, how to store, and when to publish and restore are still implemented according to the application's actual product authorization.
+Advanced tools use the existing Core/Support/Kit configuration: extend the same manifests, handlers, and execution entries to integrate subtasks, knowledge answering, or persistent tasks. Whether to record, how to store, and when to publish and restore are still implemented according to the application's actual product authorization.

package/development/docs/examples/registration/associated.mjs

@@ -0,0 +1,8 @@
+/** One executable Tool declaration supplies both model and execution contracts. */
+import { Support } from '@jangts/agent-core';
+import { toolDefinitions } from './tools.mjs';
+
+export function associatedConfiguration() {
+  const execution = Support.defineToolCatalog(toolDefinitions());
+  return { execution, tools: execution.tools };
+}

package/development/docs/examples/registration/independent.mjs

@@ -0,0 +1,20 @@
+/** Independent model and execution declarations, connected through checked Tool IDs. */
+import { Support } from '@jangts/agent-core';
+import { toolDefinitions, textInput } from './tools.mjs';
+
+export function independentConfiguration() {
+  const execution = Support.defineToolCatalog(toolDefinitions());
+  const tools = Support.defineModelTools([
+    {
+      id: 'search_notes', description: '按主题检索公开笔记', asIntent: '用户希望查找笔记',
+      inputSchema: { jsonSchema: textInput('query').jsonSchema, parse: value => value },
+      resolve: input => ({ toolId: 'search_notes', input }),
+    },
+    {
+      id: 'read_note', description: '读取已定位笔记的正文',
+      inputSchema: { jsonSchema: textInput('noteId').jsonSchema, parse: value => value },
+      resolve: input => ({ toolId: 'read_note', input }),
+    },
+  ]);
+  return { execution, tools };
+}

package/development/docs/examples/registration/protocol.mjs

@@ -0,0 +1,48 @@
+/** A name/input envelope changes model output format while preserving the same tool proposal. */
+import { Support } from '@jangts/agent-core';
+
+export function wrappedConfiguration(configuration) {
+  const capability = {
+    id: 'tool_request',
+    description: '提交工具名称和参数，由程序执行',
+    inputSchema: Support.defineSchema({
+      jsonSchema: {
+        type: 'object',
+        required: ['name', 'input'],
+        additionalProperties: false,
+        properties: {
+          name: { type: 'string', enum: configuration.tools.ids() },
+          input: { type: 'object' },
+        },
+        anyOf: configuration.tools.definitions.map((tool) => ({
+          properties: {
+            name: { const: tool.id },
+            input: tool.inputSchema.jsonSchema,
+          },
+        })),
+      },
+      parse(value) {
+        if (
+          !value ||
+          typeof value !== 'object' ||
+          Array.isArray(value) ||
+          Object.keys(value).some((key) => key !== 'name' && key !== 'input') ||
+          typeof value.name !== 'string' ||
+          !value.input ||
+          typeof value.input !== 'object' ||
+          Array.isArray(value.input)
+        ) {
+          throw new TypeError('Expected { name, input }');
+        }
+        configuration.tools.require(value.name);
+        return value;
+      },
+    }),
+    resolve: ({ name, input }) => ({ toolId: name, input }),
+  };
+  return {
+    ...configuration,
+    tools: Support.defineModelTools([capability]),
+    candidateIds: ['tool_request'],
+  };
+}

package/development/docs/examples/registration/run.mjs

@@ -0,0 +1,47 @@
+/** Run the tutorial offline and check that both configuration styles produce equivalent contracts. */
+import assert from 'node:assert/strict';
+import { independentConfiguration } from './independent.mjs';
+import { associatedConfiguration } from './associated.mjs';
+import { runCase, taskTransport } from './workflow.mjs';
+import { wrappedConfiguration } from './protocol.mjs';
+
+const separate = independentConfiguration();
+const linked = associatedConfiguration();
+assert.deepEqual(linked.tools.withIntent({}).ids(), separate.tools.withIntent({}).ids());
+const rawFunctions = (configuration) =>
+  taskTransport(configuration.tools).prepare('choose-operation').options.functions;
+assert.deepEqual(rawFunctions(linked), rawFunctions(separate));
+assert.deepEqual(
+  linked.tools.resolve(
+    { toolId: 'search_notes', input: { query: ' 咖啡 ' } },
+    { stageId: 'choose-operation' },
+  ),
+  separate.tools.resolve(
+    { toolId: 'search_notes', input: { query: ' 咖啡 ' } },
+    { stageId: 'choose-operation' },
+  ),
+);
+for (const [question, name, input] of [
+  ['帮我找咖啡相关的笔记', 'search_notes', { query: '咖啡' }],
+  ['读一下n1这篇笔记', 'read_note', { noteId: 'n1' }],
+]) {
+  const a = await runCase(separate, question, name, input);
+  const b = await runCase(linked, question, name, input);
+  assert.deepEqual(a.submitted, b.submitted);
+  assert.deepEqual(a.result, b.result);
+  console.log(JSON.stringify({ question, result: b.result }));
+}
+const a = await runCase(wrappedConfiguration(separate), '帮我找咖啡相关的笔记', 'tool_request', {
+  name: 'search_notes',
+  input: { query: '咖啡' },
+});
+const b = await runCase(wrappedConfiguration(linked), '帮我找咖啡相关的笔记', 'tool_request', {
+  name: 'search_notes',
+  input: { query: '咖啡' },
+});
+assert.deepEqual(a.submitted, b.submitted);
+assert.deepEqual(a.result, b.result);
+console.log(
+  'PASS: discovery, model functions, messages and execution results match.',
+);
+console.log('PASS: name/input envelope uses the same workflow and execution contract.');

package/development/docs/examples/registration/tools.mjs

@@ -0,0 +1,75 @@
+/** Tutorial tools: public in-memory notes only; no application database or network access. */
+import { Support } from '@jangts/agent-core';
+
+// The two business inputs differ; the model must use the selected tool's schema.
+export function textInput(field) {
+  return Support.defineSchema({
+    jsonSchema: {
+      type: 'object',
+      properties: { [field]: { type: 'string', minLength: 1 } },
+      required: [field],
+      additionalProperties: false,
+    },
+    parse(value) {
+      if (
+        !value ||
+        typeof value !== 'object' ||
+        Array.isArray(value) ||
+        Object.keys(value).length !== 1 ||
+        typeof value[field] !== 'string' ||
+        !value[field].trim()
+      ) {
+        throw new TypeError(`Expected one nonempty string: ${field}`);
+      }
+      return { [field]: value[field].trim() };
+    },
+  });
+}
+
+const notes = [{ id: 'n1', title: '咖啡烘焙', body: '烘焙程度可结合豆色和风味判断。' }];
+
+/** Build fresh declarations so manual and associated examples share no mutable request state. */
+export function toolDefinitions() {
+  return [
+    {
+      id: 'search_notes',
+      asIntent: '用户希望查找笔记',
+      kind: 'read',
+      description: '按主题检索公开笔记',
+      inputSchema: textInput('query'),
+      authorize() {}, // This tutorial uses public constants, with no private account data.
+      execute({ query }) {
+        return notes
+          .filter((note) => note.title.includes(query))
+          .map(({ id, title }) => ({ id, title }));
+      },
+      parseOutput(value) {
+        if (
+          !Array.isArray(value) ||
+          value.some((note) => typeof note?.id !== 'string' || typeof note.title !== 'string')
+        ) {
+          throw new TypeError('Invalid search result');
+        }
+        return value;
+      },
+    },
+    {
+      id: 'read_note',
+      kind: 'read',
+      description: '读取已定位笔记的正文',
+      inputSchema: textInput('noteId'),
+      authorize() {},
+      execute({ noteId }) {
+        const note = notes.find((note) => note.id === noteId);
+        if (!note) throw new Error('Note not found');
+        return { ...note };
+      },
+      parseOutput(value) {
+        if (!value || typeof value.body !== 'string') {
+          throw new TypeError('Invalid note body');
+        }
+        return value;
+      },
+    },
+  ];
+}