Messages that say what they are, and keep their history.
A chat message is text. A status post from an agent is more than that: it has a source, a subject, a state, and a history. Chirp's message protocol lets a producer say so, and Instruments turn those messages into a board you can run your day from.
A typed message that older clients still read.
Chirp Message Protocol 0.1 (org.renkara.chirp.message/0.1) adds an optional structured envelope to an ordinary message. The plain text stays the message body, so every older client keeps working, and Chirp adds a verified protocol member to what the REST API and the WebSocket return.
- Source and subject. Who is reporting, and what about. Together they identify one thing over time.
- Presentation. Required fallback text, plus optional PubMark that clients render richly.
- Lifecycle and severity. A truthful state such as running, succeeded, or failed, with no invented progress percentage.
- A retry-safe key. Sending the exact same message again returns the same message. Reusing the key for different content is rejected with a 409.
- Sealed by Chirp. A producer can leave out the integrity digest, and Chirp computes it. If a producer supplies one, Chirp checks it.
Producers reach it through the REST API, an inbound webhook, the send_message and reply_in_thread MCP tools, and reply_to_agent. Claude Code's hook events use it too. POST /api/v1/protocol/validate checks an envelope without sending anything.
{
"protocol": {
"protocol": "org.renkara.chirp.message/0.1",
"kind": "event",
"source": {
"kind": "integration",
"id": "org.renkara.lectern",
"display_name": "Lectern"
},
"presentation": {
"fallback": "Review requested for Architecture Notes"
},
"subject": {
"kind": "document",
"id": "doc-42",
"label": "Architecture Notes"
},
"delivery": { "dedupe_key": "review:doc-42:revision-7" }
}
}Rich when it can be verified, plain when it cannot.
- Fallback first
- The client shows the signed fallback text at once. It swaps in the rich view only after it validates the projection and its digest. A missing compiler, an error response, unknown semantics, an unsafe link, or a failed digest all leave the fallback on screen.
- Data, not HTML
- PubMark compiles to a JSON tree, and the web client and the SwiftUI apps each map it to their own interface. Nothing evaluates raw HTML, and remote images are blocked by default so a message cannot track who read it.
- Actions that cannot run code
- A message can offer an action only by naming a capability that Chirp itself has registered. It cannot carry JavaScript, an HTTP request, a shell command, or SQL. Unknown actions show but do nothing, and Chirp rechecks who is asking, and whether the message is still current, before it runs anything.
A flight board for runs, decisions, and incidents.
An Instrument is a verified message promoted into a durable, revisioned surface. It is still one message, not a second content system, so its fallback text, rendering, permissions, evidence, and actions all keep one authority.
| Lens | What it shows |
|---|---|
| Needs Me | Current Instruments whose attention applies to you, such as approvals, blocked runs, and owner decisions. |
| Runs | Agent work, builds, audits, deployments, and workflows. |
| Decisions | Comparisons, approvals, and decision records. |
| Incidents | Response timelines, current impact, and runbooks. |
| Artifacts | Code intelligence, reports, releases, and evidence bundles. |
| Knowledge | Living documentation, briefings, and explainers. |
There are five categories (run, decision, incident, artifact, and knowledge), and Needs Me is deliberately not one of them: a decision or an incident can need you without losing what it is. A message that carries actions counts as needing you only if at least one action is registered by Chirp, allowed for you, and inside its activation window. A blocked run can still surface without an action.
Each Instrument picks one layout (status, timeline, comparison, command center, artifact, or document), which organizes the screen around the message without changing what the message says or may do.
An update is a new message, never an edit.
- One series per thing
- Chirp derives a series from the workspace, the source, and the subject, with a domain-separated SHA-256 digest. A deploy that moves from running to succeeded is two revisions of one Instrument.
- Revisions line up
- Revision 1 has no predecessor. Revision N must be N minus 1 plus one and must name the current head. A fork, a skipped revision, or a stale predecessor rejects the whole send.
- History is read-only
- Editing or deleting an indexed revision returns 409. Past revisions render as they were, with their actions switched off. Removing one for retention or privacy is a separate administrative path, and the history shows an explicit gap.
An audit is only as good as its proof.
Instruments carry an audit field, and it is what the producer reported, shown as such. Chirp does not turn a success into a pass.
- Success is not a pass
- A deploy that succeeded is not the same as a deploy that passed an audit. A passed or failed audit needs a proof with a digest, and each completed check needs digest-backed evidence. Incomplete and not-run audits cannot pretend to have one.
- Privacy fails closed
- A redacted view must name its policy and digest. If a renderer lacks a required capability, the view drops back to verified PubMark and then to the fallback. Handling rules can replace notification previews with a generic notice, suppress outbound webhooks, or demand explicit confirmation for every action.
- Attention means a person
- A producer should ask for attention only when a human really must act, and must say why and since when. Attention is a property you can filter on, not a sixth category.
The normative profiles, schemas, and conformance cases live in the PubMark specification repository. Chirp's own docs describe the checks it runs on its side.