@jangts/agent-core 0.3.5 → 0.5.0

package/development/docs/api/configuration-in-workflow.md

@@ -0,0 +1,403 @@
+# 从完整代码看懂独立配置与关联配置
+
+Tool 是供模型选择和提交参数的接口。ExecutableTool 增加授权、执行和输出校验，Tool 增加一个 lifecycle 生命周期块。Intent 只是 Tool 的用途标记和专门描述，没有独立 ID 或注册表。下面使用公开的内存笔记与离线 Provider 展示完整流程。
+
+```text
+Tool declaration → node selects tools → model proposes name and arguments
+→ schema / activation / authorization → execute → validated result
+```
+
+## 1. 执行 Tool：参数、授权、处理与结果校验
+
+[tools.mjs](../examples/registration/tools.mjs)
+
+```js
+/** 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;
+      },
+    },
+  ];
+}
+```
+
+## 2. 独立配置：分别声明模型接口和执行合同
+
+[independent.mjs](../examples/registration/independent.mjs)
+
+模型声明只生成 `{ toolId, input }` 提议，不直接执行业务。执行目录另行绑定本次请求的应用上下文。
+
+```js
+/** 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 };
+}
+```
+
+## 3. 关联配置：一份声明提供模型视图与执行入口
+
+[associated.mjs](../examples/registration/associated.mjs)
+
+目录从同一 Tool 推导名称、描述、Schema 和调用映射，省掉独立写法中的重复声明；授权与执行校验仍走原通道。
+
+```js
+/** 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 };
+}
+```
+
+## 4. 工作流：节点如何装配上下文、调用模型和执行提议
+
+[workflow.mjs](../examples/registration/workflow.mjs)
+
+```js
+/** One runtime for both configuration styles; its Provider is a fixed offline fixture. */
+import { AgentCoreEngine, Support, defineWorkflow, route } from '@jangts/agent-core';
+
+const context = Support.defineContextFragments(
+  [
+    {
+      id: 'task-policy',
+      sourceId: 'tutorial',
+      trust: 'instruction',
+      lifetime: 'configuration',
+      role: 'system',
+      maxChars: 500,
+      format: () => '按用户需求选择一个已提供的能力并提交参数。操作结果由程序返回。',
+    },
+    {
+      id: 'tool-catalog',
+      sourceId: 'tool-registry',
+      trust: 'server',
+      lifetime: 'step',
+      role: 'user',
+      maxChars: 6000,
+      format: ({ tools }) => ({ tools: [...tools.values()].map(({id, description}) => ({id, description})) }),
+    },
+    {
+      id: 'question',
+      sourceId: 'user-message',
+      trust: 'user',
+      lifetime: 'turn',
+      role: 'user',
+      maxChars: 1000,
+      format: ({ question }) => ({ question }),
+    },
+  ],
+  { maxInputChars: 8000 },
+);
+
+/** Stage policy selects candidates; association does not automatically submit every registration. */
+export function taskTransport(tools, toolIds = ['search_notes', 'read_note']) {
+  return Support.createStageModelTransport({
+    id: 'task',
+    tools,
+    stages: [{ id: 'choose-operation', toolIds }],
+  });
+}
+
+const workflow = defineWorkflow({
+  id: 'notes-request',
+  nodes: [
+    {
+      id: 'decide',
+      description: '组织上下文，让模型提出一次操作',
+      async run(state, { model, app }) {
+        const input = context.build({
+          input: {
+            question: state.question,
+            tools: app.tools,
+          },
+        });
+        const { value: proposal } = await model.invoke({
+          stageId: 'choose-operation',
+          transport: 'task',
+          input,
+        });
+        return { proposal };
+      },
+      routes: [route.to('execute')],
+    },
+    {
+      id: 'execute',
+      description: '经过工具合同执行提议，取得真实结果',
+      async run(state, { tools }) {
+        const { value: result } = await tools.invoke(state.proposal);
+        return { result };
+      },
+      routes: [route.deliver('result')],
+    },
+  ],
+});
+
+/** The chosen reply is fixture input, not a language-understanding implementation. */
+export async function runCase(configuration, question, proposedName, proposedInput) {
+  const submitted = [];
+  const provider = {
+    async *stream(messages, { options }) {
+      submitted.push({ messages, functions: options.functions });
+      if (!options.functions.some((fn) => fn.name === proposedName)) {
+        throw new Error('Fixture attempted an unavailable capability');
+      }
+      yield {
+        type: 'function-call-delta',
+        index: 0,
+        id: 'offline-call',
+        name: proposedName,
+        arguments: JSON.stringify(proposedInput),
+      };
+    },
+  };
+  const agent = new AgentCoreEngine({
+    workflow,
+    app: { tools: configuration.tools },
+    tools: configuration.execution.bind({ app: {} }),
+    model: {
+      provider,
+      transports: [taskTransport(configuration.tools, configuration.candidateIds)],
+      maxCalls: 1,
+    },
+  });
+  return { result: await agent.run({ question }), submitted };
+}
+```
+
+## 5. 另一种模型协议：name/input 包装复用同一执行合同
+
+[protocol.mjs](../examples/registration/protocol.mjs)
+
+```js
+/** 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'],
+  };
+}
+```
+
+## 6. 离线验证：两种配置的模型请求与执行结果相同
+
+[run.mjs](../examples/registration/run.mjs)
+
+```js
+/** 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.');
+```
+
+## 需求识别用途与激活条件
+
+```ts
+const tools = Support.defineModelTools([{
+  id: "manage_memo",
+  description: "Process a memo draft and check conflicts",
+  inputSchema: memoSchema,
+  asIntent: {
+    description: "The user wants to remember something or set a reminder",
+    when: context => context.features.memos,
+  },
+  active: context => context.services.memos != null,
+  resolve: input => input,
+}]);
+const candidates = tools.withIntent(context);
+const known = tools.select(["manage_memo"], context);
+```
+
+`asIntent` 接受 `true`、描述、布尔判断函数或 `{ description?, when?, delegates? }`。省略不参与需求识别；`active` 省略表示激活。两种选取方式均检查激活条件，专门描述只作用于当前视图。delegates 可选，表示允许集合而不是顺序，由领域注册器校验词汇；不会产生 Intent ID 或跨 Tool 描述聚合。
+
+## 装饰器配置
+
+```ts
+@Intent({ description: "Accept memo requests", delegates: ["read", "final"] })
+@WorkflowTool("manage_memo", { ns: "assistant" })
+class MemoTool {
+  description = "Process a memo request";
+  inputSchema = memoSchema;
+  resolve(input) { return input; }
+}
+```
+
+装饰器从 `@jangts/agent-core/support/decorators` 导入。`@WorkflowTool` 与 `@WorkflowNode` 一样支持类和公开实例方法。`@Intent` 单独挂在同一目标上，单用不注册；Tool 装饰器及其定义不接收 asIntent。关联不依赖装饰器顺序。
+
+## 运行示例
+
+```sh
+node packages/agent-core/development/docs/examples/registration/run.mjs
+```
+
+离线 fixture 验证接线和合同等价，不证明自然语言识别或真实供应商表现。Cafe 保留目标和下一步一次提交的分组协议，goal 指向 GoalTool；Banker 将本轮 Tool 候选投影到 name/input 协议。两端复用相同 Tool 合同，不强求同一种业务工作流。

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

