@jangts/agent-core 0.1.1 → 0.2.1

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

@@ -0,0 +1,274 @@
+# Core: execution, models, and real tools
+
+[Shared types](types.md) · [Back to home](README.md). Below, `execution`, `OperationContext`, `SchemaAdapter`, and `ReadonlyCatalog` all use the shared contracts.
+
+## ModelRunner
+
+```ts
+new ModelRunner({ provider, transports?, execution?, ...options })
+runner.invoke({ input, stageId?, transport?, maxOutputTokens? }): Promise<ModelResult<Output>>
+runner.invoke(input: string): Promise<ModelResult<string>> // 只归一化输入，返回外形不变
+```
+
+| Constructor field | Type / semantics |
+| --- | --- |
+| provider | ChatProvider; the App supplies the actual model connection |
+| transports | Read-only ModelTransport array with unique registered IDs; defaults to only core:plain-text |
+| execution | ExecutionOptions; bound to one request, and Core supplies signal when absent |
+| maxCalls | Per-request model call limit, including selection and compression calls that use the Runner of the same request |
+| callTimeoutMs | Duration of a single call; does not extend the upper request deadline |
+| maxInputChars/maxOutputChars/maxSchemaChars | Three distinct character budgets; they are not interchangeable |
+| tokenBudget | Token budget with an explicit counter identity and counting port; character conversion is never guessed |
+| maxOutputTokens | Default output reservation for a single call; invoke can override it |
+| sink.output | (event: ModelOutputEvent) => void \| Promise<void>; body delivery is awaited in order and failures propagate; model.end is a bounded wrap-up notification |
+| execution.observe | ExecutionObserver; uniformly receives node, model, and tool process facts, out of band, with failure isolation |
+
+`input` is the shared ModelInput: plain text, a read-only message array, BuiltContext, or ContextPlan. The string shorthand omits the input object and returns the same kind of ModelResult.
+
+The two plain-text calls are fully equivalent:
+
+```ts
+const a = await runner.invoke('你好');
+const b = await runner.invoke({ input: '你好' });
+// a、b都为ModelResult<string>，正文取value，调用信息取invocation。
+```
+
+A successful result is always `{ value, invocation }`. A structured model only changes the static type of value; it never switches to a bare object and offers no raw/fullResponse return mode. Errors propagate through Promise rejection. The model cannot fill invocation with actual call events or receipts.
+
+Type inference comes from the read-only transports tuple that preserves literal IDs at construction; Output cannot be inferred from an arbitrary string alone. When invoke omits transport it always selects the built-in `core:plain-text` and does not guess a default from the "only registered transport"; stageId defaults to `model`. A known literal ID returns the matching ModelResult<T>, while a dynamic string returns ModelResult<unknown>. The string shorthand and an object input with the same value infer identically.
+
+The same `transport` field accepts a registered ID or a transport handle. When a handle is passed, the original object is verified as registered and the result is inferred from that object's contract.
+
+Budgets default to the current modelRunnerDefaults: maxCalls=8, callTimeoutMs=30000, maxInputChars=32000, maxOutputChars=16000, maxSchemaChars=16000, maxOutputTokens=1024. maxCalls is a non-negative safe integer; maxInputChars/maxOutputChars are non-negative safe integers or Infinity; maxSchemaChars/maxOutputTokens are positive safe integers, and callTimeoutMs is a safe integer from 1 to 2147483647. The token budget additionally validates the window, counter, and safety margin; these defaults are not a statement of provider capacity.
+
+Input messages contain fields such as role/content/images, and images in read-only input are retained with the message. remainingCalls, signal, and journal can be read directly; call counts use callCount/totalCallCount. lastCall is a read-only snapshot of the previous completed record and is not a basis for concurrent correlation. Selection and compression nodes share counts through the same model port. A single runner executes one call at a time; concurrent tasks each use a child runner, and each returned value is correlated by its own invocation.
+
+```ts
+interface ModelCapability<Input, Output = Input> {
+  readonly id: string;
+  readonly description: string;
+  readonly inputSchema: SchemaAdapter<Input>;
+  resolve(input: Input, context: Readonly<{ stageId: string }>): Output;
+}
+interface ModelSelection {
+  readonly capabilityId: string;
+  readonly input: unknown;
+}
+interface ModelTransportDefinition<Output> {
+  readonly id: string;
+  prepare(stageId: string): PreparedModelTransport<Output>;
+}
+```
+
+PreparedModelTransport<Output> is the unified transport preparation contract: options, schemaChars, optional instruction, and createResponse(). The returned collector has outputChars, push(part), and finish(): Output; the text collector accumulates and rejects function-call parts, and the structured collector returns a result only after full parsing. A collector is a new instance per call and does not reuse state across requests. PreparedModelInteraction is used for structured adapter composition, while text transports implement the generic collection contract directly.
+
+ModelCapability uses inputSchema.parse to parse capability parameters and resolve(input, { stageId }) to produce a typed stage result. resolve runs synchronously; a mistakenly returned thenable is rejected, and it neither executes tools nor authorizes. ModelCapabilitySource.resolve(selection, context) first verifies the IDs available in this stage, then parses, converts, and runs the declared refine checks.
+
+Core reads outputChars after the collector factory returns, after each push, and after finish: the value must be a non-negative safe integer, and NaN, Infinity, negative numbers, and fractions are rejected as protocol errors. maxOutputChars may be explicitly set to Infinity, but that does not relax the collector counting contract. Diagnostics keep the peak of each valid observation, and finish may release or normalize internal buffers; buffers are not required to grow indefinitely.
+
+Native interaction accepts a string or a valid function-call-delta. A function part must be a non-array object with index 0; id, when provided, must be a non-empty string, and name and arguments, when provided, must be strings. Conflicting IDs, multiple calls, unregistered capabilities, mixed body text, or incomplete arguments are rejected, and no tool is executed.
+
+Optional call metadata on the collector is read only once on a best-effort basis; a throwing getter does not overwrite an obtained business result, the original error, or cancellation, nor does it block the model.end wrap-up. outputChars is an execution-validated field and is exempt from this tolerance rule.
+
+Plain-text and structured transports each provide their own constructor that returns an implementation satisfying the transport preparation contract. A prepared interaction collects the complete result and parses the selection; raw parts cannot become a tool receipt.
+
+### Optional request preparation and actual measurement
+
+An ordinary `runner.invoke(input)` needs no preparation step. When an explicit context node must judge candidate input in advance, it can prepare a transport snapshot once:
+
+```ts
+const prepared = runner.prepare({ stageId: 'reply', transport, maxOutputTokens: 1000 });
+const measurement = prepared.measure(candidateMessages);
+// 调整候选消息后可以重新 measure；不会重新 prepare 或消耗模型调用。
+const result = await runner.invoke({ input: finalMessages, prepared });
+```
+
+`context.model` provides the same prepare/invoke contract, and the handle can be kept in this Workflow's state for later nodes. With multiple models, a preparation request may specify modelId, and the final invoke locates the original model through the handle without passing it again; the processing model and the final model are still bounded by the same request budget.
+
+Preparation fixes the instruction, Schema, options, and collector factory receiver of the current dynamic transport. Measurement covers the merged real messages, transport instruction, and Schema; with an explicit counter, the input token limit deducts this call's output reservation and safety margin. A handle for a registered model also keeps modelId, so selection or compression can explicitly reference another registered model while the final call still targets the originally prepared model. Without a counter no token estimate is produced. App body text is bounded by maxInputChars, while transport instructions and declarations are independently bounded by maxSchemaChars; budgets are not borrowed across them. If a JSON Schema is already embedded in the instruction, the actual total is not added twice.
+
+Measurement returns `ModelInputMeasurement` with body messageChars, added instructionChars, out-of-message declaration schemaChars, transport budget usage transportChars, the actual total inputChars, the effective limit, and withinBudget. It is not a budget reservation or a pass: the final input is still measured and validated again before the Provider. A handle belongs only to the Runner/Workflow request that prepared it, can be consumed once, and cannot replace stageId, transport, or the output reservation. Cancellation, expiry, foreign handles, and reuse are rejected; a pre-check rejection still consumes no model calls.
+
+The final call fixes a snapshot of message role, content, and images before the first asynchronous wait, and budgeting, token counting, and Provider sending share that snapshot; the caller modifying the original object afterwards does not rewrite the request. prepare fixes the set of capability IDs for this preparation, and capabilities registered later are available only to new preparations.
+
+Character budgets accept only non-negative safe integers or Infinity; a budget carried by BuiltContext must pass the same validation and can only narrow the Runner upper limit. NaN, missing budgets, fractions, and other invalid values are rejected before billing and Provider calls, and measurement and actual execution use the same judgment.
+
+### Fixed invocation results
+
+```ts
+interface ModelCallRecord extends InvocationMetadata {
+  readonly stageId?: string;
+  readonly modelId?: string;
+  readonly callSequence: number;
+  readonly startedAtMs: TimestampMs;
+  readonly status: 'success'; // 仅成功返回的invocation
+  readonly usage?: ModelUsage;
+}
+interface ToolCallRecord extends InvocationMetadata {
+  readonly toolId: string;
+  readonly startedAtMs: TimestampMs;
+  readonly status: 'success'; // 仅成功返回的invocation
+}
+```
+
+The invocation in a successful invoke return is always a success record; failure records go to events/diagnostics, and the failed call itself throws. Registered external models in ModelCalls set modelId, and Agent model stages set stageId; this does not change the result shape and does not require models to supply call metadata.
+
+### Provider and model output
+
+```ts
+interface ChatProvider {
+  stream(
+    messages: readonly ModelMessage[],
+    context: ModelProviderContext,
+  ): AsyncIterable<ModelPart>;
+}
+interface ModelProviderContext {
+  readonly signal: AbortSignal;
+  readonly options: Readonly<ModelOptions>;
+  readonly diagnostics?: DiagnosticContext;
+}
+```
+
+ModelOptions provides provider-neutral fields such as json, temperature, functions, includeUsage, and maxOutputTokens. The usage receiver is an execution accounting port: it records actual usage before notifying the observer, and observer failure isolation does not affect the usage record.
+
+The Provider contract only passes real call and transport parameters; it does not decide business authorization. The output token value on a request is called maxOutputTokens; the hard limit in connection configuration is called outputTokenLimit, and the two must not be confused with the default reservation. Provider wire fields such as max_tokens/tools continue to be converted by the adapter.
+
+The model sink and process observation reuse the same CoreEvent envelope. The sink receives model.start, model.output, model.parsed, and model.end on success, failure, or cancellation; the payload is in payload, and the real invocationId isolates calls. model.parsed means the full model value passed parsing and still must wait for delivery and cancellation checks before commit; it is not the App's final reply. model.end uses a separate 250-millisecond wrap-up deadline and still attempts to notify preview withdrawal after cancellation; a failed notification does not overwrite a committed result or the original exception, and consumers must still handle connection loss themselves. Events are discriminated by type, stage references use stageId, and model ordinal uses callSequence (starting at 1). Previews remain transient, and a final value is returned only after complete collection, parsing, budget, and cancellation checks pass.
+
+## AgentCoreEngine and Workflow
+
+### Existing request model service
+
+```ts
+const runner = new ModelRunner({ provider, maxCalls: 4, execution });
+const agent = new AgentCoreEngine({ workflow }).bindModelRuntime(runner);
+await agent.run(state);
+```
+
+When bindModel configures a definition, each run builds an independent request Runner; when bindModelRuntime binds an existing request service, it reuses that service's existing counting, budget, cancellation, and observation scope, and later runs receive no extra budget. Nodes obtain the call parent and live counts automatically through context.model. Two requests must not run overlappingly on the same Engine; fork requires resume to explicitly provide the restored model, avoiding implicit sharing of run state. Structured implementations can also be attached, and the canonical invoke/prepare fix the original receiver at bind time; the service itself is neither cloned nor frozen.
+
+### Child execution and shared budget
+
+```ts
+const child = parent.createChild({
+  id: 'app.analysis', maxCalls: 8, reserveCalls: 1, timeoutMs: 60000,
+  transports: specialistTransports, diagnostics: operation.diagnostics,
+});
+const engine = new AgentCoreEngine({ maxRounds: 8, execution: child.execution });
+// 使用同一 Engine／Workflow，App 提供独立 state、app、工具与完成检查。
+```
+
+`ModelChildOptions` are explicit child execution settings. A child runner inherits the Provider, per-call limits, token counter, and call observation ports; it does not inherit the parent conversation, journal, output sink, or transport list. When `transports` is omitted, the built-in plain-text transport is used; add specialized transports as needed. `execution` is a read-only signal/diagnostics pair that can be passed to the Engine and tool registrars. The child signal is bounded by both parent cancellation and the local deadline, and diagnostics use the single child scope of the same run and cannot be swapped for the observation parent of another run.
+
+`maxCalls` is a local limit, and `reserveCalls` is budget left for ancestors. A call atomically deducts from the local and ancestor ledgers before provider I/O, and failures do not refund the attempt; pre-check rejections do not deduct. `remainingCalls` reflects local, total budget, and reservation limits together; `callCount` still counts only this instance, while `totalCallCount` includes child calls. Creating new instances does not expand the whole-request budget.
+
+`children` configures `maxDepth`, `maxConcurrentCalls`, and `maxChildren` for this request family, defaulting to 1, 1, and 32. Depth starts at 0 for the root runner; the total creation count is not returned when subtasks finish. Configuration is fixed when the root is constructed, all descendants share capacity, and each level still keeps its own ancestor wrap-up budget. `ModelChildOptions.signal` can attach additional local cancellation, and parent cancellation propagates to all descendants.
+
+```ts
+const parent = new ModelRunner({
+  provider, maxCalls: 12,
+  children: { maxDepth: 3, maxConcurrentCalls: 2, maxChildren: 16 },
+  execution,
+});
+```
+
+Context nodes share budget through the ordinary model port. The App supplies the role list, permission ports, and result contracts, organizes tasks with Workflow/handlers, and passes the child signal to real tools and wrap-up side effects. To compose bounded parallel tasks, use [Support.runChildren](advanced-agents.md#bounded-subtask-composition).
+
+```ts
+const agent = new AgentCoreEngine({ workflow, app, tools, maxRounds: 8 });
+const result = await agent.run(state);
+```
+
+`defineWorkflow` compiles a definition. When the Workflow is known, it can be bound at construction, or bound once during assembly with `bindWorkflow`. A tool runtime instance can likewise be bound through the constructor parameter `tools`, or bound once during assembly with `bindToolRuntime`; both accept the same contract and cannot be bound repeatedly. For complete usage of nodes, routes, models, and tools, see [Workflow primer](workflow.md).
+
+`maxRounds` bounds rounds and defaults to 8. The low-level callback loop is still available through `engine.run(step)`, whose callback receives the round and execution context and returns `StepOutcome`.
+
+`run(step, { signal })` and Workflow's `run(state, { signal })` both combine single-run cancellation with the instance execution.signal and preserve the original cancellation reason. CoreStep calls without a bound Workflow do not accept modelId selection.
+
+A self-orchestrated CoreStep callback should pass the context signal to internal asynchronous operations and check cancellation before side effects. Cancellation stops waiting for the current callback, and late results do not enter subsequent rounds; cancellation cannot forcibly terminate arbitrary JavaScript, nor does it treat an unconfirmed storage commit as rolled back. Apps or Kits holding a transaction or exclusive lock must wait for the already-started storage commit to confirm before releasing resources.
+
+```ts
+type StepOutcome<Output> =
+  | { readonly type: 'continue' }
+  | { readonly type: 'complete'; readonly value: Output };
+interface WorkflowContext<App> extends OperationContext<App> {
+  readonly roundIndex: number;
+  readonly error?: unknown;
+}
+interface WorkflowNode<State, Output, App> {
+  readonly id: string;
+  readonly description: string;
+  readonly startsRound?: boolean;
+  readonly requires?: readonly (keyof State & string)[];
+  readonly provides?: readonly (keyof State & string)[];
+  readonly onErrorNodeId?: string;
+  run?(state: Readonly<State>, context: WorkflowContext<App>): MaybePromise<Partial<State> | void>;
+  readonly routes: readonly WorkflowRoute<State, Output, App>[];
+}
+```
+
+run(step) uses StepOutcome and allows undefined as a legitimate completion value. Workflow routes distinguish jumps from completion explicitly through targetNodeId and complete:
+
+```ts
+type WorkflowRoute<State, Output, App> =
+  | { readonly when?: WorkflowGuard<State, App>; readonly targetNodeId: string }
+  | { readonly when?: WorkflowGuard<State, App>; readonly complete: (state: Readonly<State>, context: WorkflowContext<App>) => Output };
+```
+
+WorkflowGuard<State, App> is the synchronous `(state: Readonly<State>, context: WorkflowContext<App>) => boolean`; a mistakenly returned thenable is rejected. WorkflowDefinition contains id, entryNodeId, read-only nodes, and optional isResult; node references, reachability, and bounded loops are checked at define time. At execution, requires is checked first, then the handler runs, cancellation and provides are checked before the patch is committed, and finally the first matching route is taken. Cancellation and contract errors cannot be turned into business success by onError.
+
+isResult only answers with a boolean; if a resumable business check is needed, the App calls a checker inside a workflow node. Workflow state remains separate from app dependencies.
+
+## ToolRegistry and ToolRuntime
+
+The low-level ToolRegistry in Core can take hand-written ExecutableTool implementations; Support's ToolRuntime comes from typed tool catalogs. Both reuse the same real invocation mechanism.
+
+```ts
+interface ExecutableTool {
+  readonly id: string;
+  readonly kind: string;
+  parseInput(input: unknown): unknown;
+  execute(input: unknown, context: ToolExecutionContext): unknown;
+  parseOutput(output: unknown): unknown;
+}
+new ToolRegistry({ execution?, errors? })
+registry.register(definition): this
+registry.registerAll(definitions): this
+registry.seal(): this
+registry.invoke({ toolId, input }): ToolResult<unknown>       // 同步，拒绝thenable
+registry.invokeAsync({ toolId, input }): Promise<ToolResult<unknown>>
+```
+
+The low-level value stays unknown, and the call result still uses the fixed InvocationResult; there is no "type validation" in which the caller self-reports Output. Type inference comes from Support catalogs. The registry implements the shared Catalog surface: get returns undefined for a missing entry, and require throws.
+
+The pipeline is fixed: parse input → registered execution/authorization adapter → await the actual result → parse output → cancellation check → record completion. The low-level execution contract does not require every tool to carry extra business authorization fields; real rules are supplied by the App or by handlers adapted through Support.
+
+The ToolCallRecord in a successful return always has status=success; a failed call throws. ToolExecutionEvent and ModelCallTrace in read-only events distinguish success/error/cancelled and carry the same InvocationMetadata; business check conclusions are recorded separately by the App and do not overwrite call status.
+
+## Journal and diagnostics
+
+[Requests, call chains, events, and Journal](observability.md) defines the complete correlation and storage contracts: per-event records and explicit parent-child keys, where Journal is the run projection of the same execution facts and does not build a second accounting system.
+
+```ts
+journal.model({ stageId, value, invocation }): void
+journal.beginTool({ toolId, input, invocation? }): string // 返回同一invocationId
+journal.finishTool({ invocationId, status, value }): void // success | error | cancelled
+journal.snapshot(): readonly ContextRecord[]
+createDiagnostics({ output?, runId?, spanId? }): DiagnosticContext
+```
+
+invocationId is assigned by the real tool call boundary, and Journal uses the same identity. Cross-run correlation must combine runId; App requestId is correlated separately by the App. A nonexistent call or a duplicate finish is rejected. One real execution nesting Tools Kit/Support/Core allocates only one invocationId, passed down the execution context; executeInvocation and its Journal share the invocationId of that boundary. A genuinely nested tool execution is another child call with an independent ID, correlated to the parent call through parentInvocationId. IDs remain unique across instances.
+
+Low-level execution callbacks and business bindings both return the original business value, and only the public invoke boundary wraps it once; internal compression subcalls use result.value and must not hand the whole envelope to a parser. durationMs covers preparation, execution, parsing, and delivery waiting for the current call, and startedAtMs is recorded when the corresponding boundary starts; callSequence is allocated only to model calls that are actually issued, and pre-check rejections go to rejected diagnostics without fabricating provider calls.
+
+ContextRecord uses type discrimination, producerSequence (starting at 1), stageId/toolId/invocationId, and value. Tool call status is success, error, or cancelled. Tool and workflow diagnostic payloads use known fields and the WorkflowEvent type; model-generated values and App exceptions may be unknown.
+
+The Core fact envelope uses version, eventId, type, occurredAtMs, runId, spanId, parentSpanId, optional invocationId, and payload. Cross-source storage sequence is assigned uniformly by the App run collector, while Core local ordinals use producerSequence. Core, Provider, and Kit each define their own event catalogs.
+
+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.
+
+### Boundaries of observation and budget
+
+ModelCallTrace contains the required invocationId, startedAtMs, durationMs, callSequence, and stageId; status is success/error/cancelled. Call results, traces, and diagnostics use the same call identity. `model.end` reports only accepted attempts; input/budget pre-check rejections go to runtime.rejected and do not fabricate output when no provider I/O was initiated. An accepted attempt whose collector factory fails still wraps up as error and retains the consumed attempt count.
+
+ModelRunner defaults and error priority are defined by modelRunnerDefaults and the executor; the original BudgetError.code and getErrorInfo.code of a budget error are both BUDGET, and the App can map them to a more specific business message in its own presentation layer. Timeout and cancellation preserve the original exception identity. CallTrace measurement covers preparation, parsing, and delivery waiting for that call; child calls share the total budget, and duration is not an additive cost.

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

@@ -0,0 +1,118 @@
+# Getting Started from the Same Contract Set
+
+[Back to home](README.md). Running the examples requires the App to supply the provider, business storage, and authentication configuration.
+
+## One Output Shape, Two Input Forms
+
+```ts
+const runner = new ModelRunner({ provider });
+
+const a = await runner.invoke('你好');
+const b = await runner.invoke({ input: '你好' });
+
+// 两者都是ModelResult<string>。
+console.log(a.value);
+console.log(b.value);
+console.log(a.invocation.durationMs);
+```
+
+The short form is only equivalent to `{ input: '你好' }`. No path returns a string directly, and there is no raw/fullResponse option to switch the return structure. A structured transport only makes value a parsed object; the outer layer is still a ModelResult.
+
+## Single-Source Tool Declaration, Model Selection, and Real Execution
+
+```ts
+import { ModelRunner, Support } from '@jangts/agent-core';
+import type { OperationContext } from '@jangts/agent-core';
+
+interface ReadNote { noteId: string }
+interface Note { title: string; body: string }
+interface App {
+  visibleNoteIds: ReadonlySet<string>;
+  notes: { read(id: string, signal: AbortSignal): Promise<Note> };
+}
+
+const inputSchema = Support.defineSchema<ReadNote>({
+  jsonSchema: {
+    type: 'object', required: ['noteId'], additionalProperties: false,
+    properties: { noteId: { type: 'string', minLength: 1 } },
+  },
+  parse(value: unknown): ReadNote {
+    if (!value || typeof value !== 'object' || !('noteId' in value)
+      || typeof value.noteId !== 'string' || !value.noteId.trim()) {
+      throw new TypeError('noteId is required');
+    }
+    return { noteId: value.noteId };
+  },
+});
+
+const readNote = Support.defineTool({
+  id: 'note-read', kind: 'read', description: '读取当前用户可见的笔记。',
+  inputSchema,
+  authorize(input: ReadNote, context: OperationContext<App>) {
+    if (!context.app.visibleNoteIds.has(input.noteId)) throw new Error('Access denied');
+  },
+  execute(input: ReadNote, context: OperationContext<App>) {
+    return context.app.notes.read(input.noteId, context.signal);
+  },
+  parseOutput(value: unknown): Note {
+    if (!value || typeof value !== 'object'
+      || !('title' in value) || typeof value.title !== 'string'
+      || !('body' in value) || typeof value.body !== 'string') {
+      throw new TypeError('Invalid note');
+    }
+    return { title: value.title, body: value.body };
+  },
+});
+
+const catalog = Support.defineToolCatalog([readNote]);
+const transport = Support.createModelTransport({
+  id: 'note-selection', capabilities: catalog.capabilities,
+});
+```
+
+A definition does not close over this user, signal, or budget; the same catalog can serve multiple requests. Binding happens only after entering a request:
+
+```ts
+const execution = { signal: requestSignal };
+const tools = catalog.bind({ app: authenticatedApp, execution });
+const runner = new ModelRunner({
+  provider, transports: [transport] as const, execution, maxCalls: 2,
+});
+
+const selected = await runner.invoke({
+  stageId: 'choose-note', transport: 'note-selection',
+  input: '读取刚才那份笔记。',
+});
+const executed = await tools.invoke({
+  toolId: selected.value.toolId,
+  input: selected.value.input,
+});
+
+// 同一外层形状，不同业务值。模型提议不是执行回执。
+const proposal = selected.value;
+const actualNote = executed.value;
+const actualInvocationId = executed.invocation.invocationId;
+```
+
+The visible set is trusted server-side context, and real storage must still check ownership and resource lifecycle again. The schema and model selection grant no permission; authorize returning false is not part of the target contract.
+
+## Reading Knowledge with the Collection Methods You Already Know
+
+```ts
+import { defineKnowledgeCatalog } from '@jangts/agent-core/kits/knowledge';
+
+const knowledge = defineKnowledgeCatalog([
+  { id: 'manual', revision: 'r1', parts: ['已维护的资料。'] },
+]);
+
+const optional = knowledge.get('missing'); // undefined
+const required = knowledge.require('manual'); // 必须存在
+const snapshot = knowledge.read({
+  documentId: required.id,
+  selection: { mode: 'document' },
+});
+```
+
+read is a read with an explicit content model and returns a KnowledgeSnapshot; it is not another output mode of model invoke. The same shape is required only for the same method with the same responsibility, so not every scalar, collection, and snapshot is called a Response.
+
+The calls above can be composed into the same Workflow; the model only proposes a structured selection, and the registered implementation performs the actual tool authorization, execution, and result checking.

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

@@ -0,0 +1,183 @@
+# Other optional Kits
+
+[Shared types](types.md) · [Back to home](README.md). Each Kit is imported by named function／constructor from its own subpath, with static declarations separated from the per-run context.
+
+## Intents, Interaction, Tools
+
+| Capability | Preferred interface／key contract |
+| --- | --- |
+| IntentRegistry | Defines the primary key id, uses scopePolicy/targetPolicy, implements the shared Registry contract |
+| ScopeRegistry | id, intentIds, toolIds, queryScopeIds, knowledgeTopicIds; aliases are retained, and query methods use scopeId |
+| defineAgentCatalog | Projects relationships from actual registrations; the current task is `{ intentId, scopeId? }`, and scope cannot be used for both policy and reference |
+| defineInteractionProtocol | One commands declaration compiles the protocol; commandField is owned by the App, which is not forced to name its wire field type or kind |
+| defineCommandCatalog | The closed commands set may be written as a Record; the public definitions are an array, and toRecord() is the explicit mapping |
+| bindInteraction | Aligns protocol with named handlers; dispatch(input, context) never executes unregistered commands |
+| ToolLifecycleRegistry | Actual execution delegates to Core tools; assertDecision checks decisions, authorize returns void on approval and throws on rejection |
+
+Registrar declarations and query results use the same set of fields. ID lists use ids(), naming rules use idPattern, and custom assertions use assertDefinition. Scope aliases are business-name references resolved by normalize.
+
+When the complete list is available at construction time, use IntentRegistry.create(definitions, policy) or ScopeRegistry.create(definitions, policy) to build and seal the catalog at once. When staged assembly is needed, use new Registry(policy).registerAll(definitions).seal(); both follow the same registration contract.
+
+InteractionProtocol and CommandCatalog are public constructors; Interaction and Interaction.Commands provide their namespace entries respectively.
+
+The Tools Kit preserves the real order: global check → selected check → authorization → resume/execute → completion → finalize. Lifecycle and contribution are local protocols of this Kit. The receiver field is called receiver and is not conflated with OutputField.owner; the in-request journal reuses the invocationId allocated by Core.
+
+## Evidence and Retrieval
+
+```ts
+defineEvidenceChecklist(providers): EvidenceChecklist
+checklist.isSatisfied({ observations, requirement }): boolean
+checklist.missing({ observations, requirements }): readonly EvidenceRequirement[]
+checklist.isComplete({ observations, requirements }): boolean
+
+defineEvidenceProjection(definition): EvidenceProjection
+projection.project({ observations, sourceIds }): readonly Observation[]
+
+defineRetrieval(definition): Retrieval
+retrieval.run(input, context): RetrievalReceipt
+```
+
+EvidenceRequirement describes a requirement, not an existing resource; it cannot be merged with ArtifactReference permissions just because both contain an ID. Projection keeps the current evidence boundary for no selection, unknown selection, and complete candidates.
+
+Retrieval definitions use assertInput, authorize, execute, assertResult, and named effects. RetrievalSource.sourceId is the reference identifier for this request and may coexist with the material entity's own id; it is not another spelling of an entity primary key. Receipt uses startedAtMs, and retrieval counts use queryCount. Definitions must not bind request state; state/budget come from this run's context.app, and errors.duplicate/budget declare rejection reasons centrally. Synchronous runs stay synchronous, and an accidental Promise return is explicitly rejected.
+
+Retrieval provides run(input, OperationContext); assertInput in the definition is a required assertion, result assertions use assertResult, and error factories live in errors.duplicate／errors.budget. limit and queryCount must be non-negative safe integers, and a quota of 0 does not start any read. Deduplication takes priority over budget; a rejected authorization makes no reservation, and a failed read retains the seen key. Cancellation is checked again before submitting evidence after source binding completes; once submitted, effects run in order, and cancellation or failure stops subsequent items without fabricating a rollback.
+
+## Policies, Normalization, Delivery, Candidates
+
+| Kit | Preferred creation and execution | Termination／error semantics |
+| --- | --- | --- |
+| Policies | definePolicySet; assess(input) | Reports all matching reasons, not just the first hit |
+| Recovery | defineRecoveryChain; tryRecover(input) | The first explicit takeover; errors must not be swallowed accidentally; use an explicit handled flag when the final value may be undefined |
+| Normalization | defineNormalization; normalize(input, context) | Sequential transformation, when conditions, and isComplete decisions; preserves 0/false/empty string |
+| Delivery | defineDelivery; deliver(input, context) | Stage hooks interleaved with handlers; explicit continue/complete, supports legitimate undefined final values |
+| Candidates | defineCandidateSelection; parse({ value, allowed }) | minCandidates/maxCandidates; order and count are constrained by real declarations |
+
+In candidate parsing, value is the value to parse and allowed indicates whether this task permits a candidate envelope. maxCandidates must be configured explicitly, and minCandidates defaults to 1 when omitted; an ordinary single value still returns a single-element array, new candidates cannot be submitted after the task has taken over, and candidates cannot be nested.
+
+Delivery stages use id; beforeStage receives { stageId, state } and OperationContext, and handle receives state and the same context. deliver's second argument provides the real signal and optional diagnostics, and cancellation is checked on entering a stage and before and after each handler; synchronous hooks or handlers do not accept Promises. ContentProjection uses named requests, and TreeProjection uses visit traversal.
+
+Each policy definition uses id, description, when, and a named handler. An ordinary single condition does not need to become a stage class; sequential pipelines, first-match, merging, and rejection checks remain distinct flows.
+
+## Projection, Aggregation, TextSkills
+
+| Kit | Shared contract |
+| --- | --- |
+| ContentProjection | defineContentProjection; project({ value, maxChars }) returns `{ text, truncated }`; fallback text must also satisfy the budget, and is rejected if it cannot; data cannot be fabricated |
+| TreeProjection | defineTreeProjection; visit(input, context), with explicit synchronous semantics for maxDepth and omit |
+| QueryAggregation | defineQueryAggregation; collect(inputs, context), preserving serial order, deduplication keys, overrides, and counting basis |
+| TextSkills | defineTextSkillLoader; load(input, context), with real file reads provided by an App port |
+
+A TextSkill definition uses id, entry, toolIds, and kind=text-workflow. Catalog entry structure is separated from body description, and IDs and tool references come from the same registration source.
+
+TextSkillLoader accepts load({ entries }, { read }). Registration ID, path, tool reference, and duplicate checks precede reading the corresponding file, and both read and custom parsers must be synchronous. The read port, registration entries, and error factory may be implemented by a class, and prototype getters and original method receivers are preserved. App-owned fields in tool receipts are projected explicitly by the App.
+
+## TextSearch, VectorSearch, RRF, ModelCalls
+
+```ts
+interface SearchHit<Document> {
+  readonly id: string;
+  readonly score: number;
+  readonly document: Readonly<Document>;
+}
+new TextSearch({ indexRevision, fields, storedFields, ...options })
+new VectorSearch({ identity, dimensions })
+textSearch.search({ query, limit, filter }): readonly TextSearchHit<Document>[]
+vectorSearch.search({ vector, limit, filter, minScore?, groupBy? }): readonly VectorSearchHit<Document>[]
+vectorSearch.upsert({ document, vector }): void
+reciprocalRankFusion(lists, options): readonly FusedRank[]
+```
+
+TextSearch's payload is still a Partial<Document> of the declared stored fields, while VectorSearch may return full documents; the unified document field does not mean full-text data has been read. Extra terms/contributions extend each algorithm. The three scores are not the same confidence, and RRF cannot mix raw scores directly.
+
+TextSearch copies only the declared index and stored fields; input originals, filter callbacks, and returned results do not share nested metadata. VectorSearch's filter and grouping callbacks each receive an independent document copy; modifying these copies does not rewrite the index or affect the other callback. Index metadata must be structuredClone-able, and vectors must supply a numeric value for every dimension; sparse arrays are rejected.
+
+TextSearch.snapshot() returns version=2, engine, configurationFingerprint, and serializedIndex; restore accepts version=2. Both the fingerprint and public constructor parameters use indexRevision／storedFields. remove waits for index vacuum before returning, ensuring deleted content does not remain in the next serialization.
+
+```ts
+new ModelCalls(bindings)
+models.invoke({ modelId, input, timeoutMs }, context): Promise<ModelResult<Output>>
+```
+
+Bindings use id, identity, invoke, assertInput/assertOutput. Binding callbacks return business values, and the ModelCalls public boundary wraps them as `{ value, invocation }`. id is the registration key and identity is the actual model identity; context.signal and timeoutMs together constrain external I/O. Heterogeneous models infer I/O from the registration ID, while dynamic IDs stay unknown.
+
+After input validation passes, ModelCalls hands over to invoke in the current call stack without queueing an extra microtask. Arbitrary App inputs may retain class instances and prototypes; if a handler uses mutable data across an await, that handler must explicitly snapshot the required fields.
+
+```ts
+const attemptBudget = new AttemptBudget(2);
+await models.invoke({ modelId, input, timeoutMs: 1000 }, { signal, attemptBudget });
+```
+
+attemptBudget is the optional call-attempt port for the current request and may directly use Core's AttemptBudget. Resolution／pre-cancellation does not consume quota; an actually accepted attempt atomically takes one before I/O and is not refunded on failure. A batch call still counts as one, while vector entries, tokens, and chat call counts are defined and metered by the App; without a budget passed in, one must not claim that external inference is subject to a unified quota. Reusing the model catalog does not automatically create a business quota for user Q&A. Upstream and downstream bindings may pass the same budget port; Core does not build in providers, model roles, or cross-business total quotas.
+
+## Artifacts
+
+```ts
+interface ArtifactReference {
+  readonly resolverId: string;
+  readonly artifactId: string;
+  readonly revision?: string;
+}
+interface ArtifactResolver<Output, App> {
+  readonly id: string;
+  resolve(reference: ArtifactReference, context: OperationContext<App>): MaybePromise<Output>;
+}
+defineArtifactCatalog(resolvers): ArtifactCatalog
+catalog.resolve(reference, context): Promise<Output>
+```
+
+resolverId points to the registered resolver and artifactId points to the resource; the two do not reuse the ambiguous id/kind. The Resolver is responsible for validating real accounts, existence, revision, and lifecycle; additional URL／path fields do not select the actual resource. Cancellation interrupts waiting and consumes late rejections, but does not prove that external reads have stopped.
+
+The execution entry accepts ArtifactReference and OperationContext. Implementations may carry their own extra members, while execution reads the fields defined by the interface.
+
+## Durable
+
+```ts
+defineDurableTask(definition, options?): DurableTask
+interface DurableTaskDefinition<State, App> {
+  readonly id: string;
+  readonly revision: string;
+  readonly steps: readonly DurableStep<State, App>[];
+  isState(input: unknown): input is State;
+  authorize?(checkpoint, context): void | Promise<void>;
+}
+task.run({ taskId, store }, context): Promise<State>
+```
+
+Steps still have id, replayPolicy, run, and optional reconcile; handlers take state first and OperationContext second. The App provides store exclusive access, load/save, user ownership, retention, and serialization validation; no SDK default database or automatic scheduling is added.
+
+Checkpoint v2 uses definitionId, revision, nextStepIndex, attemptCount, maxAttempts, deadlineAtMs, status, state. status is a Kit state and must not become a required field for all Core applications.
+
+Save the attempt and running before execution; safe steps interrupted mid-way may be safely re-run with the App's guarantee, while reconcile steps only go through reconciliation and are rejected when no reconciliation implementation exists. Recovery does not reset counts or deadlines; after a handler returns a copy of the state, check signal/deadline/shape first, then save the confirmation. Cancellation during a save cannot pretend the write was withdrawn.
+
+The DurableStore interface includes exclusive(taskId, operation), load(taskId), save(taskId, checkpoint). load/save use version=2; before execution, check definitionId/revision, state, index, count, and deadline. Unknown versions are rejected and do not fall back to a new task. A resumed task does not gain extra budget or authorization.
+
+Durable validates state with isState, decides replay with replayPolicy, and executes via run({ taskId, store }, OperationContext). Cancellation or deadline is checked when entering exclusive operations, after reading, after state validation and cloning, and before and after each save; saves always wait inside the lock, and cancellation races cannot pretend to revoke an already committed write. Handlers receive the diagnostics of the current Loop sub-scope.
+
+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.
+
+## Intentional differences of local protocols and pure algorithms
+
+PolicySet／RecoveryChain provide definitions/ids/values/entries/has/get/require and operate directly on caller input. Pure predicates／recovery chains do not need an execution signal; the second Context of Normalization, TreeProjection, and Aggregation is the algorithm context declared by the caller and has no external execution lifecycle. Reads, tool execution, and durable tasks use OperationContext.
+
+Interaction protocol receivers and handlers both plug in as interfaces, so standalone objects or class instances need no conversion to plain objects. bindInteraction fixes the command handling function and the original receiver at binding time; private state and prototype methods remain effective. Selection errors and envelope callbacks provided by the protocol class also preserve the original receiver.
+
+Interaction's ProtocolField uses jsonSchema; a compiled command exposes inputJsonSchema (complete required fields), modelJsonSchema (the projection the model may submit), and fieldSchemas (per-field descriptions), while assert performs assertions and parse performs conversion. when must be a synchronous boolean; occur is a synchronous rejection predicate or an OR array of predicates. refine returns void and format returns the converted value; all callbacks fix the original method and original receiver.
+
+ToolLifecycle's composition selects a structured template provider and preserves its existing falsey-rejection semantics without treating it as an arbitrary generic final value; control protocols in Delivery, Recovery, and AnswerFlow that may legitimately return undefined must be discriminated explicitly. Other synchronous hooks reject thenables, and authorize/inspect must return void. Bound execution signal and diagnostics are passed down through the real call context.
+
+Every RRF input ranking and contribution detail uses sourceId. The filter in Text/VectorSearch is provided by the App and must return a boolean synchronously. VectorSearch.upsert uses { document, vector }, and search uses named requests. Both hits use document, with score semantics being lexical weight and cosine similarity respectively; RRF only fuses ranks and cannot compare their scores directly.
+
+ModelCalls bindings use assertInput／assertOutput to check input and output. timeoutMs must be a safe integer from 1 to 2147483647, and illegal values are rejected before the call.
+
+DurableTask's second construction options may bind store and now; run's named request may provide a store for this run. `authorize` checks the current identity, source revision, and authorization on every resume and before returning a completed result.
+
+A Checkpoint may contain `modelBudget: { maxCalls, reservedCalls, maxCallsPerAttempt }`. Before each execution, persist the reservation for the whole run, then hand it to the handler's `maxModelCalls`; the App uses it to constrain the real runner. Interrupted or unused reservations are not refunded, so recovery after a crash cannot reset the accumulated quota. State predicates are synchronous booleans, and steps have explicit replayPolicy; clock, cancellation during save, and reconciliation follow the same lifecycle. See [Durable tasks](advanced-agents.md#durable-professional-tasks) for a complete example.
+
+## Reflection, Family, and knowledge publishing
+
+[Reflection, branching, and material publishing](advanced-agents.md) introduces the configuration and use of `defineReflection`, `defineAgentFamily`, and `Knowledge.defineKnowledgePublication`. They are optional Kits for the App, while identity, real storage, and publishing decisions are provided by the App.
+
+## MockGPT
+
+The simulated model Kit is used from `@jangts/agent-core/mock`; Node service and web source are provided by `/mock/node` and `/mock/web` respectively. It can generate JSON values directly and also test a model client's HTTP/SSE and failure handling. See [MockGPT API](mock.md) for complete input, returns, budget, and TS/JS examples.