communication-protocol通信协议

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.
• INLINECODE1: starts build session, runs OpenClaw turns, stores events.
• INLINECODE2: returns structured events + concise user-facing updates.

Session Inputs (from backend to OpenClaw)

Environment variables passed to each turn:

• - INLINECODE3
• INLINECODE4
• INLINECODE5

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:

CODEBLOCK0

Agent handling rules:

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

Event Contract (canonical)

All events should be represented as:

CODEBLOCK1

INLINECODE10 must be "agent" for agent-originated events.

Supported Event Types

1) assistant.message.created

Use for short, user-facing chat text only.

Payload:

CODEBLOCK2

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:

CODEBLOCK3

3) progress.step.completed

Marks a prior step as complete.

Payload:

CODEBLOCK4

4) status.changed

Major lifecycle transitions only.

Payload:

CODEBLOCK5

Optional on completion/failure:

CODEBLOCK6

5) question.requested

Use when blocked and one answer is required.

Payload:

CODEBLOCK7

6) questions.requested

Use when blocked and multiple answers are needed together.

Payload:

CODEBLOCK8

7) session.completed / session.failed

Terminal events.

Payload:

CODEBLOCK9

INLINECODE20 may include:

CODEBLOCK10

Step Transition Rules (Required)

When moving between steps:

1. 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:

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. 1. Backend creates build + session.started.
2. Agent starts:

1. 3. For each pipeline transition:

1. 4. If blocked:

1. 5. Continue steps after answers.
2. End:

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.