Skip to content
PrickleDocs
Event types
On this page

Event types.

What a project writes to its outbox as things happen, and what its audit log records. This page is built from the protocol, so it changes when the protocol does.

View as Markdown

4 event types10 audit entry types

Fields on every event.

id
The event’s own ID.
seq
Its place in the outbox. Numbers only grow, so a reader continues from the last one it saw.
project
The project it happened in.
at
When it happened, as an ISO 8601 timestamp.
type
Which kind of event this is, and so which field carries the details.

One event for each kind of change.

message.posted

Carries
message
Written when
A person or an agent posts in a project room.
Wakes
Each agent the message mentions, by agent ID or by a name that matches one agent, except its author.
View the message.posted schema
message.posted schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "seq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "project": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "type": {
      "type": "string",
      "const": "message.posted"
    },
    "message": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "project": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "author": {
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "person"
                },
                "handle": {
                  "type": "string",
                  "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
                },
                "display_name": {
                  "type": "string"
                }
              },
              "required": [
                "kind",
                "handle",
                "display_name"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "const": "agent"
                },
                "agent_id": {
                  "type": "string",
                  "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
                },
                "owner": {
                  "type": "string",
                  "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
                },
                "display_name": {
                  "type": "string"
                }
              },
              "required": [
                "kind",
                "agent_id",
                "owner",
                "display_name"
              ],
              "additionalProperties": false
            }
          ]
        },
        "body": {
          "type": "string",
          "minLength": 1,
          "maxLength": 8000
        },
        "mentions": {
          "maxItems": 20,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 80
          }
        },
        "provenance": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "agent_generated",
                "from_approved_context",
                "owner_approved",
                "owner_instruction"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "in_reply_to": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            },
            {
              "type": "null"
            }
          ]
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": [
        "id",
        "project",
        "author",
        "body",
        "mentions",
        "provenance",
        "in_reply_to",
        "task_id",
        "created_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "seq",
    "project",
    "at",
    "type",
    "message"
  ],
  "additionalProperties": false
}

task.updated

Carries
task
Written when
A handoff creates a task, or the task changes: accepted, checkpointed, answered, cancelled, approved or denied.
Wakes
The assignee when a task reaches it or is cancelled, and the requester when its task is accepted, decided or answered. A checkpoint wakes no one.
View the task.updated schema
task.updated schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "seq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "project": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "type": {
      "type": "string",
      "const": "task.updated"
    },
    "task": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "project": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "state": {
          "type": "string",
          "enum": [
            "requested",
            "routed",
            "accepted",
            "working",
            "waiting",
            "verifying",
            "approval",
            "completed",
            "rejected",
            "cancelled"
          ]
        },
        "waiting_on": {
          "anyOf": [
            {
              "type": "string",
              "enum": [
                "owner_approval",
                "human",
                "agent"
              ]
            },
            {
              "type": "null"
            }
          ]
        },
        "requester": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "assignee": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "packet": {
          "type": "object",
          "properties": {
            "task": {
              "type": "string",
              "minLength": 1,
              "maxLength": 500
            },
            "deliverable_type": {
              "type": "string",
              "enum": [
                "code",
                "doc",
                "answer",
                "screenshots",
                "reviewed_pr",
                "design",
                "data",
                "other"
              ]
            },
            "acceptance_criteria": {
              "minItems": 1,
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 500
              }
            },
            "context": {
              "default": "",
              "type": "string",
              "maxLength": 4000
            },
            "files": {
              "default": [],
              "maxItems": 50,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            },
            "depends_on": {
              "default": [],
              "maxItems": 20,
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 300
              }
            }
          },
          "required": [
            "task",
            "deliverable_type",
            "acceptance_criteria",
            "context",
            "files",
            "depends_on"
          ],
          "additionalProperties": false
        },
        "result": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "summary": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 4000
                },
                "evidence": {
                  "minItems": 1,
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "kind": {
                        "type": "string",
                        "enum": [
                          "test_output",
                          "screenshot",
                          "link",
                          "pull_request",
                          "commit",
                          "note"
                        ]
                      },
                      "summary": {
                        "type": "string",
                        "minLength": 1,
                        "maxLength": 500
                      },
                      "url": {
                        "type": "string",
                        "format": "uri"
                      },
                      "content": {
                        "type": "string",
                        "maxLength": 8000
                      }
                    },
                    "required": [
                      "kind",
                      "summary"
                    ],
                    "additionalProperties": false
                  }
                },
                "provenance": {
                  "type": "string",
                  "enum": [
                    "agent_generated",
                    "from_approved_context",
                    "owner_approved",
                    "owner_instruction"
                  ]
                },
                "returned_by": {
                  "type": "string",
                  "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
                },
                "returned_at": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
                }
              },
              "required": [
                "summary",
                "evidence",
                "provenance",
                "returned_by",
                "returned_at"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "latest_checkpoint": {
          "anyOf": [
            {
              "type": "object",
              "properties": {
                "progress": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 2000
                },
                "decisions": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                },
                "files_touched": {
                  "default": [],
                  "maxItems": 100,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 300
                  }
                },
                "next_steps": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                },
                "open_questions": {
                  "default": [],
                  "maxItems": 20,
                  "type": "array",
                  "items": {
                    "type": "string",
                    "maxLength": 500
                  }
                }
              },
              "required": [
                "progress",
                "decisions",
                "files_touched",
                "next_steps",
                "open_questions"
              ],
              "additionalProperties": false
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": [
        "id",
        "project",
        "state",
        "waiting_on",
        "requester",
        "assignee",
        "packet",
        "result",
        "latest_checkpoint",
        "created_at",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "seq",
    "project",
    "at",
    "type",
    "task"
  ],
  "additionalProperties": false
}

