diff --git a/python/packages/core/AGENTS.md b/python/packages/core/AGENTS.md index a552412fd4c..46da245730b 100644 --- a/python/packages/core/AGENTS.md +++ b/python/packages/core/AGENTS.md @@ -337,7 +337,7 @@ The vector store API is experimental under the shared `VECTOR_STORES` feature ID - **`FileMemoryProvider`** - `ContextProvider` that gives an agent a session-scoped, file-based memory backed by the same `AgentFileStore` abstraction. Adds tools (`file_memory_write`, `file_memory_read`, `file_memory_delete`, `file_memory_ls`, `file_memory_grep`, `file_memory_replace`, `file_memory_replace_lines`) plus default usage instructions. Port of the .NET `FileMemoryProvider`. - **Scoping** - Memories are isolated per session by default: each session writes under a working folder derived from `context.session_id`. Pass an explicit `scope` (e.g. a user id) to group memories across sessions, mirroring `FoundryMemoryProvider`'s `scope` arg. The scope (or session id) is an **opaque namespace key, not a path**: it is mapped to exactly one folder via the shared `agent_framework._filesystem._storage_key_segment` derivation, which is **injective** (except for a collision-resistant digest fallback past a length cap) — two byte-distinct values do not share a working folder, so a caller authorized for one identifier cannot reach another's memories. A multi-segment value such as `"tenants/alice"` therefore becomes a single encoded folder rather than a nested directory. The provider **fails closed** (`ValueError`) when neither a `scope` nor a `session_id` is available, because an empty working folder would be the shared store root. Applications should still canonicalize and authorize externally supplied identifiers themselves; the storage mapping is the storage-layer guarantee, not a substitute for that check. -- **Descriptions & index** - `file_memory_write` accepts an optional `description`, stored in a companion `_description.md` sidecar. After each write/delete the provider rebuilds a capped (50-entry) `memories.md` index, and `before_run` injects that index as a `user` context message so the model knows what memories exist. Sidecars and the index are internal files hidden from `file_memory_ls`/`file_memory_grep` and rejected as write targets. +- **Descriptions & index** - `file_memory_write` accepts an optional `description`, stored in a companion sidecar named after the *whole* memory file name (`notes.md` → `notes.md._description.md`), so distinct files never share a description. Names whose sidecar would exceed the 255-byte filesystem name budget — and names in the reserved `~memory-desc-` digest namespace (matched after NFKC + casefold) — use a SHA-256 digest sidecar instead, derived from the backend's canonical stored name so a case-folding store cannot scatter one description across spellings. Sidecars written by the pre-isolation format (`_description.md`) are still read as a fallback, but only when no other existing memory file shares the stem (stems compared with `casefold`); clearing or deleting a file clears its unambiguous legacy sidecar too. After each write/delete the provider rebuilds a capped (50-entry) `memories.md` index, and `before_run` injects that index as a `user` context message so the model knows what memories exist. Sidecars and the index are internal files hidden from `file_memory_ls`/`file_memory_grep` and rejected as write targets. - **`DEFAULT_FILE_MEMORY_SOURCE_ID`** / **`DEFAULT_FILE_MEMORY_INSTRUCTIONS`** - Public defaults for the provider's source id and instruction banner. - **Harness wiring** - `create_harness_agent` includes the `FileMemoryProvider` by default; the `FileAccessProvider` is opt-in and added only when a `file_access_store` is supplied (no implicit `{cwd}/working` store is created). Disable file memory via `disable_file_memory`; override its backing store via `file_memory_store`. When no file-memory store is supplied, the default is `FileSystemAgentFileStore` rooted at `{cwd}/agent-file-memory`. `create_harness_agent` also wires in `MessageInjectionMiddleware` by default (mirroring the .NET harness's `UseMessageInjection`); it is always on with no opt-out because it is a no-op when no messages are queued for the session. - **Experimental-feature gating** - `create_harness_agent` itself is released (no longer `@experimental`), but a few features it can wire in remain experimental or pre-release: **background agents** (`background_agents`), **file access** (`file_access_store`), **looping** (`loop_should_continue`), and the **shell tooling** (`shell_executor`, from the pre-release `agent-framework-tools` package). Enabling any of them emits a single `ExperimentalWarning` (naming the responsible parameter). The three experimental harness providers share one `HARNESS` dedup key so the downstream experimental provider does not warn a second time; the shell tooling uses a separate dedup key (it is not a `HARNESS`-decorated feature). diff --git a/python/packages/core/agent_framework/_harness/_file_access.py b/python/packages/core/agent_framework/_harness/_file_access.py index fb75ac1d78a..76fa62654f2 100644 --- a/python/packages/core/agent_framework/_harness/_file_access.py +++ b/python/packages/core/agent_framework/_harness/_file_access.py @@ -1151,10 +1151,19 @@ async def write(self, path: str, content: str, *, overwrite: bool = True) -> Non if not overwrite and key in self._files: raise FileExistsError(f"File already exists: {path!r}") is_new_file = key not in self._files - self._files[key] = (display, content) if is_new_file: + self._files[key] = (display, content) for ancestor in ancestors: self._dir_counts[ancestor] = self._dir_counts.get(ancestor, 0) + 1 + else: + # Overwriting through a differently-cased path updates the same + # file without renaming it — that is what a case-insensitive + # filesystem does — so keep the display name recorded when the + # file was created. Callers that derive stable identities from + # the stored name (such as FileMemoryProvider's digest + # sidecars) would otherwise see it flip with each spelling. + previous_display = self._files[key][0] + self._files[key] = (previous_display, content) async def read(self, path: str) -> str | None: """Return the file content, or ``None`` if the file does not exist.""" diff --git a/python/packages/core/agent_framework/_harness/_file_memory.py b/python/packages/core/agent_framework/_harness/_file_memory.py index b64a112376b..14fe9807c08 100644 --- a/python/packages/core/agent_framework/_harness/_file_memory.py +++ b/python/packages/core/agent_framework/_harness/_file_memory.py @@ -4,10 +4,11 @@ :class:`FileMemoryProvider` gives an agent a session-scoped, file-based memory system. Each memory is stored as an individual file with a meaningful name, and -large files can carry a companion description file (suffixed with -``_description.md``) that provides a short summary used for discovery. A -``memories.md`` index file is maintained automatically and injected into the -agent's context so the model knows what memories already exist. +large files can carry a companion description file — named after the whole +memory file name (``notes.md`` becomes ``notes.md._description.md``) — that +provides a short summary used for discovery. A ``memories.md`` index file is +maintained automatically and injected into the agent's context so the model +knows what memories already exist. File access is mediated through the :class:`~agent_framework.AgentFileStore` abstraction (shared with :class:`~agent_framework.FileAccessProvider`), so the @@ -42,7 +43,10 @@ from __future__ import annotations +import hashlib import logging +import unicodedata +from collections.abc import Iterable from typing import Annotated, Any from pydantic import BaseModel, Field @@ -84,19 +88,92 @@ _DESCRIPTION_SUFFIX = "_description.md" +# New-format sidecars are ``._description.md``. The +# separating dot is what isolates the format: a *legacy* sidecar is +# ``_description.md`` where ```` is the memory file name with its +# last extension removed, and a stem never ends in ``.`` (removing an extension +# always cuts at a dot). So ``._description.md`` can never equal any +# legacy sidecar name, which makes the two namespaces disjoint by construction: +# an old sidecar can never be read as another memory's description. +_NEW_DESCRIPTION_SUFFIX = f".{_DESCRIPTION_SUFFIX}" _MEMORY_INDEX_FILE_NAME = "memories.md" _MAX_INDEX_ENTRIES = 50 -# Prefix for scopes that are not usable verbatim as a folder name. Kept distinct -# from the other harness prefixes so the same value under a different component -# never lands in the same directory. +# Common per-component filesystem name budget (bytes on ext4, APFS and NTFS). +# A sidecar must fit inside it so every valid memory file name keeps a writable +# companion; names too long to carry the suffix verbatim use a digest instead. +_MAX_DESCRIPTION_FILE_NAME_BYTES = 255 +# Prefix for scope values that are not usable verbatim as a folder name. Kept +# distinct from the other harness prefixes so the same value under a different +# component never lands in the same directory. _ENCODED_SCOPE_PREFIX = "~scope-" +# Namespace for description sidecars that cannot be spelled verbatim: memory +# names whose sidecar would exceed the name budget, plus names that could +# otherwise forge a digest sidecar. Digest names keep the description suffix so +# they stay internal and hidden from the agent. +_DIGEST_DESCRIPTION_PREFIX = "~memory-desc-" + + +def _is_reserved_digest_name(file_name: str) -> bool: + """Return whether ``file_name`` belongs to the reserved digest namespace. + + The check runs on an NFKC-normalized, case-folded copy of the name so that + every spelling a case-folding or Unicode-folding filesystem treats as the + prefix is caught: ASCII case variants (``~MEMORY-DESC-``), Unicode case + pairs (long s folding to ``s``) and NFKC compatibility forms (a fullwidth + spelling of the prefix). Matching only ASCII lower-casing would + let a short name alias a long name's digest sidecar on default APFS or + NTFS, where writing the short name would overwrite the long name's + description and deleting it would remove that description. + """ + normalized = unicodedata.normalize("NFKC", file_name).casefold() + return normalized.startswith(_DIGEST_DESCRIPTION_PREFIX) + + +def _requires_digest_sidecar(file_name: str) -> bool: + """Return whether ``file_name`` must use the digest sidecar namespace. + + This is true when the verbatim sidecar would exceed the filesystem name + budget, and when the name itself sits in the reserved digest namespace — + otherwise a short name could be spelled so that its verbatim sidecar is + exactly another name's digest sidecar, and the two would collide without + any hash collision. + """ + if _is_reserved_digest_name(file_name): + return True + return len(f"{file_name}{_NEW_DESCRIPTION_SUFFIX}".encode("utf-8")) > _MAX_DESCRIPTION_FILE_NAME_BYTES def _description_file_name(file_name: str) -> str: """Return the companion description file name for ``file_name``. - The suffix replaces the original extension when present (so ``notes.md`` - becomes ``notes_description.md``); otherwise it is appended. + The suffix is appended to the *whole* memory file name after a separating + dot, so ``notes.md`` becomes ``notes.md._description.md`` while ``notes`` + becomes ``notes._description.md``. Keeping the extension in the derivation + makes the mapping injective — distinct memory files always get distinct + sidecars — and the dot keeps the new names disjoint from every legacy + ``_description.md`` name (see :data:`_NEW_DESCRIPTION_SUFFIX`). + + Names whose verbatim sidecar would not fit within + :data:`_MAX_DESCRIPTION_FILE_NAME_BYTES`, and names in the reserved digest + namespace, are derived from a SHA-256 digest instead. The caller is + responsible for passing the backend's canonical stored file name, because + on a case-folding store the digest must not depend on which spelling the + caller used. + """ + if _requires_digest_sidecar(file_name): + digest = hashlib.sha256(file_name.encode("utf-8")).hexdigest() + return f"{_DIGEST_DESCRIPTION_PREFIX}{digest}{_NEW_DESCRIPTION_SUFFIX}" + return f"{file_name}{_NEW_DESCRIPTION_SUFFIX}" + + +def _legacy_description_file_name(file_name: str) -> str: + """Return the pre-isolation description file name for ``file_name``. + + Sidecars written before format isolation replaced the original extension + when one was present (``notes.md`` became ``notes_description.md``) and + appended the suffix otherwise. This name is only ever read as a fallback, + and only when :func:`_legacy_sidecar_is_unambiguous` says it can belong to + exactly one existing memory file. """ dot_index = file_name.rfind(".") if dot_index > 0: @@ -104,6 +181,60 @@ def _description_file_name(file_name: str) -> str: return f"{file_name}{_DESCRIPTION_SUFFIX}" +def _legacy_sidecar_is_unambiguous(file_name: str, existing_file_names: Iterable[str]) -> bool: + """Return whether the legacy sidecar of ``file_name`` can only belong to it. + + Two memory files share a legacy sidecar exactly when they share a stem, so + the sidecar is unambiguous when no other existing memory file maps to the + same legacy name. Reading it anyway would hand one memory another's + description; when it is ambiguous the description is left unread rather + than guessed at. + + Stems are compared with :meth:`str.casefold` because a case-folding store + (NTFS, APFS) treats ``Notes.md`` and ``notes.md`` as the same file and folds + their legacy sidecars together too; folding in the conservative direction + only ever suppresses a risky read, it never invents one. + """ + dot_index = file_name.rfind(".") + folded_file_name = file_name.casefold() + stem = (file_name[:dot_index] if dot_index > 0 else file_name).casefold() + for other in existing_file_names: + if other.casefold() == folded_file_name: + continue + other_dot_index = other.rfind(".") + other_stem = (other[:other_dot_index] if other_dot_index > 0 else other).casefold() + if other_stem == stem: + return False + return True + + +async def _canonical_file_name(store: AgentFileStore, working_folder: str, file_name: str) -> str: + """Return the name under which ``file_name`` is actually stored. + + Only consulted before hashing a digest sidecar: on a case-folding store the + same memory can be addressed under several spellings, and hashing each + spelling would scatter one description across several sidecars. A + case-sensitive store keeps distinct spellings distinct because + :meth:`~agent_framework.AgentFileStore.file_exists` answers for the exact + name only, so a differently-cased name that does not exist yet keeps its own + spelling instead of being collapsed onto its neighbour. + + The alias search folds with :meth:`str.lower`, mirroring the key function + :class:`InMemoryAgentFileStore` itself uses, so an entry is only adopted + when the store would treat it as the very same file. + """ + entries = await store.list_children(working_folder) + if any(entry.name == file_name for entry in entries): + return file_name + if not await store.file_exists(_combine_paths(working_folder, file_name)): + return file_name + lowered = file_name.lower() + for entry in entries: + if entry.name.lower() == lowered: + return entry.name + return file_name + + def _is_internal_file(file_name: str) -> bool: """Return whether ``file_name`` is an internal file hidden from the agent. @@ -323,6 +454,41 @@ def _resolve_working_folder(self, context: SessionContext) -> str: ) return _storage_key_segment(raw_scope, encoded_prefix=_ENCODED_SCOPE_PREFIX) + async def _memory_file_names(self, working_folder: str) -> set[str]: + """Return the agent-visible memory file names in ``working_folder``.""" + entries = await self.store.list_children(working_folder) + return { + entry.name for entry in entries if entry.type == FileStoreEntry.FILE and not _is_internal_file(entry.name) + } + + async def _sidecar_path(self, working_folder: str, file_name: str) -> str: + """Return the store path of the new-format description sidecar for ``file_name``. + + Digest names are derived from the backend's canonical stored file name + so a case-folding store cannot scatter one description across several + sidecars; verbatim names need no resolution because the store folds them + on its own. + """ + if _requires_digest_sidecar(file_name): + file_name = await _canonical_file_name(self.store, working_folder, file_name) + return _combine_paths(working_folder, _description_file_name(file_name)) + + def _legacy_sidecar_path(self, working_folder: str, file_name: str, existing: set[str]) -> str | None: + """Return the legacy sidecar path, or ``None`` when it is not unambiguously ``file_name``'s.""" + if not _legacy_sidecar_is_unambiguous(file_name, existing): + return None + return _combine_paths(working_folder, _legacy_description_file_name(file_name)) + + async def _read_description(self, working_folder: str, file_name: str, existing: set[str]) -> str | None: + """Return the description for ``file_name``, falling back to an unambiguous legacy sidecar.""" + description = await self.store.read(await self._sidecar_path(working_folder, file_name)) + if description is not None: + return description + legacy_path = self._legacy_sidecar_path(working_folder, file_name, existing) + if legacy_path is None: + return None + return await self.store.read(legacy_path) + async def _rebuild_index(self, working_folder: str) -> None: """Rebuild the ``memories.md`` index for ``working_folder``. @@ -332,10 +498,11 @@ async def _rebuild_index(self, working_folder: str) -> None: entries = await self.store.list_children(working_folder) file_names = [entry.name for entry in entries if entry.type == FileStoreEntry.FILE] sorted_files = sorted((name for name in file_names if not _is_internal_file(name)), key=str.lower) + available = set(sorted_files) lines = ["# Memory Index", ""] for file_name in sorted_files[:_MAX_INDEX_ENTRIES]: - description = await self.store.read(_combine_paths(working_folder, _description_file_name(file_name))) + description = await self._read_description(working_folder, file_name, available) if description and description.strip(): lines.append(f"- **{file_name}**: {description.strip()}") else: @@ -377,18 +544,26 @@ async def file_memory_write(file_name: str, content: str, description: str | Non ) path = _combine_paths(working_folder, normalized) - desc_path = _combine_paths(working_folder, _description_file_name(normalized)) # Every mutating tool locks the whole working folder, not just the file, because each # write and delete rebuilds the folder's memories.md index. The lock is shared by all # providers on the store, including file-access tools editing a file in this folder, so # they cannot interleave edits or index rebuilds. async with _store_write_lock(self.store, working_folder): try: + desc_path = await self._sidecar_path(working_folder, normalized) await self.store.write(path, content) if description and description.strip(): await self.store.write(desc_path, description) else: await self.store.delete(desc_path) + # A legacy sidecar left behind by the pre-isolation format would otherwise + # be read back as this file's description, so clearing the description + # clears it too — but only when it unambiguously belongs to this file. + legacy_path = self._legacy_sidecar_path( + working_folder, normalized, await self._memory_file_names(working_folder) + ) + if legacy_path is not None: + await self.store.delete(legacy_path) await self._rebuild_index(working_folder) except ValueError as exc: return f"Could not write file '{file_name}': {exc}" @@ -426,11 +601,19 @@ async def file_memory_delete(file_name: str) -> str: return f"File '{file_name}' not found." path = _combine_paths(working_folder, normalized) - desc_path = _combine_paths(working_folder, _description_file_name(normalized)) async with _store_write_lock(self.store, working_folder): try: + # Resolve the sidecar before the file disappears: a digest name is derived + # from the backend's canonical stored name, which is only discoverable while + # the file is still listed. + desc_path = await self._sidecar_path(working_folder, normalized) deleted = await self.store.delete(path) await self.store.delete(desc_path) + legacy_path = self._legacy_sidecar_path( + working_folder, normalized, await self._memory_file_names(working_folder) + ) + if legacy_path is not None: + await self.store.delete(legacy_path) await self._rebuild_index(working_folder) except ValueError as exc: return f"Could not delete file '{file_name}': {exc}" @@ -443,22 +626,18 @@ async def file_memory_ls(glob_pattern: str | None = None) -> list[dict[str, Any] """List all memory files with their descriptions (if available). Optionally filter file names with a glob_pattern (e.g. "*.md"). Internal files (description sidecars and the memory index) are not shown. Each entry is {"name": , "type": "file", "description": }.""" # ruff:ignore[line-too-long] try: entries = await self.store.list_children(working_folder) + file_names = [entry.name for entry in entries if entry.type == FileStoreEntry.FILE] + available = {name for name in file_names if not _is_internal_file(name)} + results: list[dict[str, Any]] = [] + for file_name in file_names: + if _is_internal_file(file_name): + continue + if not _matches_glob(file_name, glob_pattern): + continue + description = await self._read_description(working_folder, file_name, available) + results.append({"name": file_name, "type": "file", "description": description}) except OSError as exc: return f"Could not list memory files: {exc.strerror or exc}" - - file_names = [entry.name for entry in entries if entry.type == FileStoreEntry.FILE] - available = set(file_names) - results: list[dict[str, Any]] = [] - for file_name in file_names: - if _is_internal_file(file_name): - continue - if not _matches_glob(file_name, glob_pattern): - continue - description: str | None = None - desc_file_name = _description_file_name(file_name) - if desc_file_name in available: - description = await self.store.read(_combine_paths(working_folder, desc_file_name)) - results.append({"name": file_name, "type": "file", "description": description}) return results @tool(name="file_memory_replace", schema=_ReplaceInput, approval_mode="never_require") diff --git a/python/packages/core/tests/core/test_harness_file_memory.py b/python/packages/core/tests/core/test_harness_file_memory.py index 5d8f7394be2..d080b52d862 100644 --- a/python/packages/core/tests/core/test_harness_file_memory.py +++ b/python/packages/core/tests/core/test_harness_file_memory.py @@ -18,6 +18,7 @@ InMemoryAgentFileStore, ) from agent_framework._harness._file_memory import ( + _DIGEST_DESCRIPTION_PREFIX, _MAX_INDEX_ENTRIES, _MEMORY_INDEX_FILE_NAME, DEFAULT_FILE_MEMORY_INSTRUCTIONS, @@ -25,6 +26,8 @@ _combine_paths, _description_file_name, _is_internal_file, + _is_reserved_digest_name, + _legacy_description_file_name, ) from agent_framework._sessions import SessionContext @@ -55,13 +58,71 @@ async def _prepare( return context, tools -def test_description_file_name_replaces_extension() -> None: - """The description sidecar replaces a known extension and appends otherwise.""" - assert _description_file_name("notes.md") == "notes_description.md" - assert _description_file_name("data.json") == "data_description.md" - assert _description_file_name("noext") == "noext_description.md" - # Leading-dot files have no stem, so the suffix is appended. - assert _description_file_name(".hidden") == ".hidden_description.md" +def test_description_file_name_appends_to_the_whole_name() -> None: + """The description sidecar keeps the whole memory file name, so distinct files stay distinct.""" + assert _description_file_name("notes.md") == "notes.md._description.md" + assert _description_file_name("data.json") == "data.json._description.md" + assert _description_file_name("noext") == "noext._description.md" + # Leading-dot files have no stem, so the suffix is appended to the whole name. + assert _description_file_name(".hidden") == ".hidden._description.md" + # The original defect: names differing only by extension must not share a sidecar. + assert _description_file_name("notes") == "notes._description.md" + assert _description_file_name("notes.md") != _description_file_name("notes") + assert _description_file_name("notes.md") != _description_file_name("notes.md.md") + + +def test_description_file_name_is_disjoint_from_legacy_names() -> None: + """No new-format sidecar name can equal a legacy sidecar name (format isolation). + + A legacy sidecar is ``_description.md`` and a stem never ends in a dot, + so appending ``._description.md`` to a memory file name can never reproduce + one. This is what stops an old sidecar from being read as another memory's + description during the format transition. + """ + for memory_name in ("notes.md", "notes", "notes.md.md", ".hidden", "a.b.c"): + new_name = _description_file_name(memory_name) + assert new_name.endswith("._description.md") + for legacy_of in ("notes.md", "notes", "notes.md.md", ".hidden", "a.b.c", "x.y"): + assert new_name != _legacy_description_file_name(legacy_of) + + +def test_description_file_name_stays_within_filesystem_name_limits() -> None: + """Sidecars over the 255-byte name budget fall back to a digest that fits inside it.""" + # 238 + ".md" = 241 bytes; the suffix adds 16 -> 257 > 255, so digest. + long_name = "a" * 238 + ".md" + sidecar = _description_file_name(long_name) + assert sidecar.startswith(_DIGEST_DESCRIPTION_PREFIX) + assert sidecar.endswith("._description.md") + assert len(sidecar.encode("utf-8")) <= 255 + + # At the budget the verbatim name is kept, so ordinary names stay readable. + fitting = "b" * (255 - len("._description.md")) + assert _description_file_name(fitting) == f"{fitting}._description.md" + + # Distinct long names still get distinct sidecars (injective). + assert _description_file_name(long_name) != _description_file_name("a" * 237 + "c.md") + # Deterministic: the same name always resolves to the same sidecar. + assert _description_file_name(long_name) == _description_file_name(long_name) + + +def test_reserved_prefix_routes_to_digest_case_and_unicode_safely() -> None: + """Every spelling a folding filesystem treats as ``~memory-desc-`` must take the digest branch.""" + # ASCII case variants. + assert _is_reserved_digest_name("~memory-desc-forged") + assert _is_reserved_digest_name("~MEMORY-DESC-FORGED") + assert _is_reserved_digest_name("~MeMoRy-DeSc-Forged") + # Fullwidth (NFKC) spelling of the whole prefix. + assert _is_reserved_digest_name("~memory-desc-forged") + # Long s U+017F casefolds to ASCII 's'. + assert _is_reserved_digest_name("~memory-deſc-forged") + # A name merely containing the prefix is not reserved. + assert not _is_reserved_digest_name("notes.md") + assert not _is_reserved_digest_name("prefix~memory-desc-x.md") + + # Reserved names take the digest branch even though they are short. + forged = _description_file_name("~memory-desc-forged") + assert forged.startswith(_DIGEST_DESCRIPTION_PREFIX) + assert forged != "~memory-desc-forged._description.md" def test_is_internal_file_detects_sidecars_and_index() -> None: @@ -152,7 +213,7 @@ async def test_description_sidecar_is_written_and_listed() -> None: ) assert "with description" in _text(result) - sidecar = await store.read(_combine_paths("user-1", "arch_description.md")) + sidecar = await store.read(_combine_paths("user-1", "arch.md._description.md")) assert sidecar == "system architecture" listed = json.loads(_text(await list_files.invoke())) @@ -160,7 +221,7 @@ async def test_description_sidecar_is_written_and_listed() -> None: # Re-saving without a description removes the sidecar. await save.invoke(arguments={"file_name": "arch.md", "content": "big content"}) - assert await store.read(_combine_paths("user-1", "arch_description.md")) is None + assert await store.read(_combine_paths("user-1", "arch.md._description.md")) is None listed_again = json.loads(_text(await list_files.invoke())) assert listed_again == [{"name": "arch.md", "type": "file", "description": None}] @@ -172,10 +233,10 @@ async def test_delete_removes_sidecar() -> None: _, tools = await _prepare(provider) await tools["file_memory_write"].invoke(arguments={"file_name": "arch.md", "content": "x", "description": "desc"}) - assert await store.read(_combine_paths("user-1", "arch_description.md")) == "desc" + assert await store.read(_combine_paths("user-1", "arch.md._description.md")) == "desc" await tools["file_memory_delete"].invoke(arguments={"file_name": "arch.md"}) - assert await store.read(_combine_paths("user-1", "arch_description.md")) is None + assert await store.read(_combine_paths("user-1", "arch.md._description.md")) is None async def test_index_is_rebuilt_and_injected_on_next_run() -> None: @@ -743,3 +804,152 @@ async def test_file_memory_replace_lines_honours_expected_line() -> None: # endregion + + +# region description sidecar isolation (#9871) + + +async def test_extension_aliases_have_independent_lifecycles() -> None: + """The #9871 repro: ``notes.md`` and ``notes`` must not share a sidecar. + + One file's description must never overwrite the other's, rewriting one + without a description must not destroy the other's, and deleting one must + not delete the other. + """ + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + save = tools["file_memory_write"] + delete = tools["file_memory_delete"] + read = tools["file_memory_read"] + list_files = tools["file_memory_ls"] + + await save.invoke(arguments={"file_name": "notes.md", "content": "a", "description": "architecture"}) + await save.invoke(arguments={"file_name": "notes", "content": "b", "description": "scratch"}) + + # Each file owns its own sidecar. + assert await store.read(_combine_paths("user-1", "notes.md._description.md")) == "architecture" + assert await store.read(_combine_paths("user-1", "notes._description.md")) == "scratch" + listed = {e["name"]: e["description"] for e in json.loads(_text(await list_files.invoke()))} + assert listed == {"notes.md": "architecture", "notes": "scratch"} + + # Rewriting ``notes`` without a description must not destroy ``notes.md``'s. + await save.invoke(arguments={"file_name": "notes", "content": "b2"}) + assert await store.read(_combine_paths("user-1", "notes.md._description.md")) == "architecture" + assert await store.read(_combine_paths("user-1", "notes._description.md")) is None + + # Deleting ``notes`` must not delete ``notes.md`` or its description. + await delete.invoke(arguments={"file_name": "notes"}) + assert _text(await read.invoke(arguments={"file_name": "notes.md"})) == "a" + listed = {e["name"]: e["description"] for e in json.loads(_text(await list_files.invoke()))} + assert listed == {"notes.md": "architecture"} + + +async def test_extension_aliases_do_not_share_a_legacy_sidecar() -> None: + """``notes`` and ``notes.md`` both stem to ``notes_description.md``; neither may claim it.""" + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + # Both files exist up front alongside the pre-isolation sidecar they share, + # so the sidecar is ambiguous for every subsequent operation. + await store.write(_combine_paths("user-1", "notes.md"), "a") + await store.write(_combine_paths("user-1", "notes"), "b") + await store.write(_combine_paths("user-1", "notes_description.md"), "legacy") + + listed = {e["name"]: e["description"] for e in json.loads(_text(await tools["file_memory_ls"].invoke()))} + assert listed == {"notes.md": None, "notes": None} + + # Rewriting one of them without a description must not destroy the shared + # sidecar: it is ambiguous, so it is neither read nor deleted. + await tools["file_memory_write"].invoke(arguments={"file_name": "notes.md", "content": "a2"}) + assert await store.read(_combine_paths("user-1", "notes_description.md")) == "legacy" + + +async def test_unambiguous_legacy_sidecar_is_still_read() -> None: + """A legacy sidecar that can only belong to one file remains visible after the format change.""" + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + await store.write(_combine_paths("user-1", "arch.md"), "content") + await store.write(_combine_paths("user-1", "arch_description.md"), "legacy summary") + + listed = json.loads(_text(await tools["file_memory_ls"].invoke())) + assert listed == [{"name": "arch.md", "type": "file", "description": "legacy summary"}] + + +async def test_clearing_description_clears_unambiguous_legacy_sidecar() -> None: + """Rewriting without a description clears the legacy sidecar too, so it cannot resurface.""" + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + await store.write(_combine_paths("user-1", "arch.md"), "content") + await store.write(_combine_paths("user-1", "arch_description.md"), "legacy summary") + + await tools["file_memory_write"].invoke(arguments={"file_name": "arch.md", "content": "content2"}) + assert await store.read(_combine_paths("user-1", "arch_description.md")) is None + listed = json.loads(_text(await tools["file_memory_ls"].invoke())) + assert listed == [{"name": "arch.md", "type": "file", "description": None}] + + +async def test_digest_sidecar_follows_the_stored_name_across_case_aliases() -> None: + """A digest sidecar derives from the backend's canonical name, not the caller's spelling. + + On a case-folding store the same memory can be addressed several ways; + hashing each spelling would scatter one description across sidecars, and a + later read under a different spelling would find nothing. + """ + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + save = tools["file_memory_write"] + list_files = tools["file_memory_ls"] + delete = tools["file_memory_delete"] + + # Long enough that the verbatim sidecar exceeds the 255-byte budget. + canonical = "N" + "a" * 240 + ".md" + alias = canonical.lower() + + await save.invoke(arguments={"file_name": canonical, "content": "x", "description": "first"}) + entries = [e.name for e in await store.list_children("user-1")] + sidecars = [name for name in entries if name.startswith(_DIGEST_DESCRIPTION_PREFIX)] + assert len(sidecars) == 1 + + # Editing through the case alias must hit the same sidecar, not a second one. + await save.invoke(arguments={"file_name": alias, "content": "y", "description": "second"}) + entries = [e.name for e in await store.list_children("user-1")] + assert [name for name in entries if name.startswith(_DIGEST_DESCRIPTION_PREFIX)] == sidecars + + listed = json.loads(_text(await list_files.invoke())) + assert len(listed) == 1 + assert listed[0]["description"] == "second" + assert await store.read(_combine_paths("user-1", sidecars[0])) == "second" + + # Deleting through the alias removes the file and its single sidecar. + await delete.invoke(arguments={"file_name": alias}) + remaining = [e.name for e in await store.list_children("user-1") if not e.name.startswith("~")] + assert remaining == [_MEMORY_INDEX_FILE_NAME] + + +async def test_long_name_round_trips_through_write_list_delete() -> None: + """A name over the byte budget still writes, lists with its description, and deletes cleanly.""" + store = InMemoryAgentFileStore() + provider = FileMemoryProvider(store=store, scope="user-1") + _, tools = await _prepare(provider) + + long_name = "c" * 240 + ".md" + await tools["file_memory_write"].invoke( + arguments={"file_name": long_name, "content": "body", "description": "big file"} + ) + + listed = json.loads(_text(await tools["file_memory_ls"].invoke())) + assert listed == [{"name": long_name, "type": "file", "description": "big file"}] + + await tools["file_memory_delete"].invoke(arguments={"file_name": long_name}) + listed = json.loads(_text(await tools["file_memory_ls"].invoke())) + assert listed == [] + # No orphaned sidecar is left behind. + leftovers = [e.name for e in await store.list_children("user-1") if e.name != _MEMORY_INDEX_FILE_NAME] + assert leftovers == [] + + +# endregion