Developer Notes#

Developer Notes explain OpenRath’s core components and runtime boundaries. 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, 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`	Composable agent workflow modules.	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

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`
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`

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`, `agent.py`, `compressor.py`	`tests/flow/test_workflow_agent.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/`

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

Developer Notes