Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Execution Model

This page defines Toolang runtime execution semantics.

Two orthogonal axes

Toolang keeps two concepts separate:

  • runtime loop a long-lived trigger source
  • execution strategy the strategy used to complete one turn

Rules:

  • runtime loops decide when a turn starts
  • execution strategies decide how that turn completes
  • these concepts must not be merged

Message model

Toolang uses one Message shape as the semantic input for one turn.

Minimal fields:

  • origin
  • channel
  • sender
  • thread_id
  • text
  • meta

origin values:

  • invoke
  • chat
  • task
  • chore
  • will

Rules:

  • origin == chat requires a non-null channel
  • origin in {invoke, task, chore, will} requires channel = null
  • task, chore, and will use sender = self
  • run and start are process surfaces, not message origins

Runtime loops

Toolang defines four runtime loops:

  • server accepts local API requests
  • poll polls external channels
  • hook accepts hook deliveries
  • pulse emits internal task, chore, and will

Rules:

  • runtime loops create turn requests
  • runtime loops do not execute turns directly
  • toolang invoke starts no runtime loops
  • toolang run starts a foreground runtime-loop set
  • toolang start starts a background runtime-loop set

Execution strategies

Execution strategy is a turn-local concern.

Examples:

  • direct
  • react
  • plan_execute

Rules:

  • one turn uses one execution strategy
  • one strategy may produce many internal steps
  • strategy selection is independent from runtime-loop selection

Core execution objects

Toolang execution is organized around:

  • run
  • thread_group
  • thread
  • turn
  • step

The local execution truth layer lives in ${AGENT_ROOM}/execution.db. ${AGENT_ROOM}/agent.run remains a current-running summary, not the historical truth.

Runs, threads, turns, and steps

  • run one continuous active interval of agent execution
  • thread one durable execution context
  • turn one complete handling attempt inside a thread
  • step one internal part of one turn

Important rules:

  • one thread may span many turns
  • one thread may span many runs
  • every turn belongs to exactly one run
  • at most one turn may run at a time for the same thread_id

Scheduling

The scheduler should enforce:

  1. thread serialization
  2. thread-group budget limits

Suggested built-in thread groups:

  • chat
  • task
  • chore
  • will

Default intent:

  • chat highest priority
  • task moderate concurrency
  • chore low priority with coalescing
  • will lowest priority with aggressive coalescing

Truth layer and projections

Execution uses three layers:

  • agent-local execution truth
  • shared bus projection
  • outbound side effects

Rules:

  • local execution state is written first
  • shared bus projection is written second
  • external delivery happens last

The truth layer should preserve enough raw data to derive later projections and statistics without depending on bus/events.db.

Loop-owned sources

Recommended source files:

  • channels.toml
  • hooks.toml
  • tasks/
  • chores/
  • will.md

Recommended runtime state:

  • poll/
  • hooks/
  • pulse.json

The pulse loop is responsible for turning local task, chore, and will state into schedulable turn requests.

Read next

© 2026 Toolang