@jangts/agent-core 0.1.1 → 0.2.1

package/development/docs/api/knowledge-answering.en.md

@@ -0,0 +1,166 @@
+# Knowledge, Answering, and Presentation
+
+[Shared types](types.md) · [Back to home](README.md). The three Kits compose through ordinary inputs and outputs.
+
+## Knowledge
+
+```ts
+defineKnowledgeCatalog(documents, options?): KnowledgeCatalog
+parseKnowledgeDocument({ id, revision, locale?, text }): KnowledgeDocument
+```
+
+A document is still `{ id, revision, locale?, parts }`, and a section is still `{ id, parts }`. Catalog extends ReadonlyCatalog<KnowledgeDocument> and adds:
+
+```ts
+catalog.sectionIds(documentId): readonly string[]
+catalog.assertSelection(request: KnowledgeRead): void
+catalog.read(request: KnowledgeRead): KnowledgeSnapshot
+interface KnowledgeRead {
+  readonly documentId: string;
+  readonly selection:
+    | { readonly mode: 'document' }
+    | { readonly mode: 'self' | 'subtree'; readonly sectionIds: readonly string[] };
+}
+interface KnowledgeSnapshot extends KnowledgeRead {
+  readonly id: string;
+  readonly revision: string;
+  readonly locale?: string;
+  readonly content: string;
+}
+```
+
+Reads remain synchronous in-memory operations that do not read files, access the network, or decide material permissions. The snapshot id distinguishes document, revision, language, and selection range. Unknown documents／sections or duplicate selections are rejected; exceeding maxChars is rejected without truncating facts. The observation callback is at options.observe, and failures are isolated.
+
+Read requests use KnowledgeRead. maxChars and observe are bound at catalog construction; structured documents, requests, and observers may be implemented by classes. Section snapshot IDs are opaque source identities.
+
+Observation callbacks for knowledge, output composition, and answer flows receive only an independent structuredClone data snapshot and retain no prototypes or methods of business values. Observable payloads that cannot be copied skip notification; observation failures do not change business results and never leak internal object references as a fallback. Answer observation cannot modify already checked body text or source data.
+
+## AnswerTaskCatalog
+
+```ts
+defineAnswerTaskCatalog(definitions, ports): AnswerTaskCatalog
+interface AnswerTaskDefinition<Input, Metadata> {
+  readonly id: string;
+  readonly description: string;
+  readonly inputSchema: SchemaAdapter<Input>;
+  readonly intentIds: readonly string[];
+  readonly scopeId?: string;
+  readonly readerId: string;
+  readonly outputId: string;
+  readonly checkIds: readonly string[];
+  readonly metadata: Metadata;
+}
+```
+
+ports contains readers, outputs, checks, and optional assertDefinition. readers/outputs/checks all receive the registration set interface.
+
+```ts
+defineAnswerReaderCatalog(definitions): AnswerReaderCatalog
+reader.read(input, context): MaybePromise<Evidence>
+catalog.read({ taskId, input }, context): Evidence
+catalog.readAsync({ taskId, input }, context): Promise<Evidence>
+```
+
+context extends OperationContext and includes the read-only task definition selected for this run. Synchronous read rejects thenables; readers with I/O use readAsync. The input schema is parsed first, and the reader is still responsible for real authorization and reading. Registration checks IDs and reader/output/check references and never implicitly selects another task.
+
+## Check catalog
+
+```ts
+defineAnswerCheckCatalog(definitions): AnswerCheckCatalog
+interface AnswerChecker<Value, App> {
+  readonly id: string;
+  check(value: Value, context: OperationContext<App>): CheckResult<Value>;
+}
+checks.check({ checkIds, value }, context): CheckResult<Value>
+```
+
+value comes first and context second. The catalog runs in checkIds order, preserves explicit corrected values, merges issues in execution order, and marks the check source; program errors are not wrapped as model factual errors. Synchronous checkers must not accidentally return a Promise.
+
+## AnswerFlow
+
+```ts
+defineAnswerFlow<Data, Value, App>(definition): AnswerFlow<Data, Value, App>
+flow.run({ inputIds, items }, context): Promise<readonly AnswerResult<Data, Value>[]>
+```
+
+definition contains reusable maxItems, maxRepairs, reviewPolicy, canInvoke, and named handlers. signal, diagnostics, and this run's App dependencies are passed through run's context; canInvoke(context) reads the real balance of these dependencies when a call is actually needed.
+
+| handler | Input | Returns |
+| --- | --- | --- |
+| generate | `{ items, repairs?, previous? }` | `Promise<ReadonlyMap<itemId, Value>>` |
+| check | `{ item, value }` | Synchronous CheckResult<Value> |
+| review | `{ items: readonly { item, value }[] }` | `Promise<ReadonlyMap<itemId, CheckResult<Value>>>` |
+| fallback | `{ item, issues }` | `{ handled: true; value: Value }` or `{ handled: false }` |
+
+The handler's second argument is uniformly OperationContext<App>. The App may provide the same ModelRunner through context.app; the Kit does not create models or add model quota. Handlers are bound at definition time and compiled into a fixed Workflow; each run builds independent task state and repair quota, and the same flow can be reused concurrently. Handlers receive the current node's cancellation signal and diagnostics scope, and stage runs are recorded by the Core Loop.
+
+```ts
+interface AnswerItem<Data> {
+  readonly id: string;
+  readonly inputIds: readonly string[];
+  readonly sourceStatus: 'ready' | 'unavailable' | 'conflict';
+  readonly data: Data;
+}
+interface AnswerResult<Data, Value> {
+  readonly item: AnswerItem<Data>;
+  readonly value?: Value;
+  readonly status: 'accepted' | 'fallback' | 'blocked';
+  readonly issues: readonly Issue[];
+  readonly checks: Readonly<{ local: CheckResult<Value>; review: CheckResult<Value> }>;
+}
+```
+
+Generation／review use a Map to support partial correction and lookup by ID; final results use an array to preserve input delivery order. This is a difference in purpose, not arbitrary reshaping of a same-named collection field.
+
+Standalone issues must be covered; unknown itemIds, duplicate ownership, and illegal references are rejected. reviewPolicy preserves the required/optional/off semantics: a confirmed factual error cannot be released just because later review is unavailable. Repairs apply only to failed items, and fallback must be produced from real evidence. Cancellation, model calls, and repair quota continue to share the upper-layer boundary.
+
+## OutputCatalog
+
+```ts
+defineOutputCatalog(definitions, { providers?, observe? }): OutputCatalog
+catalog.toModelSchema(outputId): JsonSchema
+catalog.check({ outputId, value }): CheckResult<Readonly<Record<string, unknown>>>
+catalog.compose({ outputId, input }, context): OutputResult // 同步provider；误返thenable拒绝
+```
+
+Catalog extends the shared has/get/require/ids/values. Definitions still have the four kinds text/master/record/group and do not make them outputs required across all of Core.
+
+| Declared field | Contract |
+| --- | --- |
+| id | Output or field identity |
+| owner | generated/bound/constant/semantic, indicating the value owner, not the handler's this |
+| valueSchema | Optional SchemaAdapter; defaults to string; both model and program values go through the real parser |
+| providerId | Provider reference for program binding or semantic resolution |
+| constantValue | Program fixed value, snapshotted at registration |
+| semanticKeys | Exposes only the optional keys, never private mapping values |
+| allowedOutputIds | Output IDs allowed by a group |
+
+A provider uses `resolve({ key? }, context)`; the first argument describes the selection and the second provides the execution context. toModelSchema projects only generated fields and semantic keys; the program is responsible for bound/constant and real links. check can retain valid fields for partial repair, but compose re-parses／re-checks input internally, and only a passed result can continue composing. A check result is not a permission credential, and partially usable values cannot complete an overall output.
+
+OutputResult is `{ outputId, kind, value }`. Group children use program-assigned ids and outputId references; the model cannot register outputs, providers, or permissions on its own.
+
+## Masters, semantic slots, and bubbles
+
+| Factory／method | Shared contract |
+| --- | --- |
+| defineTextTemplate(master, options) | Pure compilation; render(values) substitutes once synchronously; errors.missingField creates an error |
+| defineSemanticSlots(definition) | namespace, keys, maxOccurrences; isValid(text): boolean |
+| replyBubbleTexts(input) | Keeps the existing plain-text／bubble extraction responsibility and returns readonly string[]; count and length limits are enforced by the registered output contract |
+| publishReplyEvents({ text, delivery }, context) | Returns AsyncIterable<AgentOutputEvent>, preserving backpressure and cancellation as consumers pull; pacing continues to use *Ms |
+| serializeOutputEvents(events) / textOutputEvents(chunks) | Preserves explicit conversion between events and text streams and is not an invoke return mode |
+
+Presentation handling is not responsible for fact verification or authorization. Generation requirements are called prompt/template; a program-held substitution structure is called master, and model body text must not be treated as an executable master.
+
+Full exports, exact reloads, and declaration sources are in the [public symbol reference](reference.md). Signatures in the examples are for reading only; omitted fields do not imply arbitrary extra options.
+
+### Content and check boundaries
+
+AnswerTask.describe projects the executable inputSchema as inputJsonSchema, avoiding the case where a same-named field is sometimes an adapter and sometimes bare JSON. For a generated field in OutputCatalog, an ordinary valueSchema parse failure forms a repairable Issue; AbortError, TimeoutError, and program provider exceptions continue to propagate. Final values for kind=text/master must be strings; record/group preserve their own structure.
+
+Knowledge document parts allow paragraph strings and named sections, and sections recursively contain parts; self reads only the section's direct paragraphs, while subtree includes subsections. document reads the whole document; sectionIds must be non-empty, deduplicated, and all existing; exceeding maxChars is rejected without truncating evidence. The same definition, revision, language, and selection produce a stable snapshot identity. Read operations only work on existing in-memory documents and provide no file or account authorization.
+
+Presentation's publishReplyEvents uses `({ text, delivery? }, context)`, with delivery defaulting to chunkSize=240, intervalMs=0, bubblePauseMs=0, maxDurationMs=3000. It slices by Unicode characters; intentional pacing is constrained by maxDurationMs, and consumer pulling still provides backpressure. serializeOutputEvents converts for consumers that explicitly need a text stream protocol; it is not another output mode of invoke.
+
+Check results must include an issues array; it is empty when passed and contains at least one item when failed. The check catalog, local checks, and review use the same contract, with path as a string／number array. Explicitly returning value: undefined is still a sanitizer update and must not be confused with a missing value.
+
+signal／diagnostics are passed through the execution context. See [Basic example](../examples/offline-agent.md) for complete offline App integration of models and tools; configure the local contracts of Knowledge／Answering according to this page.

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

