@aigne/agent-runtime 1.12.0-beta.5

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

@@ -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.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory-afs.d.mts","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"}

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

@@ -0,0 +1,326 @@
+import { AFSMemory, FSStorage, InMemoryStorage } from "@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 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 FSStorage(storagePath) : new InMemoryStorage();
+	const provider = new 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
+export { MEMORY_SCOPE_ROOT, SESSION_MEMORY_STORAGE_KEY, attachMemoryMount, attachSessionIndex, attachSessionMemoryStorage, buildMemoryIndexOptsForAfs, buildMemoryStorageForAfs, clearAgentIndexAfsForTesting, clearAgentMemoryRootForTesting, clearMemoryProviderCacheForTesting, createMemoryProvider, extractManifestDomain, isMemoryPath, mountManifestMemory, readSessionIndex, resolveMemoryDomain, setAgentIndexAfs, setAgentMemoryRoot };
+//# sourceMappingURL=memory-afs.mjs.map

package/dist/agent-runners/memory-afs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-afs.mjs","names":["provider"],"sources":["../../src/agent-runners/memory-afs.ts"],"sourcesContent":["/**\n * Memory Projection — per-scope `/memory/*` overlay backed by a fresh\n * `AFSMemory` provider instance.\n *\n * Pre-Phase-3 each blocklet shared the runtime-level `/modules/memory/`\n * mount and separated tenants via a `domain` arg. Phase 3 replaces that\n * with physical isolation: every scope that declares `memory: true`\n * owns its own `AFSMemory` + `InMemoryStorage` (swap-in FSStorage later),\n * and the overlay here routes reads/writes/lists/execs on `/memory/*`\n * straight to that instance. Other paths fall through to the parent AFS\n * via the prototype chain.\n *\n * Why per-scope rather than one shared instance: see\n * `docs/architecture/agent-memory.md` §1.3 — domain strings are a\n * semantic tag, not a security boundary. Physical isolation at the\n * provider instance level is what keeps one blocklet's memory from\n * being reachable by another, regardless of what arg the LLM sends.\n */\n\nimport type {\n  AFSExecOptions,\n  AFSExecResult,\n  AFSListOptions,\n  AFSListResult,\n  AFSReadOptions,\n  AFSReadResult,\n  AFSRoot,\n  AFSStatOptions,\n  AFSStatResult,\n  AFSWriteOptions,\n  AFSWriteResult,\n} from \"@aigne/afs\";\nimport type { MemoryStorage } from \"@aigne/afs-memory\";\nimport { AFSMemory, FSStorage, InMemoryStorage } from \"@aigne/afs-memory\";\n\nexport const MEMORY_SCOPE_ROOT = \"/memory\";\nconst MEMORY_PREFIX = `${MEMORY_SCOPE_ROOT}/`;\n\n/** Paths that must route to the scope-local memory provider. */\nexport function isMemoryPath(path: string): boolean {\n  return path === MEMORY_SCOPE_ROOT || path.startsWith(MEMORY_PREFIX);\n}\n\n/**\n * Strip the `/memory` mount prefix, yielding the provider-relative path\n * (`/memory/.actions/remember` → `/.actions/remember`, `/memory` → `/`).\n */\nfunction providerPath(path: string): string {\n  if (path === MEMORY_SCOPE_ROOT) return \"/\";\n  const rest = path.slice(MEMORY_SCOPE_ROOT.length);\n  return rest.startsWith(\"/\") ? rest : `/${rest}`;\n}\n\nexport interface CreateMemoryProviderOptions {\n  /**\n   * Logical tenant. Baked into the provider as `defaultDomain`; any action\n   * that omits `domain` in its args falls back to this value. The overlay\n   * treats `domain` as fixed-at-construction — runtime callers cannot\n   * widen it by passing a different arg, because storage is already\n   * tenant-scoped.\n   */\n  readonly domain: string;\n  /**\n   * Optional instance name (shows up in descriptions / traces). Defaults\n   * to `memory:<domain>`.\n   */\n  readonly name?: string;\n  /**\n   * When set, persist observations to the local filesystem under this\n   * directory via `FSStorage`. When unset, falls back to the\n   * process-wide `agentMemoryRoot` (set via `setAgentMemoryRoot()`); when\n   * neither is set, falls back to `InMemoryStorage` (legacy behavior).\n   *\n   * The provider keyed by `(domain, resolvedStoragePath)` is cached\n   * process-wide so multiple scopes for the same tenant share the same\n   * `AFSMemory` instance — without that, two scopes pointing at the same\n   * directory would each get their own `FSStorage`, doubling on-disk\n   * fan-out and confusing the `consolidate`/`aging` background jobs that\n   * AFSMemory schedules at construction time.\n   */\n  readonly storagePath?: string;\n  /**\n   * Explicit storage backend. When provided, skips path-based storage\n   * selection (storagePath / agentMemoryRoot) and uses this directly.\n   * Used when the session AFS is the backing store (DID Space persistence).\n   * Providers created with explicit storage are NOT cached (each caller\n   * has a distinct backing AFS).\n   */\n  readonly storage?: MemoryStorage;\n  /**\n   * Test-only escape hatch: bypass the provider cache and always return a\n   * fresh instance. Used by the persistence test to prove storage is at\n   * the FS layer (not at the JS-object layer).\n   */\n  readonly _bypassCache?: boolean;\n  /**\n   * Explicit AFS root for index dispatch (indexEntry on remember/archive,\n   * queryIndex on recall). When set, overrides the process-global\n   * `agentIndexAfs` for THIS provider — used by CF per-caller memory, where\n   * the caller's session view (holding `/user/index`) is the correct index\n   * root, not a process global (which would be shared across concurrent\n   * callers). Node leaves this unset → keeps the global `/modules/index`.\n   */\n  readonly afsRoot?: { exec?: (...args: unknown[]) => unknown };\n  /**\n   * Override the default index query path (`/modules/index/.actions/query`).\n   * Set to `/user/index/.actions/query` for per-caller user-axis indexing.\n   */\n  readonly indexQueryPath?: string;\n  /**\n   * Override the default index write path (`/modules/index/.actions/index`).\n   * Set to `/user/index/.actions/index` for per-caller user-axis indexing.\n   */\n  readonly indexWritePath?: string;\n}\n\nlet agentIndexAfs: { exec?: (...args: any[]) => any } | undefined;\n\n/**\n * Daemon wire-up companion to `setAgentMemoryRoot`: attach a global AFS\n * reference that the per-scope memory provider can use to dispatch\n * `/modules/index/.actions/index` calls. Without this, `AFSMemory`'s\n * built-in `indexEntry` step (every observation goes through the\n * configured index) silently no-ops because the scope-local provider\n * has no `afsRoot` set (it's attached via Object.create overlay, not\n * `afs.mount()`).\n */\nexport function setAgentIndexAfs(afs: { exec?: (...args: any[]) => any } | undefined): void {\n  agentIndexAfs = afs;\n}\n\n/** Test-only — used by `afterEach` to drop the configured index AFS. */\nexport function clearAgentIndexAfsForTesting(): void {\n  agentIndexAfs = undefined;\n}\n\nlet agentMemoryRoot: string | undefined;\n\n/**\n * Daemon wire-up: configure a process-wide root directory for agent\n * memory. When set, `createMemoryProvider({ domain })` (no `storagePath`)\n * resolves storage to `<root>/<domain>/` via `FSStorage`. Production\n * daemons set this once at startup so cross-session recall works\n * without each call site threading the path.\n *\n * Tests should clear via `clearAgentMemoryRootForTesting()` between\n * cases to keep the cache clean.\n */\nexport function setAgentMemoryRoot(root: string | undefined): void {\n  agentMemoryRoot = root;\n}\n\n/** Test-only — used by `afterEach` to reset between cases. */\nexport function clearAgentMemoryRootForTesting(): void {\n  agentMemoryRoot = undefined;\n}\n\n/**\n * Symbol key used to attach per-session memory storage to the session AFS.\n * Propagates through `Object.create(sessionAfs)` prototype chains, so all\n * scope-local AFS objects derived from the session AFS inherit it without\n * explicit threading.\n *\n * Set via `attachSessionMemoryStorage()` in `buildCfSessionView` (CF) and\n * `buildSessionView` (Node) for authenticated callers. Anonymous callers\n * or sessions without a DID Space get no storage attached (undefined →\n * falls through to FSStorage / InMemoryStorage legacy path).\n */\nexport const SESSION_MEMORY_STORAGE_KEY: unique symbol = Symbol(\"sessionMemoryStorage\");\n\n/**\n * Attach an AFS-backed memory storage to the session AFS so that all\n * scope-local AFS objects derived from it (via `Object.create`) inherit\n * the storage via prototype-chain lookup.\n *\n * Call this in `buildCfSessionView` / `buildSessionView` for authenticated\n * callers: `attachSessionMemoryStorage(sessionView, new AFSBackedStorage(sessionView, \"/user/memory\"))`.\n */\nexport function attachSessionMemoryStorage(afs: AFSRoot, storage: MemoryStorage): void {\n  Object.defineProperty(afs, SESSION_MEMORY_STORAGE_KEY, {\n    value: storage,\n    writable: false,\n    configurable: false,\n    enumerable: false,\n  });\n}\n\n/**\n * Build memory storage for the given scope AFS using the session-attached\n * storage (set via `attachSessionMemoryStorage`). Returns undefined when no\n * storage is attached (anonymous callers, tests without wiring).\n */\nexport function buildMemoryStorageForAfs(afs: AFSRoot): MemoryStorage | undefined {\n  return (afs as unknown as Record<symbol, MemoryStorage | undefined>)[SESSION_MEMORY_STORAGE_KEY];\n}\n\n/** Per-session index dispatch config, attached in `buildCfSessionView`. */\nexport interface SessionIndexConfig {\n  /** AFS whose `indexQueryPath`/`indexWritePath` resolve to the caller's index. */\n  readonly afsRoot: { exec?: (...args: unknown[]) => unknown };\n  readonly indexQueryPath: string;\n  readonly indexWritePath: string;\n}\n\nconst SESSION_INDEX_KEY: unique symbol = Symbol(\"sessionIndexConfig\");\n\n/**\n * Point per-caller memory at a per-caller index. Companion to\n * `attachSessionMemoryStorage`: when set, `createMemoryProvider` dispatches\n * `indexEntry`/`queryIndex` to `config.afsRoot` at the given paths instead of\n * the process-global `agentIndexAfs` + `/modules/index`. Propagates through\n * `Object.create(sessionAfs)` prototype chains. CF calls this in\n * `buildCfSessionView`; Node leaves it unset (keeps the global index).\n */\nexport function attachSessionIndex(afs: AFSRoot, config: SessionIndexConfig): void {\n  Object.defineProperty(afs, SESSION_INDEX_KEY, {\n    value: config,\n    writable: false,\n    configurable: false,\n    enumerable: false,\n  });\n}\n\n/** Read the session-attached index config (via prototype chain), or undefined. */\nexport function readSessionIndex(afs: AFSRoot): SessionIndexConfig | undefined {\n  return (afs as unknown as Record<symbol, SessionIndexConfig | undefined>)[SESSION_INDEX_KEY];\n}\n\n/**\n * Spread-ready index opts for `createMemoryProvider`, derived from the session's\n * attached index config. Empty object when none is attached (Node / anonymous)\n * → the provider keeps the process-global index root + default `/modules/index`.\n */\nexport function buildMemoryIndexOptsForAfs(\n  afs: AFSRoot,\n): Pick<CreateMemoryProviderOptions, \"afsRoot\" | \"indexQueryPath\" | \"indexWritePath\"> {\n  const cfg = readSessionIndex(afs);\n  if (!cfg) return {};\n  return {\n    afsRoot: cfg.afsRoot,\n    indexQueryPath: cfg.indexQueryPath,\n    indexWritePath: cfg.indexWritePath,\n  };\n}\n\nconst providerCache = new Map<string, AFSMemory>();\n\n/** Test-only — used by `afterEach` to drop cached instances. */\nexport function clearMemoryProviderCacheForTesting(): void {\n  providerCache.clear();\n}\n\nfunction resolveStoragePath(opts: CreateMemoryProviderOptions): string | undefined {\n  if (typeof opts.storagePath === \"string\" && opts.storagePath.length > 0) {\n    return opts.storagePath;\n  }\n  if (typeof agentMemoryRoot === \"string\" && agentMemoryRoot.length > 0) {\n    // The memory provider already namespaces every path by domain\n    // (`/<domain>/observations/<id>`), and FSStorage just maps that\n    // through to a JSON file. Returning the root unmodified makes the\n    // on-disk layout `<root>/<domain>/observations/<id>.json` cleanly —\n    // joining `domain` here once would yield `<root>/<domain>/<domain>/...`,\n    // an extra level that breaks recall and consolidates jobs.\n    return agentMemoryRoot;\n  }\n  return undefined;\n}\n\n/**\n * Instantiate an `AFSMemory` suitable for a scope-local `/memory/` mount.\n *\n * Storage selection follows this order:\n *\n *   1. Explicit `opts.storage` — used as-is, not cached (caller controls lifecycle).\n *   2. Explicit `opts.storagePath` (typically test fixtures).\n *   3. Process-wide `agentMemoryRoot` set by the daemon — yields\n *      `<root>/<domain>` via `FSStorage`. Cross-session recall lives here.\n *   4. Default `InMemoryStorage` — used when no persistence is configured\n *      (legacy + most tests).\n *\n * Provider instances are cached by `(domain, resolvedPath)` for cases 2–4.\n * Case 1 (explicit storage) is not cached because the storage is per-session.\n */\nexport function createMemoryProvider(opts: CreateMemoryProviderOptions): AFSMemory {\n  validateDomain(opts.domain);\n\n  // Case 1: explicit storage — bypass cache, create directly. This is the CF\n  // per-caller path (storage = AFSBackedStorage over /user/memory), so honor an\n  // explicit per-caller index root + paths when provided (falls back to the\n  // process-global agentIndexAfs + default /modules/index when unset).\n  if (opts.storage) {\n    const provider = new AFSMemory({\n      name: opts.name ?? `memory:${opts.domain}`,\n      defaultDomain: opts.domain,\n      enforceDefaultDomain: true,\n      storage: opts.storage,\n      indexQueryPath: opts.indexQueryPath,\n      indexWritePath: opts.indexWritePath,\n    });\n    const indexAfs = opts.afsRoot ?? agentIndexAfs;\n    if (indexAfs) {\n      (provider as unknown as { afsRoot?: unknown }).afsRoot = indexAfs;\n    }\n    return provider;\n  }\n\n  const storagePath = resolveStoragePath(opts);\n  const cacheKey = `${opts.domain}::${storagePath ?? \":memory:\"}`;\n\n  if (!opts._bypassCache) {\n    const cached = providerCache.get(cacheKey);\n    if (cached) return cached;\n  }\n\n  const storage = storagePath ? new FSStorage(storagePath) : new InMemoryStorage();\n\n  const provider = new AFSMemory({\n    name: opts.name ?? `memory:${opts.domain}`,\n    defaultDomain: opts.domain,\n    enforceDefaultDomain: true,\n    storage,\n  });\n\n  // Hand the daemon-configured AFS reference to the provider so its\n  // `indexEntry` step (every remember/archive/boost/feedback) can\n  // dispatch `/modules/index/.actions/index`. AFSBaseProvider's\n  // `mount()` would normally set this on the provider during\n  // `afs.mount()`, but scope-local memory mounts go through a\n  // `Object.create(afs)` overlay (see `attachMemoryMount`) that\n  // skips the lifecycle hook — so we set it here directly.\n  if (agentIndexAfs) {\n    (provider as unknown as { afsRoot?: unknown }).afsRoot = agentIndexAfs;\n  }\n\n  if (!opts._bypassCache) providerCache.set(cacheKey, provider);\n  return provider;\n}\n\nfunction validateDomain(domain: string): void {\n  if (typeof domain !== \"string\" || domain.length === 0) {\n    throw new Error(`MEMORY_DOMAIN_INVALID: domain must be a non-empty string`);\n  }\n  if (!/^[a-zA-Z0-9_-]+$/.test(domain)) {\n    throw new Error(\n      `MEMORY_DOMAIN_INVALID: domain \"${domain}\" must match [a-zA-Z0-9_-]+ — segments, null bytes, and path traversal are rejected`,\n    );\n  }\n}\n\n/**\n * Overlay `/memory/*` onto `afs`, routing to `provider`. Delegates via\n * `Object.create(afs)` so siblings / other mounts on the same scope still\n * resolve through the parent's prototype chain.\n *\n * We forward to `provider.<op>(providerPath(path), …)` rather than to an\n * internal AFS + `afs.mount(provider, \"/memory\")` — the provider's\n * `AFSBaseProvider` already takes absolute-from-root paths, so one layer\n * of routing is enough. Skipping the extra AFS means we don't have to\n * await a `mount()` during scope projection (projectForChild is sync).\n *\n * Unlike the sibling `attachScratchMount` (which asserts valid scratch\n * segments at the overlay), we defer path-traversal / null-byte /\n * separator checks to `AFSMemory`'s own `AFSBaseProvider`. The provider\n * enforces the memory segment grammar at every action entry point, so a\n * parallel check here would be redundant. See\n * `providers/core/memory/src/provider.ts` and its action handlers.\n */\nexport function attachMemoryMount<T extends AFSRoot>(afs: T, provider: AFSMemory): T {\n  const child = Object.create(afs) as T;\n\n  Object.defineProperty(child, \"read\", {\n    value: async (path: string, options?: AFSReadOptions): Promise<AFSReadResult> => {\n      if (isMemoryPath(path)) return provider.read(providerPath(path), options);\n      return (afs.read as any)!.call(afs, path, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  Object.defineProperty(child, \"list\", {\n    value: async (path: string, options?: AFSListOptions): Promise<AFSListResult> => {\n      if (isMemoryPath(path)) return provider.list(providerPath(path), options);\n      return (afs.list as any)!.call(afs, path, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  Object.defineProperty(child, \"exec\", {\n    value: async (\n      path: string,\n      args: Record<string, any>,\n      options: AFSExecOptions,\n    ): Promise<AFSExecResult> => {\n      if (isMemoryPath(path)) return provider.exec(providerPath(path), args, options);\n      return (afs.exec as any)!.call(afs, path, args, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  Object.defineProperty(child, \"write\", {\n    value: async (\n      path: string,\n      payload: { content: string },\n      options?: AFSWriteOptions,\n    ): Promise<AFSWriteResult> => {\n      if (isMemoryPath(path)) return provider.write(providerPath(path), payload, options);\n      if (typeof afs.write !== \"function\") {\n        throw new Error(`MEMORY_MOUNT_NO_UNDERLYING_WRITE: afs.write not available for ${path}`);\n      }\n      return (afs.write as any)!.call(afs, path, payload, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  Object.defineProperty(child, \"stat\", {\n    value: async (path: string, options?: AFSStatOptions): Promise<AFSStatResult> => {\n      if (isMemoryPath(path)) return provider.stat(providerPath(path), options);\n      return (afs.stat as any)!.call(afs, path, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  Object.defineProperty(child, \"delete\", {\n    value: async (path: string, options?: { recursive?: boolean }) => {\n      if (isMemoryPath(path)) return provider.delete(providerPath(path), options);\n      if (typeof (afs as any).delete !== \"function\") return { success: false } as any;\n      return (afs as any).delete!.call(afs, path, options);\n    },\n    enumerable: false,\n    writable: false,\n    configurable: false,\n  });\n\n  return child;\n}\n\n/**\n * Resolve the domain used to instantiate a scope's AFSMemory.\n *\n * Precedence (design doc §3.3):\n *   1. Explicit `manifest.memory.domain`\n *   2. Parent scope's current memory domain (if already memory-backed)\n *   3. The child's member name, derived from memberPath (final non-empty segment)\n *\n * The resulting string is validated against the memory provider's segment\n * grammar; path traversal, separators, and empty strings all fail loudly.\n */\nexport function resolveMemoryDomain(opts: {\n  manifestMemory: unknown;\n  parentDomain?: string;\n  memberPath: string;\n}): string {\n  const fromManifest = extractManifestDomain(opts.manifestMemory);\n  if (fromManifest) {\n    validateDomain(fromManifest);\n    return fromManifest;\n  }\n  if (opts.parentDomain) {\n    validateDomain(opts.parentDomain);\n    return opts.parentDomain;\n  }\n  const memberName = deriveMemberId(opts.memberPath);\n  validateDomain(memberName);\n  return memberName;\n}\n\nexport function extractManifestDomain(manifestMemory: unknown): string | undefined {\n  if (typeof manifestMemory !== \"object\" || manifestMemory === null) return undefined;\n  const domain = (manifestMemory as { domain?: unknown }).domain;\n  return typeof domain === \"string\" && domain.length > 0 ? domain : undefined;\n}\n\n/**\n * Unified surface helper — mount /memory/ when a manifest declares memory.\n *\n * Consolidates the 3-step pattern (resolveMemoryDomain → createMemoryProvider →\n * attachMemoryMount) that previously appeared independently in each surface\n * handler (chat: agent-handler.ts, terminal: agent-runner-registry.ts).\n * All surfaces call this instead of replicating the logic.\n *\n * Safe to call unconditionally:\n *  - skips when manifestMemory is falsy\n *  - skips when the caller's AFS already carries a memory domain in scope\n *    (inherits parent mount rather than layering a fresh provider)\n */\nexport function mountManifestMemory<T extends AFSRoot>(\n  afs: T,\n  manifestMemory: unknown,\n  memberPath: string,\n): T {\n  if (!manifestMemory || (typeof manifestMemory !== \"object\" && manifestMemory !== true))\n    return afs;\n  if ((afs as { scope?: { memoryDomain?: string } }).scope?.memoryDomain) return afs;\n  const domain = resolveMemoryDomain({ manifestMemory, memberPath });\n  // Prefer session-attached AFS-backed storage (DID Space /user/memory) when\n  // available (authenticated callers). Falls back to FSStorage / InMemoryStorage.\n  const storage = buildMemoryStorageForAfs(afs as AFSRoot);\n  const provider = createMemoryProvider({\n    domain,\n    storage,\n    ...buildMemoryIndexOptsForAfs(afs as AFSRoot),\n  });\n  return attachMemoryMount(afs, provider);\n}\n\nfunction deriveMemberId(memberPath: string): string {\n  const trimmed = memberPath.replace(/\\/+$/, \"\");\n  const tail = trimmed.slice(trimmed.lastIndexOf(\"/\") + 1);\n  // Memory segment regex rejects \".\", so collapse leading/trailing dots and\n  // turn unsafe separators into hyphens rather than fabricating opaque ids.\n  const cleaned = tail.replace(/[^a-zA-Z0-9_-]/g, \"-\");\n  return cleaned.length > 0 ? cleaned : \"scope\";\n}\n"],"mappings":"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"}