@jangts/agent-core 0.2.0 → 0.2.5

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.

package/development/docs/operations.en.md

@@ -0,0 +1,51 @@
+# Result delivery, diagnostics, and operations
+
+[Back to development handbook](README.md) · [Core API](api/core.md) · [Support API](api/support.md)
+
+## Boundary of each run
+
+Keep startup manifests separate from per-request state. For each request, establish identity, the allowed knowledge view, an `AbortSignal`, model/tool budget, and source and output state. Credentials, endpoints, model characteristics, and error mapping for connecting to the Provider are managed by the App server, and user materials or model parameters are not allowed to override these configurations.
+
+Consider rounds, model call counts, timeouts, message and output characters, schema size, and business tool quotas separately. Repair, review, and fallback also consume budget; a step called "recovery" cannot mean unlimited retries. Core's model call budget covers only calls that actually pass through that runner; external HTTP, background jobs, and model calls made by the App itself must be limited by the App.
+
+Cancellation must reach the actual model and business I/O; for writes already started, cancellation does not mean rollback. The App should be able to judge whether an operation has executed by idempotency key/real receipt, and query state before retrying. Synchronous ToolRegistry does not wait for arbitrary Promises; asynchronous business logic should be placed in suitable asynchronous handlers/nodes and must not fake synchronous success.
+
+## Verify facts first, then form presentable output
+
+```text
+Parsed model proposal
+  → authorization and real execution
+  → input/output contracts and source checks
+  → generate candidate reply
+  → completeness/business fact checks
+  → program binds sources, action states, and links
+  → deliver in the form chosen by the App
+```
+
+A Knowledge Snapshot is a source reference, a tool event is an execution record, and model text is a candidate explanation; the three do not substitute for each other. Answering's tasks, checks, and bounded repair help organize this chain; the concrete fact checks are provided by the App. See the [knowledge answering API](api/knowledge-answering.md) for the relevant local contracts.
+
+Presentation/Interaction is an optional Kit. InteractionProtocol/CommandCatalog does not determine how the App exchanges data between front end and back end; when used, the App registers commands, parsing, and presentation implementations, and still needs actual receipts from the peer. The App may also directly adopt its own HTTP/SSE/event protocol.
+
+## Error exits
+
+| Actual cause | Program handling | Direction of user-facing wording |
+| --- | --- | --- |
+| Source not provided or not allowed to read | Do not widen permissions, do not generate fake facts | State which kind of available knowledge is missing |
+| Parameters or output violate the contract | Record the specific stage and code; repair or end within budget | State the actual action not completed this time |
+| Provider stream break/timeout | Save known execution state, retry with bounds | Reply incomplete, can retry |
+| Insufficient budget/read limit exceeded | Narrow the legal scope or split the task | State the scope limit; no silent truncation |
+| User cancellation | Stop cancellable work, verify executed operations | State clearly that it stopped and what is confirmed |
+
+Error messages should not show internal schemas, tokens, call protocols, or stack traces verbatim. Logs keep machine-locatable fields, and user copy keeps the accurate cause; not every failure should be described as a connectivity problem.
+
+## What observation and persistence each own
+
+Core's run records/diagnostics and Support's Provider observer provide observation boundaries; they do not automatically create a log database. The App decides whether to output to the console, files, telemetry systems, or a persistent repository, and how to authorize queries, redaction, and retention. `breakWhile` tags are classification hints for interruption, not permission or rule filtering switches; follow the [Support reference](api/support.md).
+
+It is recommended to correlate request/run, stage, model or tool call ID, business error code, knowledge revision/snapshot id, and actual duration. By default do not collect credentials, full prompts, user materials, or model body text; when body-text diagnostics are needed, the product must explicitly enable and limit the scope. Observation callbacks should not change business returns or escalate a record failure into duplicate execution.
+
+## Publication and recovery
+
+Deliver code manifests, knowledge, task references, and configuration as one verifiable version. Validate references before publication and prepare a rollback version; new requests switch to the new catalog while existing requests hold old snapshots. Whether multi-file or database publication is atomic is implemented by the App; the Knowledge in-memory catalog itself provides no storage transactions.
+
+When the App publishes, also state the enabled capabilities, knowledge version, configuration, and changes in externally visible behavior; the new version must still preserve the original permissions, budget, cancellation, and delivery guarantees.

package/development/docs/records.en.md