@@ -44,14 +44,14 @@ Budgets default to the current modelRunnerDefaults: maxCalls=8, callTimeoutMs=30
 Input messages contain fields such as role/content/images, and images in read-only input are retained with the message. remainingCalls, signal, and journal can be read directly; call counts use callCount/totalCallCount. lastCall is a read-only snapshot of the previous completed record and is not a basis for concurrent correlation. Selection and compression nodes share counts through the same model port. A single runner executes one call at a time; concurrent tasks each use a child runner, and each returned value is correlated by its own invocation.
 
 ```ts
-interface ModelCapability<Input, Output = Input> {
+interface BaseTool<Input, Output = Input> {
   readonly id: string;
   readonly description: string;
   readonly inputSchema: SchemaAdapter<Input>;
   resolve(input: Input, context: Readonly<{ stageId: string }>): Output;
 }
 interface ModelSelection {
-  readonly capabilityId: string;
+  readonly toolId: string;
   readonly input: unknown;
 }
 interface ModelTransportDefinition<Output> {
@@ -62,11 +62,11 @@ interface ModelTransportDefinition<Output> {
 
 PreparedModelTransport<Output> is the unified transport preparation contract: options, schemaChars, optional instruction, and createResponse(). The returned collector has outputChars, push(part), and finish(): Output; the text collector accumulates and rejects function-call parts, and the structured collector returns a result only after full parsing. A collector is a new instance per call and does not reuse state across requests. PreparedModelInteraction is used for structured adapter composition, while text transports implement the generic collection contract directly.
 
-ModelCapability uses inputSchema.parse to parse capability parameters and resolve(input, { stageId }) to produce a typed stage result. resolve runs synchronously; a mistakenly returned thenable is rejected, and it neither executes tools nor authorizes. ModelCapabilitySource.resolve(selection, context) first verifies the IDs available in this stage, then parses, converts, and runs the declared refine checks.
+BaseTool uses inputSchema.parse to parse capability parameters and resolve(input, { stageId }) to produce a typed stage result. resolve runs synchronously; a mistakenly returned thenable is rejected, and it neither executes tools nor authorizes. ModelToolSource.resolve(selection, context) first verifies the IDs available in this stage, then parses, converts, and runs the declared refine checks.
 
 Core reads outputChars after the collector factory returns, after each push, and after finish: the value must be a non-negative safe integer, and NaN, Infinity, negative numbers, and fractions are rejected as protocol errors. maxOutputChars may be explicitly set to Infinity, but that does not relax the collector counting contract. Diagnostics keep the peak of each valid observation, and finish may release or normalize internal buffers; buffers are not required to grow indefinitely.
 
-Native interaction accepts a string or a valid function-call-delta. A function part must be a non-array object with index 0; id, when provided, must be a non-empty string, and name and arguments, when provided, must be strings. Conflicting IDs, multiple calls, unregistered capabilities, mixed body text, or incomplete arguments are rejected, and no tool is executed.
+Native interaction accepts a string or a valid function-call-delta. A function part must be a non-array object with index 0; id, when provided, must be a non-empty string, and name and arguments, when provided, must be strings. Conflicting IDs, multiple calls, unregistered tools, mixed body text, or incomplete arguments are rejected, and no tool is executed.
 
 Optional call metadata on the collector is read only once on a best-effort basis; a throwing getter does not overwrite an obtained business result, the original error, or cancellation, nor does it block the model.end wrap-up. outputChars is an execution-validated field and is exempt from this tolerance rule.
 
@@ -89,7 +89,7 @@ Preparation fixes the instruction, Schema, options, and collector factory receiv
 
 Measurement returns `ModelInputMeasurement` with body messageChars, added instructionChars, out-of-message declaration schemaChars, transport budget usage transportChars, the actual total inputChars, the effective limit, and withinBudget. It is not a budget reservation or a pass: the final input is still measured and validated again before the Provider. A handle belongs only to the Runner/Workflow request that prepared it, can be consumed once, and cannot replace stageId, transport, or the output reservation. Cancellation, expiry, foreign handles, and reuse are rejected; a pre-check rejection still consumes no model calls.
 
-The final call fixes a snapshot of message role, content, and images before the first asynchronous wait, and budgeting, token counting, and Provider sending share that snapshot; the caller modifying the original object afterwards does not rewrite the request. prepare fixes the set of capability IDs for this preparation, and capabilities registered later are available only to new preparations.
+The final call fixes a snapshot of message role, content, and images before the first asynchronous wait, and budgeting, token counting, and Provider sending share that snapshot; the caller modifying the original object afterwards does not rewrite the request. prepare fixes the set of capability IDs for this preparation, and tools registered later are available only to new preparations.
 
 Character budgets accept only non-negative safe integers or Infinity; a budget carried by BuiltContext must pass the same validation and can only narrow the Runner upper limit. NaN, missing budgets, fractions, and other invalid values are rejected before billing and Provider calls, and measurement and actual execution use the same judgment.
 
@@ -221,10 +221,10 @@ isResult only answers with a boolean; if a resumable business check is needed, t
 
 ## ToolRegistry and ToolRuntime
 
-The low-level ToolRegistry in Core can take hand-written ExecutableTool implementations; Support's ToolRuntime comes from typed tool catalogs. Both reuse the same real invocation mechanism.
+The low-level ToolRegistry in Core can take hand-written ErasedTool implementations; Support's ToolRuntime comes from typed tool catalogs. Both reuse the same real invocation mechanism.
 
 ```ts
