Runtime Design

The Toolang runtime is built around the idea of a home.

Home

A home contains:

• top-level .too agent files
• toolang.toml
• toolang.lock
• local caps under skills/, services/, prompts/, and psyches/
• resolved artifacts under .caps/
• per-agent state under agents/<agent_name>/

Global storage

Toolang also uses global storage under ~/.toolang/:

~/.toolang/
  store/
  registry/
  cache/
  hotel/
  agents.db

What each part does

• store/: global object store for resolved artifacts
• registry/: cached registry metadata, including caps.sh
• cache/: transient download cache
• hotel/: materialized homes for URL-based execution
• agents.db: table of running agents across homes

Resolution

Capability resolution follows this order:

1. source files
2. toolang.lock
3. home .caps/
4. global ~/.toolang/store/
5. remote registry
6. rematerialize into home .caps/

References

• agent_ref resolves to an agent source
• run_ref resolves to a running agent
• house_no is the short persistent identifier used for runtime lookup

For the full design spec, see the repository document: runtime-design.md.