CLowl v0.2 Specification

Version 0.2 · Draft · MIT License · Oscar Sterling Agency

1. Overview

CLowl is a structured communication language for AI agent-to-agent messaging. It defines a minimal JSON schema with typed performatives, message metadata, and context referencing that runs on top of any transport (MCP, A2A, HTTP, WebSocket, stdio, etc.).

CLowl is not a transport protocol. It defines what goes inside the envelope.

Minimal

Full spec fits in a ~180-token system prompt injection

LLM-native

Any model can parse and generate CLowl after reading the system prompt

Transport-agnostic

Works over MCP, A2A, HTTP, WebSocket, file system, or stdin/stdout

Human-debuggable

Every message has a deterministic English translation

Traceable

Trace IDs link tasks across multiple agents end-to-end

Auditable

Message IDs enable deduplication and conversation reconstruction

2. Message Schema

Every CLowl message is a JSON object with 8 required fields and several optional ones.

json

{
  "clowl": "0.2",
  "mid": "<uuidv7>",
  "ts": 1709078400,
  "tid": "<trace_id>",
  "pid": "<parent_mid_or_null>",
  "p": "<performative>",
  "from": "<agent_id>",
  "to": "<agent_id_or_array>",
  "cid": "<conversation_id>",
  "body": {
    "t": "<free_form_task_type>",
    "d": {}
  },
  "ctx": {
    "ref": "<path_or_url_or_null>",
    "inline": "<fallback_string_max_2000_chars_or_null>",
    "hash": "<sha256_or_null>"
  },
  "auth": "<optional_token>",
  "det": false
}

Field	Type	Required	Description
`clowl`	string	Yes	Protocol version. Must be "0.2" for this spec.
`mid`	string	Yes	Unique message ID. Use UUIDv7 (timestamp-prefixed).
`ts`	integer	Yes	Unix epoch timestamp (seconds) when message was created.
`tid`	string	No	Trace ID. Links a task across multiple agents and hops.
`pid`	string\|null	No	Parent message ID. Null for root messages.
`p`	string	Yes	Performative code. See Performatives section.
`from`	string	Yes	Sender agent identifier.
`to`	string\|array	Yes	Recipient agent ID, "*" for broadcast, or array for multicast.
`cid`	string	Yes	Conversation ID. Groups all related messages into a thread.
`body.t`	string	Yes	Free-form task type string (e.g., "search", "draft").
`body.d`	object	Yes	Task-specific data. Schema varies by task.
`ctx`	object	No	Context reference object.
`auth`	string	No	Optional auth token for sender identity verification.
`det`	boolean	No	Determinism flag. true = reproducible result.

3. Performatives

Ten performatives define the intent of every message. Every CLowl message has exactly one p field.

Code	Name	Direction	Meaning
`REQ`	Request	Sender → Receiver	"Do this thing." Initiates a task.
`INF`	Inform	Sender → Receiver	"Here is information." No action expected.
`ACK`	Acknowledge	Receiver → Sender	"Got it, proceeding." Confirms receipt.
`ERR`	Error	Receiver → Sender	"Failed. Here's why." Structured error with code.
`DLGT`	Delegate	Agent → Agent	"Passing this to someone better suited."
`DONE`	Complete	Receiver → Sender	"Finished. Here is the result."
`CNCL`	Cancel	Sender → Receiver	"Abort this task."
`QRY`	Query	Any → Any	"What's the status?" or "Give me info without acting."
`PROG`	Progress	Receiver → Sender	"Here's a progress update on the running task."
`CAPS`	Capabilities	Agent → "*"	"Here's what I can do." Sent on connection.

Delegation (DLGT)

DLGT messages must include a delegation_mode field in body.d.

Mode	Meaning
`transfer`	Full handoff. Original agent is done, delegate takes full ownership.
`fork`	Parallel work. Original agent continues independently.
`assist`	Helper role. Original agent remains accountable; delegate supports.

json

{
  "clowl": "0.2",
  "mid": "m004",
  "ts": 1709078461,
  "tid": "t001",
  "pid": "m003",
  "p": "DLGT",
  "from": "oscar",
  "to": "muse",
  "cid": "pipe001",
  "body": {
    "t": "analyze",
    "d": {
      "delegation_mode": "transfer",
      "target": "content angle",
      "type": "competitive"
    }
  },
  "ctx": { "ref": "research/mcp-vs-a2a.md", "inline": null, "hash": null }
}

Capability Advertisement (CAPS)