@@ -0,0 +1,186 @@
+# The MockGPT simulated model Kit
+
+MockGPT simulates model replies with fixed data, functions and lightweight text algorithms, and is suited to debugging protocols, tool selection, streaming output, failure and cancellation. It does not perform real LLM inference. Ordinary rules do not use the network; the web source is an explicit optional network capability.
+
+## Entry points and public exports
+
+| Entry | Runtime exports | Type exports |
+| --- | --- | --- |
+| `@jangts/agent-core/mock` | `MockGPT`, `generators`, `generatorNames`, `responses`, `ResponseDescription`, `MockGPTError`, `routes`, `encodeModelResponse` | `JsonValue`, `Message`, `ModelRequest`, `GenerationInput`, `GenerationOptions`, `GenerationContext`, `Generator`, `Generated`, `Rule`, `MockGPTOptions`, `CallRecord`, `ToolCall`, `OutputOptions`, `ModelOutput`, `HttpFault`, `Usage`, `TextSource`, `TextOptions` |
+| `@jangts/agent-core/mock/node` | `createMockServer`, `createMockHandler` | `ServerOptions`, `HandlerOptions` |
+| `@jangts/agent-core/mock/web` | `sources`, `isPublicAddress` | `WebOptions`, `LoadedPage`, `WebProfile` |
+
+Node HTTP and web extraction are imported from separate sub-entries; the root entry can generate data directly on the frontend or server. The three entries forward the same implementation and do not define a separate rule protocol.
+
+## Starting from a fixed reply
+
+### TypeScript
+
+```ts
+import { MockGPT, type MockGPTOptions } from '@jangts/agent-core/mock';
+
+const options: MockGPTOptions = {
+  rules: [{ id: 'greeting', prompt: '你好', generator: '你好，有什么可以帮你？' }],
+};
+const mock = new MockGPT(options);
+const value = await mock.generate({
+  model: 'demo', messages: [{ role: 'user', content: '你好' }],
+});
+console.log(value);
+```
+
+### JavaScript
+
+```js
+import { MockGPT } from '@jangts/agent-core/mock';
+const mock = new MockGPT({
+  rules: [{ prompt: '你好', generator: '你好，有什么可以帮你？' }],
+});
+console.log(await mock.generate({
+  model: 'demo', messages: [{ role: 'user', content: '你好' }],
+}));
+```
+
+`generate(input, options?) → Promise<Generated>`: input contains `model: string` and `messages: readonly Message[]` and may carry additional JSON condition fields; options accepts `signal`. Message has a required role, plus content, tool_calls, tool_call_id and extension fields.
+
+The return value is a standalone frozen snapshot of a string, native JSON or an explicit ResponseDescription. generate does not create an HTTP response and does not perform the delays, chunking or faults in the description; the caller interprets the description itself. Optional undefined fields of the input object are omitted; array holes, undefined array elements, circular references and non-JSON data are rejected. Output must likewise be complete valid JSON and cannot contain undefined.
+
+JSON snapshots are limited to 64 levels and 100,000 value nodes; an over-limit request is `MOCK_REQUEST` (400), and an over-limit generation result is `MOCK_GENERATION`. Fields are read once and no hidden `toJSON` is executed; names such as `__proto__` are kept as ordinary own data fields.
+
+`encodeModelResponse(request, output, id, created, signal, finish)` encodes a validated model result as a Chat Completions JSON／SSE Response. `created` uses Unix seconds; `finish(error?, cancelled?)` is called when the response completes, fails or is cancelled. The adapter owns request validation, first-packet delay, ID and lifecycle; the encoder owns content chunking, backpressure, tools, usage and the terminal frame, and does not execute rules or modify MockGPT records.
+
+## Instance configuration and rules
+
+| MockGPTOptions | Semantics／default |
+| --- | --- |
+| rules | Required, ordered Rule array |
+| fallback | Optional Generator; fails when nothing matches and there is no fallback, and does not forward to a real model |
+| selectPrompt(request) | Synchronously returns the matching text; by default takes the text blocks of the last user message and joins them with newlines in their original order |
+| stream | Instance defaults chunkSize=24, intervalMs=0, optional wireChunkSize |
+| seed | Random initial value, default 1; 0 to 4294967295 |
+| clock | Function returning milliseconds, default current time |
+| recordLimit | Maximum number of retained records, default 100; 0 to 10000 |
+| maxBodyBytes | Byte limit for fetch request bodies, default 1048576, positive safe integer |
+| maxOutputChars | Output character limit, default 1000000, positive safe integer |
+
+Rule requires `generator`; `id` may be omitted and is generated from position, and explicit IDs must be unique. `prompt` accepts an exact string or a regular expression, `model` restricts the model name, `when(request)` is a synchronous boolean predicate, and `times` is a positive integer hit limit. Declaration order determines priority: the first rule that satisfies all conditions and is not exhausted runs.
+
+A Generator is JSON／string／ResponseDescription, or `(context) => Generated | Promise<Generated>`. context contains the frozen request, the projected prompt, the regex match, the global callIndex, the hit ruleIndex of the current rule, signal, random, clock and report(metadata). request is a standard request containing model, messages, stream and optional tools／stream_options.
+
+On a hit, the hit count and sequence number are allocated and are not refunded on failure or cancellation. A fixed seed reproduces output verbatim only when the call order, clock, callbacks and external environment are also fixed. Configuration is stored as a snapshot; external state captured by callback closures remains the caller's responsibility.
+
+## Input-dependent generators
+
+All generators come from `generators`; `generatorNames` gives the names in that same registry.
+
+| Method | Parameters and result |
+| --- | --- |
+| summary(options?) | Extracts representative sentences; default at most 240 code points and 3 sentences |
+| bullets(options?) | Bullet text; default at most 500 code points and 3 items |
+| keywords(options?) | JSON string array sorted by word frequency; count defaults to 3 |
+| title(options?) | Title from the first sentence; default at most 24 code points |
+| reply(options?) | Simulated reply; default at most 500 code points; may provide template({ text, previous }) |
+| extract(options?) | Returns a field object; fields is a dictionary from name to regular expression, taking the first capture group or the full match, and null when there is no match; defaults to email/date/amount |
+| integer(min?, max?)／float(min?, max?) | Returns a number generator function; integers default 0 to 100, floats default 0 to 1 |
+| boolean()／pick(items) | Returns a boolean／option generator function; items must be non-empty |
+| id(prefix?)／date()／sentence() | Returns an ID／ISO date／built-in sentence generator function; the ID prefix defaults to mock |
+| imageUrl({ width?, height? }?) | Returns a local SVG data URL generator function; default 320×180, side lengths 1 to 4096 |
+| sequence(items) | Selects a Generator from a non-empty list by rule hit sequence number, and fails when exhausted |
+| toolCall(name, arguments, options?) | Generates an explicit tool proposal and does not execute the tool |
+
+TextOptions supports `source: string | (context => string | Promise<string>)`, `maxChars` (1 to 30000) and `count` (1 to 100); source defaults to prompt. summary／bullets use sentence ranking and repetition control, analyze at most 30000 code points and 180 distribution candidate sentences, and sample over-long sources from the beginning／middle／end; the other text generators analyze at most the first 30000 code points. JSON arrays and objects are not truncated into invalid JSON for character limits. These algorithms provide no guarantee of semantic reasoning accuracy.
+
+```ts
+import { MockGPT, generators } from '@jangts/agent-core/mock';
+const age = generators.integer(18, 60);
+const mock = new MockGPT({
+  seed: 42,
+  rules: [
+    { prompt: /总结/, generator: generators.summary({ maxChars: 120 }) },
+    { prompt: '用户资料', generator: context => ({ age: age(context) }) },
+  ],
+});
+```
+
+The example above also works directly as JavaScript. Field generator functions should be evaluated with the current context inside the generator callback and cannot be returned directly as JSON fields.
+
+## Explicit responses and faults
+
+`ResponseDescription` distinguishes model, http and reject by kind and value; ordinary JSON does not become transport control because of a field with the same name.
+
+| helper | Input／product |
+| --- | --- |
+| responses.text(content, options?) | Text ModelOutput description |
+| responses.toolCalls(tools, options?) | Tool array description with content=null; each item contains name, JSON arguments and an optional id |
+| responses.httpError(status, body?) | HTTP 400 to 599; the default error.message is a simulated error description |
+| responses.reject(message?) | Network failure description |
+
+OutputOptions: `finishReason` is stop／length／tool_calls／content_filter; `usage` contains prompt_tokens, completion_tokens and total_tokens, all non-negative safe integers whose total is consistent. `delayMs` is the first-response delay and `intervalMs` the frame interval, both default 0; `chunkSize` controls the code points of content／tool deltas, and `wireChunkSize` splits SSE further by bytes; `interruptAfter` interrupts after the specified data frame without sending a successful end marker. Chunk sizes are 1 to 1000000, delays／intervals 0 to 60000 milliseconds, and the interrupt frame count 0 to 60000.
+
+```js
+import { MockGPT, responses } from '@jangts/agent-core/mock';
+const mock = new MockGPT({ rules: [
+  { prompt: '限流', generator: responses.httpError(429, { error: { message: 'limited' } }) },
+  { prompt: '中断', generator: responses.text('逐步输出', { chunkSize: 1, interruptAfter: 2 }) },
+  { generator: responses.toolCalls([{ name: 'lookup', arguments: { id: 'demo' } }]) },
+] });
+```
+
+## fetch and the streaming protocol
+
+`mock.fetch(input, init?) → Promise<Response>` is a bound standard fetch callback that can be injected directly into clients that accept a custom fetch. `routes` lists the supported routes: POST `/v1/chat/completions` and `/chat/completions`. Plain JSON returns a single choice, and a plain JSON product is encoded as JSON text in message.content; stream=true returns SSE. Only n=1 is supported, and explicit usage enters the SSE usage chunk only when the request sets stream_options.include_usage; real tokens are not estimated.
+
+```js
+const response = await mock.fetch('https://mock.local/v1/chat/completions', {
+  method: 'POST',
+  body: JSON.stringify({ model: 'demo', messages: [{ role: 'user', content: '你好' }] }),
+});
+console.log(await response.json());
+```
+
+It does not intercept the network globally and does not forward to a real model. HTTP errors return the corresponding Response; network faults reject fetch; a stream interruption is expressed by a failed read of response.body. Request cancellation prevents generators that have not started and aborts delays, streams and waits; external side effects already emitted are not rolled back automatically, and custom generators should cooperate with signal.
+
+## Node HTTP server
+
+```ts
+import { MockGPT } from '@jangts/agent-core/mock';
+import { createMockServer } from '@jangts/agent-core/mock/node';
+const mock = new MockGPT({ rules: [{ generator: '调试回复' }] });
+const server = createMockServer({ mock });
+const address = await server.listen({ port: 4317 });
+console.log(address);
+// 调试结束：await server.close();
+```
+
+JavaScript uses the same form. HandlerOptions contains the required mock, maxBodyBytes (default 1048576), requestTimeoutMs (default 30000), allowedHosts and allowedOrigins; ServerOptions additionally has closeTimeoutMs (default 1000 milliseconds). `createMockHandler(options)` returns a Node IncomingMessage／ServerResponse handler that can be mounted on an existing HTTP server.
+
+`listen({ host?, port? }?)` defaults to the loopback host and port 4317, and port=0 is for temporary tests; it returns `{ host: string, port: number, url: string }`. Closing cancels in-flight requests and is bounded by the close deadline; repeated listen while starting, listening or closing is rejected with MOCK_ACTIVE; concurrent close waits for the same shutdown, and the server can listen again after it closes.
+
+Host is validated before Origin. By default only localhost, loopback addresses and the local address the connection arrived on are accepted; an explicitly bound host name is also usable. allowedHosts explicitly lists proxy host names and does not support wildcards; allowedOrigins authorizes cross-origin sources separately and does not relax Host. A proxy cannot bypass target validation by forging Origin.
+
+## Web source
+
+```js
+import { MockGPT, generators } from '@jangts/agent-core/mock';
+import { sources } from '@jangts/agent-core/mock/web';
+const mock = new MockGPT({ rules: [{
+  generator: generators.summary({ source: sources.web({
+    url: 'https://example.com/', timeoutMs: 20000,
+    fallback: '无法取得网页正文，请提供文字材料。',
+  }) }),
+}] });
+```
+
+`sources.web(options?) → TextSource` fetches HTML or plain text and extracts the body; it is not a browser and does not log in, carry cookies or carry model credentials. WebOptions: url is a fixed HTTP(S) URL or a synchronous context selector function; when omitted, the prompt must contain exactly one URL. profile uses browser; the type also accepts crawler (identical request headers); headers are used only for restricted content negotiation. timeoutMs defaults to 20000 and covers the full download; maxBytes defaults to 2097152, maxChars to 30000 and maxRedirects to 3.
+
+Only public addresses are allowed, and DNS and redirects are checked hop by hop; `isPublicAddress(address)` returns a boolean for whether the address is usable. Local, private, special-purpose addresses and URLs carrying credentials are rejected. fallback is the alternative source text used when reading fails; it still passes through the text generators and records sourceFallback; cancellation, invalid URL and target address rejection are not turned into a successful fallback. Verification pages, login redirects, firewalls and upstream HTTP failures keep their real cause.
+
+A trusted `load(url: URL, signal, maxBytes) → Promise<LoadedPage>` can be injected for offline or custom reads; LoadedPage is `{ bytes: Uint8Array, url: string, contentType: string, status?: number }`, and an omitted status is treated as 200. A custom load owns its own target access policy and cannot be injected by a remote request.
+
+## Records, cancellation and errors
+
+`mock.records` returns a CallRecord snapshot: id, index, model, optional path／ruleId, fallback, status (pending/completed/error/cancelled), optional errorCode, metadata. Requests and generated bodies are not stored by default, and report accepts only bounded JSON metadata. `mock.counts` returns rule hit counts, and `activeRequests` contains streams that have not completed. `reset()` clears records, counts and random state; it is rejected with MOCK_ACTIVE while requests or streams are active.
+
+MockGPTError carries code, status and optional details. Common codes: MOCK_CONFIG invalid configuration, MOCK_REQUEST invalid request, MOCK_BODY_LIMIT／MOCK_OUTPUT_LIMIT budget exceeded, MOCK_RULE_NOT_FOUND no match, MOCK_SEQUENCE_EXHAUSTED sequence exhausted, MOCK_NETWORK network fault, MOCK_HTTP simulated HTTP fault, MOCK_ACTIVE active lifecycle conflict. Cancellation preserves the caller's signal reason; fetch may encode a respondable error as an error response, and custom generator exceptions are recorded as failures without fabricating successful content.
+
+These budgets limit simulated execution and do not replace the Agent's real model／tool budgets and permissions. Tool proposals are always authorized and executed by the caller; low-level negative cases such as hand-written broken SSE and invalid bytes are still expressed by dedicated fixtures.

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

