refactor: A2 path restructure — remove python/ prefix

[Nafania]

Summary

Removes the python/ prefix from all module directories, aligning with upstream v1.1 structure:

• python/helpers/ → helpers/
• python/tools/ → tools/
• python/api/ → api/
• python/extensions/ → extensions/python/
• python/websocket_handlers/ → websocket_handlers/

3649 import references updated. All 2559 tests pass (including integration).

Part of

Upstream backport project (Phase 1) — see docs/specs/2026-03-28-upstream-backport-design.md.

Changes

• Directory moves — git mv preserving history
• Import rewrites — all python.helpers.* → helpers.*, etc.
• Dynamic path loaders — extension.py, agent.py tool loading, run_ui.py handler loading, websocket_namespace_discovery.py
• get_base_dir() fix — adjusted for new directory depth
• __init__.py files — created for all new top-level packages
• Pytest config — added pythonpath = ["."] and --import-mode=importlib to resolve tests/helpers/ vs helpers/ collision
• CI path triggers — updated for new directory structure
• Documentation — AGENTS.md architecture diagram, all docs updated

Breaking Changes

• All worktree branches require rebase after merge
• All open PRs require rebase after merge
• Any external code importing python.helpers.* etc. must update imports

Test plan

• All 2559 unit + integration tests pass
• Zero remaining python.(helpers|tools|api|extensions|websocket_handlers) references
• Import smoke test from new paths
• CI path triggers updated
• AGENTS.md and all docs updated

Made with Cursor

[Nafania]

Code Review

Reviewed all 523 changed files across 9 commits (base 6fa12269..head 2e1de4c4).

Strengths

• Zero stale references — all 3649 python.* dot-imports fully rewritten, no stragglers in .py or .yml files
• Symmetric diff — 3866 insertions / 3866 deletions in source files, confirming pure rename with no accidental content changes during bulk sed
• get_base_dir() correctly updated — navigates 1 level up from helpers/files.py instead of 2 from python/helpers/files.py
• pytest config properly handles tests/helpers/ vs helpers/ shadowing via --import-mode=importlib and pythonpath = ["."]
• All __init__.py files present — all 6 new top-level packages have them
• CI path triggers properly updated — both push and pull_request filters list new directories
• Dynamic loaders updated — run_ui.py, websocket_namespace_discovery.py, agent.py tool loading all use correct new paths
• Well-structured commit history — logical progression: docs → moves → imports → strings → fixups → docs

Issues

Important: Extension override paths silently broken

helpers/extension.py:33 — call_extensions() now passes subpaths to get_paths() in a way that breaks agent-profile and user extension overrides:

# Current (after this PR)
paths = subagents.get_paths(agent, "python", extension_point, default_root="extensions")

This produces:

• ✅ Default path: extensions/python/<ext_point> (correct)
• ❌ Agent profile: agents/<profile>/python/<ext_point> (should be agents/<profile>/extensions/python/<ext_point>)
• ❌ User override: usr/python/<ext_point> (should be usr/extensions/python/<ext_point>)

No crash occurs — non-existent paths are silently skipped via must_exist_completely=True — but override mechanisms are silently dropped. Evidence: agents/_example/extensions/agent_init/ exists on disk but would be ignored by the new code.

Fix: Pass "extensions", "python" as separate subpath components:

paths = subagents.get_paths(agent, "extensions", "python", extension_point, default_root="")

Minor: USER_EXTENSIONS_FOLDER is dead code

helpers/extension.py:11 — the constant USER_EXTENSIONS_FOLDER = "usr/extensions" is defined but never used at runtime (only imported by test for assertion).

Minor: Test coverage gap for path resolution

tests/helpers/test_extension.py:65 — the test mocks subagents.get_paths entirely, so the actual subpath arguments are never verified. A targeted assertion would have caught the Important issue above:

@pytest.mark.asyncio
async def test_call_extensions_passes_correct_paths(self):
    with patch("helpers.subagents.get_paths", return_value=[]) as mock_gp:
        await call_extensions("agent_init", agent=None)
    mock_gp.assert_called_once_with(
        None, "extensions", "python", "agent_init", default_root=""
    )

Assessment

