@jangts/agent-core 0.2.1 → 0.2.5

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

@@ -0,0 +1,54 @@
+/**
+ * Node-partitioned cache contracts. Engine memory is synchronous; service-owned storage is
+ * asynchronous and explicitly selects volatile or persistent space. Neither is workflow state.
+ */
+/** Optional Engine memory bounds; TTL is measured from the latest write. */
+export interface EngineCacheOptions {
+    readonly maxEntries?: number;
+    readonly ttlMs?: number;
+}
+/** Only reads may name another node. Partition names are not authorization boundaries. */
+export interface CacheReadOptions {
+    readonly nodeId?: string;
+}
+/** Synchronous view of the current node's Engine-owned memory. Values retain identity. */
+export interface NodeCache {
+    get(key: string, options?: CacheReadOptions): unknown;
+    has(key: string): boolean;
+    set(key: string, value: unknown): void;
+    delete(key: string): boolean;
+    clear(): void;
+}
+/** Persistent and volatile storage are independent; there is no implicit fallback or mirroring. */
+export interface AgentCacheOptions {
+    readonly persistence?: boolean;
+}
+/** Exact immutable address passed to the App port, including cancellation for this visit. */
+export interface AgentCacheAddress {
+    readonly nodeId: string;
+    readonly key: string;
+    readonly persistence: boolean;
+    readonly signal: AbortSignal;
+}
+/** App-owned storage. Capacity, expiry, serialization and user isolation belong to the App. */
+export interface AgentCachePort {
+    readonly supportsPersistence?: boolean;
+    get(address: AgentCacheAddress): Promise<unknown>;
+    has(address: AgentCacheAddress): Promise<boolean>;
+    set(address: AgentCacheAddress, value: unknown): Promise<void>;
+    delete(address: AgentCacheAddress): Promise<boolean>;
+    clear(partition: Omit<AgentCacheAddress, 'key'>): Promise<void>;
+}
+/** Async node view. Writes and clear can only address the current partition. */
+export interface NodeAgentCache {
+    get(key: string, options?: AgentCacheOptions & CacheReadOptions): Promise<unknown>;
+    has(key: string, options?: AgentCacheOptions): Promise<boolean>;
+    set(key: string, value: unknown, options?: AgentCacheOptions): Promise<void>;
+    delete(key: string, options?: AgentCacheOptions): Promise<boolean>;
+    clear(options?: AgentCacheOptions): Promise<void>;
+}
+/** Cache access shared by workflow visits and the low-level $step loop. */
+export interface CacheContext {
+    readonly cache: NodeCache;
+    readonly agentCache?: NodeAgentCache;
+}

package/dist/esm/structs/execution/cache.js

@@ -0,0 +1,5 @@
+/**
+ * Node-partitioned cache contracts. Engine memory is synchronous; service-owned storage is
+ * asynchronous and explicitly selects volatile or persistent space. Neither is workflow state.
+ */
+export {};

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jangts/agent-core",
-  "version": "0.2.1",
+  "version": "0.2.5",
   "type": "commonjs",
   "license": "Apache-2.0",
   "description": "Platform-independent agent runtime and configurable modules for evidence, delivery, policies and interactions",
@@ -250,7 +250,7 @@
   },
   "dependencies": {
     "@jangts/streaming": "^0.1.2",
-    "@jangts/mock-gpt": "0.2.0",
+    "@jangts/mock-gpt": "0.2.2",
     "minisearch": "^7.2.0"
   },
   "devDependencies": {