refactor: extract turn assembly; fix gateway BOOT.md startup guard

[Aliciawque]

What does this PR do?

This PR extracts two explicit Phase 1 runtime seams from run_agent.py while preserving existing external behavior:

• API-call-time turn assembly now lives in agent/turn_assembly.py
• tool execution result normalization now lives in agent/tool_runtime.py

It also hardens the built-in gateway BOOT.md startup hook so it only runs when a gateway model can be resolved, and adds HERMES_DISABLE_BOOT_MD as an explicit disable switch.

The intent is to make turn preparation and tool-result handling easier to reason about without changing approval, registry dispatch, or legacy tool-message compatibility.

Related Issue

Fixes #5239

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Added agent/turn_assembly.py with TurnAssembly / SideChannelContext helpers for API-call-time prompt assembly
• Added agent/tool_runtime.py with ToolExecutionEnvelope / ToolFailure normalization helpers
• Integrated turn assembly and tool-result normalization into run_agent.py
• Preserved legacy string-based tool-message behavior after normalization
• Added focused tests for:
  • tests/agent/test_turn_assembly.py
  • tests/agent/test_run_agent_context_references.py
  • tests/agent/test_tool_runtime.py
  • tests/run_agent/test_run_agent.py
• Added architecture/docs artifacts:
  • docs/architecture/2026-04-09-hermes-runtime-organs-rfc.md
  • docs/architecture/2026-04-09-phase1-runtime-organs-implementation-plan.md
• Updated gateway startup handling:
  • gateway/builtin_hooks/boot_md.py now resolves the configured gateway model before running BOOT.md
  • startup skips cleanly when the model is missing or resolution fails
  • gateway/hooks.py now supports disabling the built-in boot hook via HERMES_DISABLE_BOOT_MD

How to Test

1. Run the focused runtime and agent-loop regression coverage:
   pytest -q tests/agent/test_turn_assembly.py tests/agent/test_run_agent_context_references.py tests/agent/test_tool_runtime.py tests/run_agent/test_run_agent.py tests/agent/test_context_references.py tests/run_agent/test_agent_loop_tool_calling.py tests/run_agent/test_dict_tool_call_args.py tests/run_agent/test_tool_arg_coercion.py tests/run_agent/test_agent_loop.py
2. Confirm the targeted validation passes:
   • 323 passed
   • 1 skipped
   • 0 failed
3. For gateway behavior:
   • start the gateway with a valid configured model and confirm BOOT.md runs normally
   • start the gateway with no resolvable model and confirm the boot hook is skipped with a warning
   • set HERMES_DISABLE_BOOT_MD=1 and confirm the built-in startup hook is not registered

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: Ubuntu / WSL

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Focused validation result:

• 323 passed
• 1 skipped
• 0 failed

[Aliciawque]

Follow-up context for reviewers:

This PR intentionally bundles two tightly related changes:

1. Phase 1 runtime extraction from run_agent.py

   • extracts API-call-time turn assembly into agent/turn_assembly.py
   • extracts tool execution result normalization into agent/tool_runtime.py
   • keeps external behavior and legacy tool-message compatibility intact

2. Gateway startup hardening for built-in BOOT.md

   • only runs the boot hook when a gateway model can be resolved
   • adds HERMES_DISABLE_BOOT_MD as an explicit disable switch
   • fixes the startup path covered by BOOT.md startup hook bypasses gateway runtime auth #5239

Reason for bundling: the PR is a small runtime-boundary cleanup plus a closely adjacent gateway startup guard, both validated in the same focused regression pass.

Focused validation run used for this PR:
pytest -q tests/agent/test_turn_assembly.py tests/agent/test_run_agent_context_references.py tests/agent/test_tool_runtime.py tests/run_agent/test_run_agent.py tests/agent/test_context_references.py tests/run_agent/test_agent_loop_tool_calling.py tests/run_agent/test_dict_tool_call_args.py tests/run_agent/test_tool_arg_coercion.py tests/run_agent/test_agent_loop.py

Result:

• 323 passed
• 1 skipped
• 0 failed

[alt-glitch]

Note: #5239 (the linked issue) was already closed — fixed by #17093 which removed BOOT.md entirely. The refactor portion of this PR may still have value but the bug-fix motivation is moot.

[Aliciawque]

Thanks for the update. Since #5239 was resolved by #17093 and the BOOT.md built-in hook has been removed, the gateway fix here is no longer applicable. I’ll close this PR rather than keep a stale/conflicting refactor open. If the turn assembly / tool runtime extraction is still useful later, I can revisit it as a smaller focused PR against current main.