ludus run — Agent Interaction

What It Does

The ludus run subcommand group sends messages to agents via OpenClaw. These commands cost LLM tokens — use judiciously.

Subcommands: agent ping, agent task, agent ask, e2e, watcher.

Environment

• Working directory: ludus/
• Ludus host reachable via SSH
• OpenClaw gateway running with registered agents
• At least the main agent must be registered and responsive

1. ludus run agent ping

Sends "Reply with exactly: PONG" and checks for the response. Cheapest way to verify an agent is alive.

1.1 Ping the default agent (main)

ludus run agent ping

Verify (human)

• Output shows "Pinging main agent..."
• Shows the sent prompt and received reply
• Reply contains "PONG" (case-insensitive)
• Shows "Agent is alive"
• Exit code 0

ludus --json run agent ping

Verify (JSON)

• Valid JSON with keys: agent, alive, reply
• agent is "main"
• alive is true
• reply contains "PONG"

1.2 Ping a specific agent

ludus --json run agent ping b4-dev

Verify (JSON)

• agent is "b4-dev"
• alive is true
• reply contains "PONG"

1.3 Ping a nonexistent agent

ludus --json run agent ping nonexistent-agent 2>&1 || true

Verify

• alive is false
• error field present with description
• Exit code 1

2. ludus run agent task

Sends a task to the main agent. The main agent is the orchestrator — it may delegate to sub-agents via beads.

ludus --json run agent task "What agents are available? Reply with a short list."

Verify (JSON)

• Valid JSON with message and reply keys
• message matches the input
• reply contains a meaningful response (not empty)
• next hints include ludus info intercom and ludus info observe

Note: The reply content depends on the agent's current context and instructions. Verification should check structure, not exact wording.

3. ludus run agent ask

Send a message to any agent (not just main). Allows specifying session ID.

ludus --json run agent ask b4-dev "Reply with exactly: HELLO"

Verify (JSON)

• agent is "b4-dev"
• message is "Reply with exactly: HELLO"
• reply contains "HELLO"

Custom session ID

ludus --json run agent ask main "What is 2+2?" --session-id test-session-001

Verify (JSON)

• reply contains "4"
• Session isolation: this message should not bleed into the default session

4. ludus run e2e

Send a task to the main agent and observe the pipeline. Use --reset to wipe beads DBs first (destructive).

ludus run e2e "Create a bead titled 'E2E test' with label dev and close it immediately."

Verify

• Output shows three phases:
  1. "Step 1/3: Reset beads (skipped — use --reset)"
  2. "Step 2/3: Send task to main agent"
  3. "Step 3/3: Observe pipeline"
• Agent processes the task (reply shown)
• Observer launches (exec into e2e-observer)

4.1 With reset

ludus run e2e --reset "Create a bead titled 'E2E test' with label dev and close it immediately."

Warning: --reset wipes all beads databases (local + remote). Only use when you need a clean slate.

Verify

• Step 1 shows "Reset beads" (not skipped)
• Local and remote beads DBs are wiped and re-initialized

Note: E2E is the most expensive command — it uses LLM tokens for the main agent and potentially sub-agents. Only run when actively testing the pipeline.

5. ludus run watcher

Poll intercom for ready beads, group by label, route to agents via agent-map.json. Replaces beads-watcher.sh | beads-notify.sh. Dry-run is safe and free (no tokens).

5.1 Dry-run (human output)

ludus run watcher --dry-run

Verify (human)

• Output shows "Beads Watcher"
• WAKE lines list ready beads grouped by label
• "DRY-RUN: would wake" messages for each agent
• Exit code 0

5.2 Dry-run (JSON output)

ludus --json run watcher --dry-run

Verify (JSON)

• Valid JSON with keys: wake_lines, notifications
• wake_lines is an array of "WAKE " strings
• Each notification has agent_id, dry_run: true, bead_ids
• next hints present

5.3 Dry-run with label filter

ludus --json run watcher --dry-run --label dev

Verify (JSON)

• Only notifications for label dev (maps to b4-dev)
• No eng-mgr notifications

5.4 Watcher help

ludus run watcher --help

Verify

• Shows --dry-run, --label, --local, --timeout options
• Description mentions "replaces beads-watcher.sh"

Cost Awareness

Command	Token Cost	Use Case
agent ping	~50 tokens	Liveness check
agent ask	Varies	Direct agent communication
agent task	Varies	Task delegation via main
e2e	High	Full pipeline validation
watcher	0 (dry-run) / Tier 4 (live)	Dispatch ready beads

Agents are billed per message. Ping is the cheapest probe. Prefer ludus info commands for monitoring — they are free. watcher --dry-run is always free — it plans without waking agents.

Edge Cases

Timeout handling

ludus --json run agent ping main --timeout 5 2>&1 || true

Verify

• With a very short timeout (5s), the command may fail gracefully
• Error message mentions timeout
• Exit code 1

Agent not registered

ludus --json run agent ping ghost-agent 2>&1 || true

Verify

• alive is false
• error describes the issue (agent not found)
• No stack trace