Roles

Role Overview

Starweft achieves distributed coordination through four node roles. Each role operates as an independent CLI process and communicates via Ed25519-signed messages.

# Specify the role in config.toml
[node]
role = "owner"  # principal / owner / worker / relay

Principal

The Principal is the "decision maker" of the system. It is the node operated by a human user and holds authority over starting and stopping projects.

Responsibilities

• Submitting visions: Sends a goal (VisionIntent) to the owner using the starweft vision submit command
• Issuing stop orders: Instructs the project or task tree to stop using the starweft stop command
• Granting approvals: Sends ApprovalGranted at the approval gate before task execution

Stop Authority

The Principal holds a dedicated key pair called stop_authority_key. StopOrder messages are signed with this key, and recipients verify them using the stop_public_key.

[identity]
actor_key_path = "~/.starweft/identity/actor_key"
stop_authority_key_path = "~/.starweft/identity/stop_authority_key"

Vision Constraints

The Principal can specify VisionConstraints when submitting a vision.

{
  "budget_mode": "minimal",
  "allow_external_agents": false,
  "human_intervention": "required"
}

• budget_mode: When set to "minimal", the number of decomposed tasks is limited
• allow_external_agents: Whether to allow external agents to participate
• human_intervention: When set to "required", approval is needed before task execution

Owner

The Owner is the project orchestrator. It decomposes visions received from the Principal into tasks, distributes them to Workers, and supervises execution.

Responsibilities

• Generating a ProjectCharter: Drafts a project from the vision and configures evaluation policies
• Task decomposition (Planning): Breaks down the vision into executable tasks
• Sending JoinOffers: Sends participation offers to Workers and verifies their capabilities
• Sending TaskDelegated: Delegates tasks to Workers
• Result evaluation: Receives TaskResultSubmitted and issues EvaluationIssued with multi-dimensional scores
• Retry control: Determines whether to retry failed tasks and re-delegates them
• Relaying StopOrders: Forwards stop orders from the Principal to Workers

Planning Strategies

The Owner supports three planning strategies.

[observation]
planner = "heuristic"
max_planned_tasks = 6
min_task_objective_chars = 48

Evaluation Policy

The Owner evaluates task results across four dimensions.

pub struct EvaluationPolicy {
    pub quality_weight: f32,     // Quality
    pub speed_weight: f32,       // Speed
    pub reliability_weight: f32, // Reliability
    pub alignment_weight: f32,   // Alignment with objectives
}

Retry Strategy

A rule-based retry decision is made for failed tasks.

[owner]
max_retry_attempts = 8
retry_cooldown_ms = 250
retry_strategy = "rule_based"

Worker

The Worker is the task executor. It launches the OpenClaw binary as a subprocess to perform the actual work.

Responsibilities

• Responding to JoinOffers: Verifies capabilities and replies with JoinAccept or JoinReject
• Task execution: Executes tasks through the OpenClaw bridge
• Progress reporting: Sends TaskProgress in the PROGRESS:<float>:<message> format
• Submitting results: Returns execution results to the Owner as TaskResultSubmitted
• Stop handling: Cancels running tasks upon receiving a StopOrder and sends StopAck / StopComplete

OpenClaw Bridge

The Worker launches the OpenClaw binary as a child process.

Worker Process
  │
  │  stdin: BridgeTaskRequest (JSON)
  ▼
┌─────────────────────┐
│  OpenClaw Binary      │
│  (Subprocess)         │
│                     │
│  stdout: PROGRESS:0.5:working...
│  stdout: BridgeTaskResponse (JSON)
│  stderr: Log output
└─────────────────────┘

[openclaw]
enabled = true
bin = "openclaw"
timeout_sec = 3600
capability_version = "openclaw.execution.v1"

Concurrency Control

The Worker can limit the number of concurrently executing tasks.

[worker]
accept_join_offers = true
max_active_tasks = 1

Task Cancellation

Upon receiving a StopOrder, the Worker safely stops tasks through the following procedure.

Relay

The Relay is a message forwarding node. It bridges communication between nodes that cannot communicate directly.

Responsibilities

• Queues received messages directly into its outbox and forwards them to other peers
• Does not verify or modify signatures: Messages are forwarded with their original signatures intact
• If a destination (to_actor_id) is specified, forwards only to that actor
• Broadcast messages are forwarded to all peers except the sender

Configuration

Relay nodes do not require Ed25519 keys.

[node]
role = "relay"
 
[p2p]
relay_enabled = true
direct_preferred = true   # Prefer direct connections

Communication Flow Between Roles

Principal                Owner                   Worker
    │                      │                       │
    │──VisionIntent───────▶│                       │
    │                      │──CapabilityQuery─────▶│
    │                      │◀─CapabilityAdvert.───│
    │                      │──JoinOffer───────────▶│
    │                      │◀─JoinAccept──────────│
    │◀─ProjectCharter──────│                       │
    │                      │──TaskDelegated───────▶│
    │                      │◀─TaskProgress────────│
    │                      │◀─TaskResultSubmitted──│
    │                      │──EvaluationIssued────▶│
    │                      │                       │
    │──StopOrder──────────▶│──StopOrder───────────▶│
    │                      │◀─StopAck─────────────│
    │◀─StopAck─────────────│                       │
    │                      │◀─StopComplete────────│
    │◀─StopComplete────────│                       │

For details on configuring each role, see the Configuration Reference.