@jangts/agent-core 0.2.0 → 0.2.5

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

@@ -0,0 +1,252 @@
+# Support: assembling against shared contracts
+
+[Shared types](types.md) · [Back to home](README.md). Support is used from the root namespace and provides implementations that conform to Core interfaces.
+
+## SchemaAdapter
+
+```ts
+Support.defineSchema<Value>({ jsonSchema, parse }): SchemaAdapter<Value>
+Support.fromJsonSchema(jsonSchema, { compile, error? }): SchemaAdapter<unknown>
+Support.fromParserSchema(schema, { toJsonSchema }): SchemaAdapter<Output>
+```
+
+defineSchema accepts an explicit raw schema and parser, copies jsonSchema, and fixes the parser reference and receiver. fromJsonSchema reuses the App's validator/compiler; fromParserSchema connects existing parser libraries such as Zod and does not maintain a second JSON Schema.
+
+Schema compilation, conversion, validation, parsing, and error factories are all synchronous contracts; an unexpected Promise/thenable return immediately throws TypeError and observes the late rejection. `compile` must return a validator function when the adapter is created, and the validator must return a boolean at runtime.
+
+A bare JSON Schema provides no TypeScript business type proof, and fromJsonSchema returns unknown by default; when Value inference is needed, use a parser that returns a validated Value or a typed compiler port, and never pass an arbitrary <Value> assertion off as type inference.
+
+All three functions return the same SchemaAdapter structure; the mode is not guessed from whether inputSchema happens to contain parse/jsonSchema fields. The parser is synchronous; asynchronous business reads and authorization belong in the execution handler.
+
+## Tool declarations and catalogs
+
+```ts
+interface ToolDefinition<Input, Output, App> {
+  readonly id: string;
+  readonly kind: string;
+  readonly description: string;
+  readonly inputSchema: SchemaAdapter<Input>;
+  authorize(input: Input, context: OperationContext<App>): MaybePromise<void>;
+  execute(input: Input, context: OperationContext<App>): MaybePromise<Output>;
+  parseOutput(value: unknown): Output;
+}
+Support.defineTool<Input, Output, App>(definition): ToolDefinition<Input, Output, App>
+Support.defineToolCatalog(definitions): ToolCatalog
+```
+
+authorize returns void on approval and throws on rejection. When adapting existing boolean permission functions, evaluate the result inside the callback and throw the App's authorization error. Support fixes methods and receivers at registration and validates the completion value of asynchronous authorization. parseOutput parses the tool execution result.
+
+```ts
+catalog.select(toolIds): ToolCatalog<SelectedDefinitions>
+catalog.bind({ app, execution }): ToolRuntime
+runtime.invoke({ toolId, input }): Promise<ToolResult<InferredOutput>>
+```
+
+catalog.capabilities projects the same jsonSchema from the tool declarations; its capability adapter checks only the raw parameter object and the selection contract, resolve returns `{ toolId, input }`, and input keeps the raw parameters. It does not run the tool's business inputSchema.parse early; the tool parses once in the real invoke before authorization and execution, avoiding repeated runs of transforming parsers. A custom model stage may register its own parsing and resolve, but a converted value must not be passed off again as the tool's raw input.
+
+Catalog implements the shared read-only collection interface. After a static selection, the inferred tool IDs and result types narrow together; dynamic IDs go through the unknown boundary. Context/App do not enter the model schema and cannot be overridden by model parameters.
+
+The return shape is always `{ value, invocation }`, with the actual tool result in value; execute/parseOutput handle only business values and do not construct call receipts themselves.
+
+runtime is created per request; all input, authorize, execute, and output callbacks receive or use the same effective signal. Cancellation, unknown tools, and input or output rejection can never write a success receipt. A static schema description by itself does not prove execution.
+
+The same binding provides asynchronous `invoke` and explicit synchronous `invokeSync`. Both reuse the same Core registry, authorization checks, and receipt recording.
+
+## App capability composition
+
+```ts
+Support.defineCapabilityCatalog(definitions, { toolReferences? }): CapabilityCatalog
+Support.validateToolReferences(toolIds, references): void
+Support.defineRegistrationCatalog(definitions): RegistrationCatalog
+```
+
+Modules use id, description, and tools. The primary key of a tools item is id; reference explicitly states requiredToolIds/optionalToolIds. The composed result inherits the shared Catalog operations and provides tools and findToolOwner(toolId); an unknown owner returns undefined.
+
+The composition layer only verifies references and assembly and does not understand the App's business completion or recovery fields. RegistrationCatalog uses a definitions array, and install(app) registers in declaration order under when conditions. Static registration, deployment configurability, and per-request authorization are judged separately; a single enabled flag does not replace all three.
+
+## Model transports and stages
+
+```ts
+Support.createTextTransport({ id, options? }): ModelTransportDefinition<string>
+Support.createJsonTransport({ id, outputSchema, options? }): ModelTransportDefinition<Output>
+Support.createModelTransport({ id, capabilities, adapter?, options?, requireStrictArguments? }): ModelTransportDefinition
+Support.createStageModelTransport({ id, capabilities, stages, adapter?, options? }): ModelTransportDefinition
+```
+
+`createJsonTransport` is used to generate JSON values that conform to a Schema directly, such as summaries, classification results, or tabular data. `outputSchema` is an ordinary `SchemaAdapter<Output>` containing `jsonSchema` and a synchronous `parse(value)`; it can be provided directly, built with a Support Schema factory, or passed as a stateful class implementation. The parser is called after JSON decoding; declaring a JSON Schema does not replace runtime validation.
+
+```ts
+const summary = Support.createJsonTransport({ id: 'summary', outputSchema: {
+  jsonSchema: { type: 'object', properties: { text: { type: 'string' } }, required: ['text'], additionalProperties: false },
+  parse(value: unknown) {
+    if (!value || typeof value !== 'object' || !('text' in value) || typeof value.text !== 'string') throw new TypeError('需要摘要正文');
+    return { text: value.text };
+  },
+} });
+const model = new ModelRunner({ provider, transports: [summary] });
+const result = await model.invoke({ input: '概括资料', transport: summary });
+console.log(result.value.text, result.invocation);
+```
+
+The ID keeps its literal type; after registration the original transport handle or the ID can be used for calls. Each call creates a new collector, and parts accumulate only within that call. Invalid JSON, Schema parser rejection, asynchronous parsers, and function-call parts all propagate as failures and produce no deliverable success value. Input/output/Schema budgets, cancellation, and call limits continue to be enforced by the same Runner.
+
+It requires no capability list and introduces no capability/input envelope; when a model must choose among registered capabilities, use `createModelTransport` or `createStageModelTransport`. The JSON request mode and the JSON value types a provider actually supports are decided by the Provider. Output remains uniformly `{ value, invocation }` and does not become a bare object in JSON mode. `options` accepts only temperature overrides and does not relax Provider and Runner constraints.
+
+capabilities is a ModelCapabilitySource or a source factory read by stageId. A stages item uses `{ id, capabilityIds }`. Static sources validate all references at assembly, and dynamic sources refresh when the interaction is prepared for this call. An unknown stage does not invoke a dynamic source and does not extend to other stages.
+
+prepare(stageId) returns the unified collector protocol; a prepared interaction fixes the resolver and receiver for this call, and the next dynamic preparation can obtain a new source. Native and JSON adapters consume the same capability projection. The native adapter validates the object shape, index, ID, name, and argument strings of neutral function-call-delta values; invalid parts do not enter capability execution. The collector's outputChars counting and call metadata reading boundaries follow the [Core transport contract](core.md). Fallback is chosen explicitly by the App and is not guessed implicitly from model names or URLs.
+
+## Model strategy and budget
+
+```ts
+Support.createModelStrategy({ model, models?, reasoning?, reasoningOptions?, budget?, ...coreSettings }): ModelRunnerOptions
+```
+
+`model` accepts a model definition or an ID in `models`. `reasoning` selects a configuration explicitly registered in `reasoningOptions`; for example, high/off correspond to a Provider already configured with provider reasoning parameters. Unknown IDs or reasoning schemes raise errors, and model capabilities are not inferred from names.
+
+The budget defaults to medium. These are overridable local task budgets, not guarantees of provider capacity or performance:
+
+| budget | Scenario | maxCalls | maxInputChars | maxOutputChars | maxOutputTokens | callTimeoutMs |
+| --- | --- | --- | --- | --- | --- | --- |
+| small | Short task with few calls | 2 | 8000 | 4000 | 512 | 15000 |
+| medium | Ordinary multi-step task | 8 | 32000 | 16000 | 1024 | 30000 |
+| large | More calls and output space | 16 | 64000 | 32000 | 4096 | 60000 |
+
+Values apply from lowest to highest: the tier, the model definition, the reasoning configuration, exact values in the budget object, and top-level Core settings. Legitimate 0 and Infinity are preserved; an explicit undefined uses the Core default. A budget object uses medium as its baseline. All Core model fields can be passed, and the output is still the same ModelRunnerOptions. A result without a bound execution can be used directly as an Engine's model; request-level execution still belongs to the Engine and cannot be bypassed through a strategy.
+
+```ts
+const settings = Support.createModelStrategy({ model: { provider }, budget: 'small', maxCalls: 1 });
+const model = new ModelRunner(settings);
+```
+
+## Context
+
+```ts
+Support.defineContextFragments(definitions, options?): ContextBuilder
+Support.defineContextAssembly(definitions, options): ContextBuilder
+builder.fragments(input): readonly ContextFragment[]
+builder.plan({ input, maxInputChars?, originalFragments?, mutableFragmentIds?, additionalMessages? }): ContextPlan
+builder.build({ input, maxInputChars?, originalFragments?, mutableFragmentIds?, additionalMessages? }): BuiltContext
+```
+
+- ContextPlan.fragments are unassembled definition fragments; BuiltContext.fragmentUsage is used-amount metadata and must not also be called fragments.
+- A fragment uses id, sourceId, trust, lifetime, maxChars, role, and value. Business original text is data and is not promoted to a system instruction.
+- Formatting first obtains this call's input, then assembles by declaration order and budget; the current question, authorization conditions, and existing evidence cannot be trimmed at will.
+- ContextBuilder has no per-request signal. Selection and compression run as plain Workflow nodes, and their internal calls reuse the Core request budget and signal.
+
+Support strategy modes are `validate | reduce | audit`. `createContextProcessingNode` returns a plain WorkflowNode; when observation and routing must be separate, use `createContextSelectionNode` and `createContextReductionNode`. Core does not schedule by these modes; for concrete run boundaries, see [Context nodes](context-processing.md).
+
+`createContextStrategy` can use `preset: compact | balanced | extended` to generate a target character count at 25%/50%/75% of the fragment hard budget and keep the most recent 1/3/6 groups of original text; exact targetChars and keepGroups take precedence. The ratio expresses only character space, not semantic retention. Without a preset, the fragment hard budget and one group of original-text protection apply. The function can generate a recent-window or continuous-task summary configuration from registered historical fragments. It reuses fragment IDs/budgets, generation step IDs, and handler references; after exact overrides of targetChars, keepGroups, grouping, and selection it still uses the same node contract. The returned policy, compressors, and selectors can be configured directly into a plain processing node. A single strategy can configure the full selection (including model), selectors, compressors, steps, and character/token triggers and target watermarks; explicit steps fully replace generation steps and their dependencies; when steps are given directly, the generation-specific kind, fragment, field, and compressor can be omitted. Default selection is decided by the final step: fixed for a single step, sequence for multiple steps. When an array of strategies is passed, each item generates an operation, shared settings go in the second parameter, and execution defaults to sequential order. Duplicate steps or conflicting handlers are rejected at assembly. Each group defaults to user-turn and the most recent group's complete original text is kept; the numbers come from configuration and complete-round protection and do not promise model performance or summary quality.
+
+The budget can be configured once at assembly. Pass a number for a fixed budget, or `maxInputChars(input)` for a per-request calculation.
+Both forms use `builder.build({ input })` or `builder.plan({ input })`, adding a budget only for a single-call override.
+If no budget is configured or passed with the request, construction raises an error. `plan` and `build` both accept the additional messages and change-audit fields of the Core ContextPlan; user messages with images participate in the final budget, and build reuses Core auditing and assembly without silently dropping these fields. Processing entry points accept the same character budgets as Core (including Infinity); a zero budget must still pass the final actual usage check. Each processing call first fixes the plan and the contract fields of structured fragments, messages, and images, allows prototype getters, and does not let caller changes to the original plan during asynchronous processing alter an already-determined budget.
+
+## Provider, previews, and streams
+
+`CompatibleModelProvider.stream` also enforces the cancellation contract when used directly: an already-cancelled call sends no HTTP request, and waiting during the request/SSE can be stopped; if a request that ignores cancellation returns late, the adapter releases its unconsumed body. Body cleanup for HTTP or format errors is best-effort and does not overwrite the original classification; diagnostic body capture still has independent size and time limits and releases the reader.
+
+`writeSseFrame` requires `writer.write` to return a boolean synchronously; waiting for drain is protected by the unified cancellation wait. `readSse` checks cancellation before obtaining a reader and between events within a network chunk, and does not deliver buffered late events.
+
+| Interface | Preferred input / semantics |
+| --- | --- |
+| new CompatibleModelProvider | `{ config, ports?, observe?, errors? }`, where config accepts static configuration or a dynamic reader function |
+| createReplyPreviewRules | generates and validates preview rules from actual stage references, capability Schemas, and explicit display eligibility |
+| createReplyPreview | `{ rules, sink, render?, maxChars? }`, returning a handler for the model output sink to call |
+| streamEvents | `(producer, context)`, where producer must await emit and maintain bounded backpressure |
+| readSse | `(body, options)`, with signal and idleTimeoutMs in options, following real transport constraints |
+| encodeSseEvent | raw SSE event structure, preserving external event/data fields |
+| writeSseFrame | `({ writer, frame }, context)`, awaiting backpressure and propagating delivery errors |
+| scanJsonObjectFrames / parseJsonFrames | stay synchronous; the former only splits, the latter parses and limits the frame count |
+
+modelInteractionCatalog selects a native function or JSON adapter by an explicitly registered interaction ID; the App supplies selection metadata, can override explicitly, and does not infer capability from brand, model name, or URL.
+
+Preview rules use stageId and capabilityId; previews are transient and cannot authorize, persist, or execute model proposals. ModelOutputEvent goes to the sink and ProviderObservation goes to the observer; they are not mixed.
+
+External SSE/wire types can keep standard fields and are converted at the Support boundary; the protocol itself is not changed to standardize SDK spelling.
+
+The compatible Provider's `requestBody` is for provider extension fields. Model identity, input messages, streaming protocol, and token limits are controlled by the adapter and Core call contracts. Overriding these fields raises an error before the request is sent. To use another request protocol, implement the same `ChatProvider` interface directly.
+
+Completion determination is selected through `ports.completionPolicy` and defaults to `Support.completionPolicyCatalog.default`; whether function parts are accepted, the expected `finish_reason`, and integrity before `[DONE]` are all judged by whether the call declares `functions`, and a stream that ends without a finish marker still ends as `MODEL_INCOMPLETE`. `Support.completionPolicyCatalog.session` judges by the on-the-wire `tool_choice`: `auto` requires every started call to be complete and allows accompanying body text, `required` and a specific function object require at least one complete call, `none` rejects any function part, omitted fields adopt the default completion rules, and unknown values are rejected before sending as configuration errors. A policy only judges whether the response satisfies the request; it does not take over the request loop, transport protection, or tool execution. Cancellation and transport failures never become success because of a policy.
+
+`Support.createToolCallCollector` aggregates call parts by index, and the completion policy and direct callers share the same implementation. Conflicting part IDs, duplicate IDs across indices, and incomplete calls are rejected as protocol errors, and one complete call does not mask another incomplete call.
+
+The protocol layer never restricts receiving multiple call parts, and `parallel_tool_calls` is only a send field that expresses neither execution authorization nor scheduling policy. The single-proposal limit on the Agent path is decided by the `nativeFunctionInteraction` collector; using the Provider directly is not subject to that limit and does not thereby gain tool execution, authorization, or loop capabilities.
+
+`ProviderMessage` provides the `tool` result and assistant `toolCalls` shapes needed for direct connection, and `chatCompletionMessages` maps them explicitly to `tool_call_id` and nested `tool_calls`; mismatched roles or fields and incomplete call fields are rejected as `TypeError`. Only declared fields are sent, and extra fields (including raw wire fields) are not passed through; `toolCallId` must be a non-empty string, and `role` and `content` are validated per the message contract. The Core `ModelMessage` and `ChatProvider` abstract signatures are unchanged.
+
+A direct tool thread uses declared fields, the assistant `content` may be an empty string, and tool results are correlated by the same call ID:
+
+```ts
+import { Support } from '@jangts/agent-core';
+
+const messages: Support.ProviderMessage[] = [
+  { role: 'user', content: '查询资料' },
+  {
+    role: 'assistant', content: '',
+    toolCalls: [{ id: 'call-1', name: 'lookup', arguments: '{"query":"资料"}' }],
+  },
+  { role: 'tool', content: '{"found":true}', toolCallId: 'call-1' },
+];
+const wireMessages = Support.chatCompletionMessages(messages);
+// 工具声明映射为 tool_calls，工具结果映射为 tool_call_id。
+```
+
+Tool registration, parameter business validation, authorization, and execution are the host's responsibility. `createToolCallCollector.complete()` checks the integrity of call IDs and names and does not parse or validate business argument JSON.
+
+When multiple requests reuse the same Provider, `Support.createProviderObservationScope` can bind the App's own output rules. Assign the returned `observer` to the Provider and, for each request, use `attach(diagnostics, destination)` to associate the log destination. Child scopes inherit the association automatically. The App is responsible for redaction, retention, and write policy, and Provider events are recorded through the existing App log outlets.
+
+## Rejection checks
+
+```ts
+Support.breakWhile(occur, error?, tags?): void
+Support.breakWhile([
+  { occur: () => expired, error: '已过期' },
+  { occur: [() => missing, () => invalid], error: '输入不可用' },
+]): void
+```
+
+`occur` specifies rejection conditions: a truthy value, a lazy predicate, or an array of OR predicates that short-circuit in order; any true item rejects, stopping later predicates and error factories. Multiple check objects also stop at the first rejection in order. ProtocolCheck uses the same `occur` field, and `when` decides whether the check is enabled.
+
+For complete exports, exact overloads, and declaration sources, see [Public symbol reference](reference.md). Signatures in examples are for reading only; omitted fields cannot be used to infer arbitrary extension options.
+
+## Context compression/selection and local callbacks
+
+`createContextCompressor({ id, instruction, transport, maxOutputTokens, parse })` and `createContextSelector({ id, instruction?, transport, maxOutputTokens, parse?, maxExcerptChars? })` construct registrable handlers. The main request and their model calls share the same runner, deadline, remaining budget, and parent diagnostic identity:
+
+```ts
+compress(request: ContextCompressionCall, context: ExecutionContext)
+select(request: ContextSelectionCall, context: ExecutionContext)
+request.callModel({ stageId, input, maxOutputTokens, transport }): Promise<ModelResult<unknown>>
+```
+
+request provides stageId and the fragments to compress or candidates to select; the result parser handles only the returned value. Policies reference handlers by handlerId; callModel takes a named request and returns a ModelResult. The cancellation signal is read from the second context. Processing nodes connect these callbacks through the Workflow model port; for original-text protection, history grouping, watermarks, reserved calls, and audit rules, see [Context nodes](context-processing.md).
+
+createReplyPreview uses `{ rules, sink, render?, maxChars? }`; rules use stageId and capabilityId (native adaptation maps the latter to the function wire name). The sink is awaited in order, and render is synchronous. Rule data is copied as a snapshot and callbacks fix the original receiver; a preview never authorizes or executes tools.
+
+When a selector omits `instruction`, it uses the built-in trimming selection instruction, which requires the model to return `{ stepIds }` and explicitly treats fragment excerpts as data. A custom parser must provide the corresponding instruction as well.
+
+
+### Explicit reasoning wire policies
+
+CompatibleModelProvider's `config.reasoning` accepts `{ format, level }`. level is off/low/medium/high; format explicitly specifies the field format the provider supports and is not guessed from the model name.
+
+| format | Generated fields |
+| --- | --- |
+| reasoning-effort | reasoning_effort: none/low/medium/high |
+| thinking | thinking.type: disabled/enabled, switch only |
+| enable-thinking | enable_thinking: false/true, switch only |
+| thinking-budget | thinking.type and budget_tokens; low/medium/high default to 1024/4096/8192, and budgets can override them precisely |
+| custom | map(level) returns custom requestBody fields and must be synchronous |
+
+Explicit requestBody fields take precedence over generated fields; neither can override model, messages, stream, or output limits. thinking-budget must reserve space for the answer, and the thinking token count must be less than the actual output limit; otherwise the request is rejected before sending without expanding the Core budget. A mapper with getters or private state keeps its receiver, static configuration is resolved only once, and dynamic configuration is resolved per request.
+
+```ts
+const provider = new Support.CompatibleModelProvider({ config: {
+  baseUrl, apiKey, model,
+  reasoning: { format: 'thinking-budget', level: 'high' },
+} });
+const settings = Support.createModelStrategy({ model: { provider }, maxOutputTokens: 10000 });
+```
+
+JSON value transports enable `json` mode by default. This mode in CompatibleModelProvider uses `json_object`; when an array or scalar is needed and the provider does not support the corresponding mode, set `json: false` explicitly in the same `options` while keeping full JSON decoding and outputSchema validation.

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

