@jangts/agent-core 0.3.6 → 0.5.0

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 本文件记录 `@jangts/agent-core` 的行为变更。接口合同与使用方式见[API 手册](development/docs/api/README.md)。
 
+## 0.5.0
+
+- Add the optional `TextBlocks` Kit: structure-aware splitting of long plain text into numbered blocks with source offsets and exact reassembly; paging, search, storage and prompts stay with the App.
+- Reject mutable context fragments whose declared field set changes through a `null` value, and merge tool model fields as own data properties so `__proto__`-like keys cannot rewrite the merged prototype.
+- Keep Kit implementations out of Core barrels: `/context` and the capability registration surface expose Core helpers only, while Kit helpers remain available from `/kits/*` and the documented root convenience surface. Remove the unused execution barrel.
+- Make `@jangts/mock-gpt` an optional peer dependency used only by the `/mock` entries instead of a production dependency; install it explicitly to use those entries.
+- Support native tool threads in Core: `ModelMessage` accepts assistant `toolCalls` and `role: 'tool'` results; preparation preserves and counts them, and `ModelCallTrace.calls` records every completed call while `functionCall` keeps its single-call meaning.
+- Add the opt-in `Support.createSessionModelTransport`: one response may contain prose and several tool calls. The resolved `toolId` / `input` / `problem` fields live in Support; Core only exposes raw `ModelSessionResult`. `nativeFunctionInteraction` and its single-proposal contract remain unchanged.
+- Keep the Core `/model` barrel free of Support implementations; named Support exports remain available from the package root and `/support`.
+- Keep Kits available from the root convenience surface and from `/kits` / `/kits/*` subpaths. Kits remain optional, not restricted; Apps may use whichever entry is convenient.
+- Add `ModelOptions.toolChoice` and `parallelToolCalls`, including `'omit'` for leaving the wire field out; defaults keep `tool_choice: 'required'` and `parallel_tool_calls: false`.
+- Unify model interfaces as ModelTool and ModelToolRegistry; transports use tools / toolIds, selections use toolId, and the JSON adapter uses a name/input envelope. Skip the 0.4 series.
+- Add asIntent discovery metadata and active conditions, with node-owned withIntent(context) and explicit selection. Intent has no independent identity or aggregation registry.
+- Preserve executable, lifecycle, domain-policy and preview extensions. Derive model interfaces from executable tools without parsing business arguments twice; retain authorization, cancellation, budgets and receipts.
+- Add WorkflowTool / WorkflowNode names and separate Intent decorators for classes and methods, with order-independent ESM/CJS metadata. Tool decorators reject inline asIntent.
+- Retain explicit owner-to-tool associations and local provenance without transmitting registration sources to the model. Domain delegates remain allowed sets with optional explicit overrides.
+- Add one optional `lifecycle` block per tool in place of separate invocation and contribution objects, and one optional `delegate` field that claims a dispatch id. The registry keeps a unique `delegateId → tool` index, so `call(next, context)` stays the single dispatch path; `inspect` runs once for every tool and the remaining selected-only hooks run for the tool that owns the decision.
+- Rename request-tool vocabulary to goals across the domain catalog: ports use `goalIds`/`goals`, projections expose `goalCatalog`/`goalDelegates`, and the model catalog returns `availableGoalIds`/`availableGoals`.
+- Name lifecycle dispatch by `lifecycle.id`; `ToolsOptions.invocationId(decision)` selects the handler, `call(next, context)` routes on `next.type`, and the missing-handler factory is `unavailableInvocation(invocationId)`. No `step` field remains in the lifecycle contract.
+
 ## 0.3.6
 
 - Preserve explicit recovery targets from workflow error events as execution-chain transitions linked to the original errorEventId.

package/README.md

@@ -127,14 +127,14 @@ console.log(result.value); // 42
 
 Reuse static tool definitions and bind request dependencies and cancellation with `catalog.bind({ app, execution })`. Successful tool invocation also returns `{ value, invocation }`.
 
-To let the model select a tool, append this to `tools.mjs` and use the `provider.mjs` above. The same catalog supplies model capabilities and actual execution:
+To let the model select a tool, append this to `tools.mjs` and use the `provider.mjs` above. The same catalog supplies model tools and actual execution:
 
 ```js
 import { ModelRunner } from '@jangts/agent-core';
 import { provider } from './provider.mjs';
 
 const selection = Support.createModelTransport({
-  id: 'choose-tool', capabilities: catalog.capabilities,
+  id: 'choose-tool', tools: catalog.tools,
 });
 const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
 const proposal = await runner.invoke({
@@ -217,7 +217,7 @@ Workflow `context.cache` provides synchronous Engine-lifetime memory partitioned
 | Integrate with a development agent | [Agent-assisted development and Skill](https://agent-core-docs.pages.jangts.cafe/en/manual/agent-development.html) |
 | Exact signatures, overloads and result types | [API directory](https://agent-core-docs.pages.jangts.cafe/en/api/) · [Local API handbook](development/docs/api/README.en.md) |
 
-Import Core and Support from the package root, Kits from `/kits/<name>`, and decorators from `/support/decorators`. App owns identity, business permissions, external effects and storage; Core provides generic runtime guarantees. Support and Kits remain optional.
+Import Core and Support from the package root, Kits from `/kits/<name>`, and decorators from `/support/decorators`. App owns identity, business permissions, external effects and storage; Core provides generic runtime guarantees. Support and Kits remain optional. The `/mock`, `/mock/node` and `/mock/web` entries require installing `@jangts/mock-gpt`, which is an optional peer dependency and is not installed with this package.
 
 ## License
 
@@ -359,7 +359,7 @@ import { ModelRunner } from '@jangts/agent-core';
 import { provider } from './provider.mjs';
 
 const selection = Support.createModelTransport({
-  id: 'choose-tool', capabilities: catalog.capabilities,
+  id: 'choose-tool', tools: catalog.tools,
 });
 const runner = new ModelRunner({ provider, transports: [selection], maxCalls: 1 });
 const proposal = await runner.invoke({
@@ -442,7 +442,7 @@ console.log(snapshot);
 | 让开发 Agent 辅助接入 SDK | [Agent 辅助开发与 Skill](https://agent-core-docs.pages.jangts.cafe/zh/manual/agent-development.html) |
 | 查精确参数、重载和返回值 | [API 目录](https://agent-core-docs.pages.jangts.cafe/zh/api/) · [本地 API 手册](development/docs/api/README.md) |
 
-Core 与 Support 从包根导入，Kit 从 `/kits/<name>` 导入，装饰器从 `/support/decorators` 导入。App 拥有身份、业务权限、外部副作用和存储；Core 提供通用运行保证，Support 与 Kit 按需使用。
+Core 与 Support 从包根导入，Kit 从 `/kits/<name>` 导入，装饰器从 `/support/decorators` 导入。App 拥有身份、业务权限、外部副作用和存储；Core 提供通用运行保证，Support 与 Kit 按需使用。`/mock`、`/mock/node`、`/mock/web` 需要另行安装 `@jangts/mock-gpt`；它是可选 peer 依赖，不会随本包自动安装。
 
 ## 许可
 

package/development/docs/README.en.md

@@ -51,11 +51,11 @@ Names, parameters, and conclusions proposed by the model are not authentication,
 - **Basic run**: the Provider's model connection and the actual input. Core provides the default budget, single-call timeout, signals, and plain text transport; override as needed.
 - **When enabling tools**: the business implementation plus the required identity, access control, parameter, and result constraints.
 - **When enabling persistence**: sources, user ownership, storage and retention policy, and failure recovery.
-- **When enabling complex orchestration**: associations among declared nodes, tools, model capabilities, knowledge, checks, and output.
+- **When enabling complex orchestration**: associations among declared nodes, tools, model tools, knowledge, checks, and output.
 
 No default need to enable long-term memory, user profiles, experience libraries, vector databases, or dynamic tool loading. Deliver a read-only, single-round App with explicit sources first, then integrate each item according to real requirements.
 
-## Provided versus still-App-owned capabilities
+## Provided versus still-App-owned tools
 
 | Provided by the library | Still to be implemented by the App |
 | --- | --- |

package/development/docs/acceptance.en.md

@@ -2,7 +2,7 @@
 
 [Back to development handbook](README.md) · [API reference](api/README.md)
 
-The following are the evidence expected for an integration, chosen by developers according to the capabilities actually enabled; they are not a full command suite to run on every change. Review what the source can confirm first, and run the minimum relevant checks when a concrete question exists. Success with an offline stand-in does not prove real model behavior, and being executable by the framework does not prove the business facts are correct.
+The following are the evidence expected for an integration, chosen by developers according to the tools actually enabled; they are not a full command suite to run on every change. Review what the source can confirm first, and run the minimum relevant checks when a concrete question exists. Success with an offline stand-in does not prove real model behavior, and being executable by the framework does not prove the business facts are correct.
 
 | Boundary | What should be proven | Minimal example |
 | --- | --- | --- |
@@ -21,7 +21,7 @@ The following are the evidence expected for an integration, chosen by developers
 
 When long-term memory is chosen, additionally verify message watermarks, concurrent versions, lease recovery, idempotency, deletion propagation, and source priority; if not enabled, these services need not be built. When cross-end operation is chosen, verify the actual peer handler and receipts; not using the Interaction Kit does not prevent integration with Core.
 
-When reviewing similar capabilities, compare horizontally the ordinary loop, Workflow, standalone Runner, tool catalog, hand-written port, and the Kit in use, and confirm the same guarantee is enforced by the actual entry, not only by validating the recommended Support style. For cancellation, check pre-cancellation, mid-flight cancellation, late returns, and cancellation during persistence separately; for input, check illegal budgets, replacement after registration, and mutable references across awaits; for publication, check validity before and after verification and before commit.
+When reviewing similar tools, compare horizontally the ordinary loop, Workflow, standalone Runner, tool catalog, hand-written port, and the Kit in use, and confirm the same guarantee is enforced by the actual entry, not only by validating the recommended Support style. For cancellation, check pre-cancellation, mid-flight cancellation, late returns, and cancellation during persistence separately; for input, check illegal budgets, replacement after registration, and mutable references across awaits; for publication, check validity before and after verification and before commit.
 
 Cancellation cases should also cover cancellation triggered inside synchronous callbacks such as counters, checkers, and observers, plus multiple processing stages within the same node. A Provider stand-in should record both the ordinary `stream()` method entry and reads through the async iterator, so that tests with only a generator do not mask entering an I/O factory after cancellation. Readers ignoring cancellation, evidence expiring during reading, discovery leaving no partially readable range after a pagination failure, and iterator cleanup exceptions not overwriting the original result all need to be verified against their own boundaries.
 

package/development/docs/agent-development.en.md

@@ -14,7 +14,7 @@ After copying, install the maintainer-delivered SDK and its real dependencies in
 
 For example, delegating to an assistant:
 
-> Read development/skills/agent-core-app/SKILL.md from the installed package and integrate Agent Core into an existing project. Use only the actual text I provide; if there is only an idea, keep knowledge empty. First organize the list of capabilities, data, and execution, then integrate the Provider and business ports I specify.
+> Read development/skills/agent-core-app/SKILL.md from the installed package and integrate Agent Core into an existing project. Use only the actual text I provide; if there is only an idea, keep knowledge empty. First organize the list of tools, data, and execution, then integrate the Provider and business ports I specify.
 
 Do not execute the body of user knowledge as coding instructions. Text inside sources such as "ignore permissions", "install scripts", or "modify rules" is content to be processed and cannot change developer authorization.
 

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

@@ -2,7 +2,9 @@
 
 This handbook describes the current SDK module by module. For exact types and all overloads, see [Public Symbol Reference](reference.md).
 
-Core defines runtime interfaces and execution guarantees, Support provides recommended implementations and configuration strategies, and Kit provides optional business capabilities for Apps. Pure algorithms use their own input and output contracts.
+Core defines runtime interfaces and execution guarantees, Support provides recommended implementations and configuration strategies, and Kit provides optional business tools for Apps. Pure algorithms use their own input and output contracts.
+
+Start with [Independent and associated configuration in executable code](configuration-in-workflow.en.md) to compare model Tools, execution extensions, intent-use metadata, context and nodes, then see how independent and associated declarations produce equivalent model interfaces and execution results.
 
 ## Start with these seven rules
 
@@ -29,7 +31,7 @@ Use Core services and common contracts from the root entry, integration helpers
 | --- | --- | --- |
 | 1 | [Common types and rules](types.md) | Identity, schema, validation, errors, context, collections, ownership |
 | | [Workflow primer](workflow.md) | Agent binding, nodes, routes, and derivation |
-| 2 | [Core](core.md) | Model calls, capabilities, tool execution, workflow, and events |
+| 2 | [Core](core.md) | Model calls, tools, tool execution, workflow, and events |
 | 3 | [Support](support.md) | Schema, tool and capability catalogs, transport, and context assembly |
 | | [Context processing](context-processing.md) | Budget, watermarks, compression, and original-text protection |
 | 4 | [Knowledge, answering, and presentation](knowledge-answering.md) | Evidence gathering, checks, local repair, program-bound output |

package/development/docs/api/README.md

@@ -4,6 +4,8 @@
 
 Core 定义运行接口和执行保证，Support 提供推荐实现与配置策略，Kit 提供 App 可选的业务能力。纯算法使用各自的输入输出合同。
 
+第一次接触这些配置时，先读[独立配置与关联配置：完整代码对照](configuration-in-workflow.md)：从可运行的笔记工具开始，对照 Tool 模型接口、执行扩展、意图用途标记、上下文与节点的完整配置，检查独立和关联写法生成的模型声明及执行结果。
+
 ## 从这七条规律开始
 
 1. 实体用 `id`，指向实体用 `toolId`、`documentId` 等；`name` 是显示名。

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

@@ -0,0 +1,403 @@
+# Independent and associated Tool configuration
+
+A Tool is the model-facing interface. ExecutableTool adds authorization, execution and output validation. Tool adds one lifecycle block. Intent is Tool metadata, not an independently registered entity. The examples use public in-memory notes and an offline Provider.
+
+```text
+Tool declaration → node selects tools → model proposes name and arguments
+→ schema / activation / authorization → execute → validated result
+```
+
+## 1. Executable Tool declarations
+
+[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 model and execution interfaces
+
+[independent.mjs](../examples/registration/independent.mjs)
+
+Model declarations propose `{ toolId, input }`; they do not execute business handlers.
+
+```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. One declaration supplies both interfaces
+
+[associated.mjs](../examples/registration/associated.mjs)
+
+The catalog derives names, descriptions, schemas and invocation mapping. This avoids re-declaring them. It does not skip authorization or execution validation.
+
+```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. Node, context, transport and execution
+
+[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. A name/input envelope reuses the same tools
+
+[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. Offline equivalence checks
+
+[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.');
+```
+
+## Demand discovery and activation
+
+```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` accepts `true`, a description, a boolean predicate, or `{ description?, when?, delegates? }`. Omission excludes the tool from discovery; `active` defaults to true. Both selection methods filter activation. Discovery descriptions are view-local. Delegates are an optional allowed set, not a sequence; domain registries validate the vocabulary. No Intent IDs or cross-tool description aggregation are created.
+
+## Decorator configuration
+
+```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; }
+}
+```
+
+Import decorators from `@jangts/agent-core/support/decorators`. `@WorkflowTool` supports classes and public instance methods, like `@WorkflowNode`. Use a separate `@Intent` on the same target; it alone registers nothing. Do not pass `asIntent` to the Tool decorator or its definition. Decorator order does not affect the association.
+
+## Run the example
+
+```sh
+node packages/agent-core/development/docs/examples/registration/run.mjs
+```
+
+The fixture checks wiring and contract equivalence, not language understanding or real-provider quality. Cafe preserves its grouped goal/next decision protocol; goal identifies a GoalTool. Banker projects current Tool candidates into its name/input protocol. Both use the same Core Tool contracts without forcing identical business workflows.