Developer Notes

Developer Notes explain the v1-compatible components and runtime boundaries retained in OpenRath v2.0.0. They are written for developers who want to extend OpenRath, read the source, write custom workflows, or connect a new backend.

This page maps the main component pages to the relevant source files and tests.

Component map

Component	Covers	Entry point
Session	Context table, Provider/backend placement, session graph.	Session
Sandbox	Backend registration, sandbox lifecycle, local/OpenSandbox behavior.	Sandbox
Tool	FlowToolCall, backend payloads, tool result chunks, streams.	Tool
AgentParam	Agent-side system session and provider options.	Agent Param
Workflow	Module tree, Provider placement, Selector routing, and static compilation.	Workflow
LLM	Provider registry, OpenAI-compatible and Anthropic clients, streaming, retry, budget, and executor replacement points.	LLM
Memory	Local and OpenViking memory stores, memory ops, and Agent recall/commit behavior.	Memory
Async runtime	Lazy sessions, resource-keyed tool dispatch, and private runtime boundaries.	Async Runtime
Persistence	Atomic JSON writes, data-root compatibility, credentials, and cross-plane GC.	Persistence Foundations

Reading order

Goal	Suggested order
Understand the runtime path	Session -> Sandbox -> Tool
Write a single agent	AgentParam -> Workflow -> LLM
Write a multi-agent workflow	Workflow -> AgentParam -> Session
Add model-routed control flow	Workflow -> LLM -> Session
Inspect resources before runtime	Workflow compile -> Memory -> LLM
Write a custom tool	Tool -> Sandbox -> Session
Connect a new model gateway	LLM -> AgentParam
Add long-term agent state	Memory -> Workflow -> Session
Reason about lazy results	Async Runtime -> Session -> Tool
Understand on-disk lifecycle	Persistence -> Session -> Memory

Source and tests

Component	Main source	Main tests
Session	src/rath/session/session.py, loop.py, compress.py, graph/	tests/session/, tests/integration/test_session_loop_real.py, tests/integration/test_session_compress_real.py
Sandbox	src/rath/backend/abc.py, local.py, opensandbox.py	tests/backends/, tests/conformance/, tests/unit/test_registry.py
Tool	src/rath/flow/tool/, src/rath/backend/tool_types.py	tests/session/test_tool_registry.py, tests/flow/test_flow_tool_user_subclass.py, tests/unit/test_flow_tool.py
AgentParam	src/rath/flow/agent_param.py, src/rath/flow/agent.py	tests/flow/test_workflow_agent.py, tests/test_import.py
Workflow	src/rath/flow/workflow.py, compile.py, agent.py, compressor.py, selector.py, empty.py	tests/flow/test_workflow_agent.py, tests/flow/test_selector.py, tests/flow/test_compile*.py
LLM	src/rath/llm/, src/rath/session/provider_builtin.py	tests/llm/, tests/session/test_llm_message_wire.py
Memory	src/rath/memory/, src/rath/flow/memory_inject.py	tests/memory/, tests/flow/test_agent_memory_*
Async runtime	src/rath/_async/, src/rath/session/session.py lazy materialization hooks	tests/session/test_lazy_session.py, tests/concurrency/, tests/bench/
Persistence	src/rath/persistence/, src/rath/config/credentials.py	tests/persistence/, tests/config/test_credentials_split.py

Developer Notes describe behavior that exists in the current source. Roadmap notes, troubleshooting, and full application tutorials are tracked separately.

Developer Notes

• Session
  • Overview
  • Source map
  • Why Context Is A Table
  • Agent Session And User Session
  • Session Provider Placement
  • Session graph
  • Five Primitives
  • Sandbox Lifecycle
  • run_session_loop State Transfer
  • run_session_compress State Transfer
  • Code Reading Checkpoints
  • Edge Cases
  • Test Coverage
• Sandbox
  • Overview
  • Source map
  • Backend Abstraction
  • Backend registry
  • How Session Binds Sandbox
  • local backend
  • OpenSandbox backend
  • Choosing local Or OpenSandbox
  • Payload Dispatch Matrix
  • Stream API
  • Health Check And Validation
  • Edge Cases
  • Code Reading Checkpoints
  • Test Coverage
• Tool
  • Overview
  • Source map
  • FlowToolCall Contract
  • How The Tool Table Is Built
  • From Model Response To Tool Result
  • BackendTool payload
  • When To Return Python Objects Directly
  • When To Use Backend Dispatch
  • Where Stream API Fits
  • Edge Cases
  • Code Reading Checkpoints
  • Test Coverage
• AgentParam
  • Overview
  • Source map
  • Data Structure
  • Why The System Prompt Is A Session
  • How Provider Enters The Request
  • Provider Placement
  • Registration In Workflow
  • What flow.Agent Wraps
  • When To Use AgentParam Directly
  • Output Session Boundary
  • Current Boundaries
  • Code Reading Checkpoints
  • Test Coverage
• Workflow
  • Overview
  • Source map
  • Minimal Workflow
  • AgentParam Auto-Registration
  • Module Tree And Provider Placement
  • Single-Agent To Multi-Agent
  • Session Is The Composition Unit
  • Session-Level Parallelism
  • Preset Workflows
  • Dynamic Workflow Routing
  • Static Compilation
  • Nested Workflow
  • Sequential Multi-Agent Pattern
  • Hierarchical Composition Pattern
  • Tool And Sandbox Boundaries
  • Call Path
  • Current Boundaries
  • Code Reading Checkpoints
  • Test Coverage
  • Related Pages
• LLM
  • Overview
  • Source map
  • Provider Parameters
  • Default Client
  • Streaming
  • Embedding And VLM Providers
  • SessionLoopExecutor
  • Requests And Responses
  • Integration Points
  • Call Path
  • Edge Cases
  • Test Coverage
• Memory
  • Symmetry With Sandbox Backends
  • Local Backend
  • OpenViking Adapter
  • Agent Memory Lifecycle
  • Design Boundaries
  • Test Coverage
• Async Runtime
  • Public Boundary
  • Lazy Session
  • Parallel Tool Dispatch
  • Persistence And Crash Detection
  • Failure Semantics
  • Stability Note
• Persistence Foundations
  • Boundaries
  • Data-root lifecycle
  • Source and tests