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

Task Model

This page defines how Toolang treats tasks as a collaboration primitive.

Core principle

Toolang should not implement a different execution model for each task system. The runtime executes one task object:

  • a local task file under ${AGENT_ROOM}/tasks/

Remote systems should be mirrored into local task files first.

Keep runtime semantics small

The runtime should provide only a small amount of task-specific structure:

  • provider
  • task ref
  • task name
  • body
  • status
  • requester
  • thread id
  • available task services

Provider-specific orchestration should stay out of core runtime logic.

Built-in task prompt

Task execution behavior should come from one built-in prompt rather than large provider-specific workflows.

That prompt should tell the agent to:

  • understand the current task before acting
  • perform the requested work
  • update the task at important milestones
  • write the result back before finishing
  • clearly report missing task-service configuration

Task context in one turn

When origin = task, the runtime should inject structured task context.

Suggested shape:

{
  "task": {
    "provider": "local|taskwarrior|linear|github",
    "ref": "task:...",
    "name": "...",
    "body": "...",
    "status": "...",
    "requester": "...",
    "thread_id": "task:..."
  },
  "task_services": {
    "read": true,
    "write": true,
    "comment": true
  }
}

This is enough for the built-in task prompt to reason about the current work.

Local task files

Local task files live under:

  • ${AGENT_ROOM}/tasks/*.md

Suggested front matter:

  • id
  • requester
  • status
  • paused

Rules:

  • filename is the human-facing task name
  • body is the full task input
  • id is a short stable identifier
  • thread_id = task:local:<id>

Recommended body sections:

  • ## Task
  • ## Notes
  • ## Progress
  • ## Outcome

Task services

Task-system integration is a service capability, not a new runtime abstraction family.

The built-in prompt should reason in terms of:

  • read
  • write
  • comment

not in terms of provider-specific APIs.

Remote task mirrors

Remote task systems should not enter the runtime directly as provider-specific task deliveries. Instead:

  1. a chore queries the remote provider
  2. Toolang creates or updates one local task file
  3. the pulse loop schedules a normal origin = task turn
  4. later sync or service calls push local progress back upstream

Mirror bookkeeping belongs in:

  • ${AGENT_ROOM}/task_mirrors.json

Each mirror entry should record:

  • provider
  • remote_ref
  • local_task_id
  • path
  • remote_updated_at
  • last_synced_at

Missing configuration

If required task services are missing, the agent should not silently degrade.

Expected behavior:

  • clearly state what is missing
  • request the needed service configuration
  • continue only when the remaining work is still meaningful

Read next

© 2026 Toolang