@jangts/agent-core 0.2.1 → 0.3.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,11 @@ 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.
+
+## Optional definition decorators
+
+Use the standard-only /support/decorators entry for class-based definitions or existing host methods. Classes supply original options except id; the decorator constructs once and supplies id. Host methods bind and register automatically during standard instance initialization; read and execute only after successful construction. Constructor failures do not roll back initializer registration. Use long-lived service hosts, never request-scoped ones. Keep helper methods/private fields in their real class, never a duplicate options metadata block or empty carrier. Existing Nest legacy compilation keeps object definitions. No public metadata-plus-function adapters, Engine factories, automatic DI or request lifecycle wrappers are provided. Use nodePool/toolPool/fragmentPool/workflowPool/agentPool/modelPool, without creating pools or manually registering. Decorator ns is a string or string array, default 'default'; same-kind ids are unique within a namespace. Read get(id, ns?), getAll(ns?) or pick(ids, ns?); get may return undefined. Multi-namespace registration shares one definition and preflights all conflicts. ESM/CJS copies share readers within one realm. Read api/decorators.md for registration, receivers and type limits.

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/decorators/definition.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classDecoration = classDecoration;
+exports.methodDecoration = methodDecoration;
+/**
+ * Internal decoration: construct definition classes or bind methods to their real host,
+ * compile through existing entry points and automatically register in the kind's root.
+ */
+const pool_js_1 = require("./pool.js");
+/** Restore only the decorator-owned id, preserving instance identity, getters and private state. */
+function withId(id, instance) {
+    if ('id' in instance)
+        throw new TypeError('Decoration supplies id; do not also define it on the class');
+    Object.defineProperty(instance, 'id', { value: id, enumerable: true });
+    return instance;
+}
+/** Class definitions register once after static initialization and successful construction. */
+function classDecoration(kind, id, options, compile) {
+    return (_target, context) => {
+        if (context?.kind !== 'class')
+            throw new TypeError('Use standard class decorator semantics');
+        context.addInitializer(function () {
+            (0, pool_js_1.registerDefinition)(kind, compile(withId(id, new this())), options.ns);
+        });
+    };
+}
+/** Method initializers bind and register automatically; no scanning or caller-side bind is needed. */
+function methodDecoration(kind, id, metadata, handlerKey, options, compile) {
+    return (method, context) => {
+        if (context?.kind !== 'method' || context.static || context.private)
+            throw new TypeError('Use a standard public instance method decorator');
+        context.addInitializer(function () {
+            const value = { ...metadata, [handlerKey]: method.bind(this) };
+            for (const key of Reflect.ownKeys(value)) {
+                const member = value[key];
+                if (typeof member === 'function')
+                    value[key] = member.bind(this);
+            }
+            (0, pool_js_1.registerDefinition)(kind, compile(withId(id, value)), options.ns);
+        });
+    };
+}

package/dist/cjs/support/decorators/index.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelPool = exports.agentPool = exports.workflowPool = exports.fragmentPool = exports.toolPool = exports.nodePool = void 0;
+exports.node = node;
+exports.tool = tool;
+exports.fragment = fragment;
+exports.workflow = workflow;
+exports.agent = agent;
+exports.model = model;
+const tools_js_1 = require("../tools.js");
+const workflow_js_1 = require("../../execution/workflow.js");
+const assembly_js_1 = require("../context/assembly.js");
+const binding_js_1 = require("../../model/binding.js");
+const definition_js_1 = require("./definition.js");
+var pool_js_1 = require("./pool.js");
+Object.defineProperty(exports, "nodePool", { enumerable: true, get: function () { return pool_js_1.nodePool; } });
+Object.defineProperty(exports, "toolPool", { enumerable: true, get: function () { return pool_js_1.toolPool; } });
+Object.defineProperty(exports, "fragmentPool", { enumerable: true, get: function () { return pool_js_1.fragmentPool; } });
+Object.defineProperty(exports, "workflowPool", { enumerable: true, get: function () { return pool_js_1.workflowPool; } });
+Object.defineProperty(exports, "agentPool", { enumerable: true, get: function () { return pool_js_1.agentPool; } });
+Object.defineProperty(exports, "modelPool", { enumerable: true, get: function () { return pool_js_1.modelPool; } });
+/** Internal conversion shared by node/tool/fragment; never a public free-function adapter. */
+function decorate(kind, id, options, key, compile) {
+    return (value, context) => {
+        if (context?.kind === 'class') {
+            (0, definition_js_1.classDecoration)(kind, id, options, compile)(value, context);
+        }
+        else {
+            const { ns, ...metadata } = options;
+            (0, definition_js_1.methodDecoration)(kind, id, metadata, key, { ns }, compile)(value, context);
+        }
+    };
+}
+function node(id, options = {}) {
+    return decorate('node', id, options, 'run', (value) => value);
+}
+function tool(id, options = {}) {
+    return decorate('tool', id, options, 'execute', (value) => (0, tools_js_1.defineTool)(value));
+}
+function fragment(id, options = {}) {
+    return decorate('fragment', id, options, 'format', (value) => {
+        (0, assembly_js_1.defineContextFragments)([value]);
+        return value;
+    });
+}
+/** Instantiate and validate workflow options, leaving actual execution with the original Engine. */
+function workflow(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('workflow', id, options, (value) => {
+        (0, workflow_js_1.defineWorkflow)(value);
+        return value;
+    });
+}
+/** Instantiate an Engine configuration class without creating an Engine, budget or request. */
+function agent(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('agent', id, options, (value) => value);
+}
+/** Instantiate and validate model options without creating a Runner or consuming calls. */
+function model(id, options = {}) {
+    return (0, definition_js_1.classDecoration)('model', id, options, (value) => {
+        (0, binding_js_1.snapshotModelBinding)(value);
+        return value;
+    });
+}

