@jangts/agent-core 0.2.0 → 0.2.1

package/development/docs/registration.en.md

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

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

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

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

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

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

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

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

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

package/dist/cjs/diagnostics/catalog.js

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

package/dist/cjs/support/model/chat-completions.js

@@ -92,7 +92,7 @@ function chatCompletionParts(delta) {
  */
 function chatCompletionMessages(messages) {
     return messages.map((message) => {
-        const { role, content, images, toolCalls, toolCallId } = message;
+        const { role, content, images, toolCalls, toolCallId, } = message;
         if (!['system', 'user', 'assistant', 'tool'].includes(role) || typeof content !== 'string')
             throw new TypeError('Invalid provider message role or content');
         if (toolCallId !== undefined && role !== 'tool')

package/dist/cjs/support/model/completion/default.js

@@ -29,4 +29,5 @@ const policy = {
         };
     },
 };
+/** Frozen default policy: strictness depends only on whether the call declared functions. */
 exports.defaultCompletionPolicy = Object.freeze(policy);

package/dist/cjs/support/model/completion/session.js

@@ -99,4 +99,9 @@ const policy = {
         };
     },
 };
+/**
+ * Frozen opt-in policy that judges rules by the request's effective `tool_choice`.
+ *
+ * Consumers that do not select it keep `defaultCompletionPolicy`.
+ */
 exports.sessionCompletionPolicy = Object.freeze(policy);