Ready to merge: With fixes (Important issue #1)

The refactoring is exceptionally clean for its scale — 523 files, zero stale references, symmetric diffs, well-structured commits, proper test infrastructure updates. The single substantive issue is a path regression in call_extensions() where agent-profile and user extension override paths silently changed. This is a one-line fix. After correcting it, this is ready for production.

[Nafania]

Follow-up Review (after fix commit dfc2ee1)

The fix commit addressed the original review's Important issue, but the fix is still incorrect. Extension override paths remain broken.

Analysis

get_paths() in helpers/subagents.py:300-359 applies *subpaths uniformly to ALL scopes (profile, user, project, default). There is no way to have python/ appear only in the default path using a single get_paths() call.

Pre-A2 (correct, working):

paths = subagents.get_paths(agent, "extensions", extension_point, default_root="python")
# subpaths = ("extensions", ext_point)
# → Profile:  agents/<profile>/extensions/<ext_point>  ✅
# → User:     usr/extensions/<ext_point>                ✅
# → Default:  python/extensions/<ext_point>             ✅

Commit 4944ee0 (broken):

paths = subagents.get_paths(agent, "python", extension_point, default_root="extensions")
# subpaths = ("python", ext_point)
# → Profile:  agents/<profile>/python/<ext_point>       ❌
# → User:     usr/python/<ext_point>                    ❌
# → Default:  extensions/python/<ext_point>             ✅

Commit dfc2ee1 (still broken):

paths = subagents.get_paths(agent, "extensions", "python", extension_point, default_root="")
# subpaths = ("extensions", "python", ext_point)
# → Profile:  agents/<profile>/extensions/python/<ext_point>  ❌
# → User:     usr/extensions/python/<ext_point>               ❌
# → Default:  extensions/python/<ext_point>                   ✅

Evidence: agents/_example/extensions/agent_init/_10_example_extension.py exists on disk. The fix looks for agents/_example/extensions/python/agent_init/ — the example agent's extension override is silently ignored.

Correct Fix

Split the path construction using the existing include_default=False parameter:

paths = subagents.get_paths(
    agent, "extensions", extension_point,
    default_root="", include_default=False,
)
default_path = files.get_abs_path("extensions", "python", extension_point)
if files.exists(default_path):
    paths.append(default_path)

This produces:

Scope	Path	Correct?
Project agent	<proj>/.a0proj/agents/<profile>/extensions/<ext_point>	✅
Project	<proj>/.a0proj/extensions/<ext_point>	✅
User agent	usr/agents/<profile>/extensions/<ext_point>	✅
Default agent	agents/<profile>/extensions/<ext_point>	✅ (matches agents/_example/extensions/agent_init/)
User	usr/extensions/<ext_point>	✅ (backward compatible)
Default	extensions/python/<ext_point>	✅ (new post-A2 location)

Override priority is preserved: profile extensions come first (higher priority), default extensions come last. The merge logic in call_extensions() keeps the first occurrence per filename, so overrides correctly shadow defaults.

Assessment

Not ready to merge — the extension override regression is still present. The correct fix is a 4-line change in helpers/extension.py:33.

[Nafania]

Review #3 — Fix Verified (commit d95c6d54)

Fix Verification

The split-path approach is correct. Full path trace for call_extensions("agent_init", agent) with profile _example:

Step 1 — get_paths(agent, "extensions", "agent_init", default_root="", include_default=False):

Priority	Scope	Path	Correct?
1	Project + Profile	<proj>/.a0proj/agents/_example/extensions/agent_init	✅
2	Project	<proj>/.a0proj/extensions/agent_init	✅
3	User Profile	usr/agents/_example/extensions/agent_init	✅
4	Default Profile	agents/_example/extensions/agent_init	✅
5	User Global	usr/extensions/agent_init	✅

No python/ segment in override paths. Backward compatible with existing agent profiles.

Step 2 — Manual default path:

Priority	Scope	Path	Correct?
6 (last)	Default	extensions/python/agent_init	✅

Override priority preserved — the dedup logic (first-occurrence wins) ensures profile extensions shadow defaults.

Verified on disk:

• agents/_example/extensions/agent_init/_10_example_extension.py — exists, would be found at priority 4 ✅
• extensions/python/agent_init/ — exists, appended at priority 6 ✅

Other get_paths() Callers — No Similar Issues

Caller	Assessment
agent.py:682 (parse_prompt)	subpaths=("prompts",) — no python/ involved. OK
agent.py:689 (read_prompt)	Same. OK
agent.py:1046 (tool loading)	subpaths=("tools", name+".py"), default_root="" — python/ was a prefix, not sandwiched. OK
skills.py:51	subpaths=("skills",) — never used python/. OK
_15_load_profile_settings.py:13	Profile/project only, include_default=False. OK

Websocket handlers use get_abs_path("websocket_handlers") directly — independent of get_paths().

Stale Reference Scan

• from python. / import python. — 0 matches
• "python/" / 'python/' string paths — 0 matches
• default_root="python" — 0 matches

Minor (Nice to Have)

1. Test coverage gap — test_extension.py patches get_paths entirely, never asserting on include_default=False or the manual default path append. A regression to the old single-call pattern wouldn't be caught by tests. Consider adding a targeted assertion.

2. Dead constants — DEFAULT_EXTENSIONS_FOLDER and USER_EXTENSIONS_FOLDER in helpers/extension.py are defined but never referenced in production code (pre-existing, not introduced by this PR).

Assessment

Ready to merge: Yes

The split-path fix correctly addresses the fundamental incompatibility between override paths (no python/ segment) and the default path (python/ sandwiched between extensions/ and <ext_point>). All other get_paths() call sites are unaffected. Zero stale references remain. Override priority is preserved. Clean for production.