@@ -0,0 +1,63 @@
+# App data format examples
+
+The JSON below only explains field design for App-owned records; it does not participate in runtime loading, register capabilities, or create data tables. Core does not require this storage format.
+
+Use null/empty arrays to indicate not yet provided, and do not fabricate facts from example default values. Field names, states, and versions are defined and validated by the App itself.
+
+## Material record
+
+Original, extraction status, ownership, lifecycle, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "scope": "private",
+  "original": { "reference": null, "mediaType": null, "contentSha256": null, "receivedAt": null },
+  "extraction": { "status": "pending", "revision": null, "text": null, "caveats": [] },
+  "lifetime": "turn",
+  "expiresAt": null,
+  "publication": { "status": "unpublished", "documentId": null }
+}
+```
+
+## User preferences
+
+Accumulated interaction preferences, source watermark, and version.
+
+```json
+{
+  "schemaVersion": 1,
+  "ownerId": null,
+  "revision": null,
+  "summary": null,
+  "sourceWindow": { "after": null, "through": null, "references": [] },
+  "updatedAt": null,
+  "expiresAt": null,
+  "status": "uninitialized"
+}
+```
+
+## Experience candidate
+
+Experience source, applicability, validation, and publication status.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": null,
+  "ownerId": null,
+  "revision": null,
+  "status": "candidate",
+  "claim": null,
+  "applicability": [],
+  "sources": [],
+  "counterexamples": [],
+  "conflicts": [],
+  "validation": { "status": "pending", "references": [] },
+  "publication": { "approvedBy": null, "approvedAt": null, "documentId": null }
+}
+```
+
+User preferences cannot carry identity and permissions; experience candidates are not published automatically; raw materials do not automatically enter shared knowledge. See [Knowledge maintenance](maintenance.md), [Materials](materials.md), and [Continuous accumulation](memory-and-learning.md).

package/development/docs/registration.en.md

