Payload schema
The LLM message role this item renders as.
The model-visible text.
Typed resources addressed by Markdown-like mention:// links in content.
Processor-authored, bounded resolution metadata for a prior message's mentions.
The section's stable identity — THE addressing mechanism: re-adding a key IS the update. An occurrence no request has sent yet is edited in place (coalesced, free); a sent one appends at the tail of the timeline with `supersedes` stamped by the fold. Existing streams' keyed events already mean exactly this.
Files riding on this item.
MIME type.
Original filename.
Project file-storage path.
Size in bytes.
Signed URL minted at attach time (stored, not re-minted, so history stays deterministic).
Coordinates for retrieving richer source material on demand.
The referenced stream's path.
The referenced event's offset on that stream.
The referenced event's type, when known.
The referenced platform user.
Project file-storage path.
The repo's mount path.
The commit id.
The repo's mount path.
The committed file path at latest HEAD.
Who supplied this item. Trust boundary at prompt time: a developer-role item keeps developer precedence only when platform-authored (no actor) or authored by an agent or its own script; every integration-lane author (slack, telegram, email, github, integration) is DEMOTED to user role — third-party text must not read as instructions.
Which surface the user wrote from.
The authenticated principal who wrote the message — the same identity device enrollments record as ownerId, so a chat-reply push can be addressed to the sender's devices only.
The authoring agent's stream path.
The capability-host execution that produced it.
Which integration supplied it.
The Slack user who wrote the source message.
The Slack bot that wrote the source message.
The Telegram user who wrote the source message.
The Telegram username, when known.
The sender's email address.
The sender's display name.
The GitHub login of the sender.
GitHub's sender classification (User, Bot, ...).
What this item does to the turn loop (ignored on system/assistant items). The interrupt behaviour is the ONLY cancel mechanism: cancellation is a property of new input, never a free-standing command.
On assistant items: offset of the llm-request-requested event this output answers. The reduce IGNORES an assistant item whose request is no longer the open one — that guard is what closes the interrupt-vs-settle race.
Metadata for the structural history rewrite produced by compaction (developer role only): this item replaces every non-system item at or below the barrier.
Replace model-visible history through this stream offset with this item.
Provider-reported usage for the summarization request.
Total input tokens, including cached ones.
Total output tokens, including reasoning ones.
Prompt-cache hits, where the model reports them.
Reasoning/thinking tokens, where the model reports them.
Raw JSON schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"role": {
"type": "string",
"enum": [
"system",
"developer",
"user",
"assistant"
],
"description": "The LLM message role this item renders as."
},
"content": {
"type": "string",
"description": "The model-visible text."
},
"mentions": {
"description": "Typed resources addressed by Markdown-like mention:// links in content.",
"maxItems": 100,
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"maxLength": 8192,
"pattern": "^[A-Za-z0-9][A-Za-z0-9._~%:/-]*$"
},
"type": {
"type": "string",
"const": "repo-file"
},
"repoPath": {
"type": "string",
"const": "/repos/config"
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 4096
}
},
"required": [
"id",
"type",
"repoPath",
"path"
],
"additionalProperties": false
}
},
"mentionResolution": {
"description": "Processor-authored, bounded resolution metadata for a prior message's mentions."
},
"key": {
"description": "The section's stable identity — THE addressing mechanism: re-adding a key IS the update. An occurrence no request has sent yet is edited in place (coalesced, free); a sent one appends at the tail of the timeline with `supersedes` stamped by the fold. Existing streams' keyed events already mean exactly this.",
"type": "string",
"minLength": 1
},
"files": {
"description": "Files riding on this item.",
"type": "array",
"items": {
"type": "object",
"properties": {
"contentType": {
"type": "string",
"description": "MIME type."
},
"filename": {
"type": "string",
"description": "Original filename."
},
"path": {
"type": "string",
"description": "Project file-storage path."
},
"size": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Size in bytes."
},
"url": {
"type": "string",
"description": "Signed URL minted at attach time (stored, not re-minted, so history stays deterministic)."
}
},
"required": [
"contentType",
"filename",
"path",
"size",
"url"
]
}
},
"refs": {
"description": "Coordinates for retrieving richer source material on demand.",
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "event"
},
"streamPath": {
"type": "string",
"description": "The referenced stream's path."
},
"offset": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "The referenced event's offset on that stream."
},
"eventType": {
"description": "The referenced event's type, when known.",
"type": "string"
}
},
"required": [
"type",
"streamPath",
"offset"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "user"
},
"userId": {
"type": "string",
"description": "The referenced platform user."
}
},
"required": [
"type",
"userId"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "file"
},
"path": {
"type": "string",
"description": "Project file-storage path."
}
},
"required": [
"type",
"path"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "git-commit"
},
"repoPath": {
"type": "string",
"description": "The repo's mount path."
},
"commitOid": {
"type": "string",
"description": "The commit id."
}
},
"required": [
"type",
"repoPath",
"commitOid"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "repo-file"
},
"repoPath": {
"type": "string",
"description": "The repo's mount path."
},
"path": {
"type": "string",
"description": "The committed file path at latest HEAD."
}
},
"required": [
"type",
"repoPath",
"path"
]
}
],
"description": "One coordinate for richer source material."
}
},
"actor": {
"description": "Who supplied this item. Trust boundary at prompt time: a developer-role item keeps developer precedence only when platform-authored (no actor) or authored by an agent or its own script; every integration-lane author (slack, telegram, email, github, integration) is DEMOTED to user role — third-party text must not read as instructions.",
"oneOf": [
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "user"
},
"origin": {
"type": "string",
"enum": [
"web",
"mcp"
],
"description": "Which surface the user wrote from."
},
"userId": {
"description": "The authenticated principal who wrote the message — the same identity device enrollments record as ownerId, so a chat-reply push can be addressed to the sender's devices only.",
"type": "string"
}
},
"required": [
"type",
"origin"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "agent"
},
"path": {
"type": "string",
"description": "The authoring agent's stream path."
}
},
"required": [
"type",
"path"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "script"
},
"executionId": {
"type": "string",
"description": "The capability-host execution that produced it."
}
},
"required": [
"type",
"executionId"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "integration"
},
"name": {
"type": "string",
"description": "Which integration supplied it."
}
},
"required": [
"type",
"name"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "slack"
},
"userId": {
"description": "The Slack user who wrote the source message.",
"type": "string"
},
"botName": {
"description": "The Slack bot that wrote the source message.",
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "telegram"
},
"userId": {
"description": "The Telegram user who wrote the source message.",
"type": "string"
},
"username": {
"description": "The Telegram username, when known.",
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "email"
},
"address": {
"description": "The sender's email address.",
"type": "string"
},
"name": {
"description": "The sender's display name.",
"type": "string"
}
},
"required": [
"type"
]
},
{
"type": "object",
"properties": {
"type": {
"type": "string",
"const": "github"
},
"login": {
"description": "The GitHub login of the sender.",
"type": "string"
},
"senderType": {
"description": "GitHub's sender classification (User, Bot, ...).",
"type": "string"
}
},
"required": [
"type"
]
}
]
},
"llmRequestPolicy": {
"default": {
"behaviour": "after-current-request"
},
"description": "What this item does to the turn loop (ignored on system/assistant items). The interrupt behaviour is the ONLY cancel mechanism: cancellation is a property of new input, never a free-standing command.",
"oneOf": [
{
"type": "object",
"properties": {
"behaviour": {
"type": "string",
"const": "dont-trigger-request"
}
},
"required": [
"behaviour"
]
},
{
"type": "object",
"properties": {
"behaviour": {
"type": "string",
"const": "interrupt-current-request"
}
},
"required": [
"behaviour"
]
},
{
"type": "object",
"properties": {
"behaviour": {
"type": "string",
"const": "after-current-request"
}
},
"required": [
"behaviour"
]
}
]
},
"llmRequestOffset": {
"description": "On assistant items: offset of the llm-request-requested event this output answers. The reduce IGNORES an assistant item whose request is no longer the open one — that guard is what closes the interrupt-vs-settle race.",
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"compaction": {
"description": "Metadata for the structural history rewrite produced by compaction (developer role only): this item replaces every non-system item at or below the barrier.",
"type": "object",
"properties": {
"replacesHistoryThrough": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991,
"description": "Replace model-visible history through this stream offset with this item."
},
"usage": {
"description": "Provider-reported usage for the summarization request.",
"type": "object",
"properties": {
"inputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total input tokens, including cached ones."
},
"outputTokens": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991,
"description": "Total output tokens, including reasoning ones."
},
"cachedInputTokens": {
"description": "Prompt-cache hits, where the model reports them.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"reasoningOutputTokens": {
"description": "Reasoning/thinking tokens, where the model reports them.",
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"inputTokens",
"outputTokens"
]
}
},
"required": [
"replacesHistoryThrough"
]
}
},
"required": [
"role",
"content"
],
"additionalProperties": false,
"description": "One model-visible context item. The single source of truth for what the LLM sees."
}