Collaboration Model

This page defines how one long-lived Toolang runtime accepts work and coordinates with humans or other agents.

Core principle

Toolang should not invent a separate execution model for:

human chat
agent-to-agent communication
task-driven work
chore-driven work

All of these enter the same runtime through one normalized queue of turn requests.

Keep `run` narrow

run already means one continuous active interval of one agent process.

The runtime queue should therefore contain:

turn requests

not run requests.

This keeps the vocabulary stable:

run process lifetime
turn request one schedulable work item inside that lifetime

Runtime shape

One long-lived runtime contains:

one run
one inbox
one scheduler
one execution store
zero or more runtime loops

Runtime loops do not execute work directly. They place turn requests into the inbox. The scheduler decides when each request may start.

Sources of turn requests

Built-in sources:

chat
task
chore
invoke
will

Rules:

all of these become turn requests
all of them are persisted under the same execution truth model
all of them are scheduled by the same scheduler

Threads remain the durable unit

Suggested mappings:

chat one chat thread id
task work task:<task_ref>
chore work chore:<chore_key>
will work will:<agent_id>

Rules:

one thread may span many turns
one thread may span many runs
at most one running turn may exist per thread at a time

Scheduler policy

The first useful scheduler policy is:

serialize by thread_id
allow different threads to run concurrently
apply group-level budgets by thread_group

Default intent:

chat highest priority
task medium priority
chore low priority
will lowest priority

Minimal communication primitives

Agent collaboration should keep only two outward-facing primitives:

chat
task

Use chat for quick coordination. Use tasks for durable delegation and tracked work.

Chores are not a communication primitive

chore is a local runtime trigger. If a chore needs to involve another actor, it should do so by emitting:

a chat
or a task mutation

Human mental model

A human operator should only need to understand:

the agent is always running inside one run
runtime loops place work into one inbox
the scheduler chooses when each thread may run
work arrives as chat, task, chore, or invoke
collaboration happens through chat or task

Everything else should remain an implementation detail.