@@ -0,0 +1,63 @@
+# Registration, assembly, and execution
+
+[Back to development handbook](README.md)
+
+## Ordinary tool integration
+
+Prefer putting static tool definitions in a separate, readable, typed manifest, preserving item types with Support.defineTool, and assembling with Support.defineToolCatalog. Each item contains id, kind, description, inputSchema, authorize, execute, and parseOutput; inputSchema provides both jsonSchema and parse; model capabilities and execution registration consume the same definition. For complete code see [Tool integration](basic-usage.md#tools-are-declared-only-once).
+
+Create catalog.bind({ app: context, execution: { signal } }) per request; the model first produces a ToolProposal, and the App then calls runtime.invoke. The latter reuses Core ToolRegistry.invokeAsync, performing input parsing, actual authorization, execution, and output checks in order. When the available set changes, use catalog.select(ids) to project the same manifest, and still check the real identity at execution. This Support adapter does not replace workflows or the business specifications of Kits.
+
+## Two different kinds of registration
+
+| Registered object | Purpose | Update method |
+| --- | --- | --- |
+| Tools/model capabilities/workflows/checks/output | Declare what the program can do, when it is available, what it accepts, and who implements it | The App compiles manifests and provides the available set by stage and real identity |
+| Documents/sections/knowledge versions | Declare what content a given read can see | The App loads sources and creates a Knowledge catalog; on update, explicitly rebuild the catalog and related views |
+
+Adding one knowledge document usually does not require adding a tool. Keep a single `knowledge.read`, and let the catalog authorized for this round provide legal document/section IDs. The model may propose read requests from the provided set, but cannot use them to register arbitrary new handlers, discover disk directories, or publish knowledge.
+
+## What a manifest should state
+
+At minimum it should be possible to read: stable identifier, purpose, input and output, real execution entry, availability conditions, read scope, side effects, errors, and receipts. Derive the model-visible catalog, schema, and reference validation from the manifest wherever possible; do not maintain one prompt capability list and another actual execution list.
+
+- `ModelCapabilityRegistry` registers the structures the model can propose along with `inputSchema` and `resolve`. inputSchema.jsonSchema is used for model declarations; business parsing, value ranges, and authorization must still be enforced by the program.
+- `ToolRegistry` registers `id/kind/parseInput/execute/parseOutput`. invoke is for synchronous implementations; invokeAsync waits for asynchronous execution before checking output and recording results; do not hand a Promise to the synchronous entry as a completed result.
+- `AgentCoreEngine` workflow nodes declare `requires/provides/routes/onErrorNodeId`. Only updates that pass cancellation and state contract checks are committed; branches are selected in declaration order.
+- `Support.defineContextFragments` assembles request input and fragments. Trust, source, and budget must be correctly labeled by the App; client self-reporting alone is not acceptable.
+- Knowledge, Answering, Presentation, Interaction, Intents, and Tools each own local contracts and are chosen according to business needs. They are not automatically installed by Core.
+
+For named constructors, static helpers, and instance methods see [Core](api/core.md), [Support](api/support.md), and [Kit](api/kits.md).
+
+## Separate model proposals from actual execution
+
+```text
+Server establishes identity and the available capability view
+  → model proposes capability + parameters
+  → Core collects the complete response, validates with inputSchema.parse, then calls the registered resolve
+  → App selects the actual execution entry
+  → tool parameter parsing → authorization by server-side identity → execute → output checks
+  → program records actual sources/execution receipts
+  → generation, checks, binding, and delivery
+```
+
+`parse` should not incidentally perform writes, send messages, or call business tools. Nor should a success receipt be generated merely because the model says it is "done". Using the Interaction Kit for cross-end actions merely selects an optional exchange specification; the App still needs to implement peer handlers, identity, permissions, and confirmation of actual results.
+
+## Static manifests and in-request views
+
+Known tools and local protocols are suitable for registration at startup. Authorization, page environment, current tenant, and allowed knowledge change per request and should be projected into the visible set during this round's assembly. Model visibility limits do not replace execution-time authorization.
+
+When new documents must be available immediately: load new knowledge → validate catalog and task references → build a new version catalog → atomically switch the App's current reference. Existing requests keep their old catalog and snapshots; new requests use the new catalog. Do not mix body text, schema, sources, and revisions from before and after the reload within the same answer.
+
+When program capabilities must genuinely be added dynamically, the App explicitly decides the code source, publication, and registration point, and reconstructs the corresponding registry. The library has no model-driven arbitrary code installation, automatic file discovery, or hot-unloading platform.
+
+## Checks at startup and per request
+
+| Timing | What to check |
+| --- | --- |
+| Startup/publication | Whether handlers exist; whether node and output references are valid; whether knowledge/sections exist; whether the Skill's tools are actually registered; whether parameter schema and parser agree |
+| Request start | Identity, knowledge access scope, budget, signal, current catalog revision, and capability set |
+| Before real execution | Current permissions, resource ownership, parameter value ranges, and necessary confirmation |
+| Before delivery | Tool result contracts, sources and numbers, generated fields, program-bound fields, output completeness |
+
+A Kit's validator can only validate the local structure it knows about. It does not know your tenants, storage paths, data permissions, or business facts; these checks cannot be omitted just because "a creator was used".

package/development/skills/agent-core-app/SKILL.md

@@ -70,3 +70,7 @@ Use `docs.acceptance` to select checks for concrete uncertainties, while followi
 ## Custom model transport boundaries
 
 A custom response collector is synchronous and request-local. Its outputChars must be a nonnegative safe integer after creation, each push and finish. An explicit infinite maxOutputChars budget does not permit infinite or invalid collector counts. Core records the largest valid observed count; finish may release buffers. Optional call metadata is read once on a best-effort basis and cannot replace the actual result, original failure or cancellation. Prefer Support transports for standard native calls and JSON; custom transports must preserve complete parsing, budgets and cancellation before any tool execution.
+
+## Node cache ownership
+
+Use context.cache for bounded Engine memory; its default capacity is 1024, partitions are node-local and only get may name another node. The low-level step partition is `$step`. An App may explicitly inject an asynchronous AgentCachePort for context.agentCache. Persistence must be supported explicitly, is separate from volatile storage and never falls back. The App owns user isolation, serialization, capacity and expiry; do not cache authorization decisions. Forks start with empty Engine memory and only regain an App port when resume explicitly supplies agentCache. Keep durable facts in state/App storage, not caches.

package/development/skills/agent-core-app/scripts/create-app.mjs

@@ -1,3 +1,13 @@
+/**
+ * Scaffold or compare an App that uses `@jangts/agent-core`.
+ *
+ * Resolves the SDK the target project depends on, renders the selected template into a staging
+ * directory and only then renames it into place, so a failed or concurrent run never leaves a
+ * half-written app. `--check` compares the managed files against the recorded receipt instead of
+ * writing. Nothing here installs dependencies, calls a model or publishes content.
+ *
+ * Usage: see `usage` below; run directly or import `createApplication`.
+ */
 import { createHash } from 'node:crypto';
 import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
@@ -215,6 +225,15 @@ async function compare(target, resources, definition) {
   };
 }
 const manifestName = '@jangts/agent-core';
