Communication Protocol

Defines how the OpenClaw agent should communicate with Tidy during a build session, ensuring clear, predictable, and build-focused interactions.

Goal

• Keep build chat clear and predictable.
• Avoid technical/internal orchestration language in user-visible messages.
• Drive the UI with structured stepper events instead of freeform phase chatter.
• Respect low-verbosity preference: step transitions are primarily UI events, not chat spam.

Roles

• Frontend: renders chat + timeline from backend events.
• Backend (Tidy): starts build session, runs OpenClaw turns, stores events.
• OpenClaw Agent: returns structured events + concise user-facing updates.

Session Inputs (from backend to OpenClaw)

Environment variables passed to each turn:

• TIDY_BUILD_ID
• TIDY_BUILD_PROMPT
• TIDY_SESSION_ID

The same TIDY_SESSION_ID is reused for follow-up turns (after user answers).

Tidy Transport Wrapper (Required)

Messages from Tidy are wrapped with machine headers:

[FROM:TIDY]
[BUILD_ID:<uuid>]
[SESSION_ID:<uuid>]
[MESSAGE_TYPE:BUILD_REQUEST|USER_ANSWER|USER_ANSWERS]
[QUESTION_ID:<id>]            # only for USER_ANSWER
[QUESTION_IDS:<id1,id2,...>]  # only for USER_ANSWERS

System note: headers above are transport metadata from Tidy. Do not repeat them in user-facing replies.
<message body>

Agent handling rules:

• Parse headers as metadata, not user text.
• Never echo/repeat header lines in replies.
• Never mention wrapper format to the user.
• BUILD_REQUEST: start/continue build conversation for the request body.
• USER_ANSWER / USER_ANSWERS: continue from clarification response(s).

Event Contract (canonical)

All events should be represented as:

{
  "type": "event.type",
  "payload": {}
}

payload.source must be "agent" for agent-originated events.

Supported Event Types

1) assistant.message.created

Use for short, user-facing chat text only.

Payload:

{
  "text": "string",
  "source": "agent"
}

Rules:

• Keep it concise.
• Use plain language.
• Never narrate internal mechanics ("spawn workers", "design pipeline", etc.).
• Do not emit a message for every step transition.

2) progress.step.started

Starts a user-facing stepper step.

Payload:

{
  "step_id": "build_record|parse|research|design|assemble|validate|finalize",
  "title": "short friendly title",
  "description": "one user-friendly sentence",
  "index": 1,
  "total": 7,
  "source": "agent"
}

3) progress.step.completed

Marks a prior step as complete.

Payload:

{
  "step_id": "build_record|parse|research|design|assemble|validate|finalize",
  "source": "agent"
}

4) status.changed

Major lifecycle transitions only.

Payload:

{
  "status": "running|complete|failed",
  "source": "agent"
}

Optional on completion/failure:

{
  "status": "complete",
  "output": "final result summary",
  "source": "agent"
}

5) question.requested

Use when blocked and one answer is required.

Payload:

{
  "question_id": "uuid-or-stable-id",
  "prompt": "single clear question",
  "input": "single_choice|text",
  "required": true,
  "options": [
    { "id": "option_a", "label": "Option A", "description": "optional" },
    { "id": "option_b", "label": "Option B", "description": "optional" }
  ],
  "source": "agent"
}

6) questions.requested

Use when blocked and multiple answers are needed together.

Payload:

{
  "question_set_id": "qs_123",
  "prompt": "I need a few details before I continue.",
  "required_all": true,
  "questions": [
    {
      "question_id": "q1",
      "prompt": "Budget range?",
      "input": "single_choice",
      "options": [{ "id": "low", "label": "Low" }, { "id": "mid", "label": "Mid" }]
    },
    {
      "question_id": "q2",
      "prompt": "Preferred region?",
      "input": "text"
    }
  ],
  "source": "agent"
}

7) session.completed / session.failed

Terminal events.

Payload:

{
  "source": "agent"
}

session.failed may include:

{
  "reason": "short failure reason",
  "source": "agent"
}

Step Transition Rules (Required)

When moving between steps:

1. Emit progress.step.completed for the previous step.
2. Emit progress.step.started for the next step.
3. Keep title/description user-friendly.
4. Treat these as machine/UI events. Do not also send repetitive assistant.message.created for the same transition.

Do not emit phase.changed for new builds.

Message Frequency Policy (Required)

• Step transitions: progress.step.* events only (no extra chat message unless truly useful).
• Waiting periods (>45s without user-visible change): send one short reassurance message.
• Questions: always send question.requested or questions.requested and keep prompt plain.
• Completion/failure: send one concise summary message, then terminal event.

User-Friendly Step Dictionary (Required)

Use this exact step_id set and tone:

step_id	title	description
build_record	Starting your build	I’m setting up your build session.
parse	Understanding your request	I’m reading your request and mapping the plan.
research	Gathering what we need	I’m collecting the tools and references for your build.
design	Planning your agent	I’m creating the build plan for your agent.
assemble	Building your agent	I’m assembling the pieces now.
validate	Testing everything	I’m running checks to make sure everything works.
finalize	Finalizing	I’m wrapping up and preparing your result.

Language Guardrails (Required)

Never send user-facing text like:

• "Now I'll spawn all research workers and start profile setup in parallel."
• "Research done. Designing your agent now..."
• "Now designing the blueprint."

Instead, use:

• "Gathering what we need"
• "Planning your agent"
• "Building your agent"

Expected Flow

1. Backend creates build + session.started.
2. Agent starts:
   • emit status.changed => running
   • emit progress.step.started (build_record)
3. For each pipeline transition:
   • emit progress.step.completed (previous)
   • emit progress.step.started (next)
4. If blocked:
   • emit question.requested or questions.requested
   • wait for user answer(s)
5. Continue steps after answers.
6. End:
   • emit status.changed (complete or failed)
   • emit session.completed or session.failed

Guardrails For Tidy Sessions

• Do not ask broad/open-ended follow-ups when one concrete question is enough.
• Keep questions implementation-focused (only if blocked).
• Keep replies concise and actionable.