Agents send CAPS on connection to advertise what they support.

json

{
  "clowl": "0.2",
  "mid": "caps-001",
  "ts": 1709078400,
  "p": "CAPS",
  "from": "radar",
  "to": "*",
  "cid": "system",
  "body": {
    "t": "capabilities",
    "d": {
      "supports": ["search:web", "search:repo", "analyze:trend"],
      "clowl": "0.2"
    }
  }
}

4. Task Types

The body.t field is free-form. Any string is valid. No fixed taxonomy is enforced.

This is intentional: agents advertise their capabilities via CAPS. Callers use whatever task name matches what the receiving agent supports.

Advisory examples (not exhaustive, not required):

searchwritereadanalyzedraftreviewdeploynotifyauditsummarizetranslatescheduleapproveescalateexecutedebugintegratepredictcapabilities

5. Context Referencing

The ctx field enables token-efficient context sharing between agents.

json

"ctx": {
  "ref": "<file_path_or_url_or_null>",
  "inline": "<fallback_string_max_2000_chars_or_null>",
  "hash": "<sha256_of_ref_content_or_null>"
}

Sub-field	Description
`ref`	Path or URL to shared context. Token-efficient — preferred mode.
`inline`	Inline fallback content. Max 2000 characters. Use when ref is unreachable.
`hash`	SHA-256 of the content at ref. Enables immutability verification.

Rules:

ref mode is preferred. Token-efficient.
inline is the degraded path — monitoring should flag its usage.
If ref is provided with a hash, receivers should verify content integrity before use.
If ref is unreachable and inline is null, receivers respond with ERR code E003.
Context is immutable once referenced. To update, create a new reference.

6. Error Codes

Errors use the ERR performative. The body.d structure for errors:

json

{
  "t": "error",
  "d": {
    "code": "E001",
    "msg": "Human-readable error description",
    "retry": true
  }
}

Code	Category	Meaning	Retryable
`E001`	Parse	Malformed CLowl message	Yes (fix and resend)
`E002`	Auth	Sender not authorized	No
`E003`	Context	Referenced context not found or inaccessible	Yes (provide valid ctx)
`E004`	Capacity	Agent rate-limited or at capacity	Yes (after delay)
`E005`	Task	Unknown task type (agent doesn't support it)	No
`E006`	Timeout	Task exceeded time limit	Yes
`E007`	Dependency	Required upstream result missing	Yes
`E008`	Validation	Task data failed validation	Yes (fix body.d)
`E009`	Internal	Unexpected internal error	Yes
`E010`	Delegation	No suitable agent to delegate to	No
`E011`	Conflict	Conflicting concurrent operation	Yes
`E012`	Budget	Token or cost budget exceeded	No
`E013`	Cancelled	Task was aborted via CNCL	No
`E014`	Version	Incompatible CLowl versions	No
`E015`	Cycle	Delegation cycle detected	No
`E016`	Security	Security violation (beyond E002)	No

7. System Prompt Injection

Copy this into any LLM's system prompt to enable CLowl communication. Optimized for minimal token usage (~180 tokens) while maintaining reliable JSON generation.

text

You speak CLowl v0.1 for agent-to-agent messages. Format:
{"cl":"0.1","mid":"<msg_id>","p":"<P>","from":"<id>","to":"<id>","cid":"<thread>","body":{"t":"<task>","d":{}},"ctx":"<ref>"}

p (Performatives): REQ=request, INF=info, ACK=proceeding, ERR=failed (needs code+msg in d), DLGT=delegate, DONE=completed (result in d).
t (Tasks): search, write, read, analyze, draft, review, deploy, notify, audit, summarize, translate, schedule, approve, escalate. Custom: x-prefix.
ctx: path/URL/hash. NEVER inline large context; reference it.
Error d: {"code":"E001-E016","msg":"...","retry":bool}

Rules: Output RAW JSON only. No markdown. No extra text. Keep 'd' payload flat. All fields required. Use natural language ONLY for human-facing output.

Architecture Note

This prompt covers the Semantic Layer only. In production, your runtime should wrap LLM output with coordination metadata (message IDs, timestamps, trace IDs, auth tokens). Don't make the LLM responsible for generating distributed systems metadata.

8. Versioning

Agents send CAPS on connection. The CAPS message includes "clowl": "0.2" in body.d. Receivers check the clowl field of incoming messages. Mismatch → ERR code E014.

Version string format: MAJOR.MINOR. v0.x is experimental. v1.0 is the first stable release.