+/**
+ * Create or check a generated application directory.
+ *
+ * @param args CLI arguments: `TARGET` plus optional flags described by `usage`.
+ * @param cwd Directory relative paths are resolved against; defaults to the process cwd.
+ * @returns A plan (`--write` omitted), a comparison (`--check`) or the creation result.
+ * @throws {TypeError} When arguments, names, the target or the source file are invalid.
+ * @throws {Error} When the template, receipt or SDK manifest is unsupported or inconsistent.
+ */
 export async function createApplication(args, cwd = process.cwd()) {
   const { target, values } = parse(args, cwd);
   if (basename(target) === '.local')

package/development/skills/agent-core-app/scripts/lib/knowledge.mjs

@@ -1,8 +1,25 @@
+/**
+ * App-owned knowledge loading for the `agent-core-app` Skill.
+ *
+ * Reads the App's `knowledge.config.json` allowlist, verifies each referenced document against the
+ * configured byte limit, and compiles the documents into a Knowledge Kit catalog. This is App
+ * configuration code, not a Core file-store API: no model or request may supply a filesystem path.
+ *
+ * Exports: `compileApplicationKnowledge`, `readApplicationKnowledge`, `loadApplicationKnowledge`.
+ */
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { Knowledge } from '@jangts/agent-core/kits/knowledge';
 
-// This is App-owned configuration and loading code, not a Core file-store API.
+/**
+ * Compile parsed documents into a Knowledge catalog.
+ *
+ * @param documents Documents produced by `Knowledge.parseKnowledgeDocument`.
+ * @param policy Validated `knowledge.config.json` content (`schemaVersion`, `maxReadChars`,
+ *   `requiredReads`).
+ * @returns The compiled catalog; required reads are resolved so a missing read fails here.
+ * @throws {TypeError} When the policy shape or a required read is invalid.
+ */
 export function compileApplicationKnowledge(documents, policy) {
   if (
     !policy ||
@@ -18,6 +35,17 @@ export function compileApplicationKnowledge(documents, policy) {
   return catalog;
 }
 
+/**
+ * Read the knowledge config and its allowed documents from one directory.
+ *
+ * The config hash is computed over the exact bytes parsed below, so a proposal identity cannot
+ * drift from the document catalog it was derived from.
+ *
+ * @param directory Directory holding `knowledge.config.json` and the listed documents.
+ * @returns Parsed `documents`, the raw `policy` and the `baseConfigSha256` of the config file.
+ * @throws {TypeError} When the config or a document entry fails validation.
+ * @throws {RangeError} When a source document exceeds `maxDocumentBytes`.
+ */
 export async function readApplicationKnowledge(directory = new URL('./', import.meta.url)) {
   // Bind validation and proposal identity to the exact bytes parsed below.
   const configBytes = await readFile(new URL('knowledge.config.json', directory));
@@ -58,6 +86,14 @@ export async function readApplicationKnowledge(directory = new URL('./', import.
   return { documents, policy, baseConfigSha256 };
 }
 
+/**
+ * Read and compile the App knowledge catalog in one step.
+ *
+ * @param directory Directory holding `knowledge.config.json` and the listed documents.
+ * @returns The compiled Knowledge catalog.
+ * @throws {TypeError | RangeError} Same validation failures as `readApplicationKnowledge` and
+ *   `compileApplicationKnowledge`.
+ */
 export async function loadApplicationKnowledge(directory = new URL('./', import.meta.url)) {
   const { documents, policy } = await readApplicationKnowledge(directory);
   return compileApplicationKnowledge(documents, policy);

package/development/skills/agent-core-app/scripts/plan.mjs

@@ -1,3 +1,12 @@
+/**
+ * Read-only planning entry for the `agent-core-app` Skill.
+ *
+ * Reports whether a project exists, which SDK it resolves, the state of its knowledge catalog and
+ * the SDK tools/docs that may be used next. It never evaluates project code, calls a model or
+ * writes files; the printed JSON is guidance for the agent, not a permission grant.
+ *
+ * Usage: `node plan.mjs PROJECT [--source UTF8_FILE]`.
+ */
 import { stat } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';

package/development/skills/agent-core-app/scripts/resources.mjs

@@ -1,3 +1,13 @@
+/**
+ * Locate the SDK installation and the Skill assets it ships.
+ *
+ * The Skill never downloads or copies files: it resolves the `@jangts/agent-core` installation the
+ * target project already depends on, or — only when this Skill runs from inside the distributed
+ * SDK — the bundled sibling assets. Every returned path is verified to be a regular file so a
+ * broken or foreign package cannot silently supply a different asset.
+ *
+ * Exports: `resolveSdkResources`.
+ */
 import { createRequire } from 'node:module';
 import { readFile, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
@@ -69,6 +79,13 @@ async function requiredFile(root, relative) {
   return filename;
 }
 
+/**
+ * Resolve the SDK root and every Skill resource path for one project.
+ *
+ * @param project Project directory used to resolve the installed SDK.
+ * @returns `sdk` (`root`, `version`, `source`), the `tools`/`docs` file paths and `knowledgeLoader`.
+ * @throws {Error} When the SDK cannot be resolved, or a declared resource is missing or not a file.
+ */
 export async function resolveSdkResources(project) {
   let sdk = await installedPackage(resolve(project));
   if (!sdk) {

package/dist/cjs/diagnostics/catalog.js

@@ -1,6 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.coreEventCatalog = void 0;
+/**
+ * Default visibility tier for every event Core can emit.
+ *
+ * The same object is the allow-list used when normalizing persisted records; adding an event to
+ * `CoreEventName` without a tier here fails type checking.
+ */
 exports.coreEventCatalog = {
     'node.progress': 'metadata',
     'model.start': 'metadata',