@jangts/agent-core 0.2.0 → 0.2.5

package/dist/esm/structs/execution/engine.d.ts

@@ -8,6 +8,7 @@
  * Exports: `LoopEvent`, `StepOutcome`, `CoreStep`, `AgentCoreEngineOptions`.
  */
 import type { ExecutionContext, ExecutionOptions, MaybePromise } from '../common.js';
+import type { CacheContext, EngineCacheOptions, AgentCachePort } from './cache.js';
 /** Progress fact for one loop round, correlated with the enclosing diagnostics span. */
 export interface LoopEvent {
     /** Unique id of this fact. */
@@ -31,9 +32,13 @@ export type StepOutcome<Value> =
     readonly value: Value;
 };
 /** One loop iteration. Must be re-entrant: the same step object runs every round. */
-export type CoreStep<Result> = (roundIndex: number, context: ExecutionContext & import('../debug.js').NodeReportingContext) => MaybePromise<StepOutcome<Result>>;
+export type CoreStep<Result> = (roundIndex: number, context: ExecutionContext & import('../debug.js').NodeReportingContext & CacheContext) => MaybePromise<StepOutcome<Result>>;
 /** Engine construction options. */
 export interface AgentCoreEngineOptions {
+    /** Engine-local LRU bounds; not copied as cache data when forking. */
+    cache?: EngineCacheOptions;
+    /** Borrowed App service cache; forks must explicitly provide their own port. */
+    agentCache?: AgentCachePort;
     /** Round budget; must be a positive safe integer. Defaults to 8 rounds. */
     maxRounds?: number;
     /** Cancellation and diagnostics shared by every round. */

package/dist/esm/structs/execution/workflow.d.ts

@@ -10,6 +10,7 @@
  * `AgentWorkflowDefinition`, `WorkflowEvent`, `WorkflowFailure`, `WorkflowExtension`,
  * `WorkflowModel`.
  */
+import type { CacheContext } from './cache.js';
 import type { OperationContext } from '../common.js';
 import type { DiagnosticContext } from '../diagnostics.js';
 import type { ModelTransportDefinition } from '../model/runtime.js';
@@ -20,7 +21,7 @@ type WorkflowModelRequest<Transport> = import('../model/runtime.js').ModelCallRe
     readonly modelId?: string;
 };
 /** Execution facts available to every node of a running workflow. */
-export interface WorkflowContext<Runtime = undefined> extends OperationContext<Runtime>, NodeReportingContext {
+export interface WorkflowContext<Runtime = undefined> extends OperationContext<Runtime>, NodeReportingContext, CacheContext {
     /** Zero-based bounded round; phases within a round do not consume another round. */
     readonly roundIndex: number;
     /** Report progress while this node is active; Core supplies its execution identity. */

package/dist/esm/structs/index.d.ts

@@ -54,3 +54,4 @@ export * from './common.js';
 export type * from './invocation.js';
 export type * from './debug.js';
 export type * from './execution/events.js';
+export type * from './execution/cache.js';

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.5",
   "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,8 +249,8 @@
     "docs:api": "node scripts/api-reference.mjs"
   },
   "dependencies": {
-    "@jangts/streaming": "0.1.0",
-    "@jangts/mock-gpt": "0.2.0",
+    "@jangts/streaming": "^0.1.2",
+    "@jangts/mock-gpt": "0.2.2",
     "minisearch": "^7.2.0"
   },
   "devDependencies": {