@jangts/agent-core 0.3.5 → 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
@@ -37,6 +71,7 @@ interface ExecutionOptions {
   readonly diagnostics?: DiagnosticContext;
 }
 interface OperationContext<App> {
+  readonly logger?: SubFlowLog;
   readonly app: Readonly<App>;
   readonly signal: AbortSignal;
   readonly diagnostics?: DiagnosticContext;
@@ -46,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
@@ -37,6 +80,7 @@ interface ExecutionOptions {
   readonly diagnostics?: DiagnosticContext;
 }
 interface OperationContext<App> {
+  readonly logger?: SubFlowLog;
   readonly app: Readonly<App>;
   readonly signal: AbortSignal;
   readonly diagnostics?: DiagnosticContext;

package/development/docs/api/workflow-views.en.md

@@ -0,0 +1,64 @@
+# Workflow graphs and execution chains
+
+`workflow.toGraph()` returns registered topology. `await workflow.toChain(runId)` returns observed visits of this Workflow within a run. Both return deeply readonly JSON data, without handlers, condition functions, layout or renderers.
+
+These interfaces support developer reviews, debugging, observability clients and demonstrations. Export does not participate in Agent decisions, scheduling or task execution and adds no business capability. A chain is a readonly projection of existing records, not a replay or resume entry. Apps can authorize log-based reflection; graphs and chains do not automatically enter learning or rule modification.
+
+## Reading a run
+
+```ts
+const workflow = defineWorkflow({
+  id: 'assistant', nodes,
+  chainSource: async runId => {
+    const capture = await authorizedRunReader.readAll(runId);
+    return { events: capture.events, coverage: capture.coverage };
+  },
+});
+const graph = workflow.toGraph();
+const chain = await workflow.toChain(runId);
+const exported = await workflow.toChain(runId, authorizedSource);
+```
+
+`WorkflowChainSource` receives a runId and returns `Promise<{ events: readonly CoreDiagnosticRecord[]; coverage: WorkflowChainCoverage }>`. The App owns authorization, account isolation, storage paths, retention, pagination and read limits. Core installs no global run store and does not retain the latest run. A per-call source overrides the bound source without modifying the Workflow. `add()` carries the bound source into the derived Workflow.
+
+An empty runId or absent source throws TypeError. Source errors propagate. No matching Workflow visits throws RangeError, rather than returning an apparently successful empty history. Readers must provide a consistent snapshot and state whether the capture is complete, live or uncertain.
+
+## WorkflowGraph
+
+The root contains `schemaVersion: 1`, `workflowId`, optional `revision`, `entryNodeId`, `nodes` and `edges`.
+
+Each `WorkflowGraphNode` contains `id`, `name` (defaults to id), `description`, zero-based `order`, `startsRound`, `requires`, `provides`, `routes`, `incomingEdgeIds` and `outgoingEdgeIds`. Empty collections are arrays. The explicit entry cannot be inferred from incoming edges because loops may lead back to it.
+
+Each `WorkflowGraphRoute` contains zero-based `order`, optional `routeId`, `description` and `conditionId`, a `conditional` boolean, and `edgeId`. Order is matching priority. Export never calls `when` or `complete`.
+
+Each `WorkflowGraphEdge` contains `id`, `kind: transition | error | complete`, `sourceNodeId`, optional `targetNodeId`, `routeOrders` and optional `errorRouteId`. Routes with the same source, kind and target share one edge while retaining their individual orders. Recovery and normal edges remain separate. Completion has no target node. Recovery has an empty routeOrders array and takes errorRouteId from onErrorRouteId. IDs are deterministic JSON tuples `[sourceNodeId, kind, targetNodeId ?? null]`; consumers should treat them as opaque strings.
+
+Registration reads a routes getter exactly once and seals a copied snapshot. The getter must be pure and depend only on immutable definitions. Runtime conditions belong in `when`. Execution and graph export use the same snapshot. Export does not inspect function bodies or infer internal tool calls and custom subnodes.
+
+## WorkflowChain
+
+The root contains `schemaVersion: 1`, `workflowId`, `runId`, `nodes`, `transitions` and `coverage`. Nodes are sorted by first observed producerSequence, transitions by their original producerSequence.
+
+A `WorkflowChainNode` identifies one visit with `spanId` and `nodeId`, plus optional `workflowInvocationId`, `definitionRevision`, `name`, `description`, `kind` and `roundIndex`. Repeated visits and multiple Workflow invocations within one run stay separate. Historical nodes absent from the current graph remain in the chain. Descriptive fields come only from captured events, never from current definitions.
+
+Visit fields also include `firstEventSequence`, `lastEventSequence`, optional `enteredAtMs`, `endedAtMs`, `durationMs`, `usedModel`, and mandatory `status`, `events`, `subflow`. Time is epoch milliseconds. Sequence values are original producer values. Status is `running | success | error | cancelled | unknown` for this visit alone; recovery does not overwrite an error with success. Missing exits in a complete capture yield unknown; an entered visit in an incomplete live capture can remain running. TIMEOUT and CANCELLED map to cancelled.
+
+Each node event contains `eventId`, `producerSequence`, `occurredAtMs`, `type: enter | progress | transition | complete | error`, and optional `phase`, `routeId`, `conditionId`, `errorCode`, `errorEventId`, `payload`. Sub-step progress is represented by subflow rather than duplicated as ordinary progress.
+
+Each `WorkflowChainTransition` contains `eventId`, `producerSequence`, `occurredAtMs`, `type: transition | complete`, `sourceSpanId`, and optional `targetSpanId`, `targetNodeId`, `routeOrder`, `routeId`, `conditionId`, `errorEventId`. Only explicit handoff facts create connections. An error event with a recovery target also creates a transition, with eventId and errorEventId referencing that original error event. Neither adjacency nor timestamps imply a handoff. A selected targetSpanId does not prove that its entry was captured; missing target visits are reported.
+
+### Ordered subflow
+
+`WorkflowSubflowRecord` retains RecordedSubStep fields: `origin`, `stepId`, `operation`, `targetStepId`, `sequence`, `createdAtMs`, `revision`, `subnodeId`, `type`, `kind`, `name`, `status`, `usedModel`, `startedAtMs`, `endedAtMs`, `relatedDefinitionId`, `relatedInvocationId`, `parentStepId`, `nextStepIds`, `caseId`, `summary`, `payload`.
+
+Records stay in node-local sequence order. Every fix retains its own stepId and targetStepId; original writes are never overwritten. Repeated snapshots deduplicate by stepId within one span. Direct progress evidence adds `sourceEventId` and `producerSequence`. Records found only in later snapshots receive no fabricated emission sequence. Historical operation/createdAtMs/revision omissions remain absent and are reported. Metadata captures may omit name, kind, payload and other content.
+
+subnodeId and type are caller-defined strings. Records without subnodeId belong to the main node's own process. Core creates no subnodes array, implicit group, merged view or dependency between subnodes. Consumer DataModels choose grouping, fix projection, filtering and expansion. A group need not be contiguous or sequential.
+
+### Coverage
+
+`complete: boolean | 'unknown'` states source event coverage; projection issues downgrade it to false. `content: included | omitted | mixed | unknown` independently describes content capture. Omitted content does not imply missing events. Each issue has a `code` and optional `spanId`, `eventId`, `count`.
+
+Core issue codes are `conflicting-event`, `invalid-workflow-event`, `missing-node-id`, `conflicting-span`, `subflow-truncated`, `conflicting-subflow`, `invalid-subflow-progress`, `missing-enter`, `missing-exit`, `historical-subflow-fields`, `missing-target-enter`. Apps can supply additional read-side issue codes. Invalid v2 diagnostic envelopes throw through normalizeDiagnosticEvent rather than becoming apparently valid history.
+
+Readonly types are exported from the root, `/engine`, `/types`, and `/structs`. See the [symbol reference](reference.en.md).

package/development/docs/api/workflow-views.md

@@ -0,0 +1,78 @@
+# 工作流图与执行链
+
+`workflow.toGraph()` 返回注册定义的纯拓扑，`await workflow.toChain(runId)` 返回一次运行中该 Workflow 的实际节点执行。两者都是深度只读、可 JSON 序列化的数据，不包含 handler、条件函数、布局或渲染器。
+
+这两个接口用于开发审查、调试、观测界面和演示。导出不参与 Agent 的决策、调度或任务执行，不增加业务能力；执行链是既有记录的只读投影，不是重放或恢复入口。日志可由 App 授权接入复盘，图与执行链没有自动接入学习或规则修改。
+
+## 数据源与调用
+
+```ts
+const workflow = defineWorkflow({
+  id: 'assistant',
+  nodes,
+  chainSource: async runId => {
+    const capture = await authorizedRunReader.readAll(runId);
+    return { events: capture.events, coverage: capture.coverage };
+  },
+});
+const graph = workflow.toGraph();
+const chain = await workflow.toChain(runId);
+// 临时导出可传入本次专用数据源，不修改 Workflow。
+const exported = await workflow.toChain(runId, authorizedSource);
+```
+
+`chainSource: WorkflowChainSource` 是 App 的只读接口，接收 `runId`，返回 `Promise<{ events: readonly CoreDiagnosticRecord[]; coverage: WorkflowChainCoverage }>`。App 负责授权、账户隔离、存储路径解析、保留期、分页和读取边界。Core 不保存全局运行日志，也不从最近一次运行取得数据。`add()` 返回的新 Workflow 沿用绑定的数据源。
+
+空 runId 或未配置数据源抛出 `TypeError`；数据源读取错误原样传播；没有该 run／Workflow 的节点执行记录时抛出 `RangeError`。这与成功返回空图不同。读取期间 App 应返回一致快照，并对正在运行、缺失或无法证明完整的记录准确填写 coverage。
+
+## WorkflowGraph
+
+| 字段 | 类型与含义 |
+| --- | --- |
+| schemaVersion | `1` |
+| workflowId / revision | 定义 ID／可选定义版本 |
+| entryNodeId | 显式入口，不能用入边数推断 |
+| nodes | 按注册顺序排列的 `WorkflowGraphNode[]` |
+| edges | 按节点和路由声明顺序生成的 `WorkflowGraphEdge[]` |
+
+节点字段：`id`、`name`（未声明时为 id）、`description`、`order`（从 0 开始）、`startsRound`、`requires`、`provides`、`routes`、`incomingEdgeIds`、`outgoingEdgeIds`。空合同及边集合返回空数组。
+
+路由字段：`order`（节点内从 0 开始）、可选 `routeId`／`description`／`conditionId`、`conditional: boolean`、`edgeId`。路由顺序是匹配优先级；导图不执行 `when` 或 `complete`。
+
+边字段：`id`、`kind: 'transition' | 'error' | 'complete'`、`sourceNodeId`、可选 `targetNodeId`、`routeOrders: number[]`、可选 `errorRouteId`。同一源节点、种类、目标合成一条边，多条路由通过 `routeOrders` 保留；普通跳转与错误恢复分别成边。完成边没有目标节点；错误边的 routeOrders 为空，errorRouteId 来自 onErrorRouteId。边 ID 是稳定的 JSON 元组 `[sourceNodeId, kind, targetNodeId ?? null]`，使用方将其视为不透明字符串。
+
+注册时仅读取一次 `get routes()`，复制并封存路由。getter 必须是只依赖不可变定义的纯函数；运行条件应写在 `when` 中。执行与导图共享注册快照。导图不分析函数体，因此不包含节点内部工具调用或自定义子节点。
+
+## WorkflowChain
+
+| 字段 | 类型与含义 |
+| --- | --- |
+| schemaVersion | `1` |
+| workflowId / runId | 查询的 Workflow 与运行 ID |
+| nodes | 按首次观察的 producerSequence 排序的节点执行 |
+| transitions | 按 producerSequence 排序的真实跳转／完成事件 |
+| coverage | 完整性、内容策略与缺失诊断 |
+
+`WorkflowChainNode` 的身份是 `spanId`，另含 `nodeId`、可选 `workflowInvocationId`／`definitionRevision`／`name`／`description`／`kind`／`roundIndex`。同一节点的多次进入和同一 run 中多次调用 Workflow 均保留独立执行；历史或图外 nodeId 不丢弃，名称等只取历史日志，不从当前定义补齐。
+
+每次执行还包含 `firstEventSequence`、`lastEventSequence`、可选 `enteredAtMs`／`endedAtMs`／`durationMs`／`usedModel`、`status`、`events`、`subflow`。时间为 epoch 毫秒，序号保留原始 producerSequence，不重新编号。status 为 `running | success | error | cancelled | unknown`，只反映本节点，错误恢复跳转不把失败节点改成成功。完整记录缺少退出时返回 unknown；不完整快照中已经进入但尚未退出的节点为 running。TIMEOUT 与 CANCELLED 均为 cancelled。
+
+`events` 保存节点生命周期和普通 progress：`eventId`、`producerSequence`、`occurredAtMs`、`type: enter | progress | transition | complete | error`，以及可选 `phase`、`routeId`、`conditionId`、`errorCode`、`errorEventId`、`payload`。专用于 subStep 的 progress 归入 subflow，不重复记为普通 progress。
+
+`WorkflowChainTransition` 字段为 `eventId`、`producerSequence`、`occurredAtMs`、`type: transition | complete`、`sourceSpanId`，以及可选 `targetSpanId`、`targetNodeId`、`routeOrder`、`routeId`、`conditionId`、`errorEventId`。只有实际事件才生成连线，不按相邻顺序或时间猜测。错误事件声明恢复目标时也生成 transition，其 eventId 与 errorEventId 均关联该原始错误事件。targetSpanId 只是选择后继的证据，不代替后继 enter；缺失后继记录会进入 coverage。
+
+### 有序 subflow
+
+`subflow` 是按节点内 sequence 排列的原始日志。它保留 `RecordedSubStep` 字段：`origin`、`stepId`、`operation`、`targetStepId`、`sequence`、`createdAtMs`、`revision`、`subnodeId`、`type`、`kind`、`name`、`status`、`usedModel`、`startedAtMs`、`endedAtMs`、`relatedDefinitionId`、`relatedInvocationId`、`parentStepId`、`nextStepIds`、`caseId`、`summary`、`payload`。
+
+每次 fix 保留独立 stepId 和 targetStepId，不合并或改写原记录。重复事件快照按本次 spanId 内的 stepId 去重。直接捕获写入／修正 progress 时补充 `sourceEventId` 和 `producerSequence`；仅在后续快照找到的记录不伪造原始事件序号。旧日志缺失 operation／createdAtMs／revision 时保留缺失并报告 historical-subflow-fields；元数据日志允许 name／kind／payload 等内容字段缺失。
+
+subnodeId 和 type 由调用方定义；没有 subnodeId 的记录属于主节点自己的过程。Core 不生成 subnodes、默认分组、合并视图或子节点之间的连线。展示端可依自己的 DataModel 分组、投影多次 fix、过滤或展开；同组不保证连续，不推导串行或依赖。
+
+### Coverage
+
+`complete: boolean | 'unknown'` 表示数据源声明的事件覆盖；投影发现问题时降为 false。`content: included | omitted | mixed | unknown` 独立说明内容采集策略，未采集正文不等于事件丢失。`issues` 每项含 `code` 和可选 `spanId`／`eventId`／`count`。
+
+Core 会追加 `conflicting-event`、`invalid-workflow-event`、`missing-node-id`、`conflicting-span`、`subflow-truncated`、`conflicting-subflow`、`invalid-subflow-progress`、`missing-enter`、`missing-exit`、`historical-subflow-fields`、`missing-target-enter`。App 可附加自己的读取诊断码。当前 v2 诊断封装不合法时由 normalizeDiagnosticEvent 抛错；Core 不把不可解析的数据伪装成成功历史。
+
+精确的 readonly 类型通过根入口、`/engine`、`/types` 和 `/structs` 导出，见[公开符号参考](reference.md)。

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

@@ -176,7 +176,7 @@ Workflow uniformly handles identifier collisions and placeholders in existing co
 ## Node reports
 
 The Loop automatically records node entry, jumps, completion, and exceptions. When a node needs to add business details, it can provide
-`report(update, context)` in its definition, returning `{ usedModel, payload, subs }`, where every field is optional. `subs` is the `SubFlowLogger` instance provided by that execution context. This completion callback is called only when diagnostics allow content, and it reads a copy of the state update; a `usedModel` that must be retained in metadata mode should be submitted during the run through `context.report`.
+`report(update, context)` in its definition, returning `{ usedModel, payload }`, where every field is optional. Sub-logs use the execution-bound `context.createSubFlowLogger()`; write/fix commit immediately without returning or submitting the instance. This completion callback is called only when diagnostics allow content, and it reads a copy of the state update; a `usedModel` that must be retained in metadata mode should be submitted during the run through `context.report`.
 The Loop attaches this supplementary information to the node's completion or jump record. If reporting fails, the original node event is still recorded.
 
 
@@ -185,7 +185,7 @@ infers the output type from the object contract, and the same field also accepts
 
 ### Reports during node execution
 
-`run(state, context)` can call `context.report({ usedModel, payload, subs })` to report progress. usedModel is optional boolean metadata about this node itself and remains unknown when not reported; payload and subs are read only when content is allowed. subs must be the instance created by `context.createSubFlowLogger()` for this execution, and a hand-written array cannot be submitted. write records the intent first and returns an ID, fix adds later results, and readAll returns an immutable snapshot in a fixed format; writes and completions reuse the existing node.progress, and a short circuit or throw still preserves the start record already sent. Reports do not submit business state and do not determine routing; the Loop adds node identity, time, and event ordinal. Late writes are not accepted after cancellation or node completion. The node's `report(update, context)` at completion continues to serve supplementary reporting when content is allowed. For the contract, see [Child log instances](observability.md#sub-log-instances-and-record-first-then-complete).
+`run(state, context)` can call `context.report({ usedModel, payload })` to report progress. usedModel is optional boolean metadata about this node itself and remains unknown when not reported; payload is read only when content is allowed. `context.createSubFlowLogger()` returns the unique logger for this execution; write/fix commit automatically and readAll is a read-only query for any holder. write records the intent first and returns an ID, fix adds later results, and readAll returns an immutable snapshot in a fixed format; writes and completions reuse the existing node.progress, and a short circuit or throw still preserves the start record already sent. Reports do not submit business state and do not determine routing; the Loop adds node identity, time, and event ordinal. After cancellation or node completion, the detached logger returns write=-1 and fix=false without throwing; readAll remains readable. The node's `report(update, context)` at completion continues to serve supplementary reporting when content is allowed. For the contract, see [Child log instances](observability.md#sub-log-instances-and-record-first-then-complete).
 
 ## Node caches
 
@@ -196,3 +196,7 @@ context.cache belongs to the current node. Only get(key, { nodeId }) may read an
 Optional Engine option agentCache accepts an AgentCachePort. context.agentCache exposes asynchronous get/has/set/delete/clear, or is absent when no port is supplied. The App receives immutable addresses with nodeId, key, persistence and signal; clear receives an address without key. Port callbacks retain their receiver. Cancellation is checked before dispatch and after completion; it does not roll back an App write already started.
 
 Persistence defaults to false. Passing true requires supportsPersistence: true; otherwise the call rejects. Volatile and persistent spaces are independent, with no fallback or mirroring. The App owns capacity, TTL, serialization, user isolation and storage. Cache partitions are not authorization boundaries. Fork resume may explicitly return agentCache to restore a borrowed port; it is never inherited implicitly. Cache data is not checkpoint state or durable business evidence, and captured views must not be used after cancellation.
+
+## Developer aids: workflow graphs and execution chains
+
+These readonly exports do not participate in Agent scheduling or business execution. `toGraph()` exports registered topology; `toChain(runId)` aggregates observed main-node visits and retains ordered subflow records. See [Workflow graphs and execution chains](workflow-views.en.md) for fields, sources, coverage and consumer responsibilities.

package/development/docs/api/workflow.md

@@ -177,7 +177,7 @@ Workflow 统一处理已有配置中的标识冲突和占位符，缺失的标
 ## 节点报告
 
 Loop 自动记录节点进入、跳转、完成和异常。节点需要补充业务细节时，可在定义中提供
-`report(update, context)`，返回 `{ usedModel, payload, subs }`，各字段均可省略。`subs` 是该次执行上下文提供的 `SubFlowLogger` 实例。这个完成回调只在诊断允许内容时调用，读取的是状态更新的副本；需要在元数据模式下保留的 `usedModel` 应在运行中通过 `context.report` 提交。
+`report(update, context)`，返回 `{ usedModel, payload }`，各字段均可省略。子日志通过 `context.createSubFlowLogger()` 绑定当前执行，write／fix 自动实时入账，无需返回或提交实例。这个完成回调只在诊断允许内容时调用，读取的是状态更新的副本；需要在元数据模式下保留的 `usedModel` 应在运行中通过 `context.report` 提交。
 Loop 将这些补充信息附在节点的完成或跳转记录上。报告失败时，原节点事件仍然记录。
 
 
@@ -186,7 +186,7 @@ Loop 将这些补充信息附在节点的完成或跳转记录上。报告失败
 
 ### 节点运行中的报告
 
-`run(state, context)` 可调用 `context.report({ usedModel, payload, subs })` 报告进度。usedModel 是本次节点自身的可选布尔元数据，未上报保持未知；payload 和 subs 仅在内容获准时读取。subs 必须为 `context.createSubFlowLogger()` 创建的本次执行实例，不能提交手写数组。write 先记意图并返回 ID，fix 补后续结果，readAll 返回固定格式不可变快照；写入和补全复用现有 node.progress，短路或抛错也保留已送出的起始记录。报告不提交业务状态，也不决定路由；Loop 补齐节点身份、时间及事件序号。取消或节点结束后不接纳迟到写入。结束时的节点 `report(update, context)` 继续用于内容获准时的补充报告。合同见[子日志实例](observability.md#子日志实例与先记后补)。
+`run(state, context)` 可调用 `context.report({ usedModel, payload })` 报告进度。usedModel 是本次节点自身的可选布尔元数据，未上报保持未知；payload 仅在内容获准时读取。`context.createSubFlowLogger()` 创建本次执行唯一实例，write／fix 自动入账，无需在报告中提交；readAll 向任何实例持有者提供只读查询。write 先记意图并返回 ID，fix 补后续结果，readAll 返回固定格式不可变快照；写入和补全复用现有 node.progress，短路或抛错也保留已送出的起始记录。报告不提交业务状态，也不决定路由；Loop 补齐节点身份、时间及事件序号。取消或节点结束后 logger 解绑，write 返回 -1、fix 返回 false 且不报错，readAll 持续可读。结束时的节点 `report(update, context)` 继续用于内容获准时的补充报告。合同见[子日志实例](observability.md#子日志实例与先记后补)。
 
 ## 节点缓存
 
@@ -209,3 +209,7 @@ if (context.agentCache) {
 agentCache 每个操作默认 persistence: false；true 必须由 supportsPersistence: true 的 App 端口明确支持，否则拒绝。两种空间不回退、不镜像，delete／clear 仅影响指定空间及当前分区。App 负责容量、TTL、序列化、用户／租户隔离和持久化。节点分区不是授权边界，不复用权限结论。
 
 缓存不进入 checkpoint／状态／Durable 恢复。fork 的 resume 可显式返回 agentCache 重新绑定 App 端口；默认不继承。需要重放或持久业务事实的数据仍使用原 state 补丁或 App 存储。取消后不可继续使用捕获的节点缓存视图。
+
+## 开发辅助：工作流图与执行链
+
+这两个只读导出接口不参与 Agent 的实际调度或业务执行。`toGraph()` 导出注册拓扑，`toChain(runId)` 读取并聚合真实主节点执行，节点内部保留有序 subflow。字段、数据源、覆盖与展示边界见[工作流图与执行链](workflow-views.md)。

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 };
+}