@@ -0,0 +1,181 @@
+# Shared types and behavior contracts
+
+[Back to API handbook](README.md). This page describes the base types and invocation rules shared by all modules.
+
+## Identity, configuration, and time
+
+```ts
+type Id = string;
+type TimestampMs = number;
+type DurationMs = number;
+type JsonSchema = Readonly<Record<string, unknown>>;
+type MaybePromise<T> = T | Promise<T>;
+```
+
+These aliases only state meaning. They do not replace runtime validation, and they do not require every App to use branded types. An id must satisfy the constraints of its catalog or adapter; IDs supplied by models and clients are not proof of permission.
+
+| Field | Sole meaning |
+| --- | --- |
+| id | Primary key of the currently registered entity |
+| *Id / *Ids | Identifiers that point to other entities |
+| name / description | Display name / description of purpose |
+| kind | Domain classification, such as a read-only tool or an output kind |
+| type | Discriminant tag of a message or event |
+| version | Version of a serializable format |
+| revision | Revision identity of content or a declaration |
+| identity | Real model or space identity behind a registered alias, not merged with id |
+| *AtMs / *Ms | Absolute millisecond time / duration |
+| *Index / *Sequence / *Count | 0-based index / 1-based sequence / cumulative quantity |
+
+`Definition` is a reusable declaration; `Config` is a configuration value; `Ports` are execution dependencies; `Options` are construction or invocation options; `State` is workflow state; `Runtime` is an instance with a bound lifecycle. A single request's signal must not be placed in a reusable Definition, and numeric budgets must not be hidden in Ports.
+
+## Execution context
+
+```ts
+interface ExecutionOptions {
+  readonly signal?: AbortSignal;
+  readonly diagnostics?: DiagnosticContext;
+}
+interface OperationContext<App> {
+  readonly app: Readonly<App>;
+  readonly signal: AbortSignal;
+  readonly diagnostics?: DiagnosticContext;
+}
+```
+
+Core supplies the actual signal when it creates a request instance; the signal received by a registered handler always exists. `app` is the business dependency supplied by the caller, and models cannot override it. A Kit may define a local execution context that extends this contract, but it cannot require other Kits to fill its fields.
+
+- A request instance binds execution at construction, so later invoke calls do not need to pass signal again.
+- Reusable capabilities receive context on every run/read/resolve.
+- App service identity, budget, and cancellation travel along the real call chain; nesting a Kit never grants new budget.
+
+## Schema and parsing
+
+```ts
+interface SchemaAdapter<Value> {
+  readonly jsonSchema: JsonSchema;
+  parse(input: unknown): Value;
+}
+```
+
+`inputSchema` uses SchemaAdapter and contains an executable parse plus a read-only jsonSchema; only jsonSchema is projected to the model. parse runs synchronously; a Promise returned by mistake is rejected and the late rejection is handled. A Promise must never be treated as a parsed value.
+
+Context-dependent permission and protocol refinements belong to named handlers; stage, source, or permission checks must not be deleted just to fit them into a pure schema.
+
+## Booleans, assertions, checks, and authorization
+
+```ts
+interface Issue {
+  readonly code: string;
+  readonly message: string;
+  readonly path?: readonly (string | number)[];
+  readonly checkId?: string;
+}
+interface CheckResult<Value = never> {
+  readonly status: 'passed' | 'failed' | 'unavailable' | 'not-run';
+  readonly issues: readonly Issue[];
+  readonly value?: Value;
+}
+```
+
+| Contract | Returns | Failure / side effects |
+| --- | --- | --- |
+| `isX(input)` | boolean | Performs no conversion; false is only a negation |
+| `assertX(input)` | void | Throws on invalid input; false must not be used to express rejection |
+| `parseX(input)` | Value | Validates and converts; throws on failure |
+| `checkX(input, context)` | CheckResult | Check issues may be returned as a report; program errors still throw |
+| `authorize(input, context)` | void or Promise<void>, decided by the corresponding execution interface | Throws on rejection; synchronous entry points do not allow thenables |
+
+A passed result has empty issues; failed has at least one Issue; unavailable/not-run must not be treated as passed. value replaces the original only when an own-property check confirms it was provided (including an explicit undefined); truthiness must not be used to test presence. Check status does not replace tool execution status, task status, or delivery status.
+
+Boolean permission tests are named isAllowed. TypeScript allows functions that return non-void values to be assigned to void callbacks, so executors check the actual completion value of authorize/assert: only undefined means approval; false, true, or any other value is a contract error. Asynchronous entry points check after await. When adapting a boolean permission test, approval returns undefined and rejection throws.
+
+A synchronous entry point rejects on detecting a thenable and consumes its late rejection so it does not become an unhandled rejection; this does not roll back external side effects that already occurred, so asynchronous authorization and I/O must use asynchronous entry points.
+
+## Invocation results: fixed shape
+
+A single invocation API can have only one success return shape. Input shorthand only normalizes; it must not return a string for one input and an object for another, and no option may switch return paradigms through fullResponse, raw, or input shape.
+
+```ts
+interface InvocationMetadata {
+  readonly runId?: string;
+  readonly spanId?: string;
+  readonly parentSpanId?: string;
+  readonly invocationId: string;
+  readonly startedAtMs: TimestampMs;
+  readonly parentInvocationId?: string;
+  readonly durationMs: number;
+}
+interface InvocationResult<Value, Metadata extends InvocationMetadata> {
+  readonly value: Value;
+  readonly invocation: Readonly<Metadata>;
+}
+type ModelResult<Value> = InvocationResult<Value, ModelCallRecord>;
+type ToolResult<Value> = InvocationResult<Value, ToolCallRecord>;
+```
+
+Both model and tool invoke use this base structure. ModelCallRecord and ToolCallRecord keep their own known metadata and both extend InvocationMetadata; model usage exists only when the provider actually supplies it and is not fabricated as 0.
+
+Plain text corresponds to ModelResult<string>, and structured protocols correspond to ModelResult<ParsedValue>: the outer layer is unchanged, only the business type of value differs. Failure always throws or rejects the Promise and must not be mixed with `{ success: false }` as a second error channel. The model raw stream, previews, and diagnostics use their own explicit interfaces and do not become alternative return modes of invoke.
+
+This rule governs the boundaries of similar invocations. is/has, parse, read, and other distinct responsibilities still return per their explicit contracts; not every pure function is wrapped just to unify invoke.
+
+## Errors and observation
+
+```ts
+interface AgentErrorInfo {
+  readonly code: string;
+  readonly codes: readonly string[];
+  readonly issues: readonly Issue[];
+  readonly stageId?: string;
+  readonly isRetryable?: boolean;
+  readonly cause: unknown;
+}
+type Observer<Event> = (event: Readonly<Event>) => void | Promise<void>;
+type AsyncSink<Event> = (event: Readonly<Event>) => Promise<void>; // 需要异步交付的端口
+// 接受同步完成的 sink 类型可返回 void；执行器仍按序 await。
+```
+
+`getErrorInfo(error)` normalizes the error view and preserves the identity of App exceptions or cancellation reasons together with structured location. The SDK's ValidationError and the error view both use issues; budget resource, stage, and other details are not expressed by attaching another competing code to the same exception. The normalizer can also read the errors array of external exceptions; this is input format adaptation and does not make the SDK output two fields at once.
+
+Observer is out of band: it is not awaited, its exceptions are isolated, and it does not change authorization, budget, or retries. AsyncSink is delivery: it awaits order and backpressure, propagates failures, and is subject to cancellation and timeouts. A critical handler is not called observe.
+
+## Registration collections
+
+```ts
+interface ReadonlyCatalog<Definition extends { readonly id: string }> {
+  readonly definitions: readonly Readonly<Definition>[];
+  ids(): readonly string[];
+  values(): IterableIterator<Readonly<Definition>>;
+  entries(): IterableIterator<readonly [string, Readonly<Definition>]>;
+  has(id: string): boolean;
+  get(id: string): Readonly<Definition> | undefined;
+  require(id: string): Readonly<Definition>;
+}
+interface Registry<Definition extends { readonly id: string }>
+  extends ReadonlyCatalog<Definition> {
+  register(definition: Definition): this;
+  registerAll(definitions: Iterable<Definition>): this;
+  seal(): this;
+}
+```
+
+registerAll does not implicitly seal; a factory that creates an already-compiled catalog returns a read-only catalog directly. If byId must be exposed, declare it explicitly as a Record and do not name it definitions or entries. A pure algorithm does not add registration entities just to implement this interface.
+
+## Ownership, missing values, and generics
+
+- Pure definition data (JSON schema, ID arrays, policy parameters) is copied and frozen; objects with methods are not structuredClone'd and not spread in a way that drops their prototype. Contract methods are read one by one, and the original methods and their original receivers are fixed; App instances are not frozen. Binding a receiver does not snapshot the instance's internal state, and handlers must still honor static and request lifecycle constraints.
+- A registrar query returns the real stored registration projection: canonical methods are bound to their original receivers, and App-attached data and prototype getter metadata are read at registration; unregistered instance helpers are not promised. The canonical lists for intent, scope, and lifecycle are read-only snapshots, and describe returns an independent list copy; custom validation and policy callbacks still receive the original implementation so they can call its helpers.
+- Readonly only constrains TypeScript writes; Map/Set and nested business objects are not automatically immutable through Object.freeze. A catalog does not expose its internal Map; business values are not promised a uniform deep copy, and each Kit defines the copy scope of its snapshot and persistence interfaces.
+- Returned snapshots or checkpoint results must state whether they are copies or views; public events do not provide writable live references.
+- Flow control uses explicit discrimination to distinguish continuation from a completion value; a legitimate generic final value may be undefined. Ordinary read/render/search returns the business value directly.
+- Generic roles are ordered Input, Output, Context; roles that are absent are omitted. Complex local flows use named role types.
+- After a static ID selection, types narrow with the actual collection; dynamic IDs keep runtime validation and the unknown boundary, and callers must not pass a self-reported result generic off as validation.
+
+For complete exports, exact overloads, and declaration sources, see [Public symbol reference](reference.md). Signatures in examples are for reading only; omitted fields cannot be used to infer arbitrary extension options.
+
+## Type entry points and base maps
+
+`import type { ... } from '@jangts/agent-core/types'` covers shared contracts and the public types of each Kit and is empty at runtime; the root and owning modules also continue to provide type imports. `/structs` keeps historical types and existing constants and is not the preferred entry point for runtime values in new code.
+
+`ProtocolRegistry<T>` is the only keyed Map that allows arbitrary protocol payloads and provides ids/require without requiring T to have an id, so it is not disguised as an entity Catalog; real entity catalogs such as CommandCatalog implement the shared collection surface. Ordered algorithm configurations such as Normalization.steps are not incrementally registerable Registries. Intent/Scope registerAll only registers, and sealing uses the subsequent seal(); create is the complete-list entry that combines both.