feat(session): add account namespace policy and shared sessions

[qin-ctx]

Description

Implement the account-level namespace policy matrix and switch sessions to account-shared storage, so filesystem visibility, retrieval filters, session ownership, and message actor semantics all resolve from the same canonical namespace rules.

This PR also updates the session message contract:

• trusted / ROOT / ADMIN may explicitly pass role_id
• USER requests must derive role_id from request context
• ADMIN may reuse X-OpenViking-User / X-OpenViking-Agent within its own account to simulate user view

Related Issue

Fixes #1351

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Refactoring (no functional changes)
• Performance improvement
• Test update

Changes Made

• Add AccountNamespacePolicy plus namespace resolver helpers, and use canonical URI + (owner_user_id, owner_agent_id) tuples across VikingFS, context, vector indexing, retrieval filtering, and directory initialization.
• Move sessions to account-shared viking://session/{session_id} paths, extend message persistence with role_id, track session participants, and enforce new auth semantics for ROOT / ADMIN / USER message writes.
• Update admin APIs, Python clients, CLI/console flows, and add examples/multi_tenant/shared_session_role_id_http.py for one-shot setup of the four policy combinations and end-to-end verification of multi-user and normal-user scenarios.
• Document the manual agent-memory upgrade path as a two-step process: before upgrading, export from legacy viking://agent/{legacy_hash}/memories/; after upgrading, import into the new agent space parent, using viking://agent/{agent_id}/ when isolate_agent_scope_by_user=false or viking://agent/{agent_id}/user/{user_id}/ when isolate_agent_scope_by_user=true.

Testing

• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• I have tested this on the following platforms:
  • Linux
  • macOS
  • Windows

Checklist

• My code follows the project's coding style
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published

Screenshots (if applicable)

N/A

Additional Notes

Demo script usage:

python examples/multi_tenant/shared_session_role_id_http.py \
  --url http://127.0.0.1:1933 \
  --root-key <root-key>

Optional flags:

• --name-prefix demo-team to control generated account names
• --run-id custom1234 to control generated account/session suffixes
• --effective-agent-a / --effective-agent-b / --normal-user-agent to override demo agents

Agent memory migration note:

# Before upgrading: export from the legacy hash namespace
ov export viking://agent/{legacy_agent_space_hash}/memories ./agent_memory.ovpack

# After upgrading: import into the new agent space parent
# isolate_agent_scope_by_user = false
ov import ./agent_memory.ovpack viking://agent/{agent_id}/ --force

# isolate_agent_scope_by_user = true
ov import ./agent_memory.ovpack viking://agent/{agent_id}/user/{user_id}/ --force

Do not import directly into .../memories/, or the imported tree will become .../memories/memories/.... When isolate_agent_scope_by_user=true, viking://agent/{agent_id}/user/ is incomplete and must include the concrete user_id.

Notes:

• I did not run the full test suite in this environment.
• The commit passed the repository's ruff and ruff format pre-commit hooks.

[github-actions]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

⏱️ Estimated effort to review: 4 🔵🔵🔵🔵⚪

🏅 Score: 85

🧪 PR contains tests

🔒 No security concerns identified

✅ No TODO sections

🔀 Multiple PR themes Sub-PR theme: Add account namespace policy resolution Relevant files: openviking/core/namespace.py openviking/core/directories.py openviking/storage/viking_vector_index_backend.py openviking/storage/viking_fs.py Sub-PR theme: Shared sessions and role_id semantics Relevant files: openviking/session/session.py openviking/server/routers/sessions.py tests/server/test_api_sessions.py Sub-PR theme: Demo script and documentation Relevant files: examples/multi_tenant/shared_session_role_id_http.py docs/design/account-namespace-shared-session-design.md

⚡ Recommended focus areas for review Missing License Header New file in openviking/ directory does not contain the required AGPL-3.0 license header. """Namespace policy helpers for account/user/agent/session URIs.""" Broad Exception Catch _ensure_container_directory uses bare except Exception: without logging, which hides real errors. try: await self._get_viking_fs().mkdir(uri, exist_ok=True, ctx=ctx) except Exception: pass

[github-actions]

PR Code Suggestions ✨

No code suggestions found for the PR.