Payload schema
The LLM message role this item renders as.
The model-visible text.
Stable logical identity: a keyed item no request has covered is REPLACED in place by an update with the same key; a covered one appends a new occurrence.
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.
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 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."
},
"key": {
"description": "Stable logical identity: a keyed item no request has covered is REPLACED in place by an update with the same key; a covered one appends a new occurrence.",
"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"
]
}
],
"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."
}
},
"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."
}