-interface ExecutableTool {
+interface ErasedTool {
   readonly id: string;
   readonly kind: string;
   parseInput(input: unknown): unknown;

package/development/docs/api/core.md

@@ -44,14 +44,14 @@ const b = await runner.invoke({ input: '你好' });
 输入消息包含 role/content/images 等字段，只读输入中的图片会随消息保留。remainingCalls、signal、journal 可直接读取；调用计数使用 callCount／totalCallCount。lastCall 是上一条完成记录的只读快照，不作为并发关联依据。选择／压缩节点通过同一模型端口共享计数。同一个 runner 同时执行一次调用；并发任务分别使用子 runner，各返回值以自己的 invocation 关联。
 
 ```ts
-interface ModelCapability<Input, Output = Input> {
+interface BaseTool<Input, Output = Input> {
   readonly id: string;
   readonly description: string;
   readonly inputSchema: SchemaAdapter<Input>;
   resolve(input: Input, context: Readonly<{ stageId: string }>): Output;
 }
 interface ModelSelection {
-  readonly capabilityId: string;
+  readonly toolId: string;
   readonly input: unknown;
 }
 interface ModelTransportDefinition<Output> {
@@ -62,11 +62,11 @@ interface ModelTransportDefinition<Output> {
 
 PreparedModelTransport<Output>为统一的传输准备合同：options、schemaChars、可选instruction、createResponse()。返回的collector具有outputChars、push(part)及finish(): Output；文本collector累积并拒绝函数调用分片，结构化collector完整解析后才返回结果。collector是每次调用新建的实例，不复用跨请求状态。PreparedModelInteraction 供结构化适配组合使用，文本传输直接实现通用收集合同。
 
-ModelCapability 使用 inputSchema.parse 解析能力参数，使用 resolve(input, { stageId }) 生成类型化阶段结果。resolve 同步执行，误返 thenable 时拒绝，不执行工具或授权。ModelCapabilitySource.resolve(selection, context) 先核对本阶段可用 ID，再解析、转换并执行已声明的 refine 检查。
+BaseTool 使用 inputSchema.parse 解析能力参数，使用 resolve(input, { stageId }) 生成类型化阶段结果。resolve 同步执行，误返 thenable 时拒绝，不执行工具或授权。ModelToolSource.resolve(selection, context) 先核对本阶段可用 ID，再解析、转换并执行已声明的 refine 检查。
 
 Core 在 collector 工厂返回后、每次 push 后和 finish 后读取 outputChars：值必须是非负安全整数，NaN、Infinity、负数和小数均按协议错误拒绝。maxOutputChars 可以显式设为 Infinity，但不放宽 collector 计数合同。诊断保留各次有效观测的峰值，finish 可释放或规范化内部缓冲，不要求缓冲一直增长。
 
-原生交互接收字符串或合法的 function-call-delta。函数分片必须是非数组对象，index 为 0；id 提供时必须是非空字符串，name 和 arguments 提供时必须是字符串。冲突 ID、多个调用、未登记能力、混合正文或不完整参数被拒绝，不执行工具。
+原生交互接收字符串或合法的 function-call-delta。函数分片必须是非数组对象，index 为 0；id 提供时必须是非空字符串，name 和 arguments 提供时必须是字符串。冲突 ID、多个调用、未登记能力、混合正文或不完整参数被拒绝，不执行工具。需要正文 + 多调用时使用 `Support.createSessionModelTransport`；它复用同一聚合 collector，但不改变原生交互的单提案合同。
 
 collector 可选 call 元数据只尽力读取一次；getter 抛错不覆盖已取得的业务结果、原始错误或取消，也不阻止 model.end 收尾。outputChars 是执行校验字段，不适用这个容错规则。
 
@@ -221,10 +221,10 @@ isResult只回答boolean；若需可恢复业务检查，App在流程节点中
 
 ## ToolRegistry 和 ToolRuntime
 
-Core低层ToolRegistry可以接手写ExecutableTool；Support的ToolRuntime来自类型化工具目录。两者复用同一个真实调用机制。
+Core低层ToolRegistry可以接手写ErasedTool；Support的ToolRuntime来自类型化工具目录。两者复用同一个真实调用机制。
 
 ```ts
-interface ExecutableTool {
+interface ErasedTool {
   readonly id: string;
   readonly kind: string;
   parseInput(input: unknown): unknown;

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

@@ -81,3 +81,23 @@ agent/model ids are registration keys, not Core branch, model or transport ident
 A routes getter may return `when: state => this._ready(state)` and `complete: state => this._reply(state)`. Workflow assembly reads and snapshots the table, potentially reading the getter multiple times. Keep getters pure and independent of request state. After state patches commit, route callbacks receive the latest state and can call private helpers. The getter is not re-evaluated each run; do not store request state on shared nodes.
 
 ESM/CJS module copies share roots within one JavaScript realm. Processes, workers and separate realms do not share roots. Independently evaluated classes registering the same kind, namespace and id reject rather than merge. Explicitly retain definition modules in the bundle: discarded side-effect-only imports cannot guarantee registration. Shared definitions must not retain request identity, signal or budget. Reading is neither execution nor authorization.
+
+## WorkflowTool and Intent
+
+WorkflowTool and WorkflowNode are explicit names for the tool and node decorators. WorkflowTool supports definition classes and public instance methods. A model-only Tool provides inputSchema and resolve; an executable Tool additionally provides kind, authorize, execute and parseOutput. The same pool stores their normalized definitions.
+
+```ts
+import { WorkflowTool, Intent, toolPool } from '@jangts/agent-core/support/decorators';
+import { Support } from '@jangts/agent-core';
+
+@Intent('The user wants to remember something')
+@WorkflowTool('memo', { ns: 'assistant' })
+class MemoTool {
+  description = 'Accept a memo draft';
+  inputSchema = memoSchema;
+  resolve(input) { return input; }
+}
+const candidates = Support.defineModelTools(toolPool.getAll('assistant')).withIntent(context);
+```
+
+Intent accepts no argument, a description, a synchronous boolean predicate, or `{ description?, when?, delegates? }`. It must decorate the same target as WorkflowTool and has no independent ID. Alone it registers nothing. Either decorator order works. Do not pass asIntent in WorkflowTool options or define it on the decorated class; use the separate Intent decorator. Explicit object configuration continues to support asIntent.

package/development/docs/api/decorators.md

@@ -106,3 +106,23 @@ Workflow 装配时读取并固定路由表；getter 应无副作用，不依赖
 agent／model 的 id 是辅助登记键，不覆盖 Core 分支、模型或 transport 身份。工具复用原 defineTool 校验；Workflow 复用原图校验，节点在完整图中验证；fragment 复用原 builder 的 formatter 检查，数据、信任与预算保持原合同；model 复用原配置快照验证，不消耗模型调用。辅助层不公开 metadata＋普通函数转换入口，顶层函数直接填入原 options。
 
 同一 JavaScript realm 内 ESM／CJS 副本共享池；不同进程、Worker 或独立 realm 不共享。两次独立加载并装饰同命名空间同 id 的类仍会重名拒绝，不自动合并。定义模块必须被打包图明确保留；被 tree-shaking 删除的纯副作用导入不能保证登记。共享定义不能保存请求身份、signal 或请求预算；池读取不是执行或授权。
+
+## WorkflowTool 与 Intent
+
+WorkflowTool、WorkflowNode 分别是 tool、node 的明确命名入口。WorkflowTool 支持定义类与公开实例方法。模型 Tool 提供 inputSchema 和 resolve；执行 Tool 另外提供 kind、authorize、execute 和 parseOutput。归一化定义进入同一个 toolPool。
+
+```ts
+import { WorkflowTool, Intent, toolPool } from '@jangts/agent-core/support/decorators';
+import { Support } from '@jangts/agent-core';
+
+@Intent('用户希望记录事情或设置提醒')
+@WorkflowTool('memo', { ns: 'assistant' })
+class MemoTool {
+  description = '接收备忘草案';
+  inputSchema = memoSchema;
+  resolve(input) { return input; }
+}
+const candidates = Support.defineModelTools(toolPool.getAll('assistant')).withIntent(context);
+```
+
+Intent 支持无参数、描述字符串、同步布尔判断函数或 `{ description?, when?, delegates? }`。必须与同一目标的 WorkflowTool 配合，没有独立 ID，单用不注册；两者书写顺序均可。WorkflowTool 参数和被装饰类中不提供 asIntent，使用独立 Intent 装饰器；普通配置对象仍支持 asIntent。

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

@@ -66,7 +66,7 @@ const readNote = Support.defineTool({
 
 const catalog = Support.defineToolCatalog([readNote]);
 const transport = Support.createModelTransport({
-  id: 'note-selection', capabilities: catalog.capabilities,
+  id: 'note-selection', tools: catalog.tools,
 });
 ```
 

package/development/docs/api/examples.md

@@ -66,7 +66,7 @@ const readNote = Support.defineTool({
 
 const catalog = Support.defineToolCatalog([readNote]);
 const transport = Support.createModelTransport({
-  id: 'note-selection', capabilities: catalog.capabilities,
+  id: 'note-selection', tools: catalog.tools,
 });
 ```
 

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

@@ -2,13 +2,15 @@
 
 [Shared types](types.md) · [Back to home](README.md). Each Kit is imported by named function／constructor from its own subpath, with static declarations separated from the per-run context.
 
-## Intents, Interaction, Tools
+## Domain Tools, Scope, Interaction, Tools
+
+IntentRegistry registers ModelTool-derived IntentTool declarations, preserving scope/target policies and task constraints. `asIntent.delegates` overrides derived delegates; delegates are optional allowed sets, not a sequence. There is no independent Intent entity or Intent ID. Scope goalIds reference actual Tool IDs. Import the optional registry helpers from `@jangts/agent-core/kits/domains`.
 
 | Capability | Preferred interface／key contract |
 | --- | --- |
 | IntentRegistry | Defines the primary key id, uses scopePolicy/targetPolicy, implements the shared Registry contract |
-| ScopeRegistry | id, intentIds, toolIds, queryScopeIds, knowledgeTopicIds; aliases are retained, and query methods use scopeId |
-| defineAgentCatalog | Projects relationships from actual registrations; the current task is `{ intentId, scopeId? }`, and scope cannot be used for both policy and reference |
+| ScopeRegistry | id, goalIds, toolIds, queryScopeIds, knowledgeTopicIds; aliases are retained, and query methods use scopeId |
+| defineAgentCatalog | Projects relationships from actual registrations; the current task is `{ goalId, scopeId? }`, and scope cannot be used for both policy and reference |
 | defineInteractionProtocol | One commands declaration compiles the protocol; commandField is owned by the App, which is not forced to name its wire field type or kind |
 | defineCommandCatalog | The closed commands set may be written as a Record; the public definitions are an array, and toRecord() is the explicit mapping |
 | bindInteraction | Aligns protocol with named handlers; dispatch(input, context) never executes unregistered commands |
@@ -20,7 +22,7 @@ When the complete list is available at construction time, use IntentRegistry.cre
 
 InteractionProtocol and CommandCatalog are public constructors; Interaction and Interaction.Commands provide their namespace entries respectively.
 
-The Tools Kit preserves the real order: global check → selected check → authorization → resume/execute → completion → finalize. Lifecycle and contribution are local protocols of this Kit. The receiver field is called receiver and is not conflated with OutputField.owner; the in-request journal reuses the invocationId allocated by Core.
+The Tools Kit preserves the real order: global check → authorization → resume/execute → completion → finalize. Each tool declares one lifecycle block: hooks such as inspect and finalize run for every tool, while id/protocol/call and authorize/resume/complete run only for the selected tool. The receiver field is called receiver and is not conflated with OutputField.owner; the in-request journal reuses the invocationId allocated by Core.
 
 ## Evidence and Retrieval
 
@@ -72,6 +74,22 @@ A TextSkill definition uses id, entry, toolIds, and kind=text-workflow. Catalog
 
 TextSkillLoader accepts load({ entries }, { read }). Registration ID, path, tool reference, and duplicate checks precede reading the corresponding file, and both read and custom parsers must be synchronous. The read port, registration entries, and error factory may be implemented by a class, and prototype getters and original method receivers are preserved. App-owned fields in tool receipts are projected explicitly by the App.
 
+## TextBlocks
+
+```ts
+interface TextBlock {
+  readonly number: number
+  readonly text: string
+  readonly start: number
+  readonly end: number
+}
+TextBlocks.split(text, { targetChars }): readonly TextBlock[]
+```
+
+`split` only processes decoded plain text: headings and horizontal rules start a new block, blank lines end the current one, and other lines break at line boundaries once `targetChars` would be exceeded. A single over-long line stays one block so paging can cut it into fragments later without turning one line into unrelated sections. Blocks reassemble into the original text exactly, including whitespace and CRLF; `number` starts at 1 and `start`／`end` are UTF-16 offsets in the source. `targetChars` must be a positive integer, and empty text returns an empty array.
+
+The Kit does not read files, page, call models or touch storage; paging windows, indexing, summaries and prompts remain App decisions. Block boundaries follow structure rather than a fixed character window, so use `start`／`end` when reporting coverage.
+
 ## TextSearch, VectorSearch, RRF, ModelCalls
 
 ```ts