@jangts/agent-core 0.2.0 → 0.2.5

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/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/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))

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 {};