@aigne/agent-runtime 1.12.0-beta.5

package/dist/agent-runners/memory-afs.cjs

@@ -0,0 +1,342 @@
+let _aigne_afs_memory = require("@aigne/afs-memory");
+
+//#region src/agent-runners/memory-afs.ts
+const MEMORY_SCOPE_ROOT = "/memory";
+const MEMORY_PREFIX = `${MEMORY_SCOPE_ROOT}/`;
+/** Paths that must route to the scope-local memory provider. */
+function isMemoryPath(path) {
+	return path === MEMORY_SCOPE_ROOT || path.startsWith(MEMORY_PREFIX);
+}
+/**
+* Strip the `/memory` mount prefix, yielding the provider-relative path
+* (`/memory/.actions/remember` → `/.actions/remember`, `/memory` → `/`).
+*/
+function providerPath(path) {
+	if (path === MEMORY_SCOPE_ROOT) return "/";
+	const rest = path.slice(7);
+	return rest.startsWith("/") ? rest : `/${rest}`;
+}
+let agentIndexAfs;
+/**
+* Daemon wire-up companion to `setAgentMemoryRoot`: attach a global AFS
+* reference that the per-scope memory provider can use to dispatch
+* `/modules/index/.actions/index` calls. Without this, `AFSMemory`'s
+* built-in `indexEntry` step (every observation goes through the
+* configured index) silently no-ops because the scope-local provider
+* has no `afsRoot` set (it's attached via Object.create overlay, not
+* `afs.mount()`).
+*/
+function setAgentIndexAfs(afs) {
+	agentIndexAfs = afs;
+}
+/** Test-only — used by `afterEach` to drop the configured index AFS. */
+function clearAgentIndexAfsForTesting() {
+	agentIndexAfs = void 0;
+}
+let agentMemoryRoot;
+/**
+* Daemon wire-up: configure a process-wide root directory for agent
+* memory. When set, `createMemoryProvider({ domain })` (no `storagePath`)
+* resolves storage to `<root>/<domain>/` via `FSStorage`. Production
+* daemons set this once at startup so cross-session recall works
+* without each call site threading the path.
+*
+* Tests should clear via `clearAgentMemoryRootForTesting()` between
+* cases to keep the cache clean.
+*/
+function setAgentMemoryRoot(root) {
+	agentMemoryRoot = root;
+}
+/** Test-only — used by `afterEach` to reset between cases. */
+function clearAgentMemoryRootForTesting() {
+	agentMemoryRoot = void 0;
+}
+/**
+* Symbol key used to attach per-session memory storage to the session AFS.
+* Propagates through `Object.create(sessionAfs)` prototype chains, so all
+* scope-local AFS objects derived from the session AFS inherit it without
+* explicit threading.
+*
+* Set via `attachSessionMemoryStorage()` in `buildCfSessionView` (CF) and
+* `buildSessionView` (Node) for authenticated callers. Anonymous callers
+* or sessions without a DID Space get no storage attached (undefined →
+* falls through to FSStorage / InMemoryStorage legacy path).
+*/
+const SESSION_MEMORY_STORAGE_KEY = Symbol("sessionMemoryStorage");
+/**
+* Attach an AFS-backed memory storage to the session AFS so that all
+* scope-local AFS objects derived from it (via `Object.create`) inherit
+* the storage via prototype-chain lookup.
+*
+* Call this in `buildCfSessionView` / `buildSessionView` for authenticated
+* callers: `attachSessionMemoryStorage(sessionView, new AFSBackedStorage(sessionView, "/user/memory"))`.
+*/
+function attachSessionMemoryStorage(afs, storage) {
+	Object.defineProperty(afs, SESSION_MEMORY_STORAGE_KEY, {
+		value: storage,
+		writable: false,
+		configurable: false,
+		enumerable: false
+	});
+}
+/**
+* Build memory storage for the given scope AFS using the session-attached
+* storage (set via `attachSessionMemoryStorage`). Returns undefined when no
+* storage is attached (anonymous callers, tests without wiring).
+*/
+function buildMemoryStorageForAfs(afs) {
+	return afs[SESSION_MEMORY_STORAGE_KEY];
+}
+const SESSION_INDEX_KEY = Symbol("sessionIndexConfig");
+/**
+* Point per-caller memory at a per-caller index. Companion to
+* `attachSessionMemoryStorage`: when set, `createMemoryProvider` dispatches
+* `indexEntry`/`queryIndex` to `config.afsRoot` at the given paths instead of
+* the process-global `agentIndexAfs` + `/modules/index`. Propagates through
+* `Object.create(sessionAfs)` prototype chains. CF calls this in
+* `buildCfSessionView`; Node leaves it unset (keeps the global index).
+*/
+function attachSessionIndex(afs, config) {
+	Object.defineProperty(afs, SESSION_INDEX_KEY, {
+		value: config,
+		writable: false,
+		configurable: false,
+		enumerable: false
+	});
+}
+/** Read the session-attached index config (via prototype chain), or undefined. */
+function readSessionIndex(afs) {
+	return afs[SESSION_INDEX_KEY];
+}
+/**
+* Spread-ready index opts for `createMemoryProvider`, derived from the session's
+* attached index config. Empty object when none is attached (Node / anonymous)
+* → the provider keeps the process-global index root + default `/modules/index`.
+*/
+function buildMemoryIndexOptsForAfs(afs) {
+	const cfg = readSessionIndex(afs);
+	if (!cfg) return {};
+	return {
+		afsRoot: cfg.afsRoot,
+		indexQueryPath: cfg.indexQueryPath,
+		indexWritePath: cfg.indexWritePath
+	};
+}
+const providerCache = /* @__PURE__ */ new Map();
+/** Test-only — used by `afterEach` to drop cached instances. */
+function clearMemoryProviderCacheForTesting() {
+	providerCache.clear();
+}
+function resolveStoragePath(opts) {
+	if (typeof opts.storagePath === "string" && opts.storagePath.length > 0) return opts.storagePath;
+	if (typeof agentMemoryRoot === "string" && agentMemoryRoot.length > 0) return agentMemoryRoot;
+}
+/**
+* Instantiate an `AFSMemory` suitable for a scope-local `/memory/` mount.
+*
+* Storage selection follows this order:
+*
+*   1. Explicit `opts.storage` — used as-is, not cached (caller controls lifecycle).
+*   2. Explicit `opts.storagePath` (typically test fixtures).
+*   3. Process-wide `agentMemoryRoot` set by the daemon — yields
+*      `<root>/<domain>` via `FSStorage`. Cross-session recall lives here.
+*   4. Default `InMemoryStorage` — used when no persistence is configured
+*      (legacy + most tests).
+*
+* Provider instances are cached by `(domain, resolvedPath)` for cases 2–4.
+* Case 1 (explicit storage) is not cached because the storage is per-session.
+*/
+function createMemoryProvider(opts) {
+	validateDomain(opts.domain);
+	if (opts.storage) {
+		const provider$1 = new _aigne_afs_memory.AFSMemory({
+			name: opts.name ?? `memory:${opts.domain}`,
+			defaultDomain: opts.domain,
+			enforceDefaultDomain: true,
+			storage: opts.storage,
+			indexQueryPath: opts.indexQueryPath,
+			indexWritePath: opts.indexWritePath
+		});
+		const indexAfs = opts.afsRoot ?? agentIndexAfs;
+		if (indexAfs) provider$1.afsRoot = indexAfs;
+		return provider$1;
+	}
+	const storagePath = resolveStoragePath(opts);
+	const cacheKey = `${opts.domain}::${storagePath ?? ":memory:"}`;
+	if (!opts._bypassCache) {
+		const cached = providerCache.get(cacheKey);
+		if (cached) return cached;
+	}
+	const storage = storagePath ? new _aigne_afs_memory.FSStorage(storagePath) : new _aigne_afs_memory.InMemoryStorage();
+	const provider = new _aigne_afs_memory.AFSMemory({
+		name: opts.name ?? `memory:${opts.domain}`,
+		defaultDomain: opts.domain,
+		enforceDefaultDomain: true,
+		storage
+	});
+	if (agentIndexAfs) provider.afsRoot = agentIndexAfs;
+	if (!opts._bypassCache) providerCache.set(cacheKey, provider);
+	return provider;
+}
+function validateDomain(domain) {
+	if (typeof domain !== "string" || domain.length === 0) throw new Error(`MEMORY_DOMAIN_INVALID: domain must be a non-empty string`);
+	if (!/^[a-zA-Z0-9_-]+$/.test(domain)) throw new Error(`MEMORY_DOMAIN_INVALID: domain "${domain}" must match [a-zA-Z0-9_-]+ — segments, null bytes, and path traversal are rejected`);
+}
+/**
+* Overlay `/memory/*` onto `afs`, routing to `provider`. Delegates via
+* `Object.create(afs)` so siblings / other mounts on the same scope still
+* resolve through the parent's prototype chain.
+*
+* We forward to `provider.<op>(providerPath(path), …)` rather than to an
+* internal AFS + `afs.mount(provider, "/memory")` — the provider's
+* `AFSBaseProvider` already takes absolute-from-root paths, so one layer
+* of routing is enough. Skipping the extra AFS means we don't have to
+* await a `mount()` during scope projection (projectForChild is sync).
+*
+* Unlike the sibling `attachScratchMount` (which asserts valid scratch
+* segments at the overlay), we defer path-traversal / null-byte /
+* separator checks to `AFSMemory`'s own `AFSBaseProvider`. The provider
+* enforces the memory segment grammar at every action entry point, so a
+* parallel check here would be redundant. See
+* `providers/core/memory/src/provider.ts` and its action handlers.
+*/
+function attachMemoryMount(afs, provider) {
+	const child = Object.create(afs);
+	Object.defineProperty(child, "read", {
+		value: async (path, options) => {
+			if (isMemoryPath(path)) return provider.read(providerPath(path), options);
+			return afs.read.call(afs, path, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(child, "list", {
+		value: async (path, options) => {
+			if (isMemoryPath(path)) return provider.list(providerPath(path), options);
+			return afs.list.call(afs, path, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(child, "exec", {
+		value: async (path, args, options) => {
+			if (isMemoryPath(path)) return provider.exec(providerPath(path), args, options);
+			return afs.exec.call(afs, path, args, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(child, "write", {
+		value: async (path, payload, options) => {
+			if (isMemoryPath(path)) return provider.write(providerPath(path), payload, options);
+			if (typeof afs.write !== "function") throw new Error(`MEMORY_MOUNT_NO_UNDERLYING_WRITE: afs.write not available for ${path}`);
+			return afs.write.call(afs, path, payload, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(child, "stat", {
+		value: async (path, options) => {
+			if (isMemoryPath(path)) return provider.stat(providerPath(path), options);
+			return afs.stat.call(afs, path, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	Object.defineProperty(child, "delete", {
+		value: async (path, options) => {
+			if (isMemoryPath(path)) return provider.delete(providerPath(path), options);
+			if (typeof afs.delete !== "function") return { success: false };
+			return afs.delete.call(afs, path, options);
+		},
+		enumerable: false,
+		writable: false,
+		configurable: false
+	});
+	return child;
+}
+/**
+* Resolve the domain used to instantiate a scope's AFSMemory.
+*
+* Precedence (design doc §3.3):
+*   1. Explicit `manifest.memory.domain`
+*   2. Parent scope's current memory domain (if already memory-backed)
+*   3. The child's member name, derived from memberPath (final non-empty segment)
+*
+* The resulting string is validated against the memory provider's segment
+* grammar; path traversal, separators, and empty strings all fail loudly.
+*/
+function resolveMemoryDomain(opts) {
+	const fromManifest = extractManifestDomain(opts.manifestMemory);
+	if (fromManifest) {
+		validateDomain(fromManifest);
+		return fromManifest;
+	}
+	if (opts.parentDomain) {
+		validateDomain(opts.parentDomain);
+		return opts.parentDomain;
+	}
+	const memberName = deriveMemberId(opts.memberPath);
+	validateDomain(memberName);
+	return memberName;
+}
+function extractManifestDomain(manifestMemory) {
+	if (typeof manifestMemory !== "object" || manifestMemory === null) return void 0;
+	const domain = manifestMemory.domain;
+	return typeof domain === "string" && domain.length > 0 ? domain : void 0;
+}
+/**
+* Unified surface helper — mount /memory/ when a manifest declares memory.
+*
+* Consolidates the 3-step pattern (resolveMemoryDomain → createMemoryProvider →
+* attachMemoryMount) that previously appeared independently in each surface
+* handler (chat: agent-handler.ts, terminal: agent-runner-registry.ts).
+* All surfaces call this instead of replicating the logic.
+*
+* Safe to call unconditionally:
+*  - skips when manifestMemory is falsy
+*  - skips when the caller's AFS already carries a memory domain in scope
+*    (inherits parent mount rather than layering a fresh provider)
+*/
+function mountManifestMemory(afs, manifestMemory, memberPath) {
+	if (!manifestMemory || typeof manifestMemory !== "object" && manifestMemory !== true) return afs;
+	if (afs.scope?.memoryDomain) return afs;
+	return attachMemoryMount(afs, createMemoryProvider({
+		domain: resolveMemoryDomain({
+			manifestMemory,
+			memberPath
+		}),
+		storage: buildMemoryStorageForAfs(afs),
+		...buildMemoryIndexOptsForAfs(afs)
+	}));
+}
+function deriveMemberId(memberPath) {
+	const trimmed = memberPath.replace(/\/+$/, "");
+	const cleaned = trimmed.slice(trimmed.lastIndexOf("/") + 1).replace(/[^a-zA-Z0-9_-]/g, "-");
+	return cleaned.length > 0 ? cleaned : "scope";
+}
+
+//#endregion
+exports.MEMORY_SCOPE_ROOT = MEMORY_SCOPE_ROOT;
+exports.SESSION_MEMORY_STORAGE_KEY = SESSION_MEMORY_STORAGE_KEY;
+exports.attachMemoryMount = attachMemoryMount;
+exports.attachSessionIndex = attachSessionIndex;
+exports.attachSessionMemoryStorage = attachSessionMemoryStorage;
+exports.buildMemoryIndexOptsForAfs = buildMemoryIndexOptsForAfs;
+exports.buildMemoryStorageForAfs = buildMemoryStorageForAfs;
+exports.clearAgentIndexAfsForTesting = clearAgentIndexAfsForTesting;
+exports.clearAgentMemoryRootForTesting = clearAgentMemoryRootForTesting;
+exports.clearMemoryProviderCacheForTesting = clearMemoryProviderCacheForTesting;
+exports.createMemoryProvider = createMemoryProvider;
+exports.extractManifestDomain = extractManifestDomain;
+exports.isMemoryPath = isMemoryPath;
+exports.mountManifestMemory = mountManifestMemory;
+exports.readSessionIndex = readSessionIndex;
+exports.resolveMemoryDomain = resolveMemoryDomain;
+exports.setAgentIndexAfs = setAgentIndexAfs;
+exports.setAgentMemoryRoot = setAgentMemoryRoot;

package/dist/agent-runners/memory-afs.d.cts

@@ -0,0 +1,221 @@
+import { AFSRoot } from "@aigne/afs";
+import { AFSMemory, MemoryStorage } from "@aigne/afs-memory";
+
+//#region src/agent-runners/memory-afs.d.ts
+declare const MEMORY_SCOPE_ROOT = "/memory";
+/** Paths that must route to the scope-local memory provider. */
+declare function isMemoryPath(path: string): boolean;
+interface CreateMemoryProviderOptions {
+  /**
+   * Logical tenant. Baked into the provider as `defaultDomain`; any action
+   * that omits `domain` in its args falls back to this value. The overlay
+   * treats `domain` as fixed-at-construction — runtime callers cannot
+   * widen it by passing a different arg, because storage is already
+   * tenant-scoped.
+   */
+  readonly domain: string;
+  /**
+   * Optional instance name (shows up in descriptions / traces). Defaults
+   * to `memory:<domain>`.
+   */
+  readonly name?: string;
+  /**
+   * When set, persist observations to the local filesystem under this
+   * directory via `FSStorage`. When unset, falls back to the
+   * process-wide `agentMemoryRoot` (set via `setAgentMemoryRoot()`); when
+   * neither is set, falls back to `InMemoryStorage` (legacy behavior).
+   *
+   * The provider keyed by `(domain, resolvedStoragePath)` is cached
+   * process-wide so multiple scopes for the same tenant share the same
+   * `AFSMemory` instance — without that, two scopes pointing at the same
+   * directory would each get their own `FSStorage`, doubling on-disk
+   * fan-out and confusing the `consolidate`/`aging` background jobs that
+   * AFSMemory schedules at construction time.
+   */
+  readonly storagePath?: string;
+  /**
+   * Explicit storage backend. When provided, skips path-based storage
+   * selection (storagePath / agentMemoryRoot) and uses this directly.
+   * Used when the session AFS is the backing store (DID Space persistence).
+   * Providers created with explicit storage are NOT cached (each caller
+   * has a distinct backing AFS).
+   */
+  readonly storage?: MemoryStorage;
+  /**
+   * Test-only escape hatch: bypass the provider cache and always return a
+   * fresh instance. Used by the persistence test to prove storage is at
+   * the FS layer (not at the JS-object layer).
+   */
+  readonly _bypassCache?: boolean;
+  /**
+   * Explicit AFS root for index dispatch (indexEntry on remember/archive,
+   * queryIndex on recall). When set, overrides the process-global
+   * `agentIndexAfs` for THIS provider — used by CF per-caller memory, where
+   * the caller's session view (holding `/user/index`) is the correct index
+   * root, not a process global (which would be shared across concurrent
+   * callers). Node leaves this unset → keeps the global `/modules/index`.
+   */
+  readonly afsRoot?: {
+    exec?: (...args: unknown[]) => unknown;
+  };
+  /**
+   * Override the default index query path (`/modules/index/.actions/query`).
+   * Set to `/user/index/.actions/query` for per-caller user-axis indexing.
+   */
+  readonly indexQueryPath?: string;
+  /**
+   * Override the default index write path (`/modules/index/.actions/index`).
+   * Set to `/user/index/.actions/index` for per-caller user-axis indexing.
+   */
+  readonly indexWritePath?: string;
+}
+/**
+ * Daemon wire-up companion to `setAgentMemoryRoot`: attach a global AFS
+ * reference that the per-scope memory provider can use to dispatch
+ * `/modules/index/.actions/index` calls. Without this, `AFSMemory`'s
+ * built-in `indexEntry` step (every observation goes through the
+ * configured index) silently no-ops because the scope-local provider
+ * has no `afsRoot` set (it's attached via Object.create overlay, not
+ * `afs.mount()`).
+ */
+declare function setAgentIndexAfs(afs: {
+  exec?: (...args: any[]) => any;
+} | undefined): void;
+/** Test-only — used by `afterEach` to drop the configured index AFS. */
+declare function clearAgentIndexAfsForTesting(): void;
+/**
+ * Daemon wire-up: configure a process-wide root directory for agent
+ * memory. When set, `createMemoryProvider({ domain })` (no `storagePath`)
+ * resolves storage to `<root>/<domain>/` via `FSStorage`. Production
+ * daemons set this once at startup so cross-session recall works
+ * without each call site threading the path.
+ *
+ * Tests should clear via `clearAgentMemoryRootForTesting()` between
+ * cases to keep the cache clean.
+ */
+declare function setAgentMemoryRoot(root: string | undefined): void;
+/** Test-only — used by `afterEach` to reset between cases. */
+declare function clearAgentMemoryRootForTesting(): void;
+/**
+ * Symbol key used to attach per-session memory storage to the session AFS.
+ * Propagates through `Object.create(sessionAfs)` prototype chains, so all
+ * scope-local AFS objects derived from the session AFS inherit it without
+ * explicit threading.
+ *
+ * Set via `attachSessionMemoryStorage()` in `buildCfSessionView` (CF) and
+ * `buildSessionView` (Node) for authenticated callers. Anonymous callers
+ * or sessions without a DID Space get no storage attached (undefined →
+ * falls through to FSStorage / InMemoryStorage legacy path).
+ */
+declare const SESSION_MEMORY_STORAGE_KEY: unique symbol;
+/**
+ * Attach an AFS-backed memory storage to the session AFS so that all
+ * scope-local AFS objects derived from it (via `Object.create`) inherit
+ * the storage via prototype-chain lookup.
+ *
+ * Call this in `buildCfSessionView` / `buildSessionView` for authenticated
+ * callers: `attachSessionMemoryStorage(sessionView, new AFSBackedStorage(sessionView, "/user/memory"))`.
+ */
+declare function attachSessionMemoryStorage(afs: AFSRoot, storage: MemoryStorage): void;
+/**
+ * Build memory storage for the given scope AFS using the session-attached
+ * storage (set via `attachSessionMemoryStorage`). Returns undefined when no
+ * storage is attached (anonymous callers, tests without wiring).
+ */
+declare function buildMemoryStorageForAfs(afs: AFSRoot): MemoryStorage | undefined;
+/** Per-session index dispatch config, attached in `buildCfSessionView`. */
+interface SessionIndexConfig {
+  /** AFS whose `indexQueryPath`/`indexWritePath` resolve to the caller's index. */
+  readonly afsRoot: {
+    exec?: (...args: unknown[]) => unknown;
+  };
+  readonly indexQueryPath: string;
+  readonly indexWritePath: string;
+}
+/**
+ * Point per-caller memory at a per-caller index. Companion to
+ * `attachSessionMemoryStorage`: when set, `createMemoryProvider` dispatches
+ * `indexEntry`/`queryIndex` to `config.afsRoot` at the given paths instead of
+ * the process-global `agentIndexAfs` + `/modules/index`. Propagates through
+ * `Object.create(sessionAfs)` prototype chains. CF calls this in
+ * `buildCfSessionView`; Node leaves it unset (keeps the global index).
+ */
+declare function attachSessionIndex(afs: AFSRoot, config: SessionIndexConfig): void;
+/** Read the session-attached index config (via prototype chain), or undefined. */
+declare function readSessionIndex(afs: AFSRoot): SessionIndexConfig | undefined;
+/**
+ * Spread-ready index opts for `createMemoryProvider`, derived from the session's
+ * attached index config. Empty object when none is attached (Node / anonymous)
+ * → the provider keeps the process-global index root + default `/modules/index`.
+ */
+declare function buildMemoryIndexOptsForAfs(afs: AFSRoot): Pick<CreateMemoryProviderOptions, "afsRoot" | "indexQueryPath" | "indexWritePath">;
+/** Test-only — used by `afterEach` to drop cached instances. */
+declare function clearMemoryProviderCacheForTesting(): void;
+/**
+ * Instantiate an `AFSMemory` suitable for a scope-local `/memory/` mount.
+ *
+ * Storage selection follows this order:
+ *
+ *   1. Explicit `opts.storage` — used as-is, not cached (caller controls lifecycle).
+ *   2. Explicit `opts.storagePath` (typically test fixtures).
+ *   3. Process-wide `agentMemoryRoot` set by the daemon — yields
+ *      `<root>/<domain>` via `FSStorage`. Cross-session recall lives here.
+ *   4. Default `InMemoryStorage` — used when no persistence is configured
+ *      (legacy + most tests).
+ *
+ * Provider instances are cached by `(domain, resolvedPath)` for cases 2–4.
+ * Case 1 (explicit storage) is not cached because the storage is per-session.
+ */
+declare function createMemoryProvider(opts: CreateMemoryProviderOptions): AFSMemory;
+/**
+ * Overlay `/memory/*` onto `afs`, routing to `provider`. Delegates via
+ * `Object.create(afs)` so siblings / other mounts on the same scope still
+ * resolve through the parent's prototype chain.
+ *
+ * We forward to `provider.<op>(providerPath(path), …)` rather than to an
+ * internal AFS + `afs.mount(provider, "/memory")` — the provider's
+ * `AFSBaseProvider` already takes absolute-from-root paths, so one layer
+ * of routing is enough. Skipping the extra AFS means we don't have to
+ * await a `mount()` during scope projection (projectForChild is sync).
+ *
+ * Unlike the sibling `attachScratchMount` (which asserts valid scratch
+ * segments at the overlay), we defer path-traversal / null-byte /
+ * separator checks to `AFSMemory`'s own `AFSBaseProvider`. The provider
+ * enforces the memory segment grammar at every action entry point, so a
+ * parallel check here would be redundant. See
+ * `providers/core/memory/src/provider.ts` and its action handlers.
+ */
+declare function attachMemoryMount<T extends AFSRoot>(afs: T, provider: AFSMemory): T;
+/**
+ * Resolve the domain used to instantiate a scope's AFSMemory.
+ *
+ * Precedence (design doc §3.3):
+ *   1. Explicit `manifest.memory.domain`
+ *   2. Parent scope's current memory domain (if already memory-backed)
+ *   3. The child's member name, derived from memberPath (final non-empty segment)
+ *
+ * The resulting string is validated against the memory provider's segment
+ * grammar; path traversal, separators, and empty strings all fail loudly.
+ */
+declare function resolveMemoryDomain(opts: {
+  manifestMemory: unknown;
+  parentDomain?: string;
+  memberPath: string;
+}): string;
+/**
+ * Unified surface helper — mount /memory/ when a manifest declares memory.
+ *
+ * Consolidates the 3-step pattern (resolveMemoryDomain → createMemoryProvider →
+ * attachMemoryMount) that previously appeared independently in each surface
+ * handler (chat: agent-handler.ts, terminal: agent-runner-registry.ts).
+ * All surfaces call this instead of replicating the logic.
+ *
+ * Safe to call unconditionally:
+ *  - skips when manifestMemory is falsy
+ *  - skips when the caller's AFS already carries a memory domain in scope
+ *    (inherits parent mount rather than layering a fresh provider)
+ */
+declare function mountManifestMemory<T extends AFSRoot>(afs: T, manifestMemory: unknown, memberPath: string): T;
+//#endregion
+export { CreateMemoryProviderOptions, MEMORY_SCOPE_ROOT, SESSION_MEMORY_STORAGE_KEY, SessionIndexConfig, attachMemoryMount, attachSessionIndex, attachSessionMemoryStorage, buildMemoryIndexOptsForAfs, buildMemoryStorageForAfs, clearAgentIndexAfsForTesting, clearAgentMemoryRootForTesting, clearMemoryProviderCacheForTesting, createMemoryProvider, isMemoryPath, mountManifestMemory, readSessionIndex, resolveMemoryDomain, setAgentIndexAfs, setAgentMemoryRoot };
+//# sourceMappingURL=memory-afs.d.cts.map

package/dist/agent-runners/memory-afs.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-afs.d.cts","names":[],"sources":["../../src/agent-runners/memory-afs.ts"],"mappings":";;;;cAmCa,iBAAA;;iBAIG,YAAA,CAAa,IAAA;AAAA,UAcZ,2BAAA;EAkDM;;;;;;AAwBvB;EAxBuB,SA1CZ,MAAA;;;;;WAKA,IAAA;EA6DyE;;AAKpF;;;;;AAgBA;;;;;AAKA;EA1BoF,SA/CzE,WAAA;;;;AAwFX;;;;WAhFW,OAAA,GAAU,aAAA;EA0FL;;;;;EAAA,SApFL,YAAA;EAoFuD;;;;AAclE;;;;EAdkE,SA3EvD,OAAA;IAAY,IAAA,OAAW,IAAA;EAAA;EAyFmC;;AAKrE;;EALqE,SApF1D,cAAA;EAyFwB;;;;EAAA,SApFxB,cAAA;AAAA;;;AAqGX;;;;;;;iBAvFgB,gBAAA,CAAiB,GAAA;EAAO,IAAA,OAAW,IAAA;AAAA;AAiGnD;AAAA,iBA5FgB,4BAAA,CAAA;;;;;;;;AAqGhB;;;iBArFgB,kBAAA,CAAmB,IAAA;;iBAKnB,8BAAA,CAAA;;;;;;;;;AA+FhB;;;cAhFa,0BAAA;;AAmHb;;;;;;;iBAzGgB,0BAAA,CAA2B,GAAA,EAAK,OAAA,EAAS,OAAA,EAAS,aAAA;;AA6LlE;;;;iBA/KgB,wBAAA,CAAyB,GAAA,EAAK,OAAA,GAAU,aAAA;;UAKvC,kBAAA;EA0KmE;EAAA,SAxKzE,OAAA;IAAW,IAAA,OAAW,IAAA;EAAA;EAAA,SACtB,cAAA;EAAA,SACA,cAAA;AAAA;;;;;AA+PX;;;;iBAlPgB,kBAAA,CAAmB,GAAA,EAAK,OAAA,EAAS,MAAA,EAAQ,kBAAA;;iBAUzC,gBAAA,CAAiB,GAAA,EAAK,OAAA,GAAU,kBAAA;;;;AA8QhD;;iBArQgB,0BAAA,CACd,GAAA,EAAK,OAAA,GACJ,IAAA,CAAK,2BAAA;;iBAaQ,kCAAA,CAAA;;;;;;;;;;;;;;;;iBAmCA,oBAAA,CAAqB,IAAA,EAAM,2BAAA,GAA8B,SAAA;;;;;;;;;;;;;;;;;;;iBAoFzD,iBAAA,WAA4B,OAAA,CAAA,CAAS,GAAA,EAAK,CAAA,EAAG,QAAA,EAAU,SAAA,GAAY,CAAA;;;;;;;;;;;;iBAyFnE,mBAAA,CAAoB,IAAA;EAClC,cAAA;EACA,YAAA;EACA,UAAA;AAAA;;;;;;;;;;;;;;iBAmCc,mBAAA,WAA8B,OAAA,CAAA,CAC5C,GAAA,EAAK,CAAA,EACL,cAAA,WACA,UAAA,WACC,CAAA"}