package/dist/cjs/support/decorators/pool.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.modelPool = exports.agentPool = exports.workflowPool = exports.fragmentPool = exports.toolPool = exports.nodePool = exports.definitionKinds = void 0;
+exports.registerDefinition = registerDefinition;
+/**
+ * One process-realm definition registry per kind. The shared symbol makes ESM/CJS copies
+ * consume the same stores; consumers receive frozen read-only views, never pool factories.
+ */
+const protocol_registry_js_1 = require("../../utils/protocol-registry.js");
+/** Enumerable categories drive allocation and lookup; no additional runtime dispatch layer. */
+exports.definitionKinds = ['node', 'tool', 'fragment', 'workflow', 'agent', 'model'];
+const sharedKey = Symbol.for('@jangts/agent-core/decorator-roots/v2');
+const realm = globalThis;
+/** Allocate once per realm, including when another module format initialized the roots first. */
+function sharedPools() {
+    const existing = realm[sharedKey];
+    if (existing) {
+        if (existing.version !== 2 || exports.definitionKinds.some((kind) => !existing.stores[kind]))
+            throw new TypeError('Incompatible decorator root registry');
+        return existing;
+    }
+    const stores = Object.fromEntries(exports.definitionKinds.map((kind) => [kind, new Map()]));
+    const pools = Object.freeze({ version: 2, stores: Object.freeze(stores) });
+    Object.defineProperty(globalThis, sharedKey, { value: pools });
+    return pools;
+}
+/** Namespace is an exact, nonblank key; no trimming, fallback or hierarchy is applied. */
+function namespace(value) {
+    if (typeof value !== 'string' || !value.trim())
+        throw new TypeError('Decorator namespace must be a nonempty string');
+    return value;
+}
+/** Preflight every destination so a conflict never leaves partial multi-namespace registration. */
+function registerDefinition(kind, definition, ns = 'default') {
+    if (typeof definition.id !== 'string' || !definition.id.trim())
+        throw new TypeError('Invalid decorator definition id');
+    const requested = typeof ns === 'string' ? [ns] : ns;
+    if (!Array.isArray(requested) || requested.length === 0)
+        throw new TypeError('Decorator ns must be a namespace or a nonempty namespace array');
+    const names = [...new Set(requested.map(namespace))];
+    const store = sharedPools().stores[kind];
+    for (const name of names) {
+        if (store.get(name)?.has(definition.id))
+            throw new Error(`Duplicate ${kind} definition: ${definition.id} (ns: ${name})`);
+    }
+    for (const name of names) {
+        let entries = store.get(name);
+        if (!entries)
+            store.set(name, (entries = new protocol_registry_js_1.ProtocolRegistry()));
+        entries.set(definition.id, definition);
+    }
+}
+/** Root reads never instantiate or execute definitions; array results are immutable snapshots. */
+function reader(kind) {
+    const store = sharedPools().stores[kind];
+    return Object.freeze({
+        get(id, ns = 'default') {
+            return store.get(namespace(ns))?.get(id);
+        },
+        getAll(ns = 'default') {
+            return Object.freeze([...(store.get(namespace(ns))?.values() ?? [])]);
+        },
+        pick(ids, ns = 'default') {
+            const entries = store.get(namespace(ns));
+            const selected = new protocol_registry_js_1.ProtocolRegistry();
+            for (const id of ids) {
+                const definition = entries?.get(id);
+                if (!definition)
+                    throw new TypeError(`Unknown ${kind} definition: ${id} (ns: ${ns})`);
+                selected.set(id, definition);
+            }
+            return Object.freeze([...selected.values()]);
+        },
+    });
+}
+/** Decorated nodes; ids are unique within each namespace. */
+exports.nodePool = reader('node');
+/** Decorated tools; namespaces isolate otherwise identical ids. */
+exports.toolPool = reader('tool');
+/** Decorated fragment configurations; use the original builder to assemble them. */
+exports.fragmentPool = reader('fragment');
+/** Decorated workflow definitions; execution still belongs to the original Engine. */
+exports.workflowPool = reader('workflow');
+/** Decorated Engine options; request-specific App contracts are supplied on typed reads. */
+exports.agentPool = reader('agent');
+/** Decorated Runner options; reading does not create a Runner or spend model calls. */
+exports.modelPool = reader('model');

package/dist/cjs/support/decorators/types.js

@@ -0,0 +1,2 @@
+"use strict";
+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;