candy-code.v1.schema.json

{
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "$id": "urn:sugarcraft:candy-code:protocol:v1",
    "title": "candy-code.v1",
    "description": "The candy-code server protocol: JSON-RPC 2.0 over the `candy-code.v1` WebSocket subprotocol. `methods` holds each request's params and result; `events` holds the data of each `event` notification, whose params are `$defs/EventEnvelope`. Generated by scripts/gen-protocol-schema.php from src/Protocol — do not edit.",
    "protocol": 1,
    "$defs": {
        "Admission": {
            "type": "object",
            "properties": {
                "admitted": {
                    "enum": [
                        "started",
                        "queued",
                        "steered",
                        "pending",
                        "handled"
                    ]
                },
                "turnId": {
                    "type": "string"
                },
                "messageId": {
                    "type": "string"
                },
                "steerId": {
                    "type": "string"
                },
                "queuePosition": {
                    "type": "integer",
                    "minimum": 1
                },
                "queueId": {
                    "type": "string",
                    "maxLength": 32
                }
            },
            "required": [
                "admitted"
            ]
        },
        "BackgroundSession": {
            "type": "object",
            "properties": {
                "bgId": {
                    "type": "string"
                },
                "name": {
                    "type": "string"
                },
                "task": {
                    "type": "string"
                },
                "status": {
                    "enum": [
                        "pending",
                        "running",
                        "streaming",
                        "stalled",
                        "completed",
                        "failed",
                        "stopped",
                        "timed_out"
                    ]
                },
                "agent": {
                    "type": "string"
                },
                "model": {
                    "type": "string"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "workingDirectory": {
                    "type": "string"
                },
                "createdAt": {
                    "type": "string"
                },
                "completedAt": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "tokensUsed": {
                    "type": "integer",
                    "minimum": 0
                },
                "costUsd": {
                    "type": "number",
                    "minimum": 0
                },
                "spendUnpriced": {
                    "type": "boolean",
                    "description": "True only when the session's model had no price on file; absent means the cost is an exact bill."
                },
                "error": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "outputBytes": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "bg.output reads the output itself, from an offset."
                },
                "forkedSessionId": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "The stored session a /fork session continues; null for /bg."
                },
                "adopted": {
                    "type": "boolean",
                    "description": "Re-adopted at boot from an earlier server or TUI."
                }
            },
            "required": [
                "bgId",
                "name",
                "task",
                "status",
                "createdAt",
                "outputBytes",
                "adopted"
            ],
            "description": "A background (/bg) session; never its output."
        },
        "BackgroundShell": {
            "type": "object",
            "properties": {
                "shellId": {
                    "type": "string"
                },
                "label": {
                    "type": "string"
                },
                "state": {
                    "enum": [
                        "running",
                        "finished",
                        "unknown"
                    ]
                },
                "exitCode": {
                    "type": [
                        "integer",
                        "null"
                    ]
                },
                "exitNote": {
                    "type": [
                        "string",
                        "null"
                    ],
                    "description": "Set when the shell settled without an ordinary exit code — its output sink hit the cap, the lifetime wall stopped it, or the exit record was unreadable."
                },
                "expired": {
                    "type": "boolean",
                    "description": "True when the lifetime wall stopped the shell."
                },
                "ageSeconds": {
                    "type": "number",
                    "minimum": 0
                },
                "interactive": {
                    "type": "boolean",
                    "description": "True when the row is an interactive (pty) shell — the tail pane and `shells.input` door apply; plain rows keep the read-only tail."
                }
            },
            "required": [
                "shellId",
                "label",
                "state",
                "expired",
                "ageSeconds"
            ],
            "description": "A background shell row from the launch's shell table, as the Shell tool started it; never its output — `shells.output` reads that."
        },
        "ContextSources": {
            "type": "object",
            "properties": {
                "instructionFiles": {
                    "type": [
                        "array",
                        "null"
                    ],
                    "items": {
                        "type": "object",
                        "properties": {
                            "path": {
                                "type": "string",
                                "maxLength": 4096
                            },
                            "bytes": {
                                "type": "integer",
                                "minimum": 0
                            },
                            "tier": {
                                "enum": [
                                    "project",
                                    "personal"
                                ]
                            }
                        },
                        "required": [
                            "path",
                            "bytes",
                            "tier"
                        ]
                    },
                    "description": "The documents the system prompt splices — names and sizes, bodies never (on the roadmap); null when this server could not price them."
                },
                "memorySections": {
                    "type": "array",
                    "items": {
                        "$ref": "#/$defs/MemoryEntry"
                    },
                    "description": "Every note of both stores across all scopes, the `memory.list` grouping rule (repo rows first)."
                },
                "skills": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "tier": {
                                "type": "string",
                                "description": "Who put the file there — a SkillOrigin value, not the format."
                            },
                            "enabled": {
                                "type": "boolean",
                                "description": "False when the `disabledSkills` setting withheld it."
                            }
                        },
                        "required": [
                            "name",
                            "tier",
                            "enabled"
                        ]
                    },
                    "description": "The skills registry, as the prompt listing sees it."
                },
                "mcp": {
                    "type": "object",
                    "properties": {
                        "status": {
                            "type": "string",
                            "description": "The config-level verdict of the read-never-run census (`Bootstrap::mcpServerInventory`): trusted, refused, or absent. Nothing is started to answer this."
                        },
                        "error": {
                            "type": [
                                "string",
                                "null"
                            ]
                        },
                        "skipped": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            }
                        },
                        "userStatus": {
                            "type": "string",
                            "description": "The USER tier's verdict from the same census — trusted, absent, or disabled; no containment or trust-list verdicts apply to the operator's own file."
                        },
                        "userError": {
                            "type": [
                                "string",
                                "null"
                            ],
                            "description": "Why the user file could not be read, in the same sentence the project tier uses; null when there was nothing to report."
                        },
                        "userSkipped": {
                            "type": "array",
                            "items": {
                                "type": "string"
                            },
                            "description": "Malformed entries the user file declared, mirrored from the project tier's `skipped`."
                        },
                        "servers": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "transport": {
                                        "type": "string"
                                    },
                                    "trust": {
                                        "enum": [
                                            "trusted"
                                        ],
                                        "description": "Rows exist only while the file is trusted; the http entry's URL stays off the wire (the `server.hello` media restraint, restated)."
                                    },
                                    "tier": {
                                        "enum": [
                                            "project",
                                            "user"
                                        ],
                                        "description": "Which file declared the row. A name the project tier declares never appears as a user row — the census shadows it, mirroring the launch's precedence."
                                    },
                                    "liveness": {
                                        "type": [
                                            "object",
                                            "null"
                                        ],
                                        "properties": {
                                            "up": {
                                                "type": [
                                                    "boolean",
                                                    "null"
                                                ],
                                                "description": "Whether the started server reports its handshake complete; null only for a transport the client cannot answer for."
                                            },
                                            "tools": {
                                                "type": "integer",
                                                "minimum": 0,
                                                "description": "Tool count the client last saw — a remembered figure, never a fresh exchange."
                                            }
                                        },
                                        "required": [
                                            "up",
                                            "tools"
                                        ],
                                        "description": "Read from the launch memo only (`Bootstrap::mcpLivenessSnapshot`), NEVER a probe — a process holding no client answers null on every row; a declared server that was never started stays null rather than being launched to be asked."
                                    }
                                },
                                "required": [
                                    "name",
                                    "transport",
                                    "trust",
                                    "tier",
                                    "liveness"
                                ]
                            }
                        }
                    },
                    "required": [
                        "status",
                        "error",
                        "skipped",
                        "userStatus",
                        "userError",
                        "userSkipped",
                        "servers"
                    ],
                    "description": "The `.mcp.json` declarations as `candy-code mcp list` reads them — both tiers, minus per-entry details."
                },
                "untrusted": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "properties": {
                            "path": {
                                "type": "string",
                                "maxLength": 4096
                            },
                            "reason": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "path",
                            "reason"
                        ]
                    },
                    "description": "Instruction paths the loader refused and why."
                },
                "trusts": {
                    "type": "array",
                    "items": {
                        "$ref": "#/$defs/TrustPrompt"
                    },
                    "description": "This root's trust prompts — the launch census' pending targets, measured here is where they are DISCOVERED: each one mints a row (once per root and target) and server-scopes it as `permission.asked`; the list also re-states rows this process already settled (a session grant that expires at next launch, a rejection that must not nag), so an empty list means nothing of this project is pending a grant."
                },
                "breakdown": {
                    "type": "object",
                    "properties": {
                        "window": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "sections": {
                            "type": [
                                "array",
                                "null"
                            ],
                            "items": {
                                "type": "object",
                                "properties": {
                                    "label": {
                                        "type": "string"
                                    },
                                    "stability": {
                                        "type": "string"
                                    },
                                    "sections": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "bytes": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "tokens": {
                                        "type": "integer",
                                        "minimum": 0
                                    }
                                },
                                "required": [
                                    "label",
                                    "stability",
                                    "sections",
                                    "bytes",
                                    "tokens"
                                ]
                            }
                        },
                        "toolCount": {
                            "type": [
                                "integer",
                                "null"
                            ],
                            "minimum": 0
                        },
                        "toolTokens": {
                            "type": [
                                "integer",
                                "null"
                            ],
                            "minimum": 0
                        },
                        "historyTokens": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "historyMessages": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "uiOnlyRows": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "largest": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "index": {
                                        "type": "integer",
                                        "minimum": 1
                                    },
                                    "role": {
                                        "type": "string"
                                    },
                                    "tokens": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "preview": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "index",
                                    "role",
                                    "tokens",
                                    "preview"
                                ]
                            }
                        },
                        "lastCache": {
                            "type": [
                                "object",
                                "null"
                            ],
                            "properties": {
                                "read": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "prompt": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "required": [
                                "read",
                                "prompt"
                            ]
                        },
                        "sessionCache": {
                            "type": [
                                "object",
                                "null"
                            ],
                            "properties": {
                                "read": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "prompt": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "replies": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "required": [
                                "read",
                                "prompt",
                                "replies"
                            ]
                        },
                        "pruning": {
                            "type": [
                                "object",
                                "null"
                            ],
                            "properties": {
                                "mode": {
                                    "type": "string"
                                },
                                "sessionMode": {
                                    "type": "boolean"
                                },
                                "outputs": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "outputTokens": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "files": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "contextRows": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "contextRowTokens": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "block": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "properties": {
                                        "id": {
                                            "type": "integer",
                                            "minimum": 0
                                        },
                                        "compressed": {
                                            "type": "integer",
                                            "minimum": 0
                                        },
                                        "summary": {
                                            "type": "integer",
                                            "minimum": 0
                                        }
                                    },
                                    "required": [
                                        "id",
                                        "compressed",
                                        "summary"
                                    ]
                                },
                                "rows": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "ref": {
                                                "type": [
                                                    "integer",
                                                    "null"
                                                ],
                                                "minimum": 0
                                            },
                                            "tool": {
                                                "type": "string"
                                            },
                                            "reason": {
                                                "type": "string"
                                            },
                                            "by": {
                                                "type": "string"
                                            },
                                            "tokens": {
                                                "type": "integer",
                                                "minimum": 0
                                            }
                                        },
                                        "required": [
                                            "tool",
                                            "reason",
                                            "by",
                                            "tokens"
                                        ]
                                    }
                                }
                            },
                            "required": [
                                "mode",
                                "sessionMode",
                                "outputs",
                                "outputTokens",
                                "contextRows",
                                "contextRowTokens",
                                "rows"
                            ]
                        },
                        "cacheBreaks": {
                            "type": [
                                "object",
                                "null"
                            ],
                            "properties": {
                                "breaks": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "last": {
                                    "type": [
                                        "object",
                                        "null"
                                    ],
                                    "properties": {
                                        "from": {
                                            "type": "integer",
                                            "minimum": 0
                                        },
                                        "to": {
                                            "type": "integer",
                                            "minimum": 0
                                        }
                                    },
                                    "required": [
                                        "from",
                                        "to"
                                    ]
                                }
                            },
                            "required": [
                                "breaks"
                            ]
                        },
                        "categories": {
                            "type": "array",
                            "items": {
                                "type": "object",
                                "properties": {
                                    "key": {
                                        "type": "string",
                                        "description": "The {@see \\SugarCraft\\Code\\Context\\ContextCategory} case value — stable vocabulary; `label` is the translated display name."
                                    },
                                    "label": {
                                        "type": "string"
                                    },
                                    "tokens": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "minimum": 0,
                                        "description": "Estimated tokens billed to this category, null when not measured — never a fabricated zero."
                                    },
                                    "share": {
                                        "type": [
                                            "integer",
                                            "null"
                                        ],
                                        "minimum": 0,
                                        "description": "`tokens` as a whole percent of `window`; null exactly when `tokens` is."
                                    },
                                    "sub": {
                                        "type": "array",
                                        "items": {
                                            "type": "object",
                                            "properties": {
                                                "label": {
                                                    "type": "string",
                                                    "description": "Server name, document path, or `#<index> <role>` for a message row."
                                                },
                                                "tokens": {
                                                    "type": [
                                                        "integer",
                                                        "null"
                                                    ],
                                                    "minimum": 0
                                                },
                                                "bytes": {
                                                    "type": [
                                                        "integer",
                                                        "null"
                                                    ],
                                                    "minimum": 0,
                                                    "description": "Set instead of `tokens` for instruction documents — priced by size, bodies never."
                                                },
                                                "personal": {
                                                    "type": "boolean",
                                                    "description": "True when the document came from the personal tier."
                                                },
                                                "note": {
                                                    "type": [
                                                        "string",
                                                        "null"
                                                    ],
                                                    "description": "Replaces the figures with the reason there are none (the never-sent MCP instructions row)."
                                                }
                                            },
                                            "required": [
                                                "label",
                                                "tokens",
                                                "bytes",
                                                "personal",
                                                "note"
                                            ]
                                        }
                                    }
                                },
                                "required": [
                                    "key",
                                    "label",
                                    "tokens",
                                    "share",
                                    "sub"
                                ]
                            },
                            "description": "The `/context` `By category` block (roadmap P-CTX.a / P-CTX.f): every measured token attributed by owner. Summing law — all rows except `autocompact-buffer` and `free-space` equal `window` less the reservation and what is left; content + buffer + free-space is the window."
                        },
                        "buffer": {
                            "type": [
                                "integer",
                                "null"
                            ],
                            "minimum": 0,
                            "description": "The autocompact reservation — room between where background compaction fires and the window end; 0 when compaction is off, null when this session reports no compaction config."
                        },
                        "mcpServers": {
                            "type": [
                                "array",
                                "null"
                            ],
                            "items": {
                                "type": "object",
                                "properties": {
                                    "name": {
                                        "type": "string"
                                    },
                                    "count": {
                                        "type": "integer",
                                        "minimum": 0
                                    },
                                    "tokens": {
                                        "type": "integer",
                                        "minimum": 0
                                    }
                                },
                                "required": [
                                    "name",
                                    "count",
                                    "tokens"
                                ]
                            },
                            "description": "The `mcp__<server>__*` bridges grouped per server — the MCP half of `toolTokens`, measured in the same single pass; null when the tool list is unknown."
                        }
                    },
                    "required": [
                        "window",
                        "sections",
                        "toolCount",
                        "toolTokens",
                        "historyTokens",
                        "historyMessages",
                        "uiOnlyRows",
                        "largest",
                        "lastCache",
                        "sessionCache"
                    ],
                    "description": "The `/context` figures ({@see \\SugarCraft\\Code\\Context\\ContextBreakdown}) — same measurement, same single writer."
                }
            },
            "required": [
                "instructionFiles",
                "memorySections",
                "skills",
                "mcp",
                "untrusted",
                "breakdown"
            ],
            "description": "What the session's context is built from — structure for the panel `/context` prints as text."
        },
        "Error": {
            "type": "object",
            "properties": {
                "code": {
                    "type": "integer"
                },
                "message": {
                    "type": "string"
                },
                "data": {
                    "type": "object",
                    "properties": {
                        "kind": {
                            "type": "string"
                        },
                        "retryable": {
                            "type": "boolean"
                        },
                        "retryAfterMs": {
                            "type": "integer",
                            "minimum": 0
                        }
                    },
                    "required": [
                        "kind"
                    ]
                }
            },
            "required": [
                "code",
                "message",
                "data"
            ]
        },
        "EventEnvelope": {
            "type": "object",
            "properties": {
                "sessionId": {
                    "oneOf": [
                        {
                            "$ref": "#/$defs/SessionId"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "seq": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Durable session events only; gap-free per session."
                },
                "type": {
                    "type": "string"
                },
                "ts": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Milliseconds since the epoch."
                },
                "turnId": {
                    "type": "string"
                },
                "durable": {
                    "type": "boolean"
                },
                "data": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "root": {
                    "type": "string",
                    "description": "Set by the serve gateway on an event relayed from another project root's workspace host (roadmap O-7)."
                }
            },
            "required": [
                "sessionId",
                "type",
                "ts",
                "durable",
                "data"
            ]
        },
        "MediaRef": {
            "type": "object",
            "properties": {
                "artifactId": {
                    "type": "string",
                    "description": "MediaStore artifact id: the stored name minus its final extension."
                },
                "kind": {
                    "enum": [
                        "image",
                        "video",
                        "html"
                    ]
                },
                "path": {
                    "type": "string",
                    "description": "Server-local path to the stored file — a reference, never the bytes (Appendix C-7)."
                },
                "bytes": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Size as the tool delivered it; 0 when the event carries only a path."
                },
                "mime": {
                    "type": "string",
                    "description": "Media type inferred from the stored extension."
                },
                "infotextDigest": {
                    "type": "string",
                    "description": "SHA-256 of the PNG infotext embedded in the artifact, when one was readable."
                },
                "indexLabel": {
                    "type": "string",
                    "description": "Batch slot label, when a multi-artifact result names its rows."
                }
            },
            "required": [
                "artifactId",
                "kind",
                "path",
                "bytes",
                "mime"
            ],
            "description": "A media artifact a finished tool produced — identity and path only; bytes never ride the journal (Appendix C-7)."
        },
        "MemoryEntry": {
            "type": "object",
            "properties": {
                "id": {
                    "type": "string"
                },
                "type": {
                    "type": "string"
                },
                "tags": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "scope": {
                    "enum": [
                        "user",
                        "project",
                        "agent"
                    ]
                },
                "content": {
                    "type": "string"
                },
                "createdAt": {
                    "type": "string"
                },
                "modifiedAt": {
                    "type": "string"
                },
                "source": {
                    "enum": [
                        "home",
                        "repo"
                    ],
                    "description": "Which store holds the note: the repository's .candy-code/memory/ or the home directory."
                }
            },
            "required": [
                "id",
                "scope",
                "content",
                "source"
            ]
        },
        "PendingAsk": {
            "type": "object",
            "properties": {
                "askId": {
                    "type": "string",
                    "maxLength": 16
                },
                "toolCallId": {
                    "type": "string"
                },
                "tool": {
                    "type": "string"
                },
                "arguments": {
                    "type": "object",
                    "additionalProperties": {}
                },
                "reason": {
                    "type": "string"
                },
                "source": {
                    "type": "string",
                    "description": "`gate`, `hook:<names>`, or `tool:<name>` for a question the call puts itself (`AskUser`, `PlanExit`)"
                },
                "mode": {
                    "type": "string"
                },
                "options": {
                    "type": "array",
                    "items": {
                        "enum": [
                            "once",
                            "always",
                            "reject"
                        ]
                    }
                },
                "choices": {
                    "type": "array",
                    "items": {
                        "type": "string",
                        "maxLength": 200
                    },
                    "maxItems": 6,
                    "description": "AskUser's own choices, in order, the first recommended; answer one with `permission.respond` reply `once` and the choice as the note. Absent for every other ask."
                },
                "alwaysScope": {
                    "type": "object",
                    "additionalProperties": {
                        "type": "string"
                    }
                },
                "diff": {
                    "type": "string",
                    "description": "The server-computed unified diff of the proposed call, confined to the session root and capped at 32 KiB (beyond it, an omitted note naming the change size, never silence); absent when the call has no previewable outcome. Has real file line numbers, unlike a client-minted snippet diff."
                },
                "origin": {
                    "type": "object",
                    "properties": {
                        "agentId": {
                            "type": "string"
                        },
                        "agentName": {
                            "type": "string"
                        },
                        "parentCallId": {
                            "type": "string"
                        }
                    },
                    "required": [
                        "agentId"
                    ],
                    "description": "The delegated run that asked, when a sub-agent's question was relayed; absent for the turn's own."
                }
            },
            "required": [
                "askId",
                "toolCallId",
                "tool",
                "arguments",
                "options"
            ]
        },
        "PermissionMode": {
            "enum": [
                "default",
                "accept-edits",
                "plan",
                "auto",
                "dont-ask",
                "bypass-permissions"
            ]
        },
        "QueueEntry": {
            "type": "object",
            "properties": {
                "queueId": {
                    "type": "string",
                    "maxLength": 32
                },
                "text": {
                    "type": "string"
                },
                "position": {
                    "type": "integer",
                    "minimum": 1
                }
            },
            "required": [
                "queueId",
                "text",
                "position"
            ]
        },
        "SessionId": {
            "type": "string",
            "maxLength": 128,
            "description": "A session id: letters, digits, \".\", \"_\" and \"-\"."
        },
        "SessionSnapshot": {
            "type": "object",
            "properties": {
                "sessionId": {
                    "$ref": "#/$defs/SessionId"
                },
                "status": {
                    "enum": [
                        "idle",
                        "busy",
                        "waiting_permission"
                    ]
                },
                "turnId": {
                    "type": "string"
                },
                "messages": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "additionalProperties": {}
                    },
                    "description": "Transcript rows, as they are saved; a paged snapshot carries only its window."
                },
                "totalMessages": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Paged snapshots: every row the session holds."
                },
                "oldestIndex": {
                    "type": "integer",
                    "minimum": 0,
                    "description": "Paged snapshots: index of the first carried row in the full history; appending never shifts it."
                },
                "hasMoreOlder": {
                    "type": "boolean",
                    "description": "Paged snapshots: older rows exist; ask session.get with beforeIndex = oldestIndex."
                },
                "queued": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                },
                "spentUsd": {
                    "type": "number",
                    "minimum": 0
                },
                "spendUnpriced": {
                    "type": "boolean",
                    "description": "True only when the session billed a model with no price on file; spentUsd is then a lower bound. Absent means priced."
                },
                "lastSeq": {
                    "type": "integer",
                    "minimum": 0
                },
                "permissionMode": {
                    "oneOf": [
                        {
                            "$ref": "#/$defs/PermissionMode"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "pendingAsks": {
                    "type": "array",
                    "items": {
                        "$ref": "#/$defs/PendingAsk"
                    }
                },
                "queue": {
                    "type": "array",
                    "items": {
                        "$ref": "#/$defs/QueueEntry"
                    }
                },
                "subagents": {
                    "type": "array",
                    "items": {
                        "type": "object",
                        "additionalProperties": {}
                    }
                },
                "subagentsDropped": {
                    "type": "integer",
                    "minimum": 1,
                    "description": "Subagent rows dropped by the display cap while this session ran; named only when at least one row was dropped. Absent means nothing was trimmed."
                }
            },
            "required": [
                "sessionId",
                "status",
                "messages",
                "lastSeq",
                "pendingAsks",
                "queue"
            ]
        },
        "SessionSummary": {
            "type": "object",
            "properties": {
                "id": {
                    "$ref": "#/$defs/SessionId"
                },
                "name": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "provider": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "model": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "agent": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "kind": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "parentId": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "createdAt": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "updatedAt": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "turns": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "preview": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "snippet": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "branch": {
                    "type": [
                        "string",
                        "null"
                    ]
                },
                "pr": {
                    "type": [
                        "object",
                        "null"
                    ],
                    "properties": {
                        "number": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "state": {
                            "type": "string"
                        },
                        "url": {
                            "type": "string"
                        },
                        "checks": {
                            "enum": [
                                "pass",
                                "fail",
                                "pending"
                            ]
                        }
                    },
                    "required": [
                        "number",
                        "state",
                        "url",
                        "checks"
                    ]
                },
                "open": {
                    "type": "boolean"
                },
                "status": {
                    "enum": [
                        "closed",
                        "idle",
                        "busy",
                        "waiting_permission"
                    ]
                },
                "permissionMode": {
                    "oneOf": [
                        {
                            "$ref": "#/$defs/PermissionMode"
                        },
                        {
                            "type": "null"
                        }
                    ]
                },
                "spentUsd": {
                    "type": [
                        "number",
                        "null"
                    ],
                    "minimum": 0
                },
                "spendUnpriced": {
                    "type": "boolean"
                },
                "archived": {
                    "type": "boolean"
                },
                "ephemeral": {
                    "type": "boolean"
                },
                "root": {
                    "type": "string",
                    "description": "Set by the serve gateway on a session another project root's workspace host answered for (roadmap O-7)."
                }
            },
            "required": [
                "id",
                "open",
                "status"
            ]
        },
        "Subscription": {
            "oneOf": [
                {
                    "type": "object",
                    "properties": {
                        "reset": {
                            "enum": [
                                true
                            ]
                        },
                        "snapshot": {
                            "$ref": "#/$defs/SessionSnapshot"
                        },
                        "throughSeq": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "pendingAsks": {
                            "type": "array",
                            "items": {
                                "$ref": "#/$defs/PendingAsk"
                            }
                        }
                    },
                    "required": [
                        "reset",
                        "snapshot",
                        "throughSeq",
                        "pendingAsks"
                    ],
                    "description": "Caught up from a snapshot; live from throughSeq."
                },
                {
                    "type": "object",
                    "properties": {
                        "fromSeq": {
                            "type": "integer",
                            "minimum": 1
                        },
                        "throughSeq": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "pendingAsks": {
                            "type": "array",
                            "items": {
                                "$ref": "#/$defs/PendingAsk"
                            }
                        }
                    },
                    "required": [
                        "fromSeq",
                        "throughSeq",
                        "pendingAsks"
                    ],
                    "description": "Replaying from fromSeq through throughSeq, then live."
                }
            ]
        },
        "TrustPrompt": {
            "type": "object",
            "properties": {
                "askId": {
                    "type": "string",
                    "maxLength": 16
                },
                "kind": {
                    "enum": [
                        "trust"
                    ],
                    "description": "The marker that makes a `permission.asked` payload a project-trust prompt — answered by `context.trust`; `permission.respond` never sees these (they are not in the turn's question registry)."
                },
                "target": {
                    "enum": [
                        "mcp",
                        "mcp-pin",
                        "hooks",
                        "commands",
                        "settings"
                    ],
                    "description": "Which grant door this prompt is about — the project `.mcp.json` census verdict (`mcp`), a drifted MCP command needing re-approval (`mcp-pin`, which answers through the same list), lifecycle hooks, `` !`cmd` `` command shell forms, or the project settings layer. A grant lands the root in that door's `trustedProject*` list (see the census in `Bootstrap::pendingProjectTrust`)."
                },
                "root": {
                    "type": "string",
                    "maxLength": 4096,
                    "description": "The project root the prompt is about — the exact string the grant writes into that door's trusted list."
                },
                "reason": {
                    "type": "string",
                    "description": "Why the prompt was put, for the panel line."
                },
                "status": {
                    "enum": [
                        "asked",
                        "granted",
                        "rejected"
                    ],
                    "description": "`asked` while open; one answer settles it for the process (the once-per-(root, target) law — the other targets' prompts stay open beside it)."
                },
                "persisted": {
                    "type": "boolean",
                    "description": "True when the answer wrote the user-tier trust list; a session grant or a refusal leaves it false."
                }
            },
            "required": [
                "askId",
                "kind",
                "target",
                "root",
                "status"
            ]
        },
        "Usage": {
            "type": "object",
            "properties": {
                "totalTokens": {
                    "type": "integer",
                    "minimum": 0
                },
                "inputTokens": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "outputTokens": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "cacheReadTokens": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "cacheCreationTokens": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "reasoningTokens": {
                    "type": [
                        "integer",
                        "null"
                    ],
                    "minimum": 0
                },
                "costUsd": {
                    "type": "number",
                    "minimum": 0
                },
                "unpricedModel": {
                    "type": [
                        "string",
                        "null"
                    ]
                }
            }
        }
    },
    "methods": {
        "agents.control": {
            "description": "Cancel, pause, resume or background a delegated run.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "agentId": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "A delegated run's id, as its `subagent.*` events name it."
                    },
                    "verb": {
                        "enum": [
                            "cancel",
                            "pause",
                            "resume",
                            "background"
                        ]
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 65536,
                        "description": "What a resumed FINISHED run is told; the default asks it to continue."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "agentId",
                    "verb"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "agentId": {
                        "type": "string"
                    },
                    "status": {
                        "enum": [
                            "queued",
                            "resuming"
                        ],
                        "description": "queued: in the running run's mailbox, read at its next step; resuming: a finished run is being continued."
                    },
                    "msgId": {
                        "type": "string"
                    }
                },
                "required": [
                    "agentId",
                    "status"
                ]
            }
        },
        "agents.list": {
            "description": "The agents a turn can delegate to.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                },
                                "model": {
                                    "type": "string"
                                },
                                "provider": {
                                    "type": "string"
                                },
                                "permissionMode": {
                                    "$ref": "#/$defs/PermissionMode"
                                },
                                "active": {
                                    "type": "boolean"
                                },
                                "mode": {
                                    "enum": [
                                        "primary",
                                        "subagent",
                                        "all"
                                    ],
                                    "description": "The preset's declaring frontmatter `mode:`; absent or unreadable answers `all`."
                                },
                                "color": {
                                    "type": "string",
                                    "maxLength": 7,
                                    "description": "The preset's `color:` vocabulary resolved through the same AgentColor law the TUI strip follows, as a `#rrggbb` hex against the server's default theme; omitted when the preset names no colour or names one that does not resolve legibly."
                                }
                            },
                            "required": [
                                "name"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "agents.message": {
            "description": "Message a delegated run: into its mailbox while it runs, as a follow-up once it finished.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "agentId": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "A delegated run's id, as its `subagent.*` events name it."
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 65536
                    },
                    "mode": {
                        "enum": [
                            "steer",
                            "interrupt"
                        ],
                        "description": "steer (the default): delivered at the run's next step boundary, the current step's tool calls all running first; interrupt: delivered there too, but the step's sequential calls that have not started are skipped, so the run reads the message before doing more work on a plan it may change. Omitted on a FINISHED run — its follow-up conversation carries no step to steer."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "agentId",
                    "text"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "agentId": {
                        "type": "string"
                    },
                    "status": {
                        "enum": [
                            "queued",
                            "resuming"
                        ],
                        "description": "queued: in the running run's mailbox, read at its next step; resuming: a finished run is being continued."
                    },
                    "msgId": {
                        "type": "string"
                    }
                },
                "required": [
                    "agentId",
                    "status"
                ]
            }
        },
        "agents.subtree": {
            "description": "The sub-agents a session's turns have delegated to, with their latest activity.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": {},
                            "description": "A delegated run's latest `subagent.*` event data, from the session's log and the live feed."
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "agents.transcript": {
            "description": "A delegated run's own transcript, read from a byte offset.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "agentId": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "A delegated run's id, as its `subagent.*` events name it."
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1024,
                        "maximum": 65536
                    }
                },
                "required": [
                    "sessionId",
                    "agentId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "agentId": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Where the next page starts: just past the last whole line read."
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "t": {
                                    "enum": [
                                        "user",
                                        "assistant",
                                        "tool_call",
                                        "tool_result",
                                        "thinking",
                                        "inbox",
                                        "status"
                                    ]
                                },
                                "ts": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "text": {
                                    "type": "string"
                                },
                                "callId": {
                                    "type": "string"
                                },
                                "tool": {
                                    "type": "string"
                                },
                                "args": {
                                    "type": "object",
                                    "additionalProperties": {}
                                },
                                "ok": {
                                    "type": "boolean"
                                },
                                "content": {
                                    "type": "string"
                                },
                                "truncated": {
                                    "type": "boolean"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "outcome": {
                                    "type": "string"
                                },
                                "error": {
                                    "type": "string"
                                },
                                "from": {
                                    "type": "string"
                                },
                                "mode": {
                                    "type": "string"
                                },
                                "msgId": {
                                    "type": "string"
                                },
                                "step": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "required": [
                                "t"
                            ]
                        }
                    },
                    "more": {
                        "type": "boolean"
                    },
                    "finished": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "agentId",
                    "offset",
                    "items",
                    "more",
                    "finished"
                ]
            }
        },
        "audio.status": {
            "description": "A transcription job's state and text, from its ledger.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "jobId": {
                        "type": "string",
                        "maxLength": 64
                    }
                },
                "required": [
                    "sessionId",
                    "jobId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "state": {
                        "enum": [
                            "running",
                            "done",
                            "failed"
                        ]
                    },
                    "text": {
                        "type": "string"
                    },
                    "error": {
                        "type": "string",
                        "maxLength": 2048
                    }
                },
                "required": [
                    "state"
                ]
            }
        },
        "audio.transcribe": {
            "description": "Transcribe a base64 audio take through the configured voice endpoint; answers with its job id.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "audioBase64": {
                        "type": "string",
                        "maxLength": 11184812,
                        "description": "Base64 of the recorded take; the decode is capped at 8 MiB of audio bytes, and the inbound WS frame ceiling (ServerConfig::MAX_CLIENT_FRAME_BYTES) already refuses a larger body before dispatch."
                    },
                    "mime": {
                        "enum": [
                            "audio/webm",
                            "audio/ogg",
                            "audio/mp4"
                        ]
                    },
                    "language": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "audioBase64",
                    "mime"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "jobId": {
                        "type": "string",
                        "maxLength": 64
                    }
                },
                "required": [
                    "jobId"
                ]
            }
        },
        "bg.inject": {
            "description": "Send a settled background session's result into a session as a prompt.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "bgId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "delivery": {
                        "enum": [
                            "queue",
                            "steer",
                            "interrupt"
                        ]
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "bgId",
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string"
                    },
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "admitted": {
                        "enum": [
                            "started",
                            "queued",
                            "steered",
                            "pending",
                            "handled"
                        ]
                    },
                    "turnId": {
                        "type": "string"
                    },
                    "messageId": {
                        "type": "string"
                    },
                    "steerId": {
                        "type": "string"
                    },
                    "queuePosition": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "queueId": {
                        "type": "string",
                        "maxLength": 32
                    }
                },
                "required": [
                    "bgId",
                    "sessionId",
                    "admitted"
                ]
            }
        },
        "bg.list": {
            "description": "The background sessions this server supervises, running and settled.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/BackgroundSession"
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "bg.output": {
            "description": "A background session's output from an offset.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1
                    }
                },
                "required": [
                    "bgId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "text": {
                        "type": "string"
                    },
                    "total": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "status": {
                        "type": "string"
                    }
                },
                "required": [
                    "bgId",
                    "offset",
                    "text",
                    "total",
                    "status"
                ]
            }
        },
        "bg.spawn": {
            "description": "Start a background session on a task, as /bg does.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "task": {
                        "type": "string",
                        "maxLength": 1048576
                    },
                    "agent": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "task"
                ]
            },
            "result": {
                "$ref": "#/$defs/BackgroundSession"
            }
        },
        "bg.stop": {
            "description": "Stop a background session.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "bgId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string"
                    },
                    "outcome": {
                        "type": "string"
                    }
                },
                "required": [
                    "bgId",
                    "outcome"
                ]
            }
        },
        "client.viewing": {
            "description": "Say which sessions this client shows, and which is in front.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionIds": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/SessionId"
                        },
                        "maxItems": 50
                    },
                    "foreground": {
                        "oneOf": [
                            {
                                "$ref": "#/$defs/SessionId"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "narrate": {
                        "type": "boolean",
                        "description": "Narrate every followed session that is not in front, instead of streaming it."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "narrated": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/SessionId"
                        },
                        "description": "The followed sessions this client now hears as narration."
                    }
                },
                "required": [
                    "narrated"
                ]
            }
        },
        "command.exec": {
            "description": "Run a slash command in a session (command files, and the built-ins that run headless).",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "args": {
                        "type": "string",
                        "maxLength": 65536
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "name"
                ]
            },
            "result": {
                "oneOf": [
                    {
                        "$ref": "#/$defs/Admission",
                        "description": "A command file: admitted like session.send, plus empty `rows` and `effects`."
                    },
                    {
                        "type": "object",
                        "properties": {
                            "rows": {
                                "type": "array",
                                "items": {
                                    "type": "object",
                                    "properties": {
                                        "role": {
                                            "type": "string"
                                        },
                                        "content": {
                                            "type": "string"
                                        },
                                        "uiOnly": {
                                            "type": "boolean"
                                        }
                                    },
                                    "required": [
                                        "role",
                                        "content",
                                        "uiOnly"
                                    ]
                                }
                            },
                            "effects": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            }
                        },
                        "required": [
                            "rows",
                            "effects"
                        ],
                        "additionalProperties": false,
                        "description": "A built-in run on the server: the rows it appended and the kinds of the effects it applied."
                    }
                ]
            }
        },
        "command.list": {
            "description": "The slash commands a session knows, and where each runs.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                },
                                "argumentHint": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "source": {
                                    "enum": [
                                        "builtin",
                                        "file",
                                        "mcp",
                                        "skill"
                                    ]
                                },
                                "runsIn": {
                                    "enum": [
                                        "server",
                                        "client"
                                    ]
                                }
                            },
                            "required": [
                                "name",
                                "source",
                                "runsIn"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "context.instructionWrite": {
            "description": "Write one instruction document the session already reads — replace it by spelling content, or append raw bytes by spelling append (exactly one). The jail is the listing itself: path must equal a context.sources instructionFiles row, or \"personal\" for your own ~/.candy-code/AGENTS.md. A replace whose expectBytes no longer matches the file on disk refuses instruction_changed; a document past the loader's size cap refuses instruction_too_large; a path that now resolves through a symlink outside its jail refuses instruction_symlink. A landed write announces context.changed (reason \"instructions\") so the panel re-measures.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "path": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "A path context.sources listed for this session (an instructionFiles row, spelled exactly), or the sentinel `personal` for your own ~/.candy-code/AGENTS.md — the jail is the listing, and `personal` resolves server-side so a first quick-add works before the file exists."
                    },
                    "content": {
                        "type": "string",
                        "maxLength": 61440,
                        "description": "The full replacement text (the loader's per-document size cap; an instruction document larger than the prompt would ever read back is refused `instruction_too_large`). Exactly one of `content` / `append` must be spelled (`instruction_mode`)."
                    },
                    "append": {
                        "type": "string",
                        "maxLength": 61440,
                        "description": "Raw bytes appended under a lock instead of replacing — the web Composer spells the TUI quick-add line (`- note\\n`) through this. The result must still fit the cap."
                    },
                    "expectBytes": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Conflict latch: the byte count the editor measured. A different count on disk now refuses `instruction_changed` — the same law the memory note save follows — so two surfaces cannot silently overwrite each other."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "path"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "The resolved file actually written."
                    },
                    "bytes": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "The file's byte count after the write."
                    },
                    "mode": {
                        "enum": [
                            "replace",
                            "append"
                        ]
                    }
                },
                "required": [
                    "path",
                    "bytes",
                    "mode"
                ]
            }
        },
        "context.sources": {
            "description": "What the session's context is built from: instruction files, memory notes, skills, declared MCP servers, refused paths, the token breakdown, and this root's pending project-trust prompts.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/ContextSources"
            }
        },
        "context.trust": {
            "description": "Answer one project-trust prompt (permission.asked with kind \"trust\") by its askId: grant or reject; a user-tier remember writes the answering prompt's target list (trustedProjectMcp for an mcp or mcp-pin row, the matching trustedProject* key for the others) in your own config, a project-tier one is refused.",
            "scope": "approve",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "askId": {
                        "type": "string",
                        "maxLength": 16,
                        "description": "The trust prompt's id, as permission.asked (kind \"trust\") carried it — one answer settles that prompt's target only; the root's other prompts stay open."
                    },
                    "decision": {
                        "enum": [
                            "grant",
                            "reject"
                        ]
                    },
                    "remember": {
                        "enum": [
                            "session",
                            "user",
                            "project"
                        ],
                        "description": "`user` writes the root into your own config under the answered prompt's target list — `trustedProjectMcp` for an `mcp` or `mcp-pin` row, the matching `trustedProject*` key for the others (effective next launch, like the TUI grant) — and refuses `trust_write_failed`, leaving the prompt open, when that write does not land; `session` — or omitted — settles for this server only; `project` is refused: a project cannot grant itself trust (the permission.respond posture)."
                    }
                },
                "required": [
                    "sessionId",
                    "askId",
                    "decision"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "askId": {
                        "type": "string",
                        "maxLength": 16
                    },
                    "status": {
                        "enum": [
                            "granted",
                            "rejected"
                        ]
                    },
                    "persisted": {
                        "type": "boolean",
                        "description": "True only when the user-tier write landed."
                    }
                },
                "required": [
                    "askId",
                    "status",
                    "persisted"
                ]
            }
        },
        "files.changed": {
            "description": "The workspace's changed and untracked files.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "path": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "from": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                }
                            },
                            "required": [
                                "path",
                                "status"
                            ]
                        }
                    },
                    "truncated": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "items",
                    "truncated"
                ]
            }
        },
        "files.diff": {
            "description": "The workspace's uncommitted changes to tracked files, as a unified diff.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "ref": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "Git revision to diff against; defaults to HEAD. Rejected together with `checkpoint`."
                    },
                    "checkpoint": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Which checkpoint base to diff against, counted the way `/diff n` counts: 1 is the most recent captured base. Needs `sessionId`; values beyond the last base settle on the oldest."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "ref": {
                        "type": "string",
                        "description": "The base actually used: a git revision, or `checkpoint:<index>` for a checkpoint diff."
                    },
                    "diff": {
                        "type": "string"
                    },
                    "truncated": {
                        "type": "boolean"
                    },
                    "checkpoints": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "How many checkpoint bases exist for the session; 0 when no `sessionId` was named or the server has no session store."
                    },
                    "omittedLines": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Patch lines dropped by the checkpoint diff bound; always 0 on the git path."
                    }
                },
                "required": [
                    "ref",
                    "diff",
                    "truncated",
                    "checkpoints",
                    "omittedLines"
                ]
            }
        },
        "files.read": {
            "description": "A file under the project root, read-only and size-capped.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1
                    }
                },
                "required": [
                    "path"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string"
                    },
                    "size": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "binary": {
                        "type": "boolean"
                    },
                    "content": {
                        "type": "string"
                    },
                    "truncated": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "path",
                    "size",
                    "offset",
                    "binary",
                    "content",
                    "truncated"
                ]
            }
        },
        "fs.listDirs": {
            "description": "The child directories (names only, never files) of a directory under the browse root; needs serve --allow-dir-browse.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "path": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "Absolute, `~`-relative, or relative to the browse root; omitted = the browse root."
                    },
                    "showHidden": {
                        "type": "boolean",
                        "description": "Also list dot-directories."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "root": {
                        "type": "string",
                        "description": "The browse root."
                    },
                    "path": {
                        "type": "string",
                        "description": "The listed directory, resolved."
                    },
                    "parent": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "Its parent; null at the browse root."
                    },
                    "entries": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "path": {
                                    "type": "string"
                                },
                                "project": {
                                    "type": "boolean",
                                    "description": "Holds .git, composer.json, package.json or .candy-code."
                                },
                                "readable": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "name",
                                "path",
                                "project",
                                "readable"
                            ],
                            "additionalProperties": false
                        }
                    },
                    "truncated": {
                        "type": "boolean"
                    },
                    "readable": {
                        "type": "boolean",
                        "description": "False when the directory itself could not be read (entries is then empty)."
                    },
                    "project": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "root",
                    "path",
                    "parent",
                    "entries",
                    "truncated",
                    "readable",
                    "project"
                ],
                "additionalProperties": false
            }
        },
        "fs.search": {
            "description": "Workspace file names ranked against a partial (the web composer @-mention popup); jailed to the project root.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "The partial typed after `@`; empty lists the front of the project."
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 100,
                        "description": "Rows to return, best-ranked first; capped at 100."
                    },
                    "showHidden": {
                        "type": "boolean",
                        "description": "Consider dot-files in the non-git fallback walk (a git listing is whatever git tracks, hidden included)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "root": {
                        "type": "string",
                        "description": "The workspace root the listing is jailed to."
                    },
                    "matches": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "description": "Workspace-relative file paths, ranked; insert one after `@`."
                    },
                    "truncated": {
                        "type": "boolean",
                        "description": "False when the whole ranked list fit in `limit`."
                    }
                },
                "required": [
                    "root",
                    "matches",
                    "truncated"
                ],
                "additionalProperties": false
            }
        },
        "generate.status": {
            "description": "A generation job's state, progress and artifact refs, from its ledger.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "jobId": {
                        "type": "string",
                        "maxLength": 64
                    }
                },
                "required": [
                    "sessionId",
                    "jobId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "state": {
                        "enum": [
                            "queued",
                            "running",
                            "done",
                            "failed",
                            "cancelled"
                        ]
                    },
                    "progress01": {
                        "type": "number",
                        "minimum": 0
                    },
                    "etaSeconds": {
                        "type": "number",
                        "minimum": 0
                    },
                    "error": {
                        "type": "string",
                        "maxLength": 2048
                    },
                    "artifacts": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/MediaRef"
                        },
                        "maxItems": 32
                    }
                },
                "required": [
                    "state",
                    "progress01"
                ]
            }
        },
        "generate.submit": {
            "description": "Start an image or video generation; answers with its job id.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "kind": {
                        "enum": [
                            "image",
                            "video"
                        ]
                    },
                    "prompt": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "What to render, self-contained: style, subject, framing. Required, non-empty"
                    },
                    "negative_prompt": {
                        "type": "string",
                        "maxLength": 2048,
                        "description": "What to steer away from, in the same comma-clause style"
                    },
                    "width": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Image width in pixels (server default applies)"
                    },
                    "height": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Image height in pixels (server default applies)"
                    },
                    "steps": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Sampling steps — more is slower, past a point indistinguishable"
                    },
                    "cfg_scale": {
                        "type": "number",
                        "minimum": 0,
                        "description": "Prompt adherence; high values burn in artefacts"
                    },
                    "seed": {
                        "type": "integer",
                        "minimum": -1,
                        "maximum": 4294967295,
                        "description": "Exact seed to reproduce a prior image, or -1 for a fresh draw"
                    },
                    "sampler_name": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "Sampler as the server names it (Euler a, DPM++ 2M Karras, ...)"
                    },
                    "scheduler": {
                        "type": "string",
                        "maxLength": 128,
                        "description": "Scheduler as the server names it"
                    },
                    "batch_size": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Images per request"
                    },
                    "n_iter": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Repeat requests; narrows the watchdog window on long renders"
                    },
                    "save_to_disk": {
                        "type": "boolean",
                        "description": "Also ask the server to write its own copy into its output directory; the tool always saves its copy regardless"
                    },
                    "num_frames": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "duration_seconds": {
                        "type": "number",
                        "minimum": 0
                    },
                    "fps": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "cfg": {
                        "type": "number",
                        "minimum": 0
                    },
                    "cfg2": {
                        "type": "number",
                        "minimum": 0
                    },
                    "motion": {
                        "type": "number",
                        "minimum": 0
                    },
                    "first_frame_image": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "prompt"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "jobId": {
                        "type": "string",
                        "maxLength": 64
                    }
                },
                "required": [
                    "jobId"
                ]
            }
        },
        "mcp.resources": {
            "description": "The launch-frozen MCP resource rows of the session root, without starting any server.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "status": {
                        "enum": [
                            "started",
                            "not-started"
                        ]
                    },
                    "servers": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "server": {
                                    "type": "string",
                                    "maxLength": 200
                                },
                                "resources": {
                                    "type": "array",
                                    "items": {
                                        "type": "object",
                                        "properties": {
                                            "uri": {
                                                "type": "string",
                                                "maxLength": 512
                                            },
                                            "name": {
                                                "type": "string",
                                                "maxLength": 200
                                            },
                                            "mimeType": {
                                                "type": [
                                                    "string",
                                                    "null"
                                                ],
                                                "maxLength": 128
                                            },
                                            "description": {
                                                "type": [
                                                    "string",
                                                    "null"
                                                ],
                                                "maxLength": 400
                                            }
                                        },
                                        "required": [
                                            "uri",
                                            "name"
                                        ]
                                    }
                                }
                            },
                            "required": [
                                "server",
                                "resources"
                            ]
                        }
                    }
                },
                "required": [
                    "status",
                    "servers"
                ]
            }
        },
        "media.fetch": {
            "description": "A stored media artifact's bytes, in base64 slices.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "artifactId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "path": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 3096576
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "artifactId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "bytes": {
                        "type": "string"
                    },
                    "totalBytes": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "eof": {
                        "type": "boolean"
                    },
                    "mime": {
                        "type": "string",
                        "maxLength": 128
                    }
                },
                "required": [
                    "artifactId",
                    "offset",
                    "bytes",
                    "totalBytes",
                    "eof"
                ]
            }
        },
        "memory.add": {
            "description": "Add a note, routed like `/memory add`: a project note goes to the repository store when the tree can host one.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "content": {
                        "type": "string",
                        "maxLength": 65536,
                        "description": "Empty text and project notes over the store bound (ProjectMemoryWriter::MAX_CONTENT_BYTES, setting memory.projectNoteMaxBytes) are refused as invalid_params."
                    },
                    "scope": {
                        "enum": [
                            "user",
                            "project",
                            "agent"
                        ]
                    },
                    "tags": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 32
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "content"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "source": {
                        "enum": [
                            "home",
                            "repo"
                        ]
                    },
                    "fellBackToHome": {
                        "type": "boolean",
                        "description": "True when a project note could not land in the repository store and went to the home directory instead (never silent)."
                    }
                },
                "required": [
                    "id",
                    "source"
                ]
            }
        },
        "memory.delete": {
            "description": "Delete a note from the store that owns the id.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "id"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "deleted": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "deleted"
                ]
            }
        },
        "memory.edit": {
            "description": "Replace a note's text in the store that owns the id.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "content": {
                        "type": "string",
                        "maxLength": 65536
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "id",
                    "content"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    }
                },
                "required": [
                    "id"
                ]
            }
        },
        "memory.list": {
            "description": "The notes of one memory scope, from both stores, each badged with its source.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "scope": {
                        "enum": [
                            "user",
                            "project",
                            "agent"
                        ]
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/MemoryEntry"
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "memory.log": {
            "description": "The home store's commit history, newest first — the revisions memory.undo names.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 200,
                        "description": "Newest revisions to list (default memory.log's own default). Like /memory log, this commits pending changes first so the list ends at what is on disk now."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "sha": {
                                    "type": "string"
                                },
                                "shortSha": {
                                    "type": "string"
                                },
                                "committedAt": {
                                    "type": "string",
                                    "description": "ISO-8601 (DATE_ATOM) commit time."
                                },
                                "subject": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "sha",
                                "shortSha",
                                "committedAt",
                                "subject"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "memory.search": {
            "description": "Notes matching a query, best first, across every scope and both stores.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "maxLength": 1024
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 500
                    }
                },
                "required": [
                    "query"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/MemoryEntry"
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "memory.undo": {
            "description": "Restore the home store to an earlier revision (by default the state before its latest commit), recorded as a new commit.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "revision": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "Hex commit id as memory.log lists; omitted means the state before the newest commit."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "restored": {
                        "type": "string",
                        "description": "The revision the store was restored to."
                    },
                    "commit": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "New commit id, or null when the restored tree equalled the current one."
                    }
                },
                "required": [
                    "restored"
                ]
            }
        },
        "permission.audit": {
            "description": "Recent tool-call decisions from this user's redacted audit log tail; a bounded read, every session unless one is named.",
            "scope": "approve",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 200,
                        "description": "Rows wanted, newest last; the server caps the read at 200."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "rows": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "time": {
                                    "type": "string",
                                    "maxLength": 19
                                },
                                "session": {
                                    "type": "string"
                                },
                                "tool": {
                                    "type": "string"
                                },
                                "verdict": {
                                    "enum": [
                                        "allow",
                                        "deny",
                                        "withheld"
                                    ]
                                },
                                "kind": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "maxLength": 512
                                },
                                "reason": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                }
                            },
                            "required": [
                                "time",
                                "session",
                                "tool",
                                "verdict"
                            ]
                        },
                        "maxItems": 200
                    },
                    "unreadable": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "rows",
                    "unreadable"
                ]
            }
        },
        "permission.forget": {
            "description": "Remove one saved permission rule from the user config, addressed by its pattern or by its 1-based saved index.",
            "scope": "approve",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "pattern": {
                        "type": "string",
                        "maxLength": 512
                    },
                    "index": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "The 1-based number the saved list shows; exactly one of pattern or index."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "removed": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "pattern": {
                                    "type": "string"
                                },
                                "action": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "pattern",
                                "action"
                            ]
                        }
                    },
                    "path": {
                        "type": "string"
                    }
                },
                "required": [
                    "removed",
                    "path"
                ]
            }
        },
        "permission.pending": {
            "description": "The questions still open, for one session or all open sessions.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/PendingAsk",
                            "description": "Each also carries its sessionId."
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "permission.respond": {
            "description": "Answer an open permission question; the first answer wins.",
            "scope": "approve",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "askId": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "reply": {
                        "enum": [
                            "once",
                            "always",
                            "reject"
                        ]
                    },
                    "note": {
                        "type": "string",
                        "maxLength": 2048
                    },
                    "cascade": {
                        "type": "boolean"
                    },
                    "remember": {
                        "enum": [
                            "session",
                            "project",
                            "user"
                        ]
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "askId",
                    "reply"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "applied": {
                        "type": "boolean"
                    },
                    "askId": {
                        "type": "string"
                    },
                    "reply": {
                        "oneOf": [
                            {
                                "enum": [
                                    "once",
                                    "always",
                                    "reject"
                                ]
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "cascaded": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "saved": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 2048,
                        "description": "With remember \"user\" on a hosted question: the notice naming where the answer's patterns were saved (or why they were not); null when the question had nothing generalisable to persist."
                    }
                },
                "required": [
                    "applied",
                    "askId",
                    "cascaded"
                ]
            }
        },
        "permission.rules": {
            "description": "The effective permission mode and rules, read-only; saved user-tier rows carry their tier and 1-based saved index.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "mode": {
                        "oneOf": [
                            {
                                "$ref": "#/$defs/PermissionMode"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "modeSource": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "rules": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "pattern": {
                                    "type": "string"
                                },
                                "action": {
                                    "type": "string"
                                },
                                "tier": {
                                    "enum": [
                                        "user",
                                        "config"
                                    ],
                                    "description": "`user` for a rule the user saved through `p` / `remember: \"user\"` (numbered by savedIndex, the same count permission.forget and `/permissions saved` address by); `config` for every other configured row."
                                },
                                "savedIndex": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ],
                                    "minimum": 1
                                }
                            },
                            "required": [
                                "pattern",
                                "action",
                                "tier"
                            ]
                        }
                    },
                    "sessionGrants": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "mode",
                    "rules",
                    "sessionGrants"
                ]
            }
        },
        "push.subscribe": {
            "description": "Store this browser's push endpoint so the server can notify it when a question is waiting or a turn finished while no client follows the session. The endpoint must be an https URL at a known push service (FCM, Mozilla, Apple, Microsoft); anything else is refused and nothing is stored. Keys arrive as the browser reports them (p256dh: base64url P-256 point, auth: base64url 16 octets). name opts the row into carrying the session title in the payload — WITHOUT it every notification stays redacted generic text.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "endpoint": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "The PushManager endpoint URL. https, default port, no credentials, host on the push-service allowlist (FCM, Mozilla, Apple, Microsoft) — an endpoint outside it is refused before anything is stored."
                    },
                    "keys": {
                        "type": "object",
                        "properties": {
                            "p256dh": {
                                "type": "string",
                                "maxLength": 256,
                                "description": "base64url of the browser's uncompressed P-256 subscription public point (65 octets)."
                            },
                            "auth": {
                                "type": "string",
                                "maxLength": 64,
                                "description": "base64url of the 16-octet subscription auth secret."
                            }
                        },
                        "required": [
                            "p256dh",
                            "auth"
                        ]
                    },
                    "name": {
                        "type": "boolean",
                        "description": "Opt this row into carrying the session title in the payload. Omitted or false: every notification stays redacted generic text (the default)."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "endpoint",
                    "keys"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "subscribed": {
                        "type": "boolean",
                        "description": "True only once the row is on disk."
                    },
                    "keyHash": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "sha256(endpoint), hex — the store's row key, so the raw endpoint never travels back as an identifier."
                    }
                },
                "required": [
                    "subscribed",
                    "keyHash"
                ]
            }
        },
        "push.unsubscribe": {
            "description": "Drop the stored row for this push endpoint, when this client's principal class owns it; an unknown or foreign-owned endpoint answers false.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "endpoint": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "The endpoint to drop. Only a row owned by this client's principal class is removed."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "endpoint"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "unsubscribed": {
                        "type": "boolean",
                        "description": "True when a row was removed; false for an unknown endpoint or one another principal owns — the answer does not distinguish which, so the store cannot be probed."
                    }
                },
                "required": [
                    "unsubscribed"
                ]
            }
        },
        "push.vapidKey": {
            "description": "The VAPID public key (RFC 8292, base64url of the 65-octet P-256 point) this server signs push messages with — the value the browser passes to PushManager.subscribe(). The private half never leaves the server.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "publicKey": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "RFC 8292 VAPID public key: base64url of the 65-octet uncompressed P-256 point, minted once into the serve state dir. The private half never appears on the wire."
                    }
                },
                "required": [
                    "publicKey"
                ]
            }
        },
        "server.health": {
            "description": "Liveness and load.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "ok": {
                        "type": "boolean"
                    },
                    "version": {
                        "type": "string"
                    },
                    "uptimeS": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "sessionsOpen": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "turnsRunning": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "draining": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "ok",
                    "version",
                    "uptimeS",
                    "sessionsOpen",
                    "turnsRunning",
                    "draining"
                ]
            }
        },
        "server.hello": {
            "description": "The handshake: protocol version, features, limits; optionally resume subscriptions (snapshotLimit pages their reset snapshots).",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "minProtocol": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "maxProtocol": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "client": {
                        "type": "object",
                        "properties": {
                            "name": {
                                "type": "string"
                            },
                            "version": {
                                "type": "string"
                            },
                            "instanceId": {
                                "type": "string"
                            }
                        }
                    },
                    "caps": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 64
                    },
                    "resume": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "integer",
                            "minimum": 0
                        },
                        "description": "sessionId => the last seq the client holds"
                    },
                    "snapshotLimit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 500,
                        "description": "Page a resumed session's reset snapshot to this many newest rows."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "protocol": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "server": {
                        "type": "object",
                        "properties": {
                            "version": {
                                "type": "string"
                            },
                            "connectionId": {
                                "type": "string"
                            },
                            "root": {
                                "type": [
                                    "string",
                                    "null"
                                ]
                            },
                            "pid": {
                                "type": [
                                    "integer",
                                    "null"
                                ]
                            }
                        },
                        "required": [
                            "version",
                            "connectionId"
                        ]
                    },
                    "features": {
                        "type": "object",
                        "properties": {
                            "methods": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "events": {
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "dirBrowse": {
                                "type": "object",
                                "properties": {
                                    "enabled": {
                                        "type": "boolean"
                                    },
                                    "root": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    }
                                },
                                "required": [
                                    "enabled",
                                    "root"
                                ],
                                "description": "Whether `fs.listDirs` and a browse-rooted `workspace.open` answer (serve --allow-dir-browse), and the directory they are confined to."
                            },
                            "media": {
                                "type": "object",
                                "properties": {
                                    "image": {
                                        "type": "boolean"
                                    },
                                    "video": {
                                        "type": "boolean"
                                    },
                                    "transcribe": {
                                        "type": "boolean"
                                    },
                                    "baseUrlHostOnly": {
                                        "type": [
                                            "string",
                                            "null"
                                        ]
                                    }
                                },
                                "required": [
                                    "image",
                                    "video",
                                    "baseUrlHostOnly"
                                ],
                                "description": "Whether this server may offer image/video generation, derived at boot from config intersected with probed capability without dialing the server; `transcribe` is optional (old clients and servers interoperate either way) and says whether `voice.baseUrl` names an endpoint — while it is off, the `audio.*` pair answers `voice_unconfigured`; `baseUrlHostOnly` is a sha256 prefix of the SD host — never the URL or hostname in the clear, null when none is configured."
                            }
                        },
                        "required": [
                            "methods",
                            "events"
                        ]
                    },
                    "limits": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "integer",
                            "minimum": 0
                        }
                    },
                    "principal": {
                        "type": "object",
                        "properties": {
                            "kind": {
                                "type": "string",
                                "description": "`owner` for the full-rights connection; `viewer` when a cv1_ viewer grant narrowed this principal to its read-only allowlist. Clients feature-detect viewer support on this field; the kind set may widen without a schema break."
                            },
                            "via": {
                                "type": "string"
                            },
                            "scopes": {
                                "type": "array",
                                "items": {
                                    "enum": [
                                        "read",
                                        "write",
                                        "approve",
                                        "admin"
                                    ]
                                }
                            }
                        },
                        "required": [
                            "kind",
                            "scopes"
                        ]
                    },
                    "defaults": {
                        "type": "object",
                        "properties": {
                            "permissionMode": {
                                "$ref": "#/$defs/PermissionMode"
                            },
                            "delivery": {
                                "enum": [
                                    "queue",
                                    "steer",
                                    "interrupt"
                                ],
                                "description": "The delivery a client should offer first for a prompt sent while a turn runs: the `queueMode` setting, `steer` unless set. A `session.send` that names none still queues."
                            }
                        }
                    },
                    "resumed": {
                        "type": "object",
                        "additionalProperties": {
                            "oneOf": [
                                {
                                    "$ref": "#/$defs/Subscription"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "error": {
                                            "type": "string"
                                        }
                                    },
                                    "required": [
                                        "error"
                                    ],
                                    "additionalProperties": false
                                }
                            ]
                        }
                    }
                },
                "required": [
                    "protocol",
                    "server",
                    "features",
                    "limits",
                    "principal",
                    "defaults",
                    "resumed"
                ]
            }
        },
        "server.info": {
            "description": "What this server offers: providers, agents, commands, tools, permission modes.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "version": {
                        "type": "string"
                    },
                    "protocol": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "root": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "providers": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "agents": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                },
                                "description": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "name"
                            ]
                        }
                    },
                    "tools": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "commands": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "permissionModes": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/PermissionMode"
                        }
                    },
                    "defaultPermissionMode": {
                        "$ref": "#/$defs/PermissionMode"
                    },
                    "limits": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number",
                            "minimum": 0
                        }
                    }
                },
                "required": [
                    "version",
                    "protocol",
                    "permissionModes",
                    "defaultPermissionMode"
                ]
            }
        },
        "server.logs": {
            "description": "The tail of the server log, flattened and capped; admin scope is the only door.",
            "scope": "admin",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "lines": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 200,
                        "description": "How many trailing lines to answer with; the newest survive the line and byte caps. Default 100."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "lines": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        },
                        "maxItems": 200,
                        "description": "Flattened server.log lines, oldest first (control bytes collapsed, each line clipped); the newest survive the byte cap."
                    },
                    "reason": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "maxLength": 35,
                        "description": "`no_log` when this server has no regular server.log to read — a foreground launch never wrote one; null otherwise. Machine token: server text stays untranslated, the browser maps it to chrome."
                    }
                },
                "required": [
                    "lines"
                ]
            }
        },
        "server.shutdown": {
            "description": "Stop the server, draining running turns first.",
            "scope": "admin",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "drainSeconds": {
                        "type": "number",
                        "minimum": 0
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "accepted": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "accepted"
                ]
            }
        },
        "server.strings": {
            "description": "The web UI chrome strings in one locale: only web.-prefixed keys; server, tool and model text stay untranslated.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "locale": {
                        "type": "string",
                        "maxLength": 35,
                        "description": "BCP-47-ish tag to serve; the ladder answers exact, then base-before-dash, then English."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "locale": {
                        "type": "string",
                        "maxLength": 35,
                        "description": "The catalogue actually served."
                    },
                    "strings": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        },
                        "description": "The web UI chrome strings (web.-prefixed keys only); placeholders ride {braces} for the client to fill."
                    }
                },
                "required": [
                    "locale",
                    "strings"
                ]
            }
        },
        "session.archive": {
            "description": "Move a session to the archive tray; it leaves the default listing.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.cancel": {
            "description": "Cancel the running turn (hard, or soft at the next step boundary).",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "turnId": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "mode": {
                        "enum": [
                            "hard",
                            "soft"
                        ]
                    },
                    "clearQueue": {
                        "type": "boolean"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "cancelled": {
                        "type": "boolean"
                    },
                    "mode": {
                        "enum": [
                            "hard",
                            "soft"
                        ]
                    },
                    "cleared": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "cancelled",
                    "mode",
                    "cleared"
                ]
            }
        },
        "session.close": {
            "description": "Release a session (refused while a turn runs unless force).",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "force": {
                        "type": "boolean"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "closed": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "closed"
                ]
            }
        },
        "session.create": {
            "description": "Create a session and open it.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "permissionMode": {
                        "$ref": "#/$defs/PermissionMode"
                    },
                    "ephemeral": {
                        "type": "boolean",
                        "description": "Incognito: a live session that persists nothing — no store row, no transcript saves, no usage records, no title or memory passes — and is dropped by the hub on close."
                    },
                    "root": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "Another project root: the serve gateway routes the call to that root's workspace host (roadmap O-7)."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                }
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.delete": {
            "description": "Delete a session and its history.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "force": {
                        "type": "boolean"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "deleted": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/SessionId"
                        }
                    }
                },
                "required": [
                    "deleted"
                ]
            }
        },
        "session.dequeue": {
            "description": "Remove a queued prompt.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "queueId": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "queueId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "dequeued": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "dequeued"
                ]
            }
        },
        "session.export": {
            "description": "A session's transcript as markdown, json or text; limit/offset page it and revision guards the walk.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "format": {
                        "enum": [
                            "markdown",
                            "json",
                            "text"
                        ]
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Byte offset into the rendered transcript; the page backs up to a UTF-8 lead byte. Only read with limit."
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 65536,
                        "maximum": 1048576,
                        "description": "Ask for a page instead of the whole transcript; the answer shrinks further if the page would not fit the frame. Omitted: one unpaged answer."
                    },
                    "revision": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "The revision a previous page reported; a page 2+ whose session re-rendered is refused export_changed so pages from two renders can never splice."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "format": {
                        "enum": [
                            "markdown",
                            "json",
                            "text"
                        ]
                    },
                    "content": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "The lead-byte-aligned byte this page starts at."
                    },
                    "nextOffset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Where the next page begins; the offset to send back (computed by the server, never by re-encoding the text)."
                    },
                    "total": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Total bytes of the rendered transcript this revision covers."
                    },
                    "more": {
                        "type": "boolean",
                        "description": "False on the last page; join the contents seen so far."
                    },
                    "revision": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "xxh128 of the whole rendered transcript; echo it on the next page."
                    }
                },
                "required": [
                    "format",
                    "content"
                ]
            }
        },
        "session.fork": {
            "description": "Branch a session into a new one carrying its transcript.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.get": {
            "description": "A session's snapshot: rows, status, queue, open questions, usage; limit/beforeIndex page the rows.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 500
                    },
                    "beforeIndex": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSnapshot"
            }
        },
        "session.import": {
            "description": "Import an external agent transcript carried in the request; byte-identical re-sends land in the same session.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "content": {
                        "type": "string",
                        "maxLength": 16711680,
                        "description": "The transcript body to import, up to the verified inbound WS frame ceiling (ServerConfig::MAX_CLIENT_FRAME_BYTES less envelope headroom); a longer body is refused as an invalid param before dispatch, a malformed one as import_refused."
                    },
                    "format": {
                        "enum": [
                            "candy-code",
                            "claude-code",
                            "codex",
                            "opencode"
                        ],
                        "description": "How to read the body; omitted, the importer detects it from the leading structure."
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "root": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "Another project root: the serve gateway routes the call to that root's workspace host (roadmap O-7)."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "content"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.list": {
            "description": "The workspace's sessions, newest activity first, paged.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "limit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 200
                    },
                    "cursor": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "query": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "search": {
                        "type": "string",
                        "maxLength": 256,
                        "description": "LIKE prefilter over name, last preview and id — the pre-full-text search shape; an attach resolving a session by id or name sends this, never `query`."
                    },
                    "archived": {
                        "type": "boolean",
                        "description": "true lists ONLY archived sessions; omitted or false lists the unarchived ones (the historical law)."
                    },
                    "root": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "Another project root: the serve gateway routes the call to that root's workspace host (roadmap O-7)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/SessionSummary"
                        }
                    },
                    "nextCursor": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "required": [
                    "items",
                    "nextCursor"
                ]
            }
        },
        "session.queue": {
            "description": "The prompts queued behind the running turn.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/QueueEntry"
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "session.rename": {
            "description": "Rename a session.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "name"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.send": {
            "description": "Send a prompt: start a turn, or queue / steer / interrupt the running one.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 1048576
                    },
                    "delivery": {
                        "enum": [
                            "queue",
                            "steer",
                            "interrupt"
                        ]
                    },
                    "images": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "maxLength": 256
                                },
                                "mime": {
                                    "enum": [
                                        "image/png",
                                        "image/jpeg",
                                        "image/gif",
                                        "image/webp"
                                    ]
                                },
                                "data": {
                                    "type": "string",
                                    "maxLength": 6990508
                                }
                            },
                            "required": [
                                "mime",
                                "data"
                            ]
                        },
                        "maxItems": 4
                    },
                    "documents": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "maxLength": 256
                                },
                                "mime": {
                                    "enum": [
                                        "application/pdf"
                                    ]
                                },
                                "data": {
                                    "type": "string",
                                    "maxLength": 15379116
                                }
                            },
                            "required": [
                                "mime",
                                "data"
                            ]
                        },
                        "maxItems": 2
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "text"
                ]
            },
            "result": {
                "$ref": "#/$defs/Admission"
            }
        },
        "session.setMode": {
            "description": "The permission mode the session's next turns run in.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "permissionMode": {
                        "$ref": "#/$defs/PermissionMode"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "permissionMode"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "permissionMode": {
                        "$ref": "#/$defs/PermissionMode"
                    }
                },
                "required": [
                    "permissionMode"
                ]
            }
        },
        "session.share": {
            "description": "Publish an HTML snapshot of a session as a self-hosted share page at /s/{token}.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "days": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 365
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "path": {
                        "type": "string"
                    },
                    "format": {
                        "enum": [
                            "html"
                        ]
                    },
                    "expiresAt": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "token",
                    "path",
                    "format",
                    "expiresAt"
                ]
            }
        },
        "session.shares": {
            "description": "The live share pages of one session, or of every session when sessionId is absent.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "sessionId": {
                                    "$ref": "#/$defs/SessionId"
                                },
                                "sessionName": {
                                    "type": [
                                        "string",
                                        "null"
                                    ]
                                },
                                "token": {
                                    "type": "string",
                                    "maxLength": 32
                                },
                                "tokenPrefix": {
                                    "type": "string",
                                    "maxLength": 8
                                },
                                "path": {
                                    "type": "string"
                                },
                                "format": {
                                    "enum": [
                                        "html"
                                    ]
                                },
                                "expiresAt": {
                                    "type": "integer",
                                    "minimum": 0
                                }
                            },
                            "required": [
                                "sessionId",
                                "sessionName",
                                "token",
                                "tokenPrefix",
                                "path",
                                "format",
                                "expiresAt"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "session.subscribe": {
            "description": "Follow a session's events from a cursor (replay) or from a snapshot; snapshotLimit pages the reset snapshot.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "afterSeq": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "mode": {
                        "enum": [
                            "full",
                            "narration"
                        ]
                    },
                    "snapshotLimit": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 500
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/Subscription"
            }
        },
        "session.unarchive": {
            "description": "Restore an archived session to the live listing.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.unshare": {
            "description": "Revoke a share page by token; it 404s from its next request.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "token": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "token"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "revoked": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "revoked"
                ]
            }
        },
        "session.unsubscribe": {
            "description": "Stop following a session.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "unsubscribed": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "unsubscribed"
                ]
            }
        },
        "settings.get": {
            "description": "Effective values and where each came from, or one tier's file; secrets masked.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "scope": {
                        "enum": [
                            "effective",
                            "user",
                            "project",
                            "project-shared"
                        ]
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "scope": {
                        "enum": [
                            "effective",
                            "user",
                            "project",
                            "project-shared"
                        ]
                    },
                    "values": {
                        "type": "object",
                        "additionalProperties": {},
                        "description": "Effective: key => {value, source, sourceLabel, sourcePath, shadowed, locked, lockReason}. A tier: the file's own object."
                    },
                    "files": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "role": {
                                    "type": "string"
                                },
                                "path": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "note": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "role",
                                "path",
                                "status",
                                "note"
                            ]
                        },
                        "description": "Effective only: the files behind the layers, and whether each was read."
                    }
                },
                "required": [
                    "scope",
                    "values"
                ]
            }
        },
        "settings.preview": {
            "description": "What a save would write — the target file's diff, when each change applies, and what blocks it — without writing.",
            "scope": "admin",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "scope": {
                        "enum": [
                            "user",
                            "project",
                            "project-shared"
                        ]
                    },
                    "set": {
                        "type": "object",
                        "additionalProperties": {}
                    },
                    "unset": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 128
                        },
                        "maxItems": 200
                    },
                    "key": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "value": {},
                    "reset": {
                        "type": "boolean"
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "scope": {
                        "type": "string"
                    },
                    "path": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "canSave": {
                        "type": "boolean"
                    },
                    "refusals": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        },
                        "description": "key (`*` for the tier) => why the save is refused"
                    },
                    "changes": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "action": {
                                    "enum": [
                                        "set",
                                        "reset"
                                    ]
                                },
                                "value": {},
                                "applies": {
                                    "type": "string"
                                },
                                "appliesLabel": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "key",
                                "action",
                                "applies",
                                "appliesLabel"
                            ]
                        }
                    },
                    "applySummary": {
                        "type": "string"
                    },
                    "notes": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "diff": {
                        "type": "string",
                        "description": "The target file's JSON, before and after, as unified-diff hunks; secrets masked."
                    }
                },
                "required": [
                    "scope",
                    "path",
                    "canSave",
                    "refusals",
                    "changes",
                    "applySummary",
                    "notes",
                    "diff"
                ]
            }
        },
        "settings.schema": {
            "description": "Every setting: type, default, help, apply mode, and whether a client may write it; and the tiers a save can target.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "key": {
                                    "type": "string"
                                },
                                "type": {
                                    "type": "string"
                                },
                                "default": {},
                                "defaultText": {
                                    "type": "string"
                                },
                                "group": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "help": {
                                    "type": "string"
                                },
                                "enum": {
                                    "type": "array",
                                    "items": {}
                                },
                                "options": {
                                    "type": "array",
                                    "items": {
                                        "type": "string"
                                    },
                                    "description": "The choices a pick-one field offers (the enum, or the launch's list: themes, providers…)."
                                },
                                "min": {
                                    "type": "number"
                                },
                                "max": {
                                    "type": "number"
                                },
                                "riskClass": {
                                    "type": "string"
                                },
                                "applies": {
                                    "enum": [
                                        "live",
                                        "next-turn",
                                        "reload",
                                        "restart",
                                        "frozen"
                                    ]
                                },
                                "appliesLabel": {
                                    "type": "string"
                                },
                                "ui": {
                                    "enum": [
                                        "easy",
                                        "list",
                                        "complex",
                                        "read-only",
                                        "hidden"
                                    ]
                                },
                                "layered": {
                                    "type": "boolean"
                                },
                                "projectSettable": {
                                    "type": "boolean"
                                },
                                "envVar": {
                                    "type": "string",
                                    "description": "The environment variable that, when set, locks the key."
                                },
                                "cliFlag": {
                                    "type": "string"
                                },
                                "sensitive": {
                                    "type": "boolean"
                                },
                                "writableRemotely": {
                                    "type": "boolean"
                                },
                                "remoteRefusal": {
                                    "type": "string",
                                    "description": "Why a client may not write the key; absent when it may."
                                }
                            },
                            "required": [
                                "key",
                                "type",
                                "group",
                                "label",
                                "riskClass",
                                "applies",
                                "sensitive",
                                "writableRemotely"
                            ]
                        }
                    },
                    "tiers": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "scope": {
                                    "enum": [
                                        "user",
                                        "project",
                                        "project-shared"
                                    ]
                                },
                                "label": {
                                    "type": "string"
                                },
                                "path": {
                                    "type": "string"
                                },
                                "writable": {
                                    "type": "boolean"
                                },
                                "refusal": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "scope",
                                "label",
                                "writable"
                            ]
                        },
                        "description": "The tiers a save can target, and whether each can be written now."
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "settings.set": {
            "description": "Write allowlisted settings to the user tier or a trusted project's local or shared file, in one write.",
            "scope": "admin",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "value": {},
                    "reset": {
                        "type": "boolean"
                    },
                    "set": {
                        "type": "object",
                        "additionalProperties": {}
                    },
                    "unset": {
                        "type": "array",
                        "items": {
                            "type": "string",
                            "maxLength": 128
                        },
                        "maxItems": 200
                    },
                    "scope": {
                        "enum": [
                            "user",
                            "project",
                            "project-shared"
                        ]
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                }
            },
            "result": {
                "type": "object",
                "properties": {
                    "key": {
                        "type": "string"
                    },
                    "scope": {
                        "type": "string"
                    },
                    "written": {
                        "type": "string"
                    },
                    "applies": {
                        "type": "string"
                    },
                    "changed": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "appliesByKey": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "scope",
                    "written",
                    "changed"
                ]
            }
        },
        "shells.input": {
            "description": "Type into a running interactive background shell: literal bytes plus at most one named key, composed in that order and delivered as one human-origin send; the answer carries the cursor a following shells.output read threads from. This is a line-oriented door for a polling client — not a PTY stream over the socket, and it does not make the browser a terminal emulator.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "shellId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "text": {
                        "type": "string",
                        "maxLength": 4096,
                        "description": "Literal UTF-8 bytes to type — at most 4096, never a NUL. The call needs text or key (or both; text goes first)."
                    },
                    "key": {
                        "enum": [
                            "Enter",
                            "Esc",
                            "Tab",
                            "Backspace",
                            "Up",
                            "Down",
                            "Left",
                            "Right",
                            "C-c",
                            "C-d",
                            "C-z"
                        ],
                        "description": "One named key from the PtyRun token grammar, appended after text; \"Enter\" is \"\\r\" and completes a line."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "shellId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "accepted": {
                        "type": "boolean"
                    },
                    "cursor": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "The stdout byte offset recorded before the keystroke — exactly what a following shells.output read threads from, so the typed answer cannot be missed."
                    }
                },
                "required": [
                    "accepted",
                    "cursor"
                ]
            }
        },
        "shells.list": {
            "description": "The background shells this session may see — its own plus the untagged ones — without their output.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/BackgroundShell"
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "shells.output": {
            "description": "One windowed read of a background shell's output from a cursor.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "shellId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "cursor": {
                        "oneOf": [
                            {
                                "type": "integer",
                                "minimum": 0
                            },
                            {
                                "type": "string",
                                "maxLength": 64
                            }
                        ],
                        "description": "The \"out.err\" token a previous read answered, or a byte count; omitted (or 0) reads fresh — a fresh window tail-wins, and skippedBytes says how much fell off the head."
                    }
                },
                "required": [
                    "sessionId",
                    "shellId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "shellId": {
                        "type": "string"
                    },
                    "stdout": {
                        "type": "string"
                    },
                    "stderr": {
                        "type": "string"
                    },
                    "cursor": {
                        "type": "string"
                    },
                    "skippedBytes": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "bytesAvailable": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "state": {
                        "enum": [
                            "running",
                            "finished",
                            "unknown"
                        ]
                    },
                    "exitCode": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "exitNote": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "expired": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "shellId",
                    "stdout",
                    "stderr",
                    "cursor",
                    "skippedBytes",
                    "bytesAvailable",
                    "state",
                    "expired"
                ]
            }
        },
        "shells.stop": {
            "description": "Stop a background shell through the launch's kill ladder; a settled or foreign id is a no-op answer.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "shellId": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "shellId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "shellId": {
                        "type": "string"
                    },
                    "found": {
                        "type": "boolean",
                        "description": "False for an unknown id AND for another session's shell — the two answers are identical by design."
                    },
                    "wasRunning": {
                        "type": "boolean"
                    },
                    "confirmed": {
                        "type": "boolean"
                    },
                    "grouped": {
                        "type": "boolean"
                    },
                    "exitCode": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    },
                    "expired": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "shellId",
                    "found",
                    "wasRunning",
                    "confirmed",
                    "grouped",
                    "expired"
                ]
            }
        },
        "todo.get": {
            "description": "A session's todo list, as its Todo tool last wrote it.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "content": {
                                    "type": "string"
                                },
                                "status": {
                                    "enum": [
                                        "pending",
                                        "in_progress",
                                        "completed",
                                        "cancelled"
                                    ]
                                }
                            },
                            "required": [
                                "content",
                                "status"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "token.grant": {
            "description": "Mint one viewer-token grant; the answer carries the raw token exactly once.",
            "scope": "admin",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "label": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "enum": [
                                "read"
                            ]
                        },
                        "description": "v1 read-only allowlist; any other scope is refused."
                    },
                    "days": {
                        "type": "integer",
                        "minimum": 1,
                        "maximum": 365,
                        "description": "Grant lifetime in days; absent means 30."
                    },
                    "sessionIds": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/SessionId"
                        },
                        "description": "Pin the grant to these sessions; absent means unpinned."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "label",
                    "scopes"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "token": {
                        "type": "string",
                        "description": "The full cv1_ token — presented ONCE at mint, never again on any surface."
                    },
                    "label": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "scopes": {
                        "type": "array",
                        "items": {
                            "enum": [
                                "read"
                            ]
                        }
                    },
                    "createdAt": {
                        "type": "string"
                    },
                    "expiresAt": {
                        "type": "string"
                    }
                },
                "required": [
                    "id",
                    "token",
                    "label",
                    "scopes",
                    "createdAt",
                    "expiresAt"
                ]
            }
        },
        "token.list": {
            "description": "List the viewer-token grants in force — never the hashes, never a token.",
            "scope": "admin",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "tokens": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string",
                                    "maxLength": 64
                                },
                                "scopes": {
                                    "type": "array",
                                    "items": {
                                        "enum": [
                                            "read"
                                        ]
                                    }
                                },
                                "sessionIds": {
                                    "type": "array",
                                    "items": {
                                        "$ref": "#/$defs/SessionId"
                                    }
                                },
                                "createdAt": {
                                    "type": "string"
                                },
                                "expiresAt": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "id",
                                "label",
                                "scopes",
                                "createdAt",
                                "expiresAt"
                            ],
                            "description": "The hash and the token are NEVER present on this surface."
                        }
                    }
                },
                "required": [
                    "tokens"
                ]
            }
        },
        "token.revoke": {
            "description": "Revoke one viewer-token grant by id; unknown and already-revoked answer alike.",
            "scope": "admin",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "id": {
                        "type": "string"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "id"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "revoked": {
                        "enum": [
                            true
                        ]
                    }
                },
                "required": [
                    "revoked"
                ],
                "description": "Unknown or already-revoked ids answer through the existing uniform error shape — no existence oracle."
            }
        },
        "tool.output": {
            "description": "A finished tool call's full output, from an offset.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "toolCallId": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "limit": {
                        "type": "integer",
                        "minimum": 1
                    }
                },
                "required": [
                    "sessionId",
                    "toolCallId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "toolCallId": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "content": {
                        "type": "string"
                    },
                    "total": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "isError": {
                        "type": "boolean"
                    },
                    "more": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "toolCallId",
                    "offset",
                    "content",
                    "total",
                    "isError",
                    "more"
                ]
            }
        },
        "tools.client.register": {
            "description": "Announce client-hosted tools for this connection; an empty list withdraws them.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "tools": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string",
                                    "maxLength": 48
                                },
                                "description": {
                                    "type": "string",
                                    "maxLength": 1024
                                },
                                "inputSchema": {
                                    "type": "object",
                                    "additionalProperties": {},
                                    "description": "A JSON Schema object for the arguments, at most 16 KiB encoded; must declare `\"type\": \"object\"`."
                                },
                                "timeoutSeconds": {
                                    "type": "integer",
                                    "minimum": 1,
                                    "maximum": 600
                                }
                            },
                            "required": [
                                "name",
                                "description",
                                "inputSchema"
                            ]
                        },
                        "maxItems": 16
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "tools"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "registrationId": {
                        "type": "string"
                    },
                    "names": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    },
                    "effective": {
                        "enum": [
                            "next_turn"
                        ]
                    }
                },
                "required": [
                    "registrationId",
                    "names",
                    "effective"
                ]
            }
        },
        "tools.client.result": {
            "description": "Answer one tool.client.call with the client's result.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "callId": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "registrationId": {
                        "type": "string",
                        "maxLength": 64
                    },
                    "content": {
                        "type": "string",
                        "maxLength": 262144
                    },
                    "isError": {
                        "type": "boolean"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "callId",
                    "registrationId",
                    "content"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "accepted": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "accepted"
                ]
            }
        },
        "usage.rollup": {
            "description": "The durable usage ledger folded by day and model — one snapshot of the same read `/usage` prints, with derived totals, the unpriced lower-bound flag, and this launch's session-retention setting (read-only). scope \"session\" narrows to sessionId; scope \"all\" spans every session the ledger holds; days trims to the last 7 or 30 whole UTC days.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId",
                        "description": "Required when scope is \"session\" (the ledger half of the answer is that session's rows); ignored for scope \"all\"."
                    },
                    "scope": {
                        "enum": [
                            "session",
                            "all"
                        ],
                        "description": "\"session\" folds one session's rows; \"all\" spans every session the durable ledger holds — the same pair `/usage` and `/usage all` answer."
                    },
                    "days": {
                        "enum": [
                            7,
                            30
                        ],
                        "description": "Trim to the last N whole UTC days inclusive of today; omitted spans the whole ledger. Anything but 7 or 30 is refused, never folded into the whole history."
                    }
                },
                "required": [
                    "scope"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "days": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "day": {
                                    "type": "string",
                                    "maxLength": 16,
                                    "description": "UTC day, \"YYYY-MM-DD\" — the store's own date() fold."
                                },
                                "model": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "maxLength": 256,
                                    "description": "Null for rows written before the model was recorded, exactly as the ledger holds them."
                                },
                                "calls": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "totalTokens": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "costUsd": {
                                    "type": "number",
                                    "minimum": 0
                                },
                                "unpriced": {
                                    "type": "boolean",
                                    "description": "The group's rows include an unpriced call — its costUsd is a lower bound (the `≥` law)."
                                }
                            },
                            "required": [
                                "day",
                                "model",
                                "calls",
                                "totalTokens",
                                "costUsd",
                                "unpriced"
                            ],
                            "additionalProperties": false
                        }
                    },
                    "models": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "model": {
                                    "type": [
                                        "string",
                                        "null"
                                    ],
                                    "maxLength": 256
                                },
                                "calls": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "totalTokens": {
                                    "type": "integer",
                                    "minimum": 0
                                },
                                "costUsd": {
                                    "type": "number",
                                    "minimum": 0
                                },
                                "unpriced": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "model",
                                "calls",
                                "totalTokens",
                                "costUsd",
                                "unpriced"
                            ],
                            "additionalProperties": false
                        }
                    },
                    "totals": {
                        "type": "object",
                        "properties": {
                            "calls": {
                                "type": "integer",
                                "minimum": 0
                            },
                            "totalTokens": {
                                "type": "integer",
                                "minimum": 0
                            },
                            "costUsd": {
                                "type": "number",
                                "minimum": 0
                            }
                        },
                        "required": [
                            "calls",
                            "totalTokens",
                            "costUsd"
                        ],
                        "additionalProperties": false,
                        "description": "Derived from the per-model fold — one source, so totals and rows cannot disagree."
                    },
                    "unpriced": {
                        "type": "boolean",
                        "description": "True when ANY folded row was unpriced: every dollar figure in the answer is then a LOWER BOUND and a surface must say so (the `≥` law)."
                    },
                    "retentionDays": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "This launch's effective sessionRetentionDays setting, read-only — the panel links to Settings, it never writes (no write path opens here)."
                    },
                    "reason": {
                        "type": "string",
                        "description": "Empty when the folds were read; otherwise the stated cause of the empty folds — \"nothing was spent\" and \"nothing can be seen\" are different answers."
                    }
                },
                "required": [
                    "days",
                    "models",
                    "totals",
                    "unpriced",
                    "retentionDays",
                    "reason"
                ]
            }
        },
        "workflow.list": {
            "description": "The workflows /workflow run can start.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "available": {
                        "type": "boolean"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "name": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "name"
                            ]
                        }
                    }
                },
                "required": [
                    "available",
                    "items"
                ]
            }
        },
        "workflow.pause": {
            "description": "Pause a workflow run before its next stage.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "workflowId": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "workflowId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "workflowId": {
                        "type": "string"
                    },
                    "status": {
                        "enum": [
                            "draft",
                            "pending",
                            "running",
                            "paused",
                            "resuming",
                            "completed",
                            "failed",
                            "cancelled"
                        ]
                    }
                },
                "required": [
                    "workflowId",
                    "status"
                ]
            }
        },
        "workflow.resume": {
            "description": "Resume a paused workflow run in a session.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "workflowId": {
                        "type": "string",
                        "maxLength": 256
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "workflowId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "rows": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "role": {
                                    "type": "string"
                                },
                                "content": {
                                    "type": "string"
                                },
                                "uiOnly": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "role",
                                "content",
                                "uiOnly"
                            ]
                        }
                    },
                    "effects": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "rows",
                    "effects"
                ],
                "additionalProperties": false
            }
        },
        "workflow.run": {
            "description": "Run a workflow in a session, as /workflow run does: it occupies the session's turn.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "name": {
                        "type": "string",
                        "maxLength": 128
                    },
                    "vars": {
                        "type": "object",
                        "additionalProperties": {},
                        "description": "Context values for the run; each a string, number or boolean with no whitespace."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "sessionId",
                    "name"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "rows": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "role": {
                                    "type": "string"
                                },
                                "content": {
                                    "type": "string"
                                },
                                "uiOnly": {
                                    "type": "boolean"
                                }
                            },
                            "required": [
                                "role",
                                "content",
                                "uiOnly"
                            ]
                        }
                    },
                    "effects": {
                        "type": "array",
                        "items": {
                            "type": "string"
                        }
                    }
                },
                "required": [
                    "rows",
                    "effects"
                ],
                "additionalProperties": false
            }
        },
        "workflow.runs": {
            "description": "The workflow runs a session's transcript holds: /workflow reports and Workflow tool calls.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "sessionId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "source": {
                                    "enum": [
                                        "command",
                                        "tool"
                                    ]
                                },
                                "name": {
                                    "type": "string"
                                },
                                "status": {
                                    "type": "string"
                                },
                                "running": {
                                    "type": "boolean"
                                },
                                "workflowId": {
                                    "type": "string"
                                },
                                "toolCallId": {
                                    "type": "string"
                                },
                                "report": {
                                    "type": "string"
                                }
                            },
                            "required": [
                                "source",
                                "name",
                                "status",
                                "running"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "workflow.status": {
            "description": "A workflow run's status.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object",
                "properties": {
                    "workflowId": {
                        "type": "string",
                        "maxLength": 256
                    }
                },
                "required": [
                    "workflowId"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "workflowId": {
                        "type": "string"
                    },
                    "status": {
                        "enum": [
                            "draft",
                            "pending",
                            "running",
                            "paused",
                            "resuming",
                            "completed",
                            "failed",
                            "cancelled"
                        ]
                    }
                },
                "required": [
                    "workflowId",
                    "status"
                ]
            }
        },
        "workspace.close": {
            "description": "Stop a workspace host; refused while one of its turns runs, unless force.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "root": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "force": {
                        "type": "boolean"
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "root"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "closed": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "closed"
                ]
            }
        },
        "workspace.list": {
            "description": "The project roots this server serves: its own, and each running workspace host.",
            "scope": "read",
            "idempotent": false,
            "params": {
                "type": "object"
            },
            "result": {
                "type": "object",
                "properties": {
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "root": {
                                    "type": "string"
                                },
                                "primary": {
                                    "type": "boolean"
                                },
                                "running": {
                                    "type": "boolean"
                                },
                                "pid": {
                                    "type": [
                                        "integer",
                                        "null"
                                    ]
                                }
                            },
                            "required": [
                                "root",
                                "primary",
                                "running"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "workspace.open": {
            "description": "Start the workspace host for another project root, or find it running.",
            "scope": "write",
            "idempotent": true,
            "params": {
                "type": "object",
                "properties": {
                    "root": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "browse": {
                        "type": "boolean",
                        "description": "The root was picked with `fs.listDirs`: refused unless directory browsing is on and the root is inside the browse root."
                    },
                    "idempotencyKey": {
                        "type": "string",
                        "maxLength": 64,
                        "description": "A retry with the same key gets the original answer (5 min)."
                    }
                },
                "required": [
                    "root"
                ]
            },
            "result": {
                "type": "object",
                "properties": {
                    "root": {
                        "type": "string"
                    },
                    "primary": {
                        "type": "boolean"
                    },
                    "running": {
                        "type": "boolean"
                    },
                    "pid": {
                        "type": [
                            "integer",
                            "null"
                        ]
                    }
                },
                "required": [
                    "root",
                    "primary",
                    "running"
                ]
            }
        }
    },
    "events": {
        "assistant.completed": {
            "description": "The reply, complete; repairs any delta a client dropped.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "messageId": {
                        "type": "string"
                    },
                    "ref": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "content": {
                        "type": "string"
                    },
                    "reasoning": {
                        "type": "string"
                    },
                    "lengthStopped": {
                        "type": "boolean"
                    },
                    "stepsTruncated": {
                        "type": "boolean"
                    },
                    "usage": {
                        "$ref": "#/$defs/Usage"
                    }
                },
                "required": [
                    "content",
                    "lengthStopped",
                    "stepsTruncated"
                ]
            }
        },
        "assistant.delta": {
            "description": "Streamed reply text.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "text": {
                        "type": "string"
                    },
                    "partId": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Byte offset into the part; a gap means a delta was dropped."
                    }
                },
                "required": [
                    "text",
                    "partId",
                    "offset"
                ]
            }
        },
        "assistant.narration": {
            "description": "The tail of the reply so far, at most every 2 s, for narration subscriptions.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "partId": {
                        "type": "string"
                    },
                    "tail": {
                        "type": "string",
                        "maxLength": 4096
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Byte offset into the part where the tail starts; the next delta continues at offset + its byte length."
                    }
                },
                "required": [
                    "partId",
                    "tail"
                ]
            }
        },
        "bg.completed": {
            "description": "A background session settled; bg.output reads its answer, bg.inject sends it to a session.",
            "durable": false,
            "scope": "server",
            "data": {
                "$ref": "#/$defs/BackgroundSession"
            }
        },
        "bg.started": {
            "description": "A background session started, or one an earlier server or TUI left running was re-adopted.",
            "durable": false,
            "scope": "server",
            "data": {
                "$ref": "#/$defs/BackgroundSession"
            }
        },
        "bg.status": {
            "description": "A background session's status changed (running, stalled, …).",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "bgId": {
                        "type": "string"
                    },
                    "status": {
                        "type": "string"
                    },
                    "previous": {
                        "type": "string"
                    }
                },
                "required": [
                    "bgId",
                    "status",
                    "previous"
                ]
            }
        },
        "compaction.completed": {
            "description": "The history was compacted before a turn.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "kind": {
                        "enum": [
                            "llm",
                            "heuristic",
                            "truncate"
                        ]
                    },
                    "before": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "after": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "savedPct": {
                        "type": "number",
                        "minimum": 0
                    }
                },
                "required": [
                    "kind",
                    "before",
                    "after"
                ]
            }
        },
        "context.changed": {
            "description": "What this session's context is built from has moved (a settle, a compaction, a rules/memory/init command); live-only, and the client re-reads context.sources.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "reason": {
                        "type": "string",
                        "description": "What moved it: settle, compaction, or the name of the context-changing command (rules, memory, init)."
                    }
                },
                "required": [
                    "reason"
                ]
            }
        },
        "message.created": {
            "description": "A transcript row was added: the prompt, a notice, a summary.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "messageId": {
                        "type": "string"
                    },
                    "ref": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "role": {
                        "type": "string"
                    },
                    "kind": {
                        "type": "string"
                    },
                    "content": {
                        "type": "string"
                    },
                    "createdAt": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "messageId",
                    "role",
                    "content"
                ]
            }
        },
        "permission.asked": {
            "description": "A question was put for a client to answer: permission.requested with its sessionId, for every client, following the session or not — and a background session's relayed question, named by its background id and answered the same way. A third shape joins the arm: a project-trust prompt (kind \"trust\") discovered by a context.sources measurement, answered by `context.trust` and not by `permission.respond`.",
            "durable": false,
            "scope": "server",
            "data": {
                "oneOf": [
                    {
                        "type": "object",
                        "properties": {
                            "askId": {
                                "type": "string",
                                "maxLength": 16
                            },
                            "toolCallId": {
                                "type": "string"
                            },
                            "tool": {
                                "type": "string"
                            },
                            "arguments": {
                                "type": "object",
                                "additionalProperties": {}
                            },
                            "reason": {
                                "type": "string"
                            },
                            "source": {
                                "type": "string",
                                "description": "`gate`, `hook:<names>`, or `tool:<name>` for a question the call puts itself (`AskUser`, `PlanExit`)"
                            },
                            "mode": {
                                "type": "string"
                            },
                            "options": {
                                "type": "array",
                                "items": {
                                    "enum": [
                                        "once",
                                        "always",
                                        "reject"
                                    ]
                                }
                            },
                            "choices": {
                                "type": "array",
                                "items": {
                                    "type": "string",
                                    "maxLength": 200
                                },
                                "maxItems": 6,
                                "description": "AskUser's own choices, in order, the first recommended; answer one with `permission.respond` reply `once` and the choice as the note. Absent for every other ask."
                            },
                            "alwaysScope": {
                                "type": "object",
                                "additionalProperties": {
                                    "type": "string"
                                }
                            },
                            "diff": {
                                "type": "string",
                                "description": "The server-computed unified diff of the proposed call, confined to the session root and capped at 32 KiB (beyond it, an omitted note naming the change size, never silence); absent when the call has no previewable outcome. Has real file line numbers, unlike a client-minted snippet diff."
                            },
                            "origin": {
                                "type": "object",
                                "properties": {
                                    "agentId": {
                                        "type": "string"
                                    },
                                    "agentName": {
                                        "type": "string"
                                    },
                                    "parentCallId": {
                                        "type": "string"
                                    }
                                },
                                "required": [
                                    "agentId"
                                ],
                                "description": "The delegated run that asked, when a sub-agent's question was relayed; absent for the turn's own."
                            },
                            "sessionId": {
                                "$ref": "#/$defs/SessionId"
                            }
                        },
                        "required": [
                            "askId",
                            "toolCallId",
                            "tool",
                            "arguments",
                            "options",
                            "sessionId"
                        ]
                    },
                    {
                        "type": "object",
                        "properties": {
                            "askId": {
                                "type": "string",
                                "maxLength": 16
                            },
                            "kind": {
                                "enum": [
                                    "trust"
                                ],
                                "description": "The marker that makes a `permission.asked` payload a project-trust prompt — answered by `context.trust`; `permission.respond` never sees these (they are not in the turn's question registry)."
                            },
                            "target": {
                                "enum": [
                                    "mcp",
                                    "mcp-pin",
                                    "hooks",
                                    "commands",
                                    "settings"
                                ],
                                "description": "Which grant door this prompt is about — the project `.mcp.json` census verdict (`mcp`), a drifted MCP command needing re-approval (`mcp-pin`, which answers through the same list), lifecycle hooks, `` !`cmd` `` command shell forms, or the project settings layer. A grant lands the root in that door's `trustedProject*` list (see the census in `Bootstrap::pendingProjectTrust`)."
                            },
                            "root": {
                                "type": "string",
                                "maxLength": 4096,
                                "description": "The project root the prompt is about — the exact string the grant writes into that door's trusted list."
                            },
                            "reason": {
                                "type": "string",
                                "description": "Why the prompt was put, for the panel line."
                            },
                            "status": {
                                "enum": [
                                    "asked",
                                    "granted",
                                    "rejected"
                                ],
                                "description": "`asked` while open; one answer settles it for the process (the once-per-(root, target) law — the other targets' prompts stay open beside it)."
                            },
                            "persisted": {
                                "type": "boolean",
                                "description": "True when the answer wrote the user-tier trust list; a session grant or a refusal leaves it false."
                            },
                            "sessionId": {
                                "$ref": "#/$defs/SessionId"
                            }
                        },
                        "required": [
                            "askId",
                            "kind",
                            "target",
                            "root",
                            "status",
                            "sessionId"
                        ]
                    }
                ]
            }
        },
        "permission.requested": {
            "description": "A tool call is waiting for an answer (permission.respond).",
            "durable": true,
            "scope": "session",
            "data": {
                "$ref": "#/$defs/PendingAsk"
            }
        },
        "permission.resolved": {
            "description": "A question was answered or cancelled.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "askId": {
                        "type": "string"
                    },
                    "reply": {
                        "enum": [
                            "once",
                            "always",
                            "reject"
                        ]
                    },
                    "note": {
                        "type": "string"
                    },
                    "cancelled": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "askId"
                ]
            }
        },
        "permission.settled": {
            "description": "A question was answered or cancelled (permission.resolved for every client) — a background session's relayed question included, cancelled when its session settled unanswered.",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "askId": {
                        "type": "string"
                    },
                    "reply": {
                        "enum": [
                            "once",
                            "always",
                            "reject"
                        ]
                    },
                    "cancelled": {
                        "type": "boolean"
                    }
                },
                "required": [
                    "sessionId",
                    "askId"
                ]
            }
        },
        "prompt.suggested": {
            "description": "A one-line follow-up suggestion for the turn that just settled, proposed by the title model and billed on it; live-only, never a transcript row, and the next settle replaces it.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "text": {
                        "type": "string"
                    },
                    "generation": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "text",
                    "generation"
                ]
            }
        },
        "reasoning.delta": {
            "description": "Streamed reasoning text.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "text": {
                        "type": "string"
                    },
                    "partId": {
                        "type": "string"
                    },
                    "offset": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Byte offset into the part; a gap means a delta was dropped."
                    }
                },
                "required": [
                    "text",
                    "partId",
                    "offset"
                ]
            }
        },
        "server.overflow": {
            "description": "This client fell behind; ephemeral events were dropped — resubscribe.",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "sessionId": {
                        "$ref": "#/$defs/SessionId"
                    },
                    "dropped": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "action": {
                        "enum": [
                            "resubscribe"
                        ]
                    }
                },
                "required": [
                    "dropped",
                    "action"
                ]
            }
        },
        "server.shutdown": {
            "description": "The server is stopping.",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "reason": {
                        "type": "string"
                    },
                    "graceSeconds": {
                        "type": "number",
                        "minimum": 0
                    }
                },
                "required": [
                    "reason",
                    "graceSeconds"
                ]
            }
        },
        "server.tick": {
            "description": "Liveness, every tickIntervalMs.",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "now": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "turnsRunning": {
                        "type": "integer",
                        "minimum": 0
                    }
                },
                "required": [
                    "now",
                    "turnsRunning"
                ]
            }
        },
        "session.created": {
            "description": "A session was created.",
            "durable": false,
            "scope": "server",
            "data": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "session.deleted": {
            "description": "A session was deleted.",
            "durable": false,
            "scope": "server",
            "data": {
                "type": "object",
                "properties": {
                    "id": {
                        "$ref": "#/$defs/SessionId"
                    }
                },
                "required": [
                    "id"
                ]
            }
        },
        "session.status": {
            "description": "The session became idle, busy or waiting_permission.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "status": {
                        "enum": [
                            "idle",
                            "busy",
                            "waiting_permission"
                        ]
                    }
                },
                "required": [
                    "status"
                ]
            }
        },
        "session.updated": {
            "description": "A session was renamed, its mode changed, its model changed, or its status changed (idle, busy, waiting_permission). A served `/model` or `/rename` reaches every client through this arm, not only the status lane.",
            "durable": false,
            "scope": "server",
            "data": {
                "$ref": "#/$defs/SessionSummary"
            }
        },
        "spend_cap.breached": {
            "description": "The session spend cap stopped the turn.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "calls": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "spent": {
                        "type": "number",
                        "minimum": 0
                    },
                    "cap": {
                        "type": "number",
                        "minimum": 0
                    }
                },
                "required": [
                    "calls",
                    "spent",
                    "cap"
                ]
            }
        },
        "subagent.finished": {
            "description": "A delegated sub-agent finished.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "v": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "id": {
                        "type": "string"
                    },
                    "op": {
                        "type": "string"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "task": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The delegated prompt; carried on started only."
                    },
                    "seq": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "tail": {},
                    "tokens": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "cost": {
                        "type": "number",
                        "minimum": 0
                    },
                    "lines": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "model": {
                        "type": "string"
                    },
                    "context": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "calls": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "state": {
                                    "type": "string"
                                },
                                "at": {
                                    "type": "integer"
                                }
                            },
                            "required": [
                                "id",
                                "label",
                                "state"
                            ]
                        }
                    },
                    "parentCallId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentAgentId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "description": {
                        "type": "string"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": {}
                        }
                    },
                    "stats": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number"
                        }
                    },
                    "outcome": {},
                    "error": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "resumeId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "transcriptLog": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "childSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "op"
                ]
            }
        },
        "subagent.progress": {
            "description": "A delegated sub-agent made progress.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "v": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "id": {
                        "type": "string"
                    },
                    "op": {
                        "type": "string"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "task": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The delegated prompt; carried on started only."
                    },
                    "seq": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "tail": {},
                    "tokens": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "cost": {
                        "type": "number",
                        "minimum": 0
                    },
                    "lines": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "model": {
                        "type": "string"
                    },
                    "context": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "calls": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "state": {
                                    "type": "string"
                                },
                                "at": {
                                    "type": "integer"
                                }
                            },
                            "required": [
                                "id",
                                "label",
                                "state"
                            ]
                        }
                    },
                    "parentCallId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentAgentId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "description": {
                        "type": "string"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": {}
                        }
                    },
                    "stats": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number"
                        }
                    },
                    "outcome": {},
                    "error": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "resumeId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "transcriptLog": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "childSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "op"
                ]
            }
        },
        "subagent.started": {
            "description": "A delegated sub-agent started.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "v": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "id": {
                        "type": "string"
                    },
                    "op": {
                        "type": "string"
                    },
                    "name": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "task": {
                        "type": [
                            "string",
                            "null"
                        ],
                        "description": "The delegated prompt; carried on started only."
                    },
                    "seq": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "tail": {},
                    "tokens": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "cost": {
                        "type": "number",
                        "minimum": 0
                    },
                    "lines": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "model": {
                        "type": "string"
                    },
                    "context": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "calls": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "id": {
                                    "type": "string"
                                },
                                "label": {
                                    "type": "string"
                                },
                                "state": {
                                    "type": "string"
                                },
                                "at": {
                                    "type": "integer"
                                }
                            },
                            "required": [
                                "id",
                                "label",
                                "state"
                            ]
                        }
                    },
                    "parentCallId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentAgentId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "description": {
                        "type": "string"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "additionalProperties": {}
                        }
                    },
                    "stats": {
                        "type": "object",
                        "additionalProperties": {
                            "type": "number"
                        }
                    },
                    "outcome": {},
                    "error": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "resumeId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "transcriptLog": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "parentSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    },
                    "childSessionId": {
                        "type": [
                            "string",
                            "null"
                        ]
                    }
                },
                "required": [
                    "id",
                    "op"
                ]
            }
        },
        "todo.updated": {
            "description": "A Todo call rewrote the session's todo list; carries the whole list.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "toolCallId": {
                        "type": "string"
                    },
                    "items": {
                        "type": "array",
                        "items": {
                            "type": "object",
                            "properties": {
                                "content": {
                                    "type": "string"
                                },
                                "status": {
                                    "enum": [
                                        "pending",
                                        "in_progress",
                                        "completed",
                                        "cancelled"
                                    ]
                                }
                            },
                            "required": [
                                "content",
                                "status"
                            ]
                        }
                    }
                },
                "required": [
                    "items"
                ]
            }
        },
        "tool.client.call": {
            "description": "A client-hosted tool call is being asked of the clients: run `name` and answer tools.client.result with `callId`/`registrationId`; ephemeral — the pending call lives on a deadline, not in the log.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "callId": {
                        "type": "string",
                        "description": "Answer tools.client.result with this; the first accepted result settles the call."
                    },
                    "registrationId": {
                        "type": "string",
                        "description": "The registration that owns the name; clients whose current registration is not this one ignore the event."
                    },
                    "name": {
                        "type": "string",
                        "description": "The full proxy name, `client__` prefix included."
                    },
                    "arguments": {
                        "type": "object",
                        "additionalProperties": {},
                        "description": "The model-supplied arguments, validated against the registered inputSchema."
                    },
                    "deadlineAt": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Wall-clock milliseconds by which the answer must land; after it the call settles as an error."
                    }
                },
                "required": [
                    "callId",
                    "registrationId",
                    "name",
                    "arguments",
                    "deadlineAt"
                ]
            }
        },
        "tool.finished": {
            "description": "A tool call finished (content capped; tool.output has the rest).",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "messageId": {
                        "type": "string"
                    },
                    "ref": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "toolCallId": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "isError": {
                        "type": "boolean"
                    },
                    "durationMs": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "content": {
                        "type": "string",
                        "description": "At most 256 KiB; tool.output reads the rest."
                    },
                    "truncated": {
                        "type": "boolean"
                    },
                    "diff": {
                        "type": "string"
                    },
                    "denial": {
                        "type": "object",
                        "properties": {
                            "kind": {
                                "type": "string"
                            },
                            "reason": {
                                "type": "string"
                            }
                        },
                        "required": [
                            "kind"
                        ]
                    },
                    "media": {
                        "type": "array",
                        "items": {
                            "$ref": "#/$defs/MediaRef"
                        },
                        "maxItems": 32,
                        "description": "Artifact refs from the session media store — paths only, never bytes (Appendix C-7)."
                    },
                    "mediaTruncated": {
                        "type": "boolean"
                    },
                    "replaces": {
                        "type": "string"
                    }
                },
                "required": [
                    "toolCallId",
                    "name",
                    "isError",
                    "content"
                ]
            }
        },
        "tool.progress": {
            "description": "Live tail of a running tool call, frame-rate capped; ephemeral — tool.finished is the contract, so a late joiner replays nothing and still sees the whole output.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "toolCallId": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "seq": {
                        "type": "integer",
                        "minimum": 1,
                        "description": "Frames of this call so far, from 1; a client keeps the highest it has seen."
                    },
                    "tail": {
                        "type": "string",
                        "description": "The last tailBudget bytes of output, replaced wholesale each frame — never a delta to stitch."
                    },
                    "truncated": {
                        "type": "boolean",
                        "description": "True once bytes fell out of the ring."
                    },
                    "tailBudget": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "Byte cap the tail obeys."
                    }
                },
                "required": [
                    "toolCallId",
                    "name",
                    "seq",
                    "tail",
                    "truncated",
                    "tailBudget"
                ]
            }
        },
        "tool.started": {
            "description": "A tool call started.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "messageId": {
                        "type": "string"
                    },
                    "ref": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "toolCallId": {
                        "type": "string"
                    },
                    "name": {
                        "type": "string"
                    },
                    "arguments": {
                        "type": "object",
                        "additionalProperties": {}
                    }
                },
                "required": [
                    "toolCallId",
                    "name"
                ]
            }
        },
        "turn.completed": {
            "description": "A turn ended, with its stopReason.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "stopReason": {
                        "enum": [
                            "end_turn",
                            "max_steps",
                            "length",
                            "cancelled",
                            "spend_cap",
                            "loop_guard",
                            "error"
                        ]
                    },
                    "error": {
                        "type": "string"
                    },
                    "messageId": {
                        "type": "string"
                    }
                },
                "required": [
                    "stopReason"
                ]
            }
        },
        "turn.dequeued": {
            "description": "A queued prompt left the queue (sent or removed).",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "queueId": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "text": {
                        "type": "string"
                    },
                    "reason": {
                        "enum": [
                            "sent",
                            "removed"
                        ]
                    }
                },
                "required": [
                    "queueId",
                    "reason"
                ]
            }
        },
        "turn.queued": {
            "description": "A prompt was queued behind the running turn.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "queueId": {
                        "type": "string",
                        "maxLength": 32
                    },
                    "text": {
                        "type": "string"
                    },
                    "position": {
                        "type": "integer",
                        "minimum": 1
                    }
                },
                "required": [
                    "queueId",
                    "text",
                    "position"
                ]
            }
        },
        "turn.started": {
            "description": "A turn began.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "turnId": {
                        "type": "string"
                    },
                    "messageId": {
                        "type": "string"
                    }
                },
                "required": [
                    "turnId"
                ]
            }
        },
        "turn.steered": {
            "description": "A steering message was handed to the running turn.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "turnId": {
                        "type": "string"
                    },
                    "steerId": {
                        "type": "string"
                    }
                },
                "required": [
                    "steerId"
                ]
            }
        },
        "turn.step": {
            "description": "The running turn reached a step boundary.",
            "durable": false,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "step": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "maxSteps": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "context": {
                        "type": [
                            "object",
                            "null"
                        ],
                        "additionalProperties": {}
                    }
                },
                "required": [
                    "step",
                    "maxSteps"
                ]
            }
        },
        "usage.updated": {
            "description": "Token and cost usage changed.",
            "durable": true,
            "scope": "session",
            "data": {
                "type": "object",
                "properties": {
                    "step": {
                        "type": "integer",
                        "minimum": 0
                    },
                    "usage": {
                        "oneOf": [
                            {
                                "$ref": "#/$defs/Usage"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    },
                    "turnUsage": {
                        "oneOf": [
                            {
                                "$ref": "#/$defs/Usage"
                            },
                            {
                                "type": "null"
                            }
                        ]
                    }
                },
                "required": [
                    "step"
                ]
            }
        }
    }
}