package/dist/esm/diagnostics/catalog.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Default visibility tier for every event Core can emit.
+ *
+ * The same object is the allow-list used when normalizing persisted records; adding an event to
+ * `CoreEventName` without a tier here fails type checking.
+ */
 export declare const coreEventCatalog: {
     readonly 'node.progress': "metadata";
     readonly 'model.start': "metadata";

package/dist/esm/diagnostics/catalog.js

@@ -1,3 +1,9 @@
+/**
+ * Default visibility tier for every event Core can emit.
+ *
+ * The same object is the allow-list used when normalizing persisted records; adding an event to
+ * `CoreEventName` without a tier here fails type checking.
+ */
 export const coreEventCatalog = {
     'node.progress': 'metadata',
     'model.start': 'metadata',

package/dist/esm/structs/kits/retrieval.d.ts

@@ -13,6 +13,7 @@
 export interface RetrievalSource {
     sourceId: string;
 }
+/** Adapter output for one accepted query; the Kit renames each source before returning it. */
 export interface RetrievalResult<Source extends RetrievalSource> {
     sources: Source[];
 }

package/dist/esm/structs/kits/search.d.ts

@@ -25,12 +25,14 @@ export interface TextSearchOptions<Document extends {
     /** How multiple query terms combine; defaults to the engine default (OR). */
     readonly combineWith?: 'AND' | 'OR';
 }
+/** One ranked match; `terms` are post-tokenization and only stored fields are returned. */
 export interface TextSearchHit<Document extends {
     id: string;
 }> extends SearchHit<Partial<Document>> {
     /** Matched terms, as reported by the engine after tokenization. */
     readonly terms: readonly string[];
 }
+/** Search input: a hard result limit and an App-owned filter, both required on every query. */
 export interface TextSearchQuery<Document extends {
     id: string;
 }> {

package/dist/esm/structs/model/messages.d.ts

@@ -13,6 +13,7 @@ export interface ModelImage {
     /** Provider resolution hint; `original` asks for no downscaling where supported. */
     detail?: 'auto' | 'low' | 'high' | 'original';
 }
+/** One provider-neutral turn; `images` are user visual input and are not part of the text budget. */
 export interface ModelMessage {
     role: 'system' | 'user' | 'assistant';
     /** Rendered text content sent to the model. */
@@ -20,6 +21,7 @@ export interface ModelMessage {
     /** User-supplied visual input. Binary payload is separate from the text character budget. */
     images?: readonly ModelImage[];
 }
+/** Provider-reported token counts for one call; used for accounting, never for admission. */
 export interface ModelUsage {
     /** Input tokens billed for the call. */
     promptTokens: number;
@@ -39,6 +41,7 @@ export interface ModelFunction {
     /** Request strict argument validation from providers that support it. */
     strict?: boolean;
 }
+/** One streamed fragment of a function call; fragments with the same `index` must be joined. */
 export interface FunctionCallDelta {
     type: 'function-call-delta';
     /** Index of the call within the response; deltas with the same index belong together. */
@@ -52,6 +55,7 @@ export interface FunctionCallDelta {
 }
 /** One streamed response part: assistant text or a function-call fragment. */
 export type ModelPart = string | FunctionCallDelta;
+/** Per-call provider options; Core passes them through and does not normalize provider ranges. */
 export interface ModelOptions {
     /** Request a JSON-object response from providers that support it. */
     json?: boolean;

package/dist/esm/structs/support/model/messages.d.ts

@@ -18,6 +18,7 @@ export interface ProviderToolCall {
     /** Raw JSON arguments exactly as the provider produced them. */
     readonly arguments: string;
 }
+/** System instruction turn; text only, so the union rejects images and tool fields here. */
 export interface ProviderSystemMessage {
     readonly role: 'system';
     readonly content: string;
@@ -25,6 +26,7 @@ export interface ProviderSystemMessage {
     readonly toolCallId?: never;
     readonly toolCalls?: never;
 }
+/** User turn; the only message type that may carry images, and never tool calls. */
 export interface ProviderUserMessage {
     readonly role: 'user';
     readonly content: string;

package/dist/esm/support/context/nodes.d.ts

@@ -3,6 +3,7 @@ import type { ContextPlan } from '../../structs/context/processing.js';
 import type { BuiltContext } from '../../structs/context/fragments.js';
 import type { ModelPrepareRequest, PreparedModelCall, ModelTransportDefinition } from '../../structs/model/runtime.js';
 import type { ContextCompressor, ContextSelector, ContextPolicy, ContextProcessingReport } from '../../structs/support/context-processing.js';
+/** Outcome of one context node: the built input, its prepared model call and the change report. */
 export interface ContextNodeResult {
     /** Context built from the processed fragments, sized against the full input limit. */
     readonly input: BuiltContext;
@@ -11,6 +12,13 @@ export interface ContextNodeResult {
     /** What processing changed: characters, token usage, selection decisions and reductions. */
     readonly report: ContextProcessingReport;
 }
+/**
+ * Definition accepted by `createContextProcessingNode`.
+ *
+ * It is a normal Core `WorkflowNode` except that the node body is declared here: `plan` builds the
+ * context, `update` decides the committed state, and policy/handlers/timeout are validated when the
+ * node is created.
+ */
 export type ContextProcessingNodeDefinition<State, Result, App> = Omit<WorkflowNode<State, Result, App>, 'run' | 'report'> & {
     /** Builds the context plan; must be synchronous so budget failures surface before any I/O. */
     readonly plan: (state: Readonly<State>, context: WorkflowContext<App>) => ContextPlan;
@@ -33,6 +41,7 @@ export type ContextProcessingNodeDefinition<State, Result, App> = Omit<WorkflowN
     /** Per-node timeout in milliseconds; defaults to the Core call timeout. */
     readonly timeoutMs?: number;
 };
+/** Result of a selection or reduction stage, before the node's `update` commits chosen fields. */
 export interface ContextStageResult {
     /** Plan describing current fragments at the full (unreduced) input limit. */
     readonly plan: ContextPlan;
@@ -41,14 +50,21 @@ export interface ContextStageResult {
     /** Processing report accumulated by this and preceding steps. */
     readonly report: ContextProcessingReport;
 }
+/** Selection stage result: the chosen step IDs plus the unchanged stage snapshot. */
 export interface ContextSelectionResult extends ContextStageResult {
     /** Registered reduction step IDs chosen for execution; selection itself executes nothing. */
     readonly stepIds: readonly string[];
 }
+/** Definition of a selection node: like a processing node, but `update` receives chosen step IDs. */
 export type ContextSelectionNodeDefinition<State, Result, App> = Omit<ContextProcessingNodeDefinition<State, Result, App>, 'update'> & {
     /** Receives the chosen step IDs so the graph can route to reduction nodes. */
     readonly update: (result: ContextSelectionResult, state: Readonly<State>) => Partial<State>;
 };
+/**
+ * Definition of a reduction node: one registered step is applied per node run.
+ *
+ * `stepId` may be fixed or derived from state, which lets a graph route over several steps.
+ */
 export type ContextReductionNodeDefinition<State, Result, App> = Omit<ContextProcessingNodeDefinition<State, Result, App>, 'update'> & {
     /** ID of the reduction step to run, fixed or derived from state. */
     readonly stepId: string | ((state: Readonly<State>) => string);

package/dist/esm/support/context/processing.d.ts

@@ -49,6 +49,13 @@ export declare const contextReductionCatalog: {
 export declare function validateStructure(fragments: readonly ContextFragment[]): void;
 /** Execution ports accepted by the processing helpers; alias of the Core options contract. */
 export type ProcessingPorts = import('../../structs/support/context-processing.js').ContextProcessingOptions;
+/**
+ * Working state for one context-processing stage.
+ *
+ * `fragments` is mutated in place by reductions while `before` keeps the original snapshot for the
+ * audit report; `ports` carries the signal, diagnostics and call budget already validated by the
+ * caller.
+ */
 export interface ProcessingState {
     /** Token count before processing; present only when a token measurement port was supplied. */
     beforeTokens?: number;

package/dist/esm/support/model/chat-completions.js

@@ -87,7 +87,7 @@ export function chatCompletionParts(delta) {
  */
 export function chatCompletionMessages(messages) {
     return messages.map((message) => {
-        const { role, content, images, toolCalls, toolCallId } = message;
+        const { role, content, images, toolCalls, toolCallId, } = message;
         if (!['system', 'user', 'assistant', 'tool'].includes(role) || typeof content !== 'string')
             throw new TypeError('Invalid provider message role or content');
         if (toolCallId !== undefined && role !== 'tool')

package/dist/esm/support/model/children.d.ts

@@ -11,6 +11,7 @@
 import type { ModelRunner } from '../../model/runner.js';
 import type { ModelChildOptions } from '../../structs/model/runtime.js';
 import type { MaybePromise } from '../../structs/common.js';
+/** One child call in a group: its own limits plus the work to run with the child runner. */
 export interface ModelChildTask<Value> extends ModelChildOptions {
     /**
      * Work executed with the child runner bound to this task's limits.
@@ -19,6 +20,7 @@ export interface ModelChildTask<Value> extends ModelChildOptions {
      */
     run(model: ModelRunner, signal: AbortSignal): MaybePromise<Value>;
 }
+/** Group options: worker count, extra cancellation and accept/commit hooks. */
 export interface ModelChildrenOptions<Value> {
     /** Parallel workers; defaults to, and may not exceed, the parent's concurrency limit. */
     readonly concurrency?: number;

package/dist/esm/support/model/completion/default.d.ts

@@ -7,4 +7,5 @@
  * Exports: `defaultCompletionPolicy`.
  */
 import type { CompletionPolicy } from '../../../structs/support/model/completion.js';
+/** Frozen default policy: strictness depends only on whether the call declared functions. */
 export declare const defaultCompletionPolicy: CompletionPolicy;

package/dist/esm/support/model/completion/default.js

@@ -26,4 +26,5 @@ const policy = {
         };
     },
 };
+/** Frozen default policy: strictness depends only on whether the call declared functions. */
 export const defaultCompletionPolicy = Object.freeze(policy);

package/dist/esm/support/model/completion/session.d.ts

@@ -8,4 +8,9 @@
  * Exports: `sessionCompletionPolicy`.
  */
 import type { CompletionPolicy } from '../../../structs/support/model/completion.js';
+/**
+ * Frozen opt-in policy that judges rules by the request's effective `tool_choice`.
+ *
+ * Consumers that do not select it keep `defaultCompletionPolicy`.
+ */
 export declare const sessionCompletionPolicy: CompletionPolicy;

package/dist/esm/support/model/completion/session.js

@@ -96,4 +96,9 @@ const policy = {
         };
     },
 };
+/**
+ * Frozen opt-in policy that judges rules by the request's effective `tool_choice`.
+ *
+ * Consumers that do not select it keep `defaultCompletionPolicy`.
+ */
 export const sessionCompletionPolicy = Object.freeze(policy);

package/dist/esm/support/model/preview-rules.d.ts

@@ -1,5 +1,10 @@
 import type { JsonSchema } from '../../structs/common.js';
 import type { ReplyPreviewRule } from './reply-preview.js';
+/**
+ * Capability declaration used to derive preview rules.
+ *
+ * Omitted `preview` means the capability never previews, so previewing is an explicit opt-in.
+ */
 export interface ReplyPreviewCapability {
     /** Capability ID, which must equal the native function wire name used for transport. */
     readonly id: string;
@@ -11,6 +16,7 @@ export interface ReplyPreviewCapability {
      */
     readonly preview?: true | Omit<ReplyPreviewRule, 'stageId' | 'capabilityId'>;
 }
+/** Stage declaration: which capabilities it exposes and whether it previews text or arguments. */
 export interface ReplyPreviewStage {
     /** Stage ID used by the workflow and transport projection. */
     readonly id: string;

package/dist/esm/support/model/reply-preview.d.ts

@@ -1,4 +1,9 @@
 import type { ModelOutputEvent } from '../../structs/model/runtime.js';
+/**
+ * One projection rule: which stage/capability it matches and which prose fields may be shown.
+ *
+ * A rule without `capabilityId` may only match a registered plain-text stage.
+ */
 export interface ReplyPreviewRule {
     /** Native function wire name. Omit only for a registered plain-text stage. */
     capabilityId?: string;
@@ -12,6 +17,7 @@ export interface ReplyPreviewRule {
         values: readonly string[];
     };
 }
+/** Rules plus optional renderer and character budget; all values are snapshotted at creation. */
 export interface ReplyPreviewSettings {
     rules: readonly ReplyPreviewRule[];
     /** Presentation only; must not authorize, persist or execute a proposal. */
@@ -19,6 +25,7 @@ export interface ReplyPreviewSettings {
     /** Streamed characters tolerated before preview is disabled; default 16000. */
     maxChars?: number;
 }
+/** Settings for `createReplyPreview`; `sink` receives every bubble list and is required. */
 export interface ReplyPreviewOptions extends ReplyPreviewSettings {
     /** Receives the current bubble list; rejection propagates to the event caller. */
     readonly sink: (bubbles: string[]) => void | Promise<void>;

package/dist/esm/support/model/strategies.d.ts

@@ -36,6 +36,10 @@ export type ModelBudgetStrategy = keyof typeof modelBudgetStrategies | Partial<M
 type StrategyModel<Transports extends readonly ModelTransportDefinition[], Execution> = Omit<ModelRunnerOptions<Transports>, 'execution'> & {
     execution?: Execution;
 };
+/**
+ * Input of `createModelStrategy`: model selection, optional reasoning and budget plus explicit
+ * Core overrides. Explicit Core fields win over every generated value.
+ */
 export type ModelStrategyOptions<Transports extends readonly ModelTransportDefinition[] = readonly ModelTransportDefinition[], Execution = ExecutionOptions> = Partial<StrategyModel<Transports, Execution>> & {
     /** An existing definition, or an ID in the explicitly supplied model catalog. */
     readonly model: StrategyModel<Transports, Execution> | string;

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@jangts/agent-core",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "commonjs",
+  "license": "Apache-2.0",
   "description": "Platform-independent agent runtime and configurable modules for evidence, delivery, policies and interactions",
   "homepage": "https://agent-core-docs.pages.jangts.cafe/",
   "engines": {
@@ -15,7 +16,9 @@
     "dist",
     "development/docs",
     "development/skills",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "LICENSE",
+    "NOTICE"
   ],
   "sideEffects": false,
   "exports": {
@@ -246,7 +249,7 @@
     "docs:api": "node scripts/api-reference.mjs"
   },
   "dependencies": {
-    "@jangts/streaming": "0.1.0",
+    "@jangts/streaming": "^0.1.2",
     "@jangts/mock-gpt": "0.2.0",
     "minisearch": "^7.2.0"
   },