api-openapi.json

{
  "openapi": "3.1.0",
  "info": {
    "title": "vinga-server configuration API",
    "description": "The domain half of one vinga-server deployment's configuration: providers, MCP servers, agents, devices, and the credentials they use. Every request carries a bearer token, whose value is the environment variable `server.api.secret_env` names.\n\nA read of one entity is a write of it. The `entity` half of the envelope an addressed read answers is resubmittable as it stands: a PUT replaces the model-shaped half and never the credentials stored beside it, so an edit is read it, change it, send the whole of it back, and the fields a read leaves out are the ones that mean absence and mean the same absence on the way back. An environment reference reads back as itself and resubmits as itself. A value shown as the mask, `********`, resubmits as keep the stored value, which is substituted before the fragment is validated; that mask written where nothing is stored is refused, naming the field where the field is one this API declares. An unchanged stored secret needs no action at all: the envelope's `secrets` mapping is informational, and rotating a credential is the secret PUT, which is the one door a plaintext value enters by. Everything else a read answers is display-only, and named here so the writable category has a stated boundary: that `secrets` mapping; the identity keys of every listing, which address the target URL rather than belonging in a body; both halves of the whole-configuration read, which has no PUT of its own; the pending-device listing, which is the running server's state; and everything under `/runtime`, `/sessions` and `/conversations`, which is not stored configuration at all. The writable shapes are that one `entity` and the three bodies this document describes as arguments rather than as entities: a device's `agents`, the default agent's `name`, and a credential's `secret`.\n\nA write is stored, and when it reaches a running server depends on the kind. What a server is serving of this half is a generation: an immutable snapshot, validated whole, built entirely before anything binds it. There is more than one over the life of a process, and applying a change installs the next one rather than editing the one in place, so a conversation goes on speaking the world it opened in and new work binds the world that is current. The one part of a deployment's configuration that is genuinely read once is the server section, which is this process's own file: the port, the directories, the limits. Nothing this API writes is in it.\n\nSo a write converges at one of two boundaries here, and sometimes at both. Device bindings are read as a device asks for them, so binding or unbinding a device applies at that device's next OTA check or connection with nothing asked of the server, and the default agent is read by the next claim that names no agent; that exception ends where the agent does, since a binding naming an agent this server is not serving resolves to nothing until the reload that installs it, which is what such a write's acknowledgement says. Everything else, which is the whole of the rest of this half, is applied by `POST /runtime/config/reload`, without a restart and without dropping a conversation. Every write says which boundaries it is waiting at, in `applies`, a set of the closed tokens the comparison read publishes: `check-in` for the two kinds a device is answered as it asks, `reload` for the whole of the rest of this half, `restart` for the server section this API does not write, and `store-boot` for a write to a server serving a configuration it was handed rather than one it read from a store, which nothing it is running reads. A set rather than a token because a binding naming an agent this server is not serving yet is waiting at two of them at once, and it carries both. That is the half to branch on. The `notice` beside it says the same thing as a sentence, for a reader rather than for a program, and it names no command: which command crosses a boundary is a fact of a client's grammar, and this server neither ships nor versions the client that will read this.\n\nA device with no binding of its own is answered at its configuration check with a six-digit activation code, which it shows on its screen and speaks, whether or not a default agent is set: an unbound device only pairs. `/devices/pending` lists the devices showing one, keyed by the code, and posting to `/devices/pending/{code}` binds the device showing it, to the agents the body names or else to the default agent, which is vinga, the built-in agent, when none is set. That listing is the running server's own state rather than stored configuration: a restart forgets it, and the devices come back with fresh codes.\n\nThe `/runtime` namespace is the running server's own state as well, and is kept apart from the entity namespaces because an entity may legally be named after any word a route might want. `/runtime/mcp-servers` says what each configured MCP server is doing right now: connected or down, since when, what it published, and which agents may reach it. Nothing there is read from the database, so it cannot disagree with what is running.\n\n`GET /runtime/info` is the read that says which deployment is answering: the version and the revision of the build that is running, whether the short onboarding path is served, and, when it is, the URL to type into a device's captive portal with the provenance of the origin in it. That URL is the one credential this API answers to a read: its last segment is a key derived from the device-auth secret and it stands in front of the token issuer, which is why the startup banner prints the origin without it. What protects it is the gate every request here passes and nothing else is asked to: the bearer token already grants every secret write this API serves, so a read of the URL widens nothing it does not hold. The response carries `Cache-Control: no-store` so that no cache between the two ends retains it, which is the same reason the whole API belongs on a loopback connection or behind TLS. With onboarding off the URL and its provenance are null: devices are configured at the path `server.ota_path` names, and that segment is this deployment's secret rather than a substitute the read could offer instead.\n\n`POST /runtime/invites` is an action in that namespace, and it answers a credential. It issues an invite link, a page a browser opens to join this deployment as a device bound before its first word to the agents the request body names, or to the default agent when it names none: `page` is the page's path with a single-use token in its fragment, and `origin` is the configured `server.public_url` when that opens a secure context in a browser and null otherwise. The token is held in the running server's memory for `lifetime_s` seconds or until a restart, together with the agents it binds, is spent by the first browser that opens the link, and travels in a fragment so that opening the link puts it in no access log; the response carries `Cache-Control: no-store` for the reason the identity read does. No link is issued while device onboarding is off, while the server serves a configuration no store describes, while a named agent is not one this deployment has or not one this server is serving, while this server is not serving the default agent (vinga, the built-in agent, when none is set) for an invite that names none, or while as many links are waiting as the server holds.\n\n`GET /runtime/agents/{name}/prompt` is the other read there: the system prompt a session opening now as that agent would be sent, block by block, with the provenance and the character count of each and the total. It is assembled from the loaded agents, the running MCP slice and the memory store rather than from the database, so it cannot disagree with what a session would get, and it is a preview of a new session rather than a readback of a running one: a conversation already in progress holds the half it assembled at its own activation.\n\n`GET /runtime/config/diff` is the third read there, and the one that spans both sides: what the database holds that this server is not serving, kind by kind, as the entity names added, removed and changed, each kind carrying the boundary its changes converge at. `reload` is what the apply below puts in place, which is every kind of this half; `check-in` is the device bindings and the default agent, which a device is answered as it asks and which are therefore never pending, so they carry the label alone and no lists. `restart` is declared and unused here, for the server section this API does not write. An agent entry converges at three different moments inside the one reload, so their kind carries three entries of its own beside its own lists: `grants`, `prompt` and `filler`, each labelled `reload`, and each a breakdown of `changed` rather than an exception to it. Changed means the stored state differs from the comparison baseline rather than that something was written: an edit changed back before anyone looked produces no diff, and a rewritten stored secret counts as different, because what is compared is an opaque mark over the ciphertext and it moves even when the plaintext may not have. Entity names and those labels are the whole of the answer: no bodies, no values and no marks cross it. The MCP half is compared against the entries running now rather than the ones this process booted with, so a change a reload has already applied is not reported as pending. What an answer does not say is that applying what it lists would succeed: it compares configuration and connects nothing, while the reload below goes on to build a server for every entry an agent references and can still refuse on one of those.\n\n`GET /runtime/events` is the fourth, and the only one that does not end: the structured events as this server emits them, streamed as Server-Sent Events. One `data:` line per event, carrying the catalogued fields of that event plus two the stream owns: `ts`, the wall-clock instant it was emitted at, and `level`, its level's name. Those are the fields the retained JSON log carries too, under the same names; the log's own record-keeping beside them, the channel and the rendered sentence, is not repeated here. It is live and nothing but: there is no buffer behind it and no `since`, so a reader that reconnects rejoins the present and reads what happened before from the conversation store, where a deployment enabled one. Three query filters narrow it, applied as the events arrive: `device`, a MAC in either separator and any case; `session`, a session's uuid hex; and `level`, a threshold over the four level names in any case, which defaults to `INFO` because that is what the retained log carries. An event naming no device or no session passes such a filter only when none is set. A reader that falls behind loses its oldest events rather than slowing the server down and is told so by a `dropped` event carrying how many went; an idle stream sends a comment line so a proxy does not close it; and the stream ends when the client goes away or when the server shuts down. Nothing that is not on the events is on it, which is the whole of what makes a live view of a conversation safe to open: what was said is in the conversation store, and these are metadata.\n\n`POST /runtime/config/reload` is the action in that namespace that applies configuration, and unlike device bindings it is asked for rather than noticed. It re-reads the stored configuration and applies the whole domain half: the `providers` entries and the `mcp_servers` entries with the secrets stored on them, the agents' `mcp` grant lists, the shared prompt fragments, the agents themselves and the `agent_defaults` layer under them. Entries are started, restarted, stopped or left alone, and no conversation is dropped. Nothing is swapped, stopped or started until the whole new world has been composed, validated and built, so a refusal has changed nothing at all. When a live conversation meets the result depends on which half moved. The tools it may reach are snapshotted per reply, so a started, restarted or stopped entry is picked up on its next utterance. Prompt text is assembled at an activation and cached for it, so an agent's prompt, a fragment it includes and an entry's `instructions` alike reach a conversation at its next activation, which is a new session or an agent switch, and never a reply of one already running; `GET /runtime/agents/{name}/prompt` previews what a session opening now would be sent. Filled pauses are synthesized during the apply and bound by a conversation when it opens, so an edited filler section reaches the next conversation and never changes what one already open is masking with. An agent is synthesized again when any field of its effective `filler` section moved or when the voice that speaks it did, and its clips are carried over as they are otherwise: the whole section is the unit of comparison, so an edit to `delay_ms` alone is a round of text-to-speech work at the configured provider even though the audio it produces is identical, and rewriting the provider entry an agent speaks through is another, since that is the voice moving; an edit that reaches neither, a prompt or a fragment, is none. An agent whose synthesis failed applies with no clip and runs unmasked rather than refusing the reload, which the answer's `fillers` section reports. The engines are the same clock and a different cost: an entry whose definition and stored credential are unchanged is carried into the new world as the object it already was, so an edit to a prompt reloads no model at all, while a rewritten entry is built before anything is swapped and the conversations that open after that speak through it. One that a conversation is still speaking through is released when that conversation ends, so an apply that changes a local model briefly holds two, and one whose engines would not build refuses with nothing changed. The agent set moves with the rest: an agent the store has added is one a device can be bound to and reach at its next check-in, and one it has deleted is one no session can be opened as from the moment this answers, while a conversation already talking as it finishes on the world it was built from. The answer's `agents` section names both, and says whether `agent_defaults` moved.\n\nThe `/sessions` and `/conversations` namespaces are not stored configuration either: they read the conversation store, the record of what was said, which `server.conversations.enabled` switches on. They are two readings of one set of rows rather than two stores, because a turn names both the session it was spoken in and the conversation it belongs to: the turns of one session can belong to several threads, and one thread's turns can come from several sessions. `/sessions` answers one connection episode at a time, which is what a session is: the session list newest first, one session whole, and one session's turns oldest first with the calls each turn made nested under it. `/conversations` answers the durable thread, which belongs to exactly one agent and outlives any single session: the thread list most recently active first and filterable by agent, one thread whole, and one thread's dialogue oldest first. Both namespaces erase as well as read, and the two erasures are asymmetric on purpose: `DELETE /sessions/{session}` and the selector purge take a session's turns wherever their threads are, while `DELETE /conversations/{conversation}` takes a thread's turns out of whatever sessions they were spoken in and leaves those sessions and their telemetry alone, with a gap in them. Three of the four listings are cursor-paginated on monotonic row ids that are never reused; the thread listing orders on activity, which moves, so it pages on the pair `cursor_active` and `cursor_id`, sent together or not at all. The two singular reads take neither `limit` nor `cursor`. A deployment that never recorded answers the empty shapes rather than a refusal, because the schema is migrated at every boot; one that recorded and has since switched recording off still serves what it recorded, because switching recording off stops the writer and not the reader. Content columns come back as they were stored, which is null where text storage was off, and every session says which way its switches were set.\n\n`/metrics` is the third reading of those same rows, and it answers about days rather than about a session or a thread: the named aggregates over the record, which are views in the store's own schema and add nothing to what is stored. `GET /metrics` lists them, each with the question it answers, the denominator its numbers are counted against, what telemetry storage being off does to that view in particular, and the columns a row of it carries; `GET /metrics/{view}` answers one of them over a window of whole UTC days, named by `since` and `until`, both included in it, defaulting to the current UTC day and the thirty before it and spanning at most three hundred and sixty-six. A wider window is refused rather than narrowed. Rows come newest day first and then by the columns a row of that view is unique by, which is a total order, and an empty list is an ordinary answer: a window with nothing in it and a deployment that never recorded are the same answer here for the reason the two namespaces above give. The word in the path is the last segment of a path this document lists and resolves through a closed mapping, so a name nothing answers to is refused rather than looked for. Every answer carries the statements that hold for all of these views beside the numbers, because what a number here cannot be made to say is the half a reader is most likely to be missing: a rate whose denominator is zero is null and not zero, a rate read outside the events' own retention window is a floor rather than a measurement, and a missing measurement has more than one cause that the store writes identically. This namespace exists for the readers that cannot speak SQL. A dashboard with a Postgres connection is a SQL client and reads the views directly, and the spelling `/metrics` shares with a scrape endpoint is a coincidence: nothing here is a Prometheus exposition, and it sits behind the same bearer token as everything else.\n\nA provider entry carries whatever options its `type` takes. The types that declare an option model, as stage and type, are: llm openai_compatible, asr faster_whisper, asr openai, tts elevenlabs. Their options are checked when the entry is written and refused by name, they are printed by `vinga schema provider <stage> <type>`, and the reference lists their fields under the provider section. Every other type has its options passed through rather than declared, so no schema can list those, and until the rest are typed (#88) they are documented in the example fragments under `vinga-server/examples/`, which is also where the measured numbers behind each default are kept.",
    "version": "1"
  },
  "servers": [
    {
      "url": "/api"
    }
  ],
  "paths": {
    "/config": {
      "get": {
        "summary": "Read Config",
        "description": "The whole domain configuration, masked, with the location of\nevery stored secret beside it.",
        "operationId": "read_config_config_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfigDocument"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/providers": {
      "get": {
        "summary": "Read Providers",
        "description": "Every provider, by stage and then by name: a provider is\naddressed by the two together, since two stages may hold one\nname.",
        "operationId": "read_providers_providers_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "additionalProperties": {
                      "$ref": "#/components/schemas/Envelope"
                    },
                    "type": "object"
                  },
                  "type": "object",
                  "title": "Response Read Providers Providers Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/providers/{stage}/{name}": {
      "get": {
        "summary": "Read Provider",
        "description": "One provider.",
        "operationId": "read_provider_providers__stage___name__get",
        "parameters": [
          {
            "name": "stage",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Stage"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Provider",
        "description": "Create or replace one provider from a fragment in the shape the YAML section had. The running server builds it again at the next reload, and the conversations that open after that speak through the new one.\n\nThe options a fragment may carry beyond the fields of `ProviderConfig` are whatever its `type` takes. This body is validated by the server rather than described as a discriminated schema here, so the types that declare their options state them as components of their own, named for the stage and the type: an entry in the `llm` stage with `type: openai_compatible` carries `LlmOpenaiCompatibleOptions`, an entry in the `asr` stage with `type: faster_whisper` carries `AsrFasterWhisperOptions`, an entry in the `asr` stage with `type: openai` carries `AsrOpenaiOptions`, an entry in the `tts` stage with `type: elevenlabs` carries `TtsElevenlabsOptions`. Every other type passes its options through undeclared, and the example fragments shipped with the server document those.",
        "operationId": "write_provider_providers__stage___name__put",
        "parameters": [
          {
            "name": "stage",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Stage"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ProviderConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Provider",
        "description": "Delete one provider, and the secrets stored on it. Refused\nwhile an agent or the agent defaults still name it.",
        "operationId": "remove_provider_providers__stage___name__delete",
        "parameters": [
          {
            "name": "stage",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Stage"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/mcp-servers": {
      "get": {
        "summary": "Read Mcp Servers",
        "description": "Every MCP server, by name.",
        "operationId": "read_mcp_servers_mcp_servers_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/Envelope"
                  },
                  "type": "object",
                  "title": "Response Read Mcp Servers Mcp Servers Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/mcp-servers/{name}": {
      "get": {
        "summary": "Read Mcp Server",
        "description": "One MCP server.",
        "operationId": "read_mcp_server_mcp_servers__name__get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Mcp Server",
        "description": "Create or replace one MCP server. The running server applies\nit at the next reload, with no restart.",
        "operationId": "write_mcp_server_mcp_servers__name__put",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/McpServerConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Mcp Server",
        "description": "Delete one MCP server, and the secrets stored on it. The\nrunning server stops it at the next reload.",
        "operationId": "remove_mcp_server_mcp_servers__name__delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/prompt-fragments": {
      "get": {
        "summary": "Read Prompt Fragments",
        "description": "Every shared prompt fragment, by name.",
        "operationId": "read_prompt_fragments_prompt_fragments_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/Envelope"
                  },
                  "type": "object",
                  "title": "Response Read Prompt Fragments Prompt Fragments Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/prompt-fragments/{name}": {
      "get": {
        "summary": "Read Prompt Fragment",
        "description": "One shared prompt fragment, with its text as it was written:\nit is what the model is given, and there is nothing in it to\nmask.",
        "operationId": "read_prompt_fragment_prompt_fragments__name__get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Prompt Fragment",
        "description": "Create or replace one shared prompt fragment.\n\nIt carries the reload sentence: a fragment is prompt text, the\nreload re-reads the whole `prompt_fragments` kind, and prompt\ntext is assembled at an activation, so the new words reach every\nagent that includes this fragment at that agent's next\nactivation. Which agents those are is whichever layer names it,\nand both layers are the same reload's: an agent's own\n`prompt_includes`, and the `agent_defaults.prompt_includes` that\nevery agent naming no list of its own inherits.",
        "operationId": "write_prompt_fragment_prompt_fragments__name__put",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptFragmentConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Prompt Fragment",
        "description": "Delete one shared prompt fragment. Refused while any layer\nstill includes it.",
        "operationId": "remove_prompt_fragment_prompt_fragments__name__delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/agents": {
      "get": {
        "summary": "Read Agents",
        "description": "Every agent, by name.",
        "operationId": "read_agents_agents_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/Envelope"
                  },
                  "type": "object",
                  "title": "Response Read Agents Agents Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{name}": {
      "get": {
        "summary": "Read Agent",
        "description": "One agent.",
        "operationId": "read_agent_agents__name__get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Agent",
        "description": "Create or replace one agent. Every provider and MCP server it\nnames has to exist already, which is what the natural creation\norder is about. No agent may be created under vinga, the\nbuilt-in agent's name; one stored under it before the built-in\nexisted may still be replaced.",
        "operationId": "write_agent_agents__name__put",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentConfig"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Agent",
        "description": "Delete one agent. Refused while a device binding or the\ndefault agent still names it.",
        "operationId": "remove_agent_agents__name__delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/agent-defaults": {
      "get": {
        "summary": "Read Agent Defaults",
        "description": "What every agent uses unless it names something else. One\nentry for the whole deployment, and never missing: an unwritten\none reads as the empty entry.",
        "operationId": "read_agent_defaults_agent_defaults_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Agent Defaults",
        "description": "Replace what every agent uses unless it names something else.\nOne entry for the whole deployment, so this is a replace and\nthere is nothing to delete.",
        "operationId": "write_agent_defaults_agent_defaults_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentDefaults"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/builtin-agent": {
      "get": {
        "summary": "Read Builtin Agent",
        "description": "What vinga, the built-in agent, uses in place of what every\nagent inherits. One entry for the whole deployment, and never\nmissing: an unwritten one reads as the empty entry.",
        "operationId": "read_builtin_agent_builtin_agent_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Builtin Agent",
        "description": "Replace what vinga, the built-in agent, uses in place of what\nevery agent inherits. One entry for the whole deployment, so\nthis is a replace and there is nothing to delete. It carries no\nprompt and no MCP grants: neither is a field it has.",
        "operationId": "write_builtin_agent_builtin_agent_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BuiltinAgentConfig"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices": {
      "get": {
        "summary": "Read Devices",
        "description": "Every device binding, by the canonical form of its MAC. Bound\ndevices only: the ones waiting to be claimed are the listing\nbelow, since they have no binding to show.",
        "operationId": "read_devices_devices_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/Envelope"
                  },
                  "type": "object",
                  "title": "Response Read Devices Devices Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/pending": {
      "get": {
        "summary": "Read Pending Devices",
        "description": "Every device showing an activation code, by the code it is\nshowing.\n\nRuntime state of the server this application is mounted on\nrather than stored configuration, so it touches no database and\ncannot answer the refusals a read of the configuration can. A\nserver that restarts forgets it, and the devices come back\nwithin a couple of minutes with fresh codes.",
        "operationId": "read_pending_devices_devices_pending_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/PendingDevice"
                  },
                  "type": "object",
                  "title": "Response Read Pending Devices Devices Pending Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/{mac}": {
      "get": {
        "summary": "Read Device",
        "description": "One device's binding. The MAC is normalized before it is\nlooked up, so `AA-BB-...` and `aa:bb:...` reach the same\ndevice.",
        "operationId": "read_device_devices__mac__get",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Device",
        "description": "Bind one device to one or more agents. The MAC is normalized\nbefore it is written, so the two spellings reach one row.\n\nThe running server reads this binding, so the device meets it at\nits next check-in rather than at the next restart; what the\nacknowledgement says depends on whether the agents named are\nones that server loaded.",
        "operationId": "write_device_devices__mac__put",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceBinding"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Device",
        "description": "Remove one device's binding, which leaves the device unbound\nwhatever the default agent: it is refused at the handshake, and\nwith onboarding on it is offered a code to be claimed again.\nLive, with no agent to be loaded or not: the device stops being\nserved at its next check-in, though a conversation already\nrunning is left to finish.",
        "operationId": "remove_device_devices__mac__delete",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/default-agent": {
      "get": {
        "summary": "Read Default Agent",
        "description": "The agent a newly claimed device starts with, or null. Unset\nis a configuration rather than a missing entity, so this is never\na 404.",
        "operationId": "read_default_agent_default_agent_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DefaultAgent"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "put": {
        "summary": "Write Default Agent",
        "description": "Set the agent a newly bound device starts with. Read by the\nnext claim that names no agent, inside its own transaction, and\nby nothing else: it admits no device by itself (#612).\n\nNo housekeeping in the pending table either, which this route\nused to do: a default agent covers no device now, so every board\nshowing a code is still waiting to be claimed.",
        "operationId": "write_default_agent_default_agent_put",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DefaultAgentName"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Default Agent",
        "description": "Unset it, after which a claim naming no agent binds a device\nto vinga, the built-in agent, exactly as `default_agent: vinga`\ndoes. Idempotent, like the CLI: there is no such thing as a\ndefault agent that was already not set. Live, like the delete\nabove: the next claim naming no agent reads it.",
        "operationId": "remove_default_agent_default_agent_delete",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/providers/{stage}/{name}/secrets/{slot}": {
      "put": {
        "summary": "Write Provider Secret",
        "description": "Store one of this provider's credentials, encrypted. The slot\nis the option name the credential fills, such as api_key; a\nstored secret takes precedence over an environment reference\nwritten for the same slot. A credential is read as the provider\nis built, and the next reload builds it again.",
        "operationId": "write_provider_secret_providers__stage___name__secrets__slot__put",
        "parameters": [
          {
            "name": "stage",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Stage"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "slot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Slot"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecretValue"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Provider Secret",
        "description": "Remove one stored credential. A slot holding none is a 404.",
        "operationId": "remove_provider_secret_providers__stage___name__secrets__slot__delete",
        "parameters": [
          {
            "name": "stage",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Stage"
            }
          },
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "slot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Slot"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/mcp-servers/{name}/secrets/{slot}": {
      "put": {
        "summary": "Write Mcp Secret",
        "description": "Store one of this MCP server's credentials, encrypted. The\nslot is `env.<KEY>` or `headers.<Key>`, which is where the value\nwould otherwise have been written as a $VAR reference.\n\nRotation is exactly what the ciphertext half of the reload's\ndiff applies, so this carries the reload notice too: the entry\nis rebuilt with the fresh credential and reconnected.",
        "operationId": "write_mcp_secret_mcp_servers__name__secrets__slot__put",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "slot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Slot"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecretValue"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Mcp Secret",
        "description": "Remove one stored credential, which the next reload applies\nby rebuilding the entry without it.",
        "operationId": "remove_mcp_secret_mcp_servers__name__secrets__slot__delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "slot",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Slot"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{name}/rename": {
      "post": {
        "summary": "Rename Agent",
        "description": "Give one agent another name, moving every live reference to it\nin the same transaction: its device bindings, the default agent\nif it was one, what it remembered, and the conversation threads\nit owns.\n\nThe act the delete-and-create workaround cannot make. A binding\nand the default agent each refuse the delete half while they\nname the agent, so the workaround is six writes with the memory\nlost in the middle, and this is one transaction that leaves\nnothing dangling or writes nothing at all.\n\nWhat it does not rewrite is the record of what happened. A turn\nspoken last month was spoken by an agent whose name at the time\nwas the old one, and the row saying so is evidence rather than a\nreference, so the sessions, the turns and the events keep the\nnames they were written with.\n\nA POST because it is not idempotent: run twice, the second run\nfinds no agent under the old name and answers 404. The new name\nis a body rather than a second path segment because it is what\nthe request carries rather than part of what it addresses, and\nit is handed to the repository unread.\n\nRefused 409 when the destination is occupied, by an agent, by\nremembered facts or by recorded threads, since a rename may\nnever merge two pasts into one; 422 when the new name is not a\nname this deployment can address, is the one the agent already\nhas, or is vinga, the built-in agent's. No refusal quotes either\nname.",
        "operationId": "rename_agent_agents__name__rename_post",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentRename"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Either the new name is already taken somewhere this rename would write, by an agent, by remembered facts or by recorded conversation threads, or the configuration database's write lock is held by another request. A rename may never merge two pasts into one, which is why an occupied destination is refused rather than merged. Nothing was changed and neither name is quoted back. The held lock clears on its own and the request can be made again; an occupied destination does not clear, and what clears it is choosing another name or taking away what is filed under this one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The new name is not one this deployment can address, being empty once the surrounding whitespace is taken off, or holding a slash or a control character; or it is the name the agent already has once both are stripped, which is nothing to rename; or the body is not a JSON object with exactly one key, `to`, holding a string. Nothing sent is quoted back, which on this endpoint covers the new name in every refusal it can meet. Nothing was changed, and none of these clears on its own: each is answered by sending a different name or a different body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/pending/{code}": {
      "post": {
        "summary": "Add Device",
        "description": "Bind the device showing this activation code, and retire the\ncode.\n\nThe MAC comes from the pending entry, so the operator binds what\nthe board in front of them is showing rather than a MAC they\nhave to go and find. The write itself is the same repository\ncall `PUT /devices/{mac}` makes, so reference checking and\ntransactionality are inherited rather than restated, and the\nacknowledgement is the same one, naming the MAC that was bound.\n\nThe claim is atomic: the code is reserved before the write and\nconsumed after it, so two operators racing one code produce one\nbind and one retryable refusal. A write that fails releases the\nreservation, leaving the code claimable again, because the\ndevice is still showing it.\n\nThe agents are optional, which is where this differs from the\nwrite by MAC (#612): none named binds the device to the default\nagent, which the repository reads inside the write's own\ntransaction, so the acknowledgement is the only place the\noperator learns which agent that was.",
        "operationId": "add_device_devices_pending__code__post",
        "parameters": [
          {
            "name": "code",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Code"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PendingClaim"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/{mac}/rename": {
      "post": {
        "summary": "Rename Device",
        "description": "Give one device another name, which is what an agent says out\nloud about the board it is speaking through.\n\nIdentity an operator manages. The other half of the record, the\nlocation, is the half a conversation may change, and that split\nis the point of two verbs rather than one write of a whole\nrecord.\n\nA POST because it addresses the device by the MAC it has and\ncarries the name it is to have, exactly as an agent's rename\ndoes. Refused 404 for a MAC with no record, because renaming\nsomething that is not there addressed nothing; 409 when another\ndevice already answers to that name once case and spacing are\nfolded together; 422 for a name holding nothing but whitespace.\nNo refusal quotes the name.",
        "operationId": "rename_device_devices__mac__rename_post",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceRename"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/{mac}/replace": {
      "post": {
        "summary": "Replace Device",
        "description": "Put this device record on another board: the record answers at\nthe new MAC from now on, and its id, its name, its place, its\nbindings and what it remembers go with it.\n\nThe act delete-and-bind cannot make. Deleted and bound again, the\noperator gets a new id, an unnamed device in nowhere in\nparticular, and a memory stranded at an address no board is\nstanding at; this is one transaction that moves the record and\nwhat the room told it, or writes nothing at all.\n\nWhat it does not rewrite is the record of what happened. A\nsession was held with the board that was connected at the time,\nand the row saying so is evidence rather than a reference.\n\nA POST because it addresses the device by the MAC it has and\ncarries the address it is to have, exactly as a rename carries a\nname. Refused 404 for a source MAC with no record; 409 when\nanother record already answers at the new address or the\ndeployment already remembers a board there, neither of which\nretrying clears; 422 for an address that is not a MAC, or one\nthat is the address the device already has.",
        "operationId": "replace_device_devices__mac__replace_post",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceReplacement"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Either something the board swap would write is already taken, by a device record answering at the new address or by facts remembered about a board that stood there, or the configuration database's write lock is held by another request. A swap may never merge two records or two memories into one, because nothing afterwards could tell them apart and no second swap could separate them, which is why an occupied destination is refused rather than merged. Nothing was changed and neither address is quoted back. The held lock clears on its own and the request can be made again; an occupied destination does not clear, and what clears it is swapping onto an address nothing is bound to, or taking away what is filed under this one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/devices/{mac}/location": {
      "put": {
        "summary": "Write Device Location",
        "description": "Say where one device stands.\n\nFree text and not unique: two devices in one room is normal.\nRefused 404 for a MAC with no record, because a location is a\nfield of a device record and not a thing on its own.",
        "operationId": "write_device_location_devices__mac__location_put",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeviceLocation"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove Device Location",
        "description": "Back to nowhere in particular, which is an ordinary state for\na device. Idempotent, like the CLI: a device that had no\nlocation still has none afterwards.",
        "operationId": "remove_device_location_devices__mac__location_delete",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Acknowledgement"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "Nothing of that identity exists.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/apply": {
      "post": {
        "summary": "Apply Document",
        "description": "Write a whole document: every entry it names, in one\ntransaction, or none of them.\n\nThe body is a partial domain configuration: its top-level keys\nare the sections of the configuration, an entity's body is\nexactly the fragment its own PUT takes, and the two settings are\nin the shape the configuration holds them in rather than the\nshape their own routes take, because this is the configuration\nand not a batch of requests.\n\nApplying is additive. A section or an entry the document does\nnot name is left alone, an empty mapping adds nothing, and\nnothing here deletes: pruning a store down to a document is a\ndifferent verb with different stakes, secret deletion among\nthem, and it is deliberately not this one. The single entry that\ntakes something away is `default_agent: null`, which is the\nexplicit unset; leaving the key out says nothing about it.\n\nIdempotent by comparison: an entry that is already exactly what\nthe document says is answered `unchanged`, with nothing written\nand nothing to apply, so the same document twice is a no-op.\n\nRefused whole. The references are checked once against the\nconfiguration the whole document would leave, which is what lets\none document create an agent and bind a device to it in the same\nbreath; any refusal names every mistake at once, in the\nsentences the single writes earn, and leaves the store exactly\nas it was.",
        "operationId": "apply_document_apply_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DomainConfig"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AppliedDocument"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Something this request needs is held by another one: the configuration database's write lock, the activation code a concurrent claim is already binding, or a reload of the MCP servers that is already running. Nothing was changed and the request can be retried.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/info": {
      "get": {
        "summary": "Read Runtime Info",
        "description": "Which deployment this is: the build that is running, and the\nURL a board is onboarded at.\n\nThe read that answers \"what server am I talking to\", which\nnothing else here does: the entity reads say what is stored, the\nreads below say what is running, and none of them says which\ndeployment is answering at all.\n\nIt carries a credential, and it is the only read in this API\nthat does. The onboarding URL's last segment is a key derived\nfrom the device-auth secret, standing in front of the token\nissuer, which is why the startup banner prints the origin and\nnot the URL: a banner is a retained record shipped to whatever\ncollects logs. Serving it here widens nothing, because the\nbearer token this request carried already grants every secret\nwrite this API has; what the design adds is that the answer is\nnot retained anywhere on the way, hence `Cache-Control:\nno-store` below, and that the one client rendering it prints it\non stdout alone.\n\nWith onboarding off the URL and its provenance are null and the\nflag says why, because there is no short URL to serve and the\npath `server.ota_path` names is this deployment's secret rather\nthan a substitute for one.\n\nAn application built without a server around it answers 503,\nlike the prompt read and the diff rather than like the MCP\nstatus read: an invented version is not an empty listing.",
        "operationId": "read_runtime_info_runtime_info_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RuntimeInfo"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there is no deployment for it to describe. Unlike the MCP status read beside it, there is no honest empty answer: a version and a revision are facts of the process that is serving, and an onboarding URL is derived from the file half a server booted from, so an application built without one would have to invent all three.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/invites": {
      "post": {
        "summary": "Issue Invite",
        "description": "Issue an invite link: a page a browser opens to join this\ndeployment as a device, bound before its first word to the\nagents the body names, or to the default agent when it names\nnone.\n\nThe answer carries a credential, and this is the one response\nthat does. `page` is the browser page's path with a token in its\nfragment, `/talk/#<token>`; whichever browser opens the link\nfirst redeems the token, and it is spent by that. Unopened, it\nexpires after `lifetime_s` seconds, and a restart of this server\nends it sooner, since links are held in the server's memory and\nnowhere else. A fragment is never sent to any server and never\nput in a `Referer`, so opening the link puts the token in no\naccess log on the way; this response carries `Cache-Control:\nno-store` so that nothing between the two ends keeps it either.\n\n`origin` is `server.public_url` when that opens a secure context\nin a browser, which is what a microphone needs, and null\notherwise: this server never names its listen address or a\nguess. A client that reached this API on a loopback address can\nname that host's own origin instead, which is what\n`vinga device invite` does.\n\nThe body is required, and `{}` is how to name no agent: a\nrequest that lost its body on the way would otherwise bind the\nbrowser to the default agent rather than to the agents it\nnamed. Every named agent has to be one this deployment has\n(422, `agents-unknown`) and one this server is serving (409,\n`agent-not-serving`), and neither refusal quotes a name.\n\nEach request is a new link. One is refused (409), with nothing\nissued, while device onboarding is off, while this server serves\na configuration no store describes, while this server is not\nserving the default agent (vinga, the built-in agent, when none\nis set) for an invite that names none (`default-agent-not-served`),\nand while as many links are\nwaiting as the server holds.",
        "operationId": "issue_invite_runtime_invites_post",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InviteRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Invite"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "No link was issued, and nothing was changed. Either the configuration database's write lock is held by another request, which clears on its own, or this deployment is in a state where opening a link could not bind a browser. Those states are five: device onboarding is off (`server.onboarding.enabled`), so there is no page and no short path for a browser to check in at; this server serves a configuration it was given rather than one a store describes, so a browser bound by a link would be written where this server does not read its devices from; the invite names an agent this server is not serving, so the browser would be bound to an agent that does not answer, which carries the `agent-not-serving` reason; the invite names no agent and this server is not serving the default agent, which is vinga, the built-in agent, when none is set, so the browser would be bound to an agent that does not answer, which carries the `default-agent-not-served` reason; and as many links are already waiting to be opened as the server holds. The last clears as links are opened or expire, the fourth when the default agent is served, the third when the apply that installs the agent has run, and the first two only with a change to how the server is started; the sentence says which one this is.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request names something that cannot be addressed, such as a stage that is not a provider stage or a MAC address that is not one.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there is nothing to hold an invite link and nothing a browser could redeem one against. A link issued here would be a token no server would ever accept.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/mcp-servers": {
      "get": {
        "summary": "Read Mcp Server Status",
        "description": "What each configured MCP server is doing right now.\n\nRuntime state of the server this application is mounted on, like\nthe pending listing: it touches no database, so it can answer\nnone of the refusals a read of the configuration can, and what\nit reports is the slice its managers were built with rather than\nanything read back out of storage.\n\n`async def`, unlike the repository's plain-`def` handlers, on\npurpose: the read then happens on the event loop that owns the\nmanagers, so it cannot interleave with a change to them and\nreport half of one world.\n\nAn application built without a server around it has no runtime\nto report and answers with an empty object, which is the honesty\n`loaded_agents = ()` already has.",
        "operationId": "read_mcp_server_status_runtime_mcp_servers_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": {
                    "$ref": "#/components/schemas/McpServerStatus"
                  },
                  "type": "object",
                  "title": "Response Read Mcp Server Status Runtime Mcp Servers Get"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/agents/{name}/prompt": {
      "get": {
        "summary": "Read Agent Prompt",
        "description": "The system prompt a session opening now as this agent would\nbe sent, block by block.\n\nA runtime read rather than a stored one: it is assembled from\nthe agents this server loaded, the MCP slice its registry is\nrunning and the memory store it writes, so it cannot disagree\nwith what a session would be given, which is the whole point of\nit.\n\nIt is a preview of a new session and says so, because there is\nno honest per-session answer to offer instead: a conversation\nalready in progress holds the know-how half it assembled at its\nown activation, which may predate a reload, and what an operator\naudits is what the configuration produces now.\n\nIt is keyed by the agent and by nothing else, so the memory it\nshows is the agent's own, and as much of it as a reply is sent:\nthe newest facts, not everything the agent has been told, since\nthe rest is reachable only by looking it up. The other two blocks\na live session can be sent, what a conversation is currently\nkeeping and what is known about the device it is happening on,\nbelong to a session rather than to an agent and are absent here:\na preview that invented a device to show its notes would be a\nsecond prompt assembler pretending to be the first. An agent\nwhose `memory` section is off has no such block at all, here or\nin a reply, and is previewed without one.\n\n`async def`, like the status read beside it: the MCP slice is\nread on the loop that mutates it, so the answer cannot be half\nof one world and half of another. The memory read that follows\nis a database round trip and happens in a worker thread, which\nis what keeps an inspection request off the loop every live\nconversation is on.\n\nAn agent this server is not serving is a 404 naming the reload,\nsince that is what installs one; an application with no server\naround it answers 503, like the reload.",
        "operationId": "read_agent_prompt_runtime_agents__name__prompt_get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AssembledPrompt"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No agent of that name is being served. An agent written since this server last installed a world waits for the reload that installs it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The request could not be read in the shape this endpoint expects. The refusal is the sanitized `Problem` body every other refusal uses, and nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there is no loaded agent, no running MCP slice and no memory store to assemble a prompt from. Unlike the MCP status read beside it, there is no honest empty answer: an empty block list would say a session opening now is sent nothing.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/config/reload": {
      "post": {
        "summary": "Reload Config",
        "description": "Apply the stored configuration to this running server.\n\nThe one action in this namespace that applies configuration,\nand the one way a stored change reaches a running server. What it applies is the whole\ndomain half: the provider entries and the MCP entries with the\nsecrets stored on them, the\nagents' effective `mcp` grant lists, the shared prompt\nfragments, the agents themselves and the `agent_defaults` layer\nunder them, which carries the stage every agent that names none\nof its own inherits, and the built-in agent's `builtin_agent`\noverrides. An agent this installs is one a device can\nbe bound to and reach at its next check-in; one it removes is\none no session can be opened as from the moment this answers,\nwhile a conversation already talking as it finishes on the world\nit was built from.\nWhat is not here is the server section, which is this process's\nown file and is never re-read: the port, the directories, the\nlimits. Nothing this API writes is in it.\n\nNothing is swapped, stopped or started until the whole new world\nhas been composed, validated and built, so a refusal (422) has\nchanged nothing at all. A server that merely will not connect is\nnot a refusal: it applies, and says `down` with its reason under\n`mcp.servers`, and is reconnected in the background when a\nsession that would use it opens.\n\nLive conversations are not dropped, and when one meets the\nresult depends on which half moved. The tools an agent may reach\nare snapshotted per reply, so a session picks those up on its\nnext utterance; a call in flight on a server this stopped fails\ninto the same error result a server dropping mid-call produces.\nPrompt text is assembled at an activation and cached for it, so\nan agent's own prompt, a fragment it includes and an entry's\n`instructions` alike reach a conversation at its\nnext activation, which is a new session or an agent switch, and\nnever a reply of one already running. Such an entry is reported `unchanged`\nunder `mcp`, which is a statement about its connection: the\nconnection is what did not change.\n\nThe engines are the third half and the one that costs\nsomething. An entry whose definition and stored credential have\nnot moved is carried into the new world as the object it already\nwas, and is reported under `providers.reused`; one that was\nrewritten is built while the old one is still serving, reported\nunder `providers.built`, and spoken through by the conversations\nthat open after this answered. An engine a conversation is still\nspeaking through is released when that conversation ends, so an\napply that changes a local model briefly holds two of it.\n\nThe world arrives in two steps, which is what makes the sentence\nabove per half rather than per apply: what a new activation\nassembles from is put in place first, and the MCP managers are\nstopped, started and swapped after it, so a session activating\nbetween the two sees the new prompts with the old tool world for\nat most one utterance. Nothing else can interleave, because one\napply runs at a time.\n\nOne apply runs at a time: a concurrent one is refused with 409\nand has changed nothing, like a write that could not take the\ndatabase's lock. A server serving a configuration that no store\ndescribes refuses with 409 as well, and says that starting from\na store is what changes it.",
        "operationId": "reload_config_runtime_config_reload_post",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfigReloadResult"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Either an apply of this server's configuration is already running, or the configuration database's write lock is held by another request, or this server serves a configuration that no store describes and so has nothing to apply. Nothing was changed. The first two clear on their own and the request can be made again; the third is what this server is, and only starting one from a store changes it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The stored configuration was refused: it does not compose into a valid snapshot, a credential stored in it will not open under the configured keys, or an engine it names could not be built (an unknown provider type or option, a model that would not load, an environment reference nothing sets, an entry `server.data_boundary` forbids). Nothing was swapped, stopped or started, and the running server is exactly as it was. What the `detail` says depends on which of those it was. A stored half that will not compose, or a credential that will not open, is refused without a location, which this refusal shares with the comparison read beside it and with nothing else in this API: what was refused is arbitrary stored state, and a sentence composed over it can quote a value that was written into the wrong field. A server started from this store refuses on the same state and names the location it refused on. An engine that would not build is refused with that server's own sentence instead, the one it prints on stderr before refusing to start. It names the entry, and with it whichever that refusal has to give: the option key, a provider type this deployment declares, the rule that was broken, or the class of the exception a factory raised. Which of them appear depends on what refused, and none of them is ever a stored value: an unknown provider type, in particular, is not quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there is nothing for a runtime action to act on. A deployment reaches the API on its server's own port; an application built without one serves the reads in the /runtime namespace emptily and refuses the actions.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/config/diff": {
      "get": {
        "summary": "Read Config Diff",
        "description": "What the database holds that this server is not serving, kind\nby kind, with the boundary each kind's changes converge at.\n\nThe read the other two in this namespace cannot give: they say\nwhat is running, the entity reads say what is stored, and the\nquestion an operator actually has after a write is what stands\nbetween the two. Everything in an answer here is waiting for the\nreload below, which is the whole of what applies this half;\ndevice bindings and the default agent are read as a device asks\nand are therefore never pending, so they carry their label and\nno lists.\n\nNames and labels, and nothing else. No entity bodies, no values,\nno masks and no secret marks cross this surface: what a\ncredential change looks like here is the entity holding it\nlisted as changed.\n\nThe stored half is the re-read the reload begins with, so a\nstored configuration that will not compose, or a credential in\nit that will not decrypt, is refused here under the status it\nwould be refused under there. That equivalence runs one way\nonly: this compares configuration and connects nothing, while a\nreload goes on to compose the world it would serve and to build\na server per referenced entry, and can still refuse on either,\nso an answer here says what has not been applied and never that\napplying it would succeed.\nThe running half is read on the loop that owns it, either side\nof that database read: a reload landing in between would leave\nthe two halves describing states that never existed together, so\nsuch an answer is not composed at all and the request is refused\nas retryable instead.",
        "operationId": "read_config_diff_runtime_config_diff_get",
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConfigDiff"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Either the configuration database's write lock is held by another request, the running world was replaced by a reload while this read was between its two halves, or this server serves a configuration that no store describes and so has nothing to compare. An answer built across a reload would describe two states that never existed together, so it is refused instead. Nothing was changed. The first two clear on their own and the request can be made again; the third is what this server is, and only starting one from a store changes it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The stored half was refused: it does not compose into a valid snapshot, or a credential stored in it will not decrypt under the configured keys. The `detail` is fixed and names nothing, which this refusal shares with the reload beside it and with nothing else this API answers with: what was refused is stored state, the sentence for it would be composed over that state, and this read's answers are entity names and labels only. A server started from this store refuses on the same state and names the location it refused on. Nothing was compared here and nothing was changed.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The stored configuration cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there is no world to compare the database with. Unlike the MCP status read beside it, there is no honest empty answer: an empty diff would say that everything stored is already in effect.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/runtime/events": {
      "get": {
        "summary": "Read Runtime Events",
        "description": "What this server is saying right now, as it says it.\n\nThe structured events, streamed as Server-Sent Events: one\n`data:` line per event, carrying the catalogued fields of that\nevent plus two the stream owns, `ts`, the wall-clock instant it\nwas emitted at, and `level`, its level's name. Those fields are\nthe ones the retained JSON log carries too, under the same\nnames; what the log has beside them is its own record-keeping,\nthe channel it was written on and the rendered sentence, which\nthis does not repeat. Nothing else crosses this surface, because\nthere is nothing else: the events are metadata by construction,\nand what was said in a conversation is in the conversation store\ninstead.\n\nLive and nothing but. There is no buffer behind this and no\n`since`: a stream carries what happens while it is open, and a\nreader that reconnects rejoins the present. What happened before\nis the conversation record's to answer, where a deployment\nenabled one.\n\nThree filters, applied as the events arrive. `device` takes a\nMAC in either separator and any case; `session` takes a\nsession's uuid hex; `level` is a threshold, one of the four\nlevel names in any case, and defaults to INFO, which is what the\nretained log carries. An event that names no device or no\nsession passes such a filter only when none is set, so a\ndevice-filtered tail is that board's traffic rather than the\nwhole server's.\n\nA reader that falls behind loses its oldest events rather than\nslowing the server down, and is told: a `dropped` event carries\nhow many went since the last delivery. An idle stream sends a\ncomment line every few seconds so a proxy does not close it, and\nthe stream ends when the client goes away or when the server\nshuts down.",
        "operationId": "read_runtime_events_runtime_events_get",
        "parameters": [
          {
            "name": "device",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Device"
            }
          },
          {
            "name": "session",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Session"
            }
          },
          {
            "name": "level",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Level"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "text/event-stream": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the three filters could not be read: `device` has to be a MAC address, `session` a session's uuid hex, and `level` one of the four level names in any case. Nothing sent is quoted back, here or in the server's log. This read addresses nothing and carries no body, so it has no other 422.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "503": {
            "description": "This application has no running server around it, so there are no events to stream. Unlike the MCP status read beside it, there is no honest empty answer: a stream that opened and said nothing is exactly what a quiet server looks like, so a caller could not tell the two apart.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/sessions": {
      "get": {
        "summary": "Read Sessions",
        "description": "The sessions this deployment recorded, newest first.\n\nFiltered by `device` when given, and paginated with `cursor`,\nwhich holds the sessions below it, so a client walks back through\nthe record one page at a time.",
        "operationId": "read_sessions_sessions_get",
        "parameters": [
          {
            "name": "device",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the sessions of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched. Anything that is not a MAC address is refused.",
              "title": "Device"
            },
            "description": "Only the sessions of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched. Anything that is not a MAC address is refused."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionList"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No session of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the cursor, the device filter or the day, or a purge named no selector at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Purge Sessions",
        "description": "Erase every session the selectors name, in one transaction.\n\nAt least one selector is required and several are combined with\nAND, so a purge always names less than everything. The semantics\nare the retired `conversations purge` command's, carried over\nrather than reopened: this is that command, as an act of the API\nwith the CLI in front of it.",
        "operationId": "purge_sessions_sessions_delete",
        "parameters": [
          {
            "name": "session",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only this session, by its uuid hex. The same erasure the addressed form of this resource performs, offered here so that one selector grammar covers every purge.",
              "title": "Session"
            },
            "description": "Only this session, by its uuid hex. The same erasure the addressed form of this resource performs, offered here so that one selector grammar covers every purge."
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the sessions of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched. Anything that is not a MAC address is refused.",
              "title": "Device"
            },
            "description": "Only the sessions of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched. Anything that is not a MAC address is refused."
          },
          {
            "name": "before",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the sessions that began strictly before this UTC day, written as YYYY-MM-DD. A session that began at any moment of the named day is not selected, which is what 'before the fifteenth' means. Anything else is refused.",
              "title": "Before"
            },
            "description": "Only the sessions that began strictly before this UTC day, written as YYYY-MM-DD. A session that began at any moment of the named day is not selected, which is what 'before the fifteenth' means. Anything else is refused."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "The conversation store's write lock is held by another writer. Nothing was deleted, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the cursor, the device filter or the day, or a purge named no selector at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{session}": {
      "get": {
        "summary": "Read Session",
        "description": "One session, whole: every column of its row, with how many\nturns and events hang off it.\n\nThe two counts are read in the same transaction as the row, so\nthey describe one snapshot rather than three moments of a\nsession that may still be running.",
        "operationId": "read_session_sessions__session__get",
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Session"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionDetail"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No session of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the cursor, the device filter or the day, or a purge named no selector at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Session",
        "description": "Erase one named session: its row, its turns wherever their\nthreads are, the calls those turns made, and its events.\n\nErasure outranks every copy the store derived from what is going\n(`threads.erase_sessions` says exactly which), and it is one\ntransaction, so a session's rows go together or none of them\ndoes. A session that is still running when its row goes stops\nbeing recorded at the writer's next marker; what it says after\nthat is not kept.\n\nA thread this leaves with nothing is deleted whole, and its\nmemory goes with it in the same transaction: what that\nconversation was keeping, and the facts it forgot and could have\nbrought back.",
        "operationId": "erase_session_sessions__session__delete",
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Session"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Erasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No session of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "The conversation store's write lock is held by another writer. Nothing was deleted, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the cursor, the device filter or the day, or a purge named no selector at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/sessions/{session}/turns": {
      "get": {
        "summary": "Read Session Turns",
        "description": "One session's timeline, oldest first, each turn carrying the\ncalls it made.\n\n`cursor` holds the turns strictly after it, which is the\ndirection a client reconciling what it has already read asks in:\nthe ids are monotonic and never reused, so what came after one is\na stable question.",
        "operationId": "read_session_turns_sessions__session__turns_get",
        "parameters": [
          {
            "name": "session",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Session"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionTurns"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No session of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the cursor, the device filter or the day, or a purge named no selector at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/conversations": {
      "get": {
        "summary": "Read Conversations",
        "description": "The threads this deployment recorded, most recently active\nfirst.\n\nFiltered by `agent` when given, and paginated with the pair\n`cursor_active` and `cursor_id`, which holds the threads below\nit. Activity moves, so the semantics under concurrent recording\nare stated rather than implied: a thread spoken to between two\npages moves ahead of the cursor and is missed by that pass,\nappearing at the head of a fresh one, and a page boundary never\nduplicates or skips a thread whose pair did not move.",
        "operationId": "read_conversations_conversations_get",
        "parameters": [
          {
            "name": "agent",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the threads of this agent, by the name the configuration gives it. Matched exactly and not refused for shape: an agent name is a word this deployment chose, and a name nothing answers to is an empty page rather than a mistake this API can recognize.",
              "title": "Agent"
            },
            "description": "Only the threads of this agent, by the name the configuration gives it. Matched exactly and not refused for shape: an agent name is a word this deployment chose, and a name nothing answers to is an empty page rather than a mistake this API can recognize."
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor_active",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The activity half of where to carry on from: the `last_active_at` of the last thread on the previous page, as an ISO-8601 instant carrying its UTC offset. Any offset is accepted and read as the instant it names; a calendar day or a local time written without one names no instant and is refused. Sent together with `cursor_id` or not at all; absent means the first page.",
              "title": "Cursor Active"
            },
            "description": "The activity half of where to carry on from: the `last_active_at` of the last thread on the previous page, as an ISO-8601 instant carrying its UTC offset. Any offset is accepted and read as the instant it names; a calendar day or a local time written without one names no instant and is refused. Sent together with `cursor_id` or not at all; absent means the first page."
          },
          {
            "name": "cursor_id",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The id half of the same cursor: the `id` of that thread, as a whole number. The page holds the threads strictly below the pair, which is what makes the order total where two threads share an activity stamp.",
              "title": "Cursor Id"
            },
            "description": "The id half of the same cursor: the `id` of that thread, as a whole number. The page holds the threads strictly below the pair, which is what makes the order total where two threads share an activity stamp."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationList"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the agent filter, or the two halves of the listing's cursor, which come together or not at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/conversations/{conversation}": {
      "get": {
        "summary": "Read Conversation",
        "description": "One thread, whole: its row, how many turns it holds across\nevery session, and the recap checkpoints hanging off it.\n\nEverything is read in the same transaction as the row, so it\ndescribes one snapshot rather than three moments of a thread\nthat may still be being spoken to.",
        "operationId": "read_conversation_conversations__conversation__get",
        "parameters": [
          {
            "name": "conversation",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Conversation"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationDetail"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No conversation of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the agent filter, or the two halves of the listing's cursor, which come together or not at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Conversation",
        "description": "Erase one named thread: its row, its turns out of whatever\nsessions they were spoken in, the calls those turns made, and\nits recap checkpoints.\n\nIts memory goes with it in the same transaction: what that\nconversation was keeping, and the facts it forgot and could have\nbrought back. What the agent remembers about the user and about\nthe device is not a thread's and stays.\n\nThe sessions themselves are untouched, and so is their\ntelemetry: a session is a connection episode and it still\nhappened, with a gap in it now. A thread that is still being\nspoken to when its row goes stops being recorded at the writer's\nnext marker, and the conversation in the room carries on.",
        "operationId": "erase_conversation_conversations__conversation__delete",
        "parameters": [
          {
            "name": "conversation",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Conversation"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ThreadErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No conversation of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "The conversation store's write lock is held by another writer. Nothing was deleted, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the agent filter, or the two halves of the listing's cursor, which come together or not at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/conversations/{conversation}/turns": {
      "get": {
        "summary": "Read Conversation Turns",
        "description": "One thread's dialogue, oldest first, each turn carrying the\ncalls it made and the session it was spoken in.\n\nThe row id cursor, not the pair the listing takes: a turn's id\nnever moves, so `cursor` holds the turns strictly after it and\nthe direction is the one a client reconciling what it has\nalready read asks in.",
        "operationId": "read_conversation_turns_conversations__conversation__turns_get",
        "parameters": [
          {
            "name": "conversation",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Conversation"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: a row id this API answered with, as a whole number. Absent means the first page. Anything else is refused."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConversationTurns"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No conversation of that id is in the conversation store.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: the limit, the agent filter, or the two halves of the listing's cursor, which come together or not at all. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/metrics": {
      "get": {
        "summary": "Read Metrics",
        "description": "The named aggregates this deployment serves, and what holds\nfor all of them.\n\nThe registry rather than the store: this opens no connection and\nanswers the same thing on a deployment that never recorded,\nbecause what it describes is what the schema declares rather\nthan what anybody wrote to it. A client discovers the vocabulary\nhere and then reads numbers at the path each view names.",
        "operationId": "read_metrics_metrics_get",
        "responses": {
          "200": {
            "description": "The views this deployment serves, each with the question it answers, the denominator its numbers are counted against, what telemetry-off does to it and the columns a row of it carries, and the statements that hold for all of them beside them.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricViews"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/metrics/{view}": {
      "get": {
        "summary": "Read Metric",
        "description": "One view over one window of whole UTC days, newest day first.\n\nThe window includes both of the days it names, and the answer\nrepeats the two it used, so a caller that sent neither can read\nthe default off what came back rather than recomputing the\nserver's own day.\n\nAn empty list is an ordinary answer here, and never a refusal. A\nwindow with nothing in it, a deployment that has switched\nrecording off since, and one that never recorded at all are the\nsame answer: the schema is migrated at every boot, so what a\ndeployment that never recorded has is empty tables, and an empty\nlist is the honest answer to a question about them.",
        "operationId": "read_metric_metrics__view__get",
        "parameters": [
          {
            "name": "view",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which view to read, by the word it is spelled with: the last segment of one of the paths `GET /metrics` lists. It resolves through a closed mapping derived from the declarations, so a name nothing answers to is refused rather than looked for, and no part of it reaches the database.",
              "title": "View"
            },
            "description": "Which view to read, by the word it is spelled with: the last segment of one of the paths `GET /metrics` lists. It resolves through a closed mapping derived from the declarations, so a name nothing answers to is refused rather than looked for, and no part of it reaches the database."
          },
          {
            "name": "since",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The first UTC day of the window, written as YYYY-MM-DD. The window begins on it rather than after it. Absent means 30 days before `until`, so the default window is that day and the 30 before it. Anything else is refused.",
              "title": "Since"
            },
            "description": "The first UTC day of the window, written as YYYY-MM-DD. The window begins on it rather than after it. Absent means 30 days before `until`, so the default window is that day and the 30 before it. Anything else is refused."
          },
          {
            "name": "until",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "The last UTC day of the window, written as YYYY-MM-DD. The window ends on it rather than before it. Absent means the current UTC day, which is the server's day and not the caller's. The two days may span at most 366, one leap year, and a wider window is refused rather than narrowed. Sent without a `since`, it also has to leave the default window room behind it: a day inside the first 30 of the calendar, which begins at 0001-01-01, is refused rather than answered from a day that does not exist, and naming a `since` asks about it.",
              "title": "Until"
            },
            "description": "The last UTC day of the window, written as YYYY-MM-DD. The window ends on it rather than before it. Absent means the current UTC day, which is the server's day and not the caller's. The two days may span at most 366, one leap year, and a wider window is refused rather than narrowed. Sent without a `since`, it also has to leave the default window room behind it: a day inside the first 30 of the calendar, which begins at 0001-01-01, is refused rather than answered from a day that does not exist, and naming a `since` asks about it."
          },
          {
            "name": "group",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How the rows are grouped, one of: `all`, `device`. Defaults to `all`, which groups by the view's own dimensions and nothing else. `device` reads the per-device sibling of the same view instead: the same question, with the device the session ran on and a label beside it added to what makes a row one row, and the answer's `view` carries that relation's own columns. Anything else is refused.",
              "title": "Group"
            },
            "description": "How the rows are grouped, one of: `all`, `device`. Defaults to `all`, which groups by the view's own dimensions and nothing else. `device` reads the per-device sibling of the same view instead: the same question, with the device the session ran on and a label beside it added to what makes a row one row, and the answer's `view` carries that relation's own columns. Anything else is refused."
          },
          {
            "name": "device",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Only the rows of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched, the way `/sessions` normalizes the same argument. Only meaningful with `group=device`, and refused without it rather than ignored. Absent means every device, including the rows of the sessions whose device was never understood, which group together under a null.",
              "title": "Device"
            },
            "description": "Only the rows of this device, by MAC. Colons or dashes, upper or lower case; it is normalized before it is matched, the way `/sessions` normalizes the same argument. Only meaningful with `group=device`, and refused without it rather than ignored. Absent means every device, including the rows of the sessions whose device was never understood, which group together under a null."
          }
        ],
        "responses": {
          "200": {
            "description": "The rows are the view's own, in the shape `columns` declares. What follows is\nwhat they cannot be made to say, which is the half a caller cannot compute\nfrom a number.\n\n### What is true of every one of them\n\n**A day is a UTC day.** `sessions.started_at` is UTC ISO-8601 text, and a turn\nand an event each carry `t_ms`, an offset from session open, so a row's day is\nits session's start converted to UTC plus that offset, cast to a date. Every\ncast names UTC, which is what stops the timezone of whoever is reading from\nmoving a row to the day before. A session is on the day it opened; its turns\nare on the day they were spoken, which is not always the same day.\n\n**Counting is per stored row.** Two provider failures in one turn are two,\ndeliberately. Each numerator stream is aggregated on its own before anything\nis joined, so an unrelated event beside a counted one cannot multiply a\ndenominator.\n\n**A rate is null when its denominator is zero**, never zero. Nothing happened\nand nothing could have happened are different facts, and a view that reported\nthem the same way would let a quiet day read as a healthy one.\n\n**Percentiles interpolate.** `p50_ms` and `p95_ms` are `percentile_cont`, so a\ntwo-turn day's p95 is mostly arithmetic between two numbers. The count they\nwere computed over is the column beside them; read it first.\n\n### Three limits worth knowing before quoting a number\n\n**Retention makes historical event rates a floor.** Turns survive with their\nconversation, by its last activity, while events are deleted by their own\nsession's age, so a recently resumed conversation can hold turns from\narbitrarily old sessions whose events are long gone. The database cannot tell\nzero events from events already pruned. So a rate read outside the events' own\nretention window is a floor, not a measurement, and zero cannot be told from\npruned. No windowing cleverness is attempted in the SQL: the honest sentence\nis the design.\n\n**A missing measurement has more than one cause, and these views cannot tell\nthem apart.** A null token count means telemetry storage was off OR the\nprovider reported no usage; a stage absent from the latency view means the\nswitch was off OR that stage was never measured on that turn. The store writes\nboth causes identically, so what a measured count reports is coverage and\nnever its reason: a gap between `turns` and `input_measured_turns` says those\ntokens were not recorded, and nothing about why. Read a measured count as a\ndenominator, never as a diagnosis.\n\n**`sessions.metrics` is the telemetry switch**, under the name the switch had\nbefore it was renamed. Column names are a compatibility surface and the rename\nwas not a schema change, so the column keeps the old spelling deliberately.\n`metrics_sessions_daily.telemetry_sessions` counts it, and it is session-level\ncontext for the day a session opened rather than a discriminator for the limit\nabove: a turn is dated by the day it was spoken, which need not be the day its\nsession opened, the column is not broken down by agent, and it knows nothing\nabout the second cause. A day where it sits below `sessions` had sessions that\nstored no measured number at all, and that is the whole of what it says.\n\n### What each view answers, and what telemetry-off does to it\n\n#### `stage-latency`\n\nHow slow was each pipeline stage, by UTC day and by the agent the turn started\nwith?\n\n**Telemetry-off.** A turn stored under telemetry-off has every stage column\nnull, so it contributes no row here at all. A turn that simply did not measure\na stage (a reply that spoke nothing has no `tts_first_audio_ms`) is absent\nfrom that stage in exactly the same way, and this view cannot tell the two\napart. Either way the turn still counts in `metrics_sessions_daily` and in the\nevent view's denominator, which is what makes `measured_turns` worth reading\nbeside a percentile.\n\n#### `tokens`\n\nWhat did each agent consume, by UTC day?\n\n**Telemetry-off.** Under telemetry-off both token fields are null, so the\nattribution row still lands and still counts in `turns` while adding nothing\nto either measured count and nothing to either sum. A turn whose provider\nreported no usage is null in exactly the same way, and this view cannot tell\nthe two apart: a gap between `turns` and a measured count says the tokens were\nnot recorded, and never why. `metrics_sessions_daily.telemetry_sessions` is\nsession-level context for the same day and not a discriminator here, because\nit counts sessions by the day they opened while these rows count turns by the\nday they were spoken, and it says nothing about which agent a turn was\nattributed to.\n\n#### `event-rates`\n\nHow often did a provider fail and how often was a barge-in suppressed, against\nthe traffic of the same day?\n\n**Telemetry-off.** A telemetry-off session writes no `events` rows at all,\nwhile its session and its turns still count. It therefore raises both\ndenominators and neither numerator, which is a property of the data this view\nreports rather than hides: read it beside\n`metrics_sessions_daily.telemetry_sessions`, which counts the same switch on\nthe same session spine. That is context and not a correction: both\ndenominators here are counted on the day a turn was spoken or a session\nopened, and neither can say which of the day's sessions a missing event\nbelonged to.\n\n#### `sessions`\n\nWhat baseline sits under the numbers in every other view?\n\n**Telemetry-off.** `telemetry_sessions` counts `sessions.metrics`, which is\nthe telemetry switch and keeps the name it had before the switch was renamed.\nSubtract it from `sessions` to get the sessions that could not have\ncontributed a measured number or an event to any other view. That is\nsession-level context for the day a session opened, and no more: it cannot say\nwhy a particular turn measured nothing, because a turn is dated by the day it\nwas spoken rather than the day its session opened, and because a null\nmeasurement elsewhere has a second cause (a provider that reported no usage, a\nstage that was never reached) that this column knows nothing about.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetricRows"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No metrics view of that name is served. GET /metrics lists the ones that are.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "One of the query arguments could not be read: a day, the window the two of them name, the grouping, or the device filter, which is only meaningful under the grouping that breaks the rows down by device. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "The conversation store cannot be read, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/agents": {
      "get": {
        "summary": "Read Agent Owners",
        "description": "Which agents are remembering anything, and how much.\n\nEvery name that has a row, whether or not this deployment still\nhas an agent of that name. A rename moves an agent's rows with\nit, so what turns up here with no agent behind it is one of two\nthings: a deleted agent's memory, or what a conversation still\nspeaking an old name wrote between a rename and the install that\napplied it. This listing is where an operator sees either.",
        "operationId": "read_agent_owners_memory_agents_get",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryOwners"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/devices": {
      "get": {
        "summary": "Read Device Owners",
        "description": "Which boards have notes about them, and how many.\n\nA device's notes are shared by every agent bound to it that may\nremember, so this is also the listing that says which places a\nhousehold's facts have accrued in. A board that has been\nreplaced leaves its notes behind, and they are answered here.",
        "operationId": "read_device_owners_memory_devices_get",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryOwners"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/conversations": {
      "get": {
        "summary": "Read Conversation Owners",
        "description": "Which conversations hold memory: what each is currently\nkeeping, and how much it has forgotten and could bring back.\n\nA thread's memory shares the thread's lifecycle, so a row here\nfor a thread the conversation record no longer has is a row the\nboot sweep has not reached yet. That is the audit point, and it\nis why nothing is filtered out.",
        "operationId": "read_conversation_owners_memory_conversations_get",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: the owner name this API answered as the previous page's `next_cursor`. The page holds the owners strictly after it, which is what makes the walk total over a set of names. Absent means the first page."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryConversations"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/agents/{name}/facts": {
      "get": {
        "summary": "Read Agent Facts",
        "description": "What one agent remembers, oldest first, with the numbers a\ncorrection and a deletion are addressed by.\n\nThe whole of the scope rather than the part a prompt carries: a\nreply is sent the newest of these inside a byte cap and reaches\nthe rest by looking them up, and what an operator is auditing is\neverything that is stored. Facts this agent has forgotten are\nhere too, marked by `forgotten_at`.\n\nAn agent with nothing stored answers an empty page rather than a\nrefusal, which is also the answer for a name nothing is\nconfigured under.",
        "operationId": "read_agent_facts_memory_agents__name__facts_get",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: a fact id this API answered with, as a whole number. The page holds the facts after it. Absent means the first page.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: a fact id this API answered with, as a whole number. The page holds the facts after it. Absent means the first page."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryFacts"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Agent Memory",
        "description": "Erase everything one agent remembers, in one transaction.\n\nAddressed at an owner rather than at a row, so an agent with\nnothing stored is erased of nothing and the count says so. This\nis the verb for an orphan the listings turned up: a deleted\nagent's rows, and the ones a conversation still speaking an old\nname wrote after a rename, have no other way out.",
        "operationId": "erase_agent_memory_memory_agents__name__facts_delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/devices/{mac}/facts": {
      "get": {
        "summary": "Read Device Facts",
        "description": "What is noted about one board and the place it stands in,\noldest first.\n\nShared by every agent bound to that board that may remember,\nwhich is the whole point of the scope and the thing worth\nauditing about it: a note made in one agent's conversation is\nread into every such sibling's prompt on that device, and\ntherefore reaches whatever provider each of them is configured\nwith. An agent whose `memory` section is off reads none of it,\nand writes none of it either.",
        "operationId": "read_device_facts_memory_devices__mac__facts_get",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused.",
              "title": "Limit"
            },
            "description": "How many rows this page may hold: a whole number from 1 to 200, defaulting to 50. Anything else is refused."
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "description": "Where to carry on from: a fact id this API answered with, as a whole number. The page holds the facts after it. Absent means the first page.",
              "title": "Cursor"
            },
            "description": "Where to carry on from: a fact id this API answered with, as a whole number. The page holds the facts after it. Absent means the first page."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryFacts"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Device Memory",
        "description": "Erase every note about one board, in one transaction, which\nis what a board leaving a household needs.",
        "operationId": "erase_device_memory_memory_devices__mac__facts_delete",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/agents/{name}/facts/{id}": {
      "put": {
        "summary": "Correct Agent Fact",
        "description": "Correct what one agent remembers, in place.\n\nThe number does not change and the fact keeps its place in the\nreading order, so a correction is a correction rather than a\ndeletion and a fresh write. What changes is the words and the\nmoment it was last written.\n\nThe same cap invariant every write to memory is held to: a fact\nwhose own line will not fit inside what its scope keeps for all\nof them is refused, because forgetting everything else would not\nmake room for it, and a correction that grows a fact re-prunes\nthe scope inside this transaction.\n\nA fact this agent has forgotten is not reachable here. It is\nwaiting to be brought back as it was said, and editing it there\nwould make that undo answer with something nobody said; erasing\nit below is the door that reaches it.",
        "operationId": "correct_agent_fact_memory_agents__name__facts__id__put",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else.",
              "title": "Id"
            },
            "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryCorrection"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryFact"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No fact of that number, or no entry of that name, is in this deployment's memory.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Agent Fact",
        "description": "Erase one thing an agent remembers.\n\nA hard delete, held facts included, and nothing here keeps it\nfor an undo: the soft forgetting an agent does belongs to the\nconversation that spoke it, and this door is correction and\naudit rather than that flow. What is removed is gone from the\nprompt of every conversation's next leg, live ones included: the\ndeletion is published to them once it has committed (#536).",
        "operationId": "erase_agent_fact_memory_agents__name__facts__id__delete",
        "parameters": [
          {
            "name": "name",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Name"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else.",
              "title": "Id"
            },
            "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No fact of that number, or no entry of that name, is in this deployment's memory.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/devices/{mac}/facts/{id}": {
      "put": {
        "summary": "Correct Device Fact",
        "description": "Correct one of a board's notes, in place, under the same\nrules the agent half is corrected under.",
        "operationId": "correct_device_fact_memory_devices__mac__facts__id__put",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else.",
              "title": "Id"
            },
            "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryCorrection"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryFact"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No fact of that number, or no entry of that name, is in this deployment's memory.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Erase Device Fact",
        "description": "Erase one of a board's notes, under the same rules.",
        "operationId": "erase_device_fact_memory_devices__mac__facts__id__delete",
        "parameters": [
          {
            "name": "mac",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Mac"
            }
          },
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else.",
              "title": "Id"
            },
            "description": "Which fact, by the `id` the facts listing answers with: a whole number, never reused. Written as a string here because it is parsed by this API rather than by the framework, whose own refusal for a path segment describes a request body; what it has to be is a number and nothing else."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No fact of that number, or no entry of that name, is in this deployment's memory.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/memory/conversations/{conversation}/state": {
      "get": {
        "summary": "Read Conversation State",
        "description": "What one conversation is currently keeping, by key.\n\nThe ledger the agent writes as it goes: the position on a board,\nthe scene it is in, what the lesson is up to. It is answered\nwhole rather than a page at a time, because a write past the\nledger's own caps is refused, so the whole of one is bounded.\n\nA thread that is keeping nothing answers an empty list, which is\nalso the answer for a thread that never existed.",
        "operationId": "read_conversation_state_memory_conversations__conversation__state_get",
        "parameters": [
          {
            "name": "conversation",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Conversation"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryState"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Clear Conversation State",
        "description": "Clear one entry of a conversation's ledger, or the whole of\nit.\n\nThe entry is named in the body and never in the path: a key is a\nword the model chose, so it can be credential-shaped, and a path\nreaches proxy and access logs where a body does not. A request\nwith no body at all clears the ledger, which is a deliberate\ndifference rather than a default: a request that lost its body\non the way would otherwise erase everything.\n\nA named entry that is not there is a 404. The whole-ledger form\nis not addressed at an entry, so it takes what is there and the\ncount says how much that was.\n\nThe deletion runs inside the order a thread's erasure publishes\nthrough, so it and a transaction erasing the same thread are\nordered rather than interleaved and this count is a count of\nrows this request took.",
        "operationId": "clear_conversation_state_memory_conversations__conversation__state_delete",
        "parameters": [
          {
            "name": "conversation",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Conversation"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful Response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MemoryStateErasure"
                }
              }
            }
          },
          "401": {
            "description": "The request carried no bearer token, or not the one this server was given.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "404": {
            "description": "No fact of that number, or no entry of that name, is in this deployment's memory.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "409": {
            "description": "Memory's write lock is held by another writer. Nothing was changed, and the same request may be made again.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "The limit or the cursor could not be read, the device in the path is not a MAC address, or the body is not the shape this endpoint takes. Nothing sent is quoted back.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "500": {
            "description": "Memory cannot be read or written, or the request failed for a reason that is not the caller's. The server's log names the class of what failed, and nothing else of it.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MemoryStateKey"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Acknowledgement": {
        "properties": {
          "wrote": {
            "type": "string",
            "title": "Wrote",
            "description": "What was written or deleted, naming the entity the way the `vinga-server config` command names it in the line it prints."
          },
          "notice": {
            "type": "string",
            "title": "Notice",
            "description": "When the change takes effect, as one of a handful of sentences, for a reader rather than for a program: `applies` beside it is the same fact in tokens, and it is the half to branch on. A device binding and the default agent are read by the running server as a device asks for them, so they apply at that device's next OTA check or connection with nothing asked of the server. Every other kind this API writes, which is the whole of the rest of the domain half (the provider entries, the MCP entries, the secret slots on either, the prompt fragments, the agents, `agent_defaults` and `builtin_agent`), is stored and waits for the stored configuration to be installed on the running server, which no restart is needed for. A binding naming an agent this server is not serving yet carries a sentence of its own, because both halves are true at once: the row is live, and the agent arrives with the install that adds it. So does a rename that moved a device binding or the default agent with the agent it renamed, for the same pair of reasons and about the references rather than about one binding; a rename that moved the agents row alone waits at the install like any other write of that kind. A server serving a configuration no store describes says that the write is stored and takes effect when a server boots from that store. Nothing this API writes waits for a server start."
          },
          "applies": {
            "items": {
              "$ref": "#/components/schemas/Applies"
            },
            "type": "array",
            "title": "Applies",
            "description": "Which boundaries this write is waiting at, as the closed tokens the comparison read publishes, so that a client can say what to do about it in its own words rather than parsing the sentence beside it. A set and not a token, because a binding naming an agent this server is not serving yet waits at two of them at once: the row is live at the device's next check-in, and the agent arrives at the install.\n\nAbsent rather than empty from a server older than the vocabulary, and that is the deliberate exception to the rule the rest of this API keeps (a field is nullable and required, never optional). An absent key here is a successful write answered by an image that predates this field, and turning that into a refusal would punish a client for the server's age after the write had already landed. Read it as absent when it carries a token you do not know: what a closed set gains a member for is a boundary that was not there before, and guessing what to do about one is worse than quoting the sentence.",
            "default": []
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "wrote",
          "notice"
        ],
        "title": "Acknowledgement",
        "description": "What a write answers with: what it did, and when it takes\neffect."
      },
      "AgentsDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "added": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Added",
            "description": "The names the database holds that this server is not serving, sorted."
          },
          "removed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Removed",
            "description": "The names this server is serving that the database no longer holds, sorted."
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The names both sides have and disagree about, sorted. Changed means the stored state differs from what this server is serving, never that something was written: an edit changed back before anyone looked is not here, and an entity whose stored credential was set again is, because what is compared is an opaque mark over the ciphertext and that moves even when the plaintext may not have."
          },
          "grants": {
            "$ref": "#/components/schemas/GrantsDiff"
          },
          "prompt": {
            "$ref": "#/components/schemas/PromptDiff"
          },
          "filler": {
            "$ref": "#/components/schemas/FillerDiff"
          },
          "fallback": {
            "$ref": "#/components/schemas/FallbackDiff"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "added",
          "removed",
          "changed",
          "grants",
          "prompt",
          "filler",
          "fallback"
        ],
        "title": "AgentsDiff",
        "description": "The agents. A reload applies the whole entry, so `changed` above\ncompares the whole entry, and the four entries below break that one\nanswer into the moments a conversation meets each part at: `grants`\nat its next utterance, `prompt` at its next activation, `filler` and\n`fallback` when the next conversation opens.\n\nA breakdown and not an exception: an agent whose prompt alone moved\nis in `changed` and in `prompt`, which is one change reported at the\naltitude an operator asks about it. The four carry `reload` for the\nsame reason the kind does, and they exist because the clocks differ\nand a single label cannot say which one an edit is on. The last two\nshare a clock and stay apart anyway, because they are re-synthesized\napart."
      },
      "AgentsReload": {
        "properties": {
          "added": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Added",
            "description": "The agents this server can serve now and could not before, sorted. A device bound to one of them reaches it at its next check-in."
          },
          "removed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Removed",
            "description": "The agents this server can no longer be asked for, sorted. A conversation already talking as one of them finishes on the world it was built with."
          },
          "defaults_changed": {
            "type": "boolean",
            "title": "Defaults Changed",
            "description": "Whether `agent_defaults` moved, which is a boolean because there is one of it for the whole deployment and nothing to name. What it changes reaches every agent that inherits the field that moved."
          },
          "builtin_changed": {
            "type": "boolean",
            "title": "Builtin Changed",
            "description": "Whether `builtin_agent`, the built-in agent's overrides, moved: a boolean for the reason `defaults_changed` is one. What it changes reaches the built-in agent alone, at its next activation. False from a server older than the built-in agent, which has no such entry to move.",
            "default": false
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "added",
          "removed",
          "defaults_changed"
        ],
        "title": "AgentsReload",
        "description": "What a reload did to the set of agents this server can serve.\n\nThe set moves at the swap and nowhere else: an agent named under\n`added` is servable from the instant this answered, and one under\n`removed` cannot be reached by anything that starts after it, while\nevery conversation already talking as it finishes on the world it\nwas built from."
      },
      "AppliedDocument": {
        "properties": {
          "entries": {
            "items": {
              "$ref": "#/components/schemas/AppliedEntry"
            },
            "type": "array",
            "title": "Entries",
            "description": "One entry per thing the document named, in the configuration's own section order. Empty for a document that named nothing. A document is written whole or not at all, so a 200 means every entry below was applied and any refusal means none of them was."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "entries"
        ],
        "title": "AppliedDocument",
        "description": "What applying one document did, entry by entry."
      },
      "AppliedEntry": {
        "properties": {
          "section": {
            "type": "string",
            "enum": [
              "providers",
              "mcp_servers",
              "prompt_fragments",
              "agent_defaults",
              "builtin_agent",
              "agents",
              "devices",
              "default_agent"
            ],
            "title": "Section",
            "description": "Which section of the domain configuration the entry is in: one of `providers`, `mcp_servers`, `prompt_fragments`, `agent_defaults`, `builtin_agent`, `agents`, `devices`, `default_agent`. The entries are listed in that order, which is the order the configuration documents as its write, read and creation order."
          },
          "identity": {
            "type": "string",
            "title": "Identity",
            "description": "The entry's identity under that section, as the row holds it rather than as the document spelled it: `<stage>.<name>` for a provider, the canonical form of the MAC for a device, the name for everything else. Empty for `agent_defaults`, `builtin_agent` and `default_agent`, which hold one thing rather than entries."
          },
          "outcome": {
            "type": "string",
            "enum": [
              "wrote",
              "unchanged"
            ],
            "title": "Outcome",
            "description": "Whether the row moved. `unchanged` means the entry was already exactly what the document says, so nothing was written for it and nothing has to be applied: the same document sent twice is a no-op by construction."
          },
          "notice": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Notice",
            "description": "What is true of this entry now, in the same sentences a single write of it is acknowledged with: a reader's half, saying what the write did and did not reach, and naming no command, because which command crosses a boundary is a fact of a client's grammar rather than of this server's. The boundary itself is `applies` beside it, which is the half to branch on. Null for an entry that was `unchanged`, which has nothing waiting to be applied."
          },
          "applies": {
            "items": {
              "$ref": "#/components/schemas/Applies"
            },
            "type": "array",
            "title": "Applies",
            "description": "Which boundaries this entry is waiting at, in the same tokens and under the same reading rule a single write's `applies` carries, and empty for an entry that was `unchanged`, which is waiting at none. Absent from a server older than the vocabulary, for the reason given there.",
            "default": []
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "section",
          "identity",
          "outcome",
          "notice"
        ],
        "title": "AppliedEntry",
        "description": "What applying one entry of a document did."
      },
      "Applies": {
        "type": "string",
        "enum": [
          "restart",
          "reload",
          "check-in",
          "store-boot"
        ],
        "title": "Applies",
        "description": "When a change reaches a conversation.\n\nFour boundaries and no fifth, because the server has four, and a\ncomparison of two worlds can announce three of them.\n\n`restart` is what this process reads once and serves until it is\nstarted again, which is now the file half alone: the port, the\ndirectories, the limits and everything else `server` holds, none of\nwhich this API writes. `reload` is what `POST\n/runtime/config/reload` applies while the process runs, which is the\nwhole domain half: the provider entries, the MCP entries, the shared\nprompt fragments, the agents, and `agent_defaults`. `check-in` is\nwhat a device is answered as it asks, the bindings and the default\nagent, which are therefore in effect within seconds of a write and\nnever pending at all.\n\n`store-boot` is the fourth and is a write's answer rather than a\ncomparison's: a server serving a configuration it was handed rather\nthan one it read from a store runs nothing that reads what was just\nwritten, so what is true of the write is that it is stored and that\na server booting from that store will serve it. Nothing is pending\nagainst the process that answered, which is why the comparison read\nnever reports this one and its own fields carry the other three."
      },
      "AssembledPrompt": {
        "properties": {
          "blocks": {
            "items": {
              "$ref": "#/components/schemas/PromptBlock"
            },
            "type": "array",
            "title": "Blocks",
            "description": "The blocks in the order they are sent, joined by one blank line each: the persona, then the shared fragments the agent includes in the order its layer lists them, then the guidance of each MCP entry the agent is granted in grant order, and within one entry what its operator wrote, then what the server ships about itself, then the prompts it publishes in the order the entry names them, and then the remembered facts. The order is fixed and not configurable. A block that would hold nothing is not sent and is not listed, which is what an agent with no prompt of its own produces."
          },
          "characters": {
            "type": "integer",
            "title": "Characters",
            "description": "The whole prompt's length in characters, which is the sum of the blocks plus the blank line between each pair of them. The prompt is the blocks joined and nothing else, so a character counted here is a character the model receives."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "blocks",
          "characters"
        ],
        "title": "AssembledPrompt",
        "description": "The system prompt a session opening now as this agent would be\nsent."
      },
      "BuiltinAgentStatus": {
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "served",
              "displaced",
              "unprovided"
            ],
            "title": "Status",
            "description": "`served`, or why not: `displaced` when an agent stored under the name vinga is served in its place, which a rename of that agent and an apply clear; `unprovided` when a provider stage resolves through neither `builtin_agent` nor `agent_defaults`. A client maps a token it knows to its own remedy and says the token it does not."
          },
          "stages": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Stages",
            "description": "The provider stages that resolve nowhere, in pipeline order, for `unprovided`; empty for the other two."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "status",
          "stages"
        ],
        "title": "BuiltinAgentStatus",
        "description": "Whether the world this server has installed serves vinga, the\nbuilt-in agent, and if not, why not."
      },
      "ConfigDiff": {
        "properties": {
          "providers": {
            "$ref": "#/components/schemas/EntityDiff"
          },
          "mcp_servers": {
            "$ref": "#/components/schemas/EntityDiff"
          },
          "prompt_fragments": {
            "$ref": "#/components/schemas/EntityDiff"
          },
          "agent_defaults": {
            "$ref": "#/components/schemas/SingletonDiff"
          },
          "builtin_agent": {
            "$ref": "#/components/schemas/SingletonDiff"
          },
          "agents": {
            "$ref": "#/components/schemas/AgentsDiff"
          },
          "devices": {
            "$ref": "#/components/schemas/LiveKind"
          },
          "default_agent": {
            "$ref": "#/components/schemas/LiveKind"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "providers",
          "mcp_servers",
          "prompt_fragments",
          "agent_defaults",
          "builtin_agent",
          "agents",
          "devices",
          "default_agent"
        ],
        "title": "ConfigDiff",
        "description": "What the database holds that the running server is not serving,\nkind by kind, in the order the domain declares them.\n\nTwo of the kinds are worth a word beyond their shapes. A provider is\naddressed as `<stage>.<name>`, the identity the store keeps its\ncredentials under and the one every refusal prints, and one whose\nstored credential was rotated is changed, since what it talks to\nmoved as surely as if a field of it had. The MCP entries are\ncompared against the entries running now rather than the ones this\nprocess booted with, because the reload swaps that world while the\nprocess runs: an entry no agent references is compared like any\nother, so is one whose only edit is to the prompt fields a\nconnection never sees, and a change a reload has already applied is\nnot reported as pending. That last property is the whole of what\nthis read is for, and it now holds for every kind: an apply installs\nthe stored domain half whole, so a comparison taken after one is\nempty."
      },
      "ConfigDocument": {
        "properties": {
          "config": {
            "additionalProperties": true,
            "type": "object",
            "title": "Config",
            "description": "The domain half of the configuration (providers, MCP servers, prompt fragments, agent defaults, the built-in agent's overrides, agents, devices, the default agent) in the shape `docs/reference/domain-config.md` documents, with every secret-bearing value masked."
          },
          "secrets": {
            "items": {
              "$ref": "#/components/schemas/StoredSecretLocation"
            },
            "type": "array",
            "title": "Secrets",
            "description": "Where every secret stored in the database is, which the masked document above cannot say. A list rather than a mapping, because a location is three fields and not a key."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "config",
          "secrets"
        ],
        "title": "ConfigDocument",
        "description": "The whole domain configuration of one deployment, masked."
      },
      "ConfigReloadResult": {
        "properties": {
          "mcp": {
            "$ref": "#/components/schemas/McpReloadResult"
          },
          "prompts": {
            "$ref": "#/components/schemas/PromptsReload"
          },
          "fillers": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FillersReload"
              },
              {
                "type": "null"
              }
            ]
          },
          "providers": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ProvidersReload"
              },
              {
                "type": "null"
              }
            ]
          },
          "agents": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/AgentsReload"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "mcp",
          "prompts"
        ],
        "title": "ConfigReloadResult",
        "description": "What one reload applied to this running server, kind by kind, and\nwhat is running once it had been applied.\n\nOne request applies a stored change and says what the change was, so\nbelieving a write took effect when it did not takes a deliberate act\nof not reading the reply. Every section answers: a reload applies\nthe whole domain half, so there is no kind left whose section would\nhave to say that this build does not touch it. The four that are\ndeclared optional stay optional in the schema, because a client\ngenerated against an earlier one is holding a document that says\nthey may be null and narrowing that is a change to the contract for\nno gain."
      },
      "ConversationDetail": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The thread's monotonic row id, never reused. It is the second half of this listing's cursor: activity moves, so a page is asked for by the pair (`last_active_at`, `id`) rather than by a row id alone."
          },
          "conversation": {
            "type": "string",
            "title": "Conversation",
            "description": "The thread's uuid hex, which addresses the reads and the deletion below and which every turn of it carries."
          },
          "agent": {
            "type": "string",
            "title": "Agent",
            "description": "The agent this thread belongs to. A conversation has exactly one, for its whole life: a handover starts a thread of the incoming agent's rather than moving this one."
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title",
            "description": "What the thread is called, which is the earliest utterance stored on it, bounded. Null where text storage was off when it began, and null for a thread that has never stored one."
          },
          "device": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device",
            "description": "The device the thread was begun on, by MAC. A record of where it started rather than a binding: a thread is reachable from any device bound to its agent."
          },
          "incomplete": {
            "type": "boolean",
            "title": "Incomplete",
            "description": "Whether a write this thread needed was lost. Product state rather than telemetry, and deliberately outside the telemetry switch that zeroes `dropped` on a session: a thread with a hole in it is a thread with a hole in it however the switches are set."
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When the thread's first turn landed, as an ISO-8601 instant in UTC."
          },
          "last_active_at": {
            "type": "string",
            "title": "Last Active At",
            "description": "When its newest turn landed, in the same form. This is what the listing orders on and what retention measures, so it moves with every turn. Where the turn that wrote it has been erased it falls back to a lower bound, which the store's reference states exactly."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns this thread holds, across every session."
          },
          "milestones": {
            "type": "integer",
            "title": "Milestones",
            "description": "How many recap checkpoints this thread holds, which is the length of `checkpoints` below and is answered beside it so a caller counting them does not have to."
          },
          "checkpoints": {
            "items": {
              "$ref": "#/components/schemas/ConversationMilestone"
            },
            "type": "array",
            "title": "Checkpoints",
            "description": "The recap checkpoints themselves, oldest first. Short by construction: one lands per recap the user consented to, and they are deleted with the thread and with the content they summarized."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "conversation",
          "agent",
          "title",
          "device",
          "incomplete",
          "created_at",
          "last_active_at",
          "turns",
          "milestones",
          "checkpoints"
        ],
        "title": "ConversationDetail",
        "description": "One thread, whole: the summary's fields and what hangs off it.\n\nThe summary plus its checkpoints, which is the one thing a listing\nleaves out: a thread carries no other nested structure."
      },
      "ConversationList": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ConversationSummary"
            },
            "type": "array",
            "title": "Items",
            "description": "The threads on this page, ordered by `last_active_at` descending with `id` descending as the tie-break."
          },
          "next_cursor_active": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor Active",
            "description": "What to send as `cursor_active` for the page after this one: the `last_active_at` of the last item here. Null when this was the last page, and null together with `next_cursor_id`, which the two request parameters are also sent together or not at all."
          },
          "next_cursor_id": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor Id",
            "description": "What to send as `cursor_id` beside it: the `id` of the last item here. Two plain values rather than one opaque cursor, so nothing here is an encoding a later release has to keep reading."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor_active",
          "next_cursor_id"
        ],
        "title": "ConversationList",
        "description": "One page of the thread listing, most recently active first."
      },
      "ConversationMilestone": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The checkpoint's row id, and what a later checkpoint names as its `parent` when it consumed this one."
          },
          "from_turn": {
            "type": "integer",
            "title": "From Turn",
            "description": "The id of the first turn this recap actually read, and the first it covers. Coverage is the inclusive range from_turn through after_turn; turns below from_turn are outside it, dropped by the recap's own input budget exactly as truncation would have dropped them."
          },
          "after_turn": {
            "type": "integer",
            "title": "After Turn",
            "description": "The id of the last turn it read, and the last it covers. Rebuilding this thread's context reads this checkpoint plus the turns with a greater id."
          },
          "parent": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Parent",
            "description": "The checkpoint whose text was part of this recap's input, and null when none was. Content that reached this row only through an earlier recap is still this row's content, which is what makes erasure of it transitive."
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When the checkpoint was stored, as an ISO-8601 instant in UTC."
          },
          "text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Text",
            "description": "The recap, byte for byte as it was spoken to the user. Conversation content, so null where text storage was off, although the flow that writes one cannot run with text off."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "from_turn",
          "after_turn",
          "parent",
          "created_at",
          "text"
        ],
        "title": "ConversationMilestone",
        "description": "One recap checkpoint on a thread.\n\nWhat the agent said out loud when the user consented to a recap,\nwith the range of turns it summarized and the checkpoint it folded\ninto itself. The range is inclusive at both ends and is what keeps\nthe claim honest: a recap bounded by its own input budget records\nwhere its reading began, so nothing here says it covers turns it\nnever read."
      },
      "ConversationSummary": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The thread's monotonic row id, never reused. It is the second half of this listing's cursor: activity moves, so a page is asked for by the pair (`last_active_at`, `id`) rather than by a row id alone."
          },
          "conversation": {
            "type": "string",
            "title": "Conversation",
            "description": "The thread's uuid hex, which addresses the reads and the deletion below and which every turn of it carries."
          },
          "agent": {
            "type": "string",
            "title": "Agent",
            "description": "The agent this thread belongs to. A conversation has exactly one, for its whole life: a handover starts a thread of the incoming agent's rather than moving this one."
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Title",
            "description": "What the thread is called, which is the earliest utterance stored on it, bounded. Null where text storage was off when it began, and null for a thread that has never stored one."
          },
          "device": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device",
            "description": "The device the thread was begun on, by MAC. A record of where it started rather than a binding: a thread is reachable from any device bound to its agent."
          },
          "incomplete": {
            "type": "boolean",
            "title": "Incomplete",
            "description": "Whether a write this thread needed was lost. Product state rather than telemetry, and deliberately outside the telemetry switch that zeroes `dropped` on a session: a thread with a hole in it is a thread with a hole in it however the switches are set."
          },
          "created_at": {
            "type": "string",
            "title": "Created At",
            "description": "When the thread's first turn landed, as an ISO-8601 instant in UTC."
          },
          "last_active_at": {
            "type": "string",
            "title": "Last Active At",
            "description": "When its newest turn landed, in the same form. This is what the listing orders on and what retention measures, so it moves with every turn. Where the turn that wrote it has been erased it falls back to a lower bound, which the store's reference states exactly."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns this thread holds, across every session."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "conversation",
          "agent",
          "title",
          "device",
          "incomplete",
          "created_at",
          "last_active_at",
          "turns"
        ],
        "title": "ConversationSummary",
        "description": "One thread as the listing shows it."
      },
      "ConversationTurn": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The turn's monotonic row id, never reused. It is this timeline's cursor: a page asked for with it holds the turns after it."
          },
          "conversation": {
            "type": "string",
            "title": "Conversation",
            "description": "The thread this turn belongs to, by its uuid hex. A turn names both its session and its conversation, which is what makes the session timeline and the thread two readings of one set of rows: the turns of one session can belong to several threads, and one thread's turns can come from several sessions."
          },
          "t_ms": {
            "type": "integer",
            "title": "T Ms",
            "description": "The utterance's offset from session open, in milliseconds, aligned with its `heard` event and with the capture's audio for the same session."
          },
          "agent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent",
            "description": "The agent that owns this turn, which is the one it started with and therefore the one whose thread it is on. A handover makes it different from the session's and from the agent that finished the reply; the legs below are where a split reply comes apart."
          },
          "utterance": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Utterance",
            "description": "The utterance this turn answers, by its uuid hex, as the server minted it when the turn opened. The name a trace knows the turn by: one turn span is exported per utterance, so this is what joins a row here to the trace it went out under. A handover records two turns and both carry this same value, since both answer one utterance. Null for a row recorded before the correlation existed."
          },
          "heard": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Heard",
            "description": "What was said to the device, as transcribed. Null under text-off."
          },
          "heard_duration_s": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Heard Duration S",
            "description": "How long the utterance lasted, in seconds. Null under telemetry-off."
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "The language the transcript was recognized as. Neither a measured number nor conversation text, so it survives both switches."
          },
          "language_confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language Confidence",
            "description": "How sure the recognizer was of that language. Null under telemetry-off."
          },
          "reply": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reply",
            "description": "What the assistant said, the legs joined. Null under text-off, and null when the reply spoke nothing."
          },
          "legs": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/TurnLeg"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Legs",
            "description": "One entry per agent that took part, and present only when a handover split the reply. Null is a turn one agent answered whole, which is not the same as an empty list and never becomes one."
          },
          "asr_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Asr Ms",
            "description": "Transcription elapsed, in milliseconds. Null where none was measured this turn, and under telemetry-off."
          },
          "first_token_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "First Token Ms",
            "description": "Request to the reply's first token, in milliseconds. Null under telemetry-off."
          },
          "llm_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Llm Ms",
            "description": "The reply's LLM round durations summed, in milliseconds. Null under telemetry-off."
          },
          "tts_first_audio_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tts First Audio Ms",
            "description": "The reply's first synthesis request to its first audio bytes, in milliseconds, measured at the provider boundary and deliberately not at the device. Null when the reply spoke nothing, and under telemetry-off."
          },
          "rounds": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rounds",
            "description": "How many LLM rounds the reply took. Null under telemetry-off."
          },
          "input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Tokens",
            "description": "Input tokens summed across the turn's rounds; OTel's `gen_ai.usage.input_tokens`. Null when the provider reported no usage, and under telemetry-off."
          },
          "output_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Output Tokens",
            "description": "Output tokens summed across the turn's rounds; OTel's `gen_ai.usage.output_tokens`. Null when the provider reported no usage, and under telemetry-off."
          },
          "tool_calls": {
            "type": "integer",
            "title": "Tool Calls",
            "description": "How many calls this turn issued, which is how many entries the list below holds. Structural rather than telemetry: it survives both switches."
          },
          "tool_invocations": {
            "items": {
              "$ref": "#/components/schemas/ToolInvocation"
            },
            "type": "array",
            "title": "Tool Invocations",
            "description": "The calls the reply made, in the order the model issued them."
          },
          "session": {
            "type": "string",
            "title": "Session",
            "description": "The session this turn was spoken in, by its uuid hex, which addresses the session reads and names that session's capture triplet."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "conversation",
          "t_ms",
          "agent",
          "utterance",
          "heard",
          "heard_duration_s",
          "language",
          "language_confidence",
          "reply",
          "legs",
          "asr_ms",
          "first_token_ms",
          "llm_ms",
          "tts_first_audio_ms",
          "rounds",
          "input_tokens",
          "output_tokens",
          "tool_calls",
          "tool_invocations",
          "session"
        ],
        "title": "ConversationTurn",
        "description": "One turn as a thread's dialogue answers it.\n\nThe session timeline's turn with the session added. A turn names\nboth, which is what makes the two views two readings of one set of\nrows: the turns of one session can belong to several threads, and\none thread's turns can come from several sessions."
      },
      "ConversationTurns": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/ConversationTurn"
            },
            "type": "array",
            "title": "Items",
            "description": "The turns on this page, ascending by id, which is chronological."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one, and null when this was the last. The next page holds the turns after it, which is also how a client that read up to a turn asks for what has happened since."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "ConversationTurns",
        "description": "One page of a thread's dialogue, oldest first."
      },
      "DefaultAgent": {
        "properties": {
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name",
            "description": "The default agent's name, or null when none is set, in which case the default is vinga, the built-in agent, and a claim by activation code that names no agent binds the device to it. It admits no device either way: the devices map is always the allowlist."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "name"
        ],
        "title": "DefaultAgent",
        "description": "The agent a newly claimed device starts with."
      },
      "EntityDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "added": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Added",
            "description": "The names the database holds that this server is not serving, sorted."
          },
          "removed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Removed",
            "description": "The names this server is serving that the database no longer holds, sorted."
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The names both sides have and disagree about, sorted. Changed means the stored state differs from what this server is serving, never that something was written: an edit changed back before anyone looked is not here, and an entity whose stored credential was set again is, because what is compared is an opaque mark over the ciphertext and that moves even when the plaintext may not have."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "added",
          "removed",
          "changed"
        ],
        "title": "EntityDiff",
        "description": "One kind of named entity, as the difference between two worlds:\nwhat the database holds that the running server does not, what it no\nlonger holds, and what both have under one name and disagree about.\n\n`applies` is where this kind's changes converge, so a consumer\nrendering a pending indicator reads what to say from the answer\nrather than knowing it."
      },
      "Envelope": {
        "properties": {
          "entity": {
            "additionalProperties": true,
            "type": "object",
            "title": "Entity",
            "description": "The entity's body, with every secret-bearing value masked, in the shape a write of it accepts and resubmittable as it stands. A PUT of it replaces the model-shaped half and never the credentials stored beside it; a field this read leaves out is one whose absence is what it means, and it means the same absence on the way back. An environment reference reads back as itself; a value shown as the mask, `********`, resubmits as keep the stored value, which is substituted before the fragment is validated, and that mask written where nothing is stored is refused. Described rather than validated here, because the mask is not a value the entity model would accept on its own: the entity schemas under `components/schemas` are what say which keys a write may carry."
          },
          "secrets": {
            "additionalProperties": {
              "$ref": "#/components/schemas/SecretSlot"
            },
            "type": "object",
            "title": "Secrets",
            "description": "The slots holding a secret stored in the database, by slot name, and never their values: reads are masked. Empty for the kinds that can hold no stored secret (prompt fragments, agents, agent defaults, devices), so that every read has one shape. Display-only, and nothing to act on when resubmitting the entity above: a stored secret is left exactly as it is by a write of the entity, and rotating one is the secret PUT, which is the one door a plaintext value enters by."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "entity",
          "secrets"
        ],
        "title": "Envelope",
        "description": "One entity as a read returns it: the entity, and its stored-secret\nslots beside it."
      },
      "Erasure": {
        "properties": {
          "sessions": {
            "type": "integer",
            "title": "Sessions",
            "description": "How many session rows were deleted, at most one per selector match."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns went with them, including turns of a thread that is still live: erasing a session erases its dialogue wherever it belongs, and the thread honestly keeps a gap."
          },
          "tool_invocations": {
            "type": "integer",
            "title": "Tool Invocations",
            "description": "How many tool invocation rows hung off those turns."
          },
          "events": {
            "type": "integer",
            "title": "Events",
            "description": "How many events rows those sessions held. Zero for a session recorded under telemetry-off, which wrote none."
          },
          "conversations": {
            "type": "integer",
            "title": "Conversations",
            "description": "How many threads were deleted whole because they lost every turn. A thread that kept turns is not counted here: it survives, renamed from its earliest surviving turn if the one its title came from is gone."
          },
          "milestones": {
            "type": "integer",
            "title": "Milestones",
            "description": "How many recap checkpoints were deleted: those whose recorded coverage held an erased turn, every checkpoint descended from one along the `parent` lineage, and those belonging to a thread that went whole."
          },
          "state": {
            "type": "integer",
            "title": "State",
            "description": "How many notes the deleted threads were keeping went with them. A conversation's state shares its thread's lifecycle, so it is deleted in the same transaction and this count is as true as the others."
          },
          "held_facts": {
            "type": "integer",
            "title": "Held Facts",
            "description": "How many facts those threads had forgotten and could still have brought back went with them. What an agent remembers about the user or the device is not a thread's and is not counted here."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "sessions",
          "turns",
          "tool_invocations",
          "events",
          "conversations",
          "milestones",
          "state",
          "held_facts"
        ],
        "title": "Erasure",
        "description": "What a deletion took, per table.\n\nCounts rather than an acknowledgement sentence, because the caller\nof a purge asked about a set it named by selector and cannot know\nwhat was in it. Eight numbers rather than one, because the tables go\nfor different reasons: a session's own row, the turns that named it\nwherever their thread is, the invocations under those turns, the\nsession's telemetry, the recap checkpoints whose coverage held an\nerased turn, the threads left with nothing, and the two halves of\nthe memory those threads took with them."
      },
      "FallbackDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The agents whose stored `fallback` section differs from what this server is serving, sorted. A reload synthesizes the new phrase in each agent's own voice and the next session speaks it when a reply fails; a conversation already open keeps the phrase it opened on. Only agents both sides hold are compared, for the reason the prompt half gives, and only each agent's own section: what `agent_defaults.fallback` holds is inherited by every agent that configures none of its own, and an edit to it is reported against `agent_defaults` instead."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "changed"
        ],
        "title": "FallbackDiff",
        "description": "The agents whose failure phrase the stored configuration would\nmove, which is the half of an agent entry a reload synthesizes again\nand the next conversation opens on.\n\nBeside `filler` rather than folded into it, because the two are\nstaled apart: an operator who switched the latency mask off has not\nasked for a failure phrase to be sent to a voice, and the reverse."
      },
      "FillerDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The agents whose stored `filler` section differs from what this server is serving, sorted. A reload synthesizes the new clips in each agent's own voice and the next session plays them; a conversation already open goes on masking with the clips it opened on. Only agents both sides hold are compared, for the reason the prompt half gives, and only each agent's own section: what `agent_defaults.filler` holds is inherited by every agent that configures none of its own, and an edit to it is reported against `agent_defaults` instead."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "changed"
        ],
        "title": "FillerDiff",
        "description": "The agents whose filled pauses the stored configuration would\nmove, which is the half of an agent entry a reload synthesizes again\nand the next conversation opens on."
      },
      "FillersReload": {
        "properties": {
          "resynthesized": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Resynthesized",
            "description": "The agents whose filler clip was made again, sorted: a field of the effective `filler` section moved, or the voice that speaks it did, which is now a thing a reload can move as well. The whole section is the unit, so an edit to `delay_ms` alone is here too, with audio identical to what it replaced; every agent named here cost a round of text-to-speech work at the configured provider."
          },
          "reused": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Reused",
            "description": "The agents whose filler clip was carried over unchanged, sorted. Reuse is the point of the comparison: an edit to a prompt never re-synthesizes a clip, and neither does an edit to a provider entry no masked agent speaks through. Rewriting the entry one does speak through is the voice moving, and puts that agent under `resynthesized` instead."
          },
          "disabled": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Disabled",
            "description": "The agents whose synthesis failed, sorted. The reload applied and those agents run with the latency mask off, because a filler is a mask and a posture where a text-to-speech hiccup blocked a prompt fix would invert what matters. The next reload tries again."
          },
          "fallback_resynthesized": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Fallback Resynthesized",
            "description": "The agents whose failure phrase was spoken again, sorted: a field of the effective `fallback` section moved, or the voice that speaks it did. The whole section is the unit, so switching the section on is here too; every agent named here cost a round of text-to-speech work at the configured provider."
          },
          "fallback_reused": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Fallback Reused",
            "description": "The agents whose failure phrase was carried over unchanged, sorted. Kept apart from the filled pauses' own reuse on purpose: an edit to one section never sends the other's words to a voice, so an agent can be here while it is under `resynthesized` above."
          },
          "fallback_degraded": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Fallback Degraded",
            "description": "The agents whose failure phrase would not synthesize, sorted, the ones that outran the build's own per-phrase deadline included. The reload applied and those agents show their failed replies on the display without speaking them, which is what makes this a different outcome from `disabled` above: nothing was lost but the audio. A later reload retries one of them when its `fallback` section or the voice that would speak it changes, and not otherwise: the phrase is cached without audio rather than absent, so an apply that moved neither carries it over and reports the agent under `fallback_reused`. Restarting the server retries every one of them, since a start keeps nothing from the process before it."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "resynthesized",
          "reused",
          "disabled",
          "fallback_resynthesized",
          "fallback_reused",
          "fallback_degraded"
        ],
        "title": "FillersReload",
        "description": "What a reload did to the speech this server synthesizes ahead of\ntime: the filled pauses that mask a slow reply, and the phrase a\nfailed one says.\n\nThree outcomes per kind and no fourth, because a reload makes\nexactly one of three decisions about an agent that configures one.\nAn agent that configures neither, or has just switched one off, is\nin none of that kind's three: there was no decision to make about\nit, and naming it under an outcome would say there had been.\n\nTwo kinds rather than one set of lists, because one agent can meet\nthem differently: a filled pause carried over unchanged beside a\nfailure phrase just re-synthesized is one honest sentence about that\nagent, and a single set of outcomes could only tell it as two\ncontradictory ones.\n\nWhich clips a conversation plays is decided when it opens, so\neverything here reaches the next conversation and none of it changes\nwhat an open one is masking or failing with."
      },
      "GrantsDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The agents that would reach a different set of MCP tools once the stored configuration is applied, sorted. Compared through the same defaults-then-own rule the server derives an agent's grants by, so moving a grant between `agent_defaults` and an agent without changing what that agent reaches is not a change. Only the agents this server is serving are compared: one the database has added rides `added` above until a reload installs it, and one the database no longer holds is here while a reload would still revoke its tools."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "changed"
        ],
        "title": "GrantsDiff",
        "description": "The agents whose effective MCP grants the stored configuration\nwould move, which is the half of an agent entry a conversation meets\nat its next utterance rather than at its next activation."
      },
      "Invite": {
        "properties": {
          "origin": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Origin",
            "description": "The origin the link names, which is `server.public_url` when that opens a secure context in a browser (an `https://` origin, or a loopback host), and null otherwise. A browser's microphone needs a secure context, so this server never names the listen address or a guessed one; null leaves the origin to the client, which knows the address it reached this API on."
          },
          "page": {
            "type": "string",
            "title": "Page",
            "description": "The browser page's path with the token in its fragment, `/talk/#<token>`, to be appended to the origin. The token is a credential: it is spent by the first browser that opens the link and expires unopened after `lifetime_s`, and a restart of this server ends it early."
          },
          "lifetime_s": {
            "type": "integer",
            "title": "Lifetime S",
            "description": "How many seconds the link stands unopened from when it was issued."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "origin",
          "page",
          "lifetime_s"
        ],
        "title": "Invite",
        "description": "An invite link: what a browser opens to join this deployment as a\ndevice bound to the agents the invite named, or to the default agent.\n\nIt carries a credential, a token that binds whichever browser\nredeems it first. The token sits in the page's fragment, which a\nbrowser sends to no server and puts in no `Referer`, so opening the\nlink puts it in no log on the way; this answer is the one response\nthat carries it, sent to the operator who asked and to nobody else,\nunder `Cache-Control: no-store`."
      },
      "LiveKind": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies"
        ],
        "title": "LiveKind",
        "description": "A kind the running server reads as a device asks for it,\nanswered with its label and no comparison.\n\nDeliberately no lists. What is stored for a device binding or for\nthe default agent is served by the entity reads and is in effect by\nthat device's next check-in, so a `changed` here would dress a fact\nthat is not pending as a diff. The label is what keeps the knowledge\nof why in this server rather than in every consumer."
      },
      "McpReloadResult": {
        "properties": {
          "started": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Started",
            "description": "The entries that had no connection before this reload and have one now: newly written, or newly named by some agent's `mcp` list. Started is not connected: an entry here whose server was unreachable is `down` below, with its reason."
          },
          "restarted": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Restarted",
            "description": "The entries whose fragment or whose stored secrets changed. Their connections were closed and made again, so a rotated credential applies as this request answers rather than at some later boundary."
          },
          "stopped": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Stopped",
            "description": "The entries this server no longer connects: deleted, or no longer named by any agent. A deleted one is gone from the status below; a de-referenced one is still there, as `unused`."
          },
          "unchanged": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Unchanged",
            "description": "The entries that kept the connection they had. It is a statement about the connection and not about the entry's text: an entry whose `instructions` was rewritten is here, because that field configures a prompt rather than a connection, and restarting a live connection to apply it would drop mid-call tools and respawn a stdio child for nothing. The conversations using such an entry keep the tools they had and the guidance they were activated with; the new guidance reaches them at their next activation."
          },
          "servers": {
            "additionalProperties": {
              "$ref": "#/components/schemas/McpServerStatus"
            },
            "type": "object",
            "title": "Servers",
            "description": "What every configured entry is doing now that the reload has been applied, keyed by entry name: exactly what `GET /runtime/mcp-servers` answers, taken in the same breath so that applying and verifying are one round trip."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "started",
          "restarted",
          "stopped",
          "unchanged",
          "servers"
        ],
        "title": "McpReloadResult",
        "description": "What one reload did, and what is running once it had done it.\n\nBoth halves in one answer on purpose: the request that applies a\nchange is the request that says what the change was and how it came\nout, so believing a write took effect when it did not takes a\ndeliberate act of not reading the reply."
      },
      "McpServerStatus": {
        "properties": {
          "state": {
            "type": "string",
            "enum": [
              "connected",
              "down",
              "unused"
            ],
            "title": "State",
            "description": "What this entry is doing: `connected` and offering the tools below, `down` and offering none, or `unused` because no agent references it, so this server never built a connection for it at all."
          },
          "reason": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reason",
            "description": "Why a `down` server is down, as a fixed token this server owns: the class of the failure, or `DroppedAfterFailedCall` for a connection dropped after a tool call failed on it. Null when it is not down. Never a message the far side wrote, since an MCP server is a third party and its bytes are not this API's to publish."
          },
          "since": {
            "type": "string",
            "title": "Since",
            "description": "When this state was last entered, as an ISO-8601 instant in UTC. A new reason for staying down counts as entering it again, since it is a fresh failure. For an entry no agent references it is when the running configuration took effect."
          },
          "tools": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Tools",
            "description": "What this server published, under the names the model is given (`<entry>__<tool>`, sanitized). Empty while it is down. Only names cross this surface: a description, or the name a server listed before the publishing rule got to it, is bytes that server chose, and a server holding a credential of this deployment's could reflect it in either."
          },
          "grants": {
            "additionalProperties": {
              "anyOf": [
                {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                {
                  "type": "null"
                }
              ]
            },
            "type": "object",
            "title": "Grants",
            "description": "Which agents may reach this server, by agent name. The value is how much of the server the agent gets: null is the whole server, and a list is the tools that agent was allowed, by the published name without the entry prefix. Beside the published list above it, so an allowed name this server does not offer is answerable in one read."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "state",
          "reason",
          "since",
          "tools",
          "grants"
        ],
        "title": "McpServerStatus",
        "description": "One configured MCP server, as the running server sees it.\n\nThe listing is keyed by the entry's name, because that is what the\noperator wrote and what every tool the server publishes is prefixed\nwith."
      },
      "MemoryConversation": {
        "properties": {
          "conversation": {
            "type": "string",
            "title": "Conversation",
            "description": "The thread's uuid hex, which is what its ledger and the facts forgotten in it are keyed by, and what addresses the state read below. A thread the conversation record no longer has is still answered here, which is what makes this listing the audit door: what such a row means is that the boot sweep has not reached it yet."
          },
          "state": {
            "type": "integer",
            "title": "State",
            "description": "How many notes this conversation is currently keeping."
          },
          "held_facts": {
            "type": "integer",
            "title": "Held Facts",
            "description": "How many facts were forgotten in it and could still be brought back. They belong to an agent or to a board, not to this thread, but they share its lifecycle: the thread's erasure and its retention prune take them with it."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "conversation",
          "state",
          "held_facts"
        ],
        "title": "MemoryConversation",
        "description": "One conversation, and how much memory is keyed to it."
      },
      "MemoryConversations": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/MemoryConversation"
            },
            "type": "array",
            "title": "Items",
            "description": "The conversations on this page, ascending by `conversation`. A thread appears once whether it holds a ledger, forgotten facts, or both."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one: the `conversation` of the last item here. Null when this was the last page."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "MemoryConversations",
        "description": "One page of the conversations that hold memory."
      },
      "MemoryEntry": {
        "properties": {
          "key": {
            "type": "string",
            "title": "Key",
            "description": "What the entry is called, chosen by the model. It is the identity of the row: writing the same one again replaces what it held."
          },
          "value": {
            "type": "string",
            "title": "Value",
            "description": "What is currently true under that key, normalized to one line."
          },
          "updated_at": {
            "type": "string",
            "title": "Updated At",
            "description": "When it was last written, as an ISO-8601 instant in UTC."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "key",
          "value",
          "updated_at"
        ],
        "title": "MemoryEntry",
        "description": "One entry of one conversation's ledger."
      },
      "MemoryErasure": {
        "properties": {
          "facts": {
            "type": "integer",
            "title": "Facts",
            "description": "How many fact rows were deleted, held ones included. These are hard deletes and nothing here holds them for an undo: the spoken undo is the agent's door, and this one is correction and audit."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "facts"
        ],
        "title": "MemoryErasure",
        "description": "What a deletion of facts took."
      },
      "MemoryFact": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The fact's row id, never reused. It is what a correction and a deletion address, and it is this listing's cursor."
          },
          "fact": {
            "type": "string",
            "title": "Fact",
            "description": "The fact as it is stored, normalized to one line. It is content: somebody said it in a room, so what is here is what the model will be sent."
          },
          "at": {
            "type": "string",
            "title": "At",
            "description": "When it was last written, as an ISO-8601 instant in UTC. A correction refreshes it; being forgotten and brought back does not."
          },
          "forgotten_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Forgotten At",
            "description": "When it was forgotten, in the same form, and null while it is active. A non-null value is the whole of what marks a held fact: it is out of every prompt, out of the lookup and out of its scope's caps until the conversation below brings it back."
          },
          "forgotten_in": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Forgotten In",
            "description": "The conversation it was forgotten in, by uuid hex, and null while it is active. It is the one that can bring it back, and the thread whose end takes the row with it. Null exactly when `forgotten_at` is."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "fact",
          "at",
          "forgotten_at",
          "forgotten_in"
        ],
        "title": "MemoryFact",
        "description": "One remembered fact, as the operator surface answers it."
      },
      "MemoryFacts": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/MemoryFact"
            },
            "type": "array",
            "title": "Items",
            "description": "The facts on this page, ascending by id, which is the order they were stored in and the order the injected block reads in. Held facts are here beside the active ones, marked by their `forgotten_at`."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one: the `id` of the last item here, and the next page holds the facts after it. Null when this was the last page."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "MemoryFacts",
        "description": "One page of one owner's facts, oldest first."
      },
      "MemoryOwner": {
        "properties": {
          "owner": {
            "type": "string",
            "title": "Owner",
            "description": "Whose memory this is, read under the scope the path names: an agent's configured name, or a board's MAC in canonical form. It is what addresses the facts listing below it, and it is answered whether or not the deployment still has an agent or a device record of that name: deleting either leaves its rows where they were. Renaming an agent moves its rows with it, and replacing the board under a device moves that device's rows to the new address, so neither of those leaves an owner behind."
          },
          "facts": {
            "type": "integer",
            "title": "Facts",
            "description": "How many rows this owner holds, the ones it has forgotten included. A forgotten fact is held rather than erased until the conversation that forgot it ends, so it is part of what is stored and is counted here."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "owner",
          "facts"
        ],
        "title": "MemoryOwner",
        "description": "One agent or one board, and how much it is remembering."
      },
      "MemoryOwners": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/MemoryOwner"
            },
            "type": "array",
            "title": "Items",
            "description": "The owners on this page, ascending by `owner`, which is the sort order."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one: the `owner` of the last item here, and the next page holds the owners strictly after it. Null when this was the last page."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "MemoryOwners",
        "description": "One page of the owners in one scope, by owner."
      },
      "MemoryState": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/MemoryEntry"
            },
            "type": "array",
            "title": "Items",
            "description": "The entries, ascending by key, which is the order the injected block reads in: a ledger is a set of current truths rather than a history, so touching one entry does not move another."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items"
        ],
        "title": "MemoryState",
        "description": "What one conversation is currently keeping, whole.\n\nNot paginated, and that is a property of the thing rather than an\nomission: a ledger is bounded by the caps the store refuses a write\npast, so the whole of one is a page by construction."
      },
      "MemoryStateErasure": {
        "properties": {
          "state": {
            "type": "integer",
            "title": "State",
            "description": "How many ledger entries were deleted: one for a request naming a key, and the whole ledger for a request with no body."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "state"
        ],
        "title": "MemoryStateErasure",
        "description": "What a deletion of conversation state took."
      },
      "MetricCaveats": {
        "properties": {
          "heading": {
            "type": "string",
            "title": "Heading",
            "description": "What this group of statements is about, as the reference heads it."
          },
          "notes": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Notes",
            "description": "The statements themselves, in the order they are declared, as Markdown with the emphasis the reference renders: the lead of each one is what a reader skims for."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "heading",
          "notes"
        ],
        "title": "MetricCaveats",
        "description": "One headed group of the statements that hold for every view.\n\nServed rather than summarized. What a number cannot be made to say\nis the half a reader is most likely to be missing, so it travels\nwith the numbers instead of living only on a documentation page\nnobody opened."
      },
      "MetricColumn": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "The column's name, which is its key in every row below."
          },
          "type": {
            "type": "string",
            "title": "Type",
            "description": "Its SQL type, as the view produces it."
          },
          "meaning": {
            "type": "string",
            "title": "Meaning",
            "description": "What the value is, for whoever is about to quote it."
          },
          "units": {
            "type": "string",
            "title": "Units",
            "description": "The unit of the value and not its SQL type: `milliseconds`, `turns`, `failures per turn`. A column whose value has no unit says `none`, so a blank is always a defect rather than sometimes a truth."
          },
          "nullable": {
            "type": "boolean",
            "title": "Nullable",
            "description": "Whether the column can be null, which is never the same fact as zero: a rate with no denominator is null, and so is a measurement nobody recorded."
          },
          "formula": {
            "type": "string",
            "title": "Formula",
            "description": "How the view computes it."
          },
          "key": {
            "type": "boolean",
            "title": "Key",
            "description": "Whether this column is part of what makes a row one row. The key columns are what a page is ordered on: the day descending, then the rest ascending with nulls last, which is total and therefore reproducible."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "name",
          "type",
          "meaning",
          "units",
          "nullable",
          "formula",
          "key"
        ],
        "title": "MetricColumn",
        "description": "One output column of one view, as the registry declares it."
      },
      "MetricRows": {
        "properties": {
          "view": {
            "$ref": "#/components/schemas/MetricView",
            "description": "Which view answered, whole, so a client renders a row without a second request and without a table of column names of its own."
          },
          "common": {
            "items": {
              "$ref": "#/components/schemas/MetricCaveats"
            },
            "type": "array",
            "title": "Common",
            "description": "The same statements the listing carries, beside the numbers they qualify."
          },
          "since": {
            "type": "string",
            "title": "Since",
            "description": "The first UTC day of the window, as `YYYY-MM-DD` and inclusive. The day that was asked for, or the default when none was."
          },
          "until": {
            "type": "string",
            "title": "Until",
            "description": "The last UTC day of the window, in the same form and also inclusive."
          },
          "group": {
            "type": "string",
            "enum": [
              "all",
              "device"
            ],
            "title": "Group",
            "description": "How the rows were grouped."
          },
          "rows": {
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array",
            "title": "Rows",
            "description": "The rows, keyed by the column names above and carrying exactly those keys. Ordered by the day descending and then by the remaining key columns ascending with nulls last, which is total. A `date` is written as `YYYY-MM-DD`. An empty list is an ordinary answer: a window with nothing in it and a deployment that never recorded are the same answer, and neither is a refusal."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "view",
          "common",
          "since",
          "until",
          "group",
          "rows"
        ],
        "title": "MetricRows",
        "description": "One view over one window: the rows, and everything needed to read\nthem."
      },
      "MetricView": {
        "properties": {
          "view": {
            "type": "string",
            "title": "View",
            "description": "The word a request spells this view by, which is the last segment of its own path. Derived from the relation's name, so the set that can be asked for and the set that is declared are one set."
          },
          "relation": {
            "type": "string",
            "title": "Relation",
            "description": "The schema-qualified view this reads, for a client that has a Postgres connection and would rather select from it: the analyst role is granted on the whole `record` schema, and nothing here is served that a SQL client could not read itself."
          },
          "question": {
            "type": "string",
            "title": "Question",
            "description": "The question this view exists to answer."
          },
          "denominator": {
            "type": "string",
            "title": "Denominator",
            "description": "What its numbers are counted against, which is a column of the view rather than a number to go and find elsewhere."
          },
          "telemetry_off": {
            "type": "string",
            "title": "Telemetry Off",
            "description": "What telemetry storage being off does to this view in particular, which is not the same thing for all of them: the latency view produces no row at all for such a turn, while the event-rate view keeps its denominators and loses its numerators."
          },
          "columns": {
            "items": {
              "$ref": "#/components/schemas/MetricColumn"
            },
            "type": "array",
            "title": "Columns",
            "description": "Its columns, in the order a row carries them."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "view",
          "relation",
          "question",
          "denominator",
          "telemetry_off",
          "columns"
        ],
        "title": "MetricView",
        "description": "One named aggregate: what it answers, what it cannot say, and the\nshape of a row of it."
      },
      "MetricViews": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/MetricView"
            },
            "type": "array",
            "title": "Items",
            "description": "Every view, in declaration order: how slow, how much, the rates that need both, and the baseline underneath them."
          },
          "common": {
            "items": {
              "$ref": "#/components/schemas/MetricCaveats"
            },
            "type": "array",
            "title": "Common",
            "description": "The statements that hold for every view rather than for one column: how to read a number, and what a number here cannot be made to say."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "common"
        ],
        "title": "MetricViews",
        "description": "The views this deployment serves, and what holds for all of\nthem."
      },
      "PendingDevice": {
        "properties": {
          "mac": {
            "type": "string",
            "title": "Mac",
            "description": "The device's MAC in canonical form, which is the row a successful claim writes."
          },
          "client_id": {
            "type": "string",
            "title": "Client Id",
            "description": "The UUID the device sent as its Client-Id at its last check-in."
          },
          "board": {
            "type": "string",
            "title": "Board",
            "description": "The board type the device reported, such as waveshare-esp32-s3-touch-lcd-1.54, or `unknown` when it reported none. Whatever the device said, bounded in length and stripped of anything unprintable."
          },
          "firmware": {
            "type": "string",
            "title": "Firmware",
            "description": "The firmware version the device reported, or 0.0.0 when it reported none."
          },
          "first_seen": {
            "type": "string",
            "title": "First Seen",
            "description": "When this device first checked in, as an ISO-8601 instant in UTC."
          },
          "last_seen": {
            "type": "string",
            "title": "Last Seen",
            "description": "Its most recent check-in, in the same form."
          },
          "expires_at": {
            "type": "string",
            "title": "Expires At",
            "description": "When this code stops being claimable. The device re-checks every couple of minutes and displays whatever the fresh reply carries, so an expired code is replaced on the screen rather than leaving the device stranded."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "mac",
          "client_id",
          "board",
          "firmware",
          "first_seen",
          "last_seen",
          "expires_at"
        ],
        "title": "PendingDevice",
        "description": "One device waiting to be claimed, as the listing shows it.\n\nThe listing is keyed by the code, because the code is what the\noperator has: they are holding a board with six digits on it, and\nthe question the board model and the firmware version answer is\nwhich of these entries is that board."
      },
      "PromptBlock": {
        "properties": {
          "provenance": {
            "type": "string",
            "title": "Provenance",
            "description": "Where this block came from, as a fixed token this server owns: `persona` for the agent's own prompt, `fragment:<name>` for a shared prompt fragment the agent includes, `instructions:<entry>` for the guidance written on an MCP server entry the agent is granted, `server_instructions:<entry>` for the guidance that server ships about itself where the entry opted into it, `server_prompt:<entry>:<position>` for one of the prompts it publishes, at its position in that entry's `inject_prompts` counted from one, `memory` for what the agent remembers. The fragment and entry names are the operator's, and both have been through the rule that keeps them to `[A-Za-z0-9_-]+`; a published prompt is identified by its position rather than by its name, because the name is a string the server chose and this token is printed in logs."
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name",
            "description": "The name the entry's `inject_prompts` gave the published prompt this block came from, and null for every other kind of block. It is carried here and not in the provenance because it is a server-chosen string the operator copied into their configuration, so nothing bounds what it holds; this body is JSON-encoded and is one of the two places operator-written configuration is echoed back, which the tokens printed in logs and structured events are not."
          },
          "characters": {
            "type": "integer",
            "title": "Characters",
            "description": "How long this block is, in characters, counted on what is stored and sent. It is what an operator tunes a small model's context budget against, block by block."
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "The block as the model receives it, heading included, whoever wrote it: a surface that hid part of the prompt would fail its own purpose, which is to say what the model was given, and an entry that opted into a server's own guidance opted those bytes into this prompt. The provenance beside it is what says whose words they are."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "provenance",
          "characters",
          "text"
        ],
        "title": "PromptBlock",
        "description": "One block of an assembled system prompt."
      },
      "PromptDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The agents whose stored `prompt` or `prompt_includes` differs from what this server is serving, sorted. A reload applies both, and each agent that moved assembles the new text at its next activation. Only agents both sides hold are compared: an agent the database has added or deleted rides the added or removed lists above, which a reload applies whole, and nothing about its prompt is separately pending here. The fragments the includes name are their own kind, and an edit to a fragment's text is reported there rather than against every agent that carries it."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "changed"
        ],
        "title": "PromptDiff",
        "description": "The agents whose prompt text the stored configuration would move,\nwhich is the half of an agent entry a reload has assembled again at\nthe next activation."
      },
      "PromptsReload": {
        "properties": {
          "changed": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Changed",
            "description": "The agents whose own prompt or whose resolved shared fragments now differ from what this server was serving, sorted. Each of them assembles the new text at its next activation, which is a new session or an agent switch; a conversation already in progress keeps the prompt it was activated with. The MCP guidance that also goes into an assembly is not counted here: what moved there is reported entry by entry under `mcp`, since that is where a connection is what changed. An agent this reload added or removed is not here either: it is named under `agents`, since an agent that has just arrived has no previous text to differ from and one that has just gone will not assemble again."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "changed"
        ],
        "title": "PromptsReload",
        "description": "The prompt text a reload put in front of the agents that use it."
      },
      "ProvidersReload": {
        "properties": {
          "built": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Built",
            "description": "The provider entries this reload constructed, as `<stage>.<name>`, sorted: written since, or changed in a way that a running instance cannot be."
          },
          "reused": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Reused",
            "description": "The provider entries carried into the new world as the objects they already were, sorted. An entry whose model and stored credentials are unchanged is never built again, which is what keeps a prompt edit from reloading a local model."
          },
          "retired": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Retired",
            "description": "The provider entries no world after this one uses, sorted. Their resources are released once the last conversation holding them has ended, not at the instant this answered."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "built",
          "reused",
          "retired"
        ],
        "title": "ProvidersReload",
        "description": "What a reload did to the built providers."
      },
      "RuntimeInfo": {
        "properties": {
          "version": {
            "type": "string",
            "title": "Version",
            "description": "The package version of the server answering, which says what this is rather than which build of it."
          },
          "revision": {
            "type": "string",
            "title": "Revision",
            "description": "Which build of it: the revision baked into the image, or what `git describe` says of the checkout it runs from, or `unknown` when neither is there to read. It is what matches a running server to the change that produced it."
          },
          "onboarding_enabled": {
            "type": "boolean",
            "title": "Onboarding Enabled",
            "description": "Whether this deployment serves the short onboarding path a person can type into a device's captive portal (`server.onboarding.enabled`). False leaves the two fields below null: devices are configured at the path `server.ota_path` names, which is this deployment's secret and is not answered here."
          },
          "onboarding_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Onboarding Url",
            "description": "The URL to type into a device's captive portal, or null when onboarding is off. It is the origin this deployment names itself by and the derived key after it, the same value `vinga ota-url` prints from the file half alone, so a deployment names itself identically wherever it is named. It is a credential: the key stands in front of the token issuer."
          },
          "onboarding_provenance": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Onboarding Provenance",
            "description": "Where the origin in that URL came from, in the words the startup banner uses (`from server.public_url`, `guessed from the listen address, ...`), or null when onboarding is off. Two of the three sources are inferences, so a URL that named neither would read as fact. It is null exactly when the URL above is, and non-null exactly when that is: the three fields are one fact and this shape refuses a body that makes them two."
          },
          "builtin_agent": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/BuiltinAgentStatus"
              },
              {
                "type": "null"
              }
            ],
            "description": "Live, unlike the fields above: whether the world installed when this request was answered serves vinga, the built-in agent, read per request so an apply that changes it is reflected at once. Null only from a server older than the built-in agent."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "version",
          "revision",
          "onboarding_enabled",
          "onboarding_url",
          "onboarding_provenance"
        ],
        "title": "RuntimeInfo",
        "description": "Which deployment this is: the build that is running, the URL a\nboard is onboarded at, and whether the built-in agent is served.\n\nThe one answer to \"what server am I talking to\". Every field of it\nbut the last is a fact of the process and of the file half it booted\nfrom, neither of which a reload moves, so those are composed once at\nstartup and answered as they stand. The last, `builtin_agent`, is the\none live field: an apply can change it, so it is read from the world\ninstalled at the moment of the request.\n\nIt carries a credential, and it is the only read here that does. The\nonboarding URL's last segment is a key derived from the device-auth\nsecret and it stands in front of the token issuer, which is why the\nstartup banner deliberately prints the origin and not the URL. The\ngate in front of this API is what makes serving it here no wider\nthan what the caller already holds: the bearer token grants\neverything this API can do, secret writes included. The response\ncarries `Cache-Control: no-store` for the same reason, and the one\nclient that renders it prints it on stdout and nowhere else."
      },
      "SecretSlot": {
        "properties": {
          "shadows": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Shadows",
            "description": "The entity key this stored secret displaces, or null when the entity writes no reference for the slot. A stored secret takes precedence over an environment reference written for the same slot, and this names what it takes the place of."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "shadows"
        ],
        "title": "SecretSlot",
        "description": "One slot of an entity that holds a secret stored in the database."
      },
      "SessionDetail": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The session's monotonic row id, the listing's cursor."
          },
          "session": {
            "type": "string",
            "title": "Session",
            "description": "The session's uuid hex."
          },
          "device": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device",
            "description": "The device's MAC in canonical form, or null when none was understood."
          },
          "device_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device Name",
            "description": "What that device was called when this session opened, or null where no name is recorded for it: a board or a browser nobody has named, a MAC a default agent covers with no record behind it, and every session that opened before the column existed. Dated rather than current: renaming the device or replacing its board does not change what a recorded session says."
          },
          "client": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Client",
            "description": "The client identifier the device announced, when it announced one."
          },
          "agent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent",
            "description": "The agent the session opened with, before any handover."
          },
          "agents": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agents",
            "description": "Every agent the device is bound to, by name, as the binding resolved at open. The first is the agent the session started on."
          },
          "protocol": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Protocol",
            "description": "The device protocol version this session negotiated."
          },
          "started_at": {
            "type": "string",
            "title": "Started At",
            "description": "When the session opened, as an ISO-8601 instant in UTC."
          },
          "closed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Closed At",
            "description": "When it closed, in the same form, or null."
          },
          "duration_s": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Duration S",
            "description": "How long it lasted, in seconds. Null under telemetry-off."
          },
          "close_reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "limit",
                  "idle",
                  "drain",
                  "client",
                  "error"
                ]
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Close Reason",
            "description": "What ended it, one of the five tokens the listing describes, or null until it closes."
          },
          "server_version": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Server Version",
            "description": "The server version that recorded this session."
          },
          "revision": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Revision",
            "description": "The build revision that recorded it."
          },
          "providers": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Providers",
            "description": "The resolved provider entry per pipeline stage, the same structure the capture manifest carries. It holds environment variable names, never credentials."
          },
          "telemetry": {
            "type": "boolean",
            "title": "Telemetry",
            "description": "Whether telemetry storage was on for this session, so a null number is distinguishable from a number that was never stored."
          },
          "text": {
            "type": "boolean",
            "title": "Text",
            "description": "Whether text storage was on for this session, so a null utterance is distinguishable from an utterance that was never stored."
          },
          "dropped": {
            "type": "integer",
            "title": "Dropped",
            "description": "Records this session lost: events refused at the writer's in-flight bound, and anything a failed transaction rolled back. The store recording its own incompleteness, the way the capture manifest records `complete`."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns this session holds."
          },
          "events": {
            "type": "integer",
            "title": "Events",
            "description": "How many events rows it holds: the decision track, `session_open` through `session_closed`. Zero under telemetry-off, where no events row lands. They are deliberately not served over REST; the database is that surface."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "session",
          "device",
          "device_name",
          "client",
          "agent",
          "agents",
          "protocol",
          "started_at",
          "closed_at",
          "duration_s",
          "close_reason",
          "server_version",
          "revision",
          "providers",
          "telemetry",
          "text",
          "dropped",
          "turns",
          "events"
        ],
        "title": "SessionDetail",
        "description": "One session, whole: its row and what hangs off it."
      },
      "SessionList": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/SessionSummary"
            },
            "type": "array",
            "title": "Items",
            "description": "The sessions on this page, newest first."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one, and null when this was the last: it is the id of the last item here, and the next page holds the sessions below it. Null means there is nothing further right now, not that there never will be; a listing re-read later starts from the top."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "SessionList",
        "description": "One page of the session listing, newest first."
      },
      "SessionSummary": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The session's monotonic row id, never reused. It is this listing's cursor: a page asked for with it holds the sessions before it."
          },
          "session": {
            "type": "string",
            "title": "Session",
            "description": "The session's uuid hex, which addresses the two reads below and names the capture triplet of the same conversation."
          },
          "device": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Device",
            "description": "The device's MAC in canonical form, and null when the session was rejected before one was understood."
          },
          "agent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent",
            "description": "The agent the session opened with, before any handover."
          },
          "started_at": {
            "type": "string",
            "title": "Started At",
            "description": "When the session opened, as an ISO-8601 instant in UTC."
          },
          "closed_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Closed At",
            "description": "When it closed, in the same form. Null in a session that is still running and in one whose close was never persisted, which a crash leaves behind."
          },
          "duration_s": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Duration S",
            "description": "How long it lasted, in seconds. A measured number: null under telemetry-off."
          },
          "close_reason": {
            "anyOf": [
              {
                "type": "string",
                "enum": [
                  "limit",
                  "idle",
                  "drain",
                  "client",
                  "error"
                ]
              },
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Close Reason",
            "description": "What ended it, one of `limit`, `idle`, `drain`, `client` or `error`, the first cause to fire winning. Null until it closes. The five tokens are the set a server latches, and the column that holds them is deliberately unconstrained, so a token a later release adds is served as it was stored: a read that refused one would drop a whole page over one row, the same reason the database refuses none."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns this session holds."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "session",
          "device",
          "agent",
          "started_at",
          "closed_at",
          "duration_s",
          "close_reason",
          "turns"
        ],
        "title": "SessionSummary",
        "description": "One session as the listing shows it."
      },
      "SessionTurn": {
        "properties": {
          "id": {
            "type": "integer",
            "title": "Id",
            "description": "The turn's monotonic row id, never reused. It is this timeline's cursor: a page asked for with it holds the turns after it."
          },
          "conversation": {
            "type": "string",
            "title": "Conversation",
            "description": "The thread this turn belongs to, by its uuid hex. A turn names both its session and its conversation, which is what makes the session timeline and the thread two readings of one set of rows: the turns of one session can belong to several threads, and one thread's turns can come from several sessions."
          },
          "t_ms": {
            "type": "integer",
            "title": "T Ms",
            "description": "The utterance's offset from session open, in milliseconds, aligned with its `heard` event and with the capture's audio for the same session."
          },
          "agent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent",
            "description": "The agent that owns this turn, which is the one it started with and therefore the one whose thread it is on. A handover makes it different from the session's and from the agent that finished the reply; the legs below are where a split reply comes apart."
          },
          "utterance": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Utterance",
            "description": "The utterance this turn answers, by its uuid hex, as the server minted it when the turn opened. The name a trace knows the turn by: one turn span is exported per utterance, so this is what joins a row here to the trace it went out under. A handover records two turns and both carry this same value, since both answer one utterance. Null for a row recorded before the correlation existed."
          },
          "heard": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Heard",
            "description": "What was said to the device, as transcribed. Null under text-off."
          },
          "heard_duration_s": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Heard Duration S",
            "description": "How long the utterance lasted, in seconds. Null under telemetry-off."
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language",
            "description": "The language the transcript was recognized as. Neither a measured number nor conversation text, so it survives both switches."
          },
          "language_confidence": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "title": "Language Confidence",
            "description": "How sure the recognizer was of that language. Null under telemetry-off."
          },
          "reply": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Reply",
            "description": "What the assistant said, the legs joined. Null under text-off, and null when the reply spoke nothing."
          },
          "legs": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/TurnLeg"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Legs",
            "description": "One entry per agent that took part, and present only when a handover split the reply. Null is a turn one agent answered whole, which is not the same as an empty list and never becomes one."
          },
          "asr_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Asr Ms",
            "description": "Transcription elapsed, in milliseconds. Null where none was measured this turn, and under telemetry-off."
          },
          "first_token_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "First Token Ms",
            "description": "Request to the reply's first token, in milliseconds. Null under telemetry-off."
          },
          "llm_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Llm Ms",
            "description": "The reply's LLM round durations summed, in milliseconds. Null under telemetry-off."
          },
          "tts_first_audio_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Tts First Audio Ms",
            "description": "The reply's first synthesis request to its first audio bytes, in milliseconds, measured at the provider boundary and deliberately not at the device. Null when the reply spoke nothing, and under telemetry-off."
          },
          "rounds": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Rounds",
            "description": "How many LLM rounds the reply took. Null under telemetry-off."
          },
          "input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Tokens",
            "description": "Input tokens summed across the turn's rounds; OTel's `gen_ai.usage.input_tokens`. Null when the provider reported no usage, and under telemetry-off."
          },
          "output_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Output Tokens",
            "description": "Output tokens summed across the turn's rounds; OTel's `gen_ai.usage.output_tokens`. Null when the provider reported no usage, and under telemetry-off."
          },
          "tool_calls": {
            "type": "integer",
            "title": "Tool Calls",
            "description": "How many calls this turn issued, which is how many entries the list below holds. Structural rather than telemetry: it survives both switches."
          },
          "tool_invocations": {
            "items": {
              "$ref": "#/components/schemas/ToolInvocation"
            },
            "type": "array",
            "title": "Tool Invocations",
            "description": "The calls the reply made, in the order the model issued them."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id",
          "conversation",
          "t_ms",
          "agent",
          "utterance",
          "heard",
          "heard_duration_s",
          "language",
          "language_confidence",
          "reply",
          "legs",
          "asr_ms",
          "first_token_ms",
          "llm_ms",
          "tts_first_audio_ms",
          "rounds",
          "input_tokens",
          "output_tokens",
          "tool_calls",
          "tool_invocations"
        ],
        "title": "SessionTurn",
        "description": "One utterance and the reply it got, with the calls the reply made."
      },
      "SessionTurns": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/SessionTurn"
            },
            "type": "array",
            "title": "Items",
            "description": "The turns on this page, ascending by id, which is chronological."
          },
          "next_cursor": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Next Cursor",
            "description": "What to send as `cursor` for the page after this one, and null when this was the last. The next page holds the turns after it, which is also how a client that read up to a turn asks for what has happened since."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "items",
          "next_cursor"
        ],
        "title": "SessionTurns",
        "description": "One page of a session's timeline, oldest first."
      },
      "SingletonDiff": {
        "properties": {
          "applies": {
            "type": "string",
            "enum": [
              "restart",
              "reload",
              "check-in"
            ],
            "title": "Applies"
          },
          "changed": {
            "type": "boolean",
            "title": "Changed",
            "description": "Whether the stored entry differs from the one this server is serving. A boolean rather than name lists, because there is one of these for the whole deployment and nothing to name."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "applies",
          "changed"
        ],
        "title": "SingletonDiff",
        "description": "A kind there is exactly one of, which therefore has nothing to\nname: it moved or it did not.\n\nCompared whole, grants included: a reload applies the whole layer,\nand what an edit to it reaches is every agent that inherits the\nfield that moved. Which agents those are is reported beside this,\nunder the agents' own three entries."
      },
      "StoredSecretLocation": {
        "properties": {
          "kind": {
            "type": "string",
            "title": "Kind",
            "description": "The kind of entity holding it: provider or mcp_server."
          },
          "identity": {
            "type": "string",
            "title": "Identity",
            "description": "The entity's identity: `<stage>.<name>` for a provider, the name for an MCP server."
          },
          "slot": {
            "type": "string",
            "title": "Slot",
            "description": "The credential slot inside that entity."
          },
          "shadows": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Shadows",
            "description": "The entity key this stored secret displaces, or null."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "kind",
          "identity",
          "slot",
          "shadows"
        ],
        "title": "StoredSecretLocation",
        "description": "Where one stored secret is, in the whole-configuration read."
      },
      "ThreadErasure": {
        "properties": {
          "conversations": {
            "type": "integer",
            "title": "Conversations",
            "description": "How many threads were deleted, which is one for an addressed erasure."
          },
          "turns": {
            "type": "integer",
            "title": "Turns",
            "description": "How many turns went with them, wherever they were spoken. Their sessions' own rows are untouched and keep the gap."
          },
          "tool_invocations": {
            "type": "integer",
            "title": "Tool Invocations",
            "description": "How many tool invocation rows hung off those turns."
          },
          "milestones": {
            "type": "integer",
            "title": "Milestones",
            "description": "How many recap checkpoints went: the thread's own, and everything descended from one along the `parent` lineage."
          },
          "state": {
            "type": "integer",
            "title": "State",
            "description": "How many notes this conversation was keeping went with it. Its state shares its lifecycle, so it is deleted in the same transaction and this count is as true as the others."
          },
          "held_facts": {
            "type": "integer",
            "title": "Held Facts",
            "description": "How many facts this conversation had forgotten and could still have brought back went with it. What the agent remembers about the user or the device is not this thread's and is not counted here."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "conversations",
          "turns",
          "tool_invocations",
          "milestones",
          "state",
          "held_facts"
        ],
        "title": "ThreadErasure",
        "description": "What erasing a thread took, per table.\n\nSix counts and deliberately not the eight a session erasure answers:\nerasing a thread takes its turns out of whatever sessions they were\nspoken in and touches neither those sessions nor their telemetry. A\nsession is a connection episode and it still happened, with a gap in\nit now.\n\nThe two about memory are here because a conversation's own memory is\nthe thread's rather than the session's: it goes when the thread does,\nin the same transaction, whichever door the deletion came through."
      },
      "ToolInvocation": {
        "properties": {
          "position": {
            "type": "integer",
            "title": "Position",
            "description": "Where this call sat in the round's call list, as the model issued it, counted from zero and with handovers included. The rows are nested in this order; it is the model's order and not the order they finished in."
          },
          "source": {
            "type": "string",
            "enum": [
              "builtin",
              "device",
              "mcp",
              "unknown"
            ],
            "title": "Source",
            "description": "Where the call was routed: `builtin` for one this application authors, `device` for one the device published, `mcp` for one an MCP entry owns, `unknown` for a name nothing answered to. Classified before the call ran. A closed set here because it is a closed set in the database, which holds the same four tokens under a check constraint."
          },
          "entry": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Entry",
            "description": "The owning MCP entry's configured name for an `mcp` call, and null otherwise. A name this deployment chose, so it survives text-off."
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Name",
            "description": "The called tool's name, and null when text storage was off for the session: a tool's name originates off this server, a device's self-description or an MCP far side, exactly as its result does."
          },
          "malformed": {
            "type": "boolean",
            "title": "Malformed",
            "description": "Whether the model's arguments were not a JSON object."
          },
          "arguments": {
            "anyOf": [
              {
                "additionalProperties": true,
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Arguments",
            "description": "What the model passed, null under text-off and null when the call was malformed, which is what `malformed` above tells them apart by."
          },
          "result": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Result",
            "description": "What the call answered, a refusal included. Null under text-off."
          },
          "is_error": {
            "type": "boolean",
            "title": "Is Error",
            "description": "Whether the call answered as an error."
          },
          "duration_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Duration Ms",
            "description": "How long the call took, in milliseconds. Null where nothing ran, as for a refused or a successful handover, and null under telemetry-off."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "position",
          "source",
          "entry",
          "name",
          "malformed",
          "arguments",
          "result",
          "is_error",
          "duration_ms"
        ],
        "title": "ToolInvocation",
        "description": "One call a turn issued, as the timeline nests it.\n\nThe transport shape of a `tool_invocations` row, not the record the\npipeline hands the writer, which is the dataclass of the same name\nin `records.py`."
      },
      "TurnLeg": {
        "properties": {
          "agent": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Agent",
            "description": "The agent whose leg this is, and null for a session that never activated one."
          },
          "text": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Text",
            "description": "What this agent said, null under text-off, and null for an agent that took part without speaking: one that asked for the handover said nothing and spent tokens all the same."
          },
          "input_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Input Tokens",
            "description": "Input tokens this agent spent on the turn. Null when the provider reported no usage, and under telemetry-off."
          },
          "output_tokens": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "title": "Output Tokens",
            "description": "Output tokens this agent spent on the turn. Null when the provider reported no usage, and under telemetry-off."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "agent",
          "text",
          "input_tokens",
          "output_tokens"
        ],
        "title": "TurnLeg",
        "description": "One agent's share of a turn a handover split.\n\nThe transport shape of one entry of `turns.legs`, whose halves\nfollow different storage switches: the text is content and the token\ncounts are measurements, which is why a leg exists at all rather\nthan the turn's totals being the whole story. The totals blend\nagents that may use different models; this is where they come apart\nagain."
      },
      "Reach": {
        "description": "How far session data handed to something travels.\n\nOne enum for both sides of the rule, because a boundary IS a reach:\nthe outermost reach session data may have on this server. A second\nenum would be two structures required to agree.\n\n`host` is the machine this process runs on and nothing beyond it.\n`network` is whatever the machine can address without leaving the\noperator's own network, which is the honest declaration for a model\nserver on the LAN. `internet` is everything else.",
        "enum": [
          "host",
          "network",
          "internet"
        ],
        "title": "Reach",
        "type": "string"
      },
      "ProviderConfig": {
        "additionalProperties": true,
        "description": "One provider entry. Options beyond `type` are passed through to the\nprovider implementation, so extra keys are allowed here.",
        "properties": {
          "type": {
            "description": "The provider implementation this entry configures, such as anthropic, openai_compatible, faster_whisper, openai, piper, elevenlabs or silero. Every key beyond the ones listed here is an option for that implementation.",
            "minLength": 1,
            "title": "Type",
            "type": "string"
          },
          "api_key_env": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The name of the environment variable holding this provider's credential, never the credential itself. Left unset for a local engine or a keyless self-hosted endpoint. A credential stored with `vinga provider secret set` fills the same slot and takes precedence.",
            "title": "Api Key Env"
          },
          "reach": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Reach"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "How far session data given to this entry travels, asserted by the operator for the types whose configuration decides it rather than their name (openai_compatible, and the openai ASR and TTS types, whose base_url may name this machine, a server on your network or a vendor). `host` is an endpoint on this machine, `network` one that stays on your own network, `internet` anything else. Under a `server.data_boundary` such an entry must declare it, and a reach exceeding the boundary refuses to boot; a type that knows its own reach rejects the key."
          }
        },
        "required": [
          "type"
        ],
        "title": "ProviderConfig",
        "type": "object"
      },
      "McpServerConfig": {
        "additionalProperties": false,
        "description": "One MCP server, named so agents can reference it.\n\n`transport` decides which of the two field groups applies: a stdio\nserver is a command this server spawns, a streamable_http one is a\nURL it connects to. Naming a field of the other transport is an\nerror rather than a silently ignored key, since the difference\nbetween \"my headers are ignored\" and \"my headers are wrong\" is a\ndebugging afternoon.",
        "properties": {
          "transport": {
            "description": "Which field group applies: stdio spawns `command` as a subprocess, streamable_http connects to `url`. Naming a field of the other transport is an error rather than a silently ignored key. An SSE-only endpoint is configured as a stdio server behind an mcp-proxy bridge, since the specification deprecated SSE in favour of streamable_http and there is no native arm for it here.",
            "enum": [
              "stdio",
              "streamable_http"
            ],
            "title": "Transport",
            "type": "string"
          },
          "command": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The executable a stdio server is spawned as. Required for that transport, and rejected for streamable_http.",
            "title": "Command"
          },
          "args": {
            "description": "The arguments the stdio command is spawned with, one per entry.",
            "items": {
              "type": "string"
            },
            "title": "Args",
            "type": "array"
          },
          "env": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Environment variables for the spawned stdio command. $NAME is read from the server's own environment at startup, either as the whole value or inside a larger one (`--token=$NAME`), and any secret-bearing key (token, api_key, authorization, ...) must reference a variable somewhere in its value. A literal $ followed by a name cannot be written: there is no escape for it.",
            "title": "Env",
            "type": "object"
          },
          "url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The endpoint a streamable_http server is reached at. Required for that transport, and rejected for stdio.",
            "title": "Url"
          },
          "headers": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Headers sent with every streamable_http request. $NAME is read from the server's own environment at startup, either as the whole value or inside a larger one (`Bearer $NAME`), and any secret-bearing key must reference a variable somewhere in its value. A literal $ followed by a name cannot be written: there is no escape for it.",
            "title": "Headers",
            "type": "object"
          },
          "reach": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Reach"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "How far session data given to this server travels: `host` for a command or URL that stays on this machine, `network` for one that stays on your own network, `internet` for anything else. Tool arguments carry conversation-derived data and neither transport can tell on its own, since a stdio command may proxy anywhere and a url may name localhost, so under a declared server.data_boundary every referenced entry must declare it, and a reach exceeding the boundary refuses to boot."
          },
          "tool_timeout_s": {
            "default": 15.0,
            "description": "How long one tool call on this server may take, in seconds, before the model is told it timed out. The device hears silence meanwhile, so keep it short.",
            "exclusiveMinimum": 0,
            "title": "Tool Timeout S",
            "type": "number"
          },
          "instructions": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Guidance for the model about using this server's tools, injected into the system prompt of every agent this entry is granted to, under a heading naming the prefix its tools carry. It is written for the whole entry rather than per tool, so guidance about a tool an agent's allow list withholds is noise the operator avoids by writing about the granted surface. The grant is the whole condition: it is injected whether or not the server is connected and whatever its tools turn out to be, and an agent with `mcp: []` never sees it. It is stored and injected as written, its indentation and its own blank lines included; the only bytes trimmed are whitespace at the two ends of the whole assembled prompt, which is also what the inspection surface reports. Editing it does not restart the connection, so a reload reports the entry as `unchanged`, and the new text reaches a conversation at its next activation: a new session or an agent switch, never a reply of a session already running.",
            "title": "Instructions"
          },
          "use_server_instructions": {
            "default": false,
            "description": "Whether to inject the guidance this server ships about itself, the `instructions` field of its initialize result, into the system prompt of every agent this entry is granted to. Off by default, and deliberately: the entry's own `instructions` is what your operator wrote, while this is a third party's text steering the agent, so consuming it is an explicit opt-in taken per entry and per channel. What a server ships is captured on every connect whatever this says, so turning it on applies at the next reload without restarting the connection, and turning it off stops the injection at the next activation. A block longer than 4000 characters is skipped whole rather than truncated. The block sits after this entry's own guidance, and `vinga agent preview <agent>` reports it under `server_instructions:<entry>`, so an operator can see whose words they are reading.",
            "title": "Use Server Instructions",
            "type": "boolean"
          },
          "inject_prompts": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The prompts this server publishes that are injected into the system prompt of every agent this entry is granted to, each by the name the server lists it under and in the order listed here. Unset means none, which is the default: a third party's text steering the agent is an opt-in per entry and per channel, and the specification defines prompts as user-controlled templates, so the operator who read the server's documentation names the ones that are standing guidance rather than invocable templates. Every name is validated against the server's own paginated prompt listing before anything is fetched, and a name the listing does not carry, one whose prompt declares required arguments, one that renders anything but text, and a rendered block longer than 4000 characters are each skipped with a warning naming this entry and the position in this list, never the name itself, since a server-chosen name is not this server's to print. Editing this list changes what a connect fetches, so unlike the other two prompt fields it restarts the connection when a reload applies it. A name listed twice is refused. Each name is stored and looked up exactly as written, surrounding whitespace included, because it is an identifier the server chose rather than a word this server may tidy: a stripped copy of it addresses a different prompt or none at all.",
            "title": "Inject Prompts"
          }
        },
        "required": [
          "transport"
        ],
        "title": "McpServerConfig",
        "type": "object"
      },
      "PromptFragmentConfig": {
        "additionalProperties": false,
        "description": "One named block of prompt text, shared by the agents that include\nit.\n\nA mapping with one field rather than a bare string. Every entity in\nthis configuration travels the same path (a stored row, a read\nenvelope, a written fragment), and all three of those want a mapping;\na one-field mapping also leaves room for a second field later without\nchanging the shape a client writes, which is why a grant took its\nobject form too.",
        "properties": {
          "text": {
            "description": "The text injected into the system prompt of every agent whose prompt_includes names this fragment, as written: its indentation and its own blank lines are part of it, and nothing is added around it, not even a heading, since this is prompt text the operator wrote and a heading would editorialize. The only bytes trimmed are whitespace at the two ends of the whole assembled prompt, which is also what the inspection surface reports. It sits after the agent's own prompt and before any MCP guidance, in the order the including layer lists it. There is no length cap: what each block costs is reported by `vinga agent preview <agent>`, and the operator is the one who knows what their model tolerates.",
            "title": "Text",
            "type": "string"
          }
        },
        "required": [
          "text"
        ],
        "title": "PromptFragmentConfig",
        "type": "object"
      },
      "FallbackConfig": {
        "additionalProperties": false,
        "description": "What the user hears when a reply fails outright.\n\nA terminally failed reply used to be a silent turn: the failure was\nlogged and nothing reached the speaker or the display, so from the\ncouch a broken pipeline was indistinguishable from a slow one\n(#384). This is the short fixed phrase that ends that silence,\nsynthesized in the agent's own voice at the server start and cached\nas PCM exactly the way a filler clip is, spoken from the failure arm\nand shown on the display.\n\nOn by default, which is the one place this differs from the filler\nbeside it: the silent turn is at its worst during onboarding, where\nmisconfiguration is likeliest and nobody has a log open. A\ndeployment that would rather have silence turns it off.\n\nCached rather than synthesized when the failure happens, for the two\nreasons the filler gives and one more: synthesis at failure time\nwould add latency to a turn that has already gone wrong, and the TTS\nprovider may itself be what failed. A phrase that will not\nsynthesize degrades rather than disappears, since the display half\nneeds no audio at all: the failure still shows the sentence and\nstill closes with the `tts stop` a device waits on, and only the\naudio is lost.",
        "properties": {
          "enabled": {
            "default": true,
            "description": "Whether a failed reply says so out loud and on the display. On by default, because a silent turn is indistinguishable from a slow one; a deployment that would rather have silence sets this to false.",
            "title": "Enabled",
            "type": "boolean"
          },
          "phrase": {
            "default": "I ran into a problem and could not answer. The server log has the details.",
            "description": "What a failed reply says, written in the agent's own language. Fixed configuration and never the failure's own words, which arrive from the far side of a network and are not this server's to speak.",
            "minLength": 1,
            "title": "Phrase",
            "type": "string"
          }
        },
        "title": "FallbackConfig",
        "type": "object"
      },
      "FillerConfig": {
        "additionalProperties": false,
        "description": "Masking reply latency with a pre-synthesized filled pause.\n\nOff by default. When enabled, the phrases are synthesized in the\nagent's own voice ahead of time and cached as PCM; a reply whose\nfirst audio has not started within `delay_ms` of the utterance being\ntranscribed plays one, and the real reply queues behind its tail.\n\"Ahead of time\" is the server start, and a reload after it: an edit\nhere is synthesized again while the process runs and reaches the\nnext conversation, since a conversation already open keeps the clips\nit opened with. A synthesis failure logs a warning and leaves the\nfeature off for that agent rather than failing the boot or refusing\nthe reload.",
        "properties": {
          "enabled": {
            "default": false,
            "description": "Whether a filled pause is played while a slow reply is prepared. Off by default.",
            "title": "Enabled",
            "type": "boolean"
          },
          "delay_ms": {
            "default": 1800.0,
            "description": "How long the user hears silence before the filler starts, in milliseconds, counted from the transcription of their utterance.",
            "exclusiveMinimum": 0,
            "title": "Delay Ms",
            "type": "number"
          },
          "phrases": {
            "description": "The phrases to play, written in the agent's own language; the player rotates through them rather than always playing the same one. At least one is required when the feature is enabled.",
            "items": {
              "minLength": 1,
              "type": "string"
            },
            "title": "Phrases",
            "type": "array"
          }
        },
        "title": "FillerConfig",
        "type": "object"
      },
      "McpGrant": {
        "additionalProperties": false,
        "description": "One `mcp` list entry in its object form: a server, and which of\nits tools the layer may reach.\n\nA second spelling of the same list entry rather than a different\nthing. A plain string names the whole server, and this names part of\none, so an agent that should switch the lights but not unlock the\ndoor does not need a second server to say it in.\n\nTools are named by the published name without its entry prefix\n(`turn_on_light` grants `home__turn_on_light`), matched exactly. That\nidentifier is this application's own: it has been through the\npublishing rule, it is what `vinga mcp-server status` shows and what\nthe model calls, so an operator writes down the name they read.\nWhat a server listed before the rule got to it never appears on a\nvinga surface, and cannot be granted by.",
        "properties": {
          "server": {
            "description": "The MCP server this grant is about, by the name it is defined under in mcp_servers.",
            "minLength": 1,
            "title": "Server",
            "type": "string"
          },
          "tools": {
            "anyOf": [
              {
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "minItems": 1,
                "type": "array",
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Which of that server's tools this layer may reach, by the published name without its entry prefix (turn_on_light for home__turn_on_light), which is the name `vinga mcp-server status` shows. Leaving it out grants the whole server, exactly as naming the server as a plain string does. A name that matches nothing the server published is not an error at write time, since only a live connection knows the list; it is logged when the server publishes and visible under grants on the status surface.",
            "title": "Tools"
          }
        },
        "required": [
          "server"
        ],
        "title": "McpGrant",
        "type": "object"
      },
      "MemoryPolicy": {
        "additionalProperties": false,
        "description": "Whether an agent remembers anything at all.\n\nOn by default, because every deployment has the schema behind it and\nan assistant that cannot remember is the exception rather than the\nshape. Switched off, the switch is the whole thing: the agent is\noffered none of the memory tools and its prompt carries none of the\nscope blocks, its device's included, so an agent that may not\nremember cannot read what its siblings on the same board accrued\neither. A half-off agent, told what the room knows and unable to\nwrite it down, would be a worse answer than either whole one.\n\nWhat the switch does not do is delete anything. Rows already stored\nunder the agent's name stay stored and stay visible to the operator\nsurface, and switching the section back on is an agent that\nremembers what it remembered before. Erasing is `vinga memory\ndelete`, which is a different act with a different door.",
        "properties": {
          "enabled": {
            "default": true,
            "description": "Whether this agent may remember anything. On by default. Off withholds the whole family at once: the memory tools are not offered and no remembered facts, device notes or conversation state are injected into the prompt, so the agent can neither write memory nor read it. Nothing already stored is deleted.",
            "title": "Enabled",
            "type": "boolean"
          }
        },
        "title": "MemoryPolicy",
        "type": "object"
      },
      "AgentConfig": {
        "additionalProperties": false,
        "description": "One agent: a prompt, plus whichever stages it overrides.",
        "properties": {
          "llm": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The language model, by the name it is defined under in providers.llm. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Llm"
          },
          "asr": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The speech recognizer, by the name it is defined under in providers.asr. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Asr"
          },
          "tts": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice, by the name it is defined under in providers.tts. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Tts"
          },
          "vad": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice activity detector, by the name it is defined under in providers.vad. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Vad"
          },
          "mcp": {
            "anyOf": [
              {
                "items": {
                  "anyOf": [
                    {
                      "minLength": 1,
                      "type": "string"
                    },
                    {
                      "$ref": "#/components/schemas/McpGrant"
                    }
                  ]
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The MCP servers whose tools this layer offers the model. An entry is either the entry name on its own, which is the whole server, or an object naming the server and the tools of it this layer may reach ({server: home, tools: [turn_on_light]}), where a tool is named by its published name without the entry prefix. Unset inherits the agent_defaults list; naming a list replaces the inherited one rather than extending it, so an empty list opts an agent out of the tools its siblings have. The builtin tools are outside this list: the memory family is offered wherever the memory section leaves it on, and switch_agent appears under a structural condition (a device that reaches more than one served agent, vinga, the built-in agent, among them while it is served) rather than by grant.",
            "title": "Mcp"
          },
          "filler": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FillerConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Latency masking with a pre-synthesized filled pause. Unset inherits the agent_defaults section; naming one replaces it wholly rather than merging with it, so `filler: {enabled: false}` opts an agent out."
          },
          "fallback": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FallbackConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "What a failed reply says out loud and on the display. Unset inherits the agent_defaults section, and an agent under neither speaks the declared default phrase, which is the default; naming a section replaces the inherited one wholly rather than merging with it, so `fallback: {enabled: false}` opts an agent out and leaves its failed turns silent."
          },
          "memory": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MemoryPolicy"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Whether this layer may remember anything. Unset inherits the agent_defaults section, and an agent under neither may remember, which is the default; naming a section replaces the inherited one wholly rather than merging with it, so `memory: {enabled: false}` opts an agent out of the memory tools and the injected scope blocks together."
          },
          "prompt_includes": {
            "anyOf": [
              {
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The shared prompt fragments this agent's system prompt carries, each by the name it is defined under in prompt_fragments, injected in the order listed and directly after the agent's own prompt. Unset inherits the agent_defaults list; naming a list replaces the inherited one rather than extending it, so an empty list opts this agent out of the fragments its siblings share. Every name has to be a fragment that exists, since the fragment is in this same database, and a name listed twice is refused. A reload applies this list, so an edit here reaches a conversation at its next activation, which is a new session or an agent switch. Leaving it unset inherits the agent_defaults list, whose edits reach this agent at the same moment.",
            "title": "Prompt Includes"
          },
          "prompt": {
            "default": "",
            "description": "The instruction this agent replies under, sent as the system prompt on every turn. State the reply language explicitly: a model otherwise picks one by its training bias.",
            "title": "Prompt",
            "type": "string"
          }
        },
        "title": "AgentConfig",
        "type": "object"
      },
      "AgentDefaults": {
        "additionalProperties": false,
        "description": "Provider references every agent inherits unless it names its own.\n\nDeliberately no prompt: an agent's prompt is its identity, and\ninheriting one silently would make two agents the same agent.",
        "properties": {
          "llm": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The language model, by the name it is defined under in providers.llm. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Llm"
          },
          "asr": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The speech recognizer, by the name it is defined under in providers.asr. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Asr"
          },
          "tts": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice, by the name it is defined under in providers.tts. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Tts"
          },
          "vad": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice activity detector, by the name it is defined under in providers.vad. An agent that leaves it unset inherits the agent_defaults entry.",
            "title": "Vad"
          },
          "mcp": {
            "anyOf": [
              {
                "items": {
                  "anyOf": [
                    {
                      "minLength": 1,
                      "type": "string"
                    },
                    {
                      "$ref": "#/components/schemas/McpGrant"
                    }
                  ]
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The MCP servers whose tools this layer offers the model. An entry is either the entry name on its own, which is the whole server, or an object naming the server and the tools of it this layer may reach ({server: home, tools: [turn_on_light]}), where a tool is named by its published name without the entry prefix. Unset inherits the agent_defaults list; naming a list replaces the inherited one rather than extending it, so an empty list opts an agent out of the tools its siblings have. The builtin tools are outside this list: the memory family is offered wherever the memory section leaves it on, and switch_agent appears under a structural condition (a device that reaches more than one served agent, vinga, the built-in agent, among them while it is served) rather than by grant.",
            "title": "Mcp"
          },
          "filler": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FillerConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Latency masking with a pre-synthesized filled pause. Unset inherits the agent_defaults section; naming one replaces it wholly rather than merging with it, so `filler: {enabled: false}` opts an agent out."
          },
          "fallback": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FallbackConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "What a failed reply says out loud and on the display. Unset inherits the agent_defaults section, and an agent under neither speaks the declared default phrase, which is the default; naming a section replaces the inherited one wholly rather than merging with it, so `fallback: {enabled: false}` opts an agent out and leaves its failed turns silent."
          },
          "memory": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MemoryPolicy"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Whether this layer may remember anything. Unset inherits the agent_defaults section, and an agent under neither may remember, which is the default; naming a section replaces the inherited one wholly rather than merging with it, so `memory: {enabled: false}` opts an agent out of the memory tools and the injected scope blocks together."
          },
          "prompt_includes": {
            "anyOf": [
              {
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The shared prompt fragments every agent's system prompt carries unless the agent names a list of its own, each by the name it is defined under in prompt_fragments, injected in the order listed and directly after the agent's own prompt. An agent naming a list replaces this one rather than extending it, so an empty list there opts that agent out of the fragments its siblings share. Every name has to be a fragment that exists, since the fragment is in this same database, and a name listed twice is refused. A reload applies this list, along with an agent's own and the text of a fragment either layer names, so a change here reaches every agent that inherits it at that agent's next activation, which is a new session or an agent switch.",
            "title": "Prompt Includes"
          }
        },
        "title": "AgentDefaults",
        "type": "object"
      },
      "BuiltinAgentConfig": {
        "additionalProperties": false,
        "description": "The built-in agent's overrides: whichever stages, sections and\nshared fragments it uses in place of what every agent inherits.\n\nAn agent layer without a prompt and without MCP grants, and the two\nare absent rather than refused: the persona is the build's, and a\ngrant on an agent every bound device may reach would be a grant to\nevery device.",
        "properties": {
          "llm": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The language model vinga replies with, by the name it is defined under in providers.llm. Unset inherits the agent_defaults entry.",
            "title": "Llm"
          },
          "asr": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The speech recognizer vinga hears with, by the name it is defined under in providers.asr. Unset inherits the agent_defaults entry.",
            "title": "Asr"
          },
          "tts": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice vinga speaks with, by the name it is defined under in providers.tts. Unset inherits the agent_defaults entry.",
            "title": "Tts"
          },
          "vad": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The voice activity detector for vinga's conversations, by the name it is defined under in providers.vad. Unset inherits the agent_defaults entry.",
            "title": "Vad"
          },
          "filler": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FillerConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Latency masking with a pre-synthesized filled pause. Unset inherits the agent_defaults section; naming one replaces it wholly."
          },
          "fallback": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/FallbackConfig"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "What a failed reply of vinga's says out loud and on the display. Unset inherits the agent_defaults section, and the declared default phrase under neither; naming one replaces it wholly."
          },
          "memory": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/MemoryPolicy"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Whether vinga may remember anything. What it remembers is its device's: it writes and reads the device's memory and never an agent memory of its own. Unset inherits the agent_defaults section; naming one replaces it wholly."
          },
          "prompt_includes": {
            "anyOf": [
              {
                "items": {
                  "minLength": 1,
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The shared prompt fragments vinga's prompt carries after its built-in persona, each by the name it is defined under in prompt_fragments, in the order listed. This is how its reply language is set: a fragment such as \"Always reply in Swedish.\" included here. Unset inherits the agent_defaults list; an empty list opts vinga out of the fragments its siblings share.",
            "title": "Prompt Includes"
          }
        },
        "title": "BuiltinAgentConfig",
        "type": "object"
      },
      "DeviceBinding": {
        "additionalProperties": false,
        "description": "What a device write carries: the agents the device may reach.",
        "properties": {
          "agents": {
            "description": "The agents this device is bound to, by name. A conversation starts on the first of them the server serves, and switch_agent reaches the rest it serves and vinga, the built-in agent, while it is served; with none of them served, vinga answers. Every name has to be an agent that exists, or the write is refused.",
            "items": {
              "type": "string"
            },
            "title": "Agents",
            "type": "array"
          }
        },
        "required": [
          "agents"
        ],
        "title": "DeviceBinding",
        "type": "object"
      },
      "PendingClaim": {
        "additionalProperties": false,
        "description": "What a claim by activation code carries: the agents the device\nis to reach, or none, for the default agent.\n\nA model of its own rather than `DeviceBinding` with a looser field,\nbecause the two writes differ in exactly this: a write by MAC is\nalso the rebind verb, where an omitted agent could mean the default\nor a mistake, and a claim is a new device, which is what a default\nagent is for (#612).",
        "properties": {
          "agents": {
            "description": "The agents this device is bound to, by name, with the meaning they have in a device binding. Left out or empty, the device is bound to the default agent, the agent a newly bound device starts with, and the claim is refused with nothing changed when none is set. Every name has to be an agent that exists, or the claim is refused.",
            "items": {
              "type": "string"
            },
            "title": "Agents",
            "type": "array"
          }
        },
        "title": "PendingClaim",
        "type": "object"
      },
      "InviteRequest": {
        "additionalProperties": false,
        "description": "What an invite's issuance carries: the agents the browser that\nopens it is to be bound to, or none, for the default agent (#612).\n\nRequired as a body, with `{}` naming none: a request that lost its\nbody on the way would otherwise bind the browser to the default\nagent rather than to the agents it named.",
        "properties": {
          "agents": {
            "description": "The agents the browser that opens the invite is bound to, by name, with the meaning they have in a device binding. Left out or empty, it is bound to the default agent, and the invite is refused with nothing issued when none is set. Every name has to be an agent that exists and that this server is serving, or the invite is refused with nothing issued; a name is never quoted back.",
            "items": {
              "type": "string"
            },
            "title": "Agents",
            "type": "array"
          }
        },
        "title": "InviteRequest",
        "type": "object"
      },
      "DeviceRename": {
        "additionalProperties": false,
        "description": "What a device rename carries: the name the device is to have.\n\nA body rather than a second path segment, for `AgentRename`'s\nreason: the device is addressed by the MAC a board connects with,\nwhich is the identity the act is performed on, and the name is what\nthe request carries.",
        "properties": {
          "to": {
            "description": "What this device is to be called. Free-form, because the agent says it out loud and a slug reads badly in speech. Names are unique once case and spacing are folded together, so `Kitchen Speaker` and `kitchen  speaker` are the same name; the stored value is exactly what was sent.",
            "title": "To",
            "type": "string"
          }
        },
        "required": [
          "to"
        ],
        "title": "DeviceRename",
        "type": "object"
      },
      "DeviceReplacement": {
        "additionalProperties": false,
        "description": "What a board swap carries: the address the record is to answer at\nfrom now on.\n\nA body rather than a second path segment, for `DeviceRename`'s\nreason and more sharply: the device is addressed by the MAC the\nboard it is losing connects with, which is the identity the act is\nperformed on, and the address it is gaining is what the request\ncarries. Two identities in the path would read as though the route\naddressed both records, and the whole point of the act is that there\nis one.",
        "properties": {
          "to": {
            "description": "The MAC of the board this device record is to answer at from now on. Stored in canonical form, so `AA-BB-CC-DD-EE-FF` and `aa:bb:cc:dd:ee:ff` are the same address. It has to be an address no device record already answers at and no memory is filed under, because a swap moves a record onto a board rather than merging two of them.",
            "title": "To",
            "type": "string"
          }
        },
        "required": [
          "to"
        ],
        "title": "DeviceReplacement",
        "type": "object"
      },
      "DeviceLocation": {
        "additionalProperties": false,
        "description": "What a relocation carries: where the device stands.\n\nNot unique and not validated beyond being a string: two devices in\none room is normal, and so is a room nobody names the same way\ntwice. Clearing it is the DELETE, not an empty string here, so\nthere is one way to say a device is nowhere in particular.",
        "properties": {
          "location": {
            "description": "Where the device stands, free-form, as a person would say it. To unset it, DELETE this resource.",
            "title": "Location",
            "type": "string"
          }
        },
        "required": [
          "location"
        ],
        "title": "DeviceLocation",
        "type": "object"
      },
      "DefaultAgentName": {
        "additionalProperties": false,
        "description": "What a default-agent write carries. Clearing it is the DELETE,\nnot a null here: one way to say a thing.",
        "properties": {
          "name": {
            "description": "The agent a newly bound device starts with: a claim by activation code that names no agent binds the device to it. It admits no device by itself. It has to be an agent that exists, or vinga, the built-in agent. To unset it, DELETE this resource, after which a claim naming no agent binds the device to vinga, exactly as naming vinga here does.",
            "title": "Name",
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "title": "DefaultAgentName",
        "type": "object"
      },
      "AgentRename": {
        "additionalProperties": false,
        "description": "What a rename carries: the name the agent is to have.\n\nA body rather than a second path segment, because the new name is\nnot part of the address. The agent is addressed by the name it has,\nwhich is the identity this act is performed on; what the request\ncarries is the name it is to be given.",
        "properties": {
          "to": {
            "description": "The name the agent is to have. Held to what every agent name is held to: it is stripped of surrounding whitespace, may not be empty after that, and may hold no slash and no control character. It has to be free everywhere the rename would write, so the request is refused when an agent, remembered facts or recorded conversation threads already sit under it, because a rename may never merge two pasts into one. Nothing sent is quoted back in any refusal.",
            "title": "To",
            "type": "string"
          }
        },
        "required": [
          "to"
        ],
        "title": "AgentRename",
        "type": "object"
      },
      "SecretValue": {
        "additionalProperties": false,
        "description": "What a secret write carries: the credential itself, the only\nplaintext this API ever accepts.",
        "properties": {
          "secret": {
            "description": "The credential, in plaintext, stored encrypted under the newest key in VINGA_MASTER_KEY. It crosses the connection as itself, which is why the whole API belongs on a loopback connection or behind TLS. It is never read back: a read names the slot and masks the value. It may not be empty.",
            "minLength": 1,
            "title": "Secret",
            "type": "string"
          }
        },
        "required": [
          "secret"
        ],
        "title": "SecretValue",
        "type": "object"
      },
      "MemoryCorrection": {
        "additionalProperties": false,
        "description": "The body of a correction: what the fact should say instead.",
        "properties": {
          "fact": {
            "description": "What the fact should say from now on, normalized to one line before it is stored. The id it is addressed by does not change and its place in the reading order does not move; what changes is the words and the moment it was last written. A body rather than a path segment or a query argument, because a remembered fact is content: it reaches proxy and access logs from either of those and cannot be taken back.",
            "title": "Fact",
            "type": "string"
          }
        },
        "required": [
          "fact"
        ],
        "title": "MemoryCorrection",
        "type": "object"
      },
      "MemoryStateKey": {
        "additionalProperties": false,
        "description": "The body of a state deletion: which entry to clear.",
        "properties": {
          "key": {
            "description": "The entry to clear. Sending no body at all clears the whole ledger, which is the deliberate difference between the two: a request that lost its body to a proxy or a client library would otherwise erase everything. The key travels here and never in the path, because keys are chosen by the model and a path reaches proxy and access logs where a body does not.",
            "title": "Key",
            "type": "string"
          }
        },
        "required": [
          "key"
        ],
        "title": "MemoryStateKey",
        "type": "object"
      },
      "DeviceRecord": {
        "additionalProperties": false,
        "description": "One device as the configuration holds it: a stable identity, the\nname a person says out loud, where it stands, and the agents it may\nreach.\n\nThree of the four are optional here and only one of them is\noptional in the database, which is deliberate rather than lax.\nAbsence in a document means \"the repository decides\", and the\nrepository is where it can be decided: it holds the domain writer\nlock and can see the stored row, so an absent id adopts the stored\none or is minted, and an absent name keeps the stored one or takes\nthe `Device <mac>` default. A required `name` here would put a\nmandatory argument on `bind` and on the pending claim, which is the\nflow an operator reaches holding a board and nothing else.\n\n`location` distinguishes absence from null, through\n`model_fields_set`: a document that does not carry the key says\nnothing about where the device is, and a document carrying `null`\nsays it is nowhere in particular. The same distinction\n`default_agent` makes, for the same reason.\n\nThe MAC is not here. The configuration's devices map is keyed by\nMAC and stays keyed by it: keying by name would make a rename read\nto the differ as a removal plus an addition, so an apply would drop\nthe record and mint a fresh id, which is the one thing a stable\nidentity may not do.",
        "properties": {
          "id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The device's stable identity, 32 lowercase hex digits. Minted by the server when the record is created and unchanged by a rename or a move. Leave it out and the stored one is kept.",
            "title": "Id"
          },
          "name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "What this device is called, free-form, spoken aloud by the agent. Names are unique once case and spacing are folded together. Leave it out and the stored name is kept, or `Device <mac>` is taken for a new record. That spelling is reserved, and so is `Browser <mac>`, what an invite link calls the browser it binds: a name of either form is refused for any device whose own MAC it is not, because it is what the server calls a device nobody has named and an agent is told the name rather than made to read a MAC address out loud.",
            "title": "Name"
          },
          "location": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Where the device stands, free-form, or null for nowhere in particular. Not unique: two devices in one room is normal. Leave the key out and the stored location is kept. Null is the only way to say nowhere: a location holding nothing but whitespace is refused, because it would be a second spelling of a state that already has one.",
            "title": "Location"
          },
          "agents": {
            "description": "The agents this device is bound to, by name. A conversation starts on the first of them the server serves, and the rest it serves are the ones it may be switched to, with vinga, the built-in agent, after them while it is served; with none of them served, vinga answers.",
            "items": {
              "minLength": 1,
              "type": "string"
            },
            "title": "Agents",
            "type": "array"
          }
        },
        "required": [
          "agents"
        ],
        "title": "DeviceRecord",
        "type": "object"
      },
      "ProvidersConfig": {
        "additionalProperties": false,
        "description": "The provider entries of each pipeline stage, keyed by the name\nagents and agent_defaults reference them by.",
        "properties": {
          "llm": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ProviderConfig"
            },
            "description": "The language model providers, keyed by the name that agents and agent_defaults reference.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Llm",
            "type": "object"
          },
          "asr": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ProviderConfig"
            },
            "description": "The speech recognition providers, keyed by the name that agents and agent_defaults reference.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Asr",
            "type": "object"
          },
          "tts": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ProviderConfig"
            },
            "description": "The speech synthesis providers, keyed by the name that agents and agent_defaults reference. A voice is a provider entry, so two agents that should sound different reference two entries.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Tts",
            "type": "object"
          },
          "vad": {
            "additionalProperties": {
              "$ref": "#/components/schemas/ProviderConfig"
            },
            "description": "The voice activity detection providers, keyed by the name that agents and agent_defaults reference.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Vad",
            "type": "object"
          }
        },
        "title": "ProvidersConfig",
        "type": "object"
      },
      "DomainConfig": {
        "additionalProperties": false,
        "description": "The domain half of a configuration, as the database holds it.\n\nThe same entity models the YAML file is validated through, in the\nsame shape, so nothing about a loaded snapshot is a second dialect\nof the configuration. What it does not hold is secrets: those ride\nbeside it in a SecretStore.",
        "properties": {
          "providers": {
            "$ref": "#/components/schemas/ProvidersConfig",
            "description": "The provider entries agents reference, one group per pipeline stage (llm, asr, tts, vad)."
          },
          "mcp_servers": {
            "additionalProperties": {
              "$ref": "#/components/schemas/McpServerConfig"
            },
            "description": "The MCP servers agents may be given tools from, keyed by entry name. The name becomes the prefix its tools are offered to the model under (home__turn_on_light), so it must match [A-Za-z0-9_-]+ and must not be one of the names the merged tool list already uses. What a tool answers with reaches the model as speakable text, since the reply is spoken; content of any other kind is named as a placeholder rather than dropped. Carrying structured content to a device is work for the display protocol, once the display path can render more than speech, rather than for the tool loop.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Mcp Servers",
            "type": "object"
          },
          "prompt_fragments": {
            "additionalProperties": {
              "$ref": "#/components/schemas/PromptFragmentConfig"
            },
            "description": "The shared blocks of prompt text agents include by name, keyed by fragment name. A fragment is written once and injected verbatim into the system prompt of every agent whose prompt_includes names it, which is how household facts or a house style stay in one place instead of being copied into every persona prompt and drifting apart. The name appears in the provenance the assembled prompt is reported under (fragment:<name>), so it must match [A-Za-z0-9_-]+.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Prompt Fragments",
            "type": "object"
          },
          "agent_defaults": {
            "$ref": "#/components/schemas/AgentDefaults",
            "description": "What every agent uses unless it names something else. One entry for the whole deployment, and deliberately without a prompt: a prompt is what makes an agent that agent, so inheriting one silently would make two agents the same one."
          },
          "builtin_agent": {
            "$ref": "#/components/schemas/BuiltinAgentConfig",
            "description": "The built-in agent's overrides: what vinga uses in place of what every agent inherits from agent_defaults. vinga is composed by the server from the build it ships in, so this entry holds no prompt and no MCP grants: only its providers, its voice, its filler, fallback and memory sections, and the shared fragments its prompt carries, which is how its reply language is set. vinga is served whenever every stage resolves, here or in agent_defaults, and no stored agent is named vinga."
          },
          "agents": {
            "additionalProperties": {
              "$ref": "#/components/schemas/AgentConfig"
            },
            "description": "The agents this deployment serves, keyed by name. An agent is a prompt plus whichever stages it overrides, and every stage must resolve to a provider, here or in agent_defaults, for the server to start. The name vinga is the built-in agent's: no agent of that name can be created, and one stored before the built-in agent existed is served in its place until it is renamed.",
            "propertyNames": {
              "minLength": 1
            },
            "title": "Agents",
            "type": "object"
          },
          "devices": {
            "additionalProperties": {
              "$ref": "#/components/schemas/DeviceRecord"
            },
            "description": "The devices this deployment serves, keyed by MAC address as the Device-Id header sends it. Each entry is a record: a server-minted id that stays the same as the rest of the record changes, the name the agent says out loud, where the device stands, and the agents it may talk to. A bare list of agent names is accepted as shorthand for a record naming only those agents.",
            "title": "Devices",
            "type": "object"
          },
          "default_agent": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The agent a newly bound device starts with: a claim by activation code that names no agent binds the device to it. It admits nothing by itself: a device with no binding of its own reaches no agent and is offered a code, set or not, so the devices map is always the allowlist. Leaving it unset means vinga, the built-in agent: unset and vinga are the same setting.",
            "title": "Default Agent"
          }
        },
        "title": "DomainConfig",
        "type": "object"
      },
      "FieldError": {
        "additionalProperties": false,
        "description": "One field of the submitted body that a refusal names.",
        "properties": {
          "path": {
            "description": "Which part of the submitted body this is about, as an RFC 6901 JSON Pointer into it: `/filler/phrases` is that field of that object, `/mcp/0` is that position of that list, and the empty string is the body as a whole. Only names this server declares and positions appear in it. A key the request invented is never one of them: an unrecognized key, an option a provider passes through, an entry of an `env` or `headers` map. A key is as good a place to paste a credential as a value is, so the pointer stops at the nearest enclosing place this server can name, which for a key written at the top of a fragment is the fragment itself.",
            "title": "Path",
            "type": "string"
          },
          "message": {
            "description": "What is wrong with it, in the same words the corresponding line of `detail` uses: the two are rendered from one computation, so a client showing this beside the field and one showing the whole sentence say the same thing. Like `detail`, it names a rule and never quotes the value it rejected or a key the request invented. Where the rule is about such a key, it names what made the key match instead, which is a word from a closed list this server owns.",
            "title": "Message",
            "type": "string"
          }
        },
        "required": [
          "path",
          "message"
        ],
        "title": "FieldError",
        "type": "object"
      },
      "RefusalReason": {
        "description": "Which of a handful of states a refusal is in, as a closed token.\n\nSeven of them, one per refusal whose next step is a command rather\nthan a correction to what was sent, because those are the refusals\na sentence composed here could only answer by naming a command it\ndoes not own.\n\n`code-not-pending` is an activation code no device is waiting under:\nexpired, already claimed, or never issued. `agents-unknown` is a\nclaim by code naming at least one agent this deployment does not\nhave, refused with nothing changed and the code still claimable, or\nan invite naming one, refused with nothing issued.\n`agent-not-serving` is a read of an agent this server has not\ninstalled, which is a different thing from one that does not exist,\nor an invite naming one, which a browser opening it would be bound\nto without an answer.\n`device-already-bound` is a conditional bind by code meeting a\ndevice that has been configured since the code was issued.\n`provider-missing` and `mcp-server-missing` are a stored secret\nwritten to a holder that is not there, and they are two states\nrather than one because the remedy names the holder's own noun.\n`default-agent-not-served` is an invite naming no agent, asked of\na deployment whose default agent, vinga when none is set, the\nworld installed now does not serve, so a browser opening it would\nbe bound to an agent that does not answer.\n\nHow to read one: map a token you know to a sentence of your own\ngrammar, and quote `detail` for one you do not. A token this\nvocabulary gains later arrives at an older client as a state it\ncannot name, which is not a state to guess at, and `detail` is\nalready the whole of what was refused. The member is absent from\nevery refusal in none of these seven states, so nothing else about\nthis API's refusals changed when it was added.",
        "enum": [
          "code-not-pending",
          "agents-unknown",
          "agent-not-serving",
          "device-already-bound",
          "provider-missing",
          "mcp-server-missing",
          "default-agent-not-served"
        ],
        "title": "RefusalReason",
        "type": "string"
      },
      "Problem": {
        "additionalProperties": false,
        "description": "A refusal, as RFC 9457 problem details.\n\nServed as `application/problem+json`. `type` and `instance` are\ndeliberately absent: an absent `type` means `about:blank`, which is\nthe truth here, since these problems are described by their status\nand their prose rather than by a URI registry nobody serves.\n\nWhich is why `reason` is an extension member rather than a `type`.\nRFC 9457 makes `type` a URI reference into a registry of problem\ntypes, and an extension member is what the same document offers a\nbody that has more to say; a handful of refusals here have a state\nworth branching on, and they carry the token for it beside the\nprose. It is absent everywhere else, so a refusal that is in none of\nthose states carries exactly the members it always has.",
        "properties": {
          "title": {
            "description": "The status code's standard HTTP reason phrase, such as `Not Found`. It is the phrase and not a description of this API's own, because with `type` absent the problem type is `about:blank`, whose title RFC 9457 says should be the status's recommended phrase; a title of this server's own would imply a problem type the body does not identify. What was actually refused is `detail`.",
            "title": "Title",
            "type": "string"
          },
          "status": {
            "description": "The HTTP status code, repeated in the body as the RFC describes, so that a problem separated from its response (in a log, in a bug report) still says what it was answered under.",
            "title": "Status",
            "type": "integer"
          },
          "detail": {
            "description": "What was refused and why: the state this server refused in, in its own words. It names the entity the request addressed and the rule that was broken; it never quotes a secret, a configuration value that was rejected, or a key the request invented. A client holding the `reason` below may extend it in its own grammar rather than relay it alone, which is what the `vinga` command does with the states it knows.",
            "title": "Detail",
            "type": "string"
          },
          "reason": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RefusalReason"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Which state this refusal is in, for a client that wants to say what to do about it in its own words. Absent rather than null wherever this server has no token for the state, which is every refusal but a handful: a member that appeared on all of them would be a member every client had to know about. Chosen by the code that classified the refusal and never read back out of the prose beside it."
          },
          "errors": {
            "description": "The fields of the submitted body the refusal names, one entry each, for a client that wants to mark the offending field rather than show a paragraph. Present on every refusal and empty where there is no field to name: a body whose whole shape was wrong, a reference to another entity, a failure that was not the caller's. The entries are the same problems `detail` lists, in the same order and the same words.",
            "items": {
              "$ref": "#/components/schemas/FieldError"
            },
            "title": "Errors",
            "type": "array"
          }
        },
        "required": [
          "title",
          "status",
          "detail",
          "errors"
        ],
        "title": "Problem",
        "type": "object"
      },
      "LlmOpenaiCompatibleOptions": {
        "additionalProperties": true,
        "description": "The options the `openai_compatible` LLM type accepts, and the one\ndoor in this file that stays open to an operator: a key this model\ndoes not declare is kept and forwarded into the outgoing request.\n\nThe type exists to reach a server this repository has never seen.\nOllama, LM Studio, llama.cpp, vLLM and every gateway in front of one\nspeak the chat-completions dialect and each takes parameters no\nother does, so a model that enumerated the dialect would be a list\nof one vendor's fields presented as the contract of all of them.\nThat is the reason `extra=\"allow\"` is here and nowhere else among\nthe closed types.\n\nAn accepted key takes EFFECT, which is the half that makes the hatch\nworth having. The extras ride into the request body as the API's own\nescape door takes them, merged UNDER the fields this type composes\nfor every request: `top_p` reaches the server, and nothing written\nhere can rewrite the conversation, the model, the stream or the\ntools the session is about to answer. A passthrough key naming one\nof those is refused when the entry is written, with the name said\nout loud, and the sentence below this one says which names those\nare.\n\nWhat the hatch does not open is a way past the rules every provider\nentry is held to. An extra is still walked for an inline secret and\nstill refused if it is a URL carrying a credential, because those\nrules read the fragment rather than the model.\n\nAny key not listed here is passed through to the endpoint as a top-level field of the chat completions request body. These names cannot be passed through, because this type composes them for every request: messages, stream, stream_options, tool_choice, tools.",
        "properties": {
          "base_url": {
            "description": "The endpoint's OpenAI-compatible base URL, such as http://localhost:11434/v1 for a local Ollama; pointing it at api.openai.com works too. Required, because it is what decides which server this entry speaks to and whether session data leaves the host.",
            "pattern": "\\S",
            "title": "Base Url",
            "type": "string"
          },
          "model": {
            "description": "The model to ask for, in the endpoint's own vocabulary (qwen3:8b on Ollama, an OpenAI model id on api.openai.com).",
            "pattern": "\\S",
            "title": "Model",
            "type": "string"
          },
          "max_tokens": {
            "description": "The cap on one reply's length, in tokens. Left out, no cap is sent and the endpoint's own default applies. An endpoint of the current OpenAI family refuses this field and takes max_completion_tokens instead, which is written here like any other passthrough key.",
            "title": "Max Tokens",
            "type": "integer"
          }
        },
        "propertyNames": {
          "not": {
            "enum": [
              "messages",
              "stream",
              "stream_options",
              "tool_choice",
              "tools"
            ]
          }
        },
        "required": [
          "base_url",
          "model"
        ],
        "title": "OpenaiCompatibleOptions",
        "type": "object"
      },
      "VadParameters": {
        "additionalProperties": true,
        "description": "The engine's own voice-activity tuning, forwarded as written.\n\nThe one model in this file whose door stays open, and it is open on\npurpose. `vad_parameters` has always been handed to\n`WhisperModel.transcribe` unread, the example documents one key of\nit, and faster-whisper's VAD takes several more that a deployment\nmay already have written. Closing the hatch on the evidence of one\ndocumented key would make a running deployment's valid setting\nunreadable on upgrade, so the model declares what vinga vouches for\nand says here that everything else still travels.\n\nWhat travels is what was written: the mapping is dumped with\n`exclude_unset=True` on the way to the engine, so an operator's\nexplicit values (nulls included) reach it and an injected default\ndoes not.",
        "properties": {
          "min_silence_duration_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "How much silence ends a speech segment, in milliseconds. Any other key written here is passed to the engine's VAD unread, which is what this section is for.",
            "title": "Min Silence Duration Ms"
          }
        },
        "title": "VadParameters",
        "type": "object"
      },
      "AsrFasterWhisperOptions": {
        "additionalProperties": false,
        "description": "The options the `faster_whisper` ASR type accepts.\n\nThe decode options mirror `WhisperModel.transcribe` arguments of the\nsame name and keep the engine's defaults when unset, with one\nexception: `beam_size` defaults to greedy decoding, because beam\nsearch buys little accuracy on short spoken commands and costs a\nmultiple of the CPU time (#19).",
        "properties": {
          "model": {
            "default": "small",
            "description": "Whisper model size (tiny, base, small, medium, large-v3, or a Hugging Face model id); weights download at server startup.",
            "title": "Model",
            "type": "string"
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Language hint (ISO 639-1, such as sv or en); omit to auto-detect per utterance. Detection costs a constant encoder pass per utterance, several seconds of it on a small CPU.",
            "title": "Language"
          },
          "device": {
            "default": "cpu",
            "description": "Where the engine runs inference, in faster-whisper's own vocabulary (cpu, cuda, auto).",
            "title": "Device",
            "type": "string"
          },
          "compute_type": {
            "default": "int8",
            "description": "The quantization the weights are loaded with, in faster-whisper's own vocabulary (int8, int8_float16, float16, float32).",
            "title": "Compute Type",
            "type": "string"
          },
          "beam_size": {
            "default": 1,
            "description": "Greedy decoding by default: beam search costs a multiple of the CPU time and buys little accuracy on short spoken commands.",
            "title": "Beam Size",
            "type": "integer"
          },
          "download_dir": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Where the model weights are cached; unset leaves the engine its own cache location.",
            "title": "Download Dir"
          },
          "cpu_threads": {
            "default": 0,
            "description": "Threads for CPU inference. The engine sizes its pool from the host's core count and ignores container CPU quotas, so inside a limit set this to the quota (0 keeps the engine default).",
            "title": "Cpu Threads",
            "type": "integer"
          },
          "vad_filter": {
            "default": false,
            "description": "Strip non-speech inside the ASR call before decoding. Cuts both latency and hallucinations on silence-padded utterances; recommended on.",
            "title": "Vad Filter",
            "type": "boolean"
          },
          "vad_parameters": {
            "$ref": "#/components/schemas/VadParameters",
            "description": "Tuning for the engine's own voice-activity filter, forwarded to it as written. Only what the fragment sets is sent."
          },
          "condition_on_previous_text": {
            "default": true,
            "description": "Feeding each window's text into the next is the documented cause of repetition loops; false is the standard mitigation.",
            "title": "Condition On Previous Text",
            "type": "boolean"
          },
          "temperature": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "items": {
                  "type": "number"
                },
                "minItems": 1,
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Fallback ladder for failed decodes, as one number or a non-empty list of them. The engine's six-step default can retry one bad utterance six times over; a short ladder bounds worst-case latency, which a voice UI feels.",
            "title": "Temperature"
          },
          "language_detect": {
            "default": "every_utterance",
            "description": "Detection scope. every_utterance detects fresh on each turn; once detects until a confident answer arrives and then reuses that language for the rest of the session, so later turns skip the detection pass.",
            "enum": [
              "every_utterance",
              "once"
            ],
            "title": "Language Detect",
            "type": "string"
          },
          "language_fallback": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The language to decode in when a detection falls below the confidence floor; unset means the low-confidence detection is used as it is.",
            "title": "Language Fallback"
          },
          "language_confidence_floor": {
            "default": 0.6,
            "description": "Below this detection confidence, distrust the guess: use language_fallback instead when one is set, and never lock a session to it. Misdetections cluster at low confidence, and a wrong language costs extra decode time on top of being wrong.",
            "title": "Language Confidence Floor",
            "type": "number"
          }
        },
        "title": "FasterWhisperOptions",
        "type": "object"
      },
      "AsrOpenaiOptions": {
        "additionalProperties": false,
        "description": "The options the `openai` ASR type accepts.\n\nSeven knobs and a door that stays shut. Six of them are what the\n`OptionsReader` ladder in `providers/openai_asr.py` had, every key\nthat builder did not read having ended its build with `finish()`\nnaming it; `languages` is the one this type gained here rather than\ninherited, and the validator below is the rule that comes with it.\n\nTwo rules are deliberately NOT here, and both live in the builder\nbecause both are facts about the endpoint rather than about a value.\n`base_url` has to be a URL with a scheme and a host, which\n`providers/openai_endpoint.py` decides for all three types speaking\nthis dialect; and `temperature` has to be inside OpenAI's own range\nonly when the endpoint IS OpenAI, which is the same module's\nquestion. This file weighs pydantic and `config.models` and nothing\nelse, so it cannot ask it, and restating those URL rules here would\nmake this the second home for them.",
        "properties": {
          "model": {
            "default": "gpt-transcribe",
            "description": "The transcription model, in OpenAI's own vocabulary. The default is the one that reports which language it heard; gpt-4o-transcribe and gpt-4o-mini-transcribe report none, and whisper-1 is the same Whisper V2 as the local engine, at roughly twice the latency. A self-hosted endpoint serves its own names and should be told one here.",
            "title": "Model",
            "type": "string"
          },
          "base_url": {
            "default": "https://api.openai.com/v1",
            "description": "The transcription endpoint. Any server implementing /v1/audio/transcriptions works here, the same way openai_compatible opens the LLM stage to local models; a keyless self-hosted one can leave api_key_env out. This is also what decides whether the audio leaves the host, so the type cannot declare its own reach.",
            "title": "Base Url",
            "type": "string"
          },
          "language": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Spoken language (ISO 639-1, such as sv or en). Set it for any deployment that is not English: detection happens inside the model at no measurable cost, but far-field microphone audio through Opus gives it far less to go on than clean audio does.",
            "title": "Language"
          },
          "languages": {
            "anyOf": [
              {
                "items": {
                  "maxLength": 16,
                  "pattern": "^[A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{1,8})*$",
                  "type": "string"
                },
                "minItems": 1,
                "type": "array",
                "uniqueItems": true
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "The languages spoken here, when there is more than one (ISO 639-1, such as [sv, en]), accepted by gpt-transcribe and answered with a 400 by whisper-1 and gpt-4o-mini-transcribe. Those take language instead, and the two options cannot both be set. A list of one is another way of writing language and reports the language heard no more than language does; a list of two or more leaves the model a choice, and what it chose is reported.",
            "title": "Languages"
          },
          "prompt": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Words the transcriber should expect (names, places, the assistant's own name), and not the agent's instruction, which is the agent's own entry. Keep it to plain vocabulary: on short or low-content audio the model hands this string back as the transcript instead of hearing anything.",
            "title": "Prompt"
          },
          "temperature": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Decoding temperature, which OpenAI itself takes between 0.0 and 1.0. Raise it only to loosen a decode that is stuck; unset leaves the API its own default.",
            "title": "Temperature"
          },
          "timeout_s": {
            "default": 30.0,
            "description": "Seconds before a transcription request is abandoned, and a real bound because the client's own retries are off: the SDK would otherwise try a failed request three times while the user waits for an answer.",
            "title": "Timeout S",
            "type": "number"
          }
        },
        "title": "OpenaiAsrOptions",
        "type": "object"
      },
      "VoiceSettings": {
        "additionalProperties": false,
        "description": "The vendor's own voice tuning, forwarded as written.\n\nFive keys and no more, which is the contract the type had before it\nhad a model: `read_voice_settings` listed exactly these and refused\nanything else, on the stated grounds that a typo the API silently\nignores is a knob that never took effect. The door stays shut here\nfor that reason, and that is the difference from `VadParameters`,\nthe other nested model, whose keys are read by an engine that takes\nmore of them than vinga documents.\n\nWhat travels is what was written: the mapping is dumped with\n`exclude_unset=True` into the request body, so an operator's explicit\nvalues reach the API and an injected default does not.",
        "properties": {
          "stability": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Higher is more monotone and more predictable.",
            "title": "Stability"
          },
          "similarity_boost": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Higher holds the synthesis closer to the reference voice.",
            "title": "Similarity Boost"
          },
          "style": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Style exaggeration, applied to voices that carry one.",
            "title": "Style"
          },
          "speed": {
            "anyOf": [
              {
                "type": "number"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "A multiplier around 1.0, which the API caps at 0.7 to 1.2.",
            "title": "Speed"
          },
          "use_speaker_boost": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Sharpens the resemblance to the reference speaker, and costs latency.",
            "title": "Use Speaker Boost"
          }
        },
        "title": "VoiceSettings",
        "type": "object"
      },
      "TtsElevenlabsOptions": {
        "additionalProperties": false,
        "description": "The options the `elevenlabs` TTS type accepts.\n\nEvery one of them is passed to the vendor's streaming endpoint, whose\nreference documents all of them. The two rules this type has of its\nown are here rather than in the builder: a voice id is required\nbecause there is nothing to synthesize with without one, and the\noutput format has to be a `pcm_<rate>` because the stage streams raw\nPCM and the rate the request asks for is the rate the session\nresamples from.",
        "properties": {
          "voice_id": {
            "description": "Voice id from your ElevenLabs voice library: the id, not the display name, and account-specific even for the stock voices.",
            "pattern": "\\S",
            "title": "Voice Id",
            "type": "string"
          },
          "model": {
            "default": "eleven_flash_v2_5",
            "description": "The synthesis model. The default is the low-latency one (~75 ms to first byte, 32 languages); eleven_multilingual_v2 sounds better and answers slower, which a conversation feels.",
            "title": "Model",
            "type": "string"
          },
          "output_format": {
            "default": "pcm_24000",
            "description": "Audio asked of the API. Only the pcm_<rate> formats work here, since the stage streams raw PCM; the default matches the rate devices are spoken at, so nothing is resampled. pcm_44100 and up need a paid ElevenLabs tier.",
            "pattern": "^pcm_[0-9]+$",
            "title": "Output Format",
            "type": "string"
          },
          "language_code": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Pin the spoken language (ISO 639-1) instead of letting the model infer it from the text.",
            "title": "Language Code"
          },
          "voice_settings": {
            "$ref": "#/components/schemas/VoiceSettings",
            "description": "Voice tuning, passed to the API as given. Only what the fragment sets is sent."
          },
          "timeout_s": {
            "default": 30.0,
            "description": "Seconds before a synthesis request is abandoned.",
            "title": "Timeout S",
            "type": "number"
          }
        },
        "required": [
          "voice_id"
        ],
        "title": "ElevenlabsOptions",
        "type": "object"
      }
    },
    "securitySchemes": {
      "bearerToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "The value of the environment variable server.api.secret_env names. It grants everything this API can do, secret writes included, so it belongs on a loopback connection or behind TLS."
      }
    }
  },
  "security": [
    {
      "bearerToken": []
    }
  ]
}