Runtime State

You do not need every internal runtime detail to use Toolang well, but you do need to know where state lives, what sync writes, and which files matter when something goes wrong.

Toolang root

By default, Toolang keeps global machine state under ~/.toolang/.

~/.toolang/
  agents.db
  sync/
  skills/
  services/
  prompts/
  psyches/
  agents/
  guests/
  sandbox/
  bus/

This is where Toolang keeps the known-agent registry, global caps, global sync output, and shared bus projections.

Agent home

An agent home is your working directory. It contains the files you author and a machine-managed .toolang/ directory.

${AGENT_HOME}/
  ship-docs.too
  agents.too
  .env
  .toolang/

Agent room

Each agent gets a private room inside .toolang/:

${AGENT_HOME}/.toolang/agents/{AGENT}/
  agent.run
  agent.log
  execution.db
  pulse.json
  task_mirrors.json
  runs/
  sync/
  chats/
  sandbox/
  tasks/
  chores/
  will.md

If you need to inspect a background process, a failed run, a prompt trace, or a chat history, this is the first place to look.

The most useful files are usually:

agent.run current running summary for a started agent
agent.log runtime log output
execution.db durable run, thread, turn, and step records
pulse.json latest scheduler state for tasks, chores, and will
task_mirrors.json bindings between remote task systems and local task files

What `sync` writes

toolang sync reads your source files, resolves refs, and materializes scope-separated runtime state.

It writes:

global synced caps under ~/.toolang/sync/
shared synced caps under ${AGENT_HOME}/.toolang/sync/
agent-scoped synced caps under ${AGENT_HOME}/.toolang/agents/{AGENT}/sync/
one per-agent sync state file under ${AGENT_HOME}/.toolang/sync/

That separation matters because runtime precedence stays explicit instead of being flattened into one merged view on disk.

Threads, turns, and steps

Toolang stores durable execution context:

a thread is the ongoing context for a conversation or task
a turn is one complete handling attempt inside that thread
a step is one internal action inside a turn

For day-to-day use, this means chat history, run traces, and turn metadata stay queryable after the process exits.

Local files are the primary truth

Toolang is local-first. Local files and local databases are the execution truth. Shared APIs and bus event streams are useful projections, but they do not replace the state on disk.

That makes the runtime easier to inspect, repair, back up, and trust on one machine.