@jangts/agent-core 0.2.1 → 0.2.5

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

@@ -186,3 +186,13 @@ infers the output type from the object contract, and the same field also accepts
 ### Reports during node execution
 
 `run(state, context)` can call `context.report({ usedModel, payload, subs })` to report progress. usedModel is optional boolean metadata about this node itself and remains unknown when not reported; payload and subs are read only when content is allowed. subs must be the instance created by `context.createSubFlowLogger()` for this execution, and a hand-written array cannot be submitted. write records the intent first and returns an ID, fix adds later results, and readAll returns an immutable snapshot in a fixed format; writes and completions reuse the existing node.progress, and a short circuit or throw still preserves the start record already sent. Reports do not submit business state and do not determine routing; the Loop adds node identity, time, and event ordinal. Late writes are not accepted after cancellation or node completion. The node's `report(update, context)` at completion continues to serve supplementary reporting when content is allowed. For the contract, see [Child log instances](observability.md#sub-log-instances-and-record-first-then-complete).
+
+## Node caches
+
+Engine option `cache: { maxEntries: 1024, ttlMs: 60000 }` configures bounded instance-local LRU memory. Capacity defaults to 1024 across all partitions; omitted TTL means no time-based expiry. Expiry is lazy and measured from writes. Values retain identity, including undefined; has distinguishes a stored undefined from a miss. delete returns a boolean; set and clear return void.
+
+context.cache belongs to the current node. Only get(key, { nodeId }) may read another partition. Other operations only address the current partition, and clear never clears the entire Engine. Low-level run(step) uses `$step`. Runs on one Engine share memory; forks preserve bounds but start with empty memory.
+
+Optional Engine option agentCache accepts an AgentCachePort. context.agentCache exposes asynchronous get/has/set/delete/clear, or is absent when no port is supplied. The App receives immutable addresses with nodeId, key, persistence and signal; clear receives an address without key. Port callbacks retain their receiver. Cancellation is checked before dispatch and after completion; it does not roll back an App write already started.
+
+Persistence defaults to false. Passing true requires supportsPersistence: true; otherwise the call rejects. Volatile and persistent spaces are independent, with no fallback or mirroring. The App owns capacity, TTL, serialization, user isolation and storage. Cache partitions are not authorization boundaries. Fork resume may explicitly return agentCache to restore a borrowed port; it is never inherited implicitly. Cache data is not checkpoint state or durable business evidence, and captured views must not be used after cancellation.

package/development/docs/api/workflow.md