@@ -0,0 +1,166 @@
+# Requests, call chains, events and Journal
+
+[Back to the API handbook](README.md) · [Core](core.md#journal-and-diagnostics). Core records runs, calls and registered entities. An App's accounts, HTTP requests and Q&A records are linked to runId in its own data model.
+
+## One fact per record, relations at the top level
+
+Core emits events one by one through the optional CoreLogOutput; it neither packs the whole call tree into a single JSON nor keeps only one summary per model Q&A. Model request／output, tool start／completion and workflow transition／failure each have their own event; they share the same v2 outer layer, and payload expresses differences by type:
+
+```ts
+interface CoreDiagnosticRecord extends DiagnosticIdentity {
+  readonly version: 2;
+  readonly eventId: string;
+  readonly type: CoreEventName;
+  readonly producerSequence: number;
+  readonly occurredAtMs: number;
+  readonly payload: unknown; // 未可信存储输入；CoreEvent按type关联具体载荷
+  readonly usedModel?: boolean; // 本次节点自身上报；未上报保持未知
+  readonly subSteps: readonly RecordedSubStep[];
+  readonly subStepsDropped: number;
+  readonly subStepsTruncated: boolean;
+}
+```
+
+| Field | Responsibility |
+| --- | --- |
+| runId | Identity of one Core run, obtained by the caller before the run; not automatically equal to requestId or messageId |
+| spanId/parentSpanId | Current execution boundary and its direct parent boundary; queries do not rely on parsing span paths |
+| invocationId/parentInvocationId | Real model or tool call and its calling parent; not a provider function-call ID |
+| workflowInvocationId | Scope of one explicit workflow call; nested workflows have their own identity and parent relation |
+| eventId | Identity of this execution fact; consistent with the fact ID seen by the workflow observer |
+| producerSequence | Sequence starting at 1 within the Core diagnostics context tree; it cannot stand in for a cross-source total order or a causal proof |
+| occurredAtMs | Millisecond time at which the Core fact was produced |
+| definitionId/definitionKind/definitionRevision | Registered entity and available revision information |
+| nodeId/nodeName/nodeKind/nodeDescription | Basic description of this boundary; storing the whole historical configuration is not required |
+| nodeRole | workflow-node/workflow-boundary/invocation/loop-step, preventing a local call from being taken for main-flow dispatch |
+
+The invocation in a successful tool or model return, the corresponding event and the Journal share the same call identity. Compression models and real nested tool calls each have their own invocationId and are linked to the parent call; pure wrapping does not create an already executed business operation out of nowhere. Re-entering the same workflow node has a different span; an identical static nodeId does not mean the same visit.
+
+## The Journal is not a second persistent log
+
+ContextJournal is the in-memory context projection for this round, used so that the model can keep referring to real call receipts; it does not create a database or store a separate execution history. Model and tool start records share the invocationId deduplication scope, so duplicate model records or model／tool identity collisions are rejected; a failed snapshot does not occupy that identity. Records use type, producerSequence, occurredAtMs and InvocationMetadata:
+
+```ts
+journal.model({ stageId, value, invocation }): void
+journal.beginTool({ toolId, input, invocation? }): string
+journal.finishTool({ invocationId, status, value }): void
+journal.snapshot(): readonly ContextRecord[]
+```
+
+The model submits value after parsing, delivery and cancellation checks; tool start／end reuse the same invocationId. By default no numbers such as call-1 that cannot be correlated across instances are produced. A missing call or a duplicate end is rejected. snapshot is a copy. Only named requests and the success/error/cancelled statuses are accepted, and records use type, value, toolId/stageId.
+
+The Journal and diagnostics project the same actual execution boundary but are not guaranteed to have identical contents: the Journal keeps the business values needed for this round, diagnostics record execution facts per collection rules, and closing diagnostics does not change the Journal or business execution. When persistence is required, the App wires up CoreLogOutput and must not treat a Journal sequence number as a new real call.
+
+## Real workflows, failures and boundaries not entered
+
+WorkflowEvent has required eventId, workflowId, workflowInvocationId, nodeId, roundIndex and type. The targetSpanId of transition/error points to the **selected next visit**; only the corresponding enter event proves actual entry. When cancellation, budget rejection or log loss happens after selection, the target must not be drawn as executed.
+
+The errorEventId of an error event is passed along the recovery context; the failure phase and failedRouteId locate the problem. Cancellation, budget and contract errors cannot be recovered into a success that was never executed. A failure before node entry is marked workflow-boundary and does not fabricate a second enter. The raw engine.run produces only loop.event and does not borrow the identity of the main workflow node.
+
+ModelCallTrace and ToolExecutionEvent use success/error/cancelled; check passed/failed belongs to business checks and does not override whether the model call completed successfully. ToolRegistry keeps tool identity and start／completion facts under metadata collection; input/value, detailed errors and subSteps are attached only when content collection is permitted. Pre-check rejections and accepted attempts are recorded separately, and a single error does not imply that the provider necessarily received the request.
+
+## State and output during a run
+
+Core invokes the receivers registered by the App and does not manipulate the interface directly. Fixed flows, model／tool calls and dynamic node progress use the same `CoreEvent` outer layer and are distinguished by `type`. The same fact received by logs and listeners has the same eventId, time and call relations; content collection rules and copies are isolated from one another.
+
+```ts
+const agent = new AgentCoreEngine({
+  workflow, model: { provider },
+  execution: { observe: {
+    // 默认只接元数据。仅对明确需要的进度报告开放内容。
+    accepts: ({ event, content }) => content === 'metadata' || event === 'node.progress',
+    event(fact) {
+      if (fact.type === 'model.start') showStatus(fact.workflowNodeId);
+      if (fact.type === 'node.progress') showProgress(fact.payload.payload);
+    },
+  } },
+});
+await agent.run(state);
+```
+
+| Access point | Content | Guarantee |
+| --- | --- | --- |
+| execution.observe.event | Loop／Workflow, model.start／end, tool start／end and permitted dynamic reports | Side channel; a synchronous throw, async rejection or hang does not change execution; still effective when persistent logging is closed |
+| execution.diagnostics → CoreLogOutput.write | Optional persistent projection of the same fact | The App decides fields, body, storage and retention; it gains no content authorization from other listeners |
+| ModelRunner.sink.output | model.start／output／parsed of the same outer layer, plus model.end on success, failure or cancellation | Body waits in order, propagates failures and preserves backpressure; the end notification is limited to 250 milliseconds independently, and its failure does not override the result or the original exception |
+| context.report({ usedModel, payload, subs }) | Immediate report during the current node's run | usedModel is optional boolean metadata, payload／subs are read only when content is permitted; Core fills in identity, time and sequence, and reports after the node ends or is cancelled are dropped |
+| node report(update, context) | usedModel／payload／subs on completion／transition | Evaluated only when content is permitted; does not replace immediate reports during the run |
+| context.createSubFlowLogger() | Sub-log instance bound to this execution | write records first, fix completes later, readAll obtains a fixed-format snapshot; reuses the existing node.progress outlet |
+
+Listeners can filter by metadata such as event, nodeId and workflowNodeId. workflowNodeId keeps the owning Workflow node, while model／tool boundaries still have their own nodeId and invocationId. Repeated visits to the same node have different spans, and concurrent runs do not correlate through lastCall or a shared "current request". `withObserver` can be called on an existing request scope to add a listener, inherited along sub-scopes; this is immutable wiring and leaves the original scope unaffected. Canonical methods are bound to their original receivers at assembly time. When a reusable Engine has no request scope configured, each run is assigned an independent identity.
+
+Listeners without accepts receive metadata only. Content events, payload and subs are collected only after the corresponding consumer explicitly accepts them; other metadata consumers do not gain the body as a side effect. Each consumer receives an independent copy. The result snapshot is isolated from the actual return value, so preview edits do not rewrite the final value; model results must still satisfy the existing Journal snapshot contract.
+
+ModelPart does not provide separate reasoning content chunks. State, process notes explicitly provided by the model, tool facts, transient previews and the final answer each keep their own meaning; internal hidden reasoning or the raw protocol must not be treated as a user reply. Selection, compression and assembly can be registered as ordinary nodes separately and use real lifecycle facts; algorithmic reports are delivered as permitted node.progress.
+
+Adding a listener only changes assembly configuration; the original Workflow, run and model result contracts are unchanged.
+
+## Sub-log instances and record-first-then-complete
+
+Workflow nodes, simple run(step), ToolRegistry／Support tools and the execution context of executeInvocation all provide `createSubFlowLogger()` and `report()`. Each node visit or call has one instance, and repeated create returns the same instance; no global logger is shared. subs accepts only SubFlowLogger instances belonging to that execution; plain objects, objects imitating readAll, hand-written arrays and readAll() snapshots are rejected; invalid material does not become a main execution fact. The normalized stored field subSteps is still an array, so reading historical data does not require re-creating a logger.
+
+```ts
+async run(state, context) {
+  const subs = context.createSubFlowLogger();
+  const id = subs.write({ name: '查询资料', kind: 'retrieval', payload: { query: state.question } });
+  // write 已记录意图；即使后续短路，也保留这条计划。
+  if (!state.canRead) {
+    subs.fix(id, { status: 'skipped', usedModel: false });
+    return;
+  }
+  subs.fix(id, { status: 'running' });
+  try {
+    const result = await readSource(state.question);
+    subs.fix(id, { status: 'success', usedModel: false, payload: { result } });
+  } catch (error) {
+    if (!context.signal.aborted) subs.fix(id, { status: 'error' });
+    throw error;
+  }
+  context.report({ usedModel: false, subs });
+}
+```
+
+| Method | Fixed contract |
+| --- | --- |
+| write(input): string | name and kind are required, status defaults to planned; stepId, sequence, createdAtMs and initial revision=1 are allocated automatically. Optional parentStepId, relatedDefinitionId, caseId, nextStepIds, status, time, summary, payload and usedModel. startedAtMs is recorded automatically only when running is reported explicitly, so planned time does not pass for an actual start. |
+| fix(stepId, patch): void | Completes status, model usage, pending times, summary, successors or payload fields for a record in the same instance; a terminal state cannot be reopened, but missing result fields can still be filled while execution is active. Keeps the ID, first order and original times, incrementing revision each time. payload merges missing keys recursively and existing facts cannot be overwritten; a given summary, time or successor cannot be rewritten. |
+| readAll(): readonly RecordedSubStep[] | Returns an immutable snapshot in first-write order; later fix calls do not change an earlier snapshot. With no steps it is [], and the snapshot remains readable after the execution is closed. |
+
+The fixed record fields are origin=reported, stepId, sequence, name, kind, status, createdAtMs and revision, plus the optional fields above. planned／unknown can advance to an actual status, while running cannot go back to planned or skipped; success／error／cancelled／skipped are terminal, the status and established facts cannot be rewritten, but pending result fields can still be filled while the owning node is active. Statuses and legal transitions come from the same reportedStepStatusCatalog. A retry writes another record and does not reopen a terminal state. The parent and successors must belong to the same logger; when the successor ID is not yet available, nextStepIds can be completed in one later fix. Pending payload fields are omitted first and are not represented by null or an empty array as an overwritable placeholder. By default at most 256 records, 65536 JSON characters for the full snapshot and 1024 write/fix calls; payload accepts only bounded-depth JSON data and does not accept functions, service instances, circular references or internal getters.
+
+write and fix emit the initial／completion event through the existing node.progress at that moment, with payload.subStep holding operation, stepId, sequence, revision, createdAtMs, status and optional usedModel metadata. When content is permitted, the event carries the fixed-format subSteps snapshot at that point; node end／failure events also carry the last snapshot. The log appends revisions, and events already emitted are not updated in place. Results returning out of order do not change the initial order, and replay can distinguish "only a plan at the time" from "a result later". When only a plan or start was received without a result, the original status is kept; success, failure or an actual model call cannot be inferred.
+
+The main node reports through context.report({ usedModel: true | false }) whether it used the model this time, and the outer usedModel in the log is kept as metadata; sub-steps report their own usedModel through write／fix. Unreported stays unknown and does not default to false; a reported true cannot change back to false. A child's true is not automatically aggregated into the main node's original marker. This is a node report: a field of true does not fabricate model.start／end or call counts, and model internal hidden reasoning is not collected. The end report(update, context) is still evaluated only when content collection is permitted; markers that must be kept in metadata mode should be submitted during the run with context.report.
+
+Content permission continues to be decided per event and per consumer. Without content authorization, payload／summary getters are not read, nor are the private payload／subs getters in reports; only permitted status, revision and boolean metadata are kept. The instance closes when execution ends or is cancelled, and write／fix reject late modifications. Log shutdown, outlet failure or a process crash still follow the original failure isolation and incomplete mechanism; recording intent first does not constitute a transactional audit guarantee.
+
+## File adaptation and relational table mapping
+
+An App can connect CoreLogOutput.write to its own file or database adapter. Core events are stored flattened, and the App／storage fields source, traceId, app, sequence and recordedAtMs are filled in by the adapter, which Core does not depend on; other application diagnostics can still use the original record interface. Files can be segmented by source; they belong to the same run session and are not another Journal persistence ledger.
+
+The collector sequence links the persisted observation order of sources such as App and Core; producerSequence keeps the producer's original sequence. occurredAtMs and recordedAtMs are preserved separately. The adapter continues to use the existing redaction, body switch, bounded queue, segmented／large-payload files and retention period; side-channel failures do not change business results, and queue drops or write failures mark incomplete. This interface provides no transactional audit or exactly-once guarantee.
+
+Relational databases can record this without mesh JSON and map it directly:
+
+| Object | Main relation columns | Details |
+| --- | --- | --- |
+| runs | run_id, started_at_ms, ended_at_ms, status, incomplete | Run summary |
+| spans | run_id, span_id, parent_span_id, invocation_id, parent_invocation_id, definition_id | Boundary summary |
+| events | event_id, run_id, span_id, invocation_id, type, sequence, producer_sequence, occurred_at_ms, recorded_at_ms | payload JSON per type; necessary bodies stored as separate references |
+| App message_run_links | message_id, run_id, relation and account isolation columns | App-owned user Q&A links |
+
+This is a feasible mapping, not a created SQL table or an SDK built-in repository. Queries are authorized by the App; one input can trigger multiple runs, and a failed／cancelled run without final output can still be linked to the input message; Core does not query App message tables back. Parent/child keys can be used for recursive upstream／downstream queries; do not guess relations from time proximity or text similarity. Storage may idempotently project summaries of the same fact and handle out-of-order and missing data, but the last persisted row cannot be treated as the authoritative completion state.
+
+## Event format validation
+
+normalizeDiagnosticEvent(input) accepts version=2, validates identity, time, sequence and reported steps, and produces an independent copy. Missing identity or unsupported versions are rejected.
+
+The payload at the read boundary is unknown, and outer validation does not equal validating arbitrary business JSON. The write interface CoreEvent associates CoreEventPayloads by type; for the exact event catalog and fields see the [public declarations](reference.md).
+
+## Difference between facts and reports
+
+Only workflow nodes actually dispatched by the Loop are primary visits; a node calling a local function does not produce an additional dispatched node. subSteps is optional, bounded reported material and must not be treated as a Core dispatch fact or a static subgraph. Only the target enter event proves entry; a selected route target or the last persisted row must not be treated as proof of execution. The App owns user input／final output and message links itself.
+
+## Large records in file adaptation
+
+When the `@jangts/diagnostics` file adapter is used, payload, subSteps and redactions in a large record are stored as body domains of the same validated attachment; the reference row keeps identity and index information. The reader restores the record after validating the attachment scope, size, SHA-256 and applicable identity. Attachments and return budgets are still configured explicitly by the App; Core itself does not own file storage.