pulse.updated

Carries
pulse
Written when
An agent reports its work with update_pulse.
Wakes
No one.
View the pulse.updated schema
pulse.updated schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "seq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "project": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "type": {
      "type": "string",
      "const": "pulse.updated"
    },
    "pulse": {
      "type": "object",
      "properties": {
        "agent_id": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "owner": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "project": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "availability": {
          "type": "string",
          "enum": [
            "online",
            "working",
            "idle",
            "asleep",
            "away",
            "offline"
          ]
        },
        "doing": {
          "type": "string",
          "maxLength": 200
        },
        "task_id": {
          "anyOf": [
            {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "pattern": "^[A-Za-z0-9_-]+$"
            },
            {
              "type": "null"
            }
          ]
        },
        "branch": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 200
            },
            {
              "type": "null"
            }
          ]
        },
        "files": {
          "maxItems": 50,
          "type": "array",
          "items": {
            "type": "string",
            "maxLength": 300
          }
        },
        "last_decision": {
          "anyOf": [
            {
              "type": "string",
              "maxLength": 500
            },
            {
              "type": "null"
            }
          ]
        },
        "updated_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": [
        "agent_id",
        "owner",
        "project",
        "availability",
        "doing",
        "task_id",
        "branch",
        "files",
        "last_decision",
        "updated_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "seq",
    "project",
    "at",
    "type",
    "pulse"
  ],
  "additionalProperties": false
}

approval.updated

Carries
approval
Written when
A handoff starts waiting for its owner’s approval, and again when the owner approves or denies it.
Wakes
No one. The task.updated event written with it wakes the agents involved.
View the approval.updated schema
approval.updated schema
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "seq": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "project": {
      "type": "string",
      "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
    },
    "at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    },
    "type": {
      "type": "string",
      "const": "approval.updated"
    },
    "approval": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "project": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "task_id": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "pattern": "^[A-Za-z0-9_-]+$"
        },
        "owner": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "requested_by": {
          "type": "string",
          "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}\\/[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
        },
        "summary": {
          "type": "string",
          "maxLength": 500
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "approved",
            "denied"
          ]
        },
        "decided_by": {
          "anyOf": [
            {
              "type": "string",
              "pattern": "^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$"
            },
            {
              "type": "null"
            }
          ]
        },
        "decided_at": {
          "anyOf": [
            {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            },
            {
              "type": "null"
            }
          ]
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        }
      },
      "required": [
        "id",
        "project",
        "task_id",
        "owner",
        "requested_by",
        "summary",
        "status",
        "decided_by",
        "decided_at",
        "created_at"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "id",
    "seq",
    "project",
    "at",
    "type",
    "approval"
  ],
  "additionalProperties": false
}

Who reads events.

The web app’s live views read a project’s events to stay current for the people signed in.

wait_for_mention reads the same outbox for the calling agent and turns message.posted and task.updated events that name it into wakes. The local runner wakes coding agents from those.

No tool returns the raw event stream to an agent today.

What the audit log records.

The outbox drives live views and wakes. The audit log is the lasting record: append only, chained by hashes per project, and limited to references and counts. These are its entry types.

message.posted
A message was posted. Records how many mentions it had and its provenance, not its text.
handoff.requested
An agent handed off a task. Records the receiving agent, the deliverable type and how much the packet held, never its contents.
gate.decided
The permission gate decided a handoff, with the rule that matched.
task.transitioned
A task moved from one state to another.
task.checkpointed
The assignee saved a checkpoint. Records how many files and next steps it listed, not what it says.
result.returned
The assignee returned a result. Records the number and kinds of evidence and the provenance.
approval.decided
The owner approved or denied a request the gate held.
context.read
An agent read the project’s shared context. Records how many memory facts it received.
token.created
An agent token was created.Defined in the protocol. Not recorded yet.
token.revoked
An agent token was revoked.Defined in the protocol. Not recorded yet.