@@ -187,3 +187,25 @@ Loop 将这些补充信息附在节点的完成或跳转记录上。报告失败
 ### 节点运行中的报告
 
 `run(state, context)` 可调用 `context.report({ usedModel, payload, subs })` 报告进度。usedModel 是本次节点自身的可选布尔元数据，未上报保持未知；payload 和 subs 仅在内容获准时读取。subs 必须为 `context.createSubFlowLogger()` 创建的本次执行实例，不能提交手写数组。write 先记意图并返回 ID，fix 补后续结果，readAll 返回固定格式不可变快照；写入和补全复用现有 node.progress，短路或抛错也保留已送出的起始记录。报告不提交业务状态，也不决定路由；Loop 补齐节点身份、时间及事件序号。取消或节点结束后不接纳迟到写入。结束时的节点 `report(update, context)` 继续用于内容获准时的补充报告。合同见[子日志实例](observability.md#子日志实例与先记后补)。
+
+## 节点缓存
+
+Engine 构造参数 `cache: { maxEntries: 1024, ttlMs: 60000 }` 控制实例级内存缓存；maxEntries 缺省 1024，ttlMs 省略表示不按时间过期，采用全 Engine 的 LRU 淘汰，不使用后台定时器。值按引用保存，允许存 undefined，has 可区分未命中与已存 undefined。delete 返回是否删除，set／clear 返回 void。
+
+每个节点通过 context.cache 访问自己的分区。get(key, { nodeId }) 可读取其他节点分区；has、set、delete、clear 只能操作当前节点，clear 不清空其他分区。run(step) 使用保留分区 `$step`。同一 Engine 跨 run 共享；fork 保留容量配置但不复制缓存数据。
+
+可选构造参数 agentCache 接收 AgentCachePort。节点的 context.agentCache 是异步视图，未提供端口时不存在。端口用命名 address 接收 nodeId、key、persistence、signal；clear 接收不含 key 的分区地址。端口方法保留原对象 this。所有节点操作前后检查本次取消；取消不会回滚已开始的 App 存储写入。
+
+```ts
+// 在节点 run 中：
+context.cache.set('selection', value);
+const prior = context.cache.get('selection');
+if (context.agentCache) {
+  await context.agentCache.set('summary', summary);
+  const saved = await context.agentCache.get('summary');
+}
+```
+
+agentCache 每个操作默认 persistence: false；true 必须由 supportsPersistence: true 的 App 端口明确支持，否则拒绝。两种空间不回退、不镜像，delete／clear 仅影响指定空间及当前分区。App 负责容量、TTL、序列化、用户／租户隔离和持久化。节点分区不是授权边界，不复用权限结论。
+
+缓存不进入 checkpoint／状态／Durable 恢复。fork 的 resume 可显式返回 agentCache 重新绑定 App 端口；默认不继承。需要重放或持久业务事实的数据仍使用原 state 补丁或 App 存储。取消后不可继续使用捕获的节点缓存视图。

package/development/skills/agent-core-app/SKILL.md

@@ -70,3 +70,7 @@ Use `docs.acceptance` to select checks for concrete uncertainties, while followi
 ## Custom model transport boundaries
 
 A custom response collector is synchronous and request-local. Its outputChars must be a nonnegative safe integer after creation, each push and finish. An explicit infinite maxOutputChars budget does not permit infinite or invalid collector counts. Core records the largest valid observed count; finish may release buffers. Optional call metadata is read once on a best-effort basis and cannot replace the actual result, original failure or cancellation. Prefer Support transports for standard native calls and JSON; custom transports must preserve complete parsing, budgets and cancellation before any tool execution.
+
+## Node cache ownership
+
+Use context.cache for bounded Engine memory; its default capacity is 1024, partitions are node-local and only get may name another node. The low-level step partition is `$step`. An App may explicitly inject an asynchronous AgentCachePort for context.agentCache. Persistence must be supported explicitly, is separate from volatile storage and never falls back. The App owns user isolation, serialization, capacity and expiry; do not cache authorization decisions. Forks start with empty Engine memory and only regain an App port when resume explicitly supplies agentCache. Keep durable facts in state/App storage, not caches.

package/dist/cjs/execution/cache.js

@@ -0,0 +1,162 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineCache = void 0;
+exports.cachePort = cachePort;
+exports.cacheContext = cacheContext;
+const cancellation_js_1 = require("../utils/cancellation.js");
+/** Validate the small cache-specific boundary; business permissions remain App-owned. */
+function textKey(value) {
+    if (typeof value !== 'string' || !value.length)
+        throw new TypeError('Cache keys must be nonempty strings');
+    return value;
+}
+/** Reject accidental cross-partition writes and unknown options instead of ignoring them. */
+function optionsOf(value, allowed) {
+    if (value !== undefined &&
+        (!value ||
+            typeof value !== 'object' ||
+            Reflect.ownKeys(value).some((key) => typeof key !== 'string' || !allowed.includes(key))))
+        throw new TypeError('Invalid cache options');
+}
+/** Bounded LRU for one Engine; forks get new memory, and values are deliberately not cloned. */
+class EngineCache {
+    entries = new Map();
+    limit;
+    ttl;
+    constructor(options = {}) {
+        this.limit = options.maxEntries ?? 1024;
+        this.ttl = options.ttlMs ?? Infinity;
+        if (!Number.isSafeInteger(this.limit) ||
+            this.limit < 1 ||
+            (this.ttl !== Infinity && (!Number.isSafeInteger(this.ttl) || this.ttl < 1)))
+            throw new TypeError('Invalid Engine cache bounds');
+    }
+    /** Remove expired entries lazily, without timers or background tasks. */
+    prune() {
+        const now = Date.now();
+        for (const [key, item] of this.entries)
+            if (item.expires <= now)
+                this.entries.delete(key);
+    }
+    /** Capture an immutable partition and visit signal; no per-run cache is introduced. */
+    view(nodeId, signal) {
+        textKey(nodeId);
+        const prefix = JSON.stringify([nodeId]).slice(0, -1) + ',';
+        const address = (key, node = nodeId) => JSON.stringify([textKey(node), textKey(key)]);
+        const read = (key, node = nodeId) => {
+            signal.throwIfAborted();
+            const id = address(key, node);
+            const item = this.entries.get(id);
+            if (item && item.expires <= Date.now()) {
+                this.entries.delete(id);
+                return undefined;
+            }
+            if (item) {
+                this.entries.delete(id);
+                this.entries.set(id, item);
+            }
+            return item;
+        };
+        return Object.freeze({
+            get: (key, options) => {
+                optionsOf(options, ['nodeId']);
+                return read(key, options?.nodeId)?.value;
+            },
+            has: (key) => read(key) !== undefined,
+            set: (key, value) => {
+                signal.throwIfAborted();
+                const id = address(key);
+                this.prune();
+                this.entries.delete(id);
+                this.entries.set(id, { value, expires: Date.now() + this.ttl });
+                if (this.entries.size > this.limit)
+                    this.entries.delete(this.entries.keys().next().value);
+            },
+            delete: (key) => {
+                signal.throwIfAborted();
+                return this.entries.delete(address(key));
+            },
+            clear: () => {
+                signal.throwIfAborted();
+                for (const key of this.entries.keys())
+                    if (key.startsWith(prefix))
+                        this.entries.delete(key);
+            },
+        });
+    }
+}
+exports.EngineCache = EngineCache;
+/** Snapshot port callbacks with their receiver, rejecting incomplete App storage early. */
+function cachePort(port) {
+    if (port === undefined)
+        return undefined;
+    const handlers = ['get', 'has', 'set', 'delete', 'clear'];
+    if (!port ||
+        handlers.some((key) => typeof port[key] !== 'function') ||
+        (port.supportsPersistence !== undefined && typeof port.supportsPersistence !== 'boolean'))
+        throw new TypeError('Invalid Agent cache port');
+    return Object.freeze({
+        supportsPersistence: port.supportsPersistence === true,
+        get: port.get.bind(port),
+        has: port.has.bind(port),
+        set: port.set.bind(port),
+        delete: port.delete.bind(port),
+        clear: port.clear.bind(port),
+    });
+}
+/** Build visit-local views. Persistent writes remain external side effects owned by the App. */
+function cacheContext(memory, port, nodeId, signal) {
+    const partition = (options, crossRead = false) => {
+        signal.throwIfAborted();
+        optionsOf(options, crossRead ? ['nodeId', 'persistence'] : ['persistence']);
+        const persistence = options?.persistence ?? false;
+        if (typeof persistence !== 'boolean')
+            throw new TypeError('Invalid cache persistence');
+        if (persistence && !port?.supportsPersistence)
+            throw new TypeError('Agent cache persistence is unsupported');
+        return Object.freeze({
+            nodeId: textKey(crossRead ? (options?.nodeId ?? nodeId) : nodeId),
+            persistence,
+            signal,
+        });
+    };
+    const address = (key, options, crossRead = false) => Object.freeze({ ...partition(options, crossRead), key: textKey(key) });
+    const call = async (invoke) => {
+        signal.throwIfAborted();
+        const value = await (0, cancellation_js_1.awaitWithSignal)(invoke(), signal);
+        signal.throwIfAborted();
+        return value;
+    };
+    return {
+        cache: memory.view(nodeId, signal),
+        ...(port
+            ? {
+                agentCache: Object.freeze({
+                    get: (key, options) => call(() => port.get(address(key, options, true))),
+                    has: (key, options) => call(async () => {
+                        const result = await port.has(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache has must return boolean');
+                        return result;
+                    }),
+                    set: (key, value, options) => call(async () => {
+                        const result = await port.set(address(key, options), value);
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache set must return void');
+                    }),
+                    delete: (key, options) => call(async () => {
+                        const result = await port.delete(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache delete must return boolean');
+                        return result;
+                    }),
+                    clear: (options) => call(async () => {
+                        const result = await port.clear(partition(options));
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache clear must return void');
+                    }),
+                }),
+            }
+            : {}),
+    };
+}

package/dist/cjs/execution/engine.js

@@ -26,6 +26,7 @@ exports.AgentCoreEngine = void 0;
  *
  * Exports: `AgentCoreEngine` and the engine option/identity types.
  */
+const cache_js_1 = require("./cache.js");
 const call_budget_js_1 = require("../model/call-budget.js");
 const runner_js_1 = require("../model/runner.js");
 const binding_js_1 = require("../model/binding.js");
@@ -56,6 +57,8 @@ class AgentCoreEngine {
     static AttemptBudget = workflow_js_1.AttemptBudget;
     /** Factory for a validated workflow definition. */
     static createWorkflow = workflow_js_1.defineWorkflow;
+    cacheMemory;
+    serviceCache;
     maxRounds;
     exhausted;
     options;
@@ -306,6 +309,8 @@ class AgentCoreEngine {
         (0, rules_js_1.breakWhile)(!!this.invokeTool && !dependencies?.tools, 'Fork requires a restored tool runtime');
         const engine = new AgentCoreEngine({
             maxRounds: this.maxRounds,
+            cache: this.options.cache,
+            agentCache: dependencies?.agentCache,
             errors: { exhausted: this.exhausted },
             execution: {
                 diagnostics: this.options.execution?.diagnostics,
@@ -350,6 +355,8 @@ class AgentCoreEngine {
             ['maxSteps', 'exhausted', 'signal', 'diagnostics', 'onWorkflowEvent', 'observe'].some((key) => key in settings)) {
             throw new TypeError('Use maxRounds, execution (including observe) and errors');
         }
+        this.cacheMemory = new cache_js_1.EngineCache(settings.cache);
+        this.serviceCache = (0, cache_js_1.cachePort)(settings.agentCache);
         const execution = settings.execution;
         if (settings.branch !== undefined)
             this.branchIdentity = (0, branch_js_1.snapshotBranch)(settings.branch);
@@ -359,6 +366,7 @@ class AgentCoreEngine {
             settings.errors?.exhausted?.bind(settings.errors) ??
                 (() => new errors_js_2.BudgetError('Agent round budget exhausted'));
         this.options = {
+            cache: { ...settings.cache },
             execution: {
                 signal: execution?.signal,
                 diagnostics: execution?.diagnostics,
@@ -478,6 +486,7 @@ class AgentCoreEngine {
                 phase = 'run';
                 signal.throwIfAborted();
                 const result = await (0, cancellation_js_1.awaitWithSignal)(step(index, {
+                    ...(0, cache_js_1.cacheContext)(this.cacheMemory, this.serviceCache, '$step', signal),
                     signal,
                     diagnostics,
                     report: reports.report.bind(reports),
@@ -673,6 +682,7 @@ class AgentCoreEngine {
             });
             const reports = new reporting_js_1.NodeReports(nodeDiagnostics, signal);
             const context = {
+                ...(0, cache_js_1.cacheContext)(this.cacheMemory, this.serviceCache, node.id, signal),
                 report: reports.report.bind(reports),
                 createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
                 roundIndex: round,

package/dist/cjs/kits/vector-search.js

@@ -80,11 +80,8 @@ class VectorSearch {
                 (!Number.isFinite(options.minScore) || options.minScore < -1 || options.minScore > 1)), 'Invalid vector query');
         const query = normalize(vector, this.space.dimensions), groups = new Map();
         for (const [id, { document, vector: value }] of this.entries) {
-            // One isolated snapshot per candidate serves filter, grouping and the
-            // returned hit; filters and groupers are typed readonly, so sharing it
-            // removes the redundant clones without exposing the index.
-            const candidate = structuredClone(document);
-            const allowed = (0, synchronous_js_1.booleanResult)(options.filter(candidate), 'Vector filters must be synchronous', 'Vector filters must return boolean');
+            // Each callback receives its own snapshot; readonly types cannot prevent runtime mutation.
+            const allowed = (0, synchronous_js_1.booleanResult)(options.filter(structuredClone(document)), 'Vector filters must be synchronous', 'Vector filters must return boolean');
             if (!allowed)
                 continue;
             let score = 0;
@@ -93,12 +90,12 @@ class VectorSearch {
             score = Math.max(-1, Math.min(1, score));
             if (score < (options.minScore ?? -1))
                 continue;
-            const group = (0, synchronous_js_1.synchronous)(options.groupBy?.(candidate), 'Vector grouping must be synchronous') ?? id;
+            const group = (0, synchronous_js_1.synchronous)(options.groupBy?.(structuredClone(document)), 'Vector grouping must be synchronous') ?? id;
             if (typeof group !== 'string')
                 throw new TypeError('Vector groups must be strings');
             const prior = groups.get(group);
             if (!prior || score > prior.score || (score === prior.score && id < prior.id))
-                groups.set(group, { id, score, document: candidate });
+                groups.set(group, { id, score, document: structuredClone(document) });
         }
         return [...groups.values()]
             .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))

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

@@ -0,0 +1,6 @@
+"use strict";
+/**
+ * Node-partitioned cache contracts. Engine memory is synchronous; service-owned storage is
+ * asynchronous and explicitly selects volatile or persistent space. Neither is workflow state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

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

@@ -0,0 +1,20 @@
+/**
+ * Engine memory and borrowed service storage views. Partition ownership is captured per visit,
+ * never in a mutable service field. Cache calls do not create model budgets or execute tools.
+ */
+import type { AgentCachePort, CacheContext, EngineCacheOptions, NodeCache } from '../structs/execution/cache.js';
+/** Bounded LRU for one Engine; forks get new memory, and values are deliberately not cloned. */
+export declare class EngineCache {
+    private readonly entries;
+    private readonly limit;
+    private readonly ttl;
+    constructor(options?: EngineCacheOptions);
+    /** Remove expired entries lazily, without timers or background tasks. */
+    private prune;
+    /** Capture an immutable partition and visit signal; no per-run cache is introduced. */
+    view(nodeId: string, signal: AbortSignal): NodeCache;
+}
+/** Snapshot port callbacks with their receiver, rejecting incomplete App storage early. */
+export declare function cachePort(port?: AgentCachePort): AgentCachePort | undefined;
+/** Build visit-local views. Persistent writes remain external side effects owned by the App. */
+export declare function cacheContext(memory: EngineCache, port: AgentCachePort | undefined, nodeId: string, signal: AbortSignal): CacheContext;

package/dist/esm/execution/cache.js

@@ -0,0 +1,156 @@
+import { awaitWithSignal } from '../utils/cancellation.js';
+/** Validate the small cache-specific boundary; business permissions remain App-owned. */
+function textKey(value) {
+    if (typeof value !== 'string' || !value.length)
+        throw new TypeError('Cache keys must be nonempty strings');
+    return value;
+}
+/** Reject accidental cross-partition writes and unknown options instead of ignoring them. */
+function optionsOf(value, allowed) {
+    if (value !== undefined &&
+        (!value ||
+            typeof value !== 'object' ||
+            Reflect.ownKeys(value).some((key) => typeof key !== 'string' || !allowed.includes(key))))
+        throw new TypeError('Invalid cache options');
+}
+/** Bounded LRU for one Engine; forks get new memory, and values are deliberately not cloned. */
+export class EngineCache {
+    entries = new Map();
+    limit;
+    ttl;
+    constructor(options = {}) {
+        this.limit = options.maxEntries ?? 1024;
+        this.ttl = options.ttlMs ?? Infinity;
+        if (!Number.isSafeInteger(this.limit) ||
+            this.limit < 1 ||
+            (this.ttl !== Infinity && (!Number.isSafeInteger(this.ttl) || this.ttl < 1)))
+            throw new TypeError('Invalid Engine cache bounds');
+    }
+    /** Remove expired entries lazily, without timers or background tasks. */
+    prune() {
+        const now = Date.now();
+        for (const [key, item] of this.entries)
+            if (item.expires <= now)
+                this.entries.delete(key);
+    }
+    /** Capture an immutable partition and visit signal; no per-run cache is introduced. */
+    view(nodeId, signal) {
+        textKey(nodeId);
+        const prefix = JSON.stringify([nodeId]).slice(0, -1) + ',';
+        const address = (key, node = nodeId) => JSON.stringify([textKey(node), textKey(key)]);
+        const read = (key, node = nodeId) => {
+            signal.throwIfAborted();
+            const id = address(key, node);
+            const item = this.entries.get(id);
+            if (item && item.expires <= Date.now()) {
+                this.entries.delete(id);
+                return undefined;
+            }
+            if (item) {
+                this.entries.delete(id);
+                this.entries.set(id, item);
+            }
+            return item;
+        };
+        return Object.freeze({
+            get: (key, options) => {
+                optionsOf(options, ['nodeId']);
+                return read(key, options?.nodeId)?.value;
+            },
+            has: (key) => read(key) !== undefined,
+            set: (key, value) => {
+                signal.throwIfAborted();
+                const id = address(key);
+                this.prune();
+                this.entries.delete(id);
+                this.entries.set(id, { value, expires: Date.now() + this.ttl });
+                if (this.entries.size > this.limit)
+                    this.entries.delete(this.entries.keys().next().value);
+            },
+            delete: (key) => {
+                signal.throwIfAborted();
+                return this.entries.delete(address(key));
+            },
+            clear: () => {
+                signal.throwIfAborted();
+                for (const key of this.entries.keys())
+                    if (key.startsWith(prefix))
+                        this.entries.delete(key);
+            },
+        });
+    }
+}
+/** Snapshot port callbacks with their receiver, rejecting incomplete App storage early. */
+export function cachePort(port) {
+    if (port === undefined)
+        return undefined;
+    const handlers = ['get', 'has', 'set', 'delete', 'clear'];
+    if (!port ||
+        handlers.some((key) => typeof port[key] !== 'function') ||
+        (port.supportsPersistence !== undefined && typeof port.supportsPersistence !== 'boolean'))
+        throw new TypeError('Invalid Agent cache port');
+    return Object.freeze({
+        supportsPersistence: port.supportsPersistence === true,
+        get: port.get.bind(port),
+        has: port.has.bind(port),
+        set: port.set.bind(port),
+        delete: port.delete.bind(port),
+        clear: port.clear.bind(port),
+    });
+}
+/** Build visit-local views. Persistent writes remain external side effects owned by the App. */
+export function cacheContext(memory, port, nodeId, signal) {
+    const partition = (options, crossRead = false) => {
+        signal.throwIfAborted();
+        optionsOf(options, crossRead ? ['nodeId', 'persistence'] : ['persistence']);
+        const persistence = options?.persistence ?? false;
+        if (typeof persistence !== 'boolean')
+            throw new TypeError('Invalid cache persistence');
+        if (persistence && !port?.supportsPersistence)
+            throw new TypeError('Agent cache persistence is unsupported');
+        return Object.freeze({
+            nodeId: textKey(crossRead ? (options?.nodeId ?? nodeId) : nodeId),
+            persistence,
+            signal,
+        });
+    };
+    const address = (key, options, crossRead = false) => Object.freeze({ ...partition(options, crossRead), key: textKey(key) });
+    const call = async (invoke) => {
+        signal.throwIfAborted();
+        const value = await awaitWithSignal(invoke(), signal);
+        signal.throwIfAborted();
+        return value;
+    };
+    return {
+        cache: memory.view(nodeId, signal),
+        ...(port
+            ? {
+                agentCache: Object.freeze({
+                    get: (key, options) => call(() => port.get(address(key, options, true))),
+                    has: (key, options) => call(async () => {
+                        const result = await port.has(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache has must return boolean');
+                        return result;
+                    }),
+                    set: (key, value, options) => call(async () => {
+                        const result = await port.set(address(key, options), value);
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache set must return void');
+                    }),
+                    delete: (key, options) => call(async () => {
+                        const result = await port.delete(address(key, options));
+                        if (typeof result !== 'boolean')
+                            throw new TypeError('Agent cache delete must return boolean');
+                        return result;
+                    }),
+                    clear: (options) => call(async () => {
+                        const result = await port.clear(partition(options));
+                        if (result !== undefined)
+                            throw new TypeError('Agent cache clear must return void');
+                    }),
+                }),
+            }
+            : {}),
+    };
+}

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

@@ -1,3 +1,4 @@
+import type { AgentCachePort } from '../structs/execution/cache.js';
 import { ModelRunner } from '../model/runner.js';
 import type { ModelRunnerOptions } from '../structs/model/runtime.js';
 import type { ToolRegistry } from '../capabilities/tools.js';
@@ -5,6 +6,7 @@ import type { AgentCoreEngineOptions, CoreStep } from '../structs/execution/engi
 import { AgentWorkflow, AttemptBudget, defineWorkflow } from './workflow.js';
 import type { WorkflowExtension } from '../structs/execution/workflow.js';
 export * from './workflow.js';
+export type * from '../structs/execution/cache.js';
 type InvokeTool = (request: import('../structs/capabilities/tools.js').ToolInvocationRequest) => Promise<import('../structs/invocation.js').ToolResult<unknown>>;
 type ToolBinding = {
     invoke: InvokeTool;
@@ -109,6 +111,8 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
     static readonly AttemptBudget: typeof AttemptBudget;
     /** Factory for a validated workflow definition. */
     static readonly createWorkflow: typeof defineWorkflow;
+    private readonly cacheMemory;
+    private readonly serviceCache?;
     private readonly maxRounds;
     private readonly exhausted;
     private readonly options;
@@ -264,6 +268,7 @@ export declare class AgentCoreEngine<Result, State = unknown, App = undefined> {
             app?: App;
             tools?: ToolBinding;
             model?: AgentModelRuntime;
+            agentCache?: AgentCachePort;
         };
     }): AgentCoreEngine<Result, State, App>;
     /**

package/dist/esm/execution/engine.js

@@ -9,6 +9,7 @@
  *
  * Exports: `AgentCoreEngine` and the engine option/identity types.
  */
+import { EngineCache, cacheContext, cachePort } from './cache.js';
 import { ModelCallBudget, parentModelBudget } from '../model/call-budget.js';
 import { ModelRunner } from '../model/runner.js';
 import { compiledModelBinding, modelBindingId, snapshotModelBinding, } from '../model/binding.js';
@@ -39,6 +40,8 @@ export class AgentCoreEngine {
     static AttemptBudget = AttemptBudget;
     /** Factory for a validated workflow definition. */
     static createWorkflow = defineWorkflow;
+    cacheMemory;
+    serviceCache;
     maxRounds;
     exhausted;
     options;
@@ -289,6 +292,8 @@ export class AgentCoreEngine {
         breakWhile(!!this.invokeTool && !dependencies?.tools, 'Fork requires a restored tool runtime');
         const engine = new AgentCoreEngine({
             maxRounds: this.maxRounds,
+            cache: this.options.cache,
+            agentCache: dependencies?.agentCache,
             errors: { exhausted: this.exhausted },
             execution: {
                 diagnostics: this.options.execution?.diagnostics,
@@ -333,6 +338,8 @@ export class AgentCoreEngine {
             ['maxSteps', 'exhausted', 'signal', 'diagnostics', 'onWorkflowEvent', 'observe'].some((key) => key in settings)) {
             throw new TypeError('Use maxRounds, execution (including observe) and errors');
         }
+        this.cacheMemory = new EngineCache(settings.cache);
+        this.serviceCache = cachePort(settings.agentCache);
         const execution = settings.execution;
         if (settings.branch !== undefined)
             this.branchIdentity = snapshotBranch(settings.branch);
@@ -342,6 +349,7 @@ export class AgentCoreEngine {
             settings.errors?.exhausted?.bind(settings.errors) ??
                 (() => new BudgetError('Agent round budget exhausted'));
         this.options = {
+            cache: { ...settings.cache },
             execution: {
                 signal: execution?.signal,
                 diagnostics: execution?.diagnostics,
@@ -461,6 +469,7 @@ export class AgentCoreEngine {
                 phase = 'run';
                 signal.throwIfAborted();
                 const result = await awaitWithSignal(step(index, {
+                    ...cacheContext(this.cacheMemory, this.serviceCache, '$step', signal),
                     signal,
                     diagnostics,
                     report: reports.report.bind(reports),
@@ -656,6 +665,7 @@ export class AgentCoreEngine {
             });
             const reports = new NodeReports(nodeDiagnostics, signal);
             const context = {
+                ...cacheContext(this.cacheMemory, this.serviceCache, node.id, signal),
                 report: reports.report.bind(reports),
                 createSubFlowLogger: reports.createSubFlowLogger.bind(reports),
                 roundIndex: round,

package/dist/esm/kits/vector-search.js

@@ -77,11 +77,8 @@ export class VectorSearch {
                 (!Number.isFinite(options.minScore) || options.minScore < -1 || options.minScore > 1)), 'Invalid vector query');
         const query = normalize(vector, this.space.dimensions), groups = new Map();
         for (const [id, { document, vector: value }] of this.entries) {
-            // One isolated snapshot per candidate serves filter, grouping and the
-            // returned hit; filters and groupers are typed readonly, so sharing it
-            // removes the redundant clones without exposing the index.
-            const candidate = structuredClone(document);
-            const allowed = booleanResult(options.filter(candidate), 'Vector filters must be synchronous', 'Vector filters must return boolean');
+            // Each callback receives its own snapshot; readonly types cannot prevent runtime mutation.
+            const allowed = booleanResult(options.filter(structuredClone(document)), 'Vector filters must be synchronous', 'Vector filters must return boolean');
             if (!allowed)
                 continue;
             let score = 0;
@@ -90,12 +87,12 @@ export class VectorSearch {
             score = Math.max(-1, Math.min(1, score));
             if (score < (options.minScore ?? -1))
                 continue;
-            const group = synchronous(options.groupBy?.(candidate), 'Vector grouping must be synchronous') ?? id;
+            const group = synchronous(options.groupBy?.(structuredClone(document)), 'Vector grouping must be synchronous') ?? id;
             if (typeof group !== 'string')
                 throw new TypeError('Vector groups must be strings');
             const prior = groups.get(group);
             if (!prior || score > prior.score || (score === prior.score && id < prior.id))
-                groups.set(group, { id, score, document: candidate });
+                groups.set(group, { id, score, document: structuredClone(document) });
         }
         return [...groups.values()]
             .sort((a, b) => b.score - a.score || a.id.localeCompare(b.id))