[BREAKING] Python: Move path normalization to common shared code

[westey (westey-m)]

Motivation & Context

Improve consistency

Description & Review Guide

Move path normalization to common shared code

Related Issue

Fixes #

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

The derivation still permits case-insensitive collisions and silently relocates several existing persisted layouts.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Centralizes filesystem-safe storage-key derivation to improve isolation consistency across Python persistence providers.

Changes:

• Adds shared storage-key encoding and safety helpers.
• Migrates session, todo, memory, and file-memory path derivation.
• Adds collision, Unicode, traversal, and isolation tests plus documentation updates.

File summaries

File	Description
python/samples/02-agents/context_providers/file_memory_provider.py	Documents opaque scopes and uses a flat example.
python/packages/core/tests/workflow/test_agent_executor.py	Removes redundant whitespace.
python/packages/core/tests/core/test_sessions.py	Tests session filename isolation and Unicode encoding.
python/packages/core/tests/core/test_harness_todo.py	Tests todo-store key derivation.
python/packages/core/tests/core/test_harness_memory.py	Tests memory-store key derivation.
python/packages/core/tests/core/test_harness_file_memory.py	Tests scope isolation and fail-closed behavior.
python/packages/core/tests/core/test_filesystem.py	Covers the shared derivation helper.
python/packages/core/AGENTS.md	Documents storage-key conventions.
python/packages/core/agent_framework/_sessions.py	Reuses shared filename derivation.
python/packages/core/agent_framework/_harness/_todo.py	Reuses shared todo path derivation.
python/packages/core/agent_framework/_harness/_memory.py	Reuses shared memory path derivation.
python/packages/core/agent_framework/_harness/_file_memory.py	Encodes scopes as single storage segments.
python/packages/core/agent_framework/_harness/_file_access.py	Clarifies path-normalizer limitations.
python/packages/core/agent_framework/_filesystem.py	Implements shared storage-key helpers.

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 6
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): 6b746d4ffaea
Model: gpt-5.6-sol-fast

Overview

This PR centralizes opaque storage-key derivation and adds strong traversal, reserved-name, Unicode-normalization, and isolation coverage. The shared encoding separates identifiers that the previous path normalizer folded together, but several consumers adopt it without preserving their existing persisted layouts. As a result, existing memory, file-memory, session/history, and todo data can appear missing after an upgrade.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
4 verified findings remained after source verification (1 high, 3 medium) across 4 files. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_filesystem.py, python/packages/core/agent_framework/_harness/_file_memory.py, python/packages/core/agent_framework/_harness/_memory.py, python/packages/core/agent_framework/_harness/_todo.py

[Evan Mattson (moonbox3)]

Following up on the digest-threshold discussion: could session-filtered search compare the requested session_id against its derived filename stem instead of reverse-decoding every file? With lowercase base32, "a/" + "a" * 108 now crosses the digest threshold, _decode_transcript_session_id returns None, and search_transcripts(..., session_id=...) skips a transcript that this version just wrote. Deriving the expected stem for filtered search would preserve access even when the stem is intentionally irreversible.