@jangts/agent-core 0.1.1 → 0.2.1

package/development/docs/examples.en.md

@@ -0,0 +1,36 @@
+# Integration references and maintenance tools
+
+[Back to development handbook](README.md) · [Manual maintenance](maintenance.md) · [Shared flow](flows/knowledge-maintenance.md)
+
+This kit provides [new project initialization](create-app.md), integration references for existing projects, copy-and-run offline code, and knowledge maintenance tools.
+
+## Integration code references
+
+For the overall flow and call timing see [How the mechanism works](mechanisms.md); the knowledge answering diagram there is an illustration of an App composing local Kit contracts.
+
+| Reference | What it offers an existing project |
+| --- | --- |
+| [Offline complete service answering](examples/offline-agent.md) | The same contract in TS/JS, from single node to tools, models, and process observation; no credentials needed |
+| [Basic model and tool calls](basic-usage.md) | Named calls, static tool catalogs, real authorization and execution, Provider stream boundaries |
+| [Core API](api/core.md) | Executor, model, tool, and cancellation/budget contracts |
+| [Support Context](api/support.md#context) | Assembling existing knowledge and profiles into model input |
+| [Knowledge API](api/knowledge-answering.md#knowledge) | Text parsing, section reading, and snapshots |
+| [Knowledge answering contract](api/knowledge-answering.md) | Connecting reading, generation, checks, and output through local Kit interfaces |
+
+The above are module call references; they do not create project directories, install dependencies, or start applications. Actual side effects are still carried by the existing project's ports.
+
+## Maintenance tools
+
+The following paths are relative to the installed package's `development/`. Scripts require Node 22+ and a resolvable Core build.
+
+| Entry | Input | Output and side effects |
+| --- | --- | --- |
+| `skills/agent-core-app/scripts/validate-knowledge.mjs PROJECT` | Existing project knowledge manifest, sources, and required read references | Check results; does not modify files |
+| `skills/agent-core-app/scripts/prepare-source.mjs PROJECT --source UTF8_FILE --id DOCUMENT_ID` | Existing project, explicitly provided source, and stable document id | Source awaiting review and a proposal; does not overwrite effective knowledge or configuration |
+| `skills/agent-core-app/scripts/plan.mjs PROJECT [--source UTF8_FILE]` | Existing project, optional source path | Agent development plan; see the Skill for specific behavior |
+| `skills/agent-core-app/scripts/create-app.mjs TARGET [--write]` | Empty target directory, name and purpose, optional real source | Read-only plan by default; explicitly creates a TypeScript/Node project and unpublished source candidates |
+| `skills/agent-core-app/scripts/create-app.mjs TARGET --check` | Generation receipt, current managed files, and the selected template | Read-only diff report; does not overwrite user modifications |
+
+Knowledge maintenance tools work from configuration explicitly provided by the project and do not scan or execute project code. For initialization and diff checks see [Create an App](create-app.md). For knowledge format, flow, and publication responsibility see the [Maintenance guide](maintenance.md). Failures exit with a non-zero code and an error report; invalid UTF-8, budget, or section errors cannot be bypassed by relaxing validation.
+
+The tools do not replace document review, resource authorization, database write-back, or publication, and they do not by default take on PDF/OCR, web crawling, or arbitrary material ingestion.

package/development/docs/flows/knowledge-maintenance.en.md

@@ -0,0 +1,38 @@
+# Knowledge Preparation, Maintenance, and Publication Flow
+
+This flow is referenced by the development-time knowledge preparation tools, the manual maintenance process, and the App's runtime knowledge growth implementation. It is not a prompt or state machine that Core executes automatically, and it grants no read or write permission. In an existing project, development-time verification and runtime loading reuse the same knowledge.config.json and compileApplicationKnowledge. When there is only an idea and no source, keep an empty file and an empty document list, and do not generate initial facts.
+
+## Shared Process
+
+| Stage | What must be obtained | Execution responsibility |
+| --- | --- | --- |
+| Obtain sources | Originals or references, source entity, time, usage/access scope | Organized by developers, or received by the App under authorization |
+| Form candidates | Locatable body text/fields; unknowns and conflicts retained | Human or App extractor; model output is only a candidate |
+| Assign identity | Stable document/section IDs, explicit revision and locale | The App's maintenance policy; not the model inventing new program handlers at will |
+| Check structure and references | Documents, sections, task reads, and budgets all usable | The same application compile entry and local validators such as Knowledge/Task |
+| Approve for publication | Human/business verification decided from sources and risk; authorization scope not widened | The App's own publication policy; the library does not build in generic approval |
+| Publish the version | Persistent records and the concurrent version commit succeed, then the new catalog becomes available | Controlled publication during development, or a transactional/CAS implementation at runtime |
+| Use and trace | Requests bind the catalog and source snapshot; corrections can find the old version | App handler and storage; Core maintains execution budget and cancellation |
+
+## Shared Rules
+
+1. Document IDs are unique within the catalog; section IDs are globally unique within a document. A title or file path does not replace identity.
+2. Changing body text or metadata that affects interpretation requires changing the revision. A snapshot does not replace source material, approval records, or a content hash.
+3. Validate references to tasks, readers, sections, outputs, and checks. A knowledge file passing syntax parsing does not mean the whole Agent integration is correct.
+4. Source material, user preferences, experience candidates, published knowledge, and tool receipts are handled separately; a user statement does not automatically become a public fact.
+5. Use the smallest complete read scope; when the budget is insufficient, report an error explicitly or read in batches, and do not silently truncate rules or necessary evidence.
+6. A failed check or publication does not overwrite the old version. Existing requests keep using their own old snapshot, and knowledge is not swapped out behind the scenes between generation and review.
+7. A data update does not automatically add execution permission. Dynamic knowledge references and program capability registration are two different flows.
+
+## Where the Shared Rules Are Enforced
+
+The example knowledge.config.json is an **App-owned configuration template**, not a new protocol in the library. It declares source files, read budgets, and read references that must be valid. compileApplicationKnowledge in development/skills/agent-core-app/scripts/lib/knowledge.mjs is used by both the validation tool and runtime loading; when the App copies or rewrites the template, it keeps the same entry:
+
+```text
+开发者／开发期脚本 → 源稿和配置 → 共享编译校验 → 发布应用资料
+运行期增长适配器 → 经审定的新版本 → 共享编译校验 → 持久提交／切换可用版本
+```
+
+The example implements only reading local source files, version computation, reference checks, and in-memory catalog construction. Runtime candidate extraction, review, persistence transactions, CAS, deletion, and permission filtering remain the App's responsibility; writing a flow in this file does not mean those capabilities are integrated.
+
+When integrating other formats, databases, or retrieval services, keep this flow and the same structure/reference checks, and replace only the input and commit adapters. There is no need to hard-code storage paths or one product's data tables into Core.

package/development/docs/getting-started.en.md

@@ -0,0 +1,71 @@
+# Installation and integration
+
+[Back to development handbook](README.md) · [API handbook](api/README.md)
+
+Install Agent Core as a dependency in your application, then integrate models, tools, and workflows as needed.
+
+When starting from an empty directory, you can first generate a TypeScript/Node project following [Create an App](create-app.md), then complete dependency and model integration along this page.
+
+## Installation
+
+Install from npm:
+
+```sh
+npm install @jangts/agent-core
+```
+
+Dependencies are installed by the package manager according to `package.json`. When using a local package provided by the maintainer, specify the tarball path:
+
+```sh
+npm install /artifacts/jangts-agent-core-0.1.0.tgz
+```
+
+Replace the path and version according to the actual delivery. Offline installation requires the maintainer to provide a complete local dependency source, and the package manager resolves all dependencies.
+
+The package provides ESM, CommonJS, and TypeScript declarations. Use Node.js 22.12.0 or later; the runtime must provide the APIs in use such as `fetch`, `AbortSignal`, and `ReadableStream`. Model credentials are managed by the application's server-side configuration.
+
+## Wire up the first call
+
+First provide a ChatProvider that the App has already configured, then pass the raw question; all other run settings have defaults:
+
+```ts
+import { Support, ModelRunner } from '@jangts/agent-core';
+
+const provider = new Support.CompatibleModelProvider({ config: {
+  baseUrl: process.env.AI_BASE_URL!,
+  apiKey: process.env.AI_API_KEY!,
+  model: process.env.AI_MODEL!,
+} });
+const model = new ModelRunner({ provider });
+const text = (await model.invoke('你好')).value;
+```
+
+The above uses the application's existing environment configuration, and the service must be compatible with Chat Completions; baseUrl does not include /chat/completions. The Provider handles HTTP/SSE itself, so you do not need to implement stream separately. Run the [Offline complete example](examples/offline-agent.md) first without model credentials; it does not call a real model. Plain text calls need no Knowledge, tools, or workflows. Kits are imported from `@jangts/agent-core/kits/<name>` as needed; see the corresponding task documentation for specific compositions.
+
+| Provided by the App | Executed by existing interfaces |
+| --- | --- |
+| The Provider's real connection configuration and user input; signal/budget overrides as needed | ModelRunner checks budget, handles cancellation/timeout, and calls the model |
+| Centralized tool declarations, server-side identity, and business implementation | Core ToolRegistry executes registrations; optional Support reduces repeated wiring, and authorization constraints come from the actual declarations |
+| Continue/end conditions and business error exits | AgentCoreEngine executes according to registered flows |
+| Knowledge reading, visibility scope, sources and versions | Kits such as Knowledge process provided data under local contracts |
+
+Next, follow [Model and tool integration](basic-usage.md) to complete text calls, tool proposals, and real execution in order. ModelRunner.invoke is one complete model call; multi-step execution is explicitly orchestrated by the App with existing Core APIs. For parameters and errors see [Core](api/core.md), [Support](api/support.md), and [Kit](api/kits.md).
+
+## Knowledge and output integration
+
+- [Knowledge documents](knowledge.md): sections, versions, selection, and snapshots; parse/define process only in-memory data and create no storage.
+- [Knowledge answering contract](api/knowledge-answering.md): the local interfaces of Knowledge, Answering, and Presentation, connected by the App through reader, authorization, model, review, and output.
+- [Manual maintenance](maintenance.md) and [Agent-assisted development](agent-development.md): shared rules and scripts for maintaining existing code and knowledge.
+- [Operations](operations.md): Core output, Support observer, App logs, cancellation, and budget.
+
+Prepare knowledge faithfully when raw material exists; when there is only an idea, keep knowledge empty with open items, and do not write speculation or demo text as facts. Knowledge growth is carried by the existing App's authorization, storage, and update flows.
+
+## Lifecycle wiring
+
+Static declarations can be validated during the existing project's assembly stage; user materials, read evidence, consumed budget, and session state should have explicit request/session ownership. Do not store mutable current-request state in objects shared across users.
+
+Before integration, verify small-scope behavior that has no real side effects, then verify real models and business execution as needed. The call code in the documentation is not a standalone application template, and it does not automatically grant publication or operation permissions.
+
+## Debug with a mock model
+
+When there are no model credentials, use the [MockGPT Kit](api/mock.md) to configure fixed replies, input-dependent generators, tool proposals, and failures. Direct calls are imported from `@jangts/agent-core/mock`; when a standalone HTTP model service is needed, use createMockServer from `@jangts/agent-core/mock/node`. Point the model client at its local address, and the application's workflow, tool authorization, and budget contracts stay the same.

package/development/docs/knowledge.en.md

@@ -0,0 +1,89 @@
+# Knowledge documents, sections, and versions
+
+[Back to development handbook](README.md) · [Knowledge API](api/knowledge-answering.md#knowledge) · [Complete answering chain](api/knowledge-answering.md)
+
+## How the library learns your knowledge structure
+
+Core does not scan knowledge directories, infer a knowledge base from file names, or automatically generate sections from Markdown headings. The App explicitly executes the following chain:
+
+```text
+App reads controlled sources
+  → provides id, revision, locale, and body/structure
+  → Knowledge.parseKnowledgeDocument (only when text anchors are used)
+  → Knowledge.defineKnowledgeCatalog
+  → App checks the task's document/section references
+  → catalog.read with the reads allowed for this round
+  → passes the KnowledgeSnapshot as evidence to subsequent handlers
+```
+
+This structure is a local specification after adopting the Knowledge Kit, not a document format every Agent must store. The App can generate `KnowledgeDocument.parts` directly without Markdown parsing.
+
+## Development-time preparation tools and runtime assembly functions
+
+| Entry/asset | Purpose | What it does not do |
+| --- | --- | --- |
+| [Maintenance guide](maintenance.md) | Prepare knowledge in the project; organize faithfully when sources exist, keep empty when none | Knowledge must have real sources; ideas are not facts |
+| `Knowledge.parseKnowledgeDocument({id, revision, text, locale?})` | Parse paired section anchors into a document tree | Does not read files, compute revision, or complete all catalog validation |
+| `Knowledge.defineKnowledgeCatalog(documents, options?)` | Compile/freeze an in-memory document catalog, providing ids, sectionIds, assertSelection, read | Does not create databases, watch files, import uploads, or automatically learn or write back |
+| [Section marker notes](#text-section-anchors) | Local code fragment explaining paired anchors and nesting rules | Not initial knowledge and not loaded automatically |
+| [knowledge.mjs](../skills/agent-core-app/scripts/lib/knowledge.mjs) | App-side template shipped with the Skill for explicitly reading files, computing versions, and compiling catalogs | Not a built-in persistent initializer of the library |
+
+Minimal document JSON structure:
+
+```json
+{
+  "id": "service-guide",
+  "revision": "content-version-1",
+  "locale": "zh-CN",
+  "parts": [
+    "全局引言。",
+    { "id": "delivery", "parts": [
+      "本章节自身正文。",
+      { "id": "delivery.timing", "parts": ["时机说明。"] }
+    ] }
+  ]
+}
+```
+
+`parts` may mix raw text strings and subsections. Structured section IDs must be non-empty strings and **globally unique within the same document**, not merely unique among adjacent siblings. Document IDs are unique within the catalog; catalog compilation rejects duplicate sections and cycles. Do not run only the text parser and skip catalog compilation.
+
+## Text section anchors
+
+Sources use paired markers on their own lines, with no indentation:
+
+```md
+<!-- agent-section:delivery -->
+本章节自身正文。
+<!-- agent-section:delivery.timing -->
+子章节正文。
+<!-- /agent-section:delivery.timing -->
+<!-- /agent-section:delivery -->
+```
+
+The characters accepted in IDs by the text adapter are English letters, digits, `_`, `.`, `:`, and `-`. Markers must keep spaces as in the example and occupy their own line; opening and closing IDs must match and nest correctly. Markdown `#` headings are merely body text. The parser recognizes anchors from raw text and is not a full Markdown interpreter; do not put example anchors on their own lines inside code fences in sources, or they will also be recognized as real sections.
+
+Stable IDs represent content identity. Changing a title does not require changing the ID; when splitting/deleting sections, migrate task mappings and historical reference policies at the same time. Characters such as `.` are only part of the ID; parent-child relationships are determined by the actual nesting in `parts` and cannot be guessed from names.
+
+## Three ways to read
+
+| Request | Returned scope |
+| --- | --- |
+| `{documentId:'service-guide', selection:{mode:'document'}}` | The whole body text and all descendants, in source order |
+| `{documentId:'service-guide', selection:{mode:'self', sectionIds:['delivery']}}` | The selected section's own string body, excluding subsections |
+| `{documentId:'service-guide', selection:{mode:'subtree', sectionIds:['delivery']}}` | The selected section and all its descendants |
+
+Sections explicitly selected are joined by two newlines in the order of the request array; duplicate IDs are rejected. If a parent section and its child are both selected into a subtree as two different IDs, the child text may still be included twice; the library does not automatically eliminate this ancestor overlap. The App should choose the appropriate minimal complete scope.
+
+`maxChars` limits the selected, trimmed body text of this call; exceeding it throws rather than silently cutting off the latter half. Document size, storage capacity, and model context budget are different limits. Unknown fields, identity, and file paths coming from the client are not trustworthy just because catalog.assertSelection passes; cross-boundary input is still parsed and authorized by the App according to its own schema.
+
+## Versions and snapshots
+
+The App provides `revision`. It can be a hash of available content and related metadata, a database version number, or a release version; the library does not compute it for you. Secretly modifying the body text under the same id/revision invalidates version semantics.
+
+`KnowledgeSnapshot` contains documentId, selection, revision, locale, content, and id. The id comes from the serialization of the above identity and selection and is **not a body-text hash, signature, persistence ID, or authorization credential**. Different section selections of the same document have different references, and selection order also affects identity. Generation and review should pass the same snapshot and must not re-read "the latest current body" to replace old evidence.
+
+## Updates and knowledge growth
+
+The current catalog has no register, upsert, delete, save, watch, or automatic retrieval interfaces over all storage. When change is needed, the App creates a new catalog and switches its own reference; see [Continuous accumulation](memory-and-learning.md) for the pattern. Before publication, re-validate task → document → sections, reader, checks, and output references.
+
+Both static sources and approved growth knowledge can be converted to KnowledgeDocument. User-uploaded originals, unverified self-descriptions, and experience candidates should not be mixed directly into a public authoritative catalog; permissions, sources, and review status are controlled by the App's storage/loading adapters.

package/development/docs/maintenance.en.md

@@ -0,0 +1,62 @@
+# Manual initialization and knowledge maintenance
+
+[Back to development handbook](README.md) · [Tool notes](examples.md) · [Shared flow](flows/knowledge-maintenance.md)
+
+## Establish sources first, not a full directory
+
+Developers are responsible for confirming which text is an actual knowledge source and which is only a product idea, pending content, or an operation instruction. When there is only an idea, keep files empty and do not generate introductions, policies, or user profiles that look real. When actual material exists, organize it faithfully; when originals are complex, conflicting, or mixed with instructions, preserve the originals and form candidates first, and never treat commands inside them as development authorization.
+
+Integrate existing projects following the [integration guide](getting-started.md), and initialize new projects following [Create an App](create-app.md). Pure conversation does not require a knowledge base; maintain knowledge configuration explicitly only when knowledge answering is needed. Compare existing directories first, preserve business files, and limit test knowledge to test scopes.
+
+A knowledge App prepares a `knowledge.config.json` in the same directory, for example the empty state below, and creates an empty `initial.knowledge.md`. Files are not read until they are registered.
+
+```json
+{
+  "schemaVersion": 1,
+  "maxDocumentBytes": 32000,
+  "maxReadChars": 8000,
+  "documents": [],
+  "requiredReads": []
+}
+```
+
+After installing the maintainer-delivered Core and full dependencies following the [installation guide](getting-started.md), you can run the shared validation entry. The directory argument below is the knowledge directory containing `knowledge.config.json` and does not have to be the project root; the tool path is located from the package installed in the current project:
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+When there is no knowledge it outputs the empty-catalog state; this is a correct preparation state and should not be made to look successful by fabricating knowledge. Actual sources can first be turned into candidates with the tools below, and after confirmation written into source files and registered in the manifest.
+
+## How the configuration is maintained
+
+`knowledge.config.json` is the template's App configuration; the library does not require every App to use this file. The current shared loader understands:
+
+| Field | Constraint and meaning |
+| --- | --- |
+| `schemaVersion` | Currently 1, checked by the shared compiler |
+| `maxDocumentBytes` | Positive integer, byte limit per source file; not a model token limit |
+| `maxReadChars` | Positive integer, per-read character limit for Knowledge |
+| `documents` | May be empty; entries are `{id,file,locale?}`; currently only lowercase `*.knowledge.md` file names in the same directory are allowed, and model-supplied paths are not accepted |
+| `requiredReads` | `{documentId,selection}` actually depended on by tasks; all references are checked at compile time |
+
+Document IDs must be unique; see [Knowledge documents](knowledge.md) for section rules. Newly added files must be registered explicitly; being on disk does not automatically grant publication or read eligibility. Source and subsequent version traceability are carried by the maintainer's own change records; candidate tools do not replace complete publication records.
+
+## Adding and updating reuse the same validation
+
+```sh
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/prepare-source.mjs ./existing-project/knowledge --source ./revision.md --id initial-doc
+node node_modules/@jangts/agent-core/development/skills/agent-core-app/scripts/validate-knowledge.mjs ./existing-project/knowledge
+```
+
+The first command only generates a candidate; the second checks the **currently effective configuration** and does not publish the candidate. The candidate contains the original file, document ID, suggested addition/replacement, source hash, revision, as well as the configuration hash at preparation time and existing document versions. Candidate validation also checks existing required section references; deleting a referenced section fails, and the task and configuration must be explicitly adjusted and the candidate prepared again—errors cannot be skipped automatically.
+
+The configuration hash comes from the raw bytes actually parsed this time, sharing a single configuration read with the candidate's budget and required-read validation, so it is not re-read after validation and marked against a different baseline. Each source file version comes from content read this time; this does not constitute an atomic multi-file filesystem snapshot.
+
+Publication is done by the maintainer: verify sources, body diffs, task references, and permissions → save the candidate to a controlled source file → add the new document to the manifest or update an existing file → use the same check entry → publish one complete version. Before publishing, compare the effective configuration and the revisions of replaced documents against the candidate baseline; if stale, redo the comparison. A single-file write is not a multi-file transaction; production systems should use their own versioned publication, transactions, or atomic switching.
+
+Direct editing follows the same flow. A failed validation keeps the published version; generation and review use the same snapshot; a failed update does not delete the original file. Manual and runtime growth can share `compileApplicationKnowledge`, replacing only the input and commit adapters.
+
+## What maintenance does not happen automatically
+
+The tools have no automatic approval, publication, file watching, indexing, scheduled learning, or database writes. User profiles and business experience are different application data; define their sources, updates, and deletions according to [Continuous accumulation](memory-and-learning.md), then decide whether to convert them into readable Knowledge documents.

package/development/docs/materials.en.md

@@ -0,0 +1,38 @@
+# User materials and data boundaries
+
+[Back to development handbook](README.md) · [Continuous accumulation](memory-and-learning.md)
+
+Receiving material, extracting body text, using it within a round, storing it in a personal profile, and publishing it as shared knowledge are different operations. Core does not automatically convert uploads into long-term memory, nor does it trust instructions in material just because the material contains section anchors.
+
+## Minimal processing chain
+
+```text
+Server confirms identity and material ownership
+  → App checks format/size, saves necessary source information
+  → Controlled parser extracts body text, records extraction failures or gaps
+  → Selects content according to this round's authorization
+  → Support context fragment marks it as user data and sets a budget
+  → Handler uses the material and binds output to actual evidence
+```
+
+Parsing and saving are provided by App adapters. The plain text example does not mean PDF, image OCR, audio transcription, web crawling, or archives are supported. When these formats are needed, register parsing capabilities and acceptable results explicitly; parsing failure must not be treated as empty content and then followed by a complete conclusion.
+
+| Field to be made explicit | Purpose |
+| --- | --- |
+| Material ID, owning user/tenant, access scope | The server establishes permissions and does not trust client-claimed owners |
+| Original reference, type, source time, content hash | Retrieve the original and determine versions; do not treat file names as stable identity |
+| Extraction version, body text, gaps, and parsing status | Distinguish originals from model/parser output |
+| Lifecycle, retention, and deletion method | Whether this round, the session, or persistent storage is decided by the product |
+| Review/publication status | Candidate material cannot automatically become shared authoritative knowledge |
+
+See [Material record](records.md#material-record) for a reference. It is an App-owned record sample with no corresponding Core persistence API.
+
+## Context and tools
+
+Use Support fragments to note the real source, `trust: 'user'`, and the corresponding lifecycle. The trust label is part of the assembly contract, not a sandbox; the App still needs to prevent material body text from being treated as higher-privilege instructions or executable code. Do not dynamically add one executable tool per uploaded file; usually keep a controlled `material.read` whose parameters reference IDs authorized for this round.
+
+When continuing use across rounds, pass only references available to the session and re-confirm permissions and lifecycle. When persistent storage is needed, enter the application's own candidate and publication flow. After deleting an original, also clean up extracted text, summaries, indexes, and references according to the App policy—do not delete only the UI list.
+
+## Delivery limits
+
+Do not output the full material text by default in errors, logs, or receipts. Partial reads, insufficient budget, and incomplete parsing should become explicit check results; retries cannot widen the visible scope. Source references, file download URLs, and cross-end presentation are chosen by the App; the Interaction Kit is optional, and front and back ends are not forced to use InteractionProtocol/CommandCatalog uniformly.

package/development/docs/mechanisms.en.md

@@ -0,0 +1,227 @@
+# How the mechanism works
+
+[Back to development handbook](README.md) · [API handbook](api/README.md) · [Knowledge answering contract](api/knowledge-answering.md)
+
+This document explains the current implementation with diagrams. Flows labeled "App composition example" are explicitly orchestrated by the application, not a fixed Agent flow built into Core; Core does not require the App to use Support, Kit, or task decomposition.
+
+## 1. Overall collaboration relationship
+
+```mermaid
+flowchart LR
+    User[User input] --> App[App: identity, configuration, business orchestration and delivery]
+    App -->|calls runtime APIs, registers handlers| Core[Core: execution, model, tools, context contracts]
+    Core -->|calls back according to registered contracts| Handler[App handler: business processing and actual ports]
+    Handler -->|state updates, results or errors| Core
+    App -->|optional integration assistance| Support[Support: builds configuration, adapters and handlers]
+    Support -->|artifacts handed to the App for registration| App
+    Handler -->|calls as needed| Kit[Optional Kit: knowledge, answering, presentation, interaction, etc.]
+    Kit -->|local business results| Handler
+    Handler --> IO[App databases, files and external services]
+    Core -->|ChatProvider contract| Provider[Model connection provided by the App]
+    Provider --> Model[Model service]
+    App --> Output[User-visible output]
+```
+
+Core and App have a call/callback relationship. Support assists the App in integrating the same set of contracts; Kit is chosen one-way by the App, and a Kit may call Core APIs internally, still bound by the same budget, cancellation, and error contracts.
+
+## 2. How task concepts map to execution mechanisms
+
+```mermaid
+flowchart TD
+    Question[User question] --> Compose[App organizes this round's processing by business]
+    Catalog[Central capability manifest: purpose, schema, constraints, handler] --> View[Capability view visible this round]
+    Identity[Server-side identity and resource permissions] --> View
+    View --> Compose
+    Compose --> Workflow[Optional AgentWorkflow: declares execution nodes and routing]
+    Workflow --> Node[Node: requires, run, provides, routes, onErrorNodeId]
+    Node --> Handler[App handler]
+    Handler --> Model[ModelRunner: obtains model proposals or answers]
+    Handler --> Tool[ToolRegistry: executes registered tools]
+    Handler --> Tasks[Optional Answering: domain answering tasks]
+    Tasks --> Definition[Task declaration: id, inputSchema, readerId, outputId, checkIds, intentIds, scopeId]
+    Definition --> Evidence[App reader: authorization, actual reading and evidence]
+    Evidence --> Items[AnswerItem: source status and owning input ID]
+    Items --> Answer[Generation, checks, local repair and delivery status]
+    Model --> Update[Handler returns results or local state updates]
+    Tool --> Update
+    Answer --> Update
+    Update --> Route[Core commits compliant updates, then selects a route per declarations]
+    Route -->|continue| Node
+    Route -->|complete| Result[Return to App for delivery]
+```
+
+The three concepts here are different: the **user question** is input, a **workflow node** is an execution stage, and an **answering task/item** is a domain object of the Answering Kit. One node can process multiple answer items; model proposals do not automatically create workflow nodes or install new handlers. A basic `ModelRunner.invoke` call needs neither a workflow nor answering tasks.
+
+## 3. How a Core workflow advances
+
+Corresponds to the actual rules of `AgentWorkflow` and a bound `AgentCoreEngine.run`.
+
+```mermaid
+flowchart TD
+    Definition[App declares workflow manifest] --> Validate[Validate on construction: nodes, route references, reachability, bounded cycles]
+    Validate --> Entry[entryNodeId corresponds to a startsRound node]
+    Entry --> Abort[Check cancellation, obtain target node]
+    Abort --> Round{Node marked startsRound?}
+    Round -->|yes| Budget{Enough round budget?}
+    Budget -->|no| Exhaust[Throw budget exhausted error]
+    Budget -->|yes| Count[Consume one round]
+    Round -->|no| Enter[Emit enter event]
+    Count --> Enter
+    Enter --> Requires[Check requires fields]
+    Requires --> Run[Call node run, obtain local updates]
+    Run --> Commit[Check cancellation, update shape and provides, then commit updates]
+    Commit --> Select[Select the first match in routes order]
+    Select --> Route{Match result}
+    Route -->|target node| Transition[Emit transition, clear previous node error]
+    Transition --> Abort
+    Route -->|complete| Complete[Compute result, isResult, check cancellation]
+    Complete --> End[Emit complete and return]
+    Route -->|no match| Contract[Workflow contract error]
+    Requires -.->|exception| Error[Error handling within the node try scope]
+    Run -.->|exception| Error
+    Commit -.->|exception| Error
+    Complete -.->|exception| Error
+    Contract --> Error
+    Error --> Recover{Not cancelled, not a contract error, and onErrorNodeId present?}
+    Recover -->|yes| ErrorNode[Move to the error node with context.error]
+    ErrorNode --> Abort
+    Recover -->|no| Throw[Throw to the caller]
+```
+
+Only entering a node with `startsRound: true` consumes a round; other stages in the same round do not count separately. Every possible cycle (including error routing) must pass through a round boundary. When the entry node omits the field, it starts a round by default. The budget entry check is outside the node's try scope, so exhaustion is not routed to that node's onErrorNodeId. `run(step)` uses an explicit StepOutcome: `{ type: 'continue' }` to continue, `{ type: 'complete', value }` to complete; value may legitimately be undefined.
+
+The commit guard covers only local state updates managed by Core; it does not roll back external writes that the handler has already performed. A failed diagnostic observation does not change business execution.
+
+## 4. Timing from model proposal to actual tool execution
+
+**App composition example**: uses the Support tool catalog, ModelRunner, and the Core tool executor.
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant A as App orchestration
+    participant S as Support tool catalog
+    participant M as ModelRunner
+    participant P as ChatProvider / model
+    participant T as Core ToolRegistry
+    participant H as App tool handler
+    U->>A: asks a question
+    A->>S: Obtains capability view and in-request runtime from the same manifest
+    S-->>A: Model declarations, parsers, real execution registration
+    A->>M: invoke (input and registered transport)
+    M->>M: Check cancellation, call quota, input and schema budget
+    M->>P: stream (input and visible capabilities)
+    P-->>M: Model chunks
+    M->>M: Full collection, protocol parsing
+    M-->>A: ToolProposal (tool name and raw parameters)
+    A->>T: runtime.invoke (tool name, parameters)
+    T->>T: Look up registered tool, parseInput
+    T->>H: authorize (parameters, server-side context, signal)
+    alt Authorization passes
+        H-->>T: Allowed
+        T->>H: execute, and wait for actual I/O
+        H-->>T: Actual result
+        T->>T: parseOutput, record success event
+        T-->>A: Validated result
+        opt App needs to continue generation based on the result
+            A->>M: invoke (tool result and follow-up input)
+            M->>P: Generate within the remaining quota
+            P-->>M: Complete response
+            M-->>A: Parsed result
+        end
+        A->>A: Business checks, bind facts and deliver
+        A-->>U: Final reply
+    else Authorization denied or execution/output check fails
+        H-->>T: Denied or exception
+        T-->>A: Error and failure event
+        A-->>U: App handles the failure according to the actual cause
+    end
+```
+
+The error branch in the diagram also covers input/output check failures in the Registry itself, where a handler call may not occur. A model proposal is not a success receipt, and Core does not automatically execute a tool just because the model proposed its name; whether to call it subsequently, generate again, or end is decided by the App handler/workflow. A failed tool output check also does not mean side effects that already occurred are rolled back.
+
+## 5. Internal flow of one model call
+
+```mermaid
+flowchart TD
+    Invoke[invoke: normalize input, select registered transport] --> Initial[Check cancellation and remaining call quota]
+    Initial --> Prepare[Prepare or reuse this transport snapshot]
+    Prepare --> Assemble[Core assembles text, messages, BuiltContext or ContextPlan]
+    Assemble --> Check[Actual message, transport instruction, Schema and optional token budget checks]
+    Check --> Consume[Obtain model call quota, set call deadline]
+    Consume --> Stream[Provider stream: collect chunks and check output budget]
+    Stream --> Finish[Complete response: finish, parse, resolve]
+    Finish --> Deliver[Await content delivery in order, check cancellation]
+    Deliver --> Journal[Commit Journal and completion information]
+    Journal --> Result[Return value and invocation]
+    Stream -.->|cancellation, timeout, upstream or output error| Error[Mark stage and error code and throw]
+    Finish -.->|protocol parsing failure| Error
+```
+
+Core is responsible for generic input assembly and final budget checks and does not implicitly select or compress. When processing is needed, the App registers Support or custom processing nodes into the same Workflow and uses ordinary routes to decide when to execute them. Model calls inside processing nodes share the request quota, cancellation, and deadlines; see [Context nodes](api/context-processing.md) for details.
+
+An ordinary invoke does not require prepare in advance. When early measurement is needed, use `model.prepare(...)` to obtain a single snapshot, call `prepared.measure(input)` repeatedly, then still consume the same handle through `model.invoke({ input, prepared })`. Measurement covers the actual transport instructions and Schema; the final check remains in effect, and the handle is not a quota reservation.
+
+`ModelRunner.sink.output` waits in order for consumers of generated chunks, and the fully parsed value is still returned through invoke; `execution.observe.event` is side-channel observation with isolated failures. Chunk preview and final business delivery are different boundaries.
+
+## 6. Task checks and local repair in the Answering Kit
+
+Corresponds to the seven nodes currently registered by `defineAnswerFlow`; this flow exists only when the Kit is adopted.
+
+```mermaid
+flowchart TD
+    Input[Validate input IDs, item ownership and count] --> Generate[generate: generate only source=ready items]
+    Generate --> Validate[validate: local checks and keep normalized values]
+    Validate --> Review[review: review per off / optional / required policy]
+    Review --> Select[select-repair: select items that are ready and still have issues]
+    Select --> Can{Failed items, repair count and call quota available?}
+    Can -->|yes| Repair[repair: consume one repair chance, submit only failed items and issues]
+    Repair --> Recheck[recheck: re-check only items generated this time]
+    Recheck --> Select
+    Can -->|no| Deliver[deliver: judge item by item]
+    Deliver --> Accepted[accepted: source ready, value present and checks satisfied]
+    Deliver --> Fallback[fallback: App fallback provided a value]
+    Deliver --> Blocked[blocked: no deliverable value]
+```
+
+Initial generation and each repair consume one workflow round; `maxRepairs` additionally limits the number of repairs. `canInvoke` reads the real quota provided by the App, and the Kit does not create an extra model budget. Non-ready sources do not enter generation or repair; items whose review has explicitly failed cannot become passing because review later becomes unavailable. Cancellation, invalid item ownership, and program contract errors throw, and are not automatically disguised as fallback.
+
+## 7. Composition timing of App knowledge answering
+
+The diagram below illustrates an App composition organized by the [Knowledge, Answering, and Presentation contracts](api/knowledge-answering.md); the concrete orchestration and ports are provided by the App. For complete code that can be copied and run directly see [Offline service answering](examples/offline-agent.md); that code does not enable Knowledge/Answering.
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant A as App answer
+    participant T as Answering task catalog
+    participant K as Knowledge / App reader
+    participant F as Answering Flow
+    participant M as Same ModelRunner
+    participant C as App checks and review
+    participant O as Presentation
+    U->>A: question, signal
+    A->>T: Parse task parameters and read
+    T->>K: Call the registered reader
+    K->>K: App authorize, read the fixed revision snapshot
+    K-->>A: Question and source evidence
+    A->>F: Run declared answer items
+    F->>M: generate: call with evidence
+    M-->>F: Draft
+    F->>C: Local checks and policy review
+    C-->>F: Check results and issues
+    loop issues remain and repair count, real quota allow
+        F->>M: Repair only failed items
+        M-->>F: Repaired draft
+        F->>C: Re-check and review
+        C-->>F: Latest check results
+    end
+    F-->>A: accepted / fallback / blocked
+    opt A deliverable value exists
+        A->>O: Bind program source fields and render the template
+        O-->>A: Body text and sources
+    end
+    A-->>U: status, text (if any), issues
+```
+
+If review uses a model, it should consume quota through the same ModelRunner passed in. Fallback evidence and allowed wording are provided by the App; when no deliverable value is provided, blocked is returned. Authorization, reading, cancellation, or contract errors may be thrown directly, with no guarantee of reaching final delivery.

package/development/docs/memory-and-learning.en.md

@@ -0,0 +1,42 @@
+# Memory and continuous accumulation
+
+[Back to development handbook](README.md) · [Shared flow](flows/knowledge-maintenance.md) · [Record templates](records.md)
+
+The library has no out-of-the-box long-term memory database, user profile merging service, or automatic learner of business experience. Core provides execution contracts, Support helps assemble context and calls, and Kits such as Knowledge/Answering provide local processing once adopted. Whether to record, how to assign ownership, and when to update and delete are all explicitly implemented by the App; not recording is also a valid choice.
+
+## Different data needs different rules
+
+| Data | Recommended use | Should not be equated with |
+| --- | --- | --- |
+| Recent Q&A | Session continuity, disambiguation | Tool execution logs, permanent knowledge |
+| Accumulated user preferences | Addressing, expression preferences, ongoing topics | Identity, permissions, public facts |
+| Business experience candidates | Inducing reusable suggestions and failure patterns from results | Proven rules, automatic authorization |
+| Published knowledge | Business facts with explicit sources, scope, and versions | Unverified user self-descriptions |
+| Original materials and extraction results | Current task evidence or authorized archives | Automatically shared knowledge |
+
+Do not use one source-less large summary to hold all categories. Each record category should at least have stable identity, ownership, source, version, status, and retention policy. Template fields are only a starting point; the App defines and validates them, and they are not a new Core protocol that all consumers must follow.
+
+## Application flow for updating user preferences
+
+```text
+Select final Q&A allowed to be recorded, and the watermark
+  → Old summary + new Q&A + explicit merge rules
+  → Model extraction of candidates under budget constraints
+  → Parsing and length/source/sensitive-scope checks
+  → Commit summary and new watermark on the premise of the old version
+  → Subsequent requests read by identity and mark it as low-trust memory
+```
+
+Do not mix the model's internal reasoning, corrections, or unexecuted actions into user profiles. When new expressions conflict with old preferences, apply the App's explicit rules; authoritative human facts are still provided by the corresponding data source. On model failure or version conflict, keep the old summary and the unconsumed watermark and retry with bounds, avoiding lost messages or duplicate merges. Scheduled tasks, storage transactions/CAS, leases, and retries are implemented by the App; the Core per-request budget cannot be assumed to cover background jobs.
+
+## Application flow for experience growth
+
+Register extraction, validation, query, and publication implementations with a fixed task type; adding an experience record is only a data change and does not automatically add a handler. Candidates should be associated with actual sources and results, retain applicability scope, counterexamples, and conflicts, and not treat one success as a universal rule.
+
+Candidate formation → deduplication/conflict checks → business validation or human confirmation → versioned publication → controlled reading, consistent with the [shared flow](flows/knowledge-maintenance.md). To integrate with Knowledge, the App converts permitted records into `KnowledgeDocument`, compiles a new catalog, and switches the request reference; active requests keep using the old snapshot.
+
+`prepare-source.mjs` is used to organize text candidates during development. Runtime persistent learning can reuse its compilation logic and source constraints, while storage, concurrency, and publication policies are provided by the App.
+
+## Decisions required before runtime integration
+
+Record scope and user choices, tenant isolation, visibility scope, retention and deletion, source priority, update conflicts, idempotency keys/consumption watermarks, failure recovery, and which content is forever candidate-only. Without these implementations, documentation and interfaces should state clearly "used for this round/session" or "manually maintained", and